Add a quicksort_adversary utility (#178)

Author: Morwenn

README.md

@@ -229,6 +229,9 @@ discussion](https://stackoverflow.com/q/2786899/1364752) on StackOverflow and ar
 backed by the article [*Applying Sorting Networks to Synthesize Optimized Sorting
 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 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)

docs/Miscellaneous-utilities.md

@@ -367,6 +367,31 @@ auto m = get<foo_tag>(mm);
 
 `utility::metrics` is still mostly experimental and unused in the rest of the library. As such this documentation is voluntarily thin.
 
+### `quicksort_adversary`
+
+```cpp
+#include <cpp-sort/utility/quicksort_adversary.h>
+```
+
+`utility::quicksort_adversary` is a function template that implements an algorithm described by M. D. McIlroy in [*A Killer Adversary for Quicksort*][quicksort-adversary], which attempts to trigger the quadratic case of many quicksort implementations by trying to guess the pivot and forcing the testing comparison to perform a certain set of comparisons.
+
+```cpp
+template<typename Sorter, typename Integer>
+auto quicksort_adversary(Sorter&& sorter, Integer size);
+```
+
+The function accepts a sorter to test, and a parameter corresponding to the size of the input for which we wish to test the sorter. It then instantiates a collection of `size` elements of `Integer` type that it passes to `sorter`, and returns the result of the operation. It additionally passes a custom comparison function to `sorter`, which means that it only works with *comparison sorters*.
+
+It can be used together with [`metrics::comparisons`][metrics-comparisons] or some other metrics to analyze the number of operations performed, and attempt to detect quadratic behavior in quicksort-like sorters:
+
+```cpp
+auto sorter = cppsort::metrics::comparisons(cppsort::quick_sort);
+auto comps = cppsort::utility::quicksort_adversary(sorter, 1000);
+std::print("Comparisons: {}", comps.value());
+```
+
+*New in version 2.1.0*
+
 ### `size`
 
 ```cpp
@@ -474,9 +499,11 @@ auto swap_index_pairs_force_unroll(RandomAccessIterator first,
   [fixed-size-sorters]: Fixed-size-sorters.md
   [is-stable]: Sorter-traits.md#is_stable
   [metrics]: Metrics.md
+  [metrics-comparisons]: Metrics.md#comparisons
   [numpy-argsort]: https://numpy.org/doc/stable/reference/generated/numpy.argsort.html
   [p0022]: https://wg21.link/P0022
   [pdq-sorter]: Sorters.md#pdq_sorter
+  [quicksort-adversary]: https://www.cs.dartmouth.edu/~doug/mdmspe.pdf
   [range-v3]: https://github.com/ericniebler/range-v3
   [sorter-adapters]: Sorter-adapters.md
   [sorters]: Sorters.md

include/cpp-sort/utility/quicksort_adversary.h

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2025 Morwenn
+ * SPDX-License-Identifier: MIT
+ */
+#ifndef CPPSORT_QUICKSORT_ADVERSARY_H_
+#define CPPSORT_QUICKSORT_ADVERSARY_H_
+
+////////////////////////////////////////////////////////////
+// Headers
+////////////////////////////////////////////////////////////
+#include <numeric>
+#include <vector>
+
+namespace cppsort::utility
+{
+    // Implementation of a quicksort adversary as described by M. D. McIlroy
+    // in *A Killer Adversary for Quicksort*
+
+    template<typename Sorter, typename Integer>
+    auto quicksort_adversary(Sorter&& sorter, Integer size)
+    {
+        Integer solid = 0;
+        auto gas = size - 1;
+        std::vector<Integer> elements(size, gas);
+
+        std::vector<Integer> values(size, 0);
+        std::iota(values.begin(), values.end(), 0);
+
+        int pivot_candidate = size; // Too big to match any
+        return sorter(values, [&, gas](Integer lhs_idx, Integer rhs_idx) {
+            int& lhs = elements[lhs_idx];
+            int& rhs = elements[rhs_idx];
+            if (lhs == gas && rhs == gas) {
+                if (lhs_idx == pivot_candidate) {
+                    lhs = solid++;
+                } else {
+                    rhs = solid++;
+                }
+            }
+            if (lhs == gas) {
+                pivot_candidate = lhs_idx;
+            } else if (rhs == gas) {
+                pivot_candidate = rhs_idx;
+            }
+            return lhs < rhs;
+        });
+    }
+}
+
+#endif // CPPSORT_QUICKSORT_ADVERSARY_H_

tests/CMakeLists.txt

@@ -266,6 +266,7 @@ add_executable(main-tests
     utility/chainable_projections.cpp
     utility/iter_swap.cpp
     utility/metric_tools.cpp
+    utility/quicksort_adversary.cpp
     utility/sorted_indices.cpp
     utility/sorted_iterators.cpp
     utility/sorting_networks.cpp

tests/utility/quicksort_adversary.cpp

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2025 Morwenn
+ * SPDX-License-Identifier: MIT
+ */
+#include <algorithm>
+#include <iterator>
+#include <vector>
+#include <catch2/catch_template_test_macros.hpp>
+#include <cpp-sort/detail/iter_sort3.h>
+#include <cpp-sort/sorters.h>
+#include <cpp-sort/metrics/comparisons.h>
+#include <cpp-sort/utility/functional.h>
+#include <cpp-sort/utility/quicksort_adversary.h>
+
+TEMPLATE_TEST_CASE( "test quicksort-based sorters with quicksort_adversary", "[utility][quicksort_adversary]",
+                    cppsort::pdq_sorter,
+                    cppsort::quick_merge_sorter,
+                    cppsort::quick_sorter,
+                    cppsort::std_sorter )
+{
+    cppsort::metrics::comparisons<TestType> sorter;
+    auto comps = cppsort::utility::quicksort_adversary(sorter, 1000);
+    CHECK( comps < 100'000 ); // Guesstimate between n and n²
+}
+
+namespace
+{
+    // Median-of-three quicksort
+    template<typename Iterator, typename Compare>
+    auto median_of_3_quicksort(Iterator first, Iterator last, Compare comp)
+        -> void
+    {
+        auto size = last - first;
+        if (size < 2) return;
+
+        auto middle = first + size / 2;
+        auto pivot_pos = cppsort::detail::iter_sort3(
+            first, middle, last - 1,
+            comp, cppsort::utility::identity{}
+        );
+
+        iter_swap(pivot_pos, last - 1);
+        auto middle1 = std::partition(
+            first, last - 1,
+            [&](int& value) { return comp(value, *(last - 1)); }
+        );
+
+        iter_swap(middle1, last - 1);
+        auto middle2 = std::partition(
+            std::next(middle1), last,
+            [&](int& value) { return not comp(*middle1, value); }
+        );
+
+        median_of_3_quicksort(first, middle1, comp);
+        median_of_3_quicksort(middle2, last, comp);
+    }
+}
+
+
+TEST_CASE( "quicksort adversary over a simple quicksort",
+           "[utility][quicksort_adversary]" )
+{
+    auto do_sort = [](std::vector<int>& vec, auto comp) {
+        return median_of_3_quicksort(vec.begin(), vec.end(), comp);
+    };
+    auto sorter = cppsort::metrics::comparisons(do_sort);
+    auto comps = cppsort::utility::quicksort_adversary(sorter, 100);
+    CHECK( comps > 5000 ); // Guesstimate over n²
+}