equal_range in C++ - GeeksforGeeks

28 Sep, 2018
std::equal_range is used to find the sub-range within a given range [first, last) that has all the elements equivalent to a given value. It returns the initial and the final bound of such a sub-range.
This function requires the range to be either sorted or partitioned according to some condition such that all the elements for which the condition evaluates to true are to the left of the given value and rest all are to its right.
It can be used in two ways as shown below:
Comparing elements using <:Syntax:Template
pair 
    equal_range (ForwardIterator first, ForwardIterator last, const T& val);

first: Forward iterator to the first element in the range.
last: Forward iterator to the last element in the range.
val: Value of the subrange to search for in the range.

Return Value: It returns a pair object, whose member pair::first 
is an iterator to the lower bound of the subrange of equivalent 
values, and pair::second its upper bound.
If there is no element equivalent to val, then both first and 
second points to the nearest element greater than val, or if val is
greater than any other value, then both of them point to last.
// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <vector>#include <algorithm>using namespace std;int main(){    vector<int> v = { 10, 10, 30, 30, 30, 100, 10,                      300, 300, 70, 70, 80 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Sorting the vector v    sort(v.begin(), v.end());    // v becomes 10 10 10 30 30 30 70 70 80 100 300 300      // Using std::equal_range and comparing the elements    // with 30    ip = std::equal_range(v.begin(), v.begin() + 12, 30);      // Displaying the subrange bounds    cout << "30 is present in the sorted vector from index "         << (ip.first - v.begin()) << " till "         << (ip.second - v.begin());      return 0;}Output:30 is present in the sorted vector from index 3 till 6
Explanation: After sorting the vector v1, we checked for the bounds within which 30 is present, i.e., from index 3 till index 6.By comparing using a pre-defined function:Syntax: pair 
    equal_range (ForwardIterator first, ForwardIterator last, 
                 const T& val, Compare comp);

Here, first, last and val are the same as previous case.

comp: Binary function that accepts two arguments of the type 
pointed by ForwardIterator (and of type T), and returns a
value convertible to bool. The value returned indicates 
whether the first argument is considered to go before the
second. 
The function shall not modify any of its arguments.
This can either be a function pointer or a function object.

Return Value: It returns a pair object, whose member 
pair::first is an iterator to the lower bound of the subrange 
of equivalent values, and pair::second its upper bound. 
If there is no element equivalent to val, then both first and
second point to the nearest element greater than val,
or if val is greater than any other value, then both
of them point to last.
// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <algorithm>#include <string>#include <vector>#include <functional>using namespace std;  // Defining the BinaryFunctionbool comp(int a, int b){    return (a > b);}int main(){    vector<int> v = { 10, 10, 30, 30, 30, 100, 10,                      300, 300, 70, 70, 80 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Sorting the vector v in descending order    sort(v.begin(), v.end(), greater<int>());    // v becomes 300 300 100 80 70 70 30 30 30 10 10 10      // Using std::equal_range and comparing the elements    // with 10    ip = std::equal_range(v.begin(), v.begin() + 12, 10, comp);      // Displaying the subrange bounds    cout << "10 is present in the sorted vector from index "         << (ip.first - v.begin()) << " till "         << (ip.second - v.begin());      return 0;}Output:10 is present in the sorted vector from index 9 till 12

Comparing elements using <:Syntax:Template
pair 
    equal_range (ForwardIterator first, ForwardIterator last, const T& val);

first: Forward iterator to the first element in the range.
last: Forward iterator to the last element in the range.
val: Value of the subrange to search for in the range.

Return Value: It returns a pair object, whose member pair::first 
is an iterator to the lower bound of the subrange of equivalent 
values, and pair::second its upper bound.
If there is no element equivalent to val, then both first and 
second points to the nearest element greater than val, or if val is
greater than any other value, then both of them point to last.
// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <vector>#include <algorithm>using namespace std;int main(){    vector<int> v = { 10, 10, 30, 30, 30, 100, 10,                      300, 300, 70, 70, 80 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Sorting the vector v    sort(v.begin(), v.end());    // v becomes 10 10 10 30 30 30 70 70 80 100 300 300      // Using std::equal_range and comparing the elements    // with 30    ip = std::equal_range(v.begin(), v.begin() + 12, 30);      // Displaying the subrange bounds    cout << "30 is present in the sorted vector from index "         << (ip.first - v.begin()) << " till "         << (ip.second - v.begin());      return 0;}Output:30 is present in the sorted vector from index 3 till 6
Explanation: After sorting the vector v1, we checked for the bounds within which 30 is present, i.e., from index 3 till index 6.
Syntax:
Template
pair 
    equal_range (ForwardIterator first, ForwardIterator last, const T& val);

first: Forward iterator to the first element in the range.
last: Forward iterator to the last element in the range.
val: Value of the subrange to search for in the range.

Return Value: It returns a pair object, whose member pair::first 
is an iterator to the lower bound of the subrange of equivalent 
values, and pair::second its upper bound.
If there is no element equivalent to val, then both first and 
second points to the nearest element greater than val, or if val is
greater than any other value, then both of them point to last.

// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <vector>#include <algorithm>using namespace std;int main(){    vector<int> v = { 10, 10, 30, 30, 30, 100, 10,                      300, 300, 70, 70, 80 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Sorting the vector v    sort(v.begin(), v.end());    // v becomes 10 10 10 30 30 30 70 70 80 100 300 300      // Using std::equal_range and comparing the elements    // with 30    ip = std::equal_range(v.begin(), v.begin() + 12, 30);      // Displaying the subrange bounds    cout << "30 is present in the sorted vector from index "         << (ip.first - v.begin()) << " till "         << (ip.second - v.begin());      return 0;}
Output:
30 is present in the sorted vector from index 3 till 6

Explanation: After sorting the vector v1, we checked for the bounds within which 30 is present, i.e., from index 3 till index 6.
By comparing using a pre-defined function:Syntax: pair 
    equal_range (ForwardIterator first, ForwardIterator last, 
                 const T& val, Compare comp);

Here, first, last and val are the same as previous case.

comp: Binary function that accepts two arguments of the type 
pointed by ForwardIterator (and of type T), and returns a
value convertible to bool. The value returned indicates 
whether the first argument is considered to go before the
second. 
The function shall not modify any of its arguments.
This can either be a function pointer or a function object.

Return Value: It returns a pair object, whose member 
pair::first is an iterator to the lower bound of the subrange 
of equivalent values, and pair::second its upper bound. 
If there is no element equivalent to val, then both first and
second point to the nearest element greater than val,
or if val is greater than any other value, then both
of them point to last.
// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <algorithm>#include <string>#include <vector>#include <functional>using namespace std;  // Defining the BinaryFunctionbool comp(int a, int b){    return (a > b);}int main(){    vector<int> v = { 10, 10, 30, 30, 30, 100, 10,                      300, 300, 70, 70, 80 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Sorting the vector v in descending order    sort(v.begin(), v.end(), greater<int>());    // v becomes 300 300 100 80 70 70 30 30 30 10 10 10      // Using std::equal_range and comparing the elements    // with 10    ip = std::equal_range(v.begin(), v.begin() + 12, 10, comp);      // Displaying the subrange bounds    cout << "10 is present in the sorted vector from index "         << (ip.first - v.begin()) << " till "         << (ip.second - v.begin());      return 0;}Output:10 is present in the sorted vector from index 9 till 12

Syntax:
 pair 
    equal_range (ForwardIterator first, ForwardIterator last, 
                 const T& val, Compare comp);

Here, first, last and val are the same as previous case.

comp: Binary function that accepts two arguments of the type 
pointed by ForwardIterator (and of type T), and returns a
value convertible to bool. The value returned indicates 
whether the first argument is considered to go before the
second. 
The function shall not modify any of its arguments.
This can either be a function pointer or a function object.

Return Value: It returns a pair object, whose member 
pair::first is an iterator to the lower bound of the subrange 
of equivalent values, and pair::second its upper bound. 
If there is no element equivalent to val, then both first and
second point to the nearest element greater than val,
or if val is greater than any other value, then both
of them point to last.

// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <algorithm>#include <string>#include <vector>#include <functional>using namespace std;  // Defining the BinaryFunctionbool comp(int a, int b){    return (a > b);}int main(){    vector<int> v = { 10, 10, 30, 30, 30, 100, 10,                      300, 300, 70, 70, 80 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Sorting the vector v in descending order    sort(v.begin(), v.end(), greater<int>());    // v becomes 300 300 100 80 70 70 30 30 30 10 10 10      // Using std::equal_range and comparing the elements    // with 10    ip = std::equal_range(v.begin(), v.begin() + 12, 10, comp);      // Displaying the subrange bounds    cout << "10 is present in the sorted vector from index "         << (ip.first - v.begin()) << " till "         << (ip.second - v.begin());      return 0;}
Output:
10 is present in the sorted vector from index 9 till 12

Where can it be used ?
std::lower_bound and std::upper_bound at one place: This function can be used if we want to use both std::lower_bound and std::upper_bound at the same time, as its first pointer will be same as std::lower_bound and its second pointer will be same as std::upper_bound. So, there is no use of separately using them, if we have std::equal_range.// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <vector>#include <algorithm>using namespace std;int main(){    vector<int> v = { 1, 2, 3, 4, 5, 5, 6, 7 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Using std::equal_range and comparing the elements    // with 5    ip = std::equal_range(v.begin(), v.end(), 5);      // Displaying the subrange bounds    cout << "std::lower_bound should be equal to "         << (ip.first - v.begin()) << " and std::upper_bound "         << "should be equal to " << (ip.second - v.begin());      vector<int>::iterator i1, i2;      // Using std::lower_bound    i1 = std::lower_bound(v.begin(), v.end(), 5);    cout << "\nstd::lower_bound is = " << (i1 - v.begin());      // Using std::upper_bound    i2 = std::upper_bound(v.begin(), v.end(), 5);    cout << "\nstd::upper_bound is = " << (i2 - v.begin());      return 0;}Output:std::lower_bound should be equal to 4 and 
std::upper_bound should be equal to 6
std::lower_bound is = 4
std::upper_bound is = 6

std::lower_bound and std::upper_bound at one place: This function can be used if we want to use both std::lower_bound and std::upper_bound at the same time, as its first pointer will be same as std::lower_bound and its second pointer will be same as std::upper_bound. So, there is no use of separately using them, if we have std::equal_range.// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <vector>#include <algorithm>using namespace std;int main(){    vector<int> v = { 1, 2, 3, 4, 5, 5, 6, 7 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Using std::equal_range and comparing the elements    // with 5    ip = std::equal_range(v.begin(), v.end(), 5);      // Displaying the subrange bounds    cout << "std::lower_bound should be equal to "         << (ip.first - v.begin()) << " and std::upper_bound "         << "should be equal to " << (ip.second - v.begin());      vector<int>::iterator i1, i2;      // Using std::lower_bound    i1 = std::lower_bound(v.begin(), v.end(), 5);    cout << "\nstd::lower_bound is = " << (i1 - v.begin());      // Using std::upper_bound    i2 = std::upper_bound(v.begin(), v.end(), 5);    cout << "\nstd::upper_bound is = " << (i2 - v.begin());      return 0;}Output:std::lower_bound should be equal to 4 and 
std::upper_bound should be equal to 6
std::lower_bound is = 4
std::upper_bound is = 6

// C++ program to demonstrate the use of std::equal_range#include <iostream>#include <vector>#include <algorithm>using namespace std;int main(){    vector<int> v = { 1, 2, 3, 4, 5, 5, 6, 7 };      // Declaring an iterator to store the    // return value of std::equal_range    std::pair<std::vector<int>::iterator,              std::vector<int>::iterator> ip;      // Using std::equal_range and comparing the elements    // with 5    ip = std::equal_range(v.begin(), v.end(), 5);      // Displaying the subrange bounds    cout << "std::lower_bound should be equal to "         << (ip.first - v.begin()) << " and std::upper_bound "         << "should be equal to " << (ip.second - v.begin());      vector<int>::iterator i1, i2;      // Using std::lower_bound    i1 = std::lower_bound(v.begin(), v.end(), 5);    cout << "\nstd::lower_bound is = " << (i1 - v.begin());      // Using std::upper_bound    i2 = std::upper_bound(v.begin(), v.end(), 5);    cout << "\nstd::upper_bound is = " << (i2 - v.begin());      return 0;}
Output:
std::lower_bound should be equal to 4 and 
std::upper_bound should be equal to 6
std::lower_bound is = 4
std::upper_bound is = 6

This article is contributed by Mrigendra Singh. If you like GeeksforGeeks and would like to contribute, you can also write an article using contribute.geeksforgeeks.org or mail your article to contribute@geeksforgeeks.org. See your article appearing on the GeeksforGeeks main page and help other Geeks.
Please write comments if you find anything incorrect, or you want to share more information about the topic discussed above.
cpp-algorithm-library
cpp-vector
STL
C++
STL
CPP
Writing code in comment?
Please use ide.geeksforgeeks.org,
generate link and share the link here.
Comments
Old Comments
Operator Overloading in C++
Sorting a vector in C++
Polymorphism in C++
Friend class and function in C++
List in C++ Standard Template Library (STL)
Pair in C++ Standard Template Library (STL)
Convert string to char array in C++
new and delete operators in C++ for dynamic memory
Destructors in C++
Queue in C++ Standard Template Library (STL)