Namespaces
Variants

    std::saturating_add

    Von de.cppreference.net
     
    C++
     
    Numerikbibliothek
     
    Sättigungsarithmetik
    Funktionen
    (C++26)
    (C++26)
    (C++26)
    (C++26)
    (C++26)
     
    Definiert in Header <numeric> 
    template< class T >
constexpr T saturating_add( T x, T y ) noexcept;
    		(seit C++26)

    Berechnet die sättigende Addition x + y. Diese Operation (anders als eingebaute arithmetische Operationen auf Ganzzahlen) verhält sich, als ob sie eine mathematische Operation mit einem unendlichen Bereich wäre. Sei q das Ergebnis einer solchen Operation. Gibt zurück:

    • q, falls q als ein Wert vom Typ T darstellbar ist. Andernfalls
    • der größte oder kleinste Wert vom Typ T, je nachdem, welcher näher an q liegt.

    Diese Überladung nimmt nur an der Überladungsauflösung teil, wenn T ein Ganzzahltyp ist, das heißt: signed char, short, int, long, long long, ein erweiterter vorzeichenbehafteter Ganzzahltyp oder eine vorzeichenlose Version solcher Typen. Insbesondere darf T nicht (möglicherweise cv-qualifiziert) bool, char, wchar_t, char8_t, char16_t und char32_t sein, da diese Typen nicht für Arithmetik vorgesehen sind.

    Parameter

    x, y - Ganzzahlwerte

    Rückgabewert

    Gesättigtes x + y.

    Hinweise

    Anders als bei den eingebauten arithmetischen Operatoren auf Ganzzahlen findet die ganzzahlige Beförderung für die Argumente x und y nicht statt.

    Wenn zwei Argumente unterschiedlichen Typs übergeben werden, schlägt der Aufruf fehl, d.h. das Verhalten bezüglich Template-Argument-Deduktion ist dasselbe wie für std::min oder std::max.

    Die meisten modernen Hardware-Architekturen bieten effiziente Unterstützung für Sättigungsarithmetik auf SIMD-Vektoren, einschließlich SSE2 für x86 und NEON für ARM.

    Feature-Test-Makro Wert Std Merkmal
    __cpp_lib_saturation_arithmetic 202311L (C++26) Sättigungsarithmetik
    202603L (C++26) Umbenennung von Sättigungsarithmetik-Funktionen

    Mögliche Implementierung

    Siehe libstdc++ (GCC), libc++ (Clang).

    Beispiel

    Kann auf Compiler Explorer in der Vorschau angezeigt werden.

    Diesen Code ausführen
    #include <climits>
#include <limits>
#include <numeric>

static_assert(CHAR_BIT == 8);
static_assert(UCHAR_MAX == 255);

int main()
{
    constexpr int a = std::saturating_add(3, 4); // no saturation occurs, T = int
    static_assert(a == 7);

    constexpr unsigned char b = std::saturating_add<unsigned char>(UCHAR_MAX, 4); // saturated
    static_assert(b == UCHAR_MAX);

    constexpr unsigned char c = std::saturating_add(UCHAR_MAX, 4); // not saturated, T = int
        // saturating_add(int, int) returns int tmp == 259,
        // then assignment truncates 259 % 256 == 3 (might yield int -> unsigned char warning)
    static_assert(c == 3);

//  unsigned char d = std::saturating_add(252, c); // Error: inconsistent deductions for T

    constexpr unsigned char e = std::saturating_add<unsigned char>(251, a); // saturated
    static_assert(e == UCHAR_MAX);
        // 251 is of type T = unsigned char, `a` is converted to unsigned char value;
        // might yield an int -> unsigned char conversion warning for `a`

    constexpr signed char f = std::saturating_add<signed char>(-123, -3); // not saturated
    static_assert(f == -126);

    constexpr signed char g = std::saturating_add<signed char>(-123, -13); // saturated
    static_assert(g == std::numeric_limits<signed char>::min()); // g == -128
}

    Siehe auch

    (C++26)
    		 sättigende Subtraktionsoperation auf zwei Ganzzahlen
    (Funktionstemplate)
    (C++26)
    		 sättigende Multiplikationsoperation auf zwei Ganzzahlen
    (Funktionstemplate)
    (C++26)
    		 sättigende Divisionsoperation auf zwei Ganzzahlen
    (Funktionstemplate)
    (C++26)
    		 gibt einen Ganzzahlwert zurück, der auf den Bereich eines anderen Ganzzahltyps begrenzt ist
    (Funktionstemplate)
    (C++17)
    		 klemmt einen Wert zwischen ein Paar von Grenzwerten
    (Funktionstemplate & Algorithmus-Funktionsobjekt)
    (C++20)
    (C++20)
    		 prüft, ob ein Ganzzahlwert im Bereich eines gegebenen Ganzzahltyps liegt
    (Funktionstemplate)
    [static]
    		 gibt den kleinsten endlichen Wert des gegebenen Nicht-Gleitkomma-Typs oder den kleinsten positiven normalen Wert des gegebenen Gleitkomma-Typs zurück
    (öffentliche statische Member-Funktion von std::numeric_limits<T>)
    [static]
    		 gibt den größten endlichen Wert des gegebenen Typs zurück
    (öffentliche statische Member-Funktion von std::numeric_limits<T>)

    Externe Links

    1.  Eine verzweigungsfreie Implementierung von Sättigungsarithmetik — Locklessinc.com, 2012