NAME¶

std::saturate_cast - std::saturate_cast

Synopsis¶

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

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¶

x - 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.

// Run this code

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

See also¶

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