W3cubDocs

/C++

std::saturate_cast

Defined in header `<numeric>`
template< class T, class U > constexpr T saturate_cast( U x ) noexcept;		(since C++26)

Converts the value x to a value of type T, clamping x between the minimum and maximum values of type T.

It is a compile-time error if either T or U is not a signed or unsigned integer type (including standard integer type and extended integer type).

Parameters

an integer value

Return value

x, if x is representable as a value of type T. Otherwise,
either the largest or smallest representable value of type T, whichever is closer to the value of x.

Exceptions

Throws no exceptions.

Notes

Feature-test macro	Value	Std	Feature
`__cpp_lib_saturation_arithmetic`	202311L	(C++26)	Saturation arithmetic

Possible implementation

See libstdc++ (gcc).

Example

Can be previewed on Compiler Explorer.

#include <cstdint>
#include <limits>
#include <numeric>
 
int main()
{
    constexpr std::int16_t x1{696};
 
    constexpr std::int8_t x2 = std::saturate_cast<std::int8_t>(x1);
    static_assert(x2 == std::numeric_limits<std::int8_t>::max());
 
    constexpr std::uint8_t x3 = std::saturate_cast<std::uint8_t>(x1);
    static_assert(x3 == std::numeric_limits<std::uint8_t>::max());
 
    constexpr std::int16_t y1{-696};
 
    constexpr std::int8_t y2 = std::saturate_cast<std::int8_t>(y1);
    static_assert(y2 == std::numeric_limits<std::int8_t>::min());
 
    constexpr std::uint8_t y3 = std::saturate_cast<std::uint8_t>(y1);
    static_assert(y3 == 0);
}

bit_cast (C++20)	reinterpret the object representation of one type as that of another (function template)
clamp (C++17)	clamps a value between a pair of boundary values (function template)
in_range (C++20)	checks if an integer value is in the range of a given integer type (function template)