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

xo-ratio: doc: ++ doxygen improvements

Browse source
This commit is contained in:
Roland Conybeare 2024-04-19 07:18:23 -04:00
commit 15b9162aa4
1 changed files with 78 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

98
include/xo/ratio/ratio.hpp
View file

@ -26,17 +26,31 @@ namespace xo {
struct promoter_type;
}
/** @brief represent a ratio of two Int values. **/
template <typename Int>
requires std::totally_ordered<Int>
/** @class ratio
* @brief represent a ratio of two Int values.
**/
template <typename Int> requires std::totally_ordered<Int>
struct ratio
{
public:
/** @defgroup ratio-types **/
///@{
/** @brief representation for (numerator, denominator) **/
using component_type = Int;
///@}
public:
/** @defgroup ratio-ctor **/
///@{
/** @brief construct ratio with numerator @p n and denominator @p d.
*
* Ratio need not be normalized
**/
constexpr ratio(Int n, Int d) : num_{n}, den_{d} {}
///@}
/** @defgroup ratio-static-methods **/
///@{
/** @brief ratio in lowest commono terms
*
**/
@ -44,7 +58,10 @@ namespace xo {
return ratio(n, d).normalize();
}
/** @brief add two ratios **/
/** @brief add ratios @p x and @p y
*
* @post result ratio is normalized
**/
static constexpr ratio add(const ratio & x,
const ratio & y) {
/* (a/b) + (c/d)
@ -63,13 +80,19 @@ namespace xo {
return ratio(num, den).maybe_reduce();
}
/** @brief subtract two ratios **/
/** @brief subtract ratio @p y from ratio @p x
*
* @post result ratio is normalized
**/
static constexpr ratio subtract(const ratio & x,
const ratio & y) {
return add(x, y.negate());
}
/** @brief multiply two ratios **/
/** @brief multiply ratios @p x and @p y
*
* @post result ratio is normalized
**/
static constexpr ratio multiply(const ratio & x,
const ratio & y) {
/* (a/b) * (c/d) = a.c / b.d */
@ -99,13 +122,20 @@ namespace xo {
return ratio(num, den).maybe_reduce();
}
/** @brief divide two ratios **/
/** @brief divide ratio @p y into ratio @p x
*
* @post result ratio is normalized
**/
static constexpr ratio divide(const ratio & x,
const ratio & y) {
return multiply(x, y.reciprocal());
}
const ratio & y)
{
return multiply(x, y.reciprocal());
}
/** @brief compute integer power of a ratio **/
/** @brief compute integer exponent @p p of this ratio
*
* @note time complexity is O(log p)
**/
constexpr ratio power(int p) const {
constexpr ratio retval = ratio(1, 1);
@ -147,19 +177,33 @@ namespace xo {
return compare_aux(x, y);
}
///@}
/** @defgroup ratio-access **/
///@{
/** @brief fetch ratio's numerator **/
constexpr Int num() const noexcept { return num_; }
/** @brief fetch ratio's denominator **/
constexpr Int den() const noexcept { return den_; }
/** @brief true if and only if ratio represents an integer
*
* (denominator is +/- 1)
**/
constexpr bool is_integer() const noexcept { return den_ == 1 || den_ == -1; }
///@}
/** @defgroup ratio-methods **/
///@{
/** @brief r.negate() is the exact ratio representing @c -r **/
constexpr ratio negate() const { return ratio(-num_, den_); }
/** @brief r.reciprocal() is the eact ratio representing @c 1/r **/
constexpr ratio reciprocal() const { return ratio(den_, num_); }
/** @brief requires component_type is totally ordered **/
/** @brief r.floor() is the largest integer x : x <= r **/
constexpr Int floor() const { return (num_ / den_); }
/** @brief requires component_type is totally ordered **/
/** @brief r.ceil() is the smallest integer x : r < x. **/
constexpr Int ceil() const { return floor() + 1; }
/** @brief reduce to lowest terms
@ -192,6 +236,12 @@ namespace xo {
return ratio::subtract(*this, this->floor());
}
/** @brief negate operator **/
constexpr ratio operator-() const { return ratio(-num_, den_); }
///@}
/** @defgroup ratio-conversion **/
///@{
/** @brief convert to non-ratio representation
*
* For example: to int or double
@ -203,10 +253,10 @@ namespace xo {
*
* Example:
* @code
* ratio(7,1).to_str<5>(); // "7"
* ratio(1,7).to_str<5>(); // "(1/7)"
* ratio(7,1).to_str<5>(); // "7"
* ratio(1,7).to_str<5>(); // "(1/7)"
* ratio(-1,7).to_str<10>(); // "(-1/7)"
* ratio(-1,7).to_str<5>(); // "(-1/"
* ratio(-1,7).to_str<5>(); // "(-1/"
* @endcode
**/
template <std::size_t N>
@ -231,14 +281,12 @@ namespace xo {
}
}
/** @brief negate operator **/
constexpr ratio operator-() const { return ratio(-num_, den_); }
/** @brief convert to representation using different integer types **/
template <typename Ratio2>
constexpr operator Ratio2 () const noexcept requires ratio_concept<Ratio2> {
return Ratio2(num_, den_);
}
///@}
private:
/** @brief 3-way compare auxiliary function.
@ -264,10 +312,13 @@ namespace xo {
}
private:
/** @defgroup ratio-instance-variables **/
///@{
/** @brief numerator **/
Int num_;
/** @brief denominator **/
Int den_;
///@}
};
namespace detail {
@ -276,7 +327,7 @@ namespace xo {
template <typename Ratio>
struct reducer_type<Ratio, true /*EnabledFlag*/> {
static constexpr Ratio attempt_reduce(Ratio x) { return x.reduce(); }
static constexpr Ratio attempt_reduce(Ratio x) { return x.normalize(); }
};
template <typename Ratio>
@ -302,6 +353,7 @@ namespace xo {
};
}
/** @brief create a ratio in lowest terms from two integers **/
template <typename Int1, typename Int2>
constexpr auto
make_ratio (Int1 n, Int2 d = 1) -> ratio<std::common_type_t<Int1, Int2>>
@ -505,6 +557,8 @@ namespace xo {
};
} /*namespace detail*/
/** @defgroup ratio-arithmetic **/
///@{
/** @brief add two ratios.
*
* One argument may be a non-ratio type if it can be promoted to a ratio
@ -552,7 +606,10 @@ namespace xo {
{
return detail::op_aux_type<Ratio1, Ratio2>::divide(x, y);
}
///@}
/** @defgroup ratio-3way-compare 3way comparison **/
///@{
/** @brief compare two ratios for equality
*
* One argument may be a non-ratio type if it can be promoted to a ratio
@ -576,6 +633,7 @@ namespace xo {
{
return detail::op_aux_type<Ratio1, Ratio2>::compare(x, y);
}
///@}
} /*namespace ratio*/
} /*namespace xo*/