std::multimap<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, нет, в качестве второго элемента возвращается итератор за концом.

Поскольку emplace и insert без подсказки всегда вставляют элементы в верхнюю границу, порядок эквивалентных элементов в диапазоне равных элементов соответствует порядку вставки, если только для вставки элемента в другую позицию не использовались insert или emplace_hint с подсказкой.

(начиная с C++11)

Сложность

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

Примечания

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

Пример

#include <iostream>
#include <map>

int main()
{
    std::multimap<int, char> dict
    {
        {1, 'A'},
        {2, 'B'},
        {2, 'C'},
        {2, 'D'},
        {4, 'E'},
        {3, 'F'}
    };

    auto range = dict.equal_range(2);

    for (auto i = range.first; i != range.second; ++i)
        std::cout << i->first << ": " << i->second << '\n';
}

Вывод:

2: B
2: C
2: D

См. также

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/multimap/equal_range