std::sub_sat(3)

🌟 std::sub_sat(3) 🌟

okay so bestie, this is the std::sub_sat(3) page from the C++ Standard Libary manual — and yes we're about to make saturating subtraction make sense, no cap 💅

💖 NAME 💖

std::sub_sat — std::sub_sat

✨ Synopsis ✨

Defined in header <numeric>
template< class T >                        (since C++26)
constexpr T sub_sat( T x, T y ) noexcept;

This computes the saturating subtraction x - y. Unlike built-in arithmetic operations on integers, this operation behaves as-if it is a mathematical operation with an infinite range. Let q denote the result of that operation. It 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.

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.

🔥 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.

👑 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::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() {}

🌈 See also 🌈

• add_sat — saturating addition operation on two integers (C++26) (function template)
• mul_sat — saturating multiplication 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 vibe, bestie — page std::sub_sat(3), from http://cppreference.com, version/date 2024.06.10. go saturate those ints, periodt 🎀✨