Add 'xo-unit/' from commit 'b531e382c2'
git-subtree-dir: xo-unit git-subtree-mainline:e9ee6992cagit-subtree-split:b531e382c2
This commit is contained in:
commit
d1fa15f248
105 changed files with 11790 additions and 0 deletions
314
xo-unit/docs/implementation.rst
Normal file
314
xo-unit/docs/implementation.rst
Normal 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue