std::clamp

Определено в заголовочном файле `<algorithm>`
template< class T > constexpr const T& clamp( const T& v, const T& lo, const T& hi );	(1)	(начиная с C++17)
template< class T, class Compare > constexpr const T& clamp( const T& v, const T& lo, const T& hi, Compare comp );	(2)	(начиная с C++17)

Если значение v находится в пределах [lo, hi], возвращает v; в противном случае возвращает ближайшую границу.

1) Для сравнения значений используется operator<(до C++20)std::less{}(начиная с C++20).

Если T не соответствует требованиям LessThanComparable, поведение не определено.^[1]

2) Для сравнения значений используется функция сравнения comp.

Если lo больше hi, поведение не определено.

Если удаётся избежать NaN, T может быть типом с плавающей точкой.

Параметры

v - значение, которое нужно ограничить

lo, hi - границы, которыми ограничивается v

comp

объект функции сравнения (то есть объект, удовлетворяющий требованиям Compare), который возвращает true, если первый аргумент меньше второго.

Сигнатура функции сравнения должна быть эквивалентна следующей:

boolcmp(constType1&a,constType2&b);

Хотя сигнатура не обязана содержать const&, функция не должна изменять переданные ей объекты и должна принимать любые значения типа (возможно, const) Type1 и Type2 независимо от категории значения (таким образом, Type1& не допускается, как и Type1, если только для Type1 перемещение не эквивалентно копированию(начиная с C++11)).
Типы Type1 и Type2 должны быть такими, чтобы объект типа T можно было неявно преобразовать в каждый из них.

Возвращаемое значение

Ссылка на lo, если v меньше lo; ссылка на hi, если hi меньше v; в противном случае ссылка на v.

Сложность

1) Не более двух сравнений с использованием operator<(до C++20)std::less{}(начиная с C++20).

2) Не более двух вызовов функции сравнения comp.

Возможная реализация

clamp (1)
template<class T> constexpr const T& clamp(const T& v, const T& lo, const T& hi) { return clamp(v, lo, hi, less{}); }
clamp (2)
template<class T, class Compare> constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp) { return comp(v, lo) ? lo : comp(hi, v) ? hi : v; }

clamp (1)

template<class T>
constexpr const T& clamp(const T& v, const T& lo, const T& hi)
{
    return clamp(v, lo, hi, less{});
}

clamp (2)

template<class T, class Compare>
constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp)
{
    return comp(v, lo) ? lo : comp(hi, v) ? hi : v;
}

Примечания

Если сохранить результат std::clamp по ссылке, получится висячая ссылка, если один из параметров является временным объектом и возвращается именно этот параметр:

int n = -1;
const int& r = std::clamp(n, 0, 255); // r is dangling

Если v сравнимо и эквивалентно одной из границ, возвращается ссылка на v, а не на границу.

Макрос проверки возможностей	Значение	Стандарт	Возможность
`__cpp_lib_clamp`	`201603L`	(C++17)	`std::clamp`

Пример

#include <algorithm>
#include <cstdint>
#include <iomanip>
#include <iostream>

int main()
{
    std::cout << "[raw] "
                 "[" << INT8_MIN << ',' << INT8_MAX << "] "
                 "[0," << UINT8_MAX << "]\n";

    for (const int v : {-129, -128, -1, 0, 42, 127, 128, 255, 256})
        std::cout << std::setw(4) << v
                  << std::setw(11) << std::clamp(v, INT8_MIN, INT8_MAX)
                  << std::setw(8) << std::clamp(v, 0, UINT8_MAX) << '\n';
}

Вывод:

[raw] [-128,127] [0,255]
-129       -128       0
-128       -128       0
  -1         -1       0
   0          0       0
  42         42      42
 127        127     127
 128        127     128
 255        127     255
 256        127     255

См. также

min	возвращает меньшее из заданных значений (шаблон функции и функциональный объект алгоритма)
ranges::min (C++20)
max	возвращает большее из заданных значений (шаблон функции и функциональный объект алгоритма)
ranges::max (C++20)
in_range (C++20)	проверяет, входит ли целочисленное значение в диапазон заданного целочисленного типа (шаблон функции)
ranges::clamp (C++20)	ограничивает значение парой граничных значений (функциональный объект алгоритма)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/algorithm/clamp