std::add_sat

 

C++

Compiler-Unterstützung

Freestanding und gehostet

Sprache

Standardbibliothek

Header der Standardbibliothek

Benannte Anforderungen

Feature-Test-Makros (C++20)

Bibliothek für Sprachunterstützung

Konzepte-Bibliothek (C++20)

Diagnostik-Bibliothek

Speicherverwaltungsbibliothek

Metaprogrammierungsbibliothek (C++11)

Allgemeine Dienstprogramme-Bibliothek

Container-Bibliothek

Iterator-Bibliothek

Ranges-Bibliothek (C++20)

Algorithmen-Bibliothek

Bibliothek für Zeichenketten

Textverarbeitungsbibliothek

Numerik-Bibliothek

Datums- und Zeitbibliothek

Ein-/Ausgabe-Bibliothek

Dateisystembibliothek (C++17)

Unterstützung für nebenläufige Programmierung (C++11)

Ausführungssteuerungsbibliothek (C++26)

Technische Spezifikationen

Symbolverzeichnis

Externe Bibliotheken

 

Numerik-Bibliothek

Allgemeine mathematische Funktionen
Mathematische Spezialfunktionen (C++17)
Mathematische Konstanten (C++20)
Grundlegende lineare Algebra-Algorithmen (C++26)
Datenparallele Typen (SIMD) (C++26)
Gleitkomma-Umgebung (C++11)
Komplexe Zahlen
Numerische Arrays (valarray)
Pseudozufallszahlengenerierung
Bit-Manipulation (C++20)
Faktoroperationen
gcd (C++17)	lcm (C++17)
Interpolationen
midpoint (C++20)	lerp (C++20)
Sättigungsarithmetik
add_sat (C++26) sub_sat (C++26) saturate_cast (C++26)	mul_sat (C++26) div_sat (C++26)
Generische numerische Operationen
iota (C++11) ranges::iota (C++23) accumulate inner_product adjacent_difference    partial_sum	reduce (C++17) transform_reduce (C++17) inclusive_scan (C++17) exclusive_scan (C++17) transform_inclusive_scan (C++17) transform_exclusive_scan (C++17)

 

Definiert in der Header-Datei <numeric>
template< class T > constexpr T add_sat( T x, T y ) noexcept;		(seit C++26)

Berechnet die saturierende Addition x + y. Diese Operation (im Gegensatz zu eingebauten arithmetischen Operationen für Ganzzahlen) verhält sich so, als wäre sie eine mathematische Operation mit einem *unendlichen* Bereich. Sei q das Ergebnis einer solchen Operation. Gibt zurück

• q, wenn q als Wert vom Typ T darstellbar ist. Andernfalls,
• den größten oder kleinsten 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, d.h.: 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 arithmetische Zwecke vorgesehen sind.

Parameter

x, y

-

Ganzzahlwerte

Rückgabewert

Saturierte x + y.

Hinweise

Im Gegensatz zu den eingebauten arithmetischen Operatoren für Ganzzahlen wird die Ganzzahlpromotion nicht auf die Argumente x und y angewendet.

Wenn zwei Argumente unterschiedlichen Typs übergeben werden, schlägt der Aufruf fehl, d.h. das Verhalten in Bezug auf die Template-Argumentdeduktion ist dasselbe wie bei std::min oder std::max.

Die meisten modernen Hardwarearchitekturen unterstützen die Sättigungsarithmetik auf SIMD-Vektoren effizient, einschließlich SSE2 für x86 und NEON für ARM.

Feature-Test-Makro	Wert	Std	Feature
__cpp_lib_saturation_arithmetic	202311L	(C++26)	Sättigungsarithmetik

Mögliche Implementierung

Siehe libstdc++ (gcc).

Beispiel

Kann auf Compiler Explorer in der Vorschau angezeigt werden.

Führen Sie diesen Code aus

#include <climits>
#include <limits>
#include <numeric>
 
static_assert(CHAR_BIT == 8);
static_assert(UCHAR_MAX == 255);
 
int main()
{
    constexpr int a = std::add_sat(3, 4); // no saturation occurs, T = int
    static_assert(a == 7);
 
    constexpr unsigned char b = std::add_sat<unsigned char>(UCHAR_MAX, 4); // saturated
    static_assert(b == UCHAR_MAX);
 
    constexpr unsigned char c = std::add_sat(UCHAR_MAX, 4); // not saturated, T = int
        // add_sat(int, int) returns int tmp == 259,
        // then assignment truncates 259 % 256 == 3
    static_assert(c == 3);
 
//  unsigned char d = std::add_sat(252, c); // Error: inconsistent deductions for T
 
    constexpr unsigned char e = std::add_sat<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::add_sat<signed char>(-123, -3); // not saturated
    static_assert(f == -126);
 
    constexpr signed char g = std::add_sat<signed char>(-123, -13); // saturated
    static_assert(g == std::numeric_limits<signed char>::min()); // g == -128
}

Siehe auch

sub_sat (C++26)	Sättigende Subtraktionsoperation auf zwei ganzen Zahlen (Funktionstemplate)
mul_sat (C++26)	Sättigende Multiplikationsoperation auf zwei ganzen Zahlen (Funktionstemplate)
div_sat (C++26)	Sättigende Divisionsoperation auf zwei ganzen Zahlen (Funktionstemplate)
saturate_cast (C++26)	gibt einen Ganzzahlwert zurück, der auf den Bereich eines anderen Ganzzahltyps beschränkt ist (Funktionstemplate)
clamp (C++17)	klemmt einen Wert zwischen einem Paar von Grenzwerte (Funktionsvorlage)
in_range (C++20)	prüft, ob ein Ganzzahlwert im Bereich eines gegebenen Ganzzahltyps liegt (Funktionsvorlage)
min [static]	gibt den kleinsten endlichen Wert des gegebenen nicht-Gleitkommatyps oder den kleinsten positiven normalen Wert des gegebenen Gleitkommatyps zurück (public static member function of std::numeric_limits<T>)
max [static]	gibt den größten endlichen Wert des gegebenen Typs zurück (public static member function of std::numeric_limits<T>)

Externe Links

1.	Eine verzweigungsfreie Implementierung der Sättigungsarithmetik — Locklessinc.com, 2012
2.	C++ Weekly - Ep 459 - C++26's Saturating Math Operations — Youtube.com, 2024-12-16