std::div_sat(3)

💅 std::div_sat — the saturation diva manual, ft. std::div_sat(3) ✨

okay so bestie, you opened the std::div_sat(3) page from the C++ Standard Library, and we are gonna read it like a group chat. Every detail stays, the vibe is just... upgraded. 🫶

---

🌸 NAME 🌸

std::div_sat - std::div_sat — yes, the name is literally the name. It's giving “no notes, iconic,” and I'm obsessed. 💖

✨ Synopsis ✨

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

So what does she do? She computes the saturating division x / y. If T is a signed integer type, x is the smallest (most negative) value of T, and y == -1, she returns the greatest value of T; otherwise, she returns x / y. That's the whole saturation moment. 🌟

🚨 bestie, y must not be 0, otherwise the behavior is undefined. And listen: the function call is not a core constant expression if undefined behavior happens. No cap, do not test her on that. 😭

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. Periodt. 💅

🫶 Parameters 🫶

• x, y — integer values

💖 Return value 💖

Saturated x / y. That's it. That's the tea. ☕✨

🚫 Exceptions 🚫

Throws no exceptions. She is noexcept, fr fr. 🙈

📝 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 slay. 🔥
• Feature-test macro: __cpp_lib_saturation_arithmetic — Value: 202311L — Std: (C++26) — Feature: Saturation arithmetic

🛠️ Possible implementation 🛠️

Here's how it could look under the hood, bestie — every token kept, just vibing in a code block. 🧚

namespace detail {
template<class T>
concept standard_or_extended_integral =
     std::is_integral_v<T> &&
    !std::is_same_v<std::remove_cv_t<T>, bool> &&
    !std::is_same_v<std::remove_cv_t<T>, char> &&
    !std::is_same_v<std::remove_cv_t<T>, char8_t> &&
    !std::is_same_v<std::remove_cv_t<T>, char16_t> &&
    !std::is_same_v<std::remove_cv_t<T>, char32_t> &&
    !std::is_same_v<std::remove_cv_t<T>, wchar_t>;
} // namespace detail

template<detail::standard_or_extended_integral T>
constexpr T div_sat( T x, T y ) noexcept
{
    if constexpr (std::is_signed_v<T>)
        if (x == std::numeric_limits<T>::min() && y == -1)
            return std::numeric_limits<T>::max();
    return x / y;
}

👀 Example 👀

Can be previewed on Compiler Explorer. It's giving “static_assert but make it fashion.” 💀

// Run this code

#include <climits>
#include <numeric>

static_assert
(""
    && (std::div_sat<int>(6, 3) == 2) // not saturated
    && (std::div_sat<int>(INT_MIN, -1) == INT_MAX) // saturated
    && (std::div_sat<unsigned>(6, 3) == 2) // not 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)
• mul_sat — saturating multiplication 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

---

mwah 💖 source: cppreference.com, version/date: 2024.06.10 — now go slay your saturating divisions, bestie! 🌈👑