xo-unit: + missing doc .rst files

docs/natural-unit-class.rst

@@ -0,0 +1,40 @@
+.. _natural-unit-class:
+
+Natural Unit
+============
+
+.. ditaa::
+
+    +----------------+----------------+
+    |    quantity    |    xquantity   |
+    +----------------+----------------+
+    |           scaled_unit           |
+    +---------------------------------+
+    |cYEL      natural_unit           |
+    +---------------------------------+
+    |               bpu               |
+    +----------------+                |
+    |    bu_store    |                |
+    +----------------+----------------+
+    |            basis_unit           |
+    +---------------------------------+
+    |             dimension           |
+    +---------------------------------+
+
+.. code-block:: cpp
+
+    #include <xo/unit/natural_unit.hpp>
+
+Representation for the unit associated with a @ref quantity or xquantity.
+
+- represents a cartesian product of basis units.
+- constexpr implementation
+- limited support for fractional dimensions such as time^-1/2
+
+.. doxygenclass:: xo::qty::natural_unit
+
+.. doxygengroup:: natural-unit-instance-vars
+.. doxygengroup:: natural-unit-ctors
+.. doxygengroup:: natural-unit-access-methods
+.. doxygengroup:: natural-unit-methods
+.. doxygengroup:: natural-unit-conversion-methods

docs/scaled-unit-class.rst

@@ -0,0 +1,59 @@
+.. _scaled-unit-class:
+
+Scaled Unit
+===========
+
+.. ditaa::
+
+    +----------------+----------------+
+    |    quantity    |    xquantity   |
+    +----------------+----------------+
+    |cYEL       scaled_unit           |
+    +---------------------------------+
+    |          natural_unit           |
+    +---------------------------------+
+    |               bpu               |
+    +----------------+                |
+    |    bu_store    |                |
+    +----------------+----------------+
+    |            basis_unit           |
+    +---------------------------------+
+    |             dimension           |
+    +---------------------------------+
+
+
+.. code-block::cpp
+
+    #include <xo/unit/scaled_unit.hpp>
+
+Result of mutliplication or division of natural units (:doc:`natural-unit-class`).
+
+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
+
+    static_assert(u_prod.natural_unit[0].bu() == detail::bu::meter);
+    static_assert(u_prod.natural_unit[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
+
+Class
+-----
+
+.. doxygenclass:: xo::qty::scaled_unit