std::atomic_ref::fetch_sub(3)

std::atomic_ref::fetch_sub(3) 💅✨

okay bestie, welcome to the C++ Standard Libary man page for std::atomic_ref::fetch_sub — yes, that's the manual name, and yes, we're respecting the iconic spelling. this page is giving atomic arithmetic realness, so grab your emotional support iced coffee. 🦋

🌸 NAME 🌸

std::atomic_ref::fetch_sub — std::atomic_ref::fetch_sub (the page says it twice, so we're saying it twice, periodt 💅)

✨ Synopsis ✨

okay so first thing: this function is member only of certain specializations. don't try to make it fetch_sub outside its lane, bestie. 👑

here's the exact synopsis energy:

          member only of atomic_ref<Integral> and atomic_ref<Floating>
          template specializations
          T fetch_sub( T arg,
                       std::memory_order order = std::memory_order_seq_cst )
       (1) (since C++20)
          const noexcept;
          member only of atomic_ref<T*> template specialization
          T* fetch_sub( std::ptrdiff_t arg,
                        std::memory_order order = std::memory_order_seq_cst
       (2) (since C++20)
          ) const noexcept;

so what does it do? atomically, it replaces the current value of the referenced object with the result of arithmetic subtraction of the value and arg. this operation is a read-modify-write operation. memory is affected according to the value of order. it's doing the most in one go. 🔥

for signed integral types, arithmetic is defined to use two’s complement representation. there are no undefined results. slay, no cursed UB here. 💖

for floating-point types, the floating-point environment in effect may be different from the calling thread's floating-point environment. the operation need not be conform to the corresponding std::numeric_limits traits but is encouraged to do so. if the result is not a representable value for its type, the result is unspecified but the operation otherwise has no undefined behavior. so: unspecified? yes. UB? no. got it? 🫶

for T* types, the result may be an undefined address, but the operation otherwise has no undefined behavior. and heads up: the program is ill-formed if T is not an object type. that's a hard no, not a vibe. 💀

🎀 Parameters 🎀

• arg — the other argument of arithmetic subtraction. it's the thing getting subtracted, bestie. 🍓
• order — memory order constraints to enforce. this is the memory-ordering vibe check. 🌈

👑 Return value 👑

the value of the referenced object, immediately preceding the effects of this function. so it's the before picture, not the after. iconic. 📸

🧚 Example 🧚

This section is incomplete Reason: no example

not me crying because there's no example 😭 we move, though. 💅

💜 Category 💜

• Todo no example

xoxo, bestie 🫶 this page is sourced from http://cppreference.com, version/date 2024.06.10, and it's the std::atomic_ref::fetch_sub(3) page. now go subtract atomically and stay hydrated. 💖✨