Namespaces
Variants
Actions

std::ranges::clamp

From cppreference.com
< cpp‎ | algorithm‎ | ranges
 
 
Algorithm library
Constrained algorithms, e.g. ranges::copy, ranges::sort, ...
(C++11)
(C++11)
(C++17)

 
Constrained algorithms
All names in this menu belong to namespace std::ranges
       
       
    
     
         
       
       
clamp

(C++23)
(C++23)  
(C++23)
(C++23)  
(C++23)            
 
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)

If the value of std::invoke (proj, v) is within [std::invoke (proj, lo)std::invoke (proj, hi)], returns v; otherwise returns the nearest boundary.

The behavior is undefined if std::invoke (proj, lo) is greater than std::invoke (proj, hi).

The function-like entities described on this page are algorithm function objects (informally known as niebloids), that is:

[edit] Parameters

v - the value to clamp
lo, hi - the boundaries to clamp v to
comp - the comparison to apply to the projected elements
proj - the projection to apply to v, lo and hi

[edit] Return value

Reference to lo if the projected value of v is less than the projected value of lo, reference to hi if the projected value of hi is less than the projected value of v, otherwise reference to v.

[edit] Complexity

At most two comparisons and three applications of the projection.

[edit] 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;

[edit] 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 a reference to v, not 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.

[edit] Example

Run this code
#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

[edit] See also

(C++20)
returns the smaller of the given values
(algorithm function object)[edit]
(C++20)
returns the greater of the given values
(algorithm function object)[edit]
(C++20)
checks if an integer value is in the range of a given integer type
(function template) [edit]
(C++17)
clamps a value between a pair of boundary values
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/algorithm/ranges/clamp&oldid=182830"

AltStyle によって変換されたページ (->オリジナル) /