Apache C++ Standard Library Reference Guide

## equal_range()

Library: Algorithms

    Function

- Local Index
- Summary
- Synopsis
- Description
- Complexity
- Example
- See Also
- Standards Conformance

### Local Index

No Entries

### Summary

Algorithm that finds the largest subrange in a range of values into which a given value can be inserted without violating the ordering of the values

### Synopsis

    #include <algorithm>

    namespace std {
      template <class ForwardIterator, class T>
      pair<ForwardIterator, ForwardIterator>
      equal_range(ForwardIterator start, ForwardIterator finish,
                  const T& value);

      template <class ForwardIterator, class T, class Compare>
      pair<ForwardIterator, ForwardIterator>
      equal_range(ForwardIterator start, ForwardIterator finish,
                  const T& value, Compare comp);
    }

### Description

The `equal_range()` algorithm performs a binary search on an ordered range to determine where the element `value` can be inserted without violating the range's ordering. The library includes two versions of the algorithm. The first version uses `operator<()` to search for the valid insertion range, and assumes that the sequence was sorted using the same ordering. The second version allows you to specify a function object of type `Compare`, and assumes that `Compare` was the function used to sort the sequence. The function object must be a binary predicate.

`equal_range()` returns a pair of iterators, `i` and `j`, that define a range containing elements equivalent to `value`, in other words, the first and last valid insertion points for `value`. If `value` is not an element in the container, `i` and `j` are equal. Otherwise, `i` points to the first element not "less" than `value`, and `j` points to the first element greater than value. In the second version, the ordering is defined by the comparison object. Formally, `equal_range()` returns a sub-range `[i, j)` such that `value` can be inserted at any iterator `k` within the range without violating the ordering. Depending upon the version of the algorithm used, `k` must satisfy one of the following conditions:

`!(*k < value) && !(value < *k)`

or

`comp(*k,value) == false && comp(value, *k) == false`

The range `[start,finish)` is assumed to be sorted. Type `T` must be LessThanComparable.

### Complexity

`equal_range()` performs at most `2 * log(finish - start) + 1` comparisons.

### Example

    //
    // eqlrange.cpp
    //

    #include <algorithm>
    #include <functional>
    #include <iostream>
    #include <vector>

    int main ()
    {
        // Typedef for convenience.
        typedef std::vector<int, std::allocator<int> > vector;

        vector::value_type arr[] = {
            0, 1, 2, 2, 3, 4, 2, 2, 2, 6, 7
        };

        // Set up a vector.
        vector v1 (arr, arr + sizeof arr / sizeof *arr);

        // Try equal_range variants.
        std::pair<vector::iterator, vector::iterator> p1 =
            std::equal_range (v1.begin (), v1.end (), 3);

        std::pair<vector::iterator, vector::iterator> p2 =
            std::equal_range (v1.begin (), v1.end (), 2,
                         std::less<vector::value_type> ());

        // Output results.
        std::cout << "\nThe equal range for 3 is: "
                  << "(" << *p1.first << " , "
                  << *p1.second << ")" << std::endl;

        std::cout << "\nThe equal range for 2 is: "
                  << "(" << *p2.first << " , "
                  << *p2.second << ")" << std::endl;

        return 0;
    }

    Program Output

    The equal range for 3 is: (3 , 4)

    The equal range for 2 is: (2 , 3)

### See Also

binary_function, `lower_bound()`, `upper_bound()`

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 25.3.3.3