=====equal_range=====
Syntax:

<code>
    #include <algorithm>
    pair<forward_iterator,forward_iterator> equal_range( forward_iterator first, forward_iterator last, const TYPE& val );
    pair<forward_iterator,forward_iterator> equal_range( forward_iterator first, forward_iterator last, const TYPE& val, CompFn comp );
</code>

The equal_range() function returns the range of elements between first and last
that are equal to val. This function assumes that the elements between first
and last are in order according to comp, if it is specified, or the < operator
otherwise.

equal_range() can be thought of as a combination of the [[lower_bound]] and
[[upper_bound]] functions, since the first of the pair of iterators that it
returns is what lower_bound returns and the second iterator in the pair is
what upper_bound returns.

For example, the following code uses equal_range() to determine all of the
possible places that the number 8 can be inserted into an ordered vector of
integers such that the existing ordering is preserved:

<code>
   vector<int> nums;
   nums.push_back( -242 );
   nums.push_back( -1 );
   nums.push_back( 0 );
   nums.push_back( 5 );
   nums.push_back( 8 );
   nums.push_back( 8 );
   nums.push_back( 11 );

   pair<vector<int>::iterator, vector<int>::iterator> result;
   int new_val = 8;

   result = equal_range( nums.begin(), nums.end(), new_val );

   cout << "The first place that " << new_val << " could be inserted is before "
        << *result.first << ", and the last place that it could be inserted is before "
        << *result.second << endl;
</code>

The above code produces the following output:

<code terminal>
   The first place that 8 could be inserted is before 8,
   and the last place that it could be inserted is before 11
</code>

Related Topics: [[binary_search]], [[lower_bound]], [[upper_bound]]