Add range overloads to gfx::timsort

Author: Morwenn

README.md

@@ -16,14 +16,37 @@ According to the benchmarks, it is slower than `std::sort()` on randomized seque
 ones. `gfx::timsort` should be usable as a drop-in replacement for `std::stable_sort`, with the difference that it
 can't fallback to a O(n log² n) algorithm when there isn't enough extra heap memory available.
 
-Additionally `gfx::timsort` can take a [projection function](https://ezoeryou.github.io/blog/article/2019-01-22-ranges-projection.html)
-after the comparison function. The support is a bit rougher than in the linked article or the C++20 standard library:
-unless `std::invoke` is available, only instances of types callable with parentheses can be used, there is no support
-for pointer to members.
+`gfx::timsort` also has a few additional features and guarantees compared to `std::stable_sort`:
+* It can take a [projection function](https://ezoeryou.github.io/blog/article/2019-01-22-ranges-projection.html)
+  after the comparison function. The support is a bit rougher than in the linked article or the C++20 standard library:
+  unless `std::invoke` is available, only instances of types callable with parentheses can be used, there is no support
+  for pointer to members.
+* It can also be passed a range instead of a pair of iterators, in which case it will sort the whole range.
+* This implementation of timsort notably avoids using the postfix `++` or `--` operators: only their prefix equivalents
+  are used, which means that timsort will work even if the postfix operators are not present or return an incompatible
+  type such as `void`.
 
-This implementation of timsort notably avoids using the postfix `++` or `--` operators: only their prefix equivalents
-are used, which means that timsort will work even if the postfix operators are not present or return an incompatible
-type such as `void`.
+
+The full list of available signatures is as follows (in namespace `gfx`):
+
+```cpp
+// Overloads taking a pair of iterators
+template <typename RandomAccessIterator>
+void timsort(RandomAccessIterator const first, RandomAccessIterator const last);
+template <typename RandomAccessIterator, typename Compare>
+void timsort(RandomAccessIterator const first, RandomAccessIterator const last,
+             Compare compare);
+template <typename RandomAccessIterator, typename Compare, typename Projection>
+void timsort(RandomAccessIterator const first, RandomAccessIterator const last,
+             Compare compare, Projection projection);
+// Overloads taking a range
+template <typename RandomAccessRange>
+void timsort(RandomAccessRange &range);
+template <typename RandomAccessRange, typename Compare>
+void timsort(RandomAccessRange &range, Compare compare);
+template <typename RandomAccessRange, typename Compare, typename Projection>
+void timsort(RandomAccessRange &range, Compare compare, Projection projection);
+```
 
 ## EXAMPLE
 
@@ -39,9 +62,8 @@ size_t len(const std::string& str) {
 }
 
 // Sort a vector of strings by length
-std::vector<std::string> vec;
-// ... fill vec ...
-gfx::timsort(vec.begin(), vec.end(), std::less<size_t>(), &len);
+std::vector<std::string> collection = { /* ... */ };
+gfx::timsort(collection, std::less<std::string>{}, &len);
 ```
 
 ## COMPATIBILITY

include/gfx/timsort.hpp

@@ -676,6 +676,7 @@ template <typename RandomAccessIterator, typename Compare> class TimSort {
 
 } // namespace detail
 
+
 // ---------------------------------------
 // Public interface implementation
 // ---------------------------------------
@@ -687,8 +688,8 @@ template <typename RandomAccessIterator, typename Compare, typename Projection>
 void timsort(RandomAccessIterator const first, RandomAccessIterator const last,
              Compare compare, Projection projection) {
     typedef detail::projection_compare<Compare, Projection> compare_t;
-    compare_t comp(compare, projection);
-    detail::TimSort<RandomAccessIterator, compare_t>::sort(first, last, comp);
+    compare_t comp(std::move(compare), std::move(projection));
+    detail::TimSort<RandomAccessIterator, compare_t>::sort(first, last, std::move(comp));
 }
 
 /**
@@ -708,6 +709,30 @@ void timsort(RandomAccessIterator const first, RandomAccessIterator const last)
     gfx::timsort(first, last, std::less<value_type>(), detail::identity());
 }
 
+/**
+ * Stably sorts a range with a comparison function and a projection function.
+ */
+template <typename RandomAccessRange, typename Compare, typename Projection>
+void timsort(RandomAccessRange &range, Compare compare, Projection projection) {
+    gfx::timsort(std::begin(range), std::end(range), compare, projection);
+}
+
+/**
+ * Same as std::stable_sort(std::begin(range), std::end(range), compare).
+ */
+template <typename RandomAccessRange, typename Compare>
+void timsort(RandomAccessRange &range, Compare compare) {
+    gfx::timsort(std::begin(range), std::end(range), compare);
+}
+
+/**
+ * Same as std::stable_sort(std::begin(range), std::end(range)).
+ */
+template <typename RandomAccessRange>
+void timsort(RandomAccessRange &range) {
+    gfx::timsort(std::begin(range), std::end(range));
+}
+
 } // namespace gfx
 
 #undef GFX_TIMSORT_ENABLE_ASSERT

tests/cxx_11_tests.cpp

@@ -6,6 +6,7 @@
  */
 #include <algorithm>
 #include <deque>
+#include <numeric>
 #include <stdexcept>
 #include <utility>
 #include <vector>
@@ -139,3 +140,26 @@ TEST_CASE( "issue14" ) {
     gfx::timsort(std::begin(c), std::end(c));
     CHECK(std::is_sorted(std::begin(c), std::end(c)));
 }
+
+TEST_CASE( "range signatures" ) {
+    std::vector<int> vec(50, 0);
+    std::iota(vec.begin(), vec.end(), -25);
+    std::random_shuffle(vec.begin(), vec.end());
+
+    SECTION( "range only" ) {
+        gfx::timsort(vec);
+        CHECK(std::is_sorted(vec.begin(), vec.end()));
+    }
+
+    SECTION( "range with a comparison function" ) {
+        using value_type = std::vector<int>::value_type;
+        gfx::timsort(vec, std::greater<value_type>{});
+        CHECK(std::is_sorted(vec.begin(), vec.end(), std::greater<value_type>{}));
+    }
+
+    SECTION( "range with comparison and projection functions" ) {
+        using value_type = std::vector<int>::value_type;
+        gfx::timsort(vec, std::greater<value_type>{}, std::negate<value_type>{});
+        CHECK(std::is_sorted(vec.begin(), vec.end()));
+    }
+}