From 454b1466a3698cf5f6766222b6e4259a476266ed Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Sun, 19 May 2024 17:53:03 -0400 Subject: [PATCH] xo-unit: ++ documentation for bu_store --- docs/CMakeLists.txt | 4 ++- docs/README | 39 +++++++++++++++++++++++++++++ docs/basis-unit-class.rst | 3 +++ docs/basis-unit-reference.rst | 19 +++++++++++++- docs/bpu-class.rst | 18 +++++++++++++ docs/bu-store-class.rst | 32 +++++++++++++++++++++--- docs/dimension-enum.rst | 18 +++++++++++++ docs/implementation.rst | 26 +++++++++++-------- docs/index.rst | 3 ++- docs/quantity-reference.rst | 19 +++++++++++++- include/xo/unit/bu_store.hpp | 43 ++++++++++++++++++++++++++++++-- include/xo/unit/natural_unit.hpp | 20 ++++++++++++++- include/xo/unit/scaled_unit.hpp | 5 +--- 13 files changed, 223 insertions(+), 26 deletions(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index f221b09c..3e28a89e 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -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 ) diff --git a/docs/README b/docs/README index 078db7c8..2fab6399 100644 --- a/docs/README +++ b/docs/README @@ -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 diff --git a/docs/basis-unit-class.rst b/docs/basis-unit-class.rst index 45550c9c..26714c6f 100644 --- a/docs/basis-unit-class.rst +++ b/docs/basis-unit-class.rst @@ -7,6 +7,9 @@ Basis Unit #include +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. diff --git a/docs/basis-unit-reference.rst b/docs/basis-unit-reference.rst index d5adcec9..acf18e14 100644 --- a/docs/basis-unit-reference.rst +++ b/docs/basis-unit-reference.rst @@ -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 diff --git a/docs/bpu-class.rst b/docs/bpu-class.rst index 7348d9b5..4d501d12 100644 --- a/docs/bpu-class.rst +++ b/docs/bpu-class.rst @@ -3,6 +3,24 @@ BPU === +.. ditaa:: + + +-----------+-----------+ + | quantity | xquantity | + +-----------+-----------+ + | scaled_unit | + +-----------------------+ + | natural_unit | + +-----------------------+ + |cYEL bpu | + +-------------+ | + | bu_store | | + +-------------+---------+ + | basis_unit | + +-----------------------+ + | dimension | + +-----------------------+ + .. code-block:: cpp #include diff --git a/docs/bu-store-class.rst b/docs/bu-store-class.rst index c7f13e2d..cf531dec 100644 --- a/docs/bu-store-class.rst +++ b/docs/bu-store-class.rst @@ -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 @@ -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::milligram => "mg" bu::gram => "g" bu::kilogram => "kg" } - map distance_table { + map distance_table<> { bu::millimeter => "mm" bu::meter => "m" bu::kilometer => "km" } - map time_table { + map time_table<> { 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 diff --git a/docs/dimension-enum.rst b/docs/dimension-enum.rst index dd7b1edc..e1dc4d24 100644 --- a/docs/dimension-enum.rst +++ b/docs/dimension-enum.rst @@ -3,6 +3,24 @@ Dimension ========= +.. ditaa:: + + +-----------+-----------+ + | quantity | xquantity | + +-----------+-----------+ + | scaled_unit | + +-----------------------+ + | natural_unit | + +-----------------------+ + | bpu | + +-----------+ | + | bu_store | | + +-----------+-----------+ + | basis_unit | + +-----------------------+ + |cYEL dimension | + +-----------------------+ + .. code-block:: cpp #include diff --git a/docs/implementation.rst b/docs/implementation.rst index 2b89fb48..4f2802fc 100644 --- a/docs/implementation.rst +++ b/docs/implementation.rst @@ -23,14 +23,17 @@ Abstraction tower for *xo-unit* components. | dimension | +-----------------------+ -- quantity: see :doc:`quantity-reference`. - quantity with compile-time unit work +- :doc:`quantity`: + + 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`: + + 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` + + 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` A rational (usually integer) power of a basis unit. Has a single dimension. -- bu_store: :doc:`bu-store-class`. +- :doc:`bu_store` Associates basis units with abbreviations. For example ``bu::kilogram`` => ``"kg"`` -- basis_unit: :doc:`basis-unit-reference`. +- :doc:`basis_unit` A unit with a single dimension and scale. -- dimension: :doc:`dimension-enum`. +- :doc:`dimension` identifies a dimension, such as mass or time. diff --git a/docs/index.rst b/docs/index.rst index f0584e79..ccba32b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/quantity-reference.rst b/docs/quantity-reference.rst index 1f3b4496..44095ce7 100644 --- a/docs/quantity-reference.rst +++ b/docs/quantity-reference.rst @@ -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 diff --git a/include/xo/unit/bu_store.hpp b/include/xo/unit/bu_store.hpp index 3bc816f0..a06d5b4f 100644 --- a/include/xo/unit/bu_store.hpp +++ b/include/xo/unit/bu_store.hpp @@ -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(), native_unit2_v[static_cast(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(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_abbrev_vv_; + ///@} }; } /*namespace detail*/ diff --git a/include/xo/unit/natural_unit.hpp b/include/xo/unit/natural_unit.hpp index d3f05da8..9cdb81ae 100644 --- a/include/xo/unit/natural_unit.hpp +++ b/include/xo/unit/natural_unit.hpp @@ -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::make_nu(bpu(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 * 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 & operator[](std::size_t i) { return bpu_v_[i]; } constexpr const bpu & operator[](std::size_t i) const { return bpu_v_[i]; } + ///@} + /** @defgroup natural-unit-conversion-methods **/ + ///@{ template constexpr natural_unit to_repr() const { natural_unit 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 bpu_v_[n_dim]; + ///@} }; template diff --git a/include/xo/unit/scaled_unit.hpp b/include/xo/unit/scaled_unit.hpp index 8e75c0f0..44129426 100644 --- a/include/xo/unit/scaled_unit.hpp +++ b/include/xo/unit/scaled_unit.hpp @@ -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)); }