diff --git a/README.md b/README.md index e22a6868..2c54d918 100644 --- a/README.md +++ b/README.md @@ -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 () - 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()` support added + - `quantity_cast()` 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 () - 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 diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 6d2b73bf..feb52651 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -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> {}; ``` `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 @@ -157,7 +157,7 @@ constexpr Velocity auto v2 = 2 / 2s * 1m; static_assert(std::same_as); 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 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 {}; ``` @@ -288,7 +288,7 @@ struct derived_unit; struct kilometre : derived_unit> {}; ``` -- 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 @@ -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 /src/include/units/bits/tools.h:25, concept same_as = std::is_same_v; ^~~~ /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>, std::ratio<1, 1, 0>>; +struct metre : unit>, 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()); `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; @@ -586,7 +586,7 @@ using ret = quantity> {}; - ``` + ``` -2. Define a concept that will match a new dimension: +3. Define a concept that will match a new dimension: ```cpp template concept DigitalInformation = units::QuantityOf; ``` -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 {}; + struct bit : units::derived_unit {}; struct byte : units::derived_unit> {}; ``` -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(l); } constexpr auto operator""_b(long double l) { return units::quantity(l); } - + constexpr auto operator""_B(unsigned long long l) { return units::quantity(l); } constexpr auto operator""_B(long double l) { return units::quantity(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 () 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? diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 22de7545..b573f519 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -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( 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 -s cppstd=20 -b=outdated -u + ```shell + cd build + conan install .. -pr -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 .. -s cppstd=20 cmake .. @@ -69,17 +67,17 @@ cmake --build . ``` -# Packaging +## Packaging To create a `conan` package and test `cmake` installation and `conan` packaging run: -```bash -$ conan create . / -s cppstd=20 -b=outdated +```shell +conan create . / -s cppstd=20 -b=outdated ``` -# Upload package to conan server +## Upload package to conan server -```bash -$ conan upload -r --all mp-units/0.0.1@/ +```shell +conan upload -r --all mp-units/0.4.0@/ ```