From 6ba4b23ecee585e41402b1d0a5f19a81ac3e0db7 Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Tue, 7 May 2024 10:45:48 -0400 Subject: [PATCH] xo-unit: docs: doxygen comments + refactoring --- include/xo/unit/mpl/quantity.hpp | 10 +++--- include/xo/unit/quantity.hpp | 52 +++++++++++++++++++++++++++++++- include/xo/unit/xquantity.hpp | 13 +++++--- 3 files changed, 65 insertions(+), 10 deletions(-) diff --git a/include/xo/unit/mpl/quantity.hpp b/include/xo/unit/mpl/quantity.hpp index 588c45ec..8ccc1628 100644 --- a/include/xo/unit/mpl/quantity.hpp +++ b/include/xo/unit/mpl/quantity.hpp @@ -28,7 +28,7 @@ namespace xo { template class quantity { public: - /** @defgroup quantity-traits **/ + /** @defgroup mpl-quantity-traits **/ ///@{ /** @brief type capturing the units (and dimension) of this quantity **/ using unit_type = Unit; @@ -45,7 +45,7 @@ namespace xo { static_assert(std::same_as< typename Unit::canon_type, typename Unit::canon_type >); public: - /** @defgroup quantity-ctors constructors + /** @defgroup mpl-quantity-ctors constructors **/ ///@{ constexpr quantity() = default; @@ -69,7 +69,7 @@ namespace xo { static constexpr auto promote(Repr x); ///@} - /** @addtogroup quantity-traits **/ + /** @addtogroup mpl-quantity-traits **/ ///@{ /** @brief report this quantity's basis-power-unit type for a given basis dimension @@ -98,7 +98,7 @@ namespace xo { ///@} - /** @defgroup quantity-access-methods **/ + /** @defgroup mpl-quantity-access-methods **/ ///@{ /** @brief get scale value (relative to unit) (@ref scale_) **/ constexpr Repr scale() const { return scale_; } @@ -117,7 +117,7 @@ namespace xo { static constexpr char const * unit_cstr() { return unit_abbrev_v.c_str(); } ///@} - /** @defgroup quantity-constants constants + /** @defgroup mpl-quantity-constants constants **/ ///@{ /** @brief report exponent of @p BasisDim in dimension of this quantity diff --git a/include/xo/unit/quantity.hpp b/include/xo/unit/quantity.hpp index a941c8f6..aaa58865 100644 --- a/include/xo/unit/quantity.hpp +++ b/include/xo/unit/quantity.hpp @@ -12,33 +12,73 @@ namespace xo { namespace qty { /** @class quantity + * * @brief represent a scalar quantity with associated units. * + * - @p NaturalUnit is a non-type template parameter + * identifying a unit used for this quantity. + * In *xo-unit* it will be an instance of @c natural_unit + * - @p Repr is a type used to represent a multiple + * of @p NaturalUnit. + * * Enforce dimensional consistency at compile time. * sizeof(quantity) == sizeof(Repr). + * + * A quantity's runtime state consists of exactly one @p Repr instance: + * @code + * sizeof(quantity) == sizeof(Repr) + * @endcode **/ template < auto NaturalUnit, typename Repr = double> class quantity { public: + /** @defgroup quantity-type-traits quantity type traits **/ + ///@{ + /** @brief runtime representation for value of this type **/ using repr_type = Repr; + /** @brief type used to represent unit information */ using unit_type = decltype(NaturalUnit); + /** @brief type used for numerator and denominator in basis-unit scalefactor ratios */ using ratio_int_type = unit_type::ratio_int_type; + /** @brief double-width type used for numerator and denominator of intermediate + * scalefactor ratios. Used to mitigate loss of precision during computation + * of conversion factors between units with widely-differing magnitude + **/ using ratio_int2x_type = detail::width2x_t; + ///@} public: + /** @defgroup quantity-ctors quantity constructors**/ + ///@{ + /** @brief create a zero amount with dimension @c NaturalUnit **/ constexpr quantity() : scale_{0} {} + /** @brief create a quantity representing @p scale @c NaturalUnits **/ explicit constexpr quantity(Repr scale) : scale_{scale} {} + ///@} + /** @defgroup quantity-constants static quantity constants **/ + ///@{ + /** @brief Use to distinguish @ref quantity from xquantity instances. + * + * Useful in c++ template resolution. + **/ static constexpr bool always_constexpr_unit = true; + ///@} + /** @defgroup quantity-access-methods quantity access methods **/ + ///@{ + /** @brief value of @c scale_ in quantity representing amount (@c scale_ * @c s_unit) **/ constexpr const repr_type & scale() const { return scale_; } + /** @brief s_unit in quantity representing amount (@c scale_ * @c s_unit) **/ constexpr const unit_type & unit() const { return s_unit; } + /** @brief true iff this quantity represents a dimensionless value **/ constexpr bool is_dimensionless() const { return s_unit.is_dimensionless(); } + ///@} // unit_qty // zero_qty @@ -94,7 +134,7 @@ namespace xo { && (ScaledUnit2.outer_scale_sq_ == 1.0)) ? 1.0 : ::sqrt(rr.outer_scale_sq_ / ScaledUnit2.outer_scale_sq_)) - * rr.outer_scale_factor_.template convert_to() + * rr.outer_scale_factor_.template convert_to() * this->scale_ / ScaledUnit2.outer_scale_factor_.template convert_to()); return quantity(r_scale); @@ -382,8 +422,11 @@ namespace xo { inline constexpr auto milligrams(Repr x) { return quantity(x); } template inline constexpr auto grams(Repr x) { return quantity(x); } + + /** @brief create a quantity representing @p x kilograms of mass, with compile-time unit representation **/ template inline constexpr auto kilograms(Repr x) { return quantity(x); } + template inline constexpr auto tonnes(Repr x) { return quantity(x); } template @@ -482,19 +525,26 @@ namespace xo { inline constexpr auto nanoseconds(Repr x) { return quantity(x); } template inline constexpr auto microseconds(Repr x) { return quantity(x); } + template inline constexpr auto milliseconds(Repr x) { return quantity(x); } + /** @brief create quantity representing @p x seconds of time, with compile-time unit representation **/ template inline constexpr auto seconds(Repr x) { return quantity(x); } + /** @brief create quantity representing @p x minutes of time, with compile-time unit representation **/ template inline constexpr auto minutes(Repr x) { return quantity(x); } + /** @brief create quantity representing @p x hours of time, with compile-time unit representation **/ template inline constexpr auto hours(Repr x) { return quantity(x); } + + /** @brief create quantity representing @p x days of time, with compile-time unit representation **/ template inline constexpr auto days(Repr x) { return quantity(x); } + template inline constexpr auto weeks(Repr x) { return quantity(x); } template diff --git a/include/xo/unit/xquantity.hpp b/include/xo/unit/xquantity.hpp index c0d3df78..31c9ef31 100644 --- a/include/xo/unit/xquantity.hpp +++ b/include/xo/unit/xquantity.hpp @@ -11,16 +11,21 @@ namespace xo { namespace qty { - /** @class Quantity - * @brief represent a scalar quantity with attached units. enforce dimensional consistency. + /** @class xquantity + * @brief represent a scalar quantity with polymorphic units. + * + * - @p Repr type used represent a dimensionless multiple of a natural unit. * * Constexpr implementation, but units are explicitly represented: + * @code * sizeof(Quantity2) > sizeof(Repr) + * @endcode * * Explicit unit representation allows introducing units at runtime, - * for example in python bindings + * for example in python bindings. + * See for example xo-pyutil * - * See xo::qty::quantity<> for implementation with units established at compile time + * See @ref quantity for implementation with units established at compile time * * Require: * - Repr supports numeric operations (+, -, *, /)