libs/histogram/doc/concepts/Accumulator.qbk

   1 [/
   2             Copyright Hans Dembinski 2018 - 2019.
   3    Distributed under the Boost Software License, Version 1.0.
   4       (See accompanying file LICENSE_1_0.txt or copy at
   5             https://www.boost.org/LICENSE_1_0.txt)
   6 ]
   7
   8 [section:Accumulator Accumulator]
   9
  10 An [*Accumulator] is a functor which consumes the argument to update some internal state. The state can be read with member functions or free functions. Must be [@https://en.cppreference.com/w/cpp/named_req/DefaultConstructible DefaultConstructible], [@https://en.cppreference.com/w/cpp/named_req/CopyConstructible CopyConstructible], and [@https://en.cppreference.com/w/cpp/named_req/CopyAssignable CopyAssignable].
  11
  12 [heading Required features]
  13
  14 * `A` is a type meeting the requirements of [*Accumulator]
  15 * `a` and `b` are values of type `A`
  16 * `ts...` is a pack of values of arbitrary types
  17
  18 [table Valid expressions
  19 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  20 [
  21   [`a(ts...)` or `++a`]
  22   []
  23   [
  24     Either a call operator accepting a fixed number of arguments must be implemented, or the pre-increment operator. The call operator may not be templated and not overloaded, except to support weights as described under optional features.
  25   ]
  26 ]
  27 [
  28   [`a == b`]
  29   [`bool`]
  30   [
  31     Returns `true` if all state variables compare equal. Otherwise returns `false`.
  32   ]
  33 ]
  34 [
  35   [`a != b`]
  36   [`bool`]
  37   [
  38     Must be implemented if `a == b` is implemented and must be equal to `!(a == b)`.
  39   ]
  40 ]
  41 ]
  42
  43 [heading Optional features]
  44
  45 * `A` is a type meeting the requirements of [*Accumulator]
  46 * `a` and `b` are values of type `A`
  47 * `w` is a value of type [classref boost::histogram::weight_type], where `T` is a number type
  48 * `ts...` is a pack of values of arbitrary types
  49 * `v` is a number value (integral or floating point)
  50
  51 [table Valid expressions
  52 [[Expression] [Return] [Semantics, Pre/Post-conditions]]
  53 [
  54   [`a += v` or `a(w, ts...)`]
  55   []
  56   [
  57     Does a weighted fill of the accumulator. Use this to implement weight support for an accumulator that is normally filled with `++a` or `a(ts...)`, respectively. Only the corresponding matching form may be implemented: `a += v` for `++a`, `a(w, ts...)` for `a(ts...)`. The implementations may not be templated and not overloaded.
  58   ]
  59 ]
  60 [
  61   [`a += b`]
  62   [`A&`]
  63   [
  64     Adds a second accumulator `b` of type `A`. The result must be the same as if `a` had been filled with all arguments of `b`.
  65   ]
  66 ]
  67 [
  68   [`a *= x`]
  69   [`A&`]
  70   [
  71     Scales the accumulator state by the real value `x`. The result must be the same as if `a` had been filled with all arguments scaled by `x`.
  72   ]
  73 ]
  74 [
  75   [`os << a`]
  76   [`std::basic_ostream<CharT, Traits>&`]
  77   [
  78     `os` is a value of type `std::basic_ostream<CharT, Traits>`. Streams a text representation of the axis. May not mutate `a`.
  79   ]
  80 ]
  81 [
  82   [`a.serialize(ar, n)`]
  83   []
  84   [
  85     `ar` is a value of an archive with Boost.Serialization semantics and `n` is an unsigned integral value. Saves to the archive or loads serialized state from the archive. The version number `n` is the stored version when the object is loaded or the current version when the object is saved.
  86   ]
  87 ]
  88 ]
  89
  90 [heading Models]
  91
  92 * [classref boost::histogram::accumulators::sum]
  93 * [classref boost::histogram::accumulators::weighted_sum]
  94 * [classref boost::histogram::accumulators::mean]
  95 * [classref boost::histogram::accumulators::weighted_mean]
  96
  97 [endsect]