From a9c7b696fb4a411f8b3d1428b5f7050165b48178 Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Sat, 4 May 2024 11:38:28 -0400 Subject: [PATCH] xo-unit: ++ docs --- docs/examples.rst | 93 ++++++++++++++++++++++------------------------- docs/glossary.rst | 6 +-- 2 files changed, 46 insertions(+), 53 deletions(-) diff --git a/docs/examples.rst b/docs/examples.rst index b486a494..0360f0af 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -47,21 +47,12 @@ with output: t: 2min, d: 2.5km, t^2: 4min^2, d.t^-2: 0.625km.min^-2 -Remarks: - -- ``xo::qty::quantity`` performs unit consistency checking and propagation at compile time. Runtime space/time overhead is zero. -- Unit abbreviations (such as ``kg.min^-2`` above) are computed at compile time. See ``xo::flatstring`` for constexpr string implementation. -- 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/`` -- See ``xo::xquantity`` for parallel implementation that defers unit checking until runtime. - We can use static asserts to prove that units are being computed at compile-time .. code-block:: cpp :linenos: - static_assert(std::same_as); + static_assert(std::same_as); static_assert(sizeof(t) == sizeof(double)); static_assert(t.scale() == 2); static_assert(t.abbrev() == flatstring("min")); @@ -71,7 +62,7 @@ We can use static asserts to prove that units are being computed at compile-time static_assert(d.scale() == 2.5); static_assert(d.abbrev() == flatstring("km")); - static_assert(std::same_as); + static_assert(std::same_as); static_assert(sizeof(t2) == sizeof(double)); static_assert(t2.scale() == 4); static_assert(t2.abbrev() == flatstring("min^2")); @@ -81,17 +72,34 @@ We can use static asserts to prove that units are being computed at compile-time static_assert(a.scale() == 0.625); static_assert(a.abbrev() == flatstring("km.min^-2")); +Remarks: -Explicit scale conversion using rescale method ----------------------------------------------- +- ``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. -Can convert between compatible units explictly: + +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: 9 + :emphasize-lines: 10,13,16-17 ... @@ -101,45 +109,32 @@ See ``xo-unit/examples/ex2`` for code below. constexpr auto t2 = t*t; constexpr auto a = d / (t*t); - constexpr auto a2 = a.template rescale(); + // 1. + constexpr auto a2 = with_units(a); + + // 2. + constexpr auto a3 = a.rescale_ext(); + + // 3. + constexpr auto au = q::meter / (q::second * q::second); + constexpr auto a4 = with_units_from(a, au); // 3. static_assert(a2.abbrev() == flatstring("m.s^-2")); cerr << "a2: " << a2 << endl; + cerr << "a3: " << a3 << endl; + cerr << "a4: " << a4 << endl; with output: .. code-block:: cpp a2: 0.173611m.s^-2 - -Explicit scale conversion from another quantity ------------------------------------------------ - -Alternatively, can transfer units from another quantity - -See ``xo-unit/example/ex2`` for code below - -.. code-block:: cpp - :linenos: - :emphasize-lines: 1-2 - - constexpr auto au = q::meter / (q::second * q::second); /* just for units */ - constexpr auto a3 = with_units_from(a, au); /* a, but with units from au */ - - static_assert(a3.abbrev() == flatstring("m.s^-2")); - - cerr << "a3: " << a3 << endl; - -with output: - -.. code-block:: cpp - a3: 0.173611m.s^-2 + a4: 0.173611m.s^-2 - -Implicit Scale conversion triggered by assignment -------------------------------------------------- +Implicit Scale conversion +------------------------- Another way to convert units is to assign to a variable with desired units -- this works because the units are encoded @@ -156,20 +151,18 @@ See ``xo-unit/example/ex3`` for code below namespace q = xo::qty::qty; namespace nu = xo::qty::nu; using xo::qty::with_units; - using xo::qty::stdquantity; using xo::qty::quantity; using xo::flatstring; - using namespace std; - constexpr stdquantity t = q::minutes(2); - constexpr stdquantity d = q::kilometers(2.5); + constexpr quantity t = q::minutes(2); + constexpr quantity d = q::kilometers(2.5); constexpr auto t2 = t*t; constexpr auto a = d / (t*t); - cerr << "t: " << t << ", d: " << d - << ", d.t^-2: " << a - << endl; + std::cerr << "t: " << t << ", d: " << d + << ", d.t^-2: " << a + << std::endl; } with output: @@ -181,7 +174,7 @@ with output: Remarks: * Assignment to ``t`` converted to representation ``double``. - We could have used :code:`stdquantity` to preserve + We could have used :code:`quantity` to preserve right-hand-side representation. Scale conversion triggered by arithmetic diff --git a/docs/glossary.rst b/docs/glossary.rst index b7a4f864..e12cc190 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -8,7 +8,7 @@ Glossary Orthogonal directions associated with basis units, for example *mass*, *length*, *time*. In xo-unit these are represented by the enum ``xo::qty::dim``. - basis unit + basis unit (bu) An implementation type representing a quantity (with associated scale) in the direction of a single :term:`basis dimension`. For example *milliseconds*, *seconds*, and *hours* stand for different basis units with the *time* dimension. In xo-unit these are represented by the template type ``xo::qty::basis_unit``. @@ -17,11 +17,11 @@ Glossary A rational power of a (single) basis unit. For example *s\ :sup:-2* or *hr\ :sup:-(1/2)*. In xo-unit these are represented by the template type ``xo::qty::bpu``. - nu + natural unit (nu) A cartesian product of basis power units (bpus). For example *kg.m.s\ :sup:-2* or *hr\ :sup:-(1/2)*. In xo-unit these are represented by template type ``xo::qty::natural_unit``. - su + 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 ``xo::qty::scaled_unit``.