std::map equal_range() 方法

自 C++14 起

// (1) Non const version
std::pair<iterator, iterator> equal_range( const Key& key );

// (2) Const version
std::pair<const_iterator, const_iterator> equal_range( const Key& key ) const;

// (3) Non const version
template< class K >
std::pair<iterator, iterator> equal_range( const K& x );

// (4) Const version
template< class K >
std::pair<const_iterator, const_iterator> equal_range( const K& x ) const;

C++98 起

// (1) Non const version
std::pair<iterator, iterator> equal_range( const Key& key );

// (2) Const version
std::pair<const_iterator, const_iterator> equal_range( const Key& key ) const;

返回一个包含容器中所有具有给定键的元素的范围。该范围由两个迭代器定义，一个指向不小于 key 的第一个元素，另一个指向大于 key 的第一个元素。或者，第一个迭代器可以通过 lower_bound() 获得，第二个迭代器可以通过 upper_bound() 获得。

• (1-2) 将键与 key 进行比较。
• (3-4) 将键与值 x 进行比较。此重载仅在限定 ID Compare::is_transparent 有效且表示一个类型时才参与重载解析。它允许在不构造 Key 实例的情况下调用此函数。

参数

• key - 要计数的元素的键值
• x - 可以与键透明比较的任何类型的值

返回值

std::pair 包含一对迭代器，它们定义了所需范围：第一个指向不小于 key 的第一个元素，第二个指向大于 key 的第一个元素。

如果没有不小于 key 的元素，则将末尾后（参见 end()）迭代器作为第一个元素返回。同样，如果没有大于 key 的元素，则将末尾后迭代器作为第二个元素返回。

复杂度

对容器大小呈对数关系 - O(log size())。

异常

(无)

备注

特性测试宏：__cpp_lib_generic_associative_lookup（用于重载 (3) 和 (4)）。

示例

Main.cpp

#include <map>
#include <iostream>
 
int main()
{
    const std::map<int, const char*> m{
        { 0, "zero" },
        { 1, "one" },
        { 2, "two" },
    };
 
    {
        auto p = m.equal_range(1);
        for (auto& q = p.first; q != p.second; ++q) {
            std::cout << "m[" << q->first << "] = " << q->second << '\n';
        }
 
        if (p.second == m.find(2)) {
            std::cout << "end of equal_range (p.second) is one-past p.first\n";
        } else {
            std::cout << "unexpected; p.second expected to be one-past p.first\n";
        }
    }
 
    {
        auto pp = m.equal_range(-1);
        if (pp.first == m.begin()) {
            std::cout << "pp.first is iterator to first not-less than -1\n";
        } else {
            std::cout << "unexpected pp.first\n";
        }
 
        if (pp.second == m.begin()) {
            std::cout << "pp.second is iterator to first element greater-than -1\n";
        } else {
            std::cout << "unexpected pp.second\n";
        }
    }
 
    {
        auto ppp = m.equal_range(3);
        if (ppp.first == m.end()) {
            std::cout << "ppp.first is iterator to first not-less than 3\n";
        } else {
            std::cout << "unexpected ppp.first\n";
        }
 
        if (ppp.second == m.end()) {
            std::cout << "ppp.second is iterator to first element greater-than 3\n";
        } else {
            std::cout << "unexpected ppp.second\n";
        }
    }
}

输出

m[1] = one
end of equal_range (p.second) is one-past p.first
pp.first is iterator to first not-less than -1
pp.second is iterator to first element greater-than -1
ppp.first is iterator to first not-less than 3
ppp.second is iterator to first element greater-than 3