std::add_sat

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

数値ライブラリ

共通の数学関数
数学特殊関数 (C++17)
数学定数 (C++20)
基本的な線形代数アルゴリズム (C++26)
データ並列型 (SIMD) (C++26)
浮動小数点環境 (C++11)
複素数
数値配列 (valarray)
擬似乱数生成
ビット操作 (C++20)
因数操作
gcd (C++17)	lcm (C++17)
補間
midpoint (C++20)	lerp (C++20)
飽和演算
add_sat (C++26) sub_sat (C++26) saturate_cast (C++26)	mul_sat (C++26) div_sat (C++26)
汎用数値演算
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)

 

ヘッダー <numeric> で定義
template< class T > constexpr T add_sat( T x, T y ) noexcept;		(C++26以降)

x + y を計算する飽和加算を実行します。この演算は（組み込みの整数演算とは異なり）、あたかも無限の範囲を持つ数学的な演算であるかのように振る舞います。このような演算の結果をqとします。以下を返します。

• q が型Tの値として表現可能である場合は、q。
• それ以外の場合は、型Tの最大値または最小値のうち、qに最も近い方。

このオーバーロードは、Tが整数型である場合のみ、オーバーロード解決に参加します。つまり、signed char、short、int、long、long long、拡張符号付き整数型、またはそれらの符号なしバージョンです。特に、Tは（cv修飾されている可能性のある）bool、char、wchar_t、char8_t、char16_t、およびchar32_tであってはいけません。これらは算術演算用ではありません。

パラメータ

x, y

-

整数値

戻り値

飽和されたx + y。

注記

組み込みの整数演算子とは異なり、整数昇格はxおよびy引数には適用されません。

異なる型の2つの引数が渡された場合、コンパイルは失敗します。つまり、テンプレート引数推論に関する動作は、std::minまたはstd::maxの場合と同じです。

ほとんどの最新のハードウェアアーキテクチャは、x86用のSSE2やARM用のNEONなど、SIMDベクトル上の飽和算術演算に効率的なサポートを持っています。

機能テストマクロ	値	規格	機能
__cpp_lib_saturation_arithmetic	202311L	(C++26)	飽和演算

実装例

libstdc++ (gcc)を参照してください。

例

Compiler Explorerでプレビューできます。

このコードを実行

#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
}

関連項目

sub_sat (C++26)	2つの整数に対する飽和減算操作 (関数テンプレート)
mul_sat (C++26)	2つの整数に対する飽和乗算操作 (関数テンプレート)
div_sat (C++26)	2つの整数に対する飽和除算操作 (関数テンプレート)
saturate_cast (C++26)	別の整数型の範囲にクランプされた整数値を返す (関数テンプレート)
clamp (C++17)	値を一対の境界値の間に制限する (関数テンプレート)
in_range (C++20)	整数値が指定された整数型の範囲内にあるかを確認する (関数テンプレート)
min [static]	与えられた非浮動小数点数型の最小の有限値を返すか、与えられた浮動小数点数型の最小の正の正規化された値を返す (std::numeric_limits<T>のpublic staticメンバ関数)
max [static]	与えられた型の最大の有限値を返す (std::numeric_limits<T>のpublic staticメンバ関数)

外部リンク

1.	A branch-free implementation of saturation arithmetic — Locklessinc.com, 2012
2.	C++ Weekly - Ep 459 - C++26's Saturating Math Operations — Youtube.com, 2024-12-16