Skip to content

Commit

Permalink
Documentation for D functions
Browse files Browse the repository at this point in the history
  • Loading branch information
@jtlap
jtlap authored Jun 29, 2024
1 parent 05c4bff commit 3cf352d
Show file tree
Hide file tree
Showing 13 changed files with 221 additions and 141 deletions.
4 changes: 3 additions & 1 deletion include/eve/module/combinatorial/regular/bernouilli.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,10 @@ namespace eve
//! 1. The value of the nth Bernouilli number is returned.
//! 2. [The operation is performed conditionnaly](@ref conditional).
//!
//! @groupheader{Example}
//! @groupheader{External references}
//! * [Wolfram MathWorld](https://mathworld.wolfram.com/BernoulliNumber.html)
//!
//! @groupheader{Example}
//! @godbolt{doc/combinatorial/regular/bernouilli.cpp}
//! @}
//================================================================================================
Expand Down
2 changes: 1 addition & 1 deletion include/eve/module/core/regular/add.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ namespace eve
//! {
//! // Regular overloads
//! constexpr auto add(value auto x, value auto ... xs) noexcept; // 1
//! constexpr auto absmin(kumi::non_empty_product_type auto const& tup) noexcept; // 2
//! constexpr auto add(kumi::non_empty_product_type auto const& tup) noexcept; // 2
//!
//! // Lanes masking
//! constexpr auto add[conditional_expr auto c](/*any of the above overloads*/) noexcept; // 3
Expand Down
40 changes: 18 additions & 22 deletions include/eve/module/core/regular/dec.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ namespace eve
//! @addtogroup core_arithmetic
//! @{
//! @var dec
//! @brief return the input decremented by 1.
//! @brief `elementwise_callable` object returning the input decremented by 1.
//!
//! **Defined in Header**
//! @groupheader{Header file}
//!
//! @code
//! #include <eve/module/core.hpp>
Expand All @@ -40,37 +40,33 @@ namespace eve
//! @code
//! namespace eve
//! {
//! template< eve::value T >
//! T dec(T x) noexcept;
//! // Regular overload
//! constexpr auto dec(value auto x) noexcept; // 1
//!
//! // Lanes masking
//! constexpr auto dec[conditional_expr auto c](value auto x) noexcept; // 2
//! constexpr auto dec[logical_value auto m](value auto x) noexcept; // 2
//!
//! // Semantic options
//! constexpr auto dec[saturated](value auto x) noexcept; // 3
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `x` : [real](@ref eve::value) argument.
//! * `x`: [SIMD or scalar value](@ref value).
//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation.
//! * `m`: [Logical value](@ref logical) masking the operation.
//!
//! **Return value**
//!
//! The value of `x - 1` is returned.
//! 1. The value of `x - 1` is returned.
//! 2. [The operation is performed conditionnaly](@ref conditional).
//! 3. The saturated decrementation of `x`. More specifically, for signed
//! integral, `abs[saturated](valmin(as<T>{}))` returns `eve:valmin(as<T>{}))`
//!
//! @groupheader{Example}
//!
//! @godbolt{doc/core/dec.cpp}
//!
//! @groupheader{Semantic Modifiers}
//!
//! * Masked Call
//!
//! The call `eve::dec[mask](x, ...)` provides a masked
//! version of `dec` which is
//! equivalent to `if_else(mask, dec(x, ...), x)`
//!
//! * eve::saturated
//!
//! The call `saturated(dec)(x)` computes the saturated decrement of `x`.
//! The only interest of this behaviour is that
//! for integral type T the call `saturated(dec)(Valmin<T>())` returns `Valmin<T>()`.
//!
//! @}
//================================================================================================
inline constexpr auto dec = functor<dec_t>;
Expand Down
45 changes: 21 additions & 24 deletions include/eve/module/core/regular/diff_of_prod.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,10 @@ namespace eve
//! @addtogroup core_accuracy
//! @{
//! @var diff_of_prod
//! @brief Computes the difference of products operation with better accuracy
//! @brief `elementwise_callable` object computing the difference of products operation with better accuracy
//! than the naive formula.
//!
//! **Defined in Header**
//! @groupheader{Header file}
//!
//! @code
//! #include <eve/module/core.hpp>
Expand All @@ -46,39 +46,36 @@ namespace eve
//! @code
//! namespace eve
//! {
//! template< eve::floating_value T
//! , eve::floating_value U
//! , eve::floating_value V
//! , eve::floating_value W>
//! T diff_of_prod(T x, U y, V z, W t ) noexcept;
//! // Regular overload
//! constexpr auto diff_of_prod(floating_value auto x, floating_value auto y,
//! floating_value auto z, floating_value auto t) noexcept; // 1
//!
//! // Lanes masking
//! constexpr auto diff_of_prod[conditional_expr auto c](floating_value auto x, floating_value auto y,
//! floating_value auto z, floating_value auto t) noexcept; // 2
//!
//! // Semantic exclusive options
//! constexpr auto diff_of_prod[raw](floating_value auto x, floating_value auto y,
//! floating_value auto z, floating_value auto t) noexcept; // 3
//! constexpr auto diff_of_prod[pedantic](floating_value auto x, floating_value auto y,
//! floating_value auto z, floating_value auto t) noexcept; // 4
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `x`, `y`, `z`, `t`: [floating value arguments](@ref eve::floating_value).
//! * `x`, `y`, `z`, `t`: [floating values](@ref floating_value).
//!
//! **Return value**
//!
//! The value of `x*y-z*t`, with better precision if correct fma is available,
//! is returned.
//! 1. The value of `x*y-z*t`, with better precision if correct fma is available,
//! is returned.
//! 2. [The operation is performed conditionnaly](@ref conditional).
//! 3. computes a raw version of diff_of_prod, i.e. the naive formula (in fact `fms(x, y, z*t)`)
//! 4. computes a pedantic version of `diff_of_prod` ensuring better accuracy in any case.
//!
//! @groupheader{Example}
//!
//! @godbolt{doc/core/diff_of_prod.cpp}
//!
//! @groupheader{Semantic Modifiers}
//!
//! * eve::raw
//!
//! The call `eve::raw(eve::diff_of_prod)(x, y, z, t)` computes a raw
//! version of eve::diff_of_prod, i.e. the naive formula (in fact `fms(x, y, z, t)`)
//!
//! * eve::pedantic
//!
//! The call `eve::pedantic(eve::diff_of_prod)(x, y, z, t)` computes a pedantic
//! version of eve::diff_of_prod ensuring better accuracy in any case.
//!
//! @}
//================================================================================================
inline constexpr auto diff_of_prod = functor<diff_of_prod_t>;
Expand Down
45 changes: 23 additions & 22 deletions include/eve/module/core/regular/dist.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ namespace eve
//! @addtogroup core_arithmetic
//! @{
//! @var dist
//! @brief Computes the distance of its arguments.
//! @brief `elementwise_callable` object computing the distance of its arguments.
//!
//! **Defined in Header**
//! @groupheader{Header file}
//!
//! @code
//! #include <eve/module/core.hpp>
Expand All @@ -48,37 +48,38 @@ namespace eve
//! @code
//! namespace eve
//! {
//! template< eve::value T, eve::value U >
//! eve::common_value_t<T, U> dist(T x, U y) noexcept;
//! // Regular overloads
//! constexpr auto dist(eve::value auto x, eve::value auto y) noexcept; // 1
//!
//! // Lanes masking
//! constexpr auto dist[conditional_expr auto c](eve::value auto x, eve::value auto y) noexcept; // 2
//! constexpr auto dist[logical_value auto m](eve::value auto x, eve::value auto y) noexcept; // 2
//!
//! // Semantic options
//! constexpr auto dist[saturated](eve::value auto x, eve::value auto y) noexcept; // 3
//! constexpr auto dist[pedantic](eve::value auto x, eve::value auto y) noexcept; // 4
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `x`, `y` : [real](@ref eve::value) arguments.
//! * `x`, `y`: [values](@ref value).
//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation.
//! * `m`: [Logical value](@ref logical) masking the operation.
//!
//! **Return value**
//!
//! The value of the distance of the arguments is returned, i.e. `eve::abs (x-y)`.
//! 1. The value of the distance of the arguments is returned, i.e. `abs (x-y)`.
//! 2. [The operation is performed conditionnaly](@ref conditional).
//! 3. The call `dist[saturated](x, y)` computes a saturated distance.
//! Contrary to the non decorated case, it guarantees
//! that the result is always defined. If \f$|x-y|\f$ is not representable,
//! [the greatest representable positive value](@ref valmax) is returned.
//! 4. `dist[pedantic](x, y)`computes a distance wich is `NaN` if and only
//! if one of the parameters is a `NaN`.
//!
//! @groupheader{Example}
//!
//! @godbolt{doc/core/dist.cpp}
//!
//! @groupheader{Semantic Modifiers}
//!
//! * eve::saturated
//!
//! The call `saturated(dist)(x, y)` computes a saturated distance.
//! Contrary to the non decorated case, it guarantees
//! that the result is always defined. If \f$|x-y|\f$ is not representable
//! [the greatest representable positive value](@ref eve::valmax) is returned.
//!
//! * eve::pedantic
//!
//! The call `pedantic(dist)(x, y)` computes a distance wich is nan if and only
//! if a or b is a Nan.
//!
//! @}
//================================================================================================
inline constexpr auto dist = functor<dist_t>;
Expand Down
77 changes: 39 additions & 38 deletions include/eve/module/core/regular/div.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,9 @@ namespace eve
//! @addtogroup core_arithmetic
//! @{
//! @var div
//! @brief Computes the division of multiple values.
//! @brief `elementwise_callable` object computing the division of multiple values.
//!
//! **Defined in Header**
//! @groupheader{Header file}
//!
//! @code
//! #include <eve/module/core.hpp>
Expand All @@ -50,19 +50,52 @@ namespace eve
//! @code
//! namespace eve
//! {
//! template< eve::value... Ts >
//! eve::common_value_t<T, Ts ...> div(Ts ... xs) noexcept;
//! // Regular overloads
//! constexpr auto div(value auto x, value auto ... xs) noexcept; // 1
//! constexpr auto div(kumi::non_empty_product_type auto const& tup) noexcept; // 2
//!
//! // Lanes masking
//! constexpr auto div[conditional_expr auto c](/*any of the above overloads*/) noexcept; // 3
//! constexpr auto div[logical_value auto m](/*any of the above overloads*/) noexcept; // 3
//!
//! // Semantic exclusive options
//! constexpr auto div[upward](/*any of the above overloads*/) noexcept; // 4
//! constexpr auto div[downward](/*any of the above overloads*/) noexcept; // 4
//! constexpr auto div[toward_zero](/*any of the above overloads*/) noexcept; // 4
//! constexpr auto div[to_nearest](/*any of the above overloads*/) noexcept; // 4
//!
//! // Semantic options
//! constexpr auto div[saturated](integral_value auto x, integral_value auto y)) noexcept; // 5
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `xs ...` : [real](@ref eve::value) arguments.
//! * `x`, `...xs`: [real](@ref value) arguments.
//! * `tup`: [non empty tuple](@ref kumi::non_empty_product_type) of arguments.
//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation.
//! * `m`: [Logical value](@ref logical) masking the operation.
//!
//! **Return value**
//!
//! If the arguments are \f$(x_i)_{0\le i\le n}\f$ The value of \f$x/\prod_1^n x_i\f$
//! 1. If the arguments are \f$(x_i)_{0\le i\le n}\f$ The value of \f$x/\prod_1^n x_i\f$
//! is returned.
//! 2. equivalent to the call on the elements of the tuple.
//! 3. [The operation is performed conditionnaly](@ref conditional)
//! 4. If `z` denotes the prduct of the `xs`, the call `div[o](x, xs...)` produces:
//!
//! * `eve::trunc(div(x, z))`, if `d` is `toward_zero`.
//! * `eve::floor(div(x, z))`, if `d` is `downward`.
//! * `eve::ceil(div(x, z))`, if `d` is `upward`.
//! * `eve::nearest(div(x, z))`, if `d` is `to_nearest`.
//! 5. computes the saturated division of `x` by `y`.
//! The result is always defined even if the denominator is 0.
//!
//! The relevant cases are just in fact the division by 0 for integral types
//! in which case the result is [`eve::valmin(as(x))`](@ref valmin) or
//! [`valmax(as(x))`](ref eve::valmax) according to the dividend sign, and
//! the division of [`valmin(as(x))`](@ref valmin)
//! by -1 that produces [`valmax(as(x))`](@ref valmax).
//!
//! @note
//! * With two parameters, the call `div(x, y)` is equivalent to `x / y`
Expand All @@ -73,39 +106,7 @@ namespace eve
//! standard scalar types is the original one and so can lead to automatic promotion.
//!
//! @groupheader{Example}
//!
//! @godbolt{doc/core/div.cpp}
//!
//! @groupheader{Semantic Modifiers}
//!
//! * Masked Call
//!
//! The call `eve::div[mask](x, ...)` provides a masked
//! version of `div` which is
//! equivalent to `if_else(mask, div(x, ...), x)`
//!
//! * eve::saturated
//!
//! The expression `eve::saturated(eve::div)(x, xs...)` computes the saturated
//! division of `x` by all `xs`. The result is semantically equivalent to
//! `saturated(div)(x, saturated(mul)(xs...))` but is always defined even if
//! the denominator is 0.
//!
//! The relevant cases are just in fact the division by 0 for integral types
//! in which case the result is [`eve::valmin(as(x))`](@ref eve::valmin) or
//! [`eve::valmax(as(x))`](ref eve::valmax) according to the dividend sign, and
//! the division of [`eve::valmin(as(x))`](@ref eve::valmin)
//! by -1 that produces [`eve::valmax(as(x))`](@ref eve::valmax).
//!
//! * eve::toward_zero, eve::downward, eve::upward, eve::to_nearest
//!
//! The calls `d(div)(x, y)` where d is one of these 4 decorators produce respectively
//!
//! * `eve::trunc (div(x, y))` for eve::toward_zero.
//! * `eve::floor (div(x, y))` for deve::downward.
//! * `eve::ceil (div(x, y))` for eve::upward.
//! * `eve::nearest (div(x,y))`for eve::to_nearest.
//!
//! @}
//================================================================================================
inline constexpr auto div = functor<div_t>;
Expand Down
4 changes: 2 additions & 2 deletions include/eve/module/core/regular/dot.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,11 @@ namespace eve
//! @addtogroup core_arithmetic
//! @{
//! @var dot
//! @brief Computes elementwise the dot product of the two parameters.
//! @brief `elementwise_callable` object computing elementwise the dot product of the two parameters.
//!
//! @warning This is not a reduction ! For reals the dot product is the product
//!
//! **Defined in Header**
//! @groupheader{Header file}
//!
//! @code
//! #include <eve/module/core.hpp>
Expand Down
23 changes: 15 additions & 8 deletions include/eve/module/math/regular/deginrad.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ namespace eve
//! @{
//! @var deginrad
//!
//! @brief Callable object multiplying the input by \f$\pi/180\f$.
//! @brief `elementwise_callable` object computing the product of the input by \f$\pi/180\f$.
//!
//! **Defined in Header**
//! @groupheader{Header file}
//!
//! @code
//! #include <eve/module/math.hpp>
Expand All @@ -40,18 +40,25 @@ namespace eve
//! @code
//! namespace eve
//! {
//! template< eve::floating_value T >
//! T deginrad(T x) noexcept;
//! // Regular overload
//! constexpr auto deginrad(value auto x) noexcept; // 1
//!
//! // Lanes masking
//! constexpr auto deginrad[conditional_expr auto c](value auto x) noexcept; // 2
//! constexpr auto deginrad[logical_value auto m](value auto x) noexcept; // 2
//! }
//! @endcode
//!
//! **Parameters**
//! **Parameters**
//!
//!`x`: [floating value](@ref eve::floating_value).
//! * `x`: [floating_value](@ref value).
//! * `c`: [Conditional expression](@ref conditional_expr) masking the operation.
//! * `m`: [Logical value](@ref logical) masking the operation.
//!
//! **Return value**
//! **Return value**
//!
//! Returns the [elementwise](@ref glossary_elementwise) the degree input converted in radian.
//! 1. Returns the [elementwise](@ref glossary_elementwise) the degree input converted in radian.
//! 2. [The operation is performed conditionnaly](@ref conditional).
//!
//! @groupheader{Example}
//!
Expand Down
Loading

0 comments on commit 3cf352d

Please sign in to comment.