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

The behavior is undefined ifstd::invoke(proj, lo) is greater thanstd::invoke(proj, hi).

The function-like entities described on this page arealgorithm function objects (informally known asniebloids), that is:

• Explicit template argument lists cannot be specified when calling any of them.
• None of them are visible toargument-dependent lookup.
• When any of them are found bynormal unqualified lookup as the name to the left of the function-call operator,argument-dependent lookup is inhibited.

[edit]Parameters

[edit]Return value

Reference tolo if the projected value ofv is less than the projected value oflo, reference tohi if the projected value ofhi is less than the projected value ofv, otherwise reference tov.

[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>constexprconst 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;}}; inlineconstexpr clamp_fn clamp;

[edit]Notes

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

Ifv compares equivalent to either bound, returns a reference tov, 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 viastd::invoke would change the result of projection, the behavior is undefined due tothe semantic requirements ofstd::regular_invocable (subsumed bystd::indirect_strict_weak_order).

The standard requires that the value category of the result of the projection be preserved, andproj can only be called onv 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

#include <algorithm>#include <cstdint>#include <iomanip>#include <iostream>#include <string> usingnamespace std::literals;namespace ranges= std::ranges; int main(){std::cout<<"[raw] ["<<INT8_MIN<<','<<INT8_MAX<<"] ""[0"<<','<<UINT8_MAX<<"]\n";for(intconst 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 functionconstauto stoi=[](std::string s){returnstd::stoi(s);}; // Same as above, but with stringsfor(std::stringconst 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

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文