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 a snapshot of the develop branch, built from commit 613cdd3b0e.
PrevUpHomeNext

Class template category

boost::histogram::axis::category — Maps at a set of unique values to bin indices.

Synopsis

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

template<typename Value, typename MetaData, typename Options, 
         typename Allocator> 
class category : public boost::histogram::axis::iterator_mixin< category< Value, MetaData, Options, Allocator > >,
                 public metadata_base_t< MetaData >
{
public:
  // construct/copy/destruct
  category() = default;
  explicit category(allocator_type);
  template<typename It> 
    category(It, It, metadata_type = {}, options_type = {}, 
             allocator_type = {});
  template<typename It, typename A> category(It, It, metadata_type, A);
  template<typename C> 
    category(const C &, metadata_type = {}, options_type = {}, 
             allocator_type = {});
  template<typename C, typename A> category(const C &, metadata_type, A);
  template<typename U> 
    category(std::initializer_list< U >, metadata_type = {}, 
             options_type = {}, allocator_type = {});
  template<typename U, typename A> 
    category(std::initializer_list< U >, metadata_type, A);
  category(const category &, index_type, index_type, unsigned);

  // public member functions
  index_type index(const value_type &) const noexcept;
  std::pair< index_type, index_type > update(const value_type &);
  auto value(index_type) const;
  decltype(auto) bin(index_type) const;
  index_type size() const noexcept;
  template<typename V, typename M, typename O, typename A> 
    bool operator==(const category< V, M, O, A > &) const noexcept;
  template<typename V, typename M, typename O, typename A> 
    bool operator!=(const category< V, M, O, A > &) const noexcept;
  allocator_type get_allocator() const;
  template<typename Archive> void serialize(Archive &, unsigned);

  // public static functions
  static constexpr unsigned options() noexcept;
  static constexpr bool inclusive() noexcept;
  static constexpr bool ordered() noexcept;
};

Description

The axis maps a set of values to bins, following the order of arguments in the constructor. The optional overflow bin for this axis counts input values that are not part of the set. Binning has O(N) complexity, but with a very small factor. For small N (the typical use case) it beats other kinds of lookup.

The options underflow andcircular are not allowed. The optionsgrowth andoverflow are mutually exclusive.

Template Parameters

  1. typename Value

    input value type, must be equal-comparable.

  2. typename MetaData

    type to store meta data.

  3. typename Options

    see boost::histogram::axis::option.

  4. typename Allocator

    allocator to use for dynamic memory management.

category public construct/copy/destruct

  1. category() = default;
  2. explicit category(allocator_type alloc);
  3. template<typename It> 
      category(It begin, It end, metadata_type meta = {}, 
               options_type options = {}, allocator_type alloc = {});
    Construct from forward iterator range of unique values.

    The constructor throws std::invalid_argument if iterator range is invalid. If the range contains duplicated values, the behavior of the axis is undefined.

    The arguments meta and alloc are passed by value. If you move either of them into the axis and the constructor throws, their values are lost. Do not move if you cannot guarantee that the bin description is not valid.

    Parameters:

    alloc

    allocator instance to use (optional).

    begin

    begin of category range of unique values.

    end

    end of category range of unique values.

    meta

    description of the axis (optional).

    options

    see boost::histogram::axis::option (optional).

  4. template<typename It, typename A> 
      category(It begin, It end, metadata_type meta, A alloc);
  5. template<typename C> 
      category(const C & iterable, metadata_type meta = {}, 
               options_type options = {}, allocator_type alloc = {});
    Construct axis from iterable sequence of unique values.

    Parameters:

    alloc

    allocator instance to use.

    iterable

    sequence of unique values.

    meta

    description of the axis.

    options

    see boost::histogram::axis::option (optional).

  6. template<typename C, typename A> 
      category(const C & iterable, metadata_type meta, A alloc);
  7. template<typename U> 
      category(std::initializer_list< U > list, metadata_type meta = {}, 
               options_type options = {}, allocator_type alloc = {});
    Construct axis from an initializer list of unique values.

    Parameters:

    alloc

    allocator instance to use.

    list

    std::initializer_list of unique values.

    meta

    description of the axis.

    options

    see boost::histogram::axis::option (optional).

  8. template<typename U, typename A> 
      category(std::initializer_list< U > list, metadata_type meta, A alloc);
  9. category(const category & src, index_type begin, index_type end, 
             unsigned merge);
    Constructor used by algorithm::reduce to shrink and rebin (not for users).

category public member functions

  1. index_type index(const value_type & x) const noexcept;
    Return index for value argument.
  2. std::pair< index_type, index_type > update(const value_type & x);
    Returns index and shift (if axis has grown) for the passed argument.
  3. auto value(index_type idx) const;
    Return value for index argument.

    Throws std::out_of_range if the index is out of bounds.

  4. decltype(auto) bin(index_type idx) const;
    Return value for index argument; alias for value(...).
  5. index_type size() const noexcept;
    Returns the number of bins, without over- or underflow.
  6. template<typename V, typename M, typename O, typename A> 
      bool operator==(const category< V, M, O, A > & o) const noexcept;
  7. template<typename V, typename M, typename O, typename A> 
      bool operator!=(const category< V, M, O, A > & o) const noexcept;
  8. allocator_type get_allocator() const;
  9. template<typename Archive> void serialize(Archive & ar, unsigned);

category public static functions

  1. static constexpr unsigned options() noexcept;
    Returns the options.
  2. static constexpr bool inclusive() noexcept;
    Whether the axis is inclusive (see axis::traits::is_inclusive).
  3. static constexpr bool ordered() noexcept;
    Indicate that the axis is not ordered.

PrevUpHomeNext