std::saturating_sub

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

Вычисляет насыщенную разность x - y. Эта операция (в отличие от встроенных арифметических операций над целыми числами) ведёт себя так, как если бы она была математической операцией с бесконечным диапазоном. Обозначим q результат такой операции. Функция возвращает:

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

Эта перегрузка участвует в разрешении перегрузки, только если T является целочисленным типом, то есть одним из следующих типов: signedchar, short, int, long, longlong, расширенный знаковый целочисленный тип или соответствующий беззнаковый тип. В частности, T не должен быть (возможно, cv-квалифицированным) типом bool, char, wchar_t, char8_t, char16_t или char32_t, поскольку эти типы не предназначены для арифметических операций.

Параметры

x, y

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

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

Насыщенная разность x - y.

Примечания

В отличие от встроенных арифметических операторов над целыми числами, к аргументам x и y не применяется целочисленное продвижение.

Если переданы два аргумента разных типов, вызов не компилируется, то есть поведение при выведении аргументов шаблона такое же, как для std::min или std::max.

Большинство современных аппаратных архитектур эффективно поддерживают арифметику с насыщением над векторами SIMD, включая SSE2 для x86 и NEON для ARM.

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

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

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

Пример

Предварительный просмотр доступен на сайте Compiler Explorer

#include <climits>
#include <numeric>
 
static_assert
(""
    && (std::saturating_sub<int>(INT_MIN + 4, 3) == INT_MIN + 1) // not saturated
    && (std::saturating_sub<int>(INT_MIN + 4, 5) == INT_MIN) // saturated
    && (std::saturating_sub<int>(INT_MAX - 4, -3) == INT_MAX - 1) // not saturated
    && (std::saturating_sub<int>(INT_MAX - 4, -5) == INT_MAX) // saturated
    && (std::saturating_sub<unsigned>(4, 3) == 1) // not saturated
    && (std::saturating_sub<unsigned>(4, 5) == 0) // saturated
);

int main() {}

См. также

saturating_add (C++26)	операция насыщенного сложения двух целых чисел (шаблон функции)
saturating_mul (C++26)	операция насыщенного умножения двух целых чисел (шаблон функции)
saturating_div (C++26)	операция насыщенного деления двух целых чисел (шаблон функции)
saturating_cast (C++26)	возвращает целочисленное значение, ограниченное диапазоном другого целочисленного типа (шаблон функции)
clamp (C++17)	ограничивает значение парой граничных значений (шаблон функции и функциональный объект алгоритма)
ranges::clamp (C++20)
in_range (C++20)	проверяет, входит ли целочисленное значение в диапазон заданного целочисленного типа (шаблон функции)
min [static]	возвращает наименьшее конечное значение заданного типа, не являющегося типом с плавающей точкой, или наименьшее положительное нормальное значение заданного типа с плавающей точкой (открытая статическая функция-член `std::numeric_limits<T>`)
max [static]	возвращает наибольшее конечное значение заданного типа (открытая статическая функция-член `std::numeric_limits<T>`)

Внешние ссылки

1.	Реализация арифметики с насыщением без ветвлений — Locklessinc.com, 2012

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