std::ranges:: clamp

std:: invoke ( proj, v ) の値が [ std:: invoke ( proj, lo ) , std:: invoke ( proj, hi ) ] の範囲内にある場合、 v を返し、そうでない場合は最も近い境界値を返します。

std:: invoke ( proj, lo ) が std:: invoke ( proj, hi ) より大きい場合、動作は未定義です。

このページで説明されている関数ライクなエンティティは、 アルゴリズム関数オブジェクト (非公式には niebloids として知られる) です。つまり：

• 明示的なテンプレート引数リストは、いずれかを呼び出す際に指定できません。
• いずれも 実引数依存の名前探索 では可視になりません。
• いずれかが関数呼び出し演算子の左側の名前として 通常の非修飾名前探索 によって見つかった場合、 実引数依存の名前探索 は抑制されます。

パラメータ

戻り値

lo の射影値が v の射影値より小さい場合は lo への参照、 hi の射影値が v の射影値より小さい場合は hi への参照、それ以外の場合は v への参照。

計算量

最大で2回の比較と3回の射影の適用。

実装例

struct clamp_fn
{
    template<class T, class Proj = std::identity,
             std::indirect_strict_weak_order<std::projected<const T*, Proj>>
                 Comp = std::ranges::less>
    constexpr const T& operator()(const T& v, const T& lo, const T& hi,
                                  Comp comp = {}, Proj proj = {}) const
    {
        auto&& pv = std::invoke(proj, v);
        if (std::invoke(comp, std::forward<decltype(pv)>(pv), std::invoke(proj, lo)))
            return lo;
        if (std::invoke(comp, std::invoke(proj, hi), std::forward<decltype(pv)>(pv)))
            return hi;
        return v;
    }
};
inline constexpr clamp_fn clamp;

注記

int n = -1;
const int& r = std::ranges::clamp(n, 0, 255); // r はダングリング参照

v がどちらかの境界値と等価と比較された場合、 v への参照を返します（境界値自体ではありません）。

この関数は、値で返す射影と値で引数を取る比較器の両方を使用する場合、射影結果型から比較器パラメータ型へのムーブがコピーと等価でない限り使用すべきではありません。 std::invoke による比較が射影の結果を変更する場合、その動作は std::regular_invocable の意味論的要件（ std::indirect_strict_weak_order によって包含される）により未定義となります。

標準では、射影の結果の値カテゴリが保持されることが要求されており、 proj は v に対して一度しか呼び出せません。これは、prvalueである射影結果が比較子の2回の呼び出しに対してキャッシュされ、2回移動されなければならないことを意味します。

• libstdc++ はこれに準拠しておらず、常に射影結果を左辺値として渡します。
• libc++ は以前、射影を2回実行していましたが、Clang 18で修正されました。
• MSVC STL は以前、射影を2回実行していましたが、VS 2022 17.2で修正されました。

例

#include <algorithm>
#include <cstdint>
#include <iomanip>
#include <iostream>
#include <string>
using namespace std::literals;
namespace ranges = std::ranges;
int main()
{
    std::cout << "[raw] [" << INT8_MIN << ',' << INT8_MAX << "] "
                 "[0" << ',' << UINT8_MAX << "]\n";
    for (int const v : {-129, -128, -1, 0, 42, 127, 128, 255, 256})
        std::cout << std::setw(4) << v
                  << std::setw(11) << ranges::clamp(v, INT8_MIN, INT8_MAX)
                  << std::setw(8) << ranges::clamp(v, 0, UINT8_MAX) << '\n';
    std::cout << std::string(23, '-') << '\n';
    // 射影関数
    const auto stoi = [](std::string s) { return std::stoi(s); };
    // 上記と同じだが文字列を使用
    for (std::string const v : {"-129", "-128", "-1", "0", "42",
                                "127", "128", "255", "256"})
        std::cout << std::setw(4) << v
                  << std::setw(11) << ranges::clamp(v, "-128"s, "127"s, {}, stoi)
                  << std::setw(8) << ranges::clamp(v, "0"s, "255"s, {}, stoi)
                  << '\n';
}

[raw] [-128,127] [0,255]
-129       -128       0
-128       -128       0
  -1         -1       0
   0          0       0
  42         42      42
 127        127     127
 128        127     128
 255        127     255
 256        127     255
-----------------------
-129       -128       0
-128       -128       0
  -1         -1       0
   0          0       0
  42         42      42
 127        127     127
 128        127     128
 255        127     255
 256        127     255

関連項目