[hist] Implement Get{Normal,Full}Range of axis

Author: hahnjo

hist/histv7/inc/ROOT/RBinIndexRange.hxx

@@ -26,6 +26,16 @@ A range of bin indices \f$[fBegin, fEnd)\f$.
 The interface allows convenient iteration over RBinIndex. If included, RBinIndex::Underflow() is encountered before the
 normal bins and RBinIndex::Overflow() is the last value.
 
+~~~ {.cxx}
+ROOT::Experimental::RRegularAxis axis(10, 0, 1);
+for (auto index : axis.GetNormalRange(2, 5)) {
+   // Will iterate over [2, 3, 4]
+}
+for (auto index : axis.GetFullRange()) {
+   // Will iterate over all bins, starting with the underflow and ending with the overflow bin
+}
+~~~
+
 \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback is
 welcome!
 */
@@ -121,6 +131,9 @@ namespace Internal {
 
 /// Internal function to create RBinIndexRange.
 ///
+/// Users are strongly advised to create bin index ranges via the respective axis types, for example with
+/// RRegularAxis::GetNormalRange(RBinIndex, RBinIndex) or RRegularAxis::GetFullRange().
+///
 /// \param[in] begin the begin of the bin index range (inclusive)
 /// \param[in] end the end of the bin index range (exclusive)
 /// \param[in] nNormalBins the number of normal bins, after which iteration advances to RBinIndex::Overflow()

hist/histv7/inc/ROOT/RRegularAxis.hxx

@@ -6,6 +6,7 @@
 #define ROOT_RRegularAxis
 
 #include "RBinIndex.hxx"
+#include "RBinIndexRange.hxx"
 #include "RLinearizedIndex.hxx"
 
 #include <cassert>
@@ -120,6 +121,50 @@ public:
       return {bin, bin < fNNormalBins};
    }
 
+   /// Get the range of all normal bins.
+   ///
+   /// \return the bin index range from the first to the last bin, inclusive
+   RBinIndexRange GetNormalRange() const
+   {
+      return Internal::CreateBinIndexRange(RBinIndex(0), RBinIndex(fNNormalBins), 0);
+   }
+
+   /// Get a range of normal bins.
+   ///
+   /// \param[in] begin the begin of the bin index range (inclusive), must be normal
+   /// \param[in] end the end of the bin index range (exclusive), must be normal and >= begin
+   /// \return a bin index range \f$[begin, end)\f$
+   RBinIndexRange GetNormalRange(RBinIndex begin, RBinIndex end) const
+   {
+      if (!begin.IsNormal()) {
+         throw std::invalid_argument("begin must be a normal bin");
+      }
+      if (begin.GetIndex() >= fNNormalBins) {
+         throw std::invalid_argument("begin must be inside the axis");
+      }
+      if (!end.IsNormal()) {
+         throw std::invalid_argument("end must be a normal bin");
+      }
+      if (end.GetIndex() > fNNormalBins) {
+         throw std::invalid_argument("end must be inside or past the axis");
+      }
+      if (!(end >= begin)) {
+         throw std::invalid_argument("end must be >= begin");
+      }
+      return Internal::CreateBinIndexRange(begin, end, 0);
+   }
+
+   /// Get the full range of all bins.
+   ///
+   /// This includes underflow and overflow bins, if enabled.
+   ///
+   /// \return the bin index range of all bins
+   RBinIndexRange GetFullRange() const
+   {
+      return fEnableFlowBins ? Internal::CreateBinIndexRange(RBinIndex::Underflow(), RBinIndex(), fNNormalBins)
+                             : GetNormalRange();
+   }
+
    /// ROOT Streamer function to throw when trying to store an object of this class.
    void Streamer(TBuffer &) { throw std::runtime_error("unable to store RRegularAxis"); }
 };

hist/histv7/inc/ROOT/RVariableBinAxis.hxx

@@ -6,6 +6,7 @@
 #define ROOT_RVariableBinAxis
 
 #include "RBinIndex.hxx"
+#include "RBinIndexRange.hxx"
 #include "RLinearizedIndex.hxx"
 
 #include <cassert>
@@ -121,6 +122,49 @@ public:
       return {bin, bin < fBinEdges.size() - 1};
    }
 
+   /// Get the range of all normal bins.
+   ///
+   /// \return the bin index range from the first to the last bin, inclusive
+   RBinIndexRange GetNormalRange() const
+   {
+      return Internal::CreateBinIndexRange(RBinIndex(0), RBinIndex(fBinEdges.size() - 1), 0);
+   }
+
+   /// Get a range of normal bins.
+   ///
+   /// \param[in] begin the begin of the bin index range (inclusive), must be normal
+   /// \param[in] end the end of the bin index range (exclusive), must be normal and >= begin
+   /// \return a bin index range \f$[begin, end)\f$
+   RBinIndexRange GetNormalRange(RBinIndex begin, RBinIndex end) const
+   {
+      if (!begin.IsNormal()) {
+         throw std::invalid_argument("begin must be a normal bin");
+      }
+      if (begin.GetIndex() >= fBinEdges.size() - 1) {
+         throw std::invalid_argument("begin must be inside the axis");
+      }
+      if (!end.IsNormal()) {
+         throw std::invalid_argument("end must be a normal bin");
+      }
+      if (end.GetIndex() > fBinEdges.size() - 1) {
+         throw std::invalid_argument("end must be inside or past the axis");
+      }
+      if (!(end >= begin)) {
+         throw std::invalid_argument("end must be >= begin");
+      }
+      return Internal::CreateBinIndexRange(begin, end, 0);
+   }
+
+   /// Get the full range of all bins.
+   ///
+   /// This includes underflow and overflow bins, if enabled.
+   ///
+   /// \return the bin index range of all bins
+   RBinIndexRange GetFullRange() const
+   {
+      return fEnableFlowBins ? Internal::CreateBinIndexRange(RBinIndex::Underflow(), RBinIndex(), fBinEdges.size() - 1)
+                             : GetNormalRange();
+   }
    /// ROOT Streamer function to throw when trying to store an object of this class.
    void Streamer(TBuffer &) { throw std::runtime_error("unable to store RVariableBinAxis"); }
 };

hist/histv7/test/hist_regular.cxx

@@ -1,6 +1,8 @@
 #include "hist_test.hxx"
 
+#include <iterator>
 #include <limits>
+#include <stdexcept>
 
 TEST(RRegularAxis, Constructor)
 {
@@ -163,3 +165,70 @@ TEST(RRegularAxis, GetLinearizedIndex)
       EXPECT_FALSE(linIndex.fValid);
    }
 }
+
+TEST(RRegularAxis, GetNormalRange)
+{
+   static constexpr std::size_t Bins = 20;
+   const RRegularAxis axis(Bins, 0, Bins);
+   const auto index0 = RBinIndex(0);
+   const auto indexBins = RBinIndex(Bins);
+
+   {
+      const auto normal = axis.GetNormalRange();
+      EXPECT_EQ(normal.GetBegin(), index0);
+      EXPECT_EQ(normal.GetEnd(), indexBins);
+      EXPECT_EQ(std::distance(normal.begin(), normal.end()), Bins);
+   }
+
+   {
+      const auto normal = axis.GetNormalRange(index0, indexBins);
+      EXPECT_EQ(normal.GetBegin(), index0);
+      EXPECT_EQ(normal.GetEnd(), indexBins);
+      EXPECT_EQ(std::distance(normal.begin(), normal.end()), Bins);
+   }
+
+   {
+      const auto index1 = RBinIndex(1);
+      const auto index5 = RBinIndex(5);
+      const auto normal = axis.GetNormalRange(index1, index5);
+      EXPECT_EQ(normal.GetBegin(), index1);
+      EXPECT_EQ(normal.GetEnd(), index5);
+      EXPECT_EQ(std::distance(normal.begin(), normal.end()), 4);
+   }
+
+   {
+      const auto index1 = RBinIndex(1);
+      const auto empty = axis.GetNormalRange(index1, index1);
+      EXPECT_EQ(empty.GetBegin(), index1);
+      EXPECT_EQ(empty.GetEnd(), index1);
+      EXPECT_EQ(empty.begin(), empty.end());
+   }
+
+   const auto underflow = RBinIndex::Underflow();
+   const auto overflow = RBinIndex::Overflow();
+   EXPECT_THROW(axis.GetNormalRange(underflow, index0), std::invalid_argument);
+   EXPECT_THROW(axis.GetNormalRange(indexBins, indexBins), std::invalid_argument);
+   EXPECT_THROW(axis.GetNormalRange(index0, overflow), std::invalid_argument);
+   EXPECT_THROW(axis.GetNormalRange(index0, indexBins + 1), std::invalid_argument);
+}
+
+TEST(RRegularAxis, FullRange)
+{
+   static constexpr std::size_t Bins = 20;
+
+   {
+      const RRegularAxis axis(Bins, 0, Bins);
+      const auto full = axis.GetFullRange();
+      EXPECT_EQ(full.GetBegin(), RBinIndex::Underflow());
+      EXPECT_EQ(full.GetEnd(), RBinIndex());
+      EXPECT_EQ(std::distance(full.begin(), full.end()), Bins + 2);
+   }
+
+   {
+      const RRegularAxis axisNoFlowBins(Bins, 0, Bins, /*enableFlowBins=*/false);
+      const auto full = axisNoFlowBins.GetFullRange();
+      EXPECT_EQ(full.GetBegin(), RBinIndex(0));
+      EXPECT_EQ(full.GetEnd(), RBinIndex(Bins));
+      EXPECT_EQ(std::distance(full.begin(), full.end()), Bins);
+   }
+}

hist/histv7/test/hist_variable.cxx

@@ -1,6 +1,8 @@
 #include "hist_test.hxx"
 
+#include <iterator>
 #include <limits>
+#include <stdexcept>
 #include <vector>
 
 TEST(RVariableBinAxis, Constructor)
@@ -194,3 +196,81 @@ TEST(RVariableBinAxis, GetLinearizedIndex)
       EXPECT_FALSE(linIndex.fValid);
    }
 }
+
+TEST(RVariableBinAxis, GetNormalRange)
+{
+   static constexpr std::size_t Bins = 20;
+   std::vector<double> bins;
+   for (std::size_t i = 0; i < Bins; i++) {
+      bins.push_back(i);
+   }
+   bins.push_back(Bins);
+
+   const RVariableBinAxis axis(bins);
+   const auto index0 = RBinIndex(0);
+   const auto indexBins = RBinIndex(Bins);
+
+   {
+      const auto normal = axis.GetNormalRange();
+      EXPECT_EQ(normal.GetBegin(), index0);
+      EXPECT_EQ(normal.GetEnd(), indexBins);
+      EXPECT_EQ(std::distance(normal.begin(), normal.end()), Bins);
+   }
+
+   {
+      const auto normal = axis.GetNormalRange(index0, indexBins);
+      EXPECT_EQ(normal.GetBegin(), index0);
+      EXPECT_EQ(normal.GetEnd(), indexBins);
+      EXPECT_EQ(std::distance(normal.begin(), normal.end()), Bins);
+   }
+
+   {
+      const auto index1 = RBinIndex(1);
+      const auto index5 = RBinIndex(5);
+      const auto normal = axis.GetNormalRange(index1, index5);
+      EXPECT_EQ(normal.GetBegin(), index1);
+      EXPECT_EQ(normal.GetEnd(), index5);
+      EXPECT_EQ(std::distance(normal.begin(), normal.end()), 4);
+   }
+
+   {
+      const auto index1 = RBinIndex(1);
+      const auto empty = axis.GetNormalRange(index1, index1);
+      EXPECT_EQ(empty.GetBegin(), index1);
+      EXPECT_EQ(empty.GetEnd(), index1);
+      EXPECT_EQ(empty.begin(), empty.end());
+   }
+
+   const auto underflow = RBinIndex::Underflow();
+   const auto overflow = RBinIndex::Overflow();
+   EXPECT_THROW(axis.GetNormalRange(underflow, index0), std::invalid_argument);
+   EXPECT_THROW(axis.GetNormalRange(indexBins, indexBins), std::invalid_argument);
+   EXPECT_THROW(axis.GetNormalRange(index0, overflow), std::invalid_argument);
+   EXPECT_THROW(axis.GetNormalRange(index0, indexBins + 1), std::invalid_argument);
+}
+
+TEST(RVariableBinAxis, FullRange)
+{
+   static constexpr std::size_t Bins = 20;
+   std::vector<double> bins;
+   for (std::size_t i = 0; i < Bins; i++) {
+      bins.push_back(i);
+   }
+   bins.push_back(Bins);
+
+   {
+      const RVariableBinAxis axis(bins);
+      const auto full = axis.GetFullRange();
+      EXPECT_EQ(full.GetBegin(), RBinIndex::Underflow());
+      EXPECT_EQ(full.GetEnd(), RBinIndex());
+      EXPECT_EQ(std::distance(full.begin(), full.end()), Bins + 2);
+   }
+
+   {
+      const RVariableBinAxis axisNoFlowBins(bins, /*enableFlowBins=*/false);
+      const auto full = axisNoFlowBins.GetFullRange();
+      EXPECT_EQ(full.GetBegin(), RBinIndex(0));
+      EXPECT_EQ(full.GetEnd(), RBinIndex(Bins));
+      EXPECT_EQ(std::distance(full.begin(), full.end()), Bins);
+   }
+}