roland/xo-umbrella2
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add 'xo-unit/' from commit 'b531e382c2'

Browse source 
git-subtree-dir: xo-unit
git-subtree-mainline: e9ee6992ca
git-subtree-split: b531e382c2
This commit is contained in:
Roland Conybeare 2025-05-10 21:29:43 -05:00
commit d1fa15f248
105 changed files with 11790 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

17
xo-unit/docs/CMakeLists.txt Normal file
View file

@ -0,0 +1,17 @@
# xo-unit/docs/CMakeLists.txt
xo_doxygen_collect_deps()
xo_docdir_doxygen_config()
xo_docdir_sphinx_config(
index.rst examples.rst glossary.rst install.rst implementation.rst
quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst quantity-source-code.rst
xquantity-reference.rst xquantity-class.rst xquantity-source-code.rst
scaled-unit-reference.rst scaled-unit-class.rst scaled-unit-constants.rst
natural-unit-class.rst
bpu-class.rst
bu-store-class.rst basis-unit-reference.rst
basis-unit-class.rst basis-unit-constants.rst
dimension-enum.rst
development.rst
ubuntu-github-workflow.rst
)

70
xo-unit/docs/README Normal file
View file

@ -0,0 +1,70 @@
build
+-----------------------------------------------+
| cmake |
| CMakeLists.txt |
| $PREFIX/share/cmake/xo_macros/xo_cxx.cmake |
+-----------------------------------------------+
|
| +----------------------+
+------------------------------------------------->| .build/docs/Doxyfile |
| +----------------------+
| |
| /------------/
| |
| v
| +---------------------------------------+ +-----------------+
+---->| doxygen |--->| .build/docs/dox |
| | $PREFIX/share/xo-macros/Doxyfile.in | | +- html/ |
| +---------------------------------------+ | +- xml/ |
| +-----------------+
| |
| /------------/
| |
| v
| +---------------------------------------+ +--------------------+
\---->| sphinx |--->| .build/docs/sphinx |
| +- conf.py | | +- html/ |
| +- _static/ | +--------------------+
| +- *.rst |
+---------------------------------------+
files
README this file
CMakeLists.txt build entry point
conf.py sphinx config
_static static files for sphinx
map
index.rst
+- install.rst
+- examples.rst
+- unit-quantities.rst
+- classes.rst
+- glossary.rst
...
examples
.. doxygenclass:: ${c++ class name}
:project:
:path:
:members:
:protected-members:
:private-members:
:undoc-members:
:member-groups:
:members-only:
:outline:
:no-link:
:allow-dot-graphs:
.. doxygendefine:: ${c preprocessor define}
.. doxygenconcept:: ${c++ concept definition}
.. doxygenenum:: ${c++ enum definition}
.. doxygenfunction:: ${c++ function name}

1
xo-unit/docs/_static/README vendored Normal file
View file

@ -0,0 +1 @@
add any static {.html, .js, ..} files for sphinx to pickup here

BIN
xo-unit/docs/_static/img/favicon.ico vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 302 KiB

76
xo-unit/docs/basis-unit-class.rst Normal file
View file

@ -0,0 +1,76 @@
.. _basis-unit-class:
Basis Unit
==========
A unit representing a fixed multiple of a native dimension.
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
|cBLU basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
Introduction
------------
A :code:`basis_unit` represents a unit belonging to a single native dimension.
For example :code:`bu::meter` representing a distance of 1 meter.
.. code-block:: cpp
#include <xo/unit/basis_unit.hpp>
.. uml::
:scale: 99%
:align: center
:caption: basis unit representing 1 minute
object bu1<<basis_unit>>
bu1 : native_dim = time
bu1 : scalefactor = 60
:code:`basis_unit` is intended as an implementation-level abstraction.
Application code will normally interact with the more-capable :code:`scaled_unit`
instead of :code:`basis_unit`.
Class
-----
.. doxygenclass:: xo::qty::basis_unit
Member Variables
----------------
.. doxygengroup:: basis-unit-instance-vars
Constructors
------------
.. doxygengroup:: basis-unit-constructors
Access Methods
--------------
.. doxygengroup:: basis-unit-access-methods
Comparison
----------
.. doxygengroup:: basis-unit-comparison-support

60
xo-unit/docs/basis-unit-constants.rst Normal file
View file

@ -0,0 +1,60 @@
.. _basis-unit-constants:
Basis Unit Constants
====================
Relative scalefactors for each built-in unit.
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
|cBLU basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
Introduction
------------
Constants in the :code:`xo::qty::detail::bu` namespace represent
low-level building blocks for specifying units.
Relative scalefactors for each unit are chosen here.
Application code will not typically use these values directtly;
instead it's expected to use units from the :code:`xo::qty::u` namespace.
Those units are implemented on top of the basis units described here.
.. code-block:: cpp
#include <xo/unit/basis_unit.hpp>
using xo::qty::detail::bu;
Mass Units
----------
.. doxygengroup:: basis-unit-mass-units
Distance Units
--------------
.. doxygengroup:: basis-unit-distance-units
Time Units
----------
.. doxygengroup:: basis-unit-time-units

31
xo-unit/docs/basis-unit-reference.rst Normal file
View file

@ -0,0 +1,31 @@
.. _basis-unit-reference:
Basis Unit Reference
====================
Built-in named units for each native dimension
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
|cBLU basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. toctree::
:maxdepth: 1
Basis Unit Class <basis-unit-class>
basis-unit-constants

98
xo-unit/docs/bpu-class.rst Normal file
View file

@ -0,0 +1,98 @@
.. _bpu-class:
BPU
===
A rational (usually integral) power of a single basis unit
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
|cBLU bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
Introduction
------------
.. code-block:: cpp
#include <xo/unit/bpu.hpp>
A :code:`xo::qty::bpu` (aka "basis power unit") represents a rational (usually integer) power of a :doc:`basis-unit-class`.
For example:
.. uml::
:caption: representation for cubic millimeters
:scale: 99%
:align: center
object mm3<<bpu>>
mm3 : native_dim = dim::distance
mm3 : scalefactor = 1/1000
mm3 : power = 3/1
.. uml::
:caption: representation for annual (365-day) volatility
:scale: 99%
:align: center
object vol<<bpu>>
vol : native_dim = dim::time
vol : scalefactor = 365*24*3600
vol : power = -1/2
:code:`bpu` is intended as an implementation-level abstraction.
Application code will normally interact with the more-general :code:`scaled_unit`
instead of :code:`bpu`.
Class
-----
.. doxygenclass:: xo::qty::bpu
Member Variables
----------------
.. doxygengroup:: bpu-instance-vars
Constructors
------------
.. doxygengroup:: bpu-ctors
Access Methods
--------------
.. doxygengroup:: bpu-access-methods
Other Methods
-------------
.. doxygengroup:: bpu-methods
Comparison
----------
.. doxygengroup:: bpu-comparison
Details
-------
.. doxygengroup:: bpu-abbrev-helpers

129
xo-unit/docs/bu-store-class.rst Normal file
View file

@ -0,0 +1,129 @@
.. _bu-store-class:
Basis Unit Store
================
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
|cBLU bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. code-block:: cpp
#include <xo/unit/bu_store.hpp>
namespace bu = xo::qty::detail::bu;
A :code:`xo::qty::bu_store` is a small, constexpr, key-value store associating
abbreviations with basis units. To satisfy the constexpr requirement,
all unit abbreviations are irrevocably established from ``bu_store``'s constructor.
The constant ``bu_abbrev_store`` contains a single instance of ``bu_store``,
recording all built-in units along with their associated abbreviations
.. uml::
:caption: basis-unit store
:scale: 99%
:align: center
map mass_table<<bu_dim_store>> {
bu::milligram => "mg"
bu::gram => "g"
bu::kilogram => "kg"
}
map distance_table<<bu_dim_store>> {
bu::millimeter => "mm"
bu::meter => "m"
bu::kilometer => "km"
}
map time_table<<bu_dim_store>> {
bu::millisecond => "ms"
bu::second => "s"
bu::minute => "min"
bu::hour => "hr"
}
object bu_abbrev_store<<bu_store>>
bu_abbrev_store : bu_abbrev_vv[dim::mass] = mass_table
bu_abbrev_store : bu_abbrev_vv[dim::distance] = distance_table
bu_abbrev_store : bu_abbrev_vv[dim::time] = time_table
bu_abbrev_store o-- mass_table
bu_abbrev_store o-- distance_table
bu_abbrev_store o-- time_table
This class exists to support the implementation of ``natural_unit::abbrev()``.
Application code is not expected to interact directly with it.
Class
-----
.. doxygenclass:: xo::qty::detail::bu_store
For example, this would be possible:
.. code-block:: cpp
#include <xo/unit/bu_store.hpp>
namespace bu = using xo::qty::detail::bu;
using xo::qty::detail::bu_store;
using xo::qty::dim;
using xo::flatstring;
constexpr bu_store store;
static_assert(store.bu_abbrev(bu::minute) == flatstring("min"));
static_assert(store.bu_abbrev(bu::microgram) == flatstring("ug"));
.. doxygengroup:: bu-store-constructors
.. doxygengroup:: bu-store-access-methods
.. doxygengroup:: bu-store-implementation-methods
.. doxygenclass:: xo::qty::detail::bu_dim_store
.. doxygengroup:: bu-dim-store-type-traits
.. doxygengroup:: bu-dim-store-instance-vars
Constants
---------
Provides dictionary of unit abbreviations
Application code is not expected to interact directly with ``bu_abbrev_store``.
.. doxygenvariable:: xo::qty::bu_abbrev_store
Functions
---------
.. doxygenfunction:: xo::qty::bu_abbrev
For example:
.. code-block:: cpp
#include <xo/unit/bu_store.hpp>
namespace bu = xo::qty::bu;
using xo::qty::bu_abbrev;
using xo::flatstring;
static_assert(bu_abbrev(bu::kilogram) == xo::flatstring("kg"));

39
xo-unit/docs/conf.py Normal file
View file

@ -0,0 +1,39 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'xo unit documentation'
copyright = '2024, Roland Conybeare'
author = 'Roland Conybeare'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
#extensions = []
extensions = [ "breathe",
"sphinx.ext.mathjax", # inline math
"sphinx.ext.autodoc", # generate info from docstrings
"sphinxcontrib.ditaa", # diagrams-through-ascii-art
"sphinxcontrib.plantuml" # text -> uml diagrams
]
# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in
# match project name in Doxyfile.in
breathe_default_project = "xodoxxml"
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
#html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_favicon = '_static/img/favicon.ico'

18
xo-unit/docs/development.rst Normal file
View file

@ -0,0 +1,18 @@
.. _development:
Development
===========
Miscellaneous development notes for *xo-unit*.
Addding a Basis Unit
--------------------
To add a basis unit for an existing dimension:
#. add unit definition to the ``xo::qty::bu`` namespace in ``include/xo/unit/basis_unit.hpp``
#. add call to ``bu_store::bu_establish_abbrev()`` from ``bu_store::bu_store``.
#. add ``natural_unit`` definition to ``xo::qty::nu`` namespace in ``include/xo/unit/natural_unit.hpp``
#. add ``scaled_unit`` definition to ``xo::qty::u`` namespace in ``include/xo/unit/scaled_unit.hpp``.
#. add unit quantity to ``xo::qty::qty`` namespace in ``include/xo/unit/quantity.hpp``
#. add factory function to ``xo::qty::qty`` namespace in ``include/xo/unit/quantity.hpp``

66
xo-unit/docs/dimension-enum.rst Normal file
View file

@ -0,0 +1,66 @@
.. _dimension:
Native Dimension
================
An abstract dimension; distinct native dimensions are orthogonal
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
|cBLU dimension |
+--------------------------------+
Introduction
------------
Identifies an abstract dimension, for example *mass* or *time*.
.. code-block:: cpp
#include <xo/unit/dimension.hpp>
For example can use this enum to index basis members of a :doc:`scaled_unit<scaled-unit-class>` instance:
.. code-block:: cpp
:emphasize-lines: 7-8
#include <xo/unit/quantity.hpp>
using namespace xo::qty;
auto x = q::kilometers(100) / q::hours(1);
auto bpu1 = x.lookup_dim(dim::time);
auto bpu2 = x.lookup_dim(dim::distance);
Enum
----
.. doxygenenum:: xo::qty::dimension
Constants
---------
.. doxygenvariable:: xo::qty::n_dim
Functions
---------
.. doxygenfunction:: xo::qty::dim2str

366
xo-unit/docs/examples.rst Normal file
View file

@ -0,0 +1,366 @@
.. _examples:
.. toctree
:maxdepth: 2
Examples
========
Compile-time unit inference
---------------------------
See ``xo-unit/examples/ex1`` for code below.
Units propagate through familiar arithmetic expressions:
.. code-block:: cpp
:linenos:
:emphasize-lines: 14-15
#include "xo/unit/quantity.hpp"
#include "xo/unit/quantity_iostream.hpp"
#include <iostream>
int
main () {
namespace q = xo::qty::qty;
namespace su = xo::qty::su;
using namespace std;
constexpr auto t = q::minutes(2);
constexpr auto d = q::kilometers(2.5);
constexpr auto t2 = t*t;
constexpr auto a = d / (t*t);
cerr << "t: " << t << ", d: " << d
<< ", t^2: " << t2
<< ", d.t^-2: " << a
<< endl;
}
with output:
.. code-block::
t: 2min, d: 2.5km, t^2: 4min^2, d.t^-2: 0.625km.min^-2
We can use static asserts to prove that units are being computed at compile-time
.. code-block:: cpp
:linenos:
static_assert(std::same_as<decltype(t)::repr_type, int>);
static_assert(sizeof(t) == sizeof(double));
static_assert(t.scale() == 2);
static_assert(t.abbrev() == flatstring("min"));
static_assert(std::same_as<decltype(d)::repr_type, double>);
static_assert(sizeof(d) == sizeof(double));
static_assert(d.scale() == 2.5);
static_assert(d.abbrev() == flatstring("km"));
static_assert(std::same_as<decltype(t2)::repr_type, int>);
static_assert(sizeof(t2) == sizeof(double));
static_assert(t2.scale() == 4);
static_assert(t2.abbrev() == flatstring("min^2"));
static_assert(std::same_as<decltype(a)::repr_type, double>);
static_assert(sizeof(a) == sizeof(double));
static_assert(a.scale() == 0.625);
static_assert(a.abbrev() == flatstring("km.min^-2"));
Remarks:
- ``xo::qty::quantity`` performs unit consistency checking and propagation at compile time. Runtime space/time overhead is zero.
- Units are sticky: since we expressed ``t`` in minutes, ``(t*t)`` and ``d/(t*t)`` also use minutes.
- Unit ordering is sticky. Distance appears on the left of time in printed value of ``d/(t*t)``
because it was on the left-hand side of ``operator/``
- ``xo-unit`` copies representation from the argument to factory functions ``q::minutes``, ``q::kilometers`` etc.
- Binary operators take representation from the 'most precise' argument, as prescribed by ``std::common_type_t``.
- Unit abbreviations (such as ``kg.min^-2`` above) are computed at compile time.
See ``xo::flatstring`` for constexpr string implementation.
- See ``xo::xquantity`` for parallel implementation that defers unit checking until runtime.
Explicit scale conversion
-------------------------
Can convert between compatible units explictly,
using:
1. ``xo::qty::with_units`` (template function)
2. ``quantity.rescale_ext`` (template method)
3. ``xo::qty::with_units_from`` (template function)
See ``xo-unit/examples/ex2`` for code below.
.. code-block:: cpp
:linenos:
:emphasize-lines: 10,13,16-17
#include "xo/unit/quantity.hpp"
#include "xo/unit/quantity_iostream.hpp"
#include <iostream>
int
main () {
namespace q = xo::qty::qty;
namespace u = xo::qty::u;
using xo::qty::with_units_from;
using xo::qty::with_units;
using xo::qty::quantity;
using xo::flatstring;
using namespace std;
constexpr auto t = q::minutes(2);
constexpr auto d = q::kilometers(2.5);
constexpr auto t2 = t*t;
constexpr auto a = d / (t*t);
cerr << "t: " << t << ", d: " << d
<< ", t^2: " << t2
<< ", d.t^-2: " << a
<< endl;
constexpr auto a2 = with_units<u::meter / (u::second * u::second)>(a);
static_assert(a2.abbrev() == flatstring("m.s^-2"));
cerr << "a2: " << a2 << endl;
constexpr auto a3 = a.rescale_ext<u::meter / (u::second * u::second)>();
static_assert(a3.abbrev() == flatstring("m.s^-2"));
cerr << "a3: " << a3 << endl;
constexpr auto au = q::meter / (q::second * q::second);
constexpr auto a4 = with_units_from(a, au);
static_assert(a4.abbrev() == flatstring("m.s^-2"));
cerr << "a4: " << a4 << endl;
}
with output:
.. code-block:: cpp
a2: 0.173611m.s^-2
a3: 0.173611m.s^-2
a4: 0.173611m.s^-2
Implicit Scale conversion
-------------------------
Another way to convert units is to assign to a variable
with desired units -- this works because the units are encoded
as part of the assigned variable's type.
See ``xo-unit/example/ex3`` for code below
.. code-block:: cpp
:linenos:
:emphasize-lines: 12-13
int
main () {
namespace q = xo::qty::qty;
namespace u = xo::qty::u;
using xo::qty::quantity;
constexpr quantity<u::second> t = q::minutes(2);
constexpr quantity<u::meter> d = q::kilometers(2.5);
constexpr auto t2 = t*t;
constexpr auto a = d / (t*t);
std::cerr << "t: " << t << ", d: " << d
<< ", d.t^-2: " << a
<< std::endl;
}
with output:
.. code-block::
t: 120s, d: 2500m, d.t^-2: 0.17e611m.s^-2
Remarks:
- Assignment to ``t`` converted to representation ``double``.
We could have instead used :code:`quantity<u::second, int>` to propagate
right-hand-side representation
Scale conversion and arithmetic
-------------------------------
When representing a particular quantity,
xo-unit uses at most one scale for each :term:`basis dimension` associated with the unit for that quantity.
When an arithmetic operator encounters basis units involving two different scales,
the operator will adopt the scale provided by the left-hand argument:
See ``xo-unit/example/ex4`` for code below
.. code-block:: cpp
:linenos:
:emphasize-lines: 11
#include "xo/unit/quantity.hpp"
#include <iostream>
int main() {
namespace q = xo::qty::qty;
auto t1 = qty::milliseconds(1);
auto t2 = qty::minutes(1);
auto p = t1 * t2;
std::cerr << "t1: " << t1 << ", t2: " << t2 << ", p: " << p << std::endl;
}
with output:
.. code-block::
t1: 1ms, t2: 1min, t1*t2: 60000ms^2
Dimensionless quantities unwrap implicitly
------------------------------------------
Conversely, compiler rejects attempt to implictly unwrap a dimensioned quantity.
See ``xo-unit/examples/ex4`` for code below.
.. code-block:: cpp
:linenos:
:emphasize-lines: 23,26
#include "xo/unit/quantity.hpp"
#include "xo/unit/quantity_iostream.hpp"
#include <iostream>
int
main () {
namespace q = xo::qty::qty;
auto t1 = q::milliseconds(1);
auto t2 = q::minutes(1);
auto r1 = t1 / with_repr<double>(t2);
static_assert(r1.is_dimensionless());
static_assert(!t2.is_dimensionless());
static_assert(std::same_as<static_cast<double>(r1), double>);
// r1_value: assignment compiles, since r1 dimensionless
double r1_value = r1;
// r2_value: bad assignment won't compile, 'cannot convert' error
//double r2_value = t2;
std::cerr << "t1: " << t1 << ", t2: " << t2 << ", t1/t2: " << r1_value << std::endl;
}
with output:
.. code-block::
t1: 1ms, t2: 1min, t1/t2: 1.66667e-05
Fractional dimension
--------------------
Fractional dimensions have limited support.
Prior to c++26 we can only support fractional dimensions with denominator 2,
such as powers -3/2, -1/2, +1/2, +3/2 etc.
c++26 will enable support for support fractional dimensions involving other ratios,
by offering constexpr ``::pow()``
See ``xo-unit/examples/ex6`` for code below
.. code-block:: cpp
:linenos:
:emphasize-lines: 15
#include "xo/unit/quantity.hpp"
#include "xo/unit/quantity_iostream.hpp"
#include <iostream>
int
main () {
namespace u = xo::unit::units;
namespace q = xo::unit::qty;
using namespace std;
/* 20% volatility over 250 days (approx number of trading days in one year) */
auto q1 = q::volatility_250d(0.2);
/* 10% volatility over 30 days */
auto q2 = q::volatility_30d(0.1);
auto sum = q1 + q2;
auto prod = q1 * q2;
static_assert(sum.abbrev() == flatstring("yr360^(-1/2)"));
static_assert(prod.abbrev() == flatstring("yr360^-1"));
std::cerr << "q1: " << q1 << std::endl;
std::cerr << "q2: " << q2 << std::endl;
std::cerr << "q1+q2: " << sum << std::endl;
std::cerr << "q1*q2: " << prod << std::endl;
}
with output:
.. code-block::
q1: 0.2yr360^(-1/2)
q2: 0.1mo^(-1/2)
q1+q2: 0.54641yr360^(-1/2)
q1*q2: 0.069282yr360^-1
Dynamic dimension
-----------------
If the dimension (or units) associated with a quantity are not known at compile-time,
use ``xo::qty::xquantity`` instead of ``xo::qty::quantity``.
See ``xo-unit/example/ex8`` for code below
.. code-block:: cpp
:linenos:
:emphasize-lines: 10-12
#include "xo/unit/xquantity.hpp"
#include "xo/unit/xquantity_iostream.hpp"
#include <iostream>
int
main () {
using namespace xo::qty;
namespace u = xo::qty::u;
xquantity qty1(7, u::foot);
xquantity qty2(6.0, u::inch);
xquantity qty3 = qty1 + qty2;
std::cerr << "qty1: " << qty1 << std::endl;
std::cerr << "qty2: " << qty2 << std::endl;
std::cerr << "qty3: " << qty3 << std::endl;
/* rescale to mm */
xquantity res = qty3.rescale(xo::qty::nu::millimeter);
/* 2286mm */
std::cerr << "res: " << res << std::endl;
}
Here ``u::foot`` and ``u::inch`` are literals,
but they could have been read from console input or another runtime-only context.

43
xo-unit/docs/glossary.rst Normal file
View file

@ -0,0 +1,43 @@
.. _glossary:
Glossary
--------
.. glossary::
dimension
dim
| Fundamental, orthogonal directions associated available for constructing units.
| For example *mass*, *length*, *time*.
| In *xo-unit* these are represented by the enum :doc:`xo::qty::dimension<dimension-enum>`.
basis unit
bu
| An implementation type representing a quantity (with associated scale) in the direction of a single :term:`dimension`.
| For example *milliseconds*, *seconds*, and *hours* stand for different basis units within the *time* dimension.
| In *xo-unit* these are represented by the template type :doc:`xo::qty::basis_unit<basis-unit-class>`.
basis power unit
bpu
| A rational power of a (single) basis unit.
| For example :math:`s^{-2}` for unit "per second squared" or :math:`yr^{-(1/2)}` for "per square-root of a year".
| In *xo-unit* these are represented by the template type :doc:`xo::qty::bpu<bpu-class>`
natural unit
nu
| A cartesian product of basis power units (bpus);
| For example :math:`kg.m.s^{-2}` or :math:`hr^{-(1/2)}`.
| In *xo-unit* these are represented by template type :doc:`xo::qty::natural_unit<natural-unit-class>`.
scaled unit
su
| A dimensionless multiple of a natural unit.
| Used as intermediate value when coalescing quantities involving different units.
| In *xo-unit* these are represented by template type :doc:`xo::qty::scaled_unit<scaled-unit-class>`.
XO
A set of integrated c++ libraries for complex event processing, with browser and python integration.
`xo documentation here`_
.. _xo documentation here: https://rconybea.github.io/web/sw/xo.html
.. toctree::

314
xo-unit/docs/implementation.rst Normal file
View file

@ -0,0 +1,314 @@
.. _implementation:
Components
==========
Library dependency tower for *xo-unit*:
.. ditaa::
+-----------------+
| xo_unit |
+-----------------+
| xo_ratio |
+-----------------+
| xo_flatstring |
+-----------------+
| xo_cmake |
+-----------------+
Install instructions :doc:`here<install>`
Abstraction tower for *xo-unit* components:
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
- :doc:`quantity<quantity-reference>`:
A quantity with unit checking and conversion done at compile-time
.. code-block:: cpp
#include "xo/unit/quantity.hpp"
auto q1 = xo::qty::qty::kilometers(7.5);
- :doc:`xquantity<xquantity-reference>`:
A quantity with unit checking and conversion done at run-time.
This is useful if unit information isn't known at compile time, for example
if reading units from console input.
.. code-block:: cpp
#include "xo/unit/xquantity.hpp"
xquantity qty1(7.5, xo::qty::u::foot)
- :doc:`scaled_unit<scaled-unit-class>`:
.. code-block:: cpp
#include "xo/unit/scaled_unit.hpp"
auto u = xo::qty::u::millimeter;
A unit involving zero or more dimensions, and associated conversion factor.
- can express result of arithmetic involving multiple scales,
by reporting an outer scalefactor
- a scaled unit is 'natural' if its outer scalefactor is 1.
- quantities are represented by associating a natural scaled_unit instance
- scaled_units are closed under multiplication and division.
- multiplication and division commit to a single :code:`basis_unit` for each
dimension.
- :doc:`natural_unit<natural-unit-class>`
.. code-block:: cpp
#include "xo/unit/natural_unit.hpp"
auto u = xo::qty::nu::millimeter;
A unit involving zero or more dimensions, and at most one scale per dimension.
A quantity instance is always represented as a dimensionless multiple
of a natural unit
- natural_units are *not* closed under multiplication and division.
(for example consider :code:`xo::qty::qty::foot * xo::qty::qty::meter`)
- :doc:`bpu<bpu-class>`
A rational (usually integer) power of a basis unit. Has a single dimension.
.. code-block:: cpp
#include "xo/unit/bpu.hpp"
xo::qty::bpu(xo::qty::detail::bu::millimeter,
xo::qty::power_ratio_type(2)); // mm^2
- :doc:`bu_store<bu-store-class>`
Associates basis units with abbreviations.
Abbreviations used to decorate printed quantities.
For example ``bu::kilogram`` => ``"kg"``
.. code-block:: cpp
#include "xo/unit/bu_store.hpp"
xo::qty::bu_abbrev_store.bu_abbrev(xo::qty::detail::bu::picogram); // "pg"
- :doc:`basis_unit<basis-unit-reference>`
A unit with a single dimension and scale.
.. code-block:: cpp
#include "xo/unit/basis_unit.hpp"
auto b = xo::qty::detail::bu::picogram;
- :doc:`dimension<dimension-enum>`
identifies a dimension, such as mass or time.
.. code-block:: cpp
#include "xo/unit/dimension.hpp"
auto d = xo::qty::dimension::mass;
Representation
==============
Worked example using :cpp:class:`xo::qty::quantity`.
.. code-block:: cpp
:linenos:
:emphasize-lines: 6
#include "xo/unit/quantity.hpp"
...
using xo::qty;
namespace q = xo::qty::qty;
// 7.55km.min^-2
quantity qty1 = 7.55 * q::kilometer / (q::minute * q::minute);
Note: in diagrams below, components with pale blue background are discarded before runtime
.. uml::
:caption: representation for quantity 7.55km.min^-2
:scale: 99%
:align: center
object qty1<<quantity>>
qty1 : scale = 7.55
rectangle #e0f0ff {
object km_per_min2<<natural_unit>>
km_per_min2 : n_bpu = 2
km_per_min2 : bpu[0] = km
km_per_min2 : bpu[1] = per_min
object km<<bpu>>
km : native_dim = dim.mass
km : scalefactor = 1000/1
km : power = 1
object per_min2<<bpu>>
per_min2 : native_dim = dim.time
per_min2 : scalefactor = 60/1
per_min2 : power = -2
qty1 o-- km_per_min2 : s_unit (static constexpr)
km_per_min2 *-- km
km_per_min2 *-- per_min2
}
.. code-block:: cpp
:linenos:
// 123ng
quantity qty2 = q::nanograms(123);
.. uml::
:caption: representation for quantity 123 nanograms
:scale: 99%
:align: center
object qty2<<quantity>>
qty2 : scale = 123
rectangle #e0f0ff {
object ng_unit<<natural_unit>>
ng_unit : n_bpu = 1
ng_unit : bpu[0] = ng
object ng<<bpu>>
ng : native_dim = dim::mass
ng : scalefactor = 1/10^9
ng : power = 1
qty2 o-- ng_unit : s_unit (static constexpr)
ng_unit *-- ng
}
.. code-block:: cpp
:linenos:
// (123*7.55) ng.km.min^-2
quantity qty3 = qty2 * qty1;
.. uml::
:caption: quantity 928.65 ng.km.min^-2
:scale: 99%
:align: center
object qty3<<quantity>>
qty3 : scale = 928.65
rectangle #e0f0ff {
object ng_km_min2_unit<<natural_unit>>
ng_km_min2_unit : n_bpu = 3
ng_km_min2_unit : bpu[0] = ng
ng_km_min2_unit : bpu[1] = km
ng_km_min2_unit : bpu[2] = per_min2
object ng<<bpu>>
ng : native_dim = dim::mass
ng : scalefactor = 1/10^9
ng : power = 1
object km<<bpu>>
km : native_dim = dim::distance
km : scalefactor = 1000/1
km : power = 1
object per_min2<<bpu>>
per_min2 : native_dim = dim::time
per_min2 : scalefactor = 60/1
per_min2 : power = -2
qty3 o-- ng_km_min2_unit : s_unit (static constexpr)
ng_km_min2_unit *-- ng
ng_km_min2_unit *-- km
ng_km_min2_unit *-- per_min2
}
.. code-block:: cpp
:linenos:
namespace u = xo::qty::u;
// (123*7.55) ng.km.min^-2 ==> 2.57958e-10kg.m.s^-2
constexpr auto newton = u::kilogram * u::meter / (u::second * u::second);
quantity<newton> qty3b = qty3;
// quantity qty3b = qty3.rescale_ext<newton>();
.. uml::
:caption: quantity 928.65 ng.km.min^-2
:scale: 99%
:align: center
object qty3b<<quantity>>
qty3b : scale = 2.59758e-10
rectangle #e0f0ff {
object kg_m_s2_unit<<natural_unit>>
kg_m_s2_unit : n_bpu = 3
kg_m_s2_unit : bpu[0] = kg
kg_m_s2_unit : bpu[1] = m
kg_m_s2_unit : bpu[2] = per_s2
object kg<<bpu>>
kg : native_dim = dim::mass
kg : scalefactor = 1000/1
kg : power = 1
object m<<bpu>>
m : native_dim = dim::distance
m : scalefactor = 1/1
m : power = 1
object per_s2<<bpu>>
per_s2 : native_dim = dim::time
per_s2 : scalefactor = 1/1
per_s2 : power = -2
qty3b o-- kg_m_s2_unit : s_unit (static constexpr)
kg_m_s2_unit *-- kg
kg_m_s2_unit *-- m
kg_m_s2_unit *-- per_s2
}
.. toctree::
:maxdepth: 2
:caption: Abstractions

48
xo-unit/docs/index.rst Normal file
View file

@ -0,0 +1,48 @@
.. xo-unit-examples documentation master file, created by
sphinx-quickstart on Wed Mar 6 23:32:27 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
xo-unit documentation
=====================
xo-unit is a lightweight header-only library that provides compile-time
dimension checking and unit conversion.
Functionality is similar in spirit to that provided by ``boost::units``;
however there are some important differences:
* streamlined implementation using c++20 features.
* along with no-runtime-overhead compile-time unit inference,
also provides defer-until-runtime representation.
* constexpr string representation for things like unit abbreviations.
* supports fractional dimensions, for concepts like volatility.
* integration with python (see sister project xo-pyunit)
Second, ``xo-unit`` supports fractional dimensions. This allows using it to naturally handle
concepts like volatility (dimension 1/sqrt(time)), for example.
Finally, ``xo-unit`` is written with the expectation of providing
python integration via pybind11. This requires a parallel set of data structures that can work at
runtime (since we can't construct new c++ types at runtime).
.. toctree::
:maxdepth: 2
:caption: xo-unit contents
install
examples
implementation
quantity-reference
xquantity-reference
scaled-unit-reference
natural-unit-class
bpu-class
bu-store-class
basis-unit-reference
dimension-enum
development
ubuntu-github-workflow
glossary
genindex
search

305
xo-unit/docs/install.rst Normal file
View file

@ -0,0 +1,305 @@
.. _install:
.. toctree
:maxdepth: 2
Install
=======
``xo-unit`` uses supporting header-only libraries ``xo-ratio`` and ``xo-flatstring``.
and (optionally) cmake macros ``xo-cmake``. These are on github:
- `xo-unit source`_ (constexpr quantities, units and dimension-checking)
- `xo-ratio source`_ (constexpr exact ratios)
- `xo-flatstring source`_ (constexpr strings)
- `xo-cmake source`_ (shared cmake macros)
.. _xo-unit source: https://github.com/rconybea/xo-unit
.. _xo-ratio source: https://github.com/rconybea/xo-ratio
.. _xo-flatstring source: https://github.com/rconybea/xo-flatstring
.. _xo-cmake source: https://github.com/rconybea/xo-cmake
`xo-cmake` is nccessary to invoke `xo` cmake build for:
- site install
- example programs
- unit tests
Can omit to instead copy `xo_unit`, `xo-ratio` and `xo-flatstring` source trees;
see instructions below for including as git submodule
Implementation relies on some c++20 features (for example class-instances as template arguments).
Tested with gcc 12.3, 13.2
Include as submodule
--------------------
One way to use ``xo-unit`` in a project is to import the source tree directly:
.. code-block:: bash
cd myproject
git submodule add -b main https://github.com/rconybea/xo-flatstring ext/xo-flatstring
git submodule add -b main https://github.com/rconybea/xo-ratio ext/xo-ratio
git submodule add -b main https://github.com/rconybea/xo-unit ext/xo-unit
git submodule update --init
This assumes you organize directly-incorporated dependencies under directory ``myproject/ext``.
You would then add to your compiler's include path the directories ``myproject/ext/xo-flatstring/include``,
``myproject/ext/xo-ratio/include``, ``myproject/ext/xo-unit/include``;
and add
.. code-block:: c++
#include <xo/unit/quantity.hpp>
to c++ source files that rely on xo-unit
Ubuntu Install Pattern
----------------------
:doc:`Example instructions<ubuntu-github-workflow>` (used for github actions CI) for build starting from stock ubuntu
Installing from source
----------------------
Install scripts for `xo-unit`, `xo-ratio` and `xo-flatstring` depend on shared cmake macros
and a bootstrap script `xo-cmake-config` from `xo-cmake`.
Preamble:
.. code-block:: bash
mkdir -p ~/proj/xo
cd ~/proj/xo
git clone https://github.com/rconybea/xo-cmake
git clone https://github.com/rconybea/xo-flatstring
git clone https://github.com/rconybea/xo-ratio
git clone https://github.com/rconybea/xo-unit
PREFIX=~/local # ..or other desired installation prefix
Ordering below is important; cmake support for each subsystem
requires successful installation of its predecessor.
Install `xo-cmake`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-cmake/.build -S xo-cmake
cmake --build xo-cmake/.build -j # placeholder, no-op for now
cmake --install xo-cmake/.build
Build and Install `xo-flatstring`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_TESTING=0 \
-B xo-flatstring/.build -S xo-flatstring
cmake --build xo-flatstring/.build -j
cmake --install xo-flatstring/.build
Build and Install `xo-ratio`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_TESTING=0 \
-B xo-ratio/.build -S xo-ratio
cmake --build xo-ratio/.build -j
cmake --install xo-ratio/.build
Build and Install `xo-unit`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_TESTING=0 \
-B xo-unit/.build -S xo-unit
cmake --build xo-unit/.build -j
cmake --install xo-unit/.build
Directories under ``PREFIX`` will then contain:
.. code-block::
PREFIX
+- bin
| \- xo-cmake-config
+- include
| \- xo
| +- cxxutil/
| +- flatstring/
| +- ratio/
| +- unit/
+- lib
| \- cmake
| +- indentlog/
| +- randomgen/
| +- xo_flatstring/
| \- xo_unit/
+- share
\- cmake
\- xo_macros/
Use CMake Support
-----------------
To use built-in cmake suport:
Make sure ``PREFIX/lib/cmake`` is searched by cmake (if necessary, include it in ``CMAKE_PREFIX_PATH``)
Add to ``CMakeLists.txt``:
.. code-block:: cmake
FindPackage(xo_unit CONFIG REQUIRED)
target_link_libraries(mytarget INTERFACE xo_unit)
Build and Install with Unit Tests Enabled
-----------------------------------------
Running unit tests require a few additional dependencies:
* `catch2`_ header-only unit-test framework
* `xo-indentlog`_ logging with call-structure indenting
* `xo-randomgen`_ fast random number generator (xoshiro256ss)
.. _catch2: https://github.com/catchorg/Catch2
.. _xo-indentlog: https://github.com/rconybea/indentlog
.. _xo-randomgen: https://github.com/rconybea/randomgen
Preamble:
.. code-block:: bash
mkdir -p ~/proj/xo
cd ~/proj/xo
git clone https://github.com/rconybea/xo-cmake
git clone https://github.com/rconybea/indentlog xo-indentlog
git clone https://github.com/rconybea/randomgen xo-randomgen
git clone https://github.com/rconybea/xo-flatstring
git clone https://github.com/rconybea/xo-ratio
git clone https://github.com/rconybea/xo-unit
PREFIX=~/local # ..or other desired installation prefix
Build and Install `catch2` (assuming ubuntu here):
.. code-block:: bash
sudo apt-get install catch2 # on ubuntu, for example
Build and Install `xo-cmake`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-cmake/.build -S xo-cmake
cmake --build xo-cmake/.build -j # placeholder, no-op for now
cmake --install xo-cmake/.build
Build, Test and Install `xo-indentlog`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-indentlog/.build -S xo-indentlog
cmake --build xo-indentlog/.build -j
cmake --build xo-indentlog/.build -- test # run unit tests, cmake invokes ctest
(cd xo-indentlog/.build && ctest) # or invoke ctest directly
cmake --install xo-indentlog/.build
Build and Install `xo-randomgen` (no unit tests yet):
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-randomgen/.build -S xo-randomgen
cmake --build xo-randomgen/.build -j
cmake --install xo-randomgen/.build
Build, Test and Install `xo-flatstring`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-flatstring/.build -S xo-flatstring
cmake --build xo-flatstring/.build -j
cmake --build xo-flatstring/.build -- test # run unit tests, cmake invokes ctest
(cd xo-flatstring/.build && ctest) # or invoke ctest directly
cmake --install xo-flatstring/.build
Build, Test and Install `xo-ratio`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-ratio/.build -S xo-ratio
cmake --build xo-ratio/.build -j
cmake --build xo-ratio/.build -- test # run unit tests, cmake invokes ctest
(cd xo-ratio/.build && ctest) # or invoke ctest directly
cmake --install xo-ratio/.build
Build, Test and Install `xo-unit`:
.. code-block:: bash
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-unit/.build -S xo-unit
cmake --build xo-unit/.build -j
cmake --build xo-unit/.build -- test # run unit tests, cmake invokes ctest
(cd xo-unit/.build && ctest) # or invoke ctest directly
cmake --install xo-unit/.build
Build Examples
--------------
To enable building example programs:
.. code-block:: bash
cd ~/proj/xo
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DXO_ENABLE_EXAMPLES=1 -B xo-unit/.build -S xo-unit
Run examples from the build directory:
.. code-block:: bash
~/proj/xo/xo-unit/.build/example/ex1/xo_unit_ex1
~/proj/xo/xo-unit/.build/example/ex2/xo_unit_ex2
# etc
Build and Install Documentation
-------------------------------
xo-unit documentation has these additional dependencies:
* `doxygen`_ annotation-driven inline documentation
* `sphinx`_ documentation based on ReST files
* `sphinx-rtd-theme`_ popular CSS theme for sphinx
* `breathe`_ make doxygen-generated ingredients available from sphinx
.. _doxygen: https://www.doxygen.nl
.. _sphinx: https://www.sphinx-doc.org
.. _sphinx-rtd-theme: https://pypi.org/project/sphinx-rtd-theme
.. _breathe: https://breathe.readthedocs.io/en/latest
Preamble (assuming ubuntu here):
.. code-block:: bash
sudo apt-get install doxygen
sudo apt-get install python3-sphinx
sudo apt-get install python3-sphinx-rtd-theme
sudo apt-get install python3-breathe
Build `xo-unit` docs
.. code-block:: bash
cd ~/proj/xo
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-unit/.build
cmake --build xo-unit/.build -- docs
cmake --install xo-unit/.build # if docs built, installs to $PREFIX/share/doc/xo_unit/html
Supported compilers
-------------------
* developed with gcc 12.3.0 and gcc 13.2.0; github CI using gcc 11.4.0 (asof March 2024)

109
xo-unit/docs/natural-unit-class.rst Normal file
View file

@ -0,0 +1,109 @@
.. _natural-unit-class:
Natural Unit
============
A natural unit represents a product of terms, each involving a distinct basis dimension
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
|cBLU natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
Introduction
------------
.. code-block:: cpp
#include <xo/unit/natural_unit.hpp>
Representation for the unit associated with a :doc:`xquantity<xquantity-class>`
- represents a cartesian product of basis units.
- constexpr implementation
- limited support for fractional dimensions such as time^-1/2
.. uml::
:caption: natural unit for a Newton (unit of force)
:scale: 99%
:align: center
object newton<<natural_unit>>
newton : n_bpu = 3
newton : bpu_v[]
object kg<<bpu>>
kg : native_dim = dim::mass
kg : scalefactor = 1000/1
kg : power = 1/1
object m<<bpu>>
m : native_dim = dim::distance
m : scalefactor = 1/1
m : power = 1/1
object s2<<bpu>>
s2 : native_dim = dim::time
s2 : scalefactor = 1/1
s2 : power = -2/1
newton o-- kg
newton o-- m
newton o-- s2
Class
-----
.. doxygenclass:: xo::qty::natural_unit
Member Variables
----------------
.. doxygengroup:: natural-unit-instance-vars
Type Traits
-----------
.. doxygengroup:: natural-unit-type-traits
Constructors
------------
.. doxygengroup:: natural-unit-ctors
Access Methods
--------------
.. doxygengroup:: natural-unit-access-methods
General Methods
---------------
.. doxygengroup:: natural-unit-methods
Conversion
----------
.. doxygengroup:: natural-unit-conversion-methods
Comparison Functions
--------------------
.. doxygengroup:: natural-unit-comparison-functions

144
xo-unit/docs/quantity-class.rst Normal file
View file

@ -0,0 +1,144 @@
.. _quantity-class:
Quantity
========
Dimensioned quantity with compile-time unit checking/conversion
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. code-block:: cpp
#include <xo/unit/quantity.hpp>
.. uml::
:scale: 99%
:align: center
allowmixing
object qty1<<quantity>>
qty1 : scale = 1.23
rectangle constexpr #e0f0ff {
object unit<<scaled_unit>>
unit : is_natural() = true
qty1 o-- unit : s_scaled_unit (static constexpr)
}
- Arithmetic on :doc:`xo::qty::quantity<quantity-reference>` instances
does *not* use ``xo::qty::quantity::s_scaled_unit`` at runtime;
instead gets everything it needs at compile time.
- The :code:`xo::qty::quantity` template takes a :doc:`xo::qty::scaled_unit<scaled-unit-class>` instance,
but only accepts values with :code:`xo::qty::scaled_unit::is_natural() == true`.
This accomodation (instead of requiring a :doc:`xo::qty::natural_unit<natural-unit-class>` instance
is to make possible code like this possible:
.. code-block:: cpp
#include "xo/unit/quantity.hpp"
using namespace xo::qty;
quantity<u::meter / u::second> x;
quantity<u::meter * u::mter> y;
while rejecting attempt to mix multiple scales in the same quantity value:
.. code-block:: cpp
quantity<u::meter * u::millimeter> x; // will not compile
Class
-----
The primary data structure for interacting with xo-unit is the
template class ``xo::qty::quantity``.
A quantity is a compile-time wrapper around a single arithmetic value,
with type taken from the ``Repr`` parameter in ``quantity<Unit, Repr>``.
.. doxygenclass:: xo::qty::quantity
Member Variables
----------------
.. doxygengroup:: quantity-static-vars
.. doxygengroup:: quantity-instance-vars
Type Traits
-----------
.. doxygengroup:: quantity-type-traits
Constructors
------------
.. doxygengroup:: quantity-ctors
The simplest way to create a quantity instance is to use either
* factory functions in ``xo::qty::qty``, see :doc:`quantity-factoryfunctions`
* unit variables in ``xo::qty::qty``, see :doc:`quantity-unitvars`
Assignment
----------
.. doxygengroup:: quantity-assignment
Access Methods
--------------
.. doxygengroup:: quantity-access-methods
Constants
---------
.. doxygengroup:: quantity-constants
Conversion Methods
------------------
Amount-preserving conversion to quantities with different units and/or representation.
.. doxygengroup:: quantity-unit-conversion
Arithmetic
----------
.. doxygengroup:: quantity-operators
Support methods for arithmetic operations
.. doxygengroup:: quantity-arithmetic-support
Comparison
----------
Support methods for comparison operators
.. doxygengroup:: quantity-comparison-support

94
xo-unit/docs/quantity-factoryfunctions.rst Normal file
View file

@ -0,0 +1,94 @@
.. _quantity_factoryfunctions:
Quantity Factory Functions
==========================
Convenience functions for creating quantities with compile-time units
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. toctree::
:maxdepth: 2
Introduction
------------
.. code-block:: cpp
#include <xo/unit/quantity.hpp>
Mass
----
.. doxygenfunction:: xo::qty::qty::picograms
.. doxygenfunction:: xo::qty::qty::nanograms
.. doxygenfunction:: xo::qty::qty::micrograms
.. doxygenfunction:: xo::qty::qty::milligrams
.. doxygenfunction:: xo::qty::qty::grams
.. doxygenfunction:: xo::qty::qty::kilograms
.. doxygenfunction:: xo::qty::qty::tonnes
.. doxygenfunction:: xo::qty::qty::kilotonnes
.. doxygenfunction:: xo::qty::qty::megatonnes
.. doxygenfunction:: xo::qty::qty::gigatonnes
Distance
--------
.. doxygenfunction:: xo::qty::qty::picometers
.. doxygenfunction:: xo::qty::qty::nanometers
.. doxygenfunction:: xo::qty::qty::micrometers
.. doxygenfunction:: xo::qty::qty::millimeters
.. doxygenfunction:: xo::qty::qty::meters
.. doxygenfunction:: xo::qty::qty::kilometers
.. doxygenfunction:: xo::qty::qty::megameters
.. doxygenfunction:: xo::qty::qty::gigameters
.. doxygenfunction:: xo::qty::qty::lightseconds
.. doxygenfunction:: xo::qty::qty::astronomicalunits
.. doxygenfunction:: xo::qty::qty::inches
.. doxygenfunction:: xo::qty::qty::feet
.. doxygenfunction:: xo::qty::qty::yards
.. doxygenfunction:: xo::qty::qty::miles
Time
----
.. doxygenfunction:: xo::qty::qty::picoseconds
.. doxygenfunction:: xo::qty::qty::nanoseconds
.. doxygenfunction:: xo::qty::qty::microseconds
.. doxygenfunction:: xo::qty::qty::milliseconds
.. doxygenfunction:: xo::qty::qty::seconds
.. doxygenfunction:: xo::qty::qty::minutes
.. doxygenfunction:: xo::qty::qty::hours
.. doxygenfunction:: xo::qty::qty::days
.. doxygenfunction:: xo::qty::qty::weeks
.. doxygenfunction:: xo::qty::qty::months
.. doxygenfunction:: xo::qty::qty::years
.. doxygenfunction:: xo::qty::qty::year250s
.. doxygenfunction:: xo::qty::qty::year360s
.. doxygenfunction:: xo::qty::qty::year365s
Volatility
----------
.. doxygenfunction:: xo::qty::qty::volatility_30d
.. doxygenfunction:: xo::qty::qty::volatility_250d
.. doxygenfunction:: xo::qty::qty::volatility_360d
.. doxygenfunction:: xo::qty::qty::volatility_365d

31
xo-unit/docs/quantity-reference.rst Normal file
View file

@ -0,0 +1,31 @@
.. _quantity-reference:
Quantity Reference
==================
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. toctree::
:maxdepth: 2
quantity-class
quantity-factoryfunctions
quantity-unitvars
quantity-source-code

11
xo-unit/docs/quantity-source-code.rst Normal file
View file

@ -0,0 +1,11 @@
.. _quantity-source-code:
Quantity Source Code
====================
github: `quantity.hpp @github`_
.. _`quantity.hpp @github`: https://github.com/rconybea/xo-unit/blob/main/include/xo/unit/quantity.hpp
.. literalinclude:: ../include/xo/unit/quantity.hpp
:language: c++

98
xo-unit/docs/quantity-unitvars.rst Normal file
View file

@ -0,0 +1,98 @@
.. _quantity-unitvars:
Quantity Unit Variables
=======================
Built-in unit quantities
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
Introduction
------------
.. code-block:: cpp
#include <xo/unit/quantity.hpp>
The ``xo::qty::qty`` namespace contains unit quantities in each dimension.
Can use these to assemble unit quantities with compound dimensions
.. code-block:: cpp
:linenos:
:emphasize-lines: 6
#include "xo/unit/quantity.hpp"
namespace q = xo::qty::qty;
auto q1 = (q::kilometers(150.0) / q::hours(0.5));
constexpr auto u_mps = q:meter / q:second;
auto q2 = with_units_from(q1, u_mps);
Mass
----
.. doxygenvariable:: xo::qty::qty::picogram
.. doxygenvariable:: xo::qty::qty::nanogram
.. doxygenvariable:: xo::qty::qty::microgram
.. doxygenvariable:: xo::qty::qty::milligram
.. doxygenvariable:: xo::qty::qty::gram
.. doxygenvariable:: xo::qty::qty::kilogram
.. doxygenvariable:: xo::qty::qty::tonne
.. doxygenvariable:: xo::qty::qty::kilotonne
.. doxygenvariable:: xo::qty::qty::megatonne
.. doxygenvariable:: xo::qty::qty::gigatonne
Distance
--------
.. doxygenvariable:: xo::qty::qty::picometer
.. doxygenvariable:: xo::qty::qty::nanometer
.. doxygenvariable:: xo::qty::qty::micrometer
.. doxygenvariable:: xo::qty::qty::millimeter
.. doxygenvariable:: xo::qty::qty::meter
.. doxygenvariable:: xo::qty::qty::kilometer
.. doxygenvariable:: xo::qty::qty::megameter
.. doxygenvariable:: xo::qty::qty::gigameter
.. doxygenvariable:: xo::qty::qty::lightsecond
.. doxygenvariable:: xo::qty::qty::astronomicalunit
.. doxygenvariable:: xo::qty::qty::inch
.. doxygenvariable:: xo::qty::qty::foot
.. doxygenvariable:: xo::qty::qty::yard
.. doxygenvariable:: xo::qty::qty::mile
Time
----
.. doxygenvariable:: xo::qty::qty::picosecond
.. doxygenvariable:: xo::qty::qty::nanosecond
.. doxygenvariable:: xo::qty::qty::microsecond
.. doxygenvariable:: xo::qty::qty::millisecond
.. doxygenvariable:: xo::qty::qty::second
.. doxygenvariable:: xo::qty::qty::minute
.. doxygenvariable:: xo::qty::qty::hour
.. doxygenvariable:: xo::qty::qty::day
.. doxygenvariable:: xo::qty::qty::week
.. doxygenvariable:: xo::qty::qty::month
.. doxygenvariable:: xo::qty::qty::year
.. doxygenvariable:: xo::qty::qty::year250
.. doxygenvariable:: xo::qty::qty::year360
.. doxygenvariable:: xo::qty::qty::year365

165
xo-unit/docs/scaled-unit-class.rst Normal file
View file

@ -0,0 +1,165 @@
.. _scaled-unit-class:
Scaled Unit
===========
A dimensionless multiple of a :doc:`natural_unit<natural-unit-class>`
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+----------------+
| quantity | xquantity |
+----------------+----------------+
|cBLU scaled_unit |
+---------------------------------+
| natural_unit |
+---------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+----------------+
| basis_unit |
+---------------------------------+
| dimension |
+---------------------------------+
Introduction
------------
.. code-block::cpp
#include <xo/unit/scaled_unit.hpp>
Extension of :doc:`natural_unit<natural-unit-class>` to enable representing the intermediate
result of multiplication (or division) of natural units.
- represents a (dimensionless) multiple of a cartesian product of basis units.
- constexpr implementation
- limited support for fractional dimensions such as time^-1/2
.. uml::
:caption: scaled unit after (u::meter * u::foot / u::minute)
:scale: 99%
:align: center
object area_per_time<<scaled_unit>>
area_per_time : outer_scale_factor = 3048/10000
area_per_time : outer_scale_sq = 1.0
area_per_time : natural_unit = m2_per_min
object m2_per_min<<natural_unit>>
m2_per_min : n_bpu = 2
m2_per_min : bpu_v[]
object m2<<bpu>>
m2 : native_dim = dim::distance
m2 : scalefactor = 1/1
m2 : power = 2/1
object min<<bpu>>
min : native_dim = dim::time
min : scalefactor = 60/1
min : power = -1/1
area_per_time o-- m2_per_min
m2_per_min o-- m2
m2_per_min o-- min
Scaled units with non-unity outer scalefactors arise as intermediate results
of quantity arithmetic
Motivation
^^^^^^^^^^
Consider multiplying two units:
.. code-block:: cpp
using namespace xo::qty;
constexpr auto u_prod = u::meter * u::kilometer;
How should we represent the product?
We don't want to mix units. Instead we consolidate on a common unit;
to do this we accumulate a product of conversion factors from such consolidation.
For example:
.. code-block:: cpp
:emphasize-lines: 3
static_assert(u_prod.n_bpu() == 1);
static_assert(u_prod[0].bu() == detail::bu::meter);
static_assert(u_prod[0].power() == power_ratio_type(2));
static_assert(u_prod.outer_scale_factor_ == xo::ratio::ratio<int64_t>(1000));
static_assert(u_prod.outer_scale_sq_ == 1.0); // used if fractional dimension
Here we accumulate :code:`1000`, from converting kilometers to meters.
Division works similarly. In this example dimension cancel, but we still have a non-unity conversion factor.
.. code-block:: cpp
:emphasize-lines: 7
namespace u = xo::qty::u;
constexpr auto u_div = u::meter / u::kilometer;
// dimensionlesss result
static_assert(u_prod.n_bpu() == 0);
static_assert(u_prod.outer_scale_factor_ == xo::ratio::ratio<int64_t>(1,1000));
static_assert(u_prod.outer_scale_sq_ == 1.0);
When multiple dimensions needing conversion are involved, scalefactors accumulate:
.. code-block:: cpp
:emphasize-lines: 8
namespace u = xo::qty::u;
constexpr auto u2_prod = u::meter * u::hour * u::kilometer * u::minute;
static_assert(u2_prod.n_bpu() == 2);
static_assert(u2_prod[0].bu() == detail::bu::meter);
static_assert(u2_prod[1].bu() == detail::bu::hour);
static_assert(u2_prod.outer_scale_factor_ == xo::ratio::ratio<int64_t>(50,3));
static_assert(u2_prod.outer_scale_sq_ == 1.0); // used if fractional dimension
Here the :code:`50/3` result comes from multiplying :code:`1000/1` (converting kilometers -> meters)
by :code:`1/60` (converting minutes -> hours)
Class
-----
.. doxygenclass:: xo::qty::scaled_unit
Member Variables
----------------
.. doxygengroup:: scaled-unit-instance-vars
Type Traits
-----------
.. doxygengroup:: scaled-unit-type-traits
Access Methods
--------------
.. doxygengroup:: scaled-unit-access-methods
General Methods
---------------
.. doxygengroup:: scaled-unit-general-methods
Operators
---------
.. doxygengroup:: scaled-unit-operators

75
xo-unit/docs/scaled-unit-constants.rst Normal file
View file

@ -0,0 +1,75 @@
.. _scaled-unit-constants
Scaled Unit Constants
=====================
Built-in unit constants, for use with conversions
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
|cBLU scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
Introduction
------------
Built-in units. Application code may use these to trigger conversion
.. code-block:: cpp
:emphasize-lines: 5
#include <xo/unit/quantity.hpp>
using namespace xo::qty;
constexpr quantity<u::meter / u::second> q1 = q::miles(60) / q::hour;
Note that it's often easiest to use :doc:`unit quantity constants<quantity-unitvars>`,
like :code:`q::hour` in the example above
Dimensionless Constant
----------------------
.. doxygengroup:: scaled-unit-dimensionless
Mass Units
----------
.. doxygengroup:: scaled-unit-mass
Distance Units
--------------
.. doxygengroup:: scaled-unit-distance
Time Units
----------
.. doxygengroup:: scaled-unit-time
Volatility Units
----------------
.. doxygengroup:: scaled-unit-volatility
Miscellaneous Units
-------------------
.. doxygengroup:: scaled-unit-misc

31
xo-unit/docs/scaled-unit-reference.rst Normal file
View file

@ -0,0 +1,31 @@
.. _scaled-unit-reference:
Scaled Unit Reference
=====================
A dimensionless multiple of a :doc:`natural_unit<natural-unit-class>`
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
|cBLU scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. toctree::
:maxdepth: 1
Scaled Unit Class <scaled-unit-class>
scaled-unit-constants

9
xo-unit/docs/ubuntu-github-workflow.rst Normal file
View file

@ -0,0 +1,9 @@
.. ubuntu-github-workflow:
Ubuntu Github Workflow
======================
Instructions for build starting on a stock ubuntu platform (see `xo-unit/.github/workflows/ubuntu_main.yml`)
.. literalinclude:: ../.github/workflows/ubuntu-main.yml
:language: yaml

96
xo-unit/docs/xquantity-class.rst Normal file
View file

@ -0,0 +1,96 @@
.. _xquantity-class:
Xquantity
=========
Polymorphic dimensioned quantity with runtime unit checking/conversion
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity |cBLU xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. code-block:: cpp
#include <xo/unit/xquantity.hpp>
.. uml::
:scale: 99%
:align: center
allowmixing
object qty1<<xquantity>>
qty1 : scale = 1.23
qty1 : unit = unit
object unit<<scaled_unit>>
unit : is_natural() = true
qty1 o-- unit
Class
-----
Class with run-time unit representation.
.. doxygenclass:: xo::qty::xquantity
Member Variables
----------------
.. doxygengroup:: xquantity-instance-vars
Constructors
------------
.. doxygengroup:: xquantity-ctors
Access Methods
--------------
.. doxygengroup:: xquantity-access-methods
Constants
---------
.. doxygengroup:: xquantity-constants
Conversion Methods
------------------
.. doxygengroup:: xquantity-unit-conversion
Arithmetic
----------
.. doxygengroup:: xquantity-operators
Support methods for arithmetic operations
.. doxygengroup:: xquantity-arithmetic-support
Comparison
----------
Support methods for comparison operators
.. doxygengroup:: xquantity-comparison-support

29
xo-unit/docs/xquantity-reference.rst Normal file
View file

@ -0,0 +1,29 @@
.. _xquantity-reference:
Xquantity Reference
===================
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity |cBLU xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. toctree::
:maxdepth: 2
xquantity-class
xquantity-source-code

11
xo-unit/docs/xquantity-source-code.rst Normal file
View file

@ -0,0 +1,11 @@
.. _xquantity-source-code:
Xquantity Source Code
=====================
github: `xquantity.hpp @github`_
.. _`xquantity.hpp @github`: https://github.com/rconybea/xo-unit/blob/main/include/xo/unit/xquantity.hpp
.. literalinclude:: ../include/xo/unit/xquantity.hpp
:language: c++