# std::equal_range

< cpp‎ | algorithm

定义于头文件 `<algorithm>` |  |
| (1) |
template< class ForwardIt, class T > std::pair<ForwardIt,ForwardIt> equal_range( ForwardIt first, ForwardIt last, const T& value ); |  | (C++20 前)
template< class ForwardIt, class T > constexpr std::pair<ForwardIt,ForwardIt> equal_range( ForwardIt first, ForwardIt last, const T& value ); |  | (C++20 起)
| (2) |
template< class ForwardIt, class T, class Compare > std::pair<ForwardIt,ForwardIt> equal_range( ForwardIt first, ForwardIt last, const T& value, Compare comp ); |  | (C++20 前)
template< class ForwardIt, class T, class Compare > constexpr std::pair<ForwardIt,ForwardIt> equal_range( ForwardIt first, ForwardIt last, const T& value, Compare comp ); |  | (C++20 起)

返回范围 `[first, last)` 中含有所有等价于 `value` 的元素的范围。

范围 `[first, last)` 必须至少相对于 `value` 有序，即它必须满足下列所有要求：

- 已相对 element < value 或 comp(element, value) 划分（即所有令该表达式为 true 的元素必须前趋所有令此表达式为 false 的元素）
- 已相对 !(value < element) 或 !comp(value, element) 划分
- 对于所有元素，若 element < value 或 comp(element, value) 为 true ，则 !(value < element) 或 !comp(value, element) 亦为 true

完全排序的范围满足这些判别标准。

以二个迭代器定义返回的范围，一个指向首个不小于 `value` 的元素，而另一个指向首个大于 `value` 的元素。可替而用 std::lower_bound() 获得第一迭代器，用 std::upper_bound() 获得第二迭代器。

第一版本用 operator< 比较元素，第二版本用给定的比较函数 `comp` 。

### 参数

first, last | - | 要检验的元素范围
value | - | 要与元素比较的值
comp | - | 若第一参数小于（即先序于）第二个则返回 ​true 的二元谓词。 谓词函数的签名应等价于如下： bool pred(const Type1 &a, const Type2 &b); 虽然签名不必有 const & ，函数也不能修改传递给它的对象，而且必须接受（可为 const 的）类型 `Type1` 与 `Type2` 的值，无关乎值类别（从而不允许 Type1 & ，亦不允许 Type1 ，除非 `Type1` 的移动等价于复制 (C++11 起)）。 类型 Type1 必须使得 ForwardIt 类型的对象能在解引用后隐式转换到 Type1 。类型 Type2 必须使得 T 类型的对象能隐式转换到 Type2 。 ​
类型要求
- `ForwardIt` 必须满足老式向前迭代器 (LegacyForwardIterator) 的要求。
- `Compare` 必须满足二元谓词 (BinaryPredicate) 的要求。不要求满足 比较 (Compare) 。

### 返回值

含有定义所需范围的一对迭代器的 std::pair ，第一迭代器指向首个不小于 `value` 的元素，而第二迭代器指向首个大于 `value` 的元素。

若无元素不小于 `value` ，则 `last` 作为第一元素返回。类似地，若无元素大于 `value` ，则 `last` 作为第二元素返回。

### 复杂度

进行的比较次数与 `first` 和 `last` 间的距离成对数（至多 log
2(last - first) + O(1) 次比较）。然而，对于非老式随机访问迭代器 (LegacyRandomAccessIterator) ，迭代次自增次数为线性。

### 可能的实现

版本一
    template<class ForwardIt, class T>
    std::pair<ForwardIt,ForwardIt>
        equal_range(ForwardIt first, ForwardIt last,
                    const T& value)
    {
        return std::make_pair(std::lower_bound(first, last, value),
                              std::upper_bound(first, last, value));
    }
版本二
    template<class ForwardIt, class T, class Compare>
    std::pair<ForwardIt,ForwardIt>
        equal_range(ForwardIt first, ForwardIt last,
                    const T& value, Compare comp);
    {
        return std::make_pair(std::lower_bound(first, last, value, comp),
                              std::upper_bound(first, last, value, comp));
    }

### 示例

版本一
    template<class ForwardIt, class T>
    std::pair<ForwardIt,ForwardIt>
        equal_range(ForwardIt first, ForwardIt last,
                    const T& value)
    {
        return std::make_pair(std::lower_bound(first, last, value),
                              std::upper_bound(first, last, value));
    }
版本二
    template<class ForwardIt, class T, class Compare>
    std::pair<ForwardIt,ForwardIt>
        equal_range(ForwardIt first, ForwardIt last,
                    const T& value, Compare comp)
    {
        return std::make_pair(std::lower_bound(first, last, value, comp),
                              std::upper_bound(first, last, value, comp));
    }

### Example

    #include <algorithm>
    #include <vector>
    #include <iostream>

    struct S
    {
        int number;
        char name;
        // 注：此比较运算符忽略 name
        bool operator< ( const S& s ) const { return number < s.number; }
    };

    int main()
    {
        // 注：无序，仅相对定义如下的 S 划分
        const std::vector<S> vec = { {1,'A'}, {2,'B'}, {2,'C'}, {2,'D'}, {4,'G'}, {3,'F'} };

        const S value = {2, '?'};

        std::cout << "Compare using S::operator<(): ";
        const auto p = std::equal_range(vec.begin(), vec.end(), value);

        for ( auto i = p.first; i != p.second; ++i )
            std::cout << i->name << ' ';

        std::cout << "\n" "Using heterogeneous comparison: ";
        struct Comp
        {
            bool operator() ( const S& s, int i ) const { return s.number < i; }
            bool operator() ( int i, const S& s ) const { return i < s.number; }
        };

        const auto p2 = std::equal_range(vec.begin(),vec.end(), 2, Comp{});

        for ( auto i = p2.first; i != p2.second; ++i )
            std::cout << i->name << ' ';
    }

输出：

    Compare using S::operator<(): B C D
    Using heterogeneous comparison: B C D

### 缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

DR | 应用于 | 出版时的行为 | 正确行为
--- | --- | --- | ---
LWG 270 | C++98 | 曾要求 Compare 为严格弱序 | 只需要划分；容许异相比较

### 参阅

lower_bound | 返回指向第一个不小于给定值的元素的迭代器 (函数模板)
upper_bound | 返回指向第一个大于给定值的元素的迭代器 (函数模板)
binary_search | 确定元素是否存在于某范围中 (函数模板)
partition | 将范围中的元素分为两组 (函数模板)
equal | 确定两个元素集合是否是相同的 (函数模板)
ranges::equal_ranges (C++20) | 返回匹配特定值的元素范围 (niebloid)