mirror of
https://github.com/mpusz/mp-units.git
synced 2025-08-03 20:34:26 +02:00
Documentation cleanup
This commit is contained in:
Mateusz Pusz
32
README.md
32
README.md
@@ -1,8 +1,8 @@
|
||||
[](https://raw.githubusercontent.com/mpusz/units/master/LICENSE)
|
||||
[](https://travis-ci.com/mpusz/units)
|
||||
[](https://ci.appveyor.com/project/mpusz/units)
|
||||
[ ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link)
|
||||
[ ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/_latestVersion)
|
||||
[](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link)
|
||||
[](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
|
||||
|
||||
@@ -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?
|
||||
|
||||
@@ -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>
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user