std::saturate_cast(3)

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)