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

xo-unit: ++ documentation for bu_store

Browse source
This commit is contained in:
Roland Conybeare 2024-05-19 17:53:03 -04:00
commit 454b1466a3
13 changed files with 223 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/CMakeLists.txt
View file

@ -5,7 +5,9 @@ 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
unit-reference.rst unit-concept.rst unit-quantities.rst bpu-class.rst bu-store-class.rst basis-unit-reference.rst
unit-reference.rst unit-concept.rst unit-quantities.rst
scaled-unit-class.rst natural-unit-class.rst
bpu-class.rst bu-store-class.rst basis-unit-reference.rst
basis-unit-class.rst basis-unit-constants.rst
dimension-enum.rst
)

39
docs/README
View file

@ -1,3 +1,41 @@
build
+-----------------------------------------------+
| cmake |
| CMakeLists.txt |
| $PREFIX/share/cmake/xo_macros/xo_cxx.cmake |
+-----------------------------------------------+
|
| +----------------------+
+------------------------------------------------->| .build/docs/Doxyfile |
| +----------------------+
| |
| /------------/
| |
| v
| +---------------------------------------+ +-----------------+
+---->| doxygen |--->| .build/docs/dox |
| | $PREFIX/share/xo-macros/Doxyfile.in | | +- html/ |
| +---------------------------------------+ | +- xml/ |
| +-----------------+
| |
| /------------/
| |
| v
| +---------------------------------------+ +--------------------+
\---->| sphinx |--->| .build/docs/sphinx |
| +- conf.py | | +- html/ |
| +- _static/ | +--------------------+
| +- *.rst |
+---------------------------------------+
files
README this file
CMakeLists.txt build entry point
conf.py sphinx config
_static static files for sphinx
map
index.rst
@ -6,6 +44,7 @@ map
+- unit-quantities.rst
+- classes.rst
+- glossary.rst
...
examples

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

@ -7,6 +7,9 @@ Basis Unit
#include <xo/unit/basis_unit.hpp>
Class
-----
A :code:`basis_unit` represents a unit belonging to a single native dimension.
For example :code:`bu::meter` representing a distance of 1 meter.

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

@ -3,9 +3,26 @@
Basis Unit Reference
====================
.. ditaa::
+-----------+-----------+
| quantity | xquantity |
+-----------+-----------+
| scaled_unit |
+-----------------------+
| natural_unit |
+-----------------------+
| bpu |
+-----------+ |
| bu_store | |
+-----------+-----------+
|cYEL basis_unit |
+-----------------------+
| dimension |
+-----------------------+
.. toctree::
:maxdepth: 2
:caption: Basis-Unit Reference
basis-unit-class
basis-unit-constants

18
docs/bpu-class.rst
View file

@ -3,6 +3,24 @@
BPU
===
.. ditaa::
+-----------+-----------+
| quantity | xquantity |
+-----------+-----------+
| scaled_unit |
+-----------------------+
| natural_unit |
+-----------------------+
|cYEL bpu |
+-------------+ |
| bu_store | |
+-------------+---------+
| basis_unit |
+-----------------------+
| dimension |
+-----------------------+
.. code-block:: cpp
#include <xo/unit/bpu.hpp>

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

@ -3,6 +3,24 @@
Basis Unit Store
================
.. ditaa::
+-----------+-----------+
| quantity | xquantity |
+-----------+-----------+
| scaled_unit |
+-----------------------+
| natural_unit |
+-----------------------+
| bpu |
+-------------+ |
|cYEL bu_store| |
+-------------+---------+
| basis_unit |
+-----------------------+
| dimension |
+-----------------------+
.. code-block:: cpp
#include <xo/unit/bu_store.hpp>
@ -21,19 +39,19 @@ recording all built-in units along with their associated abbreviations
:scale: 99%
:align: center
map mass_table {
map mass_table<<bu_dim_store>> {
bu::milligram => "mg"
bu::gram => "g"
bu::kilogram => "kg"
}
map distance_table {
map distance_table<<bu_dim_store>> {
bu::millimeter => "mm"
bu::meter => "m"
bu::kilometer => "km"
}
map time_table {
map time_table<<bu_dim_store>> {
bu::millisecond => "ms"
bu::second => "s"
bu::minute => "min"
@ -50,10 +68,13 @@ recording all built-in units along with their associated abbreviations
bu_abbrev_store o-- time_table
This class supports the implementation of ``natural_unit::abbrev()``.
This class exists to support the implementation of ``natural_unit::abbrev()``.
Application code is not expected to interact directly with it.
Class
-----
.. doxygenclass:: xo::qty::detail::bu_store
For example, this would be possible:
@ -71,6 +92,9 @@ For example, this would be possible:
static_assert(store.bu_abbrev(bu::minute) == flatstring("min"));
static_assert(store.bu_abbrev(bu::microgram) == flatstring("ug"));
.. doxygengroup:: bu-store-constructors
.. doxygengroup:: bu-store-access-methods
.. doxygengroup:: bu-store-implementation-methods
.. doxygenclass:: xo::qty::detail::bu_dim_store
.. doxygengroup:: bu-dim-store-type-traits

18
docs/dimension-enum.rst
View file

@ -3,6 +3,24 @@
Dimension
=========
.. ditaa::
+-----------+-----------+
| quantity | xquantity |
+-----------+-----------+
| scaled_unit |
+-----------------------+
| natural_unit |
+-----------------------+
| bpu |
+-----------+ |
| bu_store | |
+-----------+-----------+
| basis_unit |
+-----------------------+
|cYEL dimension |
+-----------------------+
.. code-block:: cpp
#include <xo/unit/dimension.hpp>

26
docs/implementation.rst
View file

@ -23,14 +23,17 @@ Abstraction tower for *xo-unit* components.
| dimension |
+-----------------------+
- quantity: see :doc:`quantity-reference`.
quantity with compile-time unit work
- :doc:`quantity<quantity-reference>`:
A quantity with compile-time unit work
- xquantity:
quantity with unit work deferred until runtime
- scaled_unit:
a unit involving zero or more dimensions, and associated conversion factor.
A quantity with unit work deferred until runtime
- :doc:`scaled_unit<scaled-unit-class>`:
A unit involving zero or more dimensions, and associated conversion factor.
- can express result of arithmetic involving multiple scales,
by reporting an outer scalefactor
@ -40,29 +43,30 @@ Abstraction tower for *xo-unit* components.
- multiplication and division commit to a single :code:`basis_unit` for each
dimension.
- natural_unit:
a unit involving zero or more dimensions, and at most one scale per dimension.
- :doc:`natural_unit<natural-unit-class>`
A unit involving zero or more dimensions, and at most one scale per dimension.
A quantity instance is always represented as a dimensionless multiple
of a natural unit
- natural_units are *not* closed under multiplication and division.
(for example consider :code:`xo::qty::qty::foot * xo::qty::qty::meter`)
- bpu: :doc:`bpu-class`.
- :doc:`bpu<bpu-class>`
A rational (usually integer) power of a basis unit. Has a single dimension.
- bu_store: :doc:`bu-store-class`.
- :doc:`bu_store<bu-store-class>`
Associates basis units with abbreviations.
For example ``bu::kilogram`` => ``"kg"``
- basis_unit: :doc:`basis-unit-reference`.
- :doc:`basis_unit<basis-unit-reference>`
A unit with a single dimension and scale.
- dimension: :doc:`dimension-enum`.
- :doc:`dimension<dimension-enum>`
identifies a dimension, such as mass or time.

3
docs/index.rst
View file

@ -36,7 +36,8 @@ runtime (since we can't construct new c++ types at runtime).
development
unit-quantities
quantity-reference
unit-reference
scaled-unit-class
natural-unit-class
bpu-class
bu-store-class
basis-unit-reference

19
docs/quantity-reference.rst
View file

@ -3,9 +3,26 @@
Quantity Reference
==================
.. ditaa::
+----------------+---------------+
|cYEL quantity | xquantity |
+----------------+---------------+
| scaled_unit |
+--------------------------------+
| natural_unit |
+--------------------------------+
| bpu |
+----------------+ |
| bu_store | |
+----------------+---------------+
| basis_unit |
+--------------------------------+
| dimension |
+--------------------------------+
.. toctree::
:maxdepth: 2
:caption: Quantity Reference
quantity-class
quantity-factoryfunctions

43
include/xo/unit/bu_store.hpp
View file

@ -125,6 +125,9 @@ namespace xo {
* @brief associate basis units with abbreviations
**/
struct bu_store {
/** @defgroup bu-store-constructors bu-store constructors **/
///@{
/** construct canonical instance containing all known basis units **/
constexpr bu_store() {
// ----- mass -----
@ -180,7 +183,25 @@ namespace xo {
this->bu_establish_abbrev(detail::bu::currency, bu_abbrev_type::from_chars("ccy"));
this->bu_establish_abbrev(detail::bu::price, bu_abbrev_type::from_chars("px"));
}
///@}
/** @defgroup bu-store-implementation-methods **/
///@{
/** report fallback abbreviation for a basis unit.
*
* Typically unused. Will be invoked only if a basis unit exists for which
* @ref bu_store::bu_establish_abbrev was not called by bu_store's constructor.
*
* Tries to produce something unambiguous,
* while still supplying enough information
* to indicate what's needed to resolve the problem.
*
* Example
* @code
* bu_store.bu_fallback_abbrev(dim::mass, scalefactor_ratio_type(1234,1))
* => "1234g"
* @endcode
**/
static constexpr bu_abbrev_type
bu_fallback_abbrev(dim basis_dim,
const scalefactor_ratio_type & scalefactor)
@ -190,7 +211,10 @@ namespace xo {
(scalefactor.to_str<bu_abbrev_type::fixed_capacity>(),
native_unit2_v[static_cast<std::uint32_t>(basis_dim)].abbrev_str())));
}
///@}
/** @defgroup bu-store-access-methods **/
///@{
/** @brief get basis-unit abbreviation at runtime **/
constexpr bu_abbrev_type bu_abbrev(const basis_unit & bu) const
{
@ -206,17 +230,32 @@ namespace xo {
return bu_fallback_abbrev(bu.native_dim(), bu.scalefactor());
}
}
///@}
/** @addtogroup bu-store-implementation-methods **/
///@{
/** associate abbreviation @p abbrev with basis unit @p bu
*
* Example:
* @code
* // femtograms
* bu_store.bu_establish_abbrev(detail::bu::mass_unit(1, 1000000000000000), "fg")
* @endcode
**/
constexpr void bu_establish_abbrev(const basis_unit & bu,
const bu_abbrev_type & abbrev) {
auto & dim_store = bu_abbrev_vv_[static_cast<std::size_t>(bu.native_dim_)];
dim_store.bu_establish_abbrev(bu.scalefactor_, abbrev);
}
///@}
public:
/** **/
public: /* ntoe: public members required so bu_dim_store can be a structural type */
/** @defgroup bu-store-instance-vars **/
///@{
/** bu-store contents, indexed by native dimension **/
std::array<bu_dim_store, n_dim> bu_abbrev_vv_;
///@}
};
} /*namespace detail*/

20
include/xo/unit/natural_unit.hpp
View file

@ -63,13 +63,18 @@ namespace xo {
using ratio_int_type = Int;
public:
/** @addtogroup natural-unit-ctors **/
///@{
constexpr natural_unit() : n_bpu_{0} {}
static constexpr natural_unit from_bu(basis_unit bu,
power_ratio_type power = power_ratio_type(1)) {
return detail::nu_maker<Int>::make_nu(bpu<Int>(bu, power));
}
///@}
/** @addtogroup natural-unit-access-methods **/
///@{
/** always true. @see scaled_unit::is_natural **/
constexpr bool is_natural() const { return true; }
@ -77,7 +82,10 @@ namespace xo {
constexpr bool is_dimensionless() const { return n_bpu_ == 0; }
constexpr bpu<Int> * bpu_v() const { return bpu_v_; }
///@}
/** @defgroup natural-unit-methods **/
///@{
constexpr natural_unit reciprocal() const {
natural_unit retval;
@ -111,10 +119,16 @@ namespace xo {
if (n_bpu_ < n_dim)
bpu_v_[n_bpu_++] = bpu;
}
///@}
/** @addtogroup natural-unit-access-methods **/
///@{
constexpr bpu<Int> & operator[](std::size_t i) { return bpu_v_[i]; }
constexpr const bpu<Int> & operator[](std::size_t i) const { return bpu_v_[i]; }
///@}
/** @defgroup natural-unit-conversion-methods **/
///@{
template <typename Int2>
constexpr natural_unit<Int2> to_repr() const {
natural_unit<Int2> retval;
@ -125,13 +139,17 @@ namespace xo {
return retval;
}
///@}
public: /* need public members so that a natural_unit instance can be a non-type template parameter (a structural type) */
public: /* public members so instance can be non-type template parameter (is a structural type) */
/** @defgroup natural-unit-instance-vars **/
///@{
/** @brief the number of occupied slots in @c bpu_v_ **/
std::size_t n_bpu_;
/** @brief storage for basis power units **/
bpu<Int> bpu_v_[n_dim];
///@}
};
template <typename Int>

5
include/xo/unit/scaled_unit.hpp
View file

@ -33,10 +33,7 @@ namespace xo {
1.0 / outer_scale_sq_);
}
/** @brief true iff scaled unit can be faithfully represented by a @ref natural_unit
*
* @see natural_unit::is_natural
**/
/** @brief true iff scaled unit can be faithfully represented by a @ref natural_unit **/
constexpr bool is_natural() const {
return (outer_scale_factor_ == OuterScale(1) && (outer_scale_sq_ == 1.0));
}