beman.at_most: Safe versions of partial_sort and get_nth_element (P3735)

beman.at_most is (... TODO: description).

Implements: partial_sort_at_most and nth_element_at_most proposed in partial_sort_at_most, nth_element_at_most (P3735R1).

Status: Under development and not yet ready for production use.

License

beman.at_most is licensed under the Apache License v2.0 with LLVM Exceptions.

Usage

partial_sort_at_most and nth_element_at_most provide safer, count-based alternatives to partial_sort and nth_element.

Usage: partial_sort_at_most

The following code snippet illustrates how we can sort the "at most" 3 smallest elements of a vector:

#include <beman/at_most/at_most.hpp>
#include <vector>
#include <iostream>

int main() {
    std::vector<int> v = {5, 4, 3, 2, 1};

    // Sort at most 3 elements
    beman::at_most::partial_sort_at_most(v.begin(), v.end(), 3);

    // Output: 1 2 3 5 4 (first 3 are sorted)
    for (int x : v)
        std::cout << x << " ";
    std::cout << "\n";

    return 0;
}

Full runnable examples can be found in examples/.

Dependencies

Build Environment

This project requires at least the following to build:

• A C++ compiler that conforms to the C++20 standard or greater
• CMake 3.30 or later
• (Test Only) GoogleTest

You can disable building tests by setting CMake option BEMAN_AT_MOST_BUILD_TESTS to OFF when configuring the project.

Supported Platforms

Compiler	Version	C++ Standards	Standard Library
GCC	16-13	C++26-C++20	libstdc++
GCC	12-11	C++23, C++20	libstdc++
Clang	22-19	C++26-C++20	libstdc++, libc++
Clang	18	C++26-C++20	libc++
Clang	18	C++23, C++20	libstdc++
Clang	17	C++26-C++20	libc++
Clang	17	C++20	libstdc++
AppleClang	latest	C++26-C++20	libc++
MSVC	latest	C++23	MSVC STL

Development

See the Contributing Guidelines.

Integrate beman.at_most into your project

Build

You can build at_most using a CMake workflow preset:

cmake --workflow --preset gcc-release

To list available workflow presets, you can invoke:

cmake --list-presets=workflow

For details on building beman.at_most without using a CMake preset, refer to the Contributing Guidelines.

Installation

Vcpkg

The preferred way to install at_most is via vcpkg. To do so, after installing vcpkg itself, you need to add support for the Beman project's vcpkg registry by configuring a vcpkg-configuration.json file (which at_most provides).

Then, simply run vcpkg install beman-at-most.

Manual

To install beman.at_most globally after building with the gcc-release preset, you can run:

sudo cmake --install build/gcc-release

Alternatively, to install to a prefix, for example /opt/beman, you can run:

sudo cmake --install build/gcc-release --prefix /opt/beman

This will generate the following directory structure:

/opt/beman
├── include
│   └── beman
│       └── at_most
│           ├── at_most.hpp
│           └── ...
└── lib
    └── cmake
        └── beman.at_most
            ├── beman.at_most-config-version.cmake
            ├── beman.at_most-config.cmake
            └── beman.at_most-targets.cmake

CMake Configuration

If you installed beman.at_most to a prefix, you can specify that prefix to your CMake project using CMAKE_PREFIX_PATH; for example, -DCMAKE_PREFIX_PATH=/opt/beman.

You need to bring in the beman.at_most package to define the beman::at_most CMake target:

find_package(beman.at_most REQUIRED)

You will then need to add beman::at_most to the link libraries of any libraries or executables that include beman.at_most headers.

target_link_libraries(yourlib PUBLIC beman::at_most)

Using beman.at_most

To use beman.at_most in your C++ project, include an appropriate beman.at_most header from your source code.

#include <beman/at_most/at_most.hpp>