std::clamp

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

演算法庫

有約束演算法與針對範圍的演算法 (C++20)
有約束的演算法，例如 ranges::copy、 ranges::sort 等……
執行策略 (C++17)
is_execution_policy (C++17)   execution::seqexecution::parexecution::par_unseqexecution::unseq (C++17)    (C++17)(C++17)(C++20)	execution::sequenced_policyexecution::parallel_policyexecution::parallel_unsequenced_policyexecution::parallel_unsequenced (C++17)(C++17)(C++17)(C++20)
非修改序列操作 批次操作 for_each for_each_n (C++17) 搜尋操作 all_ofany_ofnone_of (C++11)                (C++11)(C++11) countcount_if mismatch equal findfind_iffind_if_not (C++11) find_end find_first_of adjacent_find search search_n 修改序列操作 複製操作 copycopy_if (C++11) copy_backward copy_n (C++11) move (C++11) move_backward (C++11) 交換操作 swap iter_swap swap_ranges 變換操作 replacereplace_if transform replace_copyreplace_copy_if 生成操作 fill fill_n generate generate_n 移除操作 removeremove_if unique remove_copyremove_copy_if unique_copy 順序變換操作 reverse reverse_copy rotate rotate_copy random_shuffleshuffle (C++17 前)(C++11) shift_leftshift_right (C++20)(C++20) 取樣操作 sample (C++17)	排序及相關操作 劃分操作 partition partition_copy (C++11)   stable_partition is_partitioned (C++11) partition_point (C++11) 排序操作 sort stable_sort partial_sort partial_sort_copy is_sorted (C++11) is_sorted_until (C++11) nth_element 二分搜尋操作 （於已劃分範圍上） lower_bound upper_bound equal_range binary_search 集合操作（於已排序範圍上） includes set_union set_intersection set_difference set_symmetric_difference 歸併操作（於已排序範圍上） merge inplace_merge 堆操作 push_heap pop_heap make_heap sort_heap is_heap (C++11) is_heap_until (C++11) 最小/最大值操作 max min minmax (C++11) clamp (C++17) max_element min_element minmax_element (C++11) 字典序比較操作 lexicographical_compare lexicographical_compare_three_way (C++20) 排列操作 next_permutation prev_permutation is_permutation (C++11) C 庫 qsort bsearch
數值操作
iota (C++11) inner_product adjacent_difference    accumulate reduce (C++17) transform_reduce (C++17)	partial_sum inclusive_scan (C++17)    exclusive_scan (C++17) transform_inclusive_scan (C++17) transform_exclusive_scan (C++17)
未初始化記憶體上的操作
uninitialized_copy uninitialized_move (C++17)    uninitialized_fill uninitialized_copy_n (C++11) uninitialized_move_n (C++17) uninitialized_fill_n	destroy (C++17) destroy_n (C++17) destroy_at (C++17) construct_at (C++20)       uninitialized_default_construct (C++17) uninitialized_value_construct (C++17) uninitialized_default_construct_n (C++17) uninitialized_value_construct_n (C++17)

 

定義於標頭檔案 <algorithm>
template< class T > constexpr const T& clamp( const T& v, const T& lo, const T& hi );	(1)	(C++17 起)
template< class T, class Compare > constexpr const T& clamp( const T& v, const T& lo, const T& hi,                           Compare comp );	(2)	(C++17 起)

如果 v 的值在 [lo, hi] 範圍內，則返回 v；否則返回最近的邊界。

1) 使用 operator<(C++20 前)std::less{}(C++20 起) 比較值。

如果 T 不是 LessThanComparable，則行為未定義。

2) 使用比較函式 comp 比較值。

如果 lo 大於 hi，則行為未定義。

引數

v	-	要限制的值
lo, hi	-	限制 v 的邊界
comp	-	比較函式物件（即滿足 Compare 要求的物件），如果第一個引數“小於”第二個引數，則返回 true。 比較函式的簽名應等效於以下內容 bool cmp(const Type1& a, const Type2& b); 雖然簽名不需要包含 const&，但函式不得修改傳遞給它的物件，並且必須能夠接受 Type1 和 Type2 型別的所有值（可能為 const），而不管其 值類別（因此，不允許使用 Type1&，除非對於 Type1，移動等同於複製，否則也不允許使用 Type1(C++11 起)）。 型別 Type1 和 Type2 必須能夠讓型別 T 的物件隱式轉換為它們兩者。

返回值

如果 v 小於 lo，則返回對 lo 的引用；如果 hi 小於 v，則返回對 hi 的引用；否則返回對 v 的引用。

複雜度

1) 使用 operator<(C++20 前)std::less{}(C++20 起) 最多進行兩次比較。

2) 最多兩次應用比較函式 comp。

可能實現

clamp (1)
template<class T> constexpr const T& clamp(const T& v, const T& lo, const T& hi) { return clamp(v, lo, hi, less{}); }
clamp (2)
template<class T, class Compare> constexpr const T& clamp(const T& v, const T& lo, const T& hi, Compare comp) { return comp(v, lo) ? lo : comp(hi, v) ? hi : v; }

注意

如果引數之一是臨時變數且該引數被返回，則透過引用捕獲 std::clamp 的結果會產生懸空引用。

int n = -1;
const int& r = std::clamp(n, 0, 255); // r is dangling

如果 v 與任一邊界比較相等，則返回對 v 的引用，而不是對邊界的引用。

特性測試宏	值	標準	特性
__cpp_lib_clamp	201603L	(C++17)	std::clamp

示例

執行此程式碼

#include <algorithm>
#include <cstdint>
#include <iomanip>
#include <iostream>
 
int main()
{
    std::cout << "[raw] "
                 "[" << INT8_MIN << ',' << INT8_MAX << "] "
                 "[0," << UINT8_MAX << "]\n";
 
    for (const int v : {-129, -128, -1, 0, 42, 127, 128, 255, 256})
        std::cout << std::setw(4) << v
                  << std::setw(11) << std::clamp(v, INT8_MIN, INT8_MAX)
                  << std::setw(8) << std::clamp(v, 0, UINT8_MAX) << '\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

參閱

min	返回給定值中較小的那個 (函式模板)
max	返回給定值中較大的那個 (函式模板)
in_range (C++20)	檢查整數值是否在給定整數型別的範圍內 (函式模板)
ranges::clamp (C++20)	將值限制在邊界值對之間 (演算法函式物件)