# std::saturate_cast

> C++ Atlas: `cppatlas.com/w/cpp/numeric/saturate_cast` | Source: https://en.cppreference.com/w/cpp/numeric/saturate_cast | Domain: Numerics | Standards: C++17, C++20, C++26

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

## Official Specification Summary (cppreference)

```cpp
// 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.

```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

- [`bit_cast`](https://en.cppreference.com/w/cpp/numeric/bit_cast) (C++20): reinterpret the object representation of one type as that of another (function template)
- [`clamp`](https://en.cppreference.com/w/cpp/algorithm/clamp) (C++17): clamps a value between a pair of boundary values (function template)
- [`in_range`](https://en.cppreference.com/w/cpp/utility/in_range) (C++20): checks if an integer value is in the range of a given integer type (function template)

---
Attribution: content from https://en.cppreference.com/w/cpp/numeric/saturate_cast (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.