add

eve::add = functor<add_t>

inlineconstexpr

Header file

#include <eve/module/core.hpp>

Callable Signatures

namespace eve
{
   // Regular overloads
   constexpr auto add(value auto x, value auto ... xs)                          noexcept; // 1
   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
   constexpr auto add[logical_value auto m](/*any of the above overloads*/)     noexcept; // 3
 
   // Semantic options
   constexpr auto add[saturated](/*any of the above overloads*/)                noexcept; // 4
   constexpr auto add[lower](/*any of the above overloads*/)                    noexcept; // 5
   constexpr auto add[upper](/*any of the above overloads*/)                    noexcept; // 6
   constexpr auto add[lower][strict](/*any of the above overloads*/)            noexcept; // 5
   constexpr auto add[upper][strict](/*any of the above overloads*/)            noexcept; // 6
   constexpr auto add[widen](/*any of the above overloads*/)                    noexcept; // 7
   constexpr auto add[to_nearest_odd](/*any of the above overloads*/)           noexcept; // 8
   constexpr auto add[mod = p](/*any of the above overloads*/)                  noexcept; // 9
   constexpr auto add[kahan](/*any of the above overloads*/)                    noexcept; // 10
}

Parameters

• x, ...xs: real arguments.
• tup: non empty tuple of arguments.
• c: Conditional expression masking the operation.
• m: Logical value masking the operation.
• p: modulo p operation. p must be flint less than maxflint.

Return value

The value of the sum of the arguments is returned.

1. Take care that for floating entries, the addition is not perfectly associative due to rounding errors. This call performs additions in reverse incoming order. If you have not changed the processor rounding mode, round toward nearest mode tie to even is generally performed on standard systems.
2. equivalent to the call on the elements of the tuple.
3. The operation is performed conditionnaly
4. The call add[saturated](...) computes a saturated version of add. Take care that for signed integral entries this kind of addition is not associative at all. This call perform saturated additions in reverse incoming order.
5. The summation is computed in a round toward \(-\infty\) mode. The result is guaranted to be less or equal to the exact one (except for Nans). Combined with strict the option ensures generally faster computation, but strict inequality.
6. The summation is computed in a round toward \(\infty\) mode. The result is guaranted to be greater or equal to the exact one (except for Nans). Combined with strict the option ensures generally faster computation, but strict inequality.
7. The summation is computed in the double sized element type (if available). This decorator has no effect on double and 64 bits integrals.
8. The summation is computed in a round toward nearest mode but tie to odd (not hardware available on common systems).
9. compute the result in modular arithmetic. the parameters must be floating positive and less than the modulus. The modulus itself must be less than maxflint.
10. A kahan like summation is performed ensuring better accuracy, using two-add function. If the x, ...xs parameter are assumed positive and non increasing (or at least with non increasing exponents) adding raw option can speed a bit the accurate summation,

Note

• Although the infix notation with + is supported for two parameters, the + operator on standard scalar types is the original one and so can lead to automatic promotion.
• add has many options. The regular user will only be interested with saturated, unless it has to deal with uncommon accuracy or order properties requirements whose enforcement can have an heavy cost even if hardware fma-like processor intrinsics are available.

External references

{kahan summation](https://en.wikipedia.org/wiki/Kahan_summation_algorithm)

Example

// revision 0
#include <eve/module/core.hpp>
#include <iostream>
#include <iomanip>
#include <cfenv>
 
 
int main()
{
  eve::wide wf0{1.0f, 1.0f, 2.0f, 3.0f, -1.0f, -2.0f, -3.0f, -4.0f};
  eve::wide wf1{eve::eps(eve::as(1.0f))/4, -eve::eps(eve::as(1.0f))/4, 1.0f, -1.0f, 2.0f, -2.0f, 3.0f, -3.0f};
  eve::wide wi0{0, 1, 2, 3, -1, -2, -3, -4};
  eve::wide wi1{0, -4, 1, -1, 2, -2, 3, -3};
  eve::wide<std::uint16_t, eve::fixed<8>> wu0{65534u, 65000u, 2u, 3u, 4u, 5u, 6u, 7u};
  eve::wide<std::uint16_t, eve::fixed<8>> wu1{2u, 6u, 5u, 4u, 3u, 2u, 1u, 0u};
 
  std::cout << std::setprecision(16) << "<- wf0                           = " << wf0 << "\n";
  std::cout << std::setprecision(16) << "<- wf1                           = " << wf1 << "\n";
  std::cout << "<- wi0                           = " << wi0 << "\n";
  std::cout << "<- wi1                           = " << wi1 << "\n";
  std::cout << "<- wu0                           = " << wu0 << "\n";
  std::cout << "<- wu1                           = " << wu1 << "\n";
 
  std::cout << "-> add(wf0, wf1)                 = " << eve::add(wf0, wf1) << "\n";
  std::cout << "-> add[ignore_last(2)](wf0, wf1) = " << eve::add[eve::ignore_last(2)](wf0, wf1) << "\n";
  std::cout << "-> add[wf0 != 0](wf0, wf1)       = " << eve::add[wf0 != 0](wf0, wf1) << "\n";
  std::cout << "-> add(wu0, wu1)                 = " << eve::add(wu0, wu1) << "\n";
  std::cout << "-> add(wi0, wi1)                 = " << eve::add(wi0, wi1) << "\n";
 
  std::cout << std::setprecision(16) << "-> add(wf0, wf1)                  = " << eve::add(wf0, wf1) << "\n";
  std::cout << std::setprecision(16) << "-> add[to_nearest_odd(wf0, wf1)   = " << eve::add(wf0, wf1) << "\n";
  std::cout << std::setprecision(16) << "-> add[lower](wf0, wf1)           = " << eve::add[eve::lower](wf0, wf1) << "\n";
  std::cout << std::setprecision(16) << "-> add[upper](wf0, wf1)           = " << eve::add[eve::upper](wf0, wf1) << "\n";
  std::cout << std::setprecision(16) << "-> add[lower][strict](wf0, wf1)   = " << eve::add[eve::lower][eve::strict](wf0, wf1) << "\n";
  std::cout << std::setprecision(16) << "-> add[upper][strict](wf0, wf1)   = " << eve::add[eve::upper][eve::strict](wf0, wf1) << "\n";
 
  std::cout << "-> add(wu0, wu1)                 = " << eve::add(wu0, wu1) << "\n";
  std::cout << "-> add[widen](wu0, wu1)          = " << eve::add[eve::widen](wu0, wu1) << "\n";
  std::cout << "-> add(wf0, wf1)                 = " << eve::add(wf0, wf1) << "\n";
  std::cout << "-> add[widen](wf0, wf1)          = " << eve::add[eve::widen](wf0, wf1) << "\n";
  auto eps_4 = eve::eps(eve::as<float>())/4;
  std::cout << "-> add(1.0f, eps_4, eps_4, eps_4, eps_4)          = " << eve::add(1.0f, eps_4, eps_4, eps_4, eps_4) << "\n";
  std::cout << "-> add[kahan](1.0f, eps_4, eps_4, eps_4, eps_4)   = " << eve::add[eve::kahan](1.0f, eps_4, eps_4, eps_4, eps_4) << "// float result\n";
  std::cout << "-> add(1.0f, eps_4, eps_4, eps_4, eps_4)          = " << eve::add(1.0f, eps_4, eps_4, eps_4, eps_4) << "\n";
  std::cout << "-> add[widen](1.0f, eps_4, eps_4, eps_4, eps_4)   = " << float(eve::add[eve::widen](1.0f, eps_4, eps_4, eps_4, eps_4)) << "// double result converted to float\n";
  auto tup = kumi::tuple{1.0f, eps_4, eps_4, eps_4, eps_4};
  std::cout << "-> add[kahan](tup)   = " << eve::add[eve::kahan](tup) << "\n";
 
 
}