Roland Conybeare
d1fa15f248
git-subtree-dir: xo-unit git-subtree-mainline:e9ee6992cagit-subtree-split:b531e382c2
114 lines
2.9 KiB
Markdown
114 lines
2.9 KiB
Markdown
# unit library
|
|
|
|
Provides compile-time dimension checking and scaling.
|
|
|
|
Similar in spirit to `boost::units`, but:
|
|
1. streamlined: assumes modern (c++20) support
|
|
2. supports fractional dimensions (rational powers)
|
|
|
|
## Documentation
|
|
|
|
- xo-unit documentation [under construction]: [documentation](https://rconybea.github.io/web/xo-unit/html/index.html)
|
|
- unit test coverage here: [coverage](https://rconybea.github.io/web/xo-unit/ccov/html/index.html)
|
|
|
|
## Example
|
|
|
|
```
|
|
#include "xo/unit/quantity.hpp"
|
|
#include "xo/unit/quantity_iostream.hpp"
|
|
|
|
namespace q = xo::qty::qty;
|
|
namespace u = xo::qty::u;
|
|
|
|
constexpr auto t = q::minutes(2);
|
|
constexpr auto d = q::kilometers(2.5);
|
|
|
|
constexpr auto t2 = t*t; // unit will be min^-2
|
|
constexpr auto a = d / t2; // unit will be km.min^-2
|
|
|
|
// convert to m.s^-2
|
|
constexpr quantity<u::meter / (u::second * u::second)> a2 = a;
|
|
|
|
//constexpr quantity<u::meter> a3 = a; // dimension mismatch, will not compile
|
|
|
|
// get dimensionless scale value
|
|
double x = a2.scale();
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
See [full install instructions](https://rconybea.github.io/web/xo-unit/html/install.html) for other installation strategies.
|
|
|
|
### build + install `xo-cmake` dependency
|
|
|
|
- [github/Rconybea/xo-cmake](https://github.com/Rconybea/xo-cmake)
|
|
|
|
Installs a few cmake ingredients, along with build assistant `xo-build` for XO projects such as this one.
|
|
|
|
### build + install other XO dependencies
|
|
```
|
|
$ xo-build --clone --configure --build --install xo-flatstring
|
|
$ xo-build --clone --configure --build --install xo-ratio
|
|
```
|
|
|
|
Note: can use `-n` to dry-run here
|
|
|
|
### copy `xo-unit` repository locally
|
|
```
|
|
$ xo-build --clone xo-unit
|
|
```
|
|
|
|
or equivalently
|
|
```
|
|
$ git clone https://github.com/rconybea/xo-unit
|
|
```
|
|
|
|
### build + install `xo-unit`
|
|
```
|
|
$ xo-build --configure --build --install xo-unit
|
|
```
|
|
|
|
or equivalently:
|
|
```
|
|
$ PREFIX=/usr/local # or wherever you prefer
|
|
$ cmake -DCMAKE_INSTALL_PREFIX=${PREFIX} -S xo-unit -B xo-unit/.build
|
|
$ cmake --build xo-unit/.build -j
|
|
$ cmake --install xo-unit/.build
|
|
```
|
|
|
|
### build documentation
|
|
```
|
|
$ cd xo-unit
|
|
$ cmake -DCMAKE_INSTALL_PREFIX=${PREFIX} --build .build -- sphinx
|
|
```
|
|
When this completes, can point local browser to `xo-unit/.build/docs/sphinx/index.html`.
|
|
|
|
### build for unit test coverage
|
|
|
|
(Note that unit tests involve additional dependencies):
|
|
```
|
|
$ xo-build --clone --configure --build --install xo-indentlog
|
|
$ xo-build --clone --configure --build --install xo-randomgen
|
|
```
|
|
|
|
```
|
|
$ cmake -DCMAKE_BUILD_TYPE=coverage -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_TESTING=1 xo-unit/.build-ccov
|
|
$ cmake --build xo-unit/.build-ccov
|
|
```
|
|
|
|
run coverage-enabled unit tests:
|
|
```
|
|
$ cmake --build xo-unit/.build-ccov -- test
|
|
```
|
|
|
|
generate html+text coverage report:
|
|
```
|
|
$ xo-unit/.build-ccov/gen-ccov
|
|
```
|
|
To see coverage, can point local browser to `xo-unit/.build-ccov/ccov/html/index.html`
|
|
|
|
### LSP support
|
|
```
|
|
$ cd xo-unit
|
|
$ ln -s .build/compile_commands.json # lsp will look for compile_commands.json in the root of the source tree
|
|
```
|