std::mul_sat(3)

🎀 NAME 🎀

okay so bestie, welcome to std::mul_sat(3) from the C++ Standard Libary (yes, that's the header's spelling, not me being chaotic 💅).

std::mul_sat - std::mul_sat

✨ Synopsis ✨

Defined in header <numeric>:

template< class T >                        (since C++26)
constexpr T mul_sat( T x, T y ) noexcept;

so it computes the saturating multiplication x × y. This operation (unlike built-in arithmetic operations on integers) behaves as-if it is a mathematical operation with an infinite range. Let q denote the result of such operation. Returns:

• q, if q is representable as a value of type T. Otherwise,
• the largest or smallest value of type T, whichever is closer to the q.

no cap, this overload participates in overload resolution only if T is an integer type, that is: signed char, short, int, long, long long, an extended signed integer type, or an unsigned version of such types.

In particular, T must not be (possibly cv-qualified) bool, char, wchar_t, char8_t, char16_t, and char32_t, as these types are not intended for arithmetic.

🌸 Parameters 🌸

• x, y — integer values

💖 Return value 💖

Saturated x × y.

🦋 Exceptions 🦋

Throws no exceptions. literally zero drama.

💅 Notes 💅

• Unlike the built-in arithmetic operators on integers, the integral promotion does not apply to the x and y arguments.
• If two arguments of different type are passed, the call fails to compile, i.e. the behavior relative to template argument deduction is the same as for std::min or std::max.
• Most modern hardware architectures have efficient support for saturation arithmetic on SIMD vectors, including SSE2 for x86 and NEON for ARM.

highkey, the feature-test macro check is 👀:

• Feature-test macro: __cpp_lib_saturation_arithmetic
• Value: 202311L
• Std: (C++26)
• Feature: Saturation arithmetic

🧚 Possible implementation 🧚

See libstdc++ (gcc).

🍓 Example 🍓

Can be previewed on Compiler Explorer.

       // Run this code

        #include <climits>
        #include <numeric>

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

        int main() {}

👑 See also 👑

• add_sat — saturating addition operation on two integers (C++26) (function template)
• sub_sat — saturating subtraction operation on two integers (C++26) (function template)
• div_sat — saturating division operation on two integers (C++26) (function template)
• saturate_cast — returns an integer value clamped to the range of a another integer type (C++26) (function template)
• clamp — clamps a value between a pair of boundary values (C++17) (function template)
• in_range — checks if an integer value is in the range of a given integer type (C++20) (function template)
• min — returns the smallest finite value of the given type [static] (public static member function of std::numeric_limits<T>)
• max — returns the largest finite value of the given type [static] (public static member function of std::numeric_limits<T>)

🌈 External links 🌈

1. A branch-free implementation of saturation arithmetic — Locklessinc.com, 2012

---

that's the whole page, bestie 💖 source/version: http://cppreference.com · date: 2024.06.10 · page: std::mul_sat(3) — mwah 🫶