libs/histogram/doc/concepts/IntervalAxis.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:IntervalAxis IntervalAxis]
   9
  10 A [*IntervalAxis] is one of two optional refinements of the [link histogram.concepts.Axis [*Axis]] concept, the other one is the [link histogram.concepts.DiscreteAxis DiscreteAxis]. It is for ordered values that form intervals with a well-defined lower and upper edge, and a center. Each bin represents an interval of values.
  11
  12 [heading Associated Types]
  13
  14 * [link histogram.concepts.Axis [*Axis]]
  15 * [link histogram.concepts.DiscreteAxis [*DiscreteAxis]]
  16
  17 [heading Requirements]
  18
  19 * `A` is a type meeting the requirements of [*IntervalAxis]
  20 * `a` is a value of type `A`
  21 * `V` is the type accepted for conversion into an index
  22 * `B` is the type that represents the bin interval
  23 * `v` is a value of type `V`
  24 * `i` is a value of type [headerref boost/histogram/fwd.hpp `boost::histogram::axis::index_type`]
  25 * `j` is a value of type [headerref boost/histogram/fwd.hpp `boost::histogram::axis::real_index_type`]
  26 * `AxisIter` is an /RandomAccessIterator/ over the bins of `A`
  27 * `ReAxisIter` is a reverse /RandomAccessIterator/ over the bins of `A`
  28
  29 [table Valid expressions
  30 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  31 [
  32   [`a.value(i)`]
  33   [`V`]
  34   [
  35     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 result of `a.value(a.index(v))` should agree to very high precision with `v` (the mapping may not be exact due to the finite precision of floating point computations). The return value may be a const reference, if the lifetime of the referred object is equal to the lifetime of the axis. `a.value(j)` is expected to return the lower edge of the bin, `a.value(j+1)` the upper edge, and `a.value(j + 0.5)` the center.
  36   ]
  37 ]
  38 [
  39   [`a.bin(i)`]
  40   [`B`]
  41   [
  42     Const member function which returns an instance that represents the current bin. Nothing about the type is required, but it is recommended that the type has the methods `B::lower()`, `B::upper()`, and `B::center()` similar to the types used by the builtin axis models. The return value may be a const reference, if the lifetime of the referred object is equal to the lifetime of the axis.
  43   ]
  44 ]
  45 [
  46   [`s.begin()`]
  47   [`AxisIter`]
  48   [
  49     Const member function which return an iterator to the bin with index `0`.
  50   ]
  51 ]
  52 [
  53   [`s.end()`]
  54   [`AxisIter`]
  55   [
  56     Const member function which returns an iterator to the bin with index `s.size()`.
  57   ]
  58 ]
  59 [
  60   [`s.rbegin()`]
  61   [`ReAxisIter`]
  62   [
  63     Const member function which return a reverse iterator to the bin with index `s.size()-1`.
  64   ]
  65 ]
  66 [
  67   [`s.rend()`]
  68   [`ReAxisIter`]
  69   [
  70     Const member function which returns an iterator to the bin with index `-1`.
  71   ]
  72 ]
  73 ]
  74
  75 [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].]
  76
  77 [heading Models]
  78
  79 * [classref boost::histogram::axis::regular]
  80 * [classref boost::histogram::axis::variable]
  81 * [classref boost::histogram::axis::integer], if first template parameter is a floating point type
  82
  83 [endsect]