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, в качестве первого элемента возвращается итератор за концом диапазона (см. end()). Аналогично, если нет элементов, которые больше key, в качестве второго элемента возвращается итератор за концом диапазона.

Сложность

Логарифмическая относительно размера контейнера.

Примечания

Макрос проверки наличия функции	Значение	Стандарт	Функция
`__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	находит диапазон элементов, соответствующих заданному значению, с помощью двоичного поиска (шаблон функции и функциональный объект алгоритма)
ranges::equal_range (C++20)

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