std::map<Key,T,Compare,Allocator>::equal_range

std::pair<iterator,iterator> equal_range( const Key& key );	(1)
std::pair<const_iterator,const_iterator> equal_range( const Key& key ) const;	(2)
template< class K > std::pair<iterator,iterator> equal_range( const K& x );	(3)	(с C++14)
template< class K > std::pair<const_iterator,const_iterator> equal_range( const K& x ) const;	(4)	(с C++14)

Возвращает диапазон, содержащий все элементы с заданным ключом в контейнере. Диапазон определяется двумя итераторами, один из которых указывает на первый элемент, который не меньше key, а другой — на первый элемент, больший key. В качестве альтернативы, первый итератор можно получить с помощью lower_bound(), а второй — с помощью upper_bound().

1,2) Сравнивает ключи с key.

3,4) Сравнивает ключи со значением x. Этот перегруз участвует в разрешении перегрузки только в том случае, если квалифицированный идентификатор Compare::is_transparent является допустимым и обозначает тип. Он позволяет вызвать эту функцию без создания экземпляра Key.

Параметры

key	-	значение ключа для сравнения с элементами
x	-	альтернативное значение, которое можно сравнить с `Key`

Возвращаемое значение

std::pair, содержащий пару итераторов, определяющих желаемый диапазон: первый указывает на первый элемент, который не меньше key, а второй — на первый элемент, больший key.

Если нет элементов, не меньших key, возвращается итератор past-the-end (см. end()). Аналогично, если нет элементов, больших key, в качестве второго элемента возвращается итератор past-the-end.

Сложность

Логарифмическая по отношению к размеру контейнера.

Примечания

Макрос проверки наличия функции	Значение	Стандарт	Функция
`__cpp_lib_generic_associative_lookup`	201304L	(C++14)	Гетерогенный поиск по сравнению, (3,4)

Пример

#include <iostream>
#include <map>
 
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

См. также

find	находит элемент с определенным ключом (публичный член-функция)
contains (C++20)	проверяет, содержит ли контейнер элемент с определенным ключом (публичный член-функция)
count	возвращает количество элементов, соответствующих определенному ключу (публичный член-функция)
upper_bound	возвращает итератор на первый элемент, больший, чем заданный ключ (публичный член-функция)
lower_bound	возвращает итератор на первый элемент, не меньший, чем заданный ключ (публичный член-функция)
equal_range	возвращает диапазон элементов, соответствующих определенному ключу (шаблон функции)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/container/map/equal_range