Renamed extrude to slice and added docs.

Author: 5cript

README.md

@@ -210,6 +210,7 @@ Options are:
     - [value\_type operator-(interval const\& other) const](#value_type-operator-interval-const-other-const)
     - [value\_type size() const](#value_type-size-const)
     - [interval join(interval const\& other) const](#interval-joininterval-const-other-const)
+    - [slice\_type slice(interval const\& other) const](#slice_type-sliceinterval-const-other-const)
 
 ### iterator insert(interval_type const& ival)
 Adds an interval into the tree.
@@ -443,7 +444,7 @@ Returns a past the end const_iterator in reverse.
 **Returns**: past the end const_iterator.
 
 ## Members of Interval
-___You can implement your own interval if you provide the same functions, except (operator-, size, operator!=).___
+___You can implement your own interval if you provide the same functions, except (slice, operator-, size, operator!=).___
 
 There are 6 types of intervals:
 - open: (a, b)
@@ -505,3 +506,12 @@ Overlapping intervals have 0 distance.
 Returns The amount of elements in the interval when integral, or the distance between the 2 bounds when floating point.
 ### interval join(interval const& other) const
 Joins 2 intervals and whatever is inbetween.
+### slice_type<interval> slice(interval const& other) const
+Removes other from this interval returning what is remaining.
+The range of other going beyond the range of this is ignored.
+Returns a struct with 2 members: left_slice and right_slice.
+[   this interval  ]
+[left][other][right]
+
+When the intervals are closed, adjacent results are differenty by 1.
+[0, 9].slice([5, 19]) => left: [0, 4], right: nullopt

include/interval-tree/interval_tree.hpp

@@ -32,6 +32,30 @@ namespace lib_interval_tree
     // ############################################################################################################
     using default_interval_value_type = int;
     // ############################################################################################################
+    namespace detail
+    {
+        template <class...>
+        using void_t = void;
+
+        template <typename interval_t, typename = void>
+        struct has_slice_impl : std::false_type
+        {};
+
+        template <typename interval_t>
+        struct has_slice_impl<
+            interval_t,
+            void_t<decltype(std::declval<interval_t>().slice(std::declval<interval_t>()))>> : std::true_type
+        {};
+
+#if __cplusplus >= 202002L
+        template <typename interval_t>
+        concept has_slice = has_slice_impl<interval_t>::value;
+#else
+        template <typename interval_t>
+        constexpr bool has_slice = has_slice_impl<interval_t>::value;
+#endif
+    }
+    // ############################################################################################################
     template <typename numerical_type, typename interval_kind_>
     struct interval_base
     {
@@ -212,12 +236,14 @@ namespace lib_interval_tree
         }
 
         /**
-         * @brief Extrudes other from this interval returning what is remaining.
+         * @brief Removes other from this interval returning what is remaining.
+         *
+         * The range of other going beyond the range of this is ignored.
          *
          * @param other
          * @return slice_type<interval>
          */
-        slice_type<interval> extrude(interval const& other) const
+        slice_type<interval> slice(interval const& other) const
         {
             slice_type<interval> slices{};
             if (low_ < other.low_)
@@ -362,12 +388,12 @@ namespace lib_interval_tree
         }
 
         /**
-         * @brief Extrudes other from this interval returning what is remaining.
+         * @brief Removes other from this interval returning what is remaining.
          *
          * @param other
          * @return slice_type<interval>
          */
-        slice_type<interval> extrude(interval const& other) const
+        slice_type<interval> slice(interval const& other) const
         {
             if (!overlaps(other))
                 return {};
@@ -1417,9 +1443,7 @@ namespace lib_interval_tree
         {
             if (empty())
                 return {};
-            auto min = std::begin(*this)->interval()->low();
-            auto max = root_->max_;
-            return punch({min, max});
+            return punch({begin()->low(), root_->max_});
         }
 
         /**
@@ -1429,7 +1453,14 @@ namespace lib_interval_tree
          *
          * @param ival The range in which to punch out the gaps as a new tree
          */
-        interval_tree punch(interval_type ival) const
+        template <typename interval_t = interval_type>
+#ifdef LIB_INTERVAL_TREE_CONCEPTS
+        requires detail::has_slice<interval_t>
+        interval_tree
+#else
+        typename std::enable_if<detail::has_slice<interval_t>, interval_tree>::type
+#endif
+        punch(interval_type ival) const
         {
             interval_tree result;
 
@@ -1462,7 +1493,7 @@ namespace lib_interval_tree
             bool insert_remaining = false;
             for (; iter != cend(); ++iter)
             {
-                ex = ival.extrude(*iter);
+                ex = ival.slice(*iter);
                 if (ex.left_slice)
                     result.insert(*ex.left_slice);
 

tests/interval_tests.hpp

@@ -899,4 +899,77 @@ TEST_F(IntervalTests, CanFindDynamicIntervalUsingComparisonFunction)
     EXPECT_EQ(iter->high(), 5);
     EXPECT_EQ(iter->left_border(), interval_border::closed);
     EXPECT_EQ(iter->right_border(), interval_border::closed);
+}
+
+TEST_F(IntervalTests, ClosedSliceLeftOverlap)
+{
+    // [   this  ]
+    // [ls][param]
+    const auto result = i<closed>(1, 8).slice(i<closed>(5, 100));
+    ASSERT_TRUE(result.left_slice);
+    EXPECT_EQ(result.left_slice->low(), 1);
+    EXPECT_EQ(result.left_slice->high(), 4);
+    EXPECT_FALSE(result.right_slice);
+}
+
+TEST_F(IntervalTests, OpenSliceLeftOverlap)
+{
+    // [   this  ]
+    // [ls][param]
+    using lib_interval_tree::open;
+    const auto result = i<open>(1, 8).slice(i<open>(5, 10));
+    ASSERT_TRUE(result.left_slice);
+    EXPECT_EQ(result.left_slice->low(), 1);
+    EXPECT_EQ(result.left_slice->high(), 5);
+    EXPECT_FALSE(result.right_slice);
+}
+
+TEST_F(IntervalTests, ClosedRightRemains)
+{
+    // [   this  ]
+    // [param][rs]
+    const auto result = i<closed>(8, 15).slice(i<closed>(8, 12));
+    ASSERT_TRUE(result.right_slice);
+    EXPECT_EQ(result.right_slice->low(), 13);
+    EXPECT_EQ(result.right_slice->high(), 15);
+    EXPECT_FALSE(result.left_slice);
+}
+
+TEST_F(IntervalTests, OpenRightRemains)
+{
+    // [   this  ]
+    // [param][rs]
+    using lib_interval_tree::open;
+    const auto result = i<open>(8, 15).slice(i<open>(8, 12));
+    ASSERT_TRUE(result.right_slice);
+    EXPECT_EQ(result.right_slice->low(), 12);
+    EXPECT_EQ(result.right_slice->high(), 15);
+    EXPECT_FALSE(result.left_slice);
+}
+
+TEST_F(IntervalTests, ClosedMiddleExtrusion)
+{
+    // [   this      ]
+    // [ls][param][rs]
+    const auto result = i<closed>(0, 10).slice(i<closed>(5, 8));
+    ASSERT_TRUE(result.left_slice);
+    EXPECT_EQ(result.left_slice->low(), 0);
+    EXPECT_EQ(result.left_slice->high(), 4);
+    ASSERT_TRUE(result.right_slice);
+    EXPECT_EQ(result.right_slice->low(), 9);
+    EXPECT_EQ(result.right_slice->high(), 10);
+}
+
+TEST_F(IntervalTests, OpenMiddleExtrusion)
+{
+    // [   this      ]
+    // [ls][param][rs]
+    using lib_interval_tree::open;
+    const auto result = i<open>(0, 10).slice(i<open>(5, 8));
+    ASSERT_TRUE(result.left_slice);
+    EXPECT_EQ(result.left_slice->low(), 0);
+    EXPECT_EQ(result.left_slice->high(), 5);
+    ASSERT_TRUE(result.right_slice);
+    EXPECT_EQ(result.right_slice->low(), 8);
+    EXPECT_EQ(result.right_slice->high(), 10);
 }

tests/punch_tests.hpp

@@ -668,4 +668,27 @@ TEST_F(PunchTests, ClosedFloatGap)
     EXPECT_NEAR(iter->high(), 6.0f, 0.001f);
     EXPECT_NEAR((++iter)->low(), 10.0f, 0.001f);
     EXPECT_FLOAT_EQ(iter->high(), 12.0f);
+}
+
+TEST_F(PunchTests, PunchWithoutArgsEncompassesTree)
+{
+    using types = closed<int>;
+
+    auto tree = types::tree_type{};
+    tree.insert(types::interval_type{0, 5});
+    tree.insert(types::interval_type{10, 15});
+    tree.insert(types::interval_type{20, 25});
+    tree.insert(types::interval_type{30, 35});
+    auto result = tree.punch();
+
+    ASSERT_EQ(result.size(), 3);
+    auto iter = result.begin();
+    EXPECT_EQ(iter->low(), 6);
+    EXPECT_EQ(iter->high(), 9);
+
+    EXPECT_EQ((++iter)->low(), 16);
+    EXPECT_EQ(iter->high(), 19);
+
+    EXPECT_EQ((++iter)->low(), 26);
+    EXPECT_EQ(iter->high(), 29);
 }