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

xo-unit: expand bpu docs

Browse source
This commit is contained in:
Roland Conybeare 2024-05-09 10:35:02 -04:00
commit 02f44264d7
3 changed files with 76 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -10,9 +10,6 @@ Basis Unit
A :code:`basis_unit` represents a unit belonging to a single native dimension.
For example :code:`bu::meter` representing a distance of 1 meter.
Class
-----
.. doxygenclass:: xo::qty::basis_unit
Member Variables

34
docs/bpu-class.rst
View file

@ -7,7 +7,7 @@ BPU
#include <xo/unit/bpu.hpp>
A :code:`xo::qty::bpu` represents a rational (usually integer) power of a :doc:`basis-unit-class`.
A :code:`xo::qty::bpu` (aka "basis power unit") represents a rational (usually integer) power of a :doc:`basis-unit-class`.
For example:
@ -30,3 +30,35 @@ For example:
vol : native_dim = dim::time
vol : scalefactor = 365*24*3600
vol : power = -1/2
.. doxygenclass:: xo::qty::bpu
Member Variables
----------------
.. doxygengroup:: bpu-instance-vars
Constructors
------------
.. doxygengroup:: bpu-ctors
Access Methods
--------------
.. doxygengroup:: bpu-access-methods
Other Methods
-------------
.. doxygengroup:: bpu-methods
Comparison
----------
.. doxygengroup:: bpu-comparison
Details
-------
.. doxygengroup:: bpu-abbrev-helpers

53
include/xo/unit/bpu.hpp
View file

@ -13,6 +13,12 @@ namespace xo {
namespace abbrev {
using power_abbrev_type = flatstring<16>;
/** @defgroup bpu-abbrev-helpers bpu abbrev helpers **/
///@{
/** @brief construct prefix string for unit exponent
*
* Auxiliary function for @ref bpu_abbrev
**/
constexpr power_abbrev_type
flatstring_from_exponent(std::int64_t num,
std::int64_t den)
@ -33,6 +39,7 @@ namespace xo {
}
}
/** @brief construct suffix abbreviation for a basis-power-unit **/
static constexpr bpu_abbrev_type
bpu_abbrev(dim native_dim,
const scalefactor_ratio_type & scalefactor,
@ -43,6 +50,7 @@ namespace xo {
(bu_abbrev(basis_unit(native_dim, scalefactor)),
flatstring_from_exponent(power.num(), power.den()))));
}
///@}
}
/** @class bpu
@ -55,6 +63,8 @@ namespace xo {
using ratio_int_type = Int;
public:
/** @defgroup bpu-ctors bpu constructors **/
///@{
constexpr bpu() = default;
constexpr bpu(const basis_unit & bu,
const power_ratio_type & power)
@ -67,21 +77,29 @@ namespace xo {
: bu_(native_dim, scalefactor),
power_{power}
{}
///@}
static constexpr bpu<Int> unit_power(const basis_unit & bu) {
return bpu<Int>(bu, power_ratio_type(1,1));
}
/** @defgroup bpu-access-methods bpu access methods **/
///@{
/** @brief report this bpu's @ref basis_unit **/
constexpr const basis_unit & bu() const { return bu_; }
constexpr dimension native_dim() const { return bu_.native_dim(); }
constexpr const scalefactor_ratio_type & scalefactor() const { return bu_.scalefactor(); }
constexpr const power_ratio_type & power() const { return power_; }
///@}
/** @defgroup bpu-methods **/
///@{
/** @brief abbreviation for this dimension
*
* @code
* bpu2<int64_t>(dim::time,
* scalefactor_ratio_type(60,1),
* power_ratio_type(-2,1)).abbrev() => "min^-2"
* bpu<int64_t>(dim::time,
* scalefactor_ratio_type(60,1),
* power_ratio_type(-2,1)).abbrev() => "min^-2"
* @endcode
**/
constexpr bpu_abbrev_type abbrev() const
@ -91,30 +109,43 @@ namespace xo {
power_);
}
/* for bpu x, x.reciprocal() represents dimension of 1/x */
/** @brief for bpu @c x, @c x.reciprocal() represents dimension of @c 1/x
*
* Example:
* @code
* constexpr auto x = bpu<int64_t>(dim::time,
* scalefactor_ratio_type(60,1),
* power_ratio_type(1));
* x.abbrev() => "min"
* x.reciprocal().abbrev() => "min^-1"
* @endcode
**/
constexpr bpu<Int> reciprocal() const {
return bpu<Int>(bu_.native_dim(), bu_.scalefactor(), power_.negate());
}
/** @brief construct bpu representing the same unit, but using @c Int2 to represent exponenct **/
template <typename Int2>
constexpr bpu<Int2> to_repr() const {
return bpu<Int2>(this->native_dim(),
this->scalefactor(),
ratio::ratio<Int2>(power_.num(), power_.den()));
}
///@}
public: /* need public members so that a basis_unit instance can be a non-type template parameter (a structural type) */
/** @defgroup bpu-instance-vars **/
///@{
/** @brief this bpu represent a power of this basis unit **/
basis_unit bu_;
struct basis_unit bu_;
/** @brief this unit represents basis dimension (bu) taken to this power **/
power_ratio_type power_;
///@}
};
template <typename Int>
constexpr auto make_unit_power(const basis_unit & bu) {
return bpu<Int>::unit_power(bu);
}
/** @defgroup bpu-comparison **/
///@{
/** @brief compare bpus @p x and @p y for equality **/
template <typename Int>
inline constexpr bool
operator==(const bpu<Int> & x, const bpu<Int> & y) {
@ -123,6 +154,7 @@ namespace xo {
&& (x.power_ == y.power_));
}
/** @brief compare bpus @p x and @p y for inequality **/
template <typename Int>
inline constexpr bool
operator!=(const bpu<Int> & x, const bpu<Int> & y) {
@ -130,6 +162,7 @@ namespace xo {
|| (x.scalefactor() != y.scalefactor())
|| (x.power_ != y.power_));
}
///@}
} /*namespace qty*/
} /*namespace xo*/