std::equal_range

From Cppreference

Jump to: navigation, search
Defined in header <algorithm>

template< class ForwardIterator, class T >

std::pair<ForwardIterator,ForwardIterator>
    equal_range( ForwardIterator first, ForwardIterator last,

                 const T& value );
(1)
template< class ForwardIterator, class T, class Compare >

std::pair<ForwardIterator,ForwardIterator>
    equal_range( ForwardIterator first, ForwardIterator last,

                 const T& value, Compare comp );
(2)

Returns a range containing all elements equal to value in the sorted range [first, last). The range is defined by two iterators, one pointing to the first element that is not less than value and another pointing to the first element greater than value. The first iterator may be alternatively obtained with lower_bound(), the second - with upper_bound().

The first version uses operator< to compare the elements, the second version uses the given comparison function comp.

Contents

[edit] Parameters

first, last - the range of elements to examine
value - value to compare the elements to
comp - comparison function which returns ​true if the first argument is less than the second.

The signature of the comparison function should be equivalent to the following:

bool cmp(const Type1 &a, const Type2 &b);

The signature does not need to have const &, but the function must not modify the objects passed to it.
The type Type1 must be such that an object of type T can be implicitly converted to Type1. The type Type2 must be such that an object of type ForwardIterator can be dereferenced and then implicitly converted to Type2. ​

[edit] Return value

std::pair containing a pair of iterators defining the wanted range, the first pointing to the first element that is not less than value and the second pointing to the first element greater than value.

If there are no elements not less than value, last is returned as the first element. Similarly if there are no elements greater than value, last is returned as the second element

[edit] Complexity

logarithmic in the distance between first and last

[edit] Equivalent function

[edit] Example

[edit] See also

lower_bound
returns an iterator to the first element not less than the given value
(function template)
upper_bound
returns an iterator to the first element greater than a certain value
(function template)
binary_search
determines if an element exists in a certain range
(function template)