diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 43df570c..efad16e2 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -3,7 +3,7 @@ xo_doxygen_collect_deps() xo_docdir_doxygen_config() xo_docdir_sphinx_config( - index.rst examples.rst glossary.rst install.rst + index.rst examples.rst glossary.rst install.rst abstractions.rst quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst unit-reference.rst unit-concept.rst unit-quantities.rst ) diff --git a/docs/abstractions.rst b/docs/abstractions.rst new file mode 100644 index 00000000..f23c6a25 --- /dev/null +++ b/docs/abstractions.rst @@ -0,0 +1,191 @@ +.. _abstractions: + +Representation +============== + +.. ditaa:: + + +-----------+-----------+ + | quantity | xquantity | + +-----------+-----------+ + | scaled_unit | + +-----------------------+ + | natural_unit | + +-----------------------+ + | bpu | + +-----------------------+ + | basis_unit | + +-----------------------+ + | dimension | + +-----------------------+ + +- quantity: see :doc:`quantity-reference` + +.. code-block:: cpp + :linenos: + :emphasize-lines: 6 + + #include "xo/unit/quantity.hpp" + ... + namespace q = xo::qty::qty; + + // 7.55km.min^-2 + quantity qty1 = 7.55 * q::kilometer / (q::minute * q::minute); + +.. uml:: + :caption: representation for quantity 7.55km.min^-2 + :scale: 99% + :align: center + + object qty1<> + qty1 : scale = 7.55 + + rectangle { + + object km_per_min2<> + km_per_min2 : n_bpu = 2 + km_per_min2 : bpu[0] = km + km_per_min2 : bpu[1] = per_min + + object km<> + km : native_dim = dim.mass + km : scalefactor = 1000/1 + km : power = 1 + + object per_min2<> + 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<> + qty2 : scale = 123 + + rectangle { + + object ng_unit<> + ng_unit : n_bpu = 1 + ng_unit : bpu[0] = ng + + object ng<> + 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<> + qty3 : scale = 928.65 + + rectangle { + + object ng_km_min2_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<> + ng : native_dim = dim::mass + ng : scalefactor = 1/10^9 + ng : power = 1 + + object km<> + km : native_dim = dim::distance + km : scalefactor = 1000/1 + km : power = 1 + + object per_min2<> + 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 su = xo::qty::su; + + // (123*7.55) ng.km.min^-2 ==> 2.57958e-10kg.m.s^-2 + + quantity qty3b = qty3.rescale_ext(); + +.. uml:: + :caption: quantity 928.65 ng.km.min^-2 + :scale: 99% + :align: center + + object qty3b<> + qty3b : scale = 2.59758e-10 + + rectangle { + + object kg_m_s2_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<> + kg : native_dim = dim::mass + kg : scalefactor = 1000/1 + kg : power = 1 + + object m<> + m : native_dim = dim::distance + m : scalefactor = 1/1 + m : power = 1 + + object per_s2<> + 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 diff --git a/docs/conf.py b/docs/conf.py index a590afbe..ed3a2912 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,7 +15,9 @@ author = 'Roland Conybeare' #extensions = [] extensions = [ "breathe", - "sphinx.ext.autodoc" # generate info from docstrings + "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 diff --git a/docs/index.rst b/docs/index.rst index 72d51cf5..a68e6163 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,9 +12,11 @@ dimension checking and unit conversion. Functionality is similar in spirit to that provided by ``boost::units``; however there are some important differences: -* interchangeable compile-time / run-time unit representation. +* 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. +* 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 @@ -30,6 +32,7 @@ runtime (since we can't construct new c++ types at runtime). install examples + abstractions unit-quantities quantity-reference unit-reference diff --git a/docs/quantity-class.rst b/docs/quantity-class.rst index 9e1d2c01..5e7a9329 100644 --- a/docs/quantity-class.rst +++ b/docs/quantity-class.rst @@ -8,29 +8,24 @@ Quantity #include The primary data structure for interacting with xo-unit is the -template class ``xo::unit::quantity``. +template class ``xo::qty::quantity``. -.. doxygenclass:: xo::unit::quantity +.. doxygenclass:: xo::qty::quantity Type Traits ----------- -.. doxygengroup:: quantity-traits - :content-only: +.. doxygengroup:: quantity-type-traits Constructors ------------ .. doxygengroup:: quantity-ctors - :content-only: - -.. doxygengroup:: quantity-named-ctors - :content-only: The simplest way to create a quantity instance is to use either -* factory functions in ``xo::unit::qty``, see :doc:`quantity-factoryfunctions` -* unit variables in ``xo::unit::units``, see :doc:`quantity-unitvars` +* factory functions in ``xo::qty::qty``, see :doc:`quantity-factoryfunctions` +* unit variables in ``xo::qty::qty``, see :doc:`quantity-unitvars` Assignment ---------- diff --git a/docs/quantity-factoryfunctions.rst b/docs/quantity-factoryfunctions.rst index f73d9745..daf4e8ea 100644 --- a/docs/quantity-factoryfunctions.rst +++ b/docs/quantity-factoryfunctions.rst @@ -10,18 +10,26 @@ Quantity Factory Functions #include -.. doxygenfunction:: xo::unit::qty::milligrams -.. doxygenfunction:: xo::unit::qty::grams -.. doxygenfunction:: xo::unit::qty::kilograms +Mass +---- +.. doxygenfunction:: xo::qty::qty::milligrams +.. doxygenfunction:: xo::qty::qty::grams +.. doxygenfunction:: xo::qty::qty::kilograms -.. doxygenfunction:: xo::unit::qty::millimeters -.. doxygenfunction:: xo::unit::qty::meters -.. doxygenfunction:: xo::unit::qty::kilometers +Distance +-------- +.. doxygenfunction:: xo::qty::qty::millimeters +.. doxygenfunction:: xo::qty::qty::meters +.. doxygenfunction:: xo::qty::qty::kilometers -.. doxygenfunction:: xo::unit::qty::nanoseconds -.. doxygenfunction:: xo::unit::qty::microseconds -.. doxygenfunction:: xo::unit::qty::milliseconds -.. doxygenfunction:: xo::unit::qty::seconds -.. doxygenfunction:: xo::unit::qty::minutes -.. doxygenfunction:: xo::unit::qty::hours -.. doxygenfunction:: xo::unit::qty::days +.. doxygenfunction:: xo::qty::qty::inches + +Time +---- +.. 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 diff --git a/docs/quantity-unitvars.rst b/docs/quantity-unitvars.rst index 77c09946..719197bb 100644 --- a/docs/quantity-unitvars.rst +++ b/docs/quantity-unitvars.rst @@ -10,36 +10,56 @@ Quantity Unit Variables #include -The ``xo::unit::unit_qty`` namespace contains unit quantities in each dimension. -Can use these to request unit conversion involving multiple dimensions, for example: +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 - namespace qty = xo::unit::qty; - namespace u = xo::unit::unit_qty; + #include "xo/unit/quantity.hpp" - auto q1 = (qty::kilometers(150.0) / qty::hours(0.5); - auto q2 = q1.with_units_from(u:meter / u:second); + 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::unit::unit_qty::milligram -.. doxygenvariable:: xo::unit::unit_qty::gram -.. doxygenvariable:: xo::unit::unit_qty::kilogram +.. 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 Distance -------- -.. doxygenvariable:: xo::unit::unit_qty::millimeter -.. doxygenvariable:: xo::unit::unit_qty::meter -.. doxygenvariable:: xo::unit::unit_qty::kilometer +.. 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 Time ---- -.. doxygenvariable:: xo::unit::unit_qty::nanosecond -.. doxygenvariable:: xo::unit::unit_qty::microsecond -.. doxygenvariable:: xo::unit::unit_qty::millisecond -.. doxygenvariable:: xo::unit::unit_qty::second -.. doxygenvariable:: xo::unit::unit_qty::minute -.. doxygenvariable:: xo::unit::unit_qty::hour -.. doxygenvariable:: xo::unit::unit_qty::day +.. notyet .. doxygenvariable:: xo::qty::qty::picosecond +.. notyet .. doxygenvariable:: xo::qty::qty::nanosecond +.. notyet .. doxygenvariable:: xo::qty::qty::microsecond +.. notyet .. 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 +.. notyet doxygenvariable:: xo::qty::qty::week +.. notyet doxygenvariable:: xo::qty::qty::month +.. notyet doxygenvariable:: xo::qty::qty::year +.. notyet doxygenvariable:: xo::qty::qty::year250 +.. notyet doxygenvariable:: xo::qty::qty::year360 +.. notyet doxygenvariable:: xo::qty::qty::year365