feedc0de/mp-units
1
0
Fork 0
forked from mpusz/mp-units
Code Pull Requests Activity

Documentation cleanup

Browse Source
This commit is contained in:
Mateusz Pusz
2019-10-04 08:29:24 +02:00
parent 7c4e5d086a
commit 9c436812f5
3 changed files with 73 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@@ -1,8 +1,8 @@
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?maxAge=3600)](https://raw.githubusercontent.com/mpusz/units/master/LICENSE)
[![Travis CI](https://img.shields.io/travis/com/mpusz/units/master.svg?label=Travis%20CI)](https://travis-ci.com/mpusz/units)
[![AppVeyor](https://img.shields.io/appveyor/ci/mpusz/units/master.svg?label=AppVeyor)](https://ci.appveyor.com/project/mpusz/units)
[![Conan stable](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg?version=0.3.1%3Astable) ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link)
[![Conan testing](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg) ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/_latestVersion)
[![Conan stable](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg?version=0.3.1%3Astable)](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link)
[![Conan testing](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg)](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/_latestVersion)
# `mp-units` - A Units Library for C++
@@ -10,7 +10,7 @@
`Units` is a compile-time enabled Modern C++ library that provides compile-time dimensional
analysis and unit/quantity manipulation. The basic idea and design heavily bases on
`std::chrono::duration` and extends it to work properly with many dimensions.
`std::chrono::duration` and extends it to work properly with many dimensions.
Here is a small example of possible operations:
@@ -35,11 +35,11 @@ static_assert(10_km / 5_km == 2);
## Repository structure
That repository contains the following independent `cmake`-based projects:
- `./src` - header-only project for `units`
- `.` - project used for development needs that wraps `./src` project together with
usage examples and unit tests
- `./test_package` - library installation and Conan package verification
- `./src` - header-only project for `units`
- `.` - project used for development needs that wraps `./src` project together with
usage examples and unit tests
- `./test_package` - library installation and Conan package verification
Please note that the projects depend on `cmake` git submodule in the `./cmake/common`
subdirectory.
@@ -52,8 +52,8 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
## Library design
`units` library design rationale and documentation can be found in
[doc/DESIGN.md](doc/DESIGN.md)
`mp-units` library design rationale and documentation can be found in
[doc/DESIGN.md](doc/DESIGN.md)
## Release notes
@@ -67,7 +67,7 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
- cmcstl2 dependency changed to range-v3 0.9.1
- 0.3.0 Sep 16, 2019 (CppCon 2019 design)
- The design as described on CppCon 2019 talk
- The design as described on CppCon 2019 talk (<https://youtu.be/0YW6yxkdhlU>)
- Applied the feedback from the Cologne evening session
- `upcasting_traits` renamed to `downcasting_traits`
- `Dimension` template parameter removed from quantity
@@ -75,21 +75,21 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
- Leading underscore prefix removed from UDLs
- Added a few more derived dimensions
- `meter` renamed to `metre`
- Missing `operator*` added
- Missing `operator*` added
- Predefined dimensions moved to a dedicated directory
- `dimension_` prefix removed from names of derived dimensions
- cmcstl2 library updated to 2019.09.19
- `base_dimension` is a value provided as `const&` to the `exp` type
- integrated with Compiler Explorer
- gsl-lite deppendency removed
- gsl-lite dependency removed
- Fractional dimension exponents support added
- `QuantityOf` concept introduced
- `quantity_cast<U, Rep>()` support added
- `quantity_cast<U, Rep>()` support added
- 0.2.0 July 18, 2019 (C++Now 2019 design)
- The design as described on C++Now 2019 talk (https://youtu.be/wKchCktZPHU)
- The design as described on C++Now 2019 talk (<https://youtu.be/wKchCktZPHU>)
- Added C++20 features supported by gcc-9.1 (`std::remove_cvref_t`, down with typename, `std::type_identity`)
- Compile-time performance optimisations (`type_list`, `common_ratio`, `ratio`, `conditional_t`)
- Compile-time performance optimizations (`type_list`, `common_ratio`, `ratio`, `conditional_t`)
- 0.1.0 May 18, 2019
- Initial library release

58
doc/DESIGN.md
View File

@@ -4,7 +4,7 @@
`Units` is a compile-time enabled Modern C++ library that provides compile-time dimensional
analysis and unit/quantity manipulation. The basic idea and design heavily bases on
`std::chrono::duration` and extends it to work properly with many dimensions.
`std::chrono::duration` and extends it to work properly with many dimensions.
Here is a small example of possible operations:
@@ -39,7 +39,7 @@ static_assert(10km / 5km == 2);
3. No macros in the user interface
4. Easy extensibility
5. No external dependencies
6. Possibility to be standardized as a freestanding part of the C++ Standard Library
6. Possibility to be standardized as a freestanding part of the C++ Standard Library
## Overview
@@ -83,7 +83,7 @@ struct dimension : downcast_base<dimension<Es...>> {};
```
`units::Dimension` is a concept that is satisfied by a type that is empty and publicly
derived from `units::dimension` class template:
derived from `units::dimension` class template:
```cpp
template<typename T>
@@ -157,7 +157,7 @@ constexpr Velocity auto v2 = 2 / 2s * 1m;
static_assert(std::same_as<decltype(v1), decltype(v2)>);
static_assert(v1 == v2);
```
```
Above code, no matter what is the order of the base dimensions in an expression forming our result,
must produce the same `Velocity` type so that both values can be easily compared. In order to achieve
@@ -167,10 +167,10 @@ helper:
```cpp
template<typename Child, Exponent... Es>
struct derived_dimension;
```
```
`Child` class template parameter is a part of a CRTP idiom and is used to provide a downcasting facility
described later in this document.
described later in this document.
So for example to create a `velocity` type we have to do:
@@ -246,7 +246,7 @@ struct derived_unit;
```
For example to define the base unit of `length`:
```cpp
struct metre : derived_unit<metre, length> {};
```
@@ -288,7 +288,7 @@ struct derived_unit<Child, U>;
struct kilometre : derived_unit<kilometre, kilo<metre>> {};
```
- helper that automatically calculates ratio based on info in desired dimension and provided list
- helper that automatically calculates ratio based on info in desired dimension and provided list
of units of base dimensions
```cpp
@@ -301,7 +301,7 @@ struct kilometre_per_hour : derived_unit<kilometre_per_hour, velocity, kilometre
```
`units::Unit` is a concept that is satisfied by a type that is empty and publicly
derived from `units::unit` class template:
derived from `units::unit` class template:
```cpp
template<typename T>
@@ -312,7 +312,7 @@ concept Unit =
### `Quantities`
`units::quantity` is a class template that expresses the quantity/amount of a specific dimension
`units::quantity` is a class template that expresses the quantity/amount of a specific dimension
expressed in a specific unit of that dimension:
```cpp
@@ -392,7 +392,7 @@ Beside adding new elements a few other changes where applied compared to the `st
#### `quantity_cast`
To explicitly force truncating conversions `quantity_cast` function is provided which is a direct
counterpart of `std::chrono::duration_cast`. As a template argument user can provide here either
counterpart of `std::chrono::duration_cast`. As a template argument user can provide here either
a `quantity` type or only its template parameters (`Unit`, `Rep`):
```cpp
@@ -477,7 +477,7 @@ In file included from <path>/src/include/units/bits/tools.h:25,
concept same_as = std::is_same_v<T, U>;
^~~~
<path>/src/include/units/bits/stdconcepts.h:33:18: note: 'std::is_same_v' evaluated to false
```
```
Now
@@ -498,10 +498,10 @@ class specialization with a strong type assigned to it by the user. A simplified
facility may be represented as:
```cpp
struct metre : unit<dimension<exp<base_dim_length, 1>>, std::ratio<1, 1, 0>>;
struct metre : unit<dimension<exp<base_dim_length, 1>>, std::ratio<1, 1, 0>>;
```
In the above example `metre` is a downcasting target (child class) and a specific `unit` class
In the above example `metre` is a downcasting target (child class) and a specific `unit` class
template specialization is a downcasting source (base class). The downcasting facility provides
1 to 1 tpe substitution mechanism. Only one child class can be created for a specific base class
template instantiation.
@@ -576,7 +576,7 @@ using downcast_target = decltype(detail::downcast_target_impl<T>());
`units::downcast_target` is used to obtain the target type of the downcasting operation registered
for a given specialization in a base type.
For example to determine a downcasted type of a quantity multiply operation the following can be done:
For example to determine a downcasted type of a quantity multiply operation the following can be done:
```cpp
using dim = dimension_multiply_t<typename U1::dimension, typename U2::dimension>;
@@ -586,7 +586,7 @@ using ret = quantity<downcast_target<unit<dim, ratio_multiply<typename U1::ratio
`detail::downcast_target_impl` checks if a downcasting target is registered for the specific base class.
If yes, it returns the registered type, otherwise it works like a regular identity type returning
a provided base class.
a provided base class.
```cpp
namespace detail {
@@ -626,34 +626,34 @@ In order to extend the library with custom dimensions the user has to:
inline constexpr units::base_dimension base_dim_digital_information{"digital information"};
```
2. Create a new dimension type with the recipe of how to construct it from base dimensions and
register it for a downcasting facitlity:
2. Create a new dimension type with the recipe of how to construct it from base dimensions and
register it for a downcasting facility:
```cpp
struct digital_information : units::derived_dimension<digital_information, units::exp<base_dim_digital_information, 1>> {};
```
```
2. Define a concept that will match a new dimension:
3. Define a concept that will match a new dimension:
```cpp
template<typename T>
concept DigitalInformation = units::QuantityOf<T, digital_information>;
```
3. Define units and register them to a downcasting facility:
4. Define units and register them to a downcasting facility:
```cpp
struct bit : units::derived_unit<bit, digital_information> {};
struct bit : units::derived_unit<bit, digital_information> {};
struct byte : units::derived_unit<byte, digital_information, units::ratio<8>> {};
```
4. Provide user-defined literals for the most important units:
5. Provide user-defined literals for the most important units:
```cpp
inline namespace literals {
constexpr auto operator""_b(unsigned long long l) { return units::quantity<bit, std::int64_t>(l); }
constexpr auto operator""_b(long double l) { return units::quantity<bit, long double>(l); }
constexpr auto operator""_B(unsigned long long l) { return units::quantity<byte, std::int64_t>(l); }
constexpr auto operator""_B(long double l) { return units::quantity<byte, long double>(l); }
}
@@ -681,17 +681,17 @@ In order to extend the library with custom dimensions the user has to:
6. Should we provide integral UDLs or just leave floating point ones?
7. Should we provide support for dimensionless quantities?
7. Should we provide support for dimensionless quantities?
Because dimensionless quantities have no associated units, they behave as normal scalars,
and allow implicit conversion to and from the underlying value type or types that are
convertible to/from that value type.
9. Should we standardize accompany tools (downcasting facility, `type_list` operations, `common_ratio`, etc)?
8. Should we standardize accompany tools (downcasting facility, `type_list` operations, `common_ratio`, etc)?
10. `k`, `K`, `W`, `F` UDLs conflict with gcc GNU extensions (https://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Fixed_002dPoint.html)
9. `k`, `K`, `W`, `F` UDLs conflict with gcc GNU extensions (<https://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Fixed_002dPoint.html>)
for floating point types.
11. `J` imaginary constants are a GCC extension
10. `J` imaginary constants are a GCC extension
12. Do we need custom/multiple systems?
11. Do we need custom/multiple systems?

58
doc/INSTALL.md
View File

@@ -1,45 +1,43 @@
# Installation and Reuse
# Installation Guide
## Installation and Reuse
There are a few different ways of installing/reusing `units` in your project.
## Copy
### Copy
As `units` is a header-only library you can simply copy `src/include` directory to
your source tree and use it as regular header files.
NOTE: Until C++20 arrives the library has some 3rd party dependencies that provide
experimental C++20 features. They can be easily obtained with conan
experimental C++20 features. The list of dependncies include:
- `range-v3@ericniebler`
```python
requires = (
"cmcstl2/2019.03.18@mpusz/stable",
"gsl-lite/0.33.0@nonstd-lite/stable"
)
```
All of them are easily obtained with `conan`.
## cmake + conan
### cmake + conan
To use `units` as a `cmake` imported library via `cmake` configuration files the following
steps may be done:
- add the following remotes to your local `conan` instance
```bash
$ conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz
$ conan remote add conan-nonstd https://api.bintray.com/conan/martinmoene/nonstd-lite
```shell
conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz
```
- add `units` as a dependency to your `conan` file
- add `units` as a dependency to your `conan` file. For example to use testing version of
`0.4.0` of `mp-units` add:
- `conanfile.txt`
```text
[requires]
mp-units/0.0.1@mpusz/testing
mp-units/0.4.0@mpusz/testing
```
- `conanfile.py`
```python
requires = "mp-units/0.0.1@mpusz/testing"
requires = "mp-units/0.4.0@mpusz/testing"
```
- link your `cmake` target with units
@@ -48,20 +46,20 @@ steps may be done:
target_link_libraries(<your_target> PUBLIC|PRIVATE|INTERFACE CONAN_PKG::mp-units)
```
- install conan dependencies before configuring cmake
- install `conan` dependencies before configuring cmake
```bash
$ cd build
$ conan install .. -pr <your_conan_profile> -s cppstd=20 -b=outdated -u
```shell
cd build
conan install .. -pr <your_conan_profile> -s cppstd=20 -b=outdated -u
```
# Full build and unit testing
## Full build and unit testing
In case you would like to build all the code in that repository (with unit tests and examples)
you should use `CMakeLists.txt` from the parent directory.
you should use the `CMakeLists.txt` from the parent directory.
```bash
```shell
mkdir build && cd build
conan install .. <your_profile_and_settings> -s cppstd=20
cmake .. <your_cmake_configuration>
@@ -69,17 +67,17 @@ cmake --build .
```
# Packaging
## Packaging
To create a `conan` package and test `cmake` installation and `conan` packaging run:
```bash
$ conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings>
```shell
conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings>
```
# Upload package to conan server
## Upload package to conan server
```bash
$ conan upload -r <remote-name> --all mp-units/0.0.1@<user>/<channel>
```shell
conan upload -r <remote-name> --all mp-units/0.4.0@<user>/<channel>
```