Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Class template histogram

boost::histogram::histogram — Central class of the histogram library.

Synopsis

// In header: <boost/histogram/histogram.hpp>

template<typename Axes, typename Storage> 
class histogram {
public:
  // types
  typedef Axes                                  axes_type;       
  typedef Storage                               storage_type;    
  typedef typename storage_type::value_type     value_type;      
  typedef typename storage_type::iterator       iterator;        
  typedef typename storage_type::const_iterator const_iterator;  
  typedef unspecified                           multi_index_type;

  // construct/copy/destruct
  histogram() = default;
  template<typename A, typename S> explicit histogram(histogram< A, S > &&);
  template<typename A, typename S> 
    explicit histogram(const histogram< A, S > &);
  template<typename A> histogram(A &&, Storage);
  explicit histogram(Axes);
  template<class... As> explicit histogram(As &&...);
  template<typename A, typename S> histogram & operator=(histogram< A, S > &&);
  template<typename A, typename S> 
    histogram & operator=(const histogram< A, S > &);

  // public member functions
  constexpr unsigned rank() const noexcept;
  std::size_t size() const noexcept;
  void reset();
  template<unsigned N = 0> 
    decltype(auto) axis(std::integral_constant< unsigned, N > = {}) const;
  decltype(auto) axis(unsigned) const;
  template<typename Unary> auto for_each_axis(Unary &&) const;
  template<typename T0, class... Ts> 
    iterator operator()(const T0 &, const Ts &...);
  template<class... Ts> iterator operator()(const std::tuple< Ts... > &);
  template<typename Iterable> void fill(const Iterable &);
  template<typename Iterable, typename T> 
    void fill(const Iterable &, const weight_type< T > &);
  template<typename Iterable, typename T> 
    void fill(const weight_type< T > &, const Iterable &);
  template<typename Iterable, class... Ts> 
    void fill(const Iterable &, const sample_type< std::tuple< Ts... >> &);
  template<typename Iterable, typename T> 
    void fill(const sample_type< T > &, const Iterable &);
  template<typename Iterable, typename T, class... Ts> 
    void fill(const Iterable &, const weight_type< T > &, 
              const sample_type< std::tuple< Ts... >> &);
  template<typename Iterable, typename T, typename U> 
    void fill(const sample_type< T > &, const weight_type< U > &, 
              const Iterable &);
  template<typename Iterable, typename T, typename U> 
    void fill(const weight_type< T > &, const sample_type< U > &, 
              const Iterable &);
  template<typename Iterable, typename T, typename U> 
    void fill(const Iterable &, const sample_type< T > &, 
              const weight_type< U > &);
  template<class... Is> decltype(auto) at(axis::index_type, Is...);
  template<class... Is> decltype(auto) at(axis::index_type, Is...) const;
  decltype(auto) at(const multi_index_type &);
  decltype(auto) at(const multi_index_type &) const;
  decltype(auto) operator[](axis::index_type);
  decltype(auto) operator[](axis::index_type) const;
  decltype(auto) operator[](const multi_index_type &);
  decltype(auto) operator[](const multi_index_type &) const;
  template<typename A, typename S> 
    bool operator==(const histogram< A, S > &) const noexcept;
  template<typename A, typename S> 
    bool operator!=(const histogram< A, S > &) const noexcept;
  template<typename A, typename S> 
    histogram & operator+=(const histogram< A, S > &);
  template<typename S> 
    histogram & operator+=(const histogram< axes_type, S > &);
  template<typename A, typename S> 
    histogram & operator-=(const histogram< A, S > &);
  template<typename A, typename S> 
    histogram & operator *=(const histogram< A, S > &);
  template<typename A, typename S> 
    histogram & operator/=(const histogram< A, S > &);
  histogram & operator *=(const double);
  histogram & operator/=(const double);
  iterator begin() noexcept;
  iterator end() noexcept;
  const_iterator begin() const noexcept;
  const_iterator end() const noexcept;
  const_iterator cbegin() const noexcept;
  const_iterator cend() const noexcept;
  template<typename Archive> void serialize(Archive &, unsigned);
};

Description

Histogram uses the call operator to insert data, like the Boost.Accumulators.

Use factory functions (see make_histogram.hpp andmake_profile.hpp) to conveniently create histograms rather than calling the ctors directly.

Use the indexed range generator to iterate over filled histograms, which is convenient and faster than hand-written loops for multi-dimensional histograms.

Template Parameters

  1. typename Axes

    std::tuple of axis types OR std::vector of an axis type or axis::variant

  2. typename Storage

    class that implements the storage interface

histogram public construct/copy/destruct

  1. histogram() = default;
  2. template<typename A, typename S> explicit histogram(histogram< A, S > && rhs);
  3. template<typename A, typename S> 
      explicit histogram(const histogram< A, S > & rhs);
  4. template<typename A> histogram(A && a, Storage s);
  5. explicit histogram(Axes axes);
  6. template<class... As> explicit histogram(As &&... as);
  7. template<typename A, typename S> 
      histogram & operator=(histogram< A, S > && rhs);
  8. template<typename A, typename S> 
      histogram & operator=(const histogram< A, S > & rhs);

histogram public member functions

  1. constexpr unsigned rank() const noexcept;
    Number of axes (dimensions).
  2. std::size_t size() const noexcept;
    Total number of bins (including underflow/overflow).
  3. void reset();
    Reset all bins to default initialized values.
  4. template<unsigned N = 0> 
      decltype(auto) axis(std::integral_constant< unsigned, N > = {}) const;
    Get N-th axis using a compile-time number.

    This version is more efficient than the one accepting a run-time number.

  5. decltype(auto) axis(unsigned i) const;
    Get N-th axis with run-time number.

    Prefer the version that accepts a compile-time number, if you can use it.

  6. template<typename Unary> auto for_each_axis(Unary && unary) const;
    Apply unary functor/function to each axis.
  7. template<typename T0, class... Ts> 
      iterator operator()(const T0 & arg0, const Ts &... args);
    Fill histogram with values, an optional weight, and/or a sample.

    Returns iterator to located cell.

    Arguments are passed in order to the axis objects. Passing an argument type that is not convertible to the value type accepted by the axis or passing the wrong number of arguments causes a throw of std::invalid_argument.

    Optional weight

    An optional weight can be passed as the first or last argument with the weight helper function. Compilation fails if the storage elements do not support weights.

    Samples

    If the storage elements accept samples, pass them with the sample helper function in addition to the axis arguments, which can be the first or last argument. The sample helper function can pass one or more arguments to the storage element. If samples and weights are used together, they can be passed in any order at the beginning or end of the argument list.

    Axis with multiple arguments

    If the histogram contains an axis which accepts a std::tuple of arguments, the arguments for that axis need to be passed as astd::tuple, for example,std::make_tuple(1.2, 2.3). If the histogram contains only this axis and no other, the arguments can be passed directly.

  8. template<class... Ts> iterator operator()(const std::tuple< Ts... > & args);
    Fill histogram with values, an optional weight, and/or a sample from a std::tuple.
  9. template<typename Iterable> void fill(const Iterable & args);
    Fill histogram with several values at once.

    The argument must be an iterable with a size that matches the rank of the histogram. The element of an iterable may be 1) a value or 2) an iterable over a contiguous sequence of values or 3) a variant of 1) and 2). Sub-iterables must have the same length.

    Warning: std::vector<bool> is not a contiguous sequence over boolean values because of the infamous vector specialization for booleans. It cannot be used as an argument, but any truely contiguous sequence of boolean values can (std::array<bool, N> orstd::valarray<bool>, for example).

    Values are passed to the corresponding histogram axis in order. If a single value is passed together with an iterable of values, the single value is treated like an iterable with matching length of copies of this value.

    If the histogram has only one axis, an iterable of values may be passed directly.

    Parameters:

    args

    iterable as explained in the long description.

  10. template<typename Iterable, typename T> 
      void fill(const Iterable & args, const weight_type< T > & weights);
    Fill histogram with several values and weights at once.

    Parameters:

    args

    iterable of values.

    weights

    single weight or an iterable of weights.

  11. template<typename Iterable, typename T> 
      void fill(const weight_type< T > & weights, const Iterable & args);
    Fill histogram with several values and weights at once.

    Parameters:

    args

    iterable of values.

    weights

    single weight or an iterable of weights.

  12. template<typename Iterable, class... Ts> 
      void fill(const Iterable & args, 
                const sample_type< std::tuple< Ts... >> & samples);
    Fill histogram with several values and samples at once.

    Parameters:

    args

    iterable of values.

    samples

    single sample or an iterable of samples.

  13. template<typename Iterable, typename T> 
      void fill(const sample_type< T > & samples, const Iterable & args);
    Fill histogram with several values and samples at once.

    Parameters:

    args

    iterable of values.

    samples

    single sample or an iterable of samples.

  14. template<typename Iterable, typename T, class... Ts> 
      void fill(const Iterable & args, const weight_type< T > & weights, 
                const sample_type< std::tuple< Ts... >> & samples);
  15. template<typename Iterable, typename T, typename U> 
      void fill(const sample_type< T > & samples, 
                const weight_type< U > & weights, const Iterable & args);
  16. template<typename Iterable, typename T, typename U> 
      void fill(const weight_type< T > & weights, 
                const sample_type< U > & samples, const Iterable & args);
  17. template<typename Iterable, typename T, typename U> 
      void fill(const Iterable & args, const sample_type< T > & samples, 
                const weight_type< U > & weights);
  18. template<class... Is> decltype(auto) at(axis::index_type i, Is... is);
    Access cell value at integral indices.

    You can pass indices as individual arguments, as a std::tuple of integers, or as an interable range of integers. Passing the wrong number of arguments causes a throw of std::invalid_argument. Passing an index which is out of bounds causes a throw of std::out_of_range.

    Parameters:

    i

    index of first axis.

    is

    indices of second, third, ... axes.

    Returns:

    reference to cell value.

  19. template<class... Is> decltype(auto) at(axis::index_type i, Is... is) const;
    Access cell value at integral indices (read-only).
  20. decltype(auto) at(const multi_index_type & is);
    Access cell value at integral indices stored in iterable.
  21. decltype(auto) at(const multi_index_type & is) const;
    Access cell value at integral indices stored in iterable (read-only).
  22. decltype(auto) operator[](axis::index_type i);
    Access value at index (for rank = 1).
  23. decltype(auto) operator[](axis::index_type i) const;
    Access value at index (for rank = 1, read-only).
  24. decltype(auto) operator[](const multi_index_type & is);
    Access value at index tuple.
  25. decltype(auto) operator[](const multi_index_type & is) const;
    Access value at index tuple (read-only).
  26. template<typename A, typename S> 
      bool operator==(const histogram< A, S > & rhs) const noexcept;
    Equality operator, tests equality for all axes and the storage.
  27. template<typename A, typename S> 
      bool operator!=(const histogram< A, S > & rhs) const noexcept;
    Negation of the equality operator.
  28. template<typename A, typename S> 
      histogram & operator+=(const histogram< A, S > & rhs);
    Add values of another histogram.

    This operator is only available if the value_type supports operator+=.

    Both histograms must be compatible to be addable. The histograms are compatible, if the axes are either all identical. If the axes only differ in the states of their discrete growing axis types, then they are also compatible. The discrete growing axes are merged in this case.

  29. template<typename S> 
      histogram & operator+=(const histogram< axes_type, S > & rhs);
  30. template<typename A, typename S> 
      histogram & operator-=(const histogram< A, S > & rhs);
    Subtract values of another histogram.

    This operator is only available if the value_type supports operator-=.

  31. template<typename A, typename S> 
      histogram & operator *=(const histogram< A, S > & rhs);
    Multiply by values of another histogram.

    This operator is only available if the value_type supports operator*=.

  32. template<typename A, typename S> 
      histogram & operator/=(const histogram< A, S > & rhs);
    Divide by values of another histogram.

    This operator is only available if the value_type supports operator/=.

  33. histogram & operator *=(const double x);
    Multiply all values with a scalar.

    This operator is only available if the value_type supports operator*=.

  34. histogram & operator/=(const double x);
    Divide all values by a scalar.

    This operator is only available if operator*= is available.

  35. iterator begin() noexcept;
    Return value iterator to the beginning of the histogram.
  36. iterator end() noexcept;
    Return value iterator to the end in the histogram.
  37. const_iterator begin() const noexcept;
    Return value iterator to the beginning of the histogram (read-only).
  38. const_iterator end() const noexcept;
    Return value iterator to the end in the histogram (read-only).
  39. const_iterator cbegin() const noexcept;
    Return value iterator to the beginning of the histogram (read-only).
  40. const_iterator cend() const noexcept;
    Return value iterator to the end in the histogram (read-only).
  41. template<typename Archive> void serialize(Archive & ar, unsigned);

PrevUpHomeNext