| Home | Libraries | People | FAQ | More

## Class template variable

boost::histogram::axis::variable — Axis for non-equidistant bins on the real line.

## Synopsis

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

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

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

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

## Description

Binning is a O(log(N)) operation. If speed matters and the problem domain allows it, prefer a regular axis, possibly with a transform.

If the axis has an overflow bin (the default), a value on the upper edge of the last bin is put in the overflow bin. The axis range represents a semi-open interval.

If the overflow bin is deactivated, then a value on the upper edge of the last bin is still counted towards the last bin. The axis range represents a closed interval. This is the desired behavior for random numbers drawn from a bounded interval, which is usually closed.

### Template Parameters

1.     typename Value

   input value type, must be floating point.

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.

### `variable` public construct/copy/destruct

1.     variable() = default;

2.     explicit variable(allocator_type alloc);

3.     template<typename It>
         variable(It begin, It end, metadata_type meta = {},
                  options_type options = {}, allocator_type alloc = {});

   Construct from forward iterator range of bin edges.

   The constructor throws `std::invalid_argument` if iterator range is invalid, if less than two edges are provided or if bin edges are not in ascending order.

   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 edge sequence.
   `end` | end of edge sequence.
   `meta` | description of the axis (optional).
   `options` | see boost::histogram::axis::option (optional).

4.     template<typename It, typename A>
         variable(It begin, It end, metadata_type meta, A alloc);

5.     template<typename U>
         variable(const U & iterable, metadata_type meta = {},
                  options_type options = {}, allocator_type alloc = {});

   Construct variable axis from iterable range of bin edges.

   Parameters:

   `alloc` | allocator instance to use (optional).
   `iterable` | iterable range of bin edges.
   `meta` | description of the axis (optional).
   `options` | see boost::histogram::axis::option (optional).

6.     template<typename U, typename A>
         variable(const U & iterable, metadata_type meta, A alloc);

7.     template<typename U>
         variable(std::initializer_list< U > list, metadata_type meta = {},
                  options_type options = {}, allocator_type alloc = {});

   Construct variable axis from initializer list of bin edges.

   Parameters:

   `alloc` | allocator instance to use (optional).
   `list` | `std::initializer_list` of bin edges.
   `meta` | description of the axis (optional).
   `options` | see boost::histogram::axis::option (optional).

8.     template<typename U, typename A>
         variable(std::initializer_list< U > list, metadata_type meta, A alloc);

9.     variable(const variable & src, index_type begin, index_type end,
                unsigned merge);

   Constructor used by algorithm::reduce to shrink and rebin (not for users).

### `variable` public member functions

1.     index_type index(value_type x) const noexcept;

   Return index for value argument.

2.     std::pair< index_type, index_type > update(value_type x) noexcept;

3.     value_type value(real_index_type i) const noexcept;

   Return value for fractional index argument.

4.     auto bin(index_type idx) const noexcept;

   Return bin for index argument.

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 variable< V, M, O, A > & o) const noexcept;

7.     template<typename V, typename M, typename O, typename A>
         bool operator!=(const variable< V, M, O, A > & o) const noexcept;

8.     auto get_allocator() const;

   Return allocator instance.

9.     template<typename Archive> void serialize(Archive & ar, unsigned);

### `variable` public static functions

1.     static constexpr unsigned options() noexcept;

   Returns the options.