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

xo-unit ++ docs ++ quantity arithmetic + example

Browse source
This commit is contained in:
Roland Conybeare 2024-05-23 14:44:00 -04:00
commit b0ce5eaee9
34 changed files with 713 additions and 173 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/CMakeLists.txt
View file

@ -3,8 +3,8 @@
xo_doxygen_collect_deps()
xo_docdir_doxygen_config()
xo_docdir_sphinx_config(
index.rst examples.rst glossary.rst install.rst implementation.rst development.rst
quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst
index.rst examples.rst glossary.rst install.rst implementation.rst
quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst quantity-source-code.rst
xquantity-reference.rst xquantity-class.rst
scaled-unit-reference.rst scaled-unit-class.rst scaled-unit-constants.rst
natural-unit-class.rst
@ -12,5 +12,7 @@ xo_docdir_sphinx_config(
bu-store-class.rst basis-unit-reference.rst
basis-unit-class.rst basis-unit-constants.rst
dimension-enum.rst
development.rst
ubuntu-github-workflow.rst
)
#xo_utest_coverage_config2()

2
docs/basis-unit-class.rst
View file

@ -22,7 +22,7 @@ Context
+----------------+ |
| bu_store | |
+----------------+---------------+
|cYEL basis_unit |
|cBLU basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+

2
docs/basis-unit-constants.rst
View file

@ -22,7 +22,7 @@ Context
+----------------+ |
| bu_store | |
+----------------+---------------+
|cYEL basis_unit |
|cBLU basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+

2
docs/basis-unit-reference.rst
View file

@ -19,7 +19,7 @@ Built-in named units for each native dimension
+----------------+ |
| bu_store | |
+----------------+---------------+
|cYEL basis_unit |
|cBLU basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+

2
docs/bpu-class.rst
View file

@ -18,7 +18,7 @@ Context
+--------------------------------+
| natural_unit |
+--------------------------------+
|cYEL bpu |
|cBLU bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+

2
docs/bu-store-class.rst
View file

@ -15,7 +15,7 @@ Basis Unit Store
+--------------------------------+
| bpu |
+----------------+ |
|cYEL bu_store | |
|cBLU bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+

1
docs/conf.py
View file

@ -15,6 +15,7 @@ author = 'Roland Conybeare'
#extensions = []
extensions = [ "breathe",
"sphinx.ext.mathjax", # inline math
"sphinx.ext.autodoc", # generate info from docstrings
"sphinxcontrib.ditaa", # diagrams-through-ascii-art
"sphinxcontrib.plantuml" # text -> uml diagrams

2
docs/dimension-enum.rst
View file

@ -24,7 +24,7 @@ Context
+----------------+---------------+
| basis_unit |
+--------------------------------+
|cYEL dimension |
|cBLU dimension |
+--------------------------------+
Introduction

39
docs/glossary.rst
View file

@ -4,26 +4,35 @@ Glossary
--------
.. glossary::
basis dimension
Orthogonal directions associated with basis units, for example *mass*, *length*, *time*.
In xo-unit these are represented by the enum ``xo::qty::dim``.
dimension
dim
| Fundamental, orthogonal directions associated available for constructing units.
| For example *mass*, *length*, *time*.
| In *xo-unit* these are represented by the enum :doc:`xo::qty::dimension<dimension-enum>`.
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``.
basis unit
bu
| An implementation type representing a quantity (with associated scale) in the direction of a single :term:`dimension`.
| For example *milliseconds*, *seconds*, and *hours* stand for different basis units within the *time* dimension.
| In *xo-unit* these are represented by the template type :doc:`xo::qty::basis_unit<basis-unit-class>`.
basis power unit
bpu
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``.
| A rational power of a (single) basis unit.
| For example :math:`s^{-2}` for unit "per second squared" or :math:`yr^{-(1/2)}` for "per square-root of a year".
| In *xo-unit* these are represented by the template type :doc:`xo::qty::bpu<bpu-class>`
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``.
natural unit
nu
| A cartesian product of basis power units (bpus);
| For example :math:`kg.m.s^{-2}` or :math:`hr^{-(1/2)}`.
| In *xo-unit* these are represented by template type :doc:`xo::qty::natural_unit<natural-unit-class>`.
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``.
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 :doc:`xo::qty::scaled_unit<scaled-unit-class>`.
XO
A set of integrated c++ libraries for complex event processing, with browser and python integration.

37
docs/implementation.rst
View file

@ -3,7 +3,7 @@
Components
==========
Library dependencies for *xo-unit*:
Library dependency tower for *xo-unit*:
.. ditaa::
@ -14,28 +14,31 @@ Library dependencies for *xo-unit*:
+-----------------+
| xo_flatstring |
+-----------------+
| xo_cmake |
+-----------------+
``xo-unit`` also depends on ``xo-cmake`` macros.
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 |
+-----------------------+
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
- :doc:`quantity<quantity-reference>`:

13
docs/index.rst
View file

@ -28,7 +28,7 @@ runtime (since we can't construct new c++ types at runtime).
.. toctree::
:maxdepth: 2
:caption: xo-unit contents:
:caption: xo-unit contents
install
examples
@ -42,10 +42,7 @@ runtime (since we can't construct new c++ types at runtime).
basis-unit-reference
dimension-enum
development
Indices and Tables
------------------
* :ref:`glossary`
* :ref:`genindex`
* :ref:`search`
ubuntu-github-workflow
glossary
genindex
search

47
docs/install.rst
View file

@ -7,26 +7,35 @@ Install
=======
``xo-unit`` uses supporting header-only libraries ``xo-ratio`` and ``xo-flatstring``.
All three are on github:
and (optionally) cmake macros ``xo-cmake``. These are on github:
- `xo-unit source`_
- `xo-ratio source`_
- `xo-flatstring source`_
- `xo-unit source`_ (constexpr quantities, units and dimension-checking)
- `xo-ratio source`_ (constexpr exact ratios)
- `xo-flatstring source`_ (constexpr strings)
- `xo-cmake source`_ (shared cmake macros)
.. _xo-unit source: https://github.com/rconybea/xo-unit
.. _xo-ratio source: https://github.com/rconybea/xo-ratio
.. _xo-flatstring source: https://github.com/rconybea/xo-flatstring
.. _xo-cmake source: https://github.com/rconybea/xo-cmake
`xo-cmake` is nccessary to invoke `xo` cmake build for:
- site install
- example programs
- unit tests
Can omit to instead copy `xo_unit`, `xo-ratio` and `xo-flatstring` source trees;
see instructions below for including as git submodule
Implementation relies on some c++20 features (for example class-instances as template arguments).
Tested with gcc 12.3, 13.2
``xo-unit`` also relies on sister header-only libraries:
One way to use ``xo-unit`` in a project is to import the source tree directly:
Include as submodule
--------------------
One way to use ``xo-unit`` in a project is to import the source tree directly:
.. code-block:: bash
cd myproject
@ -50,21 +59,18 @@ to c++ source files that rely on xo-unit
Ubuntu Install Pattern
----------------------
Example instructions (from github actions CI) for build starting from stock ubuntu are in `ubuntu-main.yml`_
.. _ubuntu-main.yml: https://github.com/Rconybea/xo-unit/blob/main/.github/workflows/ubuntu-main.yml
:doc:`Example instructions<ubuntu-github-workflow>` (used for github actions CI) for build starting from stock ubuntu
Installing from source
----------------------
Although the xo-unit, xo-ratio and xo-flatstring libraries are header-only,
they do have a build dependency on shared cmake macros, and a bootstrap script `xo-cmake-config`.
Install scripts for `xo-unit`, `xo-ratio` and `xo-flatstring` depend on shared cmake macros
and a bootstrap script `xo-cmake-config`.
* `xo-cmake`_ source
.. _xo-cmake: https://github.com/rconybea/xo-cmake
Preamble:
.. code-block:: bash
@ -183,7 +189,7 @@ Preamble:
git clone https://github.com/rconybea/xo-unit
PREFIX=~/local # ..or other desired installation prefix
Build and Install `catch2` (assuming ubuntu here):
.. code-block:: bash
@ -216,7 +222,7 @@ Build and Install `xo-randomgen` (no unit tests yet):
cmake --build xo-randomgen/.build -j
cmake --install xo-randomgen/.build
Build, Test and Install `xo-flatstring`:
Build, Test and Install `xo-flatstring`:
.. code-block:: bash
@ -255,7 +261,7 @@ To enable building example programs:
cd ~/proj/xo
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DXO_ENABLE_EXAMPLES=1 -B xo-unit/.build -S xo-unit
Run examples from the build directory:
.. code-block:: bash
@ -288,17 +294,16 @@ Preamble (assuming ubuntu here):
sudo apt-get install python3-sphinx-rtd-theme
sudo apt-get install python3-breathe
Build `xo-unit` docs
Build `xo-unit` docs
.. code-block:: bash
cd ~/proj/xo
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-unit/.build
cmake --build xo-unit/.build -- docs
cmake --build xo-unit/.build -- docs
cmake --install xo-unit/.build # if docs built, installs to $PREFIX/share/doc/xo_unit/html
Supported compilers
-------------------
* developed with gcc 12.3.0 and gcc 13.2.0; github CI using gcc 11.4.0 (asof March 2024)

2
docs/natural-unit-class.rst
View file

@ -16,7 +16,7 @@ Context
+----------------+---------------+
| scaled_unit |
+--------------------------------+
|cYEL natural_unit |
|cBLU natural_unit |
+--------------------------------+
| bpu |
+----------------+ |

51
docs/quantity-class.rst
View file

@ -3,10 +3,16 @@
Quantity
========
Dimensioned quantity with compile-time unit checking/conversion
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cYEL quantity | xquantity |
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
@ -36,15 +42,37 @@ Quantity
rectangle constexpr #e0f0ff {
object unit<<natural_unit>>
object unit<<scaled_unit>>
unit : is_natural() = true
qty1 o-- unit : s_unit (static constexpr)
qty1 o-- unit : s_scaled_unit (static constexpr)
}
Arithmetic on :doc:`xo::qty::quantity<quantity-reference>` instances
does *not* use ``xo::qty::quantity::s_scaled_unit`` at runtime;
instead gets everything it needs at compile time.
- Arithmetic on :doc:`xo::qty::quantity<quantity-reference>` instances
does *not* use ``xo::qty::quantity::s_scaled_unit`` at runtime;
instead gets everything it needs at compile time.
- The :code:`xo::qty::quantity` template takes a :doc:`xo::qty::scaled_unit<scaled-unit-class>` instance,
but only accepts values with :code:`xo::qty::scaled_unit::is_natural() == true`.
This accomodation (instead of requiring a :doc:`xo::qty::natural_unit<natural-unit-class>` instance
is to make possible code like this possible:
.. code-block:: cpp
#include "xo/unit/quantity.hpp"
using namespace xo::qty;
quantity<u::meter / u::second> x;
quantity<u::meter * u::mter> y;
while rejecting attempt to mix multiple scales in the same quantity value:
.. code-block:: cpp
quantity<u::meter * u::millimeter> x; // will not compile
Class
-----
@ -81,19 +109,16 @@ Assignment
----------
.. doxygengroup:: quantity-assignment
:content-only:
Access Methods
--------------
.. doxygengroup:: quantity-access-methods
:content-only:
Constants
---------
.. doxygengroup:: quantity-constants
:content-only:
Conversion Methods
------------------
@ -101,13 +126,11 @@ Conversion Methods
Amount-preserving conversion to quantities with different units and/or representation.
.. doxygengroup:: quantity-unit-conversion
:content-only:
Arithmetic
----------
Arithmetic Operators
--------------------
.. doxygengroup:: quantity-arithmetic
:content-only:
.. doxygengroup:: quantity-operators
Support methods for arithmetic operations

15
docs/quantity-factoryfunctions.rst
View file

@ -1,9 +1,18 @@
.. _quantity_factoryfunctions:
Quantity Factory Functions
==========================
Convenience functions for creating quantities with compile-time units
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cYEL quantity | xquantity |
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
@ -21,8 +30,8 @@
.. toctree::
:maxdepth: 2
Quantity Factory Functions
==========================
Introduction
------------
.. code-block:: cpp

4
docs/quantity-reference.rst
View file

@ -4,9 +4,10 @@ Quantity Reference
==================
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cYEL quantity | xquantity |
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
@ -27,3 +28,4 @@ Quantity Reference
quantity-class
quantity-factoryfunctions
quantity-unitvars
quantity-source-code

11
docs/quantity-source-code.rst Normal file
View file

@ -0,0 +1,11 @@
.. _quantity-source-code:
Quantity Source Code
====================
github: `quantity.hpp @github.com`_
.. _`quantity.hpp @github.com`: https://github.com/rconybea/xo-unit/blob/main/include/xo/unit/quantity.hpp
.. literalinclude:: ../include/xo/unit/quantity.hpp
:language: c++

59
docs/quantity-unitvars.rst
View file

@ -1,11 +1,35 @@
.. _quantity-unitvars:
.. toctree::
:maxdepth: 2
Quantity Unit Variables
=======================
Built-in unit quantities
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
|cBLU quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
Introduction
------------
.. code-block:: cpp
#include <xo/unit/quantity.hpp>
@ -28,11 +52,16 @@ Can use these to assemble unit quantities with compound dimensions
Mass
----
.. doxygenvariable:: xo::qty::qty::picogram
.. doxygenvariable:: xo::qty::qty::nanogram
.. doxygenvariable:: xo::qty::qty::microgram
.. 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
.. doxygenvariable:: xo::qty::qty::megatonne
.. doxygenvariable:: xo::qty::qty::gigatonne
Distance
--------
@ -46,20 +75,24 @@ Distance
.. doxygenvariable:: xo::qty::qty::gigameter
.. doxygenvariable:: xo::qty::qty::lightsecond
.. doxygenvariable:: xo::qty::qty::astronomicalunit
.. doxygenvariable:: xo::qty::qty::inch
.. doxygenvariable:: xo::qty::qty::foot
.. doxygenvariable:: xo::qty::qty::yard
.. doxygenvariable:: xo::qty::qty::mile
Time
----
.. 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::picosecond
.. doxygenvariable:: xo::qty::qty::nanosecond
.. doxygenvariable:: xo::qty::qty::microsecond
.. 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
.. doxygenvariable:: xo::qty::qty::week
.. doxygenvariable:: xo::qty::qty::month
.. doxygenvariable:: xo::qty::qty::year
.. doxygenvariable:: xo::qty::qty::year250
.. doxygenvariable:: xo::qty::qty::year360
.. doxygenvariable:: xo::qty::qty::year365

2
docs/scaled-unit-class.rst
View file

@ -14,7 +14,7 @@ Context
+----------------+----------------+
| quantity | xquantity |
+----------------+----------------+
|cYEL scaled_unit |
|cBLU scaled_unit |
+---------------------------------+
| natural_unit |
+---------------------------------+

4
docs/scaled-unit-constants.rst
View file

@ -3,7 +3,7 @@
Scaled Unit Constants
=====================
Built-in unit constants.
Built-in unit constants, for use with conversions
Context
-------
@ -14,7 +14,7 @@ Context
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
|cYEL scaled_unit |
|cBLU scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+

2
docs/scaled-unit-reference.rst
View file

@ -11,7 +11,7 @@ A dimensionless multiple of a :doc:`natural_unit<natural-unit-class>`
+----------------+---------------+
| quantity | xquantity |
+----------------+---------------+
|cYEL scaled_unit |
|cBLU scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+

9
docs/ubuntu-github-workflow.rst Normal file
View file

@ -0,0 +1,9 @@
.. ubuntu-github-workflow:
Ubuntu Github Workflow
======================
Instructions for build starting on a stock ubuntu platform (see `xo-unit/.github/workflows/ubuntu_main.yml`)
.. literalinclude:: ../.github/workflows/ubuntu-main.yml
:language: yaml

60
docs/xquantity-class.rst
View file

@ -3,13 +3,73 @@
Xquantity
=========
Polymorphic dimensioned quantity with runtime unit checking/conversion
Context
-------
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity |cBLU xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. code-block:: cpp
#include <xo/unit/xquantity.hpp>
.. uml::
:scale: 99%
:align: center
allowmixing
object qty1<<xquantity>>
qty1 : scale = 1.23
qty1 : unit = unit
object unit<<scaled_unit>>
unit : is_natural() = true
qty1 o-- unit
Class
-----
Class with run-time unit representation.
.. doxygenclass:: xo::qty::xquantity
Member Variables
----------------
.. doxygengroup:: xquantity-instance-vars
Constructors
------------
.. doxygengroup:: xquantity-ctors
Access Methods
--------------
.. doxygengroup:: xquantity-access-methods
General Methods
---------------
.. doxygengroup:: xquantity-methods

3
docs/xquantity-reference.rst
View file

@ -4,9 +4,10 @@ Xquantity Reference
===================
.. ditaa::
:--scale: 0.85
+----------------+---------------+
| quantity |cYEL xquantity |
| quantity |cBLU xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+