std::sub_sat

Определено в заголовке `<numeric>`
template< class T > constexpr T sub_sat( T x, T y ) noexcept;		(с C++26)

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

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

Этот перегруз участвует в разрешении перегрузки только в том случае, если T является целочисленным типом, то есть: signed char, short, int, long, long long, расширенным знаковым целочисленным типом или беззнаковым вариантом таких типов. В частности, 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.

Макроинструкция проверки наличия функции	Значение	Std	Функция
`__cpp_lib_saturation_arithmetic`	202311L	(C++26)	Насыщающая арифметика

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

См. libstdc++ (gcc).

Пример

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

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

См. также

add_sat (C++26)	насыщающая операция сложения двух целых чисел (шаблон функции)
mul_sat (C++26)	насыщающая операция умножения двух целых чисел (шаблон функции)
div_sat (C++26)	насыщающая операция деления двух целых чисел (шаблон функции)
saturate_cast (C++26)	возвращает целое значение, ограниченное диапазоном другого целочисленного типа (шаблон функции)
clamp (C++17)	ограничение значения между парой граничных значений (шаблон функции)
in_range (C++20)	проверяет, находится ли целое значение в диапазоне заданного целочисленного типа (шаблон функции)
min [статический]	возвращает наименьшее конечное значение заданного типа (публичный статический член-функция `std::numeric_limits<T>`)
max [статический]	возвращает наибольшее конечное значение заданного типа (публичный статический член-функция `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/w/cpp/numeric/sub_sat