std::multiset<Key,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. Эта перегрузка участвует в разрешении перегрузки, только если qualified-id 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 <set>

template<typename I>
void print_equal_range(I first, I lb, I ub, I last)
{
    for (I i{first}; i != lb; ++i)
        std::cout << *i << ' ';
    std::cout << "[ ";

    for (I i{lb}; i != ub; ++i)
        std::cout << *i << ' ';
    std::cout << ") ";

    for (I i{ub}; i != last; ++i)
        std::cout << *i << ' ';
    std::cout << '\n';
}

int main()
{
    std::multiset<int> c{4, 3, 2, 1, 3, 3};
    std::cout << "c = ";
    print_equal_range(begin(c), begin(c), end(c), end(c));
    for (int key{}; key != 6; ++key)
    {
        std::cout << "key = " << key << "; equal range = ";
        const auto [lb, ub] = c.equal_range(key);
        print_equal_range(begin(c), lb, ub, end(c));
    }
}

Вывод:

c = [ 1 2 3 3 3 4 )
key = 0; equal range = [ ) 1 2 3 3 3 4
key = 1; equal range = [ 1 ) 2 3 3 3 4
key = 2; equal range = 1 [ 2 ) 3 3 3 4
key = 3; equal range = 1 2 [ 3 3 3 ) 4
key = 4; equal range = 1 2 3 3 3 [ 4 )
key = 5; equal range = 1 2 3 3 3 4 [ )

См. также

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