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

xo-unit: docs improvements. Now using sphinxcontrib-ditaa

Browse source
This commit is contained in:
Roland Conybeare 2024-05-07 10:46:43 -04:00
commit 2a63780235
7 changed files with 267 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/CMakeLists.txt
View file

@ -3,7 +3,7 @@
xo_doxygen_collect_deps() xo_doxygen_collect_deps()
xo_docdir_doxygen_config() xo_docdir_doxygen_config()
xo_docdir_sphinx_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 quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst
unit-reference.rst unit-concept.rst unit-quantities.rst unit-reference.rst unit-concept.rst unit-quantities.rst
) )

191
docs/abstractions.rst Normal file
View file

@ -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<<quantity>>
qty1 : scale = 7.55
rectangle {
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 {
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 {
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 su = xo::qty::su;
// (123*7.55) ng.km.min^-2 ==> 2.57958e-10kg.m.s^-2
quantity qty3b = qty3.rescale_ext<su::kilogram * su::meter / (su::second * su::second)>();
.. uml::
:caption: quantity 928.65 ng.km.min^-2
:scale: 99%
:align: center
object qty3b<<quantity>>
qty3b : scale = 2.59758e-10
rectangle {
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

4
docs/conf.py
View file

@ -15,7 +15,9 @@ author = 'Roland Conybeare'
#extensions = [] #extensions = []
extensions = [ "breathe", 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 # note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in

7
docs/index.rst
View file

@ -12,9 +12,11 @@ dimension checking and unit conversion.
Functionality is similar in spirit to that provided by ``boost::units``; Functionality is similar in spirit to that provided by ``boost::units``;
however there are some important differences: 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. * 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) * integration with python (see sister project xo-pyunit)
Second, ``xo-unit`` supports fractional dimensions. This allows using it to naturally handle 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 install
examples examples
abstractions
unit-quantities unit-quantities
quantity-reference quantity-reference
unit-reference unit-reference

15
docs/quantity-class.rst
View file

@ -8,29 +8,24 @@ Quantity
#include <xo/unit/quantity.hpp> #include <xo/unit/quantity.hpp>
The primary data structure for interacting with xo-unit is the 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 Type Traits
----------- -----------
.. doxygengroup:: quantity-traits .. doxygengroup:: quantity-type-traits
:content-only:
Constructors Constructors
------------ ------------
.. doxygengroup:: quantity-ctors .. doxygengroup:: quantity-ctors
:content-only:
.. doxygengroup:: quantity-named-ctors
:content-only:
The simplest way to create a quantity instance is to use either The simplest way to create a quantity instance is to use either
* factory functions in ``xo::unit::qty``, see :doc:`quantity-factoryfunctions` * factory functions in ``xo::qty::qty``, see :doc:`quantity-factoryfunctions`
* unit variables in ``xo::unit::units``, see :doc:`quantity-unitvars` * unit variables in ``xo::qty::qty``, see :doc:`quantity-unitvars`
Assignment Assignment
---------- ----------

34
docs/quantity-factoryfunctions.rst
View file

@ -10,18 +10,26 @@ Quantity Factory Functions
#include <xo/unit/quantity.hpp> #include <xo/unit/quantity.hpp>
.. doxygenfunction:: xo::unit::qty::milligrams Mass
.. doxygenfunction:: xo::unit::qty::grams ----
.. doxygenfunction:: xo::unit::qty::kilograms .. doxygenfunction:: xo::qty::qty::milligrams
.. doxygenfunction:: xo::qty::qty::grams
.. doxygenfunction:: xo::qty::qty::kilograms
.. doxygenfunction:: xo::unit::qty::millimeters Distance
.. doxygenfunction:: xo::unit::qty::meters --------
.. doxygenfunction:: xo::unit::qty::kilometers .. doxygenfunction:: xo::qty::qty::millimeters
.. doxygenfunction:: xo::qty::qty::meters
.. doxygenfunction:: xo::qty::qty::kilometers
.. doxygenfunction:: xo::unit::qty::nanoseconds .. doxygenfunction:: xo::qty::qty::inches
.. doxygenfunction:: xo::unit::qty::microseconds
.. doxygenfunction:: xo::unit::qty::milliseconds Time
.. doxygenfunction:: xo::unit::qty::seconds ----
.. doxygenfunction:: xo::unit::qty::minutes .. doxygenfunction:: xo::qty::qty::nanoseconds
.. doxygenfunction:: xo::unit::qty::hours .. doxygenfunction:: xo::qty::qty::microseconds
.. doxygenfunction:: xo::unit::qty::days .. 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

58
docs/quantity-unitvars.rst
View file

@ -10,36 +10,56 @@ Quantity Unit Variables
#include <xo/unit/quantity.hpp> #include <xo/unit/quantity.hpp>
The ``xo::unit::unit_qty`` namespace contains unit quantities in each dimension. The ``xo::qty::qty`` namespace contains unit quantities in each dimension.
Can use these to request unit conversion involving multiple dimensions, for example: Can use these to assemble unit quantities with compound dimensions
.. code-block:: cpp .. code-block:: cpp
:linenos:
:emphasize-lines: 6
namespace qty = xo::unit::qty; #include "xo/unit/quantity.hpp"
namespace u = xo::unit::unit_qty;
auto q1 = (qty::kilometers(150.0) / qty::hours(0.5); namespace q = xo::qty::qty;
auto q2 = q1.with_units_from(u:meter / u:second);
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 Mass
---- ----
.. doxygenvariable:: xo::unit::unit_qty::milligram .. doxygenvariable:: xo::qty::qty::milligram
.. doxygenvariable:: xo::unit::unit_qty::gram .. doxygenvariable:: xo::qty::qty::gram
.. doxygenvariable:: xo::unit::unit_qty::kilogram .. doxygenvariable:: xo::qty::qty::kilogram
.. doxygenvariable:: xo::qty::qty::tonne
.. doxygenvariable:: xo::qty::qty::kilotonne
Distance Distance
-------- --------
.. doxygenvariable:: xo::unit::unit_qty::millimeter .. doxygenvariable:: xo::qty::qty::picometer
.. doxygenvariable:: xo::unit::unit_qty::meter .. doxygenvariable:: xo::qty::qty::nanometer
.. doxygenvariable:: xo::unit::unit_qty::kilometer .. 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 Time
---- ----
.. doxygenvariable:: xo::unit::unit_qty::nanosecond .. notyet .. doxygenvariable:: xo::qty::qty::picosecond
.. doxygenvariable:: xo::unit::unit_qty::microsecond .. notyet .. doxygenvariable:: xo::qty::qty::nanosecond
.. doxygenvariable:: xo::unit::unit_qty::millisecond .. notyet .. doxygenvariable:: xo::qty::qty::microsecond
.. doxygenvariable:: xo::unit::unit_qty::second .. notyet .. doxygenvariable:: xo::qty::qty::millisecond
.. doxygenvariable:: xo::unit::unit_qty::minute .. doxygenvariable:: xo::qty::qty::second
.. doxygenvariable:: xo::unit::unit_qty::hour .. doxygenvariable:: xo::qty::qty::minute
.. doxygenvariable:: xo::unit::unit_qty::day .. 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