std::saturating_mul

Определено в заголовочном файле `<numeric>`
template< class T > constexpr T saturating_mul( 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).

Пример

#include <climits>
#include <numeric>

static_assert
(""
    && (std::saturating_mul<int>(2, 3) == 6) // not saturated
    && (std::saturating_mul<int>(INT_MAX / 2, 3) == INT_MAX) // saturated
    && (std::saturating_mul<int>(-2, 3) == -6) // not saturated
    && (std::saturating_mul<int>(INT_MIN / -2, -3) == INT_MIN) // saturated
    && (std::saturating_mul<unsigned>(2, 3) == 6) // not saturated
    && (std::saturating_mul<unsigned>(UINT_MAX / 2, 3) == UINT_MAX) // saturated
);

int main() {}

См. также

saturating_add (C++26)	сложение двух целых чисел с насыщением (шаблон функции)
saturating_sub (C++26)	вычитание двух целых чисел с насыщением (шаблон функции)
saturating_div (C++26)	деление двух целых чисел с насыщением (шаблон функции)
saturating_cast (C++26)	возвращает целочисленное значение, ограниченное диапазоном другого целочисленного типа (шаблон функции)
clamp (C++17)	ограничивает значение парой граничных значений (шаблон функции и функциональный объект алгоритма)
ranges::clamp (C++20)
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/cpp/numeric/saturating_mul