std::includes

出自cppreference.com
< cpp‎ | algorithm
 
C++
 
演算法庫
受約束演算法及範圍上的演算法 (C++20)
包含演算法例如 ranges::copy, ranges::sort, ...
執行策略 (C++17)
排序和相關操作
劃分操作
排序操作
二分搜索操作（在已劃分範圍上）
集合操作（在有序範圍上）
歸併操作（在有序範圍上）
堆操作
最小/最大操作
(C++11)
(C++17)
字典序比較操作
(C++20)
排列操作
C 庫

數值運算
(C++11)                       
在未初始化內存上的操作
 
在標頭 <algorithm> 定義
template< class InputIt1, class InputIt2 >

bool includes( InputIt1 first1, InputIt1 last1,

               InputIt2 first2, InputIt2 last2 );
 (1) (C++20 起為 constexpr)
template< class ExecutionPolicy,

          class ForwardIt1, class ForwardIt2 >
bool includes( ExecutionPolicy&& policy,
               ForwardIt1 first1, ForwardIt1 last1,

               ForwardIt2 first2, ForwardIt2 last2 );
 (2) (C++17 起)
template< class InputIt1, class InputIt2, class Compare >

bool includes( InputIt1 first1, InputIt1 last1,

               InputIt2 first2, InputIt2 last2, Compare comp );
 (3) (C++20 起為 constexpr)
template< class ExecutionPolicy,

          class ForwardIt1, class ForwardIt2, class Compare >
bool includes( ExecutionPolicy&& policy,
               ForwardIt1 first1, ForwardIt1 last1,

               ForwardIt2 first2, ForwardIt2 last2, Compare comp );
 (4) (C++17 起)

在有序範圍 [first2, last2) 是有序範圍 [first1, last1) 的子序列的情況下返回 true（不必是連續的子序列）。

1) 如果 [first1, last1) 或 [first2, last2) 沒有按 operator<(C++20 前)std::less{}(C++20 起) 排序，那麼行為未定義。
3) 如果 [first1, last1) 或 [first2, last2) 沒有按 comp 排序，那麼行為未定義。
2,4) 同 (1,3)，但按照 policy 執行。
這些重載只有在滿足以下所有條件時才會參與重載決議：

std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> 是 true。

(C++20 前)

std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> 是 true。

(C++20 起)

目錄

[編輯] 參數

first1, last1 - 要檢驗的已排序元素範圍的迭代器對
first2, last2 - 要搜索的已排序元素範圍的迭代器對
policy - 所用的執行策略
comp - 比較函數對象（即滿足比較 (Compare) 概念的對象），在第一參數小於（即先 序於）第二參數時返回 ​true。

比較函數的簽名應等價於如下：

bool cmp(const Type1 &a, const Type2 &b);

雖然簽名不必有 const&，函數也不能修改傳遞給它的對象，而且必須接受（可為 const 的）類型 Type1 與 Type2 的值，無關乎值類別（從而不允許 Type1& ，也不允許 Type1，除非 Type1 的移動等價於複製(C++11 起)）。
類型 Type1 與 Type2 必須使得 InputIt 類型的對象能在解引用後隱式轉換到這兩個類型。 ​

類型要求
-
InputIt1, InputIt2 必須滿足老式輸入迭代器 (LegacyInputIterator) 。
-
ForwardIt1, ForwardIt2 必須滿足老式向前迭代器 (LegacyForwardIterator) 。
-
Compare 必須滿足比較 (Compare) 。

[編輯] 返回值

在 [first2, last2) 是 [first1, last1) 的子序列時返回 true；否則返回 false。

因為空序列是所有序列的子序列，所以在 [first2, last2) 為空時會返回 true。

[編輯] 複雜度

給定 N1 為 std::distance(first1, last1)，N2 為 std::distance(first2, last2)：

1,2) 最多應用 2⋅(N1+N2)-1 次 operator<(C++20 前)std::less{}(C++20 起) 進行比較。
3,4) 最多應用 2⋅(N1+N2)-1 次比較函數 comp。

[編輯] 異常

擁有名為 ExecutionPolicy 的模板形參的重載按下列方式報告錯誤：

  • 如果作為演算法一部分調用的函數的執行拋出異常，且 ExecutionPolicy 是標準策略之一，那麼調用 std::terminate。對於任何其他 ExecutionPolicy，行為由實現定義。
  • 如果演算法無法分配內存，那麼拋出 std::bad_alloc。

[編輯] 可能的實現

include (1) 
template<class InputIt1, class InputIt2>
bool includes(InputIt1 first1, InputIt1 last1,
              InputIt2 first2, InputIt2 last2)
{
    for (; first2 != last2; ++first1)
    {
        if (first1 == last1 || *first2 < *first1)
            return false;
        if (!(*first1 < *first2))
            ++first2;
    }
    return true;
}
include (3) 
template<class InputIt1, class InputIt2, class Compare>
bool includes(InputIt1 first1, InputIt1 last1,
              InputIt2 first2, InputIt2 last2, Compare comp)
{
    for (; first2 != last2; ++first1)
    {
        if (first1 == last1 || comp(*first2, *first1))
            return false;
        if (!comp(*first1, *first2))
            ++first2;
    }
    return true;
}

[編輯] 示例

運行此代碼
#include <algorithm>
#include <cctype>
#include <iostream>
 
template<class Os, class Co>
Os& operator<<(Os& os, const Co& v)
{
    for (const auto& i : v)
        os << i << ' ';
    return os << '\t';
}
 
int main()
{
    const auto
        v1 = {'a', 'b', 'c', 'f', 'h', 'x'},
        v2 = {'a', 'b', 'c'},
        v3 = {'a', 'c'},
        v4 = {'a', 'a', 'b'},
        v5 = {'g'},
        v6 = {'a', 'c', 'g'},
        v7 = {'A', 'B', 'C'};
 
    auto no_case = [](char a, char b) { return std::tolower(a) < std::tolower(b); };
 
    std::cout
    << v1 << "\n包含：\n" << std::boolalpha
    << v2 << "：" << std::includes(v1.begin(), v1.end(), v2.begin(), v2.end()) << '\n'
    << v3 << "：" << std::includes(v1.begin(), v1.end(), v3.begin(), v3.end()) << '\n'
    << v4 << "：" << std::includes(v1.begin(), v1.end(), v4.begin(), v4.end()) << '\n'
    << v5 << "：" << std::includes(v1.begin(), v1.end(), v5.begin(), v5.end()) << '\n'
    << v6 << "：" << std::includes(v1.begin(), v1.end(), v6.begin(), v6.end()) << '\n'
    << v7 << "：" << std::includes(v1.begin(), v1.end(), v7.begin(), v7.end(), no_case)
          << "（大小写不敏感）\n";
}

輸出： 

a b c f h x
包含：
a b c   ：true
a c     ：true
a a b   ：false
g       ：false
a c g   ：false
A B C   ：true（大小写不敏感）

[編輯] 缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告 應用於 出版時的行為 正確行為
LWG 1205 C++98 [first2, last2) 為空時返回值不明確 此時會返回 true

[編輯] 參閱

 計算兩個集合的差集
(函數模板) [編輯]
搜索元素範圍的首次出現
(函數模板) [編輯]
(C++20)
 當一個序列是另一個的子序列時返回 true
(演算法函數對象) [編輯]
取自「https://zh.cppreference.com/mwiki/index.php?title=cpp/algorithm/includes&oldid=98685」