std::clamp() algorithm

since C++17

// (1)
template< class T >
constexpr const T& clamp( const T& v, const T& lo, const T& hi );

// (2)
template< class T, class Compare >
constexpr const T& clamp( const T& v, const T& lo, const T& hi, Compare comp );

• If v compares less than lo, returns lo.

• Otherwise, if v compares more than hi, returns hi.

• Otherwise returns v.

• (1) Uses operator< to compare the values.

• (2) Same as (1), but uses comp to compare the values.

Undefined Behaviour

The behavior is undefined if the value of lo is greater than hi.

Parameters

v	The value to clamp.
lo hi	The boundaries to clamp v to.
comp	Comparison function object (i.e. an object that satisfies the requirements of Compare) which returns true if the first argument is less than the second. bool cmp(const Type1 &a, const Type2 &b); The signature does not need to have const&, but must not modify arguments. Must accept all values of type (possibly const) Type and Type2, regardless of value category (so Type1& is not allowed, nor is Type1 unless for Type1 a move is equivalent to a copy (since C++11)) The types Type1 and Type2 must be such that an object of type T can be implicitly converted to both of them.

Type requirements

• (1)

  T	LessThanComparable

  If NaN is avoided, T can be a floating-point type.

Return value

Reference to lo if v is less than lo, reference to hi if hi is less than v, otherwise reference to v.

Complexity

At most two comparisons.

Exceptions

The overloads with a template parameter named ExecutionPolicy report errors as follows:

• If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard policies, std::terminate is called. For any other ExecutionPolicy, the behavior is implementation-defined.
• If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Possible implementation

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;
}

Notes

Undefined Behaviour

Capturing the result of std::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::clamp(n, 0, 255); // r is dangling

If v compares equivalent to either bound, returns a reference to v, not the bound.

Examples

Main.cpp

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

int main()
{
    std::cout << " raw   clamped to int8_t   clamped to uint8_t\n";
    for (const int v : {-129, -128, -1, 0, 42, 127, 128, 255, 256})
    {
        std::cout 
            << std::setw(04) << v
            << std::setw(20) << std::clamp(v, INT8_MIN, INT8_MAX)
            << std::setw(21) << std::clamp(v, 0, UINT8_MAX) << '\n';
    }
}

Output

 raw   clamped to int8_t   clamped to uint8_t
-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