libs/histogram/doc/concepts/Storage.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:Storage Storage]
   9
  10 A [*Storage] handles memory for the bin counters and provides a uniform vector-like interface for accessing cell values for reading and writing. 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 * `S` is a type meeting the requirements of [*Storage]
  15 * `s` is a  value of types `S`
  16 * `i` and `n` are values of type `std::size_t`
  17
  18 [table Valid expressions
  19 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
  20 [
  21   [`S::value_type`]
  22   []
  23   [
  24     Cell element type, may be either an integral type, floating-point type, or a type meeting the requirements of [link histogram.concepts.Accumulator [*Accumulator]].
  25   ]
  26 ]
  27 [
  28   [`S::reference`]
  29   []
  30   [
  31     `S::value_type&` or a proxy class which acts like a reference.
  32   ]
  33 ]
  34 [
  35   [`S::const_reference`]
  36   []
  37   [
  38     `const S::value_type&` or a proxy class which acts like a const reference. Implicitly convertible to `S::value_type`.
  39   ]
  40 ]
  41 [
  42   [`S::iterator`]
  43   []
  44   [
  45     Returns an STL-compliant iterator type which dereferences to `S::reference`.
  46   ]
  47 ]
  48 [
  49   [`S::const_iterator`]
  50   []
  51   [
  52     Returns an STL-compliant iterator type which dereferences to `S::const_reference`.
  53   ]
  54 ]
  55 [
  56   [`S::has_threading_support`]
  57   [bool]
  58   [
  59     Static constexpr member. True, if storage supports parallel read-write access to all cells.
  60     False, if such parallel access would either cause data corruption or require synchronization so that effectively only one cell can be accessed at a time, making cell-access single-threaded.
  61   ]
  62 ]
  63 [
  64   [`s.size()`]
  65   [`std::size_t`]
  66   [
  67     Const member function which returns the current number of cells in the storage.
  68   ]
  69 ]
  70 [
  71   [`s.reset(n)`]
  72   []
  73   [
  74     Non-const member function which discards current cell values, changes storage size to `n` and initializes all cells to the default-constructed state.
  75   ]
  76 ]
  77 [
  78   [`s.begin()`]
  79   [`S::iterator`]
  80   [
  81     Non-const member function which returns the iterator to the first storage cell.
  82   ]
  83 ]
  84 [
  85   [`s.begin()`]
  86   [`S::const_iterator`]
  87   [
  88     Likewise, but a const member function which returns the const_iterator.
  89   ]
  90 ]
  91 [
  92   [`s.end()`]
  93   [`S::iterator`]
  94   [
  95     Member function which returns the iterator to the cell after the last valid storage cell.
  96   ]
  97 ]
  98 [
  99   [`s.end()`]
 100   [`S::const_iterator`]
 101   [
 102     Likewise, but a const member function which returns the const_iterator.
 103   ]
 104 ]
 105 [
 106   [`s[i]`]
 107   [`S::reference`]
 108   [
 109     Member function which returns a reference to the cell which is addressed by `i`. The index `i` must be valid: `i < s.size()`.
 110   ]
 111 ]
 112 [
 113   [`s[i]`]
 114   [`S::const_reference`]
 115   [
 116     Likewise, but a const member function which returns a const reference.
 117   ]
 118 ]
 119 [
 120   [`s == t`]
 121   [`bool`]
 122   [
 123     `t` is another value of a type which meets the requirements of [*Storage]. Returns `true` if arguments have the same number of cells and all cells compare equal. Otherwise returns `false`.
 124   ]
 125 ]
 126 [
 127   [`s.get_allocator()`]
 128   [`Alloc`]
 129   [
 130     Const member function which returns the allocator `Alloc` used by `S`. May be omitted if `S` does not use allocators. If this member function exists, also a special constructor must exists so that `S(s.get_allocator())` is a valid expression.
 131   ]
 132 ]
 133 ]
 134
 135 [heading Optional features]
 136
 137 * `S` is a type meeting the requirements of [*Storage]
 138 * `s` is a  value of types `S`
 139 * `x` is convertible to `double`
 140 * `ar` is a value of an archive with Boost.Serialization semantics
 141
 142 [table Valid expressions
 143 [[Expression] [Returns] [Semantics, Pre/Post-conditions]]
 144 [
 145   [`s *= x`]
 146   [`S&`]
 147   [
 148     Scales all cell values by the factor `x` and returns a reference to self.
 149   ]
 150 ]
 151 [
 152   [`s.serialize(ar, n)`]
 153   []
 154   [
 155     `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.
 156   ]
 157 ]
 158 ]
 159
 160 [heading Models]
 161
 162 * [classref boost::histogram::unlimited_storage]
 163 * [classref boost::histogram::storage_adaptor]
 164 * [classref boost::histogram::dense_storage]
 165 * [classref boost::histogram::weight_storage]
 166 * [classref boost::histogram::profile_storage]
 167 * [classref boost::histogram::weighted_profile_storage]
 168
 169 [endsect]