C++ set equal_range
The C++ set equal_range method is employed to retrieve the boundaries of the range that encompasses all elements in the container matching the specified value. Given that the set container does not allow duplicate values, this range will encompass a maximum of one element.
If the value "val" does not correspond to any value within the container, the resulting range will have a length of 0, and both iterators will indicate the closest value greater than "val". Conversely, if "val" exceeds all elements in the container, the iterators will point to the end of the container.
Syntax
pair<const_iterator,const_iterator> equal_range (const value_type& val) const;
pair<iterator,iterator> equal_range (const value_type& val);
The range is determined by a pair of iterators: one indicating the initial element that is equal to or greater than the specified value val, and the other indicating the first element that is greater than val.
Parameter
val : value to be searched in the set container.
Return value
This function generates a pair where the first element represents the lower limit of the range equivalent to the result of lowerbound(val), and the second element represents the upper limit corresponding to the result of upperbound(val).
Complexity
Logarithmic in size.
Iterator validity
No changes.
Data Races
The container is accessed (neither the constant nor non-constant versions alter the container).
Simultaneously retrieving the elements of a set is considered secure.
Exception Safety
If an error is raised, the container remains unchanged.
Example 1
Let's see the simple example:
#include <iostream>
#include <set>
using namespace std;
int main(void) {
set<char> m = {'a','b','c','d'};
auto ret = m.equal_range('b');
cout << "Lower bound of b is: " << *ret.first<< endl;
cout << "Upper bound of b is: " << *ret.second<< endl;
return 0;
}
Output:
Lower bound of b is: b
Upper bound of b is: c
In the aforementioned example, the minimum value of b is denoted as b, and the maximum value of b is represented as c.
Example 2
Let's see a simple example:
#include <iostream>
#include <set>
using namespace std;
int main()
{
// initialize container
set<int> mp;
// insert elements in random order
mp.insert( 4 );
mp.insert( 1 );
mp.insert( 6 );
pair<set<int>::const_iterator,set<int>::const_iterator> ret;
ret = mp.equal_range(10);
cout << "The lower bound is: " << *ret.first;
cout << "\nThe upper bound is: " << *ret.second;
return 0;
}
Output:
The lower bound is 3
The upper bound is 3
In the example provided, the equal_range method returns the end iterator, specifically 3, as it attempts to search for the value 10 within the set mp but does not find it.
Example 3
Let's see a simple example:
#include <set>
#include <iostream>
int main( )
{
using namespace std;
typedef set<int, less< int > > IntSet;
IntSet s1;
set <int, less< int > > :: const_iterator s1_RcIter;
s1.insert( 10 );
s1.insert( 20 );
s1.insert( 30 );
pair <IntSet::const_iterator, IntSet::const_iterator> p1, p2;
p1 = s1.equal_range( 20 );
cout << "The upper bound of the element with "
<< "a key of 20 in the set s1 is: "
<< *(p1.second) << "." << endl;
cout << "The lower bound of the element with "
<< "a key of 20 in the set s1 is: "
<< *(p1.first) << "." << endl;
// Compare the upper_bound called directly
s1_RcIter = s1.upper_bound( 20 );
cout << "A direct call of upper_bound( 20 ) gives "
<< *s1_RcIter << "," << endl
<< "matching the 2nd element of the pair"
<< " returned by equal_range( 20 )." << endl;
p2 = s1.equal_range( 40 );
// If no match is found for the key,
// both elements of the pair return end( )
if ( ( p2.first == s1.end( ) ) && ( p2.second == s1.end( ) ) )
cout << "The set s1 doesn't have an element "
<< "with a key less than 40." << endl;
else
cout << "The element of set s1 with a key >= 40 is: "
<< *(p1.first) << "." << endl;
return 0;
}
Output:
The upper bound of the element with a key of 20 in the set s1 is: 30.
The lower bound of the element with a key of 20 in the set s1 is: 20.
A direct call of upper_bound( 20 ) gives 30,
matching the 2nd element of the pair returned by equal_range( 20 ).
The set s1 doesn't have an element with a key less than 40.
Example 4
Let's see a simple example:
#include <iostream>
#include <set>
using namespace std;
int main ()
{
std::set<int> myset;
for (int i=1; i<=5; i++) myset.insert(i*10); // myset: 10 20 30 40 50
pair<std::set<int>::const_iterator,set<int>::const_iterator> ret;
ret = myset.equal_range(30);
cout << "The lower bound points to: " << *ret.first << '\n';
cout << "The upper bound points to: " << *ret.second << '\n';
return 0;
}
Output:
The lower bound points to: 30
The upper bound points to: 40
