...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Users can extend the library with various new types whose concepts are defined here.
An Axis maps input values to indices. It holds state specific to that axis, like the number of bins and any metadata. Must be CopyConstructible, CopyAssignable, and nothrow MoveAssignable.
A
is a type meeting the
requirements of Axis
a
is a value of type
A
I
is an alias for boost::histogram::axis::index_type
Table 1.1. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 



Const member function which returns the number of bins of the axis.
All indices from 


Const member function which maps a value 


Const member function which returns the allocator 
A
is a type meeting the
requirements of Axis
a
and b
are values of type A
i
and j
are indices of type boost::histogram::axis::index_type
n
is a value of type
unsigned
M
is a metadata type
that is CopyConstructible
and CopyAssignable
and nothrow MoveAssignable.
ar
is a value of an archive
with Boost.Serialization semantics
Table 1.2. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 



Nonconst member function which maps a value to an index (first
argument of the returned pair) and offset (second argument of the
returned pair). If the value is not covered by the axis, this method
may grow the current axis size ( 

Special constructor used by the reduce algorithm. 



Static constexpr member function which returns the 


Static constexpr member function which returns true, if the axis has a bin for every possible input value, and false otherwise. Faster code can be generated if all axes types in a histogram are inclusive. An axis with underflow and overflow bins is always inclusive. An axis may be inclusive even if underflow or overflow bins are missing. For example, a category axis is inclusive if either it has an overflow bin or if it is growing. 


Const member function which returns a const reference to the metadata associated with the axis (usually a string). 


Likewise, but nonconst member function which returns a reference to the metadata. If this member function exists, also the previous one must exist. 


Returns 


Must be implemented if 




Saves to the archive or loads serialised state from the archive.
The version number 
A DiscreteAxis is one of two optional refinements of the Axis concept, the other one is the IntervalAxis. This concept is for axes in which each bin represents a single value instead of an interval.
Discrete axes can be further divided into ordered and unordered. An axis
is ordered, when bin indices i < j < k imply that value[i] < value[j]
< value[k] or value[i] > value[j] > value[k] for all i, j, k. The
integer axis
is ordered and the category
axis
is unordered.
An unordered discrete axis cannot have an underflow bin. Since there is no order, one can have at most one extra bin that counts values not handled by the axis. By convention the overflow bin is used for that.
A
is a type meeting the
requirements of DiscreteAxis
a
is a value of type
A
V
is the type accepted
for conversion into an index
v
is a value of type
V
i
is a value of type
boost::histogram::axis::index_type
AxisIter
is an RandomAccessIterator
over the bins of A
ReAxisIter
is a reverse
RandomAccessIterator over the bins of A
Table 1.3. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 



Static constexpr member function which returns true if the axis
is ordered and false otherwise. If this is absent, the library
checks whether the value type is arithmetic instead, see 


Const member function which maps an index to a value. The mapping
must be injective: each index must be uniquely mapped to one value.
The effect must be exactly the inverse of 


Must have the same effect as 


Const member function which return an iterator to the bin with
index 


Const member function which returns an iterator to the bin with
index 


Const member function which return a reverse iterator to the bin
with index 


Const member function which returns an iterator to the bin with
index 
Tip  

The complete iterator interface can be added to a userdefined axis which
implements 
boost::histogram::axis::category
boost::histogram::axis::integer
,
if first template parameter is int
A IntervalAxis is one of two optional refinements of the Axis concept, the other one is the DiscreteAxis. It is for ordered values that form intervals with a welldefined lower and upper edge, and a center. Each bin represents an interval of values.
A
is a type meeting the
requirements of IntervalAxis
a
is a value of type
A
V
is the type accepted
for conversion into an index
B
is the type that represents
the bin interval
v
is a value of type
V
i
is a value of type
boost::histogram::axis::index_type
j
is a value of type
boost::histogram::axis::real_index_type
AxisIter
is an RandomAccessIterator
over the bins of A
ReAxisIter
is a reverse
RandomAccessIterator over the bins of A
Table 1.4. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 



Const member function which maps an index to a value. The mapping
must be injective: each index must be uniquely mapped to one value.
The result of 


Const member function which returns an instance that represents
the current bin. Nothing about the type is required, but it is
recommended that the type has the methods 


Const member function which return an iterator to the bin with
index 


Const member function which returns an iterator to the bin with
index 


Const member function which return a reverse iterator to the bin
with index 


Const member function which returns an iterator to the bin with
index 
Tip  

The complete iterator interface can be added to a userdefined axis which
implements 
boost::histogram::axis::regular
boost::histogram::axis::variable
boost::histogram::axis::integer
,
if first template parameter is a floating point type
A Transform implements a monotonic mapping
between two realvalued domains, external and internal. It is used to extend
the regular axis
.
The bins in the internal domain are of equal width, while the bins in the
external domain are nonequal width. Must be DefaultConstructible,
CopyConstructible,
and CopyAssignable.
T
is a type meeting the
requirements of Transform
t
is a value of type
T
X
is a type with the
semantics of a floatingpoint type
x
is a value of type
X
Y
is a floatingpoint
type
y
is a value of type
Y
Table 1.5. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 



Const or static member function which maps the external value to
the corresponding internal value. The return type 


Const or static member function which maps the internal value to
the corresponding external value. The result of 



T
is a type meeting the
requirements of Transform
t
is a value of type
T
ar
is a value of an archive
with Boost.Serialization semantics
Table 1.6. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 



A Storage handles memory for the bin counters and provides a uniform vectorlike interface for accessing cell values for reading and writing. Must be DefaultConstructible, CopyConstructible, and CopyAssignable.
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
Alloc
is an allocator
type for S
Table 1.7. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 


Cell element type, may be either an integral type, floatingpoint type, or a type meeting the requirements of Accumulator. 








Returns an STLcompliant iterator type which dereferences to 


Returns an STLcompliant iterator type which dereferences to 


bool 
Static constexpr member. True, if storage supports parallel readwrite 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 cellaccess singlethreaded. 


Const member function which returns the current number of cells in the storage. 

Nonconst member function which discards current cell values, changes
storage size to 



Nonconst member function which returns the iterator to the first storage cell. 


Likewise, but a const member function which returns the const_iterator. 


Member function which returns the iterator to the cell after the last valid storage cell. 


Likewise, but a const member function which returns the const_iterator. 


Member function which returns a reference to the cell which is
addressed by 


Likewise, but a const member function which returns a const reference. 





Const member function which returns the allocator used by 
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 1.8. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 



Scales all cell values by the factor 


An Accumulator is a functor which consumes the argument to update some internal state. Must be DefaultConstructible, CopyConstructible, and CopyAssignable.
A
is a type meeting the
requirements of Accumulator
a
and b
are values of type A
ts...
is a pack of values of arbitrary types
Table 1.9. Valid expressions
Expression 
Returns 
Semantics, Pre/Postconditions 


Either a call operator accepting a fixed number of arguments must be implemented, or the preincrement operator. The call operator may not be templated and not overloaded, except to support weights as described under optional features. 



Returns 


Must be implemented if 
A
is a type meeting the
requirements of Accumulator
a
and b
are values of type A
w
is a value of type
boost::histogram::weight_type
,
where T
is a number type
ts...
is a pack of values of arbitrary types
v
is a number value (integral
or floating point)
Table 1.10. Valid expressions
Expression 
Return 
Semantics, Pre/Postconditions 


Does a weighted fill of the accumulator. Use this to implement
weight support for an accumulator that is normally filled with




Adds a second accumulator 


Scales the accumulator state by the real value 




