Skip to content

Search topics & cppreference

Search all study topics, concept maps, and 6,587 C++ and C reference pages.

std::saturate_cast

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

Numerics
  • C++17
  • C++20
  • C++26
1 min readView on cppreference
NotebookLM
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.

The program is ill-formed 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.

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.

snippet.cpp
#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

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

Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.