Add utility::check_strict_weak_ordering

Morwenn · Morwenn · commit b49b5ec8afe8 · 2026-01-11T20:28:51.000+01:00
diff --git a/README.md b/README.md
@@ -231,6 +231,8 @@ Libraries*](https://arxiv.org/abs/1505.01962).
 * The algorithm behind `utility::quicksort_adversary` is a fairly straightforward adaptation of the
 one provided by M. D. McIlroy in [*A Killer Adversary for Quicksort*](https://www.cs.dartmouth.edu/~doug/mdmspe.pdf).
 
+* The algorithm used by [`utility::check_strict_weak_ordering`][utility-check-strict-weak-ordering] is a reimplementation of the one desribed in the README file of danlark1's [quadratic_strict_weak_ordering project](https://github.com/danlark1/quadratic_strict_weak_ordering).
+
 * The test suite reimplements random number algorithms originally found in the following places:
   - [xoshiro256\*\*](https://prng.di.unimi.it/)
   - [*Optimal Discrete Uniform Generation from Coin Flips, and Applications*](https://arxiv.org/abs/1304.1916)
@@ -261,3 +263,4 @@ developed by Thøger Rivera-Thorsen.
   [split-adapter]: https://codeberg.org/Morwenn/cpp-sort/wiki/Sorter-adapters#split_adapter
   [tooling]: https://codeberg.org/Morwenn/cpp-sort/wiki/Tooling
   [utility-as-function]: https://codeberg.org/Morwenn/cpp-sort/wiki/Miscellaneous-utilities#as_function
+  [utility-check-strict-weak-ordering]: https://codeberg.org/Morwenn/cpp-sort/wiki/Miscellaneous-utilities#strict-weak-ordering-checker
diff --git a/docs/Miscellaneous-utilities.md b/docs/Miscellaneous-utilities.md
@@ -491,6 +491,31 @@ auto swap_index_pairs_force_unroll(RandomAccessIterator first,
 
 `swap_index_pairs` loops over the index pairs in the simplest fashion and calls the compare-exchange operations in the simplest possible way. `swap_index_pairs_force_unroll` is a best effort function trying to achieve the same job by unrolling the loop over indices the best it can - a perfect unrolling is thus attempted, but never guaranteed, which might or might not result in faster runtime and/or increased binary size.
 
+## Strict weak ordering checker
+
+```cpp
+#include <cpp-sort/utility/check_strict_weak_ordering.h>
+```
+
+Comparison sorting requires the comparison function to model a [strict weak ordering][strict-weak-ordering] over the values of the range to sort. Otherwise, the sorting algorithm might fail to sort the collection, or encounter even fail in hard-to-predict ways, potentially invoking undefined behavior.
+
+Checking whether a comparison function models such an ordering for a given is an expensive task, which means that it is remains an unchecked precondition of algorithms in the library. If you suspect that a bug with a comparison sort might be linked to a violation of the strict weak ordering by the comparison function, you can use `utility::check_strict_weak_ordering` to analyze it over a given range:
+
+```cpp
+std::vector<double> vec = { 1.0, 9.0, std::nan("1"), 11.5, 56.3, 2.8 };
+assert(not cppsort::utility::check_strict_weak_ordering(vec, std::less{});)
+```
+
+`check_strict_weak_ordering` is a function object that follows the *unified sorting interface*: it takes a range of elements and a comparison function (and optionally a projection function). When called, it returns `true` if the passed comparison function models a strict weak ordering over the values of the input range, and `false` otherwise.
+
+**WARNING: `check_strict_weak_ordering` alters the input range.**
+
+| Time | Memory | Iterators     |
+| ---- | ------ | ------------- |
+| n²   | 1      | Random-access |
+
+*New in version 2.1.0*
+
 
   [apply-permutation]: Miscellaneous-utilities.md#apply_permutation
   [chainable-projections]: Chainable-projections.md
@@ -524,4 +549,5 @@ auto swap_index_pairs_force_unroll(RandomAccessIterator first,
   [std-ranges-greater]: https://en.cppreference.com/w/cpp/utility/functional/ranges/greater
   [std-ranges-less]: https://en.cppreference.com/w/cpp/utility/functional/ranges/less
   [std-size]: https://en.cppreference.com/w/cpp/iterator/size
+  [strict-weak-ordering]: https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings
   [transparent-func]: Comparators-and-projections.md#Transparent-function-objects
diff --git a/include/cpp-sort/utility/check_strict_weak_ordering.h b/include/cpp-sort/utility/check_strict_weak_ordering.h
@@ -0,0 +1,127 @@
+/*
+ * Copyright (c) 2026 Morwenn
+ * SPDX-License-Identifier: MIT
+ */
+#ifndef CPPSORT_UTILITY_CHECK_STRICT_WEAK_ORDERING_H_
+#define CPPSORT_UTILITY_CHECK_STRICT_WEAK_ORDERING_H_
+
+////////////////////////////////////////////////////////////
+// Headers
+////////////////////////////////////////////////////////////
+#include <functional>
+#include <iterator>
+#include <utility>
+#include <cpp-sort/sorter_facade.h>
+#include <cpp-sort/sorter_traits.h>
+#include <cpp-sort/utility/functional.h>
+#include "../detail/heapsort.h"
+#include "../detail/is_sorted_until.h"
+#include "../detail/type_traits.h"
+
+#include <cassert>
+
+namespace cppsort::utility
+{
+    ////////////////////////////////////////////////////////////
+    // Check whether a comparison function implements a strict
+    // weak ordering over a range of data, following an
+    // algorithm described by danlark1 here:
+    // https://github.com/danlark1/quadratic_strict_weak_ordering
+
+    namespace detail
+    {
+        template<typename ForwardIterator, typename Compare, typename Projection>
+        constexpr auto compare_equivalent(ForwardIterator it1, ForwardIterator it2,
+                                          Compare compare, Projection projection)
+            -> bool
+        {
+            return not compare(projection(*it1), projection(*it2))
+                && not compare(projection(*it2), projection(*it1));
+        }
+
+        struct strict_weak_ordering_checker_impl
+        {
+            template<
+                typename ForwardIterator,
+                typename Compare = std::less<>,
+                typename Projection = utility::identity,
+                typename = cppsort::detail::enable_if_t<
+                    is_projection_iterator_v<Projection, ForwardIterator, Compare>
+                >
+            >
+            constexpr auto operator()(ForwardIterator first, ForwardIterator last,
+                            Compare compare={}, Projection projection={}) const
+                -> bool
+            {
+                // In the comments below, we use the following abbreviations:
+                // - R is the input range
+                // - C is the comparison function
+                // - P is the projeciton function
+
+                auto&& comp = utility::as_function(compare);
+                auto&& proj = utility::as_function(projection);
+
+                while (first != last) {
+                    // 1. Sort R
+                    //
+                    // Note: standard library implementations of heapsort supposedly do not
+                    // crash when passed a comparison function that does not model a strict
+                    // weak ordering, and ours happens to be copy-pasted from libc++
+                    cppsort::detail::heapsort(first, last, compare, projection);
+
+                    // 2. If the R is not sorted, then C does not model a strict weak ordering
+                    if (not cppsort::detail::is_sorted(first, last, compare, projection)) {
+                        return false;
+                    }
+
+                    // 3. Find first it such as *first < *it
+                    auto it = std::next(first);
+                    while (it != last && not comp(proj(*first), proj(*it))) {
+                        ++it;
+                    }
+
+                    // 4. Check that all elements before it compare equivalent
+                    for (auto it1 = first; it1 != it; ++it1) {
+                        for (auto it2 = it1; it2 != it; ++it2) {
+                            if (not compare_equivalent(it1, it2, comp, proj)) {
+                                return false;
+                            }
+                        }
+                    }
+
+                    // 5. Check that all elements separated by it follow transitivity
+                    for (auto it1 = first; it1 != it; ++it1) {
+                        for (auto it2 = it; it2 != last; ++it2) {
+                            if (comp(proj(*it2), proj(*it1))) {
+                                return false;
+                            }
+                            if (not comp(proj(*it1), proj(*it2))) {
+                                return false;
+                            }
+                        }
+                    }
+
+                    // Exclude leading elements that compare equivalent,
+                    // start all over again with the rest of the elements
+                    first = it;
+                }
+
+                // All checks passed, C models a strict weak ordering over R
+                return true;
+            }
+
+            ////////////////////////////////////////////////////////////
+            // Sorter traits
+
+            using iterator_category = std::random_access_iterator_tag;
+        };
+    }
+
+    struct strict_weak_ordering_checker:
+        sorter_facade<detail::strict_weak_ordering_checker_impl>
+    {};
+
+    inline constexpr strict_weak_ordering_checker check_strict_weak_ordering{};
+}
+
+#endif // CPPSORT_UTILITY_CHECK_STRICT_WEAK_ORDERING_H_
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
@@ -1,4 +1,4 @@
-# Copyright (c) 2015-2025 Morwenn
+# Copyright (c) 2015-2026 Morwenn
 # SPDX-License-Identifier: MIT
 
 include(cpp-sort-utils)
@@ -263,6 +263,7 @@ add_executable(main-tests
     utility/branchless_traits.cpp
     utility/buffer.cpp
     utility/chainable_projections.cpp
+    utility/check_strict_weak_ordering.cpp
     utility/iter_swap.cpp
     utility/metric_tools.cpp
     utility/quicksort_adversary.cpp
diff --git a/tests/utility/check_strict_weak_ordering.cpp b/tests/utility/check_strict_weak_ordering.cpp
@@ -0,0 +1,95 @@
+/*
+ * Copyright (c) 2026 Morwenn
+ * SPDX-License-Identifier: MIT
+ */
+#include <cmath>
+#include <vector>
+#include <catch2/catch_test_macros.hpp>
+#include <cpp-sort/utility/check_strict_weak_ordering.h>
+#include <testing-tools/distributions.h>
+
+TEST_CASE( "check_strict_weak_ordering test", "[utility][check_strict_weak_ordering]" )
+{
+    using cppsort::utility::check_strict_weak_ordering;
+
+    SECTION( "empty collection" )
+    {
+        std::vector<int> vec = {};
+        CHECK( check_strict_weak_ordering(vec) );
+    }
+
+    SECTION( "one element" )
+    {
+        std::vector<int> vec = { 0 };
+        CHECK( check_strict_weak_ordering(vec) );
+    }
+
+    SECTION( "one element, NaN" )
+    {
+        std::vector<double> vec = { std::nan("1") };
+        CHECK( check_strict_weak_ordering(vec) );
+    }
+
+    SECTION( "empty collection" )
+    {
+        std::vector<int> vec = {};
+        CHECK( check_strict_weak_ordering(vec) );
+    }
+
+    SECTION( "two elements" )
+    {
+        std::vector<int> vec1 = { 0, 0 };
+        CHECK( check_strict_weak_ordering(vec1) );
+
+        std::vector<int> vec2 = { 0, 5 };
+        CHECK( check_strict_weak_ordering(vec2) );
+
+        std::vector<int> vec3 = { 5, 0 };
+        CHECK( check_strict_weak_ordering(vec3) );
+    }
+
+    SECTION( "two elements, NaN" )
+    {
+        std::vector<double> vec1 = { std::nan("1"), std::nan("1") };
+        CHECK( check_strict_weak_ordering(vec1) );
+
+        std::vector<double> vec2 = { std::nan("1"), 5 };
+        CHECK( check_strict_weak_ordering(vec2) );
+
+        std::vector<double> vec3 = { 5, std::nan("1") };
+        CHECK( check_strict_weak_ordering(vec3) );
+    }
+
+    SECTION( "small collection" )
+    {
+        std::vector<int> vec = { 1, 4, 32, 5, 89, 43, 56, 8, 7, 2, 44, 37, 73 };
+        CHECK( check_strict_weak_ordering(vec) );
+    }
+
+    SECTION( "small collection with duplicates" )
+    {
+        std::vector<int> vec = { 1, 4, 32, 5, 1, 89, 43, 56, 8, 7, 2, 2, 4, 44, 37, 73 };
+        CHECK( check_strict_weak_ordering(vec) );
+    }
+
+    SECTION( "small collection with NaN" )
+    {
+        std::vector<double> vec = {
+            1.0, 4.0, 32.0, 5.0, 89.0, 43.0, 56.0, 345.0,
+            8.0, 7.0, 2.0, std::nan("2"), 44.0, 37.0, 73.0,
+        };
+        CHECK_FALSE( check_strict_weak_ordering(vec) );
+    }
+
+    SECTION( "small collection with std::less_equal" )
+    {
+        std::vector<int> vec = { 1, 4, 32, 5, 89, 43, 56, 8, 7, 2, 44, 37, 73 };
+        CHECK_FALSE( check_strict_weak_ordering(vec, std::less_equal{}) );
+    }
+
+    SECTION( "small collection with duplicates with std::less_equal" )
+    {
+        std::vector<int> vec = { 1, 4, 32, 5, 1, 89, 43, 56, 8, 7, 2, 2, 4, 44, 37, 73 };
+        CHECK_FALSE( check_strict_weak_ordering(vec, std::less_equal{}) );
+    }
+}
