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) [![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) [![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) [![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 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 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++ # `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 `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 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: Here is a small example of possible operations:
@@ -35,11 +35,11 @@ static_assert(10_km / 5_km == 2);
## Repository structure ## Repository structure
That repository contains the following independent `cmake`-based projects: That repository contains the following independent `cmake`-based projects:
- `./src` - header-only project for `units` - `./src` - header-only project for `units`
- `.` - project used for development needs that wraps `./src` project together with - `.` - project used for development needs that wraps `./src` project together with
usage examples and unit tests usage examples and unit tests
- `./test_package` - library installation and Conan package verification - `./test_package` - library installation and Conan package verification
Please note that the projects depend on `cmake` git submodule in the `./cmake/common` Please note that the projects depend on `cmake` git submodule in the `./cmake/common`
subdirectory. subdirectory.
@@ -52,8 +52,8 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
## Library design ## Library design
`units` library design rationale and documentation can be found in `mp-units` library design rationale and documentation can be found in
[doc/DESIGN.md](doc/DESIGN.md) [doc/DESIGN.md](doc/DESIGN.md)
## Release notes ## 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 - cmcstl2 dependency changed to range-v3 0.9.1
- 0.3.0 Sep 16, 2019 (CppCon 2019 design) - 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 - Applied the feedback from the Cologne evening session
- `upcasting_traits` renamed to `downcasting_traits` - `upcasting_traits` renamed to `downcasting_traits`
- `Dimension` template parameter removed from quantity - `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 - Leading underscore prefix removed from UDLs
- Added a few more derived dimensions - Added a few more derived dimensions
- `meter` renamed to `metre` - `meter` renamed to `metre`
- Missing `operator*` added - Missing `operator*` added
- Predefined dimensions moved to a dedicated directory - Predefined dimensions moved to a dedicated directory
- `dimension_` prefix removed from names of derived dimensions - `dimension_` prefix removed from names of derived dimensions
- cmcstl2 library updated to 2019.09.19 - cmcstl2 library updated to 2019.09.19
- `base_dimension` is a value provided as `const&` to the `exp` type - `base_dimension` is a value provided as `const&` to the `exp` type
- integrated with Compiler Explorer - integrated with Compiler Explorer
- gsl-lite deppendency removed - gsl-lite dependency removed
- Fractional dimension exponents support added - Fractional dimension exponents support added
- `QuantityOf` concept introduced - `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) - 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`) - 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 - 0.1.0 May 18, 2019
- Initial library release - 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 `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 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: Here is a small example of possible operations:
@@ -39,7 +39,7 @@ static_assert(10km / 5km == 2);
3. No macros in the user interface 3. No macros in the user interface
4. Easy extensibility 4. Easy extensibility
5. No external dependencies 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 ## 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 `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 ```cpp
template<typename T> 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(std::same_as<decltype(v1), decltype(v2)>);
static_assert(v1 == v2); static_assert(v1 == v2);
``` ```
Above code, no matter what is the order of the base dimensions in an expression forming our result, 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 must produce the same `Velocity` type so that both values can be easily compared. In order to achieve
@@ -167,10 +167,10 @@ helper:
```cpp ```cpp
template<typename Child, Exponent... Es> template<typename Child, Exponent... Es>
struct derived_dimension; struct derived_dimension;
``` ```
`Child` class template parameter is a part of a CRTP idiom and is used to provide a downcasting facility `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: 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`: For example to define the base unit of `length`:
```cpp ```cpp
struct metre : derived_unit<metre, length> {}; struct metre : derived_unit<metre, length> {};
``` ```
@@ -288,7 +288,7 @@ struct derived_unit<Child, U>;
struct kilometre : derived_unit<kilometre, kilo<metre>> {}; 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 of units of base dimensions
```cpp ```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 `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 ```cpp
template<typename T> template<typename T>
@@ -312,7 +312,7 @@ concept Unit =
### `Quantities` ### `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: expressed in a specific unit of that dimension:
```cpp ```cpp
@@ -392,7 +392,7 @@ Beside adding new elements a few other changes where applied compared to the `st
#### `quantity_cast` #### `quantity_cast`
To explicitly force truncating conversions `quantity_cast` function is provided which is a direct 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`): a `quantity` type or only its template parameters (`Unit`, `Rep`):
```cpp ```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>; 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 <path>/src/include/units/bits/stdconcepts.h:33:18: note: 'std::is_same_v' evaluated to false
``` ```
Now Now
@@ -498,10 +498,10 @@ class specialization with a strong type assigned to it by the user. A simplified
facility may be represented as: facility may be represented as:
```cpp ```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 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 1 to 1 tpe substitution mechanism. Only one child class can be created for a specific base class
template instantiation. 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 `units::downcast_target` is used to obtain the target type of the downcasting operation registered
for a given specialization in a base type. 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 ```cpp
using dim = dimension_multiply_t<typename U1::dimension, typename U2::dimension>; 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. `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 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 ```cpp
namespace detail { 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"}; 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 2. Create a new dimension type with the recipe of how to construct it from base dimensions and
register it for a downcasting facitlity: register it for a downcasting facility:
```cpp ```cpp
struct digital_information : units::derived_dimension<digital_information, units::exp<base_dim_digital_information, 1>> {}; 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 ```cpp
template<typename T> template<typename T>
concept DigitalInformation = units::QuantityOf<T, digital_information>; 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 ```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>> {}; 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 ```cpp
inline namespace literals { inline namespace literals {
constexpr auto operator""_b(unsigned long long l) { return units::quantity<bit, std::int64_t>(l); } 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(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(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); } 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? 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, 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 and allow implicit conversion to and from the underlying value type or types that are
convertible to/from that value type. 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. 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. 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 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. your source tree and use it as regular header files.
NOTE: Until C++20 arrives the library has some 3rd party dependencies that provide 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 All of them are easily obtained with `conan`.
requires = (
"cmcstl2/2019.03.18@mpusz/stable",
"gsl-lite/0.33.0@nonstd-lite/stable"
)
```
## cmake + conan ### cmake + conan
To use `units` as a `cmake` imported library via `cmake` configuration files the following To use `units` as a `cmake` imported library via `cmake` configuration files the following
steps may be done: steps may be done:
- add the following remotes to your local `conan` instance - add the following remotes to your local `conan` instance
```bash ```shell
$ conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz 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
``` ```
- 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` - `conanfile.txt`
```text ```text
[requires] [requires]
mp-units/0.0.1@mpusz/testing mp-units/0.4.0@mpusz/testing
``` ```
- `conanfile.py` - `conanfile.py`
```python ```python
requires = "mp-units/0.0.1@mpusz/testing" requires = "mp-units/0.4.0@mpusz/testing"
``` ```
- link your `cmake` target with units - 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) 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 ```shell
$ cd build cd build
$ conan install .. -pr <your_conan_profile> -s cppstd=20 -b=outdated -u 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) 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 mkdir build && cd build
conan install .. <your_profile_and_settings> -s cppstd=20 conan install .. <your_profile_and_settings> -s cppstd=20
cmake .. <your_cmake_configuration> 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: To create a `conan` package and test `cmake` installation and `conan` packaging run:
```bash ```shell
$ conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings> conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings>
``` ```
# Upload package to conan server ## Upload package to conan server
```bash ```shell
$ conan upload -r <remote-name> --all mp-units/0.0.1@<user>/<channel> conan upload -r <remote-name> --all mp-units/0.4.0@<user>/<channel>
``` ```