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

xo-unit: docs: doxygen comments + refactoring

Browse source
This commit is contained in:
Roland Conybeare 2024-05-07 10:45:48 -04:00
commit 6ba4b23ece
3 changed files with 65 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

10
include/xo/unit/mpl/quantity.hpp
View file

@ -28,7 +28,7 @@ namespace xo {
template <typename Unit, typename Repr = double>
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<unit_type>.c_str(); }
///@}
/** @defgroup quantity-constants constants
/** @defgroup mpl-quantity-constants constants
**/
///@{
/** @brief report exponent of @p BasisDim in dimension of this quantity

52
include/xo/unit/quantity.hpp
View file

@ -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<NaturalUnit, Repr>) == 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<typename unit_type::ratio_int_type>;
///@}
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<repr_type>()
* rr.outer_scale_factor_.template convert_to<repr_type>()
* this->scale_
/ ScaledUnit2.outer_scale_factor_.template convert_to<repr_type>());
return quantity<ScaledUnit2.natural_unit_, Repr>(r_scale);
@ -382,8 +422,11 @@ namespace xo {
inline constexpr auto milligrams(Repr x) { return quantity<nu::milligram, Repr>(x); }
template <typename Repr>
inline constexpr auto grams(Repr x) { return quantity<nu::gram, Repr>(x); }
/** @brief create a quantity representing @p x kilograms of mass, with compile-time unit representation **/
template <typename Repr>
inline constexpr auto kilograms(Repr x) { return quantity<nu::kilogram, Repr>(x); }
template <typename Repr>
inline constexpr auto tonnes(Repr x) { return quantity<nu::tonne, Repr>(x); }
template <typename Repr>
@ -482,19 +525,26 @@ namespace xo {
inline constexpr auto nanoseconds(Repr x) { return quantity<nu::nanosecond, Repr>(x); }
template <typename Repr>
inline constexpr auto microseconds(Repr x) { return quantity<nu::microsecond, Repr>(x); }
template <typename Repr>
inline constexpr auto milliseconds(Repr x) { return quantity<nu::millisecond, Repr>(x); }
/** @brief create quantity representing @p x seconds of time, with compile-time unit representation **/
template <typename Repr>
inline constexpr auto seconds(Repr x) { return quantity<nu::second, Repr>(x); }
/** @brief create quantity representing @p x minutes of time, with compile-time unit representation **/
template <typename Repr>
inline constexpr auto minutes(Repr x) { return quantity<nu::minute, Repr>(x); }
/** @brief create quantity representing @p x hours of time, with compile-time unit representation **/
template <typename Repr>
inline constexpr auto hours(Repr x) { return quantity<nu::hour, Repr>(x); }
/** @brief create quantity representing @p x days of time, with compile-time unit representation **/
template <typename Repr>
inline constexpr auto days(Repr x) { return quantity<nu::day, Repr>(x); }
template <typename Repr>
inline constexpr auto weeks(Repr x) { return quantity<nu::week, Repr>(x); }
template <typename Repr>

13
include/xo/unit/xquantity.hpp
View file

@ -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 <a href="https://github.com/rconybea/xo-pyutil">xo-pyutil</a>
*
* 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 (+, -, *, /)