The C++ Multiset equal_range method is utilized to retrieve the boundary of the range that encompasses all elements within the container matching the specified value.
If the value of "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 that is greater than "val". On the other hand, if "val" exceeds all elements in the container, the iterators will point to the end of the tutorial on IC++ programming.
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 established by two iterators: one indicating the initial element that is equal to or greater than the specified value val, and the other indicating the first element exceeding the value val.
Parameter
The variable "val" represents the value that is to be searched within the multiset container.
Return value
This function outputs a pair where the first element represents the lower limit of the range equivalent to the result of lowerbound(val), and the second element corresponds to the upper limit of the range equivalent 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).
Accessing the elements of a multiset concurrently is considered to be a secure operation.
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) {
multiset<char> m = {'a','b','c','a'};
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 previous illustration, the minimum value of b is denoted as b, while 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
multiset<int> mp;
// insert elements in random order
mp.insert( 4 );
mp.insert( 1 );
mp.insert( 4 );
pair<multiset<int>::const_iterator,multiset<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 aforementioned scenario, the equal_range method returns an iterator pointing to end or position 3. This occurs because it searches for the value 10 within the multiset mp, which is not found, leading to the iterator pointing to the end position.
Example 3
Let's see a simple example:
#include <set>
#include <iostream>
int main( )
{
using namespace std;
typedef multiset<int, less< int > > IntMultiset;
IntMultiset s1;
multiset <int, less< int > > :: const_iterator s1_RcIter;
s1.insert( 10 );
s1.insert( 20 );
s1.insert( 30 );
pair <IntMultiset::const_iterator, IntMultiset::const_iterator> p1, p2;
p1 = s1.equal_range( 20 );
cout << "The upper bound of the element with "
<< "a key of 20 in the multiset s1 is: "
<< *(p1.second) << "." << endl;
cout << "The lower bound of the element with "
<< "a key of 20 in the multiset 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 multiset s1 doesn't have an element "
<< "with a key less than 40." << endl;
else
cout << "The element of multiset 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 multiset s1 is: 30.
The lower bound of the element with a key of 20 in the multiset 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 multiset 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::multiset<int> mymultiset;
for (int i=1; i<=5; i++) mymultiset.insert(i*10); // mymultiset: 10 20 30 40 50
pair<std::multiset<int>::const_iterator,multiset<int>::const_iterator> ret;
ret = mymultiset.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
