new getting started example

doc/getting_started.qbk

@@ -48,4 +48,13 @@ The library was designed to be very flexible and modular. The modularity is used
 
 [endsect]
 
+[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`.
+
+[import ../examples/getting_started_listing_04.cpp]
+[getting_started_listing_04]
+
+[endsect]
+
 [endsect]

examples/Jamfile

@@ -20,6 +20,7 @@ alias cxx14 :
     [ run getting_started_listing_01.cpp ]
     [ run getting_started_listing_02.cpp ]
     [ run getting_started_listing_03.cpp ]
+    [ run getting_started_listing_04.cpp ]
     [ run guide_axis_basic_demo.cpp ]
     [ run guide_axis_circular.cpp ]
     [ run guide_axis_growing.cpp ]

examples/getting_started_listing_01.cpp

@@ -4,14 +4,16 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+// clang-format off
+
 //[ getting_started_listing_01
 
 #include <algorithm>           // std::for_each
 #include <boost/format.hpp>    // only needed for printing
 #include <boost/histogram.hpp> // make_histogram, regular, weight, indexed
-#include <cassert>             // assert
+#include <cassert>             // assert (used to test this example for correctness)
 #include <functional>          // std::ref
-#include <iostream>            // std::cout, std::cout, std::flush
+#include <iostream>            // std::cout, std::flush
 #include <sstream>             // std::ostringstream
 
 int main() {
@@ -39,6 +41,7 @@ int main() {
   */
   auto data = {-0.5, 1.1, 0.3, 1.7};
   std::for_each(data.begin(), data.end(), std::ref(h));
+  // let's fill some more values manually
   h(-1.5); // is placed in underflow bin -1
   h(-1.0); // is placed in bin 0, bin interval is semi-open
   h(2.0);  // is placed in overflow bin 6, bin interval is semi-open
@@ -71,8 +74,8 @@ int main() {
 
   std::ostringstream os;
   for (auto&& x : indexed(h, coverage::all)) {
-    os << boost::format("bin %2i [%4.1f, %4.1f): %i\n") % x.index() % x.bin().lower() %
-              x.bin().upper() % *x;
+    os << boost::format("bin %2i [%4.1f, %4.1f): %i\n") 
+          % x.index() % x.bin().lower() % x.bin().upper() % *x;
   }
 
   std::cout << os.str() << std::flush;

examples/getting_started_listing_02.cpp

@@ -4,6 +4,8 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+// clang-format off
+
 //[ getting_started_listing_02
 
 #include <boost/format.hpp>
@@ -49,10 +51,12 @@ int main() {
   const auto& cat_axis = axis::get<cat>(h.axis(0));
   std::ostringstream os;
   for (auto&& x : indexed(h)) {
-    os << boost::format("(%i, %i, %i) %4s [%3.1f, %3.1f) [%3.1f, %3.1f) %3.0f\n") %
-              x.index(0) % x.index(1) % x.index(2) % cat_axis.bin(x.index(0)) %
-              x.bin(1).lower() % x.bin(1).upper() % x.bin(2).lower() % x.bin(2).upper() %
-              *x;
+    os << boost::format("(%i, %i, %i) %4s [%3.1f, %3.1f) [%3.1f, %3.1f) %3.0f\n")
+          % x.index(0) % x.index(1) % x.index(2)
+          % cat_axis.bin(x.index(0))
+          % x.bin(1).lower() % x.bin(1).upper()
+          % x.bin(2).lower() % x.bin(2).upper()
+          % *x;
   }
 
   std::cout << os.str() << std::flush;

examples/getting_started_listing_03.cpp

@@ -4,6 +4,8 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+// clang-format off
+
 //[ getting_started_listing_03
 
 #include <boost/format.hpp>
@@ -36,8 +38,9 @@ int main() {
   */
   std::ostringstream os;
   for (auto&& x : indexed(p)) {
-    os << boost::format("bin %i [%3.1f, %3.1f) count %i mean %g\n") % x.index() %
-              x.bin().lower() % x.bin().upper() % x->count() % x->value();
+    os << boost::format("bin %i [%3.1f, %3.1f) count %i mean %g\n") 
+          % x.index() % x.bin().lower() % x.bin().upper() 
+          % x->count() % x->value();
   }
 
   std::cout << os.str() << std::flush;

examples/getting_started_listing_04.cpp

@@ -0,0 +1,59 @@
+// Copyright 2019 Hans Dembinski
+//
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+// clang-format off
+
+//[ getting_started_listing_04
+
+#include <algorithm>           // std::max_element
+#include <boost/format.hpp>    // only needed for printing
+#include <boost/histogram.hpp> // make_histogram, integer, indexed
+#include <iostream>            // std::cout, std::endl
+#include <sstream>             // std::ostringstream
+
+int main() {
+  using namespace boost::histogram;
+  using namespace boost::histogram::literals;
+
+  /*
+    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).
+  */
+  auto h = make_histogram(
+    axis::integer<>(0, 256, "r"),
+    axis::integer<>(0, 256, "g"),
+    axis::integer<>(0, 256, "b")
+  );
+
+  /*
+    We don't have real image data, so fill some fake data.
+  */
+  h(1, 2, 3);
+  h(1, 2, 3);
+  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.
+  */
+  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.
+  */
+  std::ostringstream os;
+  os << boost::format("count=%i rgb=(%i, %i, %i)")
+        % **max_it % max_it->bin(0_c) % max_it->bin(1) % max_it->bin(2);
+
+  std::cout << os.str() << std::endl;
+
+  assert(os.str() == "count=2 rgb=(1, 2, 3)");
+}
+
+//]