diff --git a/doc/getting_started.qbk b/doc/getting_started.qbk index c58fcb8c..80e553df 100644 --- a/doc/getting_started.qbk +++ b/doc/getting_started.qbk @@ -57,7 +57,7 @@ The library was designed to be very flexible and modular. The modularity is used [section Standard library algorithms] -The library was designed to work well with the C++ standard library. Here is an example on how to get the maximum highest count in a 3d histogram with `std::max_element`. +The library was designed to work well with the C++ standard library. Here is an example on how to get the most common color from an image, using a 3d histogram and `std::max_element`. [import ../examples/getting_started_listing_04.cpp] [getting_started_listing_04] diff --git a/examples/getting_started_listing_04.cpp b/examples/getting_started_listing_04.cpp index 3a04fd49..fe44b1f5 100644 --- a/examples/getting_started_listing_04.cpp +++ b/examples/getting_started_listing_04.cpp @@ -20,7 +20,8 @@ int main() { /* We make a 3d histogram for color values (r, g, b) in an image. We assume the values - are of type char. The value range then is [0, 256). + are of type char. The value range then is [0, 256). The integer axis is perfect for + color values. */ auto h = make_histogram( axis::integer<>(0, 256, "r"), @@ -36,16 +37,16 @@ int main() { h(0, 1, 0); /* - Now let's say we want to know which color is most common. We can use std::max_element on an - indexed range for that. + Now let's say we want to know which color is most common. We can use std::max_element + on an indexed range for that. */ auto ind = indexed(h); auto max_it = std::max_element(ind.begin(), ind.end()); /* - max_it is the iterator to the maximum counter. This is the special iterator from indexed_range, - you can use it to access the cell index as well and the bin values. You need to - double-dereference it to get to the cell count. + max_it is a special iterator to the histogram cell with the highest count. + This iterator allows one to access the cell value, bin indices, and bin values. + You need to twice dereference it to get to the cell value. */ std::ostringstream os; os << boost::format("count=%i rgb=(%i, %i, %i)") diff --git a/include/boost/histogram/indexed.hpp b/include/boost/histogram/indexed.hpp index 299d37cc..0d3235ff 100644 --- a/include/boost/histogram/indexed.hpp +++ b/include/boost/histogram/indexed.hpp @@ -55,16 +55,17 @@ public: class iterator; using range_iterator = iterator; ///< deprecated - /** Pointer-like class to access value and index of current cell. + /** Lightweight view to access value and index of current cell. - Its methods provide access to the current indices and bins and it acts like a pointer - to the cell value. To interoperate with the algorithms of the standard library, the - accessor is implicitly convertible to a cell value. Assignments and comparisons are - passed through to the cell. The accessor is coupled to its parent iterator. Moving the - parent iterator forward also updates the linked accessor. Accessors are not copyable. - They cannot be stored in containers, but range_iterators can be stored. + The methods provide access to the current cell indices and bins. It acts like a + pointer to the cell value, and in a limited way also like a reference. To interoperate + with the algorithms of the standard library, the accessor is implicitly convertible to + a cell value. Assignments and comparisons are passed through to the cell. An accessor + is coupled to its parent indexed_range::iterator. Moving the parent iterator + forward also updates the linked accessor. Accessors are not copyable. They cannot be + stored in containers, but indexed_range::iterator can be stored. */ - class accessor : detail::mirrored { + class BOOST_ATTRIBUTE_NODISCARD accessor : detail::mirrored { public: /// Array-like view into the current multi-dimensional index. class index_view {