Morwenn/cpp-sort: v2.1.0 — Brewing

New year, new version of cpp-sort. Earlier this week, I once again got the opportunity to help a friend brew beer, learning a few things along the way, both the technical gestures and the biological and chemical processes underpinning the whole thing. Getting a better grasp of that and getting to taste the raw sugary barley juice obtained after the amylase has done its job inspired me new ideas that could lead to fun experiments in the field of biscuits. Beer isn't the only thing that has been brewing lately: algorithms also got their share of love.

I promised that new features would be coming to the library, and it was time to deliver: this release brings a new measure of disorder to the table, which is actually a hobby research project of mine—I wrote a few articles about it on my blog, The Sparkelling Bedangler, as well as about measures of disorder in general. The library's documentation even benefited from some illustrations I made for the blog to make explanations more palatable.

I also decided to add various sorting-related features to the utility:: namespace, which could be useful to analyze existing sorting algorithms, or bugs related to them, with the goal of helping sorting algorithm authors. I plan to add more such tools in the future: the library originally tried to add lots of useful sorters, but there's simply too many interesting sorting algorithms being released every other day, and I could never keep up with that. Helping authors analyze and refine their own algorithms surely is a more useful goal for the library.

Finally, this release also advanced a topic that's entirely orthogonal to computer science: tooling compatibility. The documentation had long been readable offline with Gollum, but I had treated it as a second-class citizen so far. This time I tried to give it some more love; the result isn't issue-free, but tables, images and mathematics equations render much better than they used to. The whole project is now also mirrored on Codeberg with a bidirectional push mechanism to and from the GitHub mirror. If you want to contribute but would rather avoid GitHub for a reason or another, you can do so from Codeberg. The only big issue is the lack of a rich CI compared to GitHub, which means that there might be a bit of back-and-forth if platform-specific bugs are introduced.

New features

New feature: probe::amp: $\textit{Amp}(X)$ is a new measure of disorder defined in terms of the following function:

$$ \mathit{comp}(x, y)= \begin{cases} 1 & \text{ if } x \lt y\ -1 & \text{ if } x \gt y\ 0 & \text{otherwise} \end{cases} $$

We define $\mathit{Amp}(X)$ as follows:

$$\mathit{Amp}(X) = \lvert X \rvert - \mathit{PTP}(X) - N_{\mathit{eq}}(X) - 1$$

Where $N_{\mathit{eq}}(X)$ is the number of pairs of neighbors that compare equivalent in the sequence $X$, and $\mathit{PTP}(X)$ is the number of unique values in the prefix sum of the sequence obtained by applying $comp$ to every pair of adjacent elements in $X$.

This new measure is not especially useful right now, but having it as a first-class citizen of the library makes things simpler for me when I attempt to analyze it further.

New feature: utility::quicksort_adversary: this function template implements an algorithm described by M. D. McIlroy in A Killer Adversary for Quicksort, which attempts to trigger the quadratic case of many quicksort implementations by trying to guess the pivot and forcing the tested algorithm to perform a certain set of comparisons.

Example: trying to force the library's quick_sorter to go quadratic over a collection of 1000 elements (which does not actually work, because that sorter falls back to median pivot selection after encountering too many bad partitions):

auto sorter = cppsort::metrics::comparisons(cppsort::quick_sort);
auto comps = cppsort::utility::quicksort_adversary(sorter, 1000);
std::print("Comparisons: {}", comps.value());

New feature: utility::check_strick_weak_ordering: this function object implements an algorithm described by Danila Kutenin in their quadratic_strict_weak_ordering project. It can be used to check whether a given comparison function implements a strict weak ordering over the values of a given range of elements.

std::vector<int> vec = { 1, 4, 32, 5, 1, 89, 43, 56, 8, 7, 2, 2, 4, 44, 37, 73 };
// <= does not model a strict weak ordering over integers
assert(not check_strict_weak_ordering(vec, std::less_equal{}));

New feature: utility::is_sorted and utility::is_sorted_until: those function objects are reimplementations of the standard library's std::is_sorted and std::is_sorted_until algorithms, benefiting from the library's unified sorting interface (see the library nomenclature in the attached wiki).

Bug fix

float_spread_sorter: apply a commit from upstream which fixes an integer overflow bug.

Improvements

• Add [[clang::lifetimebound]] and [[msvc::lifetimebound]] where it makes sense. It affects user-facing functions in the following components:
  • utility::adapter_storage::get()
  • utility::metric and utility::metrics
  • utility::identity
• Wrap calls to std::min and std::max with parentheses, making it possible to use the library even when <windows.h> is included without defining NOMINMAX first. This affects the following components:
  • grail_sorter
  • probe::dis

Tooling

Documentation:

• Add better descriptions with illustrations for the measures of disorder probe::exc and probe::osc.
• Add a section about metrics to the quickstart page.
• Fixed the rendering of math expressions and of some images with Gollum. This makes it possible to browse the documentation while offline with an experience almost as smooth as on the online wiki.
• Fixed kerning of math expressions, correctly marking words as such. It also improves word selection and copy-pasting of math expressions.
• Add a redirect file from the old measures of presortedness page to the new measures of disorder one. That redirection only works with Gollum, because GitHub wikis don't support redirection.
• Detect and fix dead links in the documentation.

Test suite:

• The test suite now tests the internal implementations of nth_element, gaining a rare percent of line coverage.
• Upgrade downloaded version of Catch2 to v3.12.0.

Miscellaneous:

• cpp-sort now has an official Codeberg mirror, another Git forge. It is bidirectional: code pushed to the GitHub repository is mirrored to Codeberg, but it also works the other way around. Contributors can target either forge with issues or pull requests, but should be aware that only the GitHub repository has an actual CI so far.
• Mark libassert as a SYSTEM library in CMake.
• CI: upgrade MacOS image to macos-14, and the corresponding GCC version to GCC13.
• The errorbar-plot benchmark legend now displays sorters in alphabetical order.

Known bugs

I didn't manage to fix every bug I could find since the previous release, so you might want to check the list of known bugs.