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. Этот перегруз участвует в разрешении перегрузки только в том случае, если квалифицированный идентификатор Compare::is_transparent допустим и обозначает тип. Он позволяет вызывать эту функцию без создания экземпляра Key.

Параметры

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

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

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

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

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

(с C++11)

Сложность

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

Примечания

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

Пример

#include <set>
#include <iostream>
 
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	возвращает диапазон элементов, соответствующих заданному ключу (шаблонная функция)

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