The C++ multimap's equal_range function is employed to retrieve the range's boundaries that encompass all key elements in the container matching x.
If the value of x doesn't correspond to any key within the data structure, the resulting range will have a length of 0, and both iterators will indicate the closest value greater than x. Conversely, if x surpasses all the elements stored in the container, the iterators will point towards the end of the collection.
Syntax
pair<const_iterator,const_iterator> equal_range (const key_type& k) const;
pair<iterator,iterator> equal_range (const key_type& k);
The range is determined by a pair of iterators. It provides the limits of a range that encompasses all the items in the container with a key that matches k.
Parameter
k : key to be searched in the multimap container.
Return value
This function produces a pair where the first element represents the lower limit of the range associated with the value that lowerbound(x) would yield, and the second element represents the upper limit corresponding to the value that upperbound(x) would produce.
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 and modifying elements concurrently is considered safe when there are no mapped values being accessed.
Exception Safety
If an error is raised, the container remains unchanged.
Example 1
Let's see the simple example:
#include <iostream>
#include <map>
using namespace std;
int main(void) {
map<char, int> m = {
{'a', 1},
{'b', 2},
{'c', 3},
{'c', 4},
{'e', 5},
};
auto ret = m.equal_range('b');
cout << "Lower bound of b is: " << ret.first->first <<
" = " << ret.first->second << endl;
cout << "Upper bound of b is: " << ret.second->first <<
" = " << ret.second->second << endl;
return 0;
}
Output:
Lower bound of b is: b = 2
Upper bound of b is: c = 3
In the given example, 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 <multimap>
using namespace std;
int main()
{
// initialize container
multimap<int, int> mp;
// insert elements in random order
mp.insert({ 4, 30 });
mp.insert({ 1, 40 });
mp.insert({ 6, 60 });
pair<multimap<int, int>::iterator, multimap<int, int>::iterator> it;
// iterator of pairs
it = mp.equal_range(10);
cout << "The lower bound is " <<
it.first->first << ":" << it.first->second;
cout << "\nThe upper bound is " <<
it.second->first << ":" << it.second->second;
return 0;
}
Output:
The lower bound is 3:0
The upper bound is 3:0
In the example provided, the equal_range method yields a result of 0 as it attempts to locate the value 10, which does not match any key within the multimap mp.
Example 3
Let's see a simple example:
#include <map>
#include <iostream>
int main( )
{
using namespace std;
typedef multimap <int, int, less<int> > IntMMap;
IntMMap m1;
multimap <int, int> :: const_iterator m1_RcIter;
typedef pair <int, int> Int_Pair;
m1.insert ( Int_Pair ( 1, 10 ) );
m1.insert ( Int_Pair ( 2, 20 ) );
m1.insert ( Int_Pair ( 3, 30 ) );
pair <IntMMap::const_iterator, IntMMap::const_iterator> p1, p2;
p1 = m1.equal_range( 2 );
cout << "The lower bound of the element with "
<< "a key of 2 in the multimap m1 is: "
<< p1.first -> second << "." << endl;
cout << "The upper bound of the element with "
<< "a key of 2 in the multimap m1 is: "
<< p1.second -> second << "." << endl;
// Compare the upper_bound called directly
m1_RcIter = m1.upper_bound( 2 );
cout << "A direct call of upper_bound( 2 ) gives "
<< m1_RcIter -> second << "," << endl
<< " matching the 2nd element of the pair"
<< " returned by equal_range( 2 )." << endl;
p2 = m1.equal_range( 4 );
// If no match is found for the key,
// both elements of the pair return end( )
if ( ( p2.first == m1.end( ) ) && ( p2.second == m1.end( ) ) )
cout << "The multimap m1 doesn't have an element "
<< "with a key less than 4." << endl;
else
cout << "The element of multimap m1 with a key >= 40 is: "
<< p1.first -> first << "." << endl;
}
Output:
The lower bound of the element with a key of 2 in the multimap m1 is: 20.
The upper bound of the element with a key of 2 in the multimap m1 is: 30.
A direct call of upper_bound( 2 ) gives 30,
matching the 2nd element of the pair returned by equal_range( 2 ).
The multimap m1 doesn't have an element with a key less than 4.
Example 4
Let's see a simple example:
#include <iostream>
#include <string>
#include <map>
int main()
{
std::multimap<std::string, int> m = {
{"A", 3},
{"B", 1},
{"A", 4},
{"D", 5}
};
using iterator = decltype(m)::iterator;
std::pair<iterator, iterator> ret = m.equal_range("B");
for (iterator it = ret.first; it != ret.second; ++it) {
std::cout << it->first << "," << it->second << std::endl;
}
}
Output:
