std::ranges::clamp
| Defined in header <algorithm>
|
||
| Call signature |
||
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 = {} );
|
(since C++20) | |
Returns a reference to the value in [lo, hi] that is closest to v, the values are projected by proj and compared using comp.
If lo is greater than hi, the behavior is undefined.
The function-like entities described on this page are algorithm function objects (informally known as niebloids), that is:
- Explicit template argument lists cannot be specified when calling any of them.
- None of them are visible to argument-dependent lookup.
- When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.
Parameters
| v | - | the value to clamp |
| lo, hi | - | the boundaries to clamp v to
|
| comp | - | the comparator to be applied to the (projected) values |
| proj | - | the projection to be applied to the values |
Return value
lo if v is less than lo, or hi if hi is less than v, otherwise v.
Complexity
At most two applications of comp and three applications of proj.
Notes
Capturing the result of std::ranges::clamp by reference produces a dangling reference if one of the parameters is a temporary and that parameter is returned:
int n = -1;
const int& r = std::ranges::clamp(n, 0, 255); // r is dangling
If v compares equivalent to either bound, returns v rather than the bound.
This function should not be used with both a projection the returns by value and comparator that takes arguments by value unless a move from the projection result type to the comparator parameter type is equivalent to a copy. If the comparison via std::invoke would change the result of projection, the behavior is undefined due to the semantic requirements of std::regular_invocable (subsumed by std::indirect_strict_weak_order).
The standard requires that the value category of the result of the projection be preserved, and proj can only be called on v once, which means that a projection result that is a prvalue has to be cached and moved from twice for the two calls to the comparator.
- libstdc++ does not conform to this and always passes the projection result as an lvalue.
- libc++ used to run the projection twice, which was corrected in Clang 18.
- MSVC STL used to run the projection twice, which was corrected in VS 2022 17.2.
Possible implementation
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;
|
Example
#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';
}
Output:
[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
See also
(C++17) |
clamps a value between a pair of boundary values (function template) |
(C++20) |
returns the smaller of the given values (algorithm function object) |
(C++20) |
returns the greater of the given values (algorithm function object) |
(C++20) |
checks if an integer value is in the range of a given integer type (function template) |