From e6afc4dd73225a96113eedb29688c56fb102b145 Mon Sep 17 00:00:00 2001 From: jtlap Date: Mon, 8 Jul 2024 08:05:11 +0200 Subject: [PATCH] Documentation for P functions --- .../combinatorial/regular/prime_ceil.hpp | 23 ++---- .../combinatorial/regular/prime_floor.hpp | 23 ++---- include/eve/module/core/regular/popcount.hpp | 13 ++-- include/eve/module/core/regular/prev.hpp | 46 ++++++------ include/eve/module/math/regular/pow.hpp | 32 ++++----- include/eve/module/math/regular/pow1p.hpp | 35 +++++----- include/eve/module/math/regular/pow_abs.hpp | 70 +++++++++---------- include/eve/module/math/regular/powm1.hpp | 35 +++++----- 8 files changed, 118 insertions(+), 159 deletions(-) diff --git a/include/eve/module/combinatorial/regular/prime_ceil.hpp b/include/eve/module/combinatorial/regular/prime_ceil.hpp index b52f66e6dc..45d378c5db 100644 --- a/include/eve/module/combinatorial/regular/prime_ceil.hpp +++ b/include/eve/module/combinatorial/regular/prime_ceil.hpp @@ -41,9 +41,9 @@ namespace eve //! @addtogroup combinatorial //! @{ //! @var prime_ceil -//! @brief Returns the smallest prime greater or equal to the input. +//! @brief `strict_elementwise_callable` object computing the smallest prime greater or equal to the input. //! -//! **Defined in Header** +//! @groupheader{Header file} //! //! @code //! #include @@ -54,8 +54,7 @@ namespace eve //! @code //! namespace eve //! { -//! template< eve::unsigned_value N > -//! constexpr N prime_ceil(N n) noexcept; +//! constexpr auto prime_ceil(unsigned_value auto x) noexcept; //! } //! @endcode //! @@ -64,23 +63,11 @@ namespace eve //! * `n` : unsigned argument. If `n` is greater than 104'729, behavior is undefined. //! //! **Return value** -//! The smallest prime greater or equal to `n`. -//! The result type is the same as the input one unless a converter is applied (see below). +//! The smallest prime greater or equal to `n`. +//! The result type is the same as the input one unless a converter is applied (see below). //! //! @groupheader{Example} -//! //! @godbolt{doc/combinatorial/regular/prime_ceil.cpp} -//! -//! @groupheader{Semantic Modifiers} -//! -//! * Optimized Conversion Call -//! -//! The converters eve::float_, eve::double_, eve::floating_ can be applied to -//! produce a floating point output. -//! -//! **Example** -//! -//! @godbolt{doc/combinatorial/conversion/prime_ceil.cpp} //! @} //================================================================================================ inline constexpr auto prime_ceil = functor; diff --git a/include/eve/module/combinatorial/regular/prime_floor.hpp b/include/eve/module/combinatorial/regular/prime_floor.hpp index 2209ca8483..33cf4824cf 100644 --- a/include/eve/module/combinatorial/regular/prime_floor.hpp +++ b/include/eve/module/combinatorial/regular/prime_floor.hpp @@ -39,9 +39,9 @@ namespace eve //! @addtogroup combinatorial //! @{ //! @var prime_floor -//! @brief Returns the the greatest prime less or equal to the input. +//! @brief `strict_elementwise_callable` object computing the greatest prime less or equal to the input. //! -//! **Defined in Header** +//! @groupheader{Header file} //! //! @code //! #include @@ -52,8 +52,7 @@ namespace eve //! @code //! namespace eve //! { -//! template< eve::unsigned_value N > -//! constexpr N prime_floor(N n) noexcept ; +//! constexpr auto prime_floor(unsigned_value auto x) noexcept; //! } //! @endcode //! @@ -62,23 +61,11 @@ namespace eve //! * `n` : unsigned argument. If `n` is greater than 104'729, behavior is undefined. //! //! **Return value** -//! The greatest prime less or equal to `n`. -//! The result type is the same as the input one unless a converter is applied (see below). +//! The greatest prime less or equal to `n`. +//! The result type is the same as the input one unless a converter is applied (see below). //! //! @groupheader{Example} -//! //! @godbolt{doc/combinatorial/regular/prime_floor.cpp} -//! -//! @groupheader{Semantic Modifiers} -//! -//! * Optimized Conversion Call -//! -//! The converters eve::float_, eve::double_, eve::floating_ can be applied to -//! produce a floating point output. -//! -//! **Example** -//! -//! @godbolt{doc/combinatorial/conversion/prime_floor.cpp} //! @} //================================================================================================ inline constexpr auto prime_floor = functor; diff --git a/include/eve/module/core/regular/popcount.hpp b/include/eve/module/core/regular/popcount.hpp index 2a625b9696..dd36a0fd34 100644 --- a/include/eve/module/core/regular/popcount.hpp +++ b/include/eve/module/core/regular/popcount.hpp @@ -29,9 +29,9 @@ namespace eve //! @addtogroup core_bitops //! @{ //! @var popcount -//! @brief Computes elementwise the number of bits set in the parameter. +//! @brief `elementwise_callable` object computing elementwise the number of bits set in the parameter. //! -//! **Defined in Header** +//! @groupheader{Header file} //! //! @code //! #include @@ -42,22 +42,19 @@ namespace eve //! @code //! namespace eve //! { -//! template< eve::unsigned_value T > -//! T popcount(T x) noexcept; +//! constexpr auto popcount(unsigned_value auto x) noexcept; //! } //! @endcode //! //! **Parameters** //! -//! * `x` : [unsigned argument](@ref eve::unsigned_value). +//! * `x`: [unsigned argument](@ref eve::unsigned_value). //! //! **Return value** //! -//! The value of number of bits set in the value `x` -//! is returned. +//! The value of number of bits set in the value `x` is returned. //! //! @groupheader{Example} -//! //! @godbolt{doc/core/popcount.cpp} //! @} //================================================================================================ diff --git a/include/eve/module/core/regular/prev.hpp b/include/eve/module/core/regular/prev.hpp index 81886840e9..63ce3762e5 100644 --- a/include/eve/module/core/regular/prev.hpp +++ b/include/eve/module/core/regular/prev.hpp @@ -60,44 +60,40 @@ namespace eve //! @code //! namespace eve //! { -//! template< eve::value T, eve::integral_value N > -//! eve::common_value_t prev(T x, N n = 1) noexcept; +//! // Regular overloads +//! constexpr auto prev(value auto x) noexcept; // 1 +//! constexpr auto prev(value auto x, integral_value auto n) noexcept; // 2 +//! +//! // Lanes masking +//! constexpr auto prev[conditional_expr auto c](/* any of the above overloads */) noexcept; // 3 +//! constexpr auto prev[logical_value auto m](/* any of the above overloads */) noexcept; // 3 +//! +//! // Exclusive Semantic options - Only one of those can be set at once +//! constexpr auto prev[pedantic](/* any of the above overloads */) noexcept; // 5.1 +//! constexpr auto prev[saturated ](/* any of the above overloads */) noexcept; // 5.2 //! } //! @endcode //! //! **Parameters** //! -//! * `x`: [floating argument](@ref eve::floating_value). -//! -//! * `n` : [integral value argument](@ref eve::integral_value). +//! * `x`: [floating argument](@ref eve::floating_value). +//! * `n`: [integral value argument](@ref eve::integral_value). +//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation. +//! * `m`: [Logical value](@ref logical) masking the operation. //! //! **Return value** //! +//! 1. the greatest representable value less than `x` is returned. +//! 2. the nth representable value less than `x` is returned. If `n` is zero returns `x`. +//! 3. [The operation is performed conditionnaly](@ref conditional) +//! 4. if `x` is floating zero and mzero are considered distinct. +//! 5. ensures that the input is never less than the result of the call. +//! //! The value of the nth representable value less than `x` is returned. //! If `n` is zero returns `x`. //! //! @groupheader{Example} -//! //! @godbolt{doc/core/prev.cpp} -//! -//! @groupheader{Semantic Modifiers} -//! -//! * Masked Call -//! -//! The call `eve::prev[mask](x, ...)` provides a masked -//! version of `prev` which is -//! equivalent to `if_else(mask, prev(x, ...), x)` -//! -//! * eve::pedantic -//! -//! The call `eve::prev[eve::pedantic](x, ...)` provides a pedantic -//! version of `prev` which ensures that the predecessor of eve::zero is eve::mzero -//! for floating points entries -//! -//! * eve::saturated -//! -//! The call `eve::prev[eve::saturated](x, ...)` provides a saturated -//! version of `prev` which ensures that that x is never greater than the result of the call. //!//! @} //================================================================================================ inline constexpr auto prev = functor; diff --git a/include/eve/module/math/regular/pow.hpp b/include/eve/module/math/regular/pow.hpp index 5c9bf34265..b9ad48de5a 100644 --- a/include/eve/module/math/regular/pow.hpp +++ b/include/eve/module/math/regular/pow.hpp @@ -57,7 +57,7 @@ namespace eve //! //! @brief Callable object computing the pow operation \f$x^y\f$. //! -//! **Defined in Header** +//! @groupheader{Header file} //! //! @code //! #include @@ -68,8 +68,15 @@ namespace eve //! @code //! namespace eve //! { -//! template< eve::floating_value T, eve::floating_value U > -//! auto pow(T x, U y) noexcept; +//! // Regular overload +//! constexpr auto pow(value auto x, value auto y) noexcept; // 1 +//! +//! // Lanes masking +//! constexpr auto pow[conditional_expr auto c](value auto x, value auto y) noexcept; // 2 +//! constexpr auto pow[logical_value auto m](value auto x, value auto y) noexcept; // 2 +//! +//! // Semantic options +//! constexpr auto pow[raw](value auto x, value auto y) noexcept; // 3 //! } //! @endcode //! @@ -78,10 +85,7 @@ namespace eve //! //! **Return value** //! -//! Returns [elementwise](@ref glossary_elementwise) \f$x^y\f$. -//! -//! * The result type is the [common value type](@ref common_value_t) of the two parameters. -//! In particular we have (IEC 60559): +//! 1. Returns [elementwise](@ref glossary_elementwise) \f$x^y\f$. In particular we have (IEC 60559): //! //! * pow(+0, y), where y is a negative odd integer, returns \f$+\infty\f$ //! * pow(-0, y), where y is a negative odd integer, returns \f$-\infty\f$ @@ -106,21 +110,11 @@ namespace eve //! * pow(\f$+\infty\f$, y) returns +0 for any y less than 0 //! * pow(\f$+\infty\f$, y) returns \f$+\infty\f$ for any y greater than 0 //! * except where specified above, if any argument is NaN, NaN is returned +//! 2. [The operation is performed conditionnaly](@ref conditional) +//! 3. faster but less accurate call //! //! @groupheader{Example} -//! //! @godbolt{doc/math/regular/pow.cpp} -//! -//! @groupheader{Semantic Modifiers} -//! -//! * Masked Call -//! -//! The call `eve::pow[mask](x, y)` provides a masked version of `eve::pow` which is -//! equivalent to `if_else (mask, pow(x, y), x)`. -//! -//! **Example** -//! -//! @godbolt{doc/math/masked/pow.cpp} //! @} //================================================================================================ inline constexpr auto pow = functor; diff --git a/include/eve/module/math/regular/pow1p.hpp b/include/eve/module/math/regular/pow1p.hpp index 08b1d867b1..5a71c46cca 100644 --- a/include/eve/module/math/regular/pow1p.hpp +++ b/include/eve/module/math/regular/pow1p.hpp @@ -38,7 +38,7 @@ namespace eve //! //! @brief Callable object computing pow1p: \f$(1+x)^y\f$. //! -//! **Defined in Header** +//! @groupheader{Header file} //! //! @code //! #include @@ -46,37 +46,36 @@ namespace eve //! //! @groupheader{Callable Signatures} //! -//! //! @code //! namespace eve //! { -//! template< eve::floating_value T, eve::floating_value U > -//! auto pow1p(T x, U y) noexcept; +//! // Regular overload +//! constexpr auto pow1p(value auto x, value auto y) noexcept; // 1 +//! +//! // Lanes masking +//! constexpr auto pow1p[conditional_expr auto c](value auto x, value auto y) noexcept; // 2 +//! constexpr auto pow1p[logical_value auto m](value auto x, value auto y) noexcept; // 2 +//! +//! // Semantic options +//! constexpr auto pow1p[raw](value auto x, value auto y) noexcept; // 3 //! } //! @endcode //! //! **Parameters** //! +//! * `x`, `y`: [integral value](@ref integral_value) arguments. +//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation. +//! * `m`: [Logical value](@ref logical) masking the operation. //! //! **Return value** //! -//! Returns the [elementwise](@ref glossary_elementwise) \f$(1+x)^y\f$, with good accuracy, -//! even when `x` is small. +//! 1. Returns the [elementwise](@ref glossary_elementwise) \f$(1+x)^y\f$, with good accuracy, +//! even when `x` is small. +//! 2. [The operation is performed conditionnaly](@ref conditional) +//! 3. faster but less accurate call. //! //! @groupheader{Example} -//! //! @godbolt{doc/math/regular/pow1p.cpp} -//! -//! @groupheader{Semantic Modifiers} -//! -//! * Masked Call -//! -//! The call `eve::pow1p[mask](x, y)` provides a masked version of `eve::pow1p` which is -//! equivalent to `if_else (mask, pow1p(x, y), x)`. -//! -//! **Example** -//! -//! @godbolt{doc/math/masked/pow1p.cpp} //! @} //================================================================================================ inline constexpr auto pow1p = functor; diff --git a/include/eve/module/math/regular/pow_abs.hpp b/include/eve/module/math/regular/pow_abs.hpp index c8d117432a..8ba1b1e631 100644 --- a/include/eve/module/math/regular/pow_abs.hpp +++ b/include/eve/module/math/regular/pow_abs.hpp @@ -36,7 +36,7 @@ namespace eve //! //! @brief Callable object computing the pow_abs function \f$|x|^y\f$. //! -//! **Defined in Header** +//! @groupheader{Header file} //! //! @code //! #include @@ -47,53 +47,53 @@ namespace eve //! @code //! namespace eve //! { -//! template< eve::floating_value T, eve::floating_value U > -//! auto pow_absm1(T x, U y) noexcept; +//! // Regular overload +//! constexpr auto powm1(value auto x, value auto y) noexcept; // 1 +//! +//! // Lanes masking +//! constexpr auto powm1[conditional_expr auto c](value auto x, value auto y) noexcept; // 2 +//! constexpr auto powm1[logical_value auto m](value auto x, value auto y) noexcept; // 2 +//! +//! // Semantic options +//! constexpr auto powm1[raw](value auto x, value auto y) noexcept; // 3 //! } //! @endcode //! //! **Parameters** //! +//! * `x`, `y`: [value](@ref value) arguments. +//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation. +//! * `m`: [Logical value](@ref logical) masking the operation. //! //! **Return value** //! //! Returns [elementwise](@ref glossary_elementwise) \f$|x|^y\f$. //! -//! The result type is the [common type](@ref common_value_t) of the two parameters. -//! In particular we have (IEC 60559) for floating entries: -//! -//! * pow_abs(\f$\pm0\f$, y), where y is a negative odd integer, returns \f$+\infty\f$. -//! * pow_abs(\f$\pm0\f$, y), where y is negative, finite, and is an even integer or a -//! non-integer, returns \f$+\infty\f$. -//! * pow_abs(\f$\pm0\f$, \f$-\infty\f$) returns \f$+\infty\f$. -//! * pow_abs(\f$\pm0\f$, y), where y is a positive odd integer, returns \f$+0\f$. -//! * pow_abs(\f$\pm0\f$, y), where y is positive non-integer or a positive even integer, returns -//! \f$+0\f$. -//! * pow_abs(-1, \f$\pm\infty\f$) returns 1. -//! * pow_abs(\f$\pm1\f$, y) returns 1 for any y, even when y is NaN. -//! * pow_abs(x, \f$\pm0\f$) returns 1 for any x, even when x is NaN. -//! * pow_abs(x, \f$-\infty\f$) returns \f$+\infty\f$ for any |x| `<` 1. -//! * pow_abs(x, \f$-\infty\f$) returns \f$+0\f$ for any |x| `>` 1. -//! * pow_abs(x, \f$+\infty\f$) returns \f$+0\f$ for any |x| `<` 1. -//! * pow_abs(x, \f$+\infty\f$) returns \f$+\infty\f$ for any |x| `>` 1. -//! * pow_abs(\f$+\infty\f$, y) returns \f$+0\f$ for any negative y. -//! * pow_abs(\f$+\infty\f$, y) returns \f$+\infty\f$ for any positive y. -//! * except where specified above, if any argument is NaN, NaN is returned. +//! 1. The result type is the [common type](@ref common_value_t) of the two parameters. +//! In particular we have (IEC 60559) for floating entries: +//! +//! * pow_abs(\f$\pm0\f$, y), where y is a negative odd integer, returns \f$+\infty\f$. +//! * pow_abs(\f$\pm0\f$, y), where y is negative, finite, and is an even integer or a +//! non-integer, returns \f$+\infty\f$. +//! * pow_abs(\f$\pm0\f$, \f$-\infty\f$) returns \f$+\infty\f$. +//! * pow_abs(\f$\pm0\f$, y), where y is a positive odd integer, returns \f$+0\f$. +//! * pow_abs(\f$\pm0\f$, y), where y is positive non-integer or a positive even integer, returns +//! \f$+0\f$. +//! * pow_abs(-1, \f$\pm\infty\f$) returns 1. +//! * pow_abs(\f$\pm1\f$, y) returns 1 for any y, even when y is NaN. +//! * pow_abs(x, \f$\pm0\f$) returns 1 for any x, even when x is NaN. +//! * pow_abs(x, \f$-\infty\f$) returns \f$+\infty\f$ for any |x| `<` 1. +//! * pow_abs(x, \f$-\infty\f$) returns \f$+0\f$ for any |x| `>` 1. +//! * pow_abs(x, \f$+\infty\f$) returns \f$+0\f$ for any |x| `<` 1. +//! * pow_abs(x, \f$+\infty\f$) returns \f$+\infty\f$ for any |x| `>` 1. +//! * pow_abs(\f$+\infty\f$, y) returns \f$+0\f$ for any negative y. +//! * pow_abs(\f$+\infty\f$, y) returns \f$+\infty\f$ for any positive y. +//! * except where specified above, if any argument is NaN, NaN is returned. +//! 2. [The operation is performed conditionnaly](@ref conditional) +//! 3. faster but less accurate call. //! //! @groupheader{Example} -//! //! @godbolt{doc/math/regular/pow_abs.cpp} -//! -//! @groupheader{Semantic Modifiers} -//! -//! * Masked Call -//! -//! The call `eve::pow_abs[mask](x, y)` provides a masked version of `eve::pow_abs` which is -//! equivalent to `if_else (mask, pow_abs(x, y), x)`. -//! -//! **Example** -//! -//! @godbolt{doc/math/masked/pow_abs.cpp} //! @} //================================================================================================ inline constexpr auto pow_abs = functor; diff --git a/include/eve/module/math/regular/powm1.hpp b/include/eve/module/math/regular/powm1.hpp index 040f98d463..10225a6dff 100644 --- a/include/eve/module/math/regular/powm1.hpp +++ b/include/eve/module/math/regular/powm1.hpp @@ -37,7 +37,7 @@ namespace eve //! //! @brief Callable object computing powm1: \f$x^y-1\f$. //! -//! **Defined in Header** +//! @groupheader{Header file} //! //! @code //! #include @@ -48,34 +48,33 @@ namespace eve //! @code //! namespace eve //! { -//! template< eve::floating_value T, eve::floating_value U > -//! auto powm1(T x, U y) noexcept; +//! // Regular overload +//! constexpr auto powm1(value auto x, value auto y) noexcept; // 1 +//! +//! // Lanes masking +//! constexpr auto powm1[conditional_expr auto c](value auto x, value auto y) noexcept; // 2 +//! constexpr auto powm1[logical_value auto m](value auto x, value auto y) noexcept; // 2 +//! +//! // Semantic options +//! constexpr auto powm1[raw](value auto x, value auto y) noexcept; // 3 //! } //! @endcode //! //! **Parameters** //! -//!`x`, `y`: [floating real values](@ref eve::floating_ordered_value). +//! * `x`, `y`: [integral value](@ref integral_value) arguments. +//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation. +//! * `m`: [Logical value](@ref logical) masking the operation. //! //! **Return value** //! -//! Returns the [elementwise](@ref glossary_elementwise) power minus one, with good accuracy, -//! even when `y` is very small, or when `x` is close to 1. +//! 1. Returns the [elementwise](@ref glossary_elementwise) power minus one, with good accuracy, +//! even when `y` is very small, or when `x` is close to 1. +//! 2. [The operation is performed conditionnaly](@ref conditional) +//! 3. faster but less accurate call. //! //! @groupheader{Example} -//! //! @godbolt{doc/math/regular/powm1.cpp} -//! -//! @groupheader{Semantic Modifiers} -//! -//! * Masked Call -//! -//! The call `eve::powm1[mask](x, y)` provides a masked version of `eve::powm1` which is -//! equivalent to `if_else (mask, powm1(x, y), x)`. -//! -//! **Example** -//! -//! @godbolt{doc/math/masked/powm1.cpp} //! @} //================================================================================================ inline constexpr auto powm1 = functor;