libs/histogram/doc/concepts/DiscreteAxis.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:DiscreteAxis DiscreteAxis]
   9
  10 A [*DiscreteAxis] is one of two optional refinements of the [link histogram.concepts.Axis [*Axis]] concept, the other one is the [link histogram.concepts.IntervalAxis IntervalAxis]. This concept is for values that do not form intervals, and for axes with intervals that contain exactly one value.
  11
  12 [heading Associated Types]
  13
  14 * [link histogram.concepts.Axis [*Axis]]
  15 * [link histogram.concepts.IntervalAxis [*IntervalAxis]]
  16
  17 [heading Requirements]
  18
  19 * `A` is a type meeting the requirements of [*DiscreteAxis]
  20 * `a` is a value of type `A`
  21 * `V` is the type accepted for conversion into an index
  22 * `v` is a value of type `V`
  23 * `i` is a value of type [headerref boost/histogram/fwd.hpp `boost::histogram::axis::index_type`]
  24 * `AxisIter` is an /RandomAccessIterator/ over the bins of `A`
  25 * `ReAxisIter` is a reverse /RandomAccessIterator/ over the bins of `A`
  26
  27 [table Valid expressions
  28 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  29 [
  30   [`a.value(i)`]
  31   [`V`]
  32   [
  33     Const member function which maps an index to a value. The mapping must be injective: each index must be uniquely mapped to one value. The effect must be exactly the inverse of `a.index(v)`. The return value may be a const reference, if the lifetime of the referred object is equal to the lifetime of the axis.
  34   ]
  35 ]
  36 [
  37   [`a.bin(i)`]
  38   [`V`]
  39   [
  40     Must have the same effect as `a.value(i)`.
  41   ]
  42 ]
  43 [
  44   [`s.begin()`]
  45   [`AxisIter`]
  46   [
  47     Const member function which return an iterator to the bin with index `0`.
  48   ]
  49 ]
  50 [
  51   [`s.end()`]
  52   [`AxisIter`]
  53   [
  54     Const member function which returns an iterator to the bin with index `s.size()`.
  55   ]
  56 ]
  57 [
  58   [`s.rbegin()`]
  59   [`ReAxisIter`]
  60   [
  61     Const member function which return a reverse iterator to the bin with index `s.size()-1`.
  62   ]
  63 ]
  64 [
  65   [`s.rend()`]
  66   [`ReAxisIter`]
  67   [
  68     Const member function which returns an iterator to the bin with index `-1`.
  69   ]
  70 ]
  71 ]
  72
  73 [tip The complete iterator interface can be added to a user-defined axis which implements `a.bin(i)` by inheriting from the [classref boost::histogram::axis::iterator_mixin iterator_mixin].]
  74
  75 [heading Models]
  76
  77 * [classref boost::histogram::axis::category]
  78 * [classref boost::histogram::axis::integer], if first template parameter is [headerref boost/histogram/fwd.hpp `boost::histogram::index_type`]
  79
  80 [endsect]