Let timmerge and timsort return the end iterator

Author: Morwenn

README.md

@@ -35,16 +35,18 @@ template <
     typename Projection = std::identity
 >
     requires std::sortable<Iterator, Compare, Projection>
-void timsort(Iterator first, Sentinel last,
-             Compare compare={}, Projection projection={});
+auto timsort(Iterator first, Sentinel last,
+             Compare compare={}, Projection projection={})
+    -> Iterator;
 
 template <
     std::ranges::random_access_range Range,
     typename Compare = std::ranges::less,
     typename Projection = std::identity
 >
     requires std::sortable<std::ranges::iterator_t<Range>, Compare, Projection>
-void timsort(Range &range, Compare compare={}, Projection projection={});
+auto timsort(Range &range, Compare compare={}, Projection projection={})
+    -> std::ranges::borrowed_iterator_t<Range>;
 
 // timmerge
 
@@ -55,17 +57,19 @@ template <
     typename Projection = std::identity
 >
     requires std::sortable<Iterator, Compare, Projection>
-void timmerge(Iterator first, Iterator middle, Sentinel last,
-              Compare compare={}, Projection projection={});
+auto timmerge(Iterator first, Iterator middle, Sentinel last,
+              Compare compare={}, Projection projection={})
+    -> Iterator;
 
 template <
     std::ranges::random_access_range Range,
     typename Compare = std::ranges::less,
     typename Projection = std::identity
 >
     requires std::sortable<std::ranges::iterator_t<Range>, Compare, Projection>
-void timmerge(Range &&range, std::ranges::iterator_t<Range> middle,
+auto timmerge(Range &&range, std::ranges::iterator_t<Range> middle,
               Compare compare={}, Projection projection={})
+    -> std::ranges::borrowed_iterator_t<Range>;
 ```
 
 ## EXAMPLE

include/gfx/timsort.hpp

@@ -700,13 +700,16 @@ template <
     typename Projection = std::identity
 >
     requires std::sortable<Iterator, Compare, Projection>
-void timmerge(Iterator first, Iterator middle, Sentinel last,
-              Compare comp={}, Projection proj={}) {
+auto timmerge(Iterator first, Iterator middle, Sentinel last,
+              Compare comp={}, Projection proj={})
+    -> Iterator
+{
     auto last_it = std::ranges::next(first, last);
     GFX_TIMSORT_AUDIT(std::is_sorted(first, middle, comp, proj) && "Precondition");
     GFX_TIMSORT_AUDIT(std::is_sorted(middle, last_it, comp, proj) && "Precondition");
     detail::TimSort<Iterator, Compare, Projection>::merge(first, middle, last_it, comp, proj);
     GFX_TIMSORT_AUDIT(std::is_sorted(first, last_it, comp, proj) && "Postcondition");
+    return last_it;
 }
 
 /**
@@ -719,10 +722,11 @@ template <
     typename Projection = std::identity
 >
     requires std::sortable<std::ranges::iterator_t<Range>, Compare, Projection>
-void timmerge(Range &&range, std::ranges::iterator_t<Range> middle,
+auto timmerge(Range &&range, std::ranges::iterator_t<Range> middle,
               Compare comp={}, Projection proj={})
+    -> std::ranges::borrowed_iterator_t<Range>
 {
-    gfx::timmerge(std::begin(range), middle, std::end(range), comp, proj);
+    return gfx::timmerge(std::begin(range), middle, std::end(range), comp, proj);
 }
 
 /**
@@ -735,11 +739,14 @@ template <
     typename Projection = std::identity
 >
     requires std::sortable<Iterator, Compare, Projection>
-void timsort(Iterator first, Sentinel last,
-             Compare comp={}, Projection proj={}) {
+auto timsort(Iterator first, Sentinel last,
+             Compare comp={}, Projection proj={})
+    -> Iterator
+{
     auto last_it = std::ranges::next(first, last);
     detail::TimSort<Iterator, Compare, Projection>::sort(first, last_it, comp, proj);
     GFX_TIMSORT_AUDIT(std::is_sorted(first, last_it, comp, proj) && "Postcondition");
+    return last_it;
 }
 
 /**
@@ -751,8 +758,10 @@ template <
     typename Projection = std::identity
 >
     requires std::sortable<std::ranges::iterator_t<Range>, Compare, Projection>
-void timsort(Range &&range, Compare comp={}, Projection proj={}) {
-    gfx::timsort(std::begin(range), std::end(range), comp, proj);
+auto timsort(Range &&range, Compare comp={}, Projection proj={})
+    -> std::ranges::borrowed_iterator_t<Range>
+{
+    return gfx::timsort(std::begin(range), std::end(range), comp, proj);
 }
 
 } // namespace gfx

tests/cxx_20_tests.cpp

@@ -8,6 +8,7 @@
 #include <random>
 #include <span>
 #include <vector>
+#include <utility>
 #include <catch2/catch_test_macros.hpp>
 #include <gfx/timsort.hpp>
 #include "test_helpers.hpp"
@@ -23,17 +24,33 @@ TEST_CASE( "support for temporary types" ) {
         gfx::timsort(middle, vec.end());
 
         auto view = std::span(vec);
-        gfx::timmerge(std::span(vec), view.begin() + 38);
+        auto last_it = gfx::timmerge(std::span(vec), view.begin() + 38);
         CHECK(std::ranges::is_sorted(vec));
+        CHECK(last_it == view.end());
     }
 
     SECTION( "timsort over std::span" ) {
         std::vector<int> vec(50);
         std::iota(vec.begin(), vec.end(), -25);
         test_helpers::shuffle(vec);
 
-        gfx::timsort(std::span(vec));
+        auto last_it = gfx::timsort(std::span(vec));
         CHECK(std::ranges::is_sorted(vec));
+        CHECK(last_it == std::span(vec).end());
+    }
+}
+
+TEST_CASE( "dangling return type" ) {
+    SECTION( "timmerge over temporary std::vector" ) {
+        std::vector<int> vec(30, 5);
+        auto last_it = gfx::timmerge(std::move(vec), vec.begin() + 14);
+        STATIC_CHECK(std::is_same_v<decltype(last_it), std::ranges::dangling>);
+    }
+
+    SECTION( "timsort over temporary std::vector" ) {
+        std::vector<int> vec(50, 8);
+        auto last_it = gfx::timsort(std::move(vec));
+        STATIC_CHECK(std::is_same_v<decltype(last_it), std::ranges::dangling>);
     }
 }
 
@@ -48,19 +65,23 @@ TEST_CASE( "support for sentinels" )
         gfx::timsort(vec.begin(), middle);
         gfx::timsort(middle, vec.end());
 
-        gfx::timmerge(std::counted_iterator(vec.begin(), 85),
-                      std::counted_iterator(middle, 85 - 38),
-                      std::default_sentinel);
+        auto last_it = gfx::timmerge(std::counted_iterator(vec.begin(), 85),
+                                     std::counted_iterator(middle, 85 - 38),
+                                     std::default_sentinel);
         CHECK(std::is_sorted(vec.begin(), vec.begin() + 85));
+        CHECK(last_it == std::counted_iterator(vec.begin() + 85, 0));
+        CHECK(last_it == std::default_sentinel);
     }
 
     SECTION( "timsort with sentinel" ) {
         std::vector<int> vec(100);
         std::iota(vec.begin(), vec.end(), -25);
         test_helpers::shuffle(vec);
 
-        gfx::timsort(std::counted_iterator(vec.begin(), 85),
-                     std::default_sentinel);
+        auto last_it = gfx::timsort(std::counted_iterator(vec.begin(), 85),
+                                    std::default_sentinel);
         CHECK(std::is_sorted(vec.begin(), vec.begin() + 85));
+        CHECK(last_it == std::counted_iterator(vec.begin() + 85, 0));
+        CHECK(last_it == std::default_sentinel);
     }
 }