std::equal_range

在标头 `<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 与 Type2 必须使得 ForwardIt 类型的对象能在解引用后隐式转换到这两个类型。
类型要求
- `ForwardIt` 必须符合老式向前迭代器 (LegacyForwardIterator) 的要求。
- `Compare` 必须符合二元谓词 (BinaryPredicate) 的要求。不要求满足比较 (Compare) 。

返回值

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

如果没有元素不小于 value，那么 last 将作为第一元素返回。类似地，如果没有元素大于 value，那么 last 将作为第二元素返回。

复杂度

进行的比较次数与 first 和 last 间的距离成对数（至多 $log 2 (last - first) + O(1)$ 次比较）。然而，对于非老式随机访问迭代器 (LegacyRandomAccessIterator) ，迭代器自增次数呈线性。要注意 std::set 和 std::multiset 的迭代器不是随机访问的，因此它们的 upper_bound 成员函数的表现更好。

可能的实现

版本一

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; }
};
 
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; }
};
 
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 << "使用 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" "使用异相比较：";
    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 << ' ';
}

输出：

使用 S::operator<() 进行比较：B C D 
使用异相比较：B C D

缺陷报告

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

缺陷报告	应用于	出版时的行为	正确行为
LWG 270	C++98	`Compare` 需要满足比较 (Compare) ，并且 `T` 需要是可小于比较 (LessThanComparable) 的（要求严格弱序）	只需要划分；允许异相比较
LWG 384	C++98	最多允许 $2 * log(last - first) + 1$ 次比较，但是无法实现^[1]	改成 $2 * log 2 (last - first) + O(1)$ 次

↑ 对包含单个元素的范围应用 equal_range 至少需要 2 次比较，但是复杂度要求最多只允许 1 次比较

参阅

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

[1] 对包含单个元素的范围应用 equal_range 至少需要 2 次比较，但是复杂度要求最多只允许 1 次比较

[1]

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用工具库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
技术规范
符号索引
外部库

std::equal_range

参数

返回值

复杂度

可能的实现

Example

缺陷报告

参阅

导航