histogram/doc/concepts/Storage.qbk

[/
            Copyright Hans Dembinski 2018 - 2019.
   Distributed under the Boost Software License, Version 1.0.
      (See accompanying file LICENSE_1_0.txt or copy at
            https://www.boost.org/LICENSE_1_0.txt)
]

[section:Storage Storage]

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].

[heading Required features]

* `S` is a type meeting the requirements of [*Storage]
* `s` is a  value of types `S`
* `i` and `n` are values of type `std::size_t`

[table Valid expressions
[[Expression] [Returns] [Semantics, Pre/Post-conditions]]
[
  [`S::value_type`]
  []
  [
    Cell element type, may be either an integral type, floating-point type, or a type meeting the requirements of [link histogram.concepts.Accumulator [*Accumulator]].
  ]
]
[
  [`S::reference`]
  []
  [
    `S::value_type&` or a proxy class which acts like a reference.
  ]
]
[
  [`S::const_reference`]
  []
  [
    `const S::value_type&` or a proxy class which acts like a const reference. Implicitly convertible to `S::value_type`.
  ]
]
[
  [`S::iterator`]
  []
  [
    Returns an STL-compliant iterator type which dereferences to `S::reference`.
  ]
]
[
  [`S::const_iterator`]
  []
  [
    Returns an STL-compliant iterator type which dereferences to `S::const_reference`.
  ]
]
[
  [`S::has_threading_support`]
  [bool]
  [
    Static constexpr member. True, if storage supports parallel read-write access to all cells.
    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.
  ]
]
[
  [`s.size()`]
  [`std::size_t`]
  [
    Const member function which returns the current number of cells in the storage.
  ]
]
[
  [`s.reset(n)`]
  []
  [
    Non-const member function which discards current cell values, changes storage size to `n` and initializes all cells to the default-constructed state.
  ]
]
[
  [`s.begin()`]
  [`S::iterator`]
  [
    Non-const member function which returns the iterator to the first storage cell.
  ]
]
[
  [`s.begin()`]
  [`S::const_iterator`]
  [
    Likewise, but a const member function which returns the const_iterator.
  ]
]
[
  [`s.end()`]
  [`S::iterator`]
  [
    Member function which returns the iterator to the cell after the last valid storage cell.
  ]
]
[
  [`s.end()`]
  [`S::const_iterator`]
  [
    Likewise, but a const member function which returns the const_iterator.
  ]
]
[
  [`s[i]`]
  [`S::reference`]
  [
    Member function which returns a reference to the cell which is addressed by `i`. The index `i` must be valid: `i < s.size()`.
  ]
]
[
  [`s[i]`]
  [`S::const_reference`]
  [
    Likewise, but a const member function which returns a const reference.
  ]
]
[
  [`s == t`]
  [`bool`]
  [
    `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`.
  ]
]
[
  [`s.get_allocator()`]
  [`Alloc`]
  [
    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.
  ]
]
]

[heading Optional features]

* `S` is a type meeting the requirements of [*Storage]
* `s` is a  value of types `S`
* `x` is convertible to `double`
* `ar` is a value of an archive with Boost.Serialization semantics

[table Valid expressions
[[Expression] [Returns] [Semantics, Pre/Post-conditions]]
[
  [`s *= x`]
  [`S&`]
  [
    Scales all cell values by the factor `x` and returns a reference to self.
  ]
]
[
  [`s.serialize(ar, n)`]
  []
  [
    `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.
  ]
]
]

[heading Models]

* [classref boost::histogram::unlimited_storage]
* [classref boost::histogram::storage_adaptor]
* [classref boost::histogram::dense_storage]
* [classref boost::histogram::weight_storage]
* [classref boost::histogram::profile_storage]
* [classref boost::histogram::weighted_profile_storage]

[endsect]