std::ranges::clamp
Объявлено в заголовочном файле <algorithm> | ||
|---|---|---|
| Сигнатура вызова | ||
template< class T, class Proj = std::identity,
std::indirect_strict_weak_order<std::projected<const T*, Proj>> Comp =
ranges::less >
constexpr const T&
clamp( const T& v, const T& lo, const T& hi, Comp comp = {}, Proj proj = {} );
| (начиная с C++20) |
Если значение v находится в пределах [lo, hi], возвращает v; в противном случае возвращает ближайшую границу.
Поведение не определено, если lo больше hi.
Описанные на этой странице сущности, подобные функциям, являются объектами-функциями алгоритмов (неофициально известными как niebloids
Параметры
v - значение, которое нужно ограничить
lo, hi - границы, которыми нужно ограничить
v comp - сравнение, применяемое к спроецированным элементам
proj - проекция, применяемая к
v, lo и hi Возвращаемое значение
Ссылка на lo, если спроецированное значение v меньше спроецированного значения lo; ссылка на hi, если спроецированное значение hi меньше спроецированного значения v; в противном случае ссылка на v.
Сложность
Не более двух сравнений и трёх применений проекции.
Возможная реализация
struct clamp_fn
{
template<class T, class Proj = std::identity,
std::indirect_strict_weak_order<std::projected<const T*, Proj>>
Comp = std::ranges::less>
constexpr const T& operator()(const T& v, const T& lo, const T& hi,
Comp comp = {}, Proj proj = {}) const
{
auto&& pv = std::invoke(proj, v);
if (std::invoke(comp, std::forward<decltype(pv)>(pv), std::invoke(proj, lo)))
return lo;
if (std::invoke(comp, std::invoke(proj, hi), std::forward<decltype(pv)>(pv)))
return hi;
return v;
}
};
inline constexpr clamp_fn clamp;
|
Примечания
Сохранение результата std::ranges::clamp по ссылке приводит к висячей ссылке, если один из параметров является временным объектом и возвращается этот параметр:
int n = -1; const int& r = std::ranges::clamp(n, 0, 255); // r is dangling
Если v эквивалентен одной из границ при сравнении, возвращается ссылка на v, а не на границу.
Эту функцию не следует использовать одновременно с проекцией, возвращающей значение, и компаратором, принимающим аргументы по значению, если только перемещение из типа результата проекции в тип параметра компаратора не эквивалентно копированию. Если сравнение посредством std::invoke изменяет результат проекции, поведение не определено из-за семантических требований std::regular_invocable (которые включает в себя std::indirect_strict_weak_order).
Стандарт требует сохранять категорию значения результата проекции, а proj можно вызвать для v только один раз. Это означает, что результат проекции, являющийся prvalue, необходимо кэшировать и дважды перемещать из него для двух вызовов компаратора.
- libstdc++ не соответствует этому требованию и всегда передаёт результат проекции как lvalue.
- libc++ ранее выполняла проекцию дважды; это было исправлено в Clang 18.
- MSVC STL ранее выполняла проекцию дважды; это было исправлено в VS 2022 17.2.
Пример
#include <algorithm>
#include <cstdint>
#include <iomanip>
#include <iostream>
#include <string>
using namespace std::literals;
namespace ranges = std::ranges;
int main()
{
std::cout << "[raw] [" << INT8_MIN << ',' << INT8_MAX << "] "
"[0" << ',' << UINT8_MAX << "]\n";
for (int const v : {-129, -128, -1, 0, 42, 127, 128, 255, 256})
std::cout << std::setw(4) << v
<< std::setw(11) << ranges::clamp(v, INT8_MIN, INT8_MAX)
<< std::setw(8) << ranges::clamp(v, 0, UINT8_MAX) << '\n';
std::cout << std::string(23, '-') << '\n';
// Projection function
const auto stoi = [](std::string s) { return std::stoi(s); };
// Same as above, but with strings
for (std::string const v : {"-129", "-128", "-1", "0", "42",
"127", "128", "255", "256"})
std::cout << std::setw(4) << v
<< std::setw(11) << ranges::clamp(v, "-128"s, "127"s, {}, stoi)
<< std::setw(8) << ranges::clamp(v, "0"s, "255"s, {}, stoi)
<< '\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 ----------------------- -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
См. также
|
(C++20) | возвращает меньшее из заданных значений (объект-функция алгоритма) |
|
(C++20) | возвращает большее из заданных значений (объект-функция алгоритма) |
|
(C++20) | проверяет, входит ли целочисленное значение в диапазон значений заданного целочисленного типа (шаблон функции) |
|
(C++17) | ограничивает значение парой граничных значений (шаблон функции) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/algorithm/ranges/clamp
