libs/histogram/doc/concepts/Axis.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:Axis Axis]
   9
  10 An [*Axis] maps input values to indices. It holds state specific to that axis, like the number of bins and any metadata. Must be [@https://en.cppreference.com/w/cpp/named_req/CopyConstructible CopyConstructible], [@https://en.cppreference.com/w/cpp/named_req/CopyAssignable CopyAssignable], and *nothrow* [@https://en.cppreference.com/w/cpp/named_req/MoveAssignable MoveAssignable].
  11
  12 [heading Associated Types]
  13
  14 * [link histogram.concepts.DiscreteAxis [*DiscreteAxis]]
  15 * [link histogram.concepts.IntervalAxis [*IntervalAxis]]
  16
  17 [heading Required features]
  18
  19 * `A` is a type meeting the requirements of [*Axis]
  20 * `a` is a value of type `A`
  21 * `I` is an alias for [headerref boost/histogram/fwd.hpp `boost::histogram::axis::index_type`]
  22
  23 [table Valid expressions
  24 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  25 [
  26   [`a.size()`]
  27   [`I`]
  28   [
  29     Const member function which returns the number of bins of the axis. All indices from `0` to `a.size() - 1` must be valid and address a bin of the axis.
  30   ]
  31 ]
  32 [
  33   [`a.index(v)`]
  34   [`I`]
  35   [
  36     Const member function which maps a value `v` to an index. The mapping must be injective: each value must be uniquely mapped to one index. If the value is not covered by the axis, return either `-1` or `a.size()`. The value `-1` indicates that the value is lower than the lowest value covered by the axis. The value `a.size()` indicates that the value is above the uppermost value covered by the axis. By convention, /NaN/-values are mapped to `a.size()`.
  37   ]
  38 ]
  39 [
  40   [`a.get_allocator()`]
  41   [`Alloc`]
  42   [
  43     Const member function which returns the allocator `Alloc` used by this axis. May be omitted if `A` does not use allocators. If this member function exists, also a special constructor must exists so that `A(a.get_allocator())` is a valid expression.
  44   ]
  45 ]
  46 ]
  47
  48 [heading Optional features]
  49
  50 * `A` is a type meeting the requirements of [*Axis]
  51 * `a` and `b` are values of type `A`
  52 * `i` and `j` are indices of type [headerref boost/histogram/fwd.hpp `boost::histogram::axis::index_type`]
  53 * `M` is a metadata type that is [@https://en.cppreference.com/w/cpp/named_req/CopyConstructible CopyConstructible] and [@https://en.cppreference.com/w/cpp/named_req/CopyAssignable CopyAssignable] and *nothrow* [@https://en.cppreference.com/w/cpp/named_req/MoveAssignable MoveAssignable].
  54
  55 [table Valid expressions
  56 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  57 [
  58   [`a.update(v)`]
  59   [`std::pair<I, I>`]
  60   [
  61     Non-const member function which maps a value to an index (first argument of the returned pair) and offset (second argument of the returned pair). If the value is not covered by the axis, this method may grow the current axis size (`old_size`) by the number of bins needed to contain the value or more (`new_size`). If the value is below the lowest value covered by the axis, return index `0` and offset `new_size - old_size`. If the value is above the uppermost value covered by the axis, return index `new_size - 1` and a negative offset `old_size - new_size`. If the value is outside, but the axis is not enlarged, then return an index equivalent to  `a.index(v)` and offset `0`.
  62   ]
  63 ]
  64 [
  65   [`A(a, i, j, n)`]
  66   []
  67   [
  68     Special constructor used by the reduce algorithm. `a` is the original axis instance, `i` and `j` are the index range to keep in the reduced axis. If `n` is larger than 1, `n` adjacent bins are merged into one larger cell. If this constructor is not implemented, [funcref boost::histogram::algorithm::reduce] throws an exception on an attempt to reduce this axis.
  69   ]
  70 ]
  71 [
  72   [`a.options()`]
  73   [`unsigned`]
  74   [
  75     Static constexpr member function which returns the [headerref boost/histogram/axis/option.hpp axis options] for this axis.
  76   ]
  77 ]
  78 [
  79   [`a.inclusive()`]
  80   [`bool`]
  81   [
  82     Static constexpr member function which returns true, if the axis has a bin for every possible input value, and false otherwise. Faster code can be generated if all axes types in a histogram are inclusive. An axis with underflow and overflow bins is always inclusive. An axis may be inclusive even if underflow or overflow bins are missing. For example, a category axis is inclusive if it has an overflow bin or if it is growing.
  83   ]
  84 ]
  85 [
  86   [`a.metadata()`]
  87   [`const M&`]
  88   [
  89     Const member function which returns a const reference to the metadata associated with the axis (usually a string).
  90   ]
  91 ]
  92 [
  93   [`a.metadata()`]
  94   [`M&`]
  95   [
  96     Likewise, but non-const member function which returns a reference to the metadata. If this member function exists, also the previous one must exist.
  97   ]
  98 ]
  99 [
 100   [`a == b`]
 101   [`bool`]
 102   [
 103      Returns `true` if all state variables compare equal, including any metadata. Otherwise returns `false`. If `a == b` is implemented, also `a != b` must be implemented. If this binary operator is not implemented, the library considers the arguments equal, if and only if their types are the same.
 104   ]
 105 ]
 106 [
 107   [`a != b`]
 108   [`bool`]
 109   [
 110     Must be implemented if `a == b` is implemented and must be equal to `!(a == b)`.
 111   ]
 112 ]
 113 [
 114   [`os << a`]
 115   [`std::basic_ostream<CharT, Traits>&`]
 116   [
 117     `os` is a value of type `std::basic_ostream<CharT, Traits>`. Streams a text representation of the axis. May not mutate `a`.
 118   ]
 119 ]
 120 [
 121   [`a.serialize(ar, n)`]
 122   []
 123   [
 124     `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.
 125   ]
 126 ]
 127 ]
 128
 129 [heading Models]
 130
 131 * [classref boost::histogram::axis::category]
 132 * [classref boost::histogram::axis::integer]
 133 * [classref boost::histogram::axis::regular]
 134 * [classref boost::histogram::axis::variable]
 135
 136 [endsect]