std::saturating_cast

Определён в заголовочном файле `<numeric>`
template< class T, class U > constexpr T saturating_cast( U x ) noexcept;		(начиная с C++26)

Преобразует значение x в значение типа T, ограничивая x минимальным и максимальным значениями типа T.

Программа некорректно сформирована, если T или U не является знаковым или беззнаковым целочисленным типом (включая стандартный целочисленный тип и расширенный целочисленный тип).

Параметры

целочисленное значение

Возвращаемое значение

x, если x представимо как значение типа T. В противном случае —
наибольшее или наименьшее представимое значение типа T — в зависимости от того, какое из них ближе к значению x.

Примечания

Макрос проверки поддержки функции	Значение	Стандарт	Функция
`__cpp_lib_saturation_arithmetic`	`202311L`	(C++26)	Арифметика с насыщением
`__cpp_lib_saturation_arithmetic`	`202603L`	(C++26)	Переименование функций арифметики с насыщением

Возможная реализация

См. libstdc++ (GCC), libc++ (Clang).

Пример

#include <cstdint>
#include <limits>
#include <numeric>

int main()
{
    constexpr std::int16_t x1{696};

    constexpr std::int8_t x2 = std::saturating_cast<std::int8_t>(x1);
    static_assert(x2 == std::numeric_limits<std::int8_t>::max());

    constexpr std::uint8_t x3 = std::saturating_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::saturating_cast<std::int8_t>(y1);
    static_assert(y2 == std::numeric_limits<std::int8_t>::min());

    constexpr std::uint8_t y3 = std::saturating_cast<std::uint8_t>(y1);
    static_assert(y3 == 0);
}

См. также

bit_cast (C++20)	переинтерпретирует представление объекта одного типа как представление объекта другого типа (шаблон функции)
clamp (C++17)	ограничивает значение диапазоном, заданным парой граничных значений (шаблон функции и функциональный объект алгоритма)
ranges::clamp (C++20)
in_range (C++20)	проверяет, входит ли целочисленное значение в диапазон значений заданного целочисленного типа (шаблон функции)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/numeric/saturating_cast