average

eve::average = functor<average_t>

inlineconstexpr

Header file

#include <eve/module/core.hpp>

Callable Signatures

namespace eve
{
   // Regular overloads
   constexpr auto average(eve::integral_value auto x, eve::integral_value auto y)             noexcept; // 1
   constexpr auto average(eve::floating_value auto x, eve::floating_value auto ... xs)        noexcept; // 2
   constexpr auto average(kumi::non_empty_product_type auto const& tup)                       noexcept; // 3
 
   // Lanes masking
   constexpr auto average[conditional_expr auto c](/* any of the above overloads */)          noexcept; // 4
   constexpr auto average[logical_value auto m](/* any of the above overloads */)             noexcept; // 4
 
   // Semantic options
   constexpr auto average[raw] (/* any of the above overloads */)                             noexcept; // 5
   constexpr auto average[upper](eve::value auto x, eve::value auto y)                        noexcept; // 6
   constexpr auto average[lower](eve::value auto x, eve::value auto y)                        noexcept; // 7
   constexpr auto average[upper][strict](eve::value auto x, eve::value auto y)                noexcept; // 6
   constexpr auto average[lower][strict](eve::value auto x, eve::value auto y)                noexcept; // 7
   constexpr auto average[widen](/* any of the above overloads */)                            noexcept; // 8
   constexpr auto average[kahan](/* any of the above overloads */)                            noexcept; // 9
 
}

Parameters

• x, y: integral value arguments.
• xs...: floating value arguments.
• tup: non empty tuple of arguments.
• c: Conditional expression masking the operation.
• m: Logical value masking the operation.

Return value

The value of the arithmetic mean of the arguments is returned.

1. For two integral parameters half the sum of x and y. No overflow occurs. If the sum is odd, the result is a rounded value at a distance guaranteed to be less than or equal to 0.5 of the average floating value, but may differ by unity from the truncation given by (x+y)/2. Moreover, as some architectures provide simd intrinsics to perform the operation, the scalar results may differ by one unit from simd ones which are system dependent.

   However the dowward (respectively upward) options can be used to ensure the result is equivalent to the integral conversion of floor((x+y)/2), (respectively ceil((x+y)/2)).

2. the arithmetic mean of its arguments. No overflow occurs.
3. the arithmetic mean of the tuple arguments. No overflow occurs.
4. The operation is performed conditionnaly
5. No provision is made to avoid overflows for more than 2 parameters.
6. The average 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. For integral type entries, these are similar to ceil((x+y)/2), but converted to an integral value.
7. The average 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. For integral type entries, these are similar to floor((x+y)/2) but converted to an integral value.
8. The average is computed in the double sized element type (if available).
9. Compensated algorithm for better precision.

Note

unless raw option is used no spurious overflow can be obtained.

See also

`welford_average` for incremental or parallel average computations.

External references

• Wikipedia Mean

Example

// revision 0
#include <eve/module/core.hpp>
#include <iostream>
#include <iomanip>
 
int main()
{
  eve::wide wf0{0.0, 1.0, 2.0, 3.0, -1.0, -2.0, -3.0, 1.0};
  eve::wide wf1{0.0, -4.0, 1.0, -1.0, 2.0, -2.0, -eve::smallestposval(eve::as(1.0)), eve::smallestposval(eve::as(1.0))};
  eve::wide wi0{0, 1, 2, 3, -1, -2, -3, -4};
  eve::wide wi1{0, -4, 1, -1, 2, -2, 3, -3};
 
  std::cout << "<- wf0                                        = " << wf0 << "\n"; 
  std::cout << "<- wf1                                        = " << wf1 << "\n";
  std::cout << "<- wi0                                        = " << wi0 << "\n";
  std::cout << "<- wi1                                        = " << wi1 << "\n";
  std::cout << std::setprecision(15);
 
  std::cout << "-> average(wf0, wf1)                          = " << eve::average(wf0, wf1) << "\n";
  std::cout << "-> average(wi0, wi1)                          = " << eve::average(wi0, wi1) << "\n";
  std::cout << "-> average[ignore_last(2)](wi0, wi1)          = " << eve::average[eve::ignore_last(2)](wi0, wi1) << "\n";
  std::cout << "-> average[wi0 != 0](wi0, wi1)                = " << eve::average[wi0 != 0](wi0, wi1) << "\n";
  std::cout << "-> average[raw](wi0, wi1)                     = " << eve::average[eve::raw](wi0, wi1) << "\n";
  std::cout << "-> average[upper](wi0, wi1)                   = " << eve::average[eve::upper](wi0, wi1) << "\n";
  std::cout << "-> average[lower](wi0, wi1)                   = " << eve::average[eve::lower](wi0, wi1) << "\n";
  std::cout << "-> average[upper](wf0, wf1)                   = " << eve::average[eve::upper](wf0, wf1) << "\n";
  std::cout << "-> average[lower](wf0, wf1)                   = " << eve::average[eve::lower](wf0, wf1) << "\n";
  std::cout << "-> average[lower][strict](wf0, wf1)           = " << eve::average[eve::lower][eve::strict](wf0, wf1) << "\n";
  std::cout << "-> average[upper][strict](wf0, wf1)           = " << eve::average[eve::upper][eve::strict](wf0, wf1) << "\n";
  auto eps_2 = eve::eps(eve::as<float>())/2;
  std::cout << "-> average(1.0f, eps_2, eps_2, eps_2)         = " << eve::average(1.0f, eps_2, eps_2, eps_2) << "\n";
  std::cout << "-> average[kahan](1.0f, eps_2, eps_2, eps_2)  = " << eve::average[eve::kahan](1.0f, eps_2, eps_2, eps_2) << " // float computation\n";
  std::cout << "-> average[raw](1.0f, eps_2, eps_2, eps_2)    = " << eve::average[eve::raw](1.0f, eps_2, eps_2, eps_2) << "\n";
  auto deps_2 = double(eps_2);
  std::cout << "-> average(1.0, deps_2, deps_2, eps_2)        = " << float(eve::average[eve::kahan](1.0, deps_2, deps_2, deps_2)) << " // double computation converted to float\n";
  auto tup = kumi::tuple{1.0f, eps_2, eps_2, eps_2};
  std::cout << "-> average[kahan](tup)   = " << eve::average[eve::kahan](tup) << "\n";
 
}