C++ unordered_multimap - equal_range() Function

The C++ unordered_multimap::equal_range function returns the bounds of a range which includes all elements in the unordered_multimap container with keys that are equivalent to the specified value. It returns a pair, with pair::first member as the lower bound of the range, and pair::second member as the upper bound of the range.

If no match is found, it will return the range with end as both its lower and upper range bounds.

Syntax

C++11

pair<const_iterator,const_iterator> 
  equal_range (const key_type& k) const;

pair<iterator,iterator> 
  equal_range (const key_type& k);

Parameters

`k`	Specify key to compare.

Return Value

Returns a pair, with pair::first member as the lower bound of the range, and pair::second member as the upper bound of the range.

Time Complexity

Average case: Constant i.e, Θ(1).
Worst case: Linear in container sizei.e, Θ(n).

Example:

In the example below, the unordered_multimap::equal_range function returns the bounds of a range for specified key of uMMap.

#include <iostream>
#include <unordered_map>
using namespace std;
 
int main (){
  unordered_multimap<string, string> uMMap;
  unordered_multimap<string, string>::iterator it;

  uMMap.insert(pair<string, string>("CAN", "Montreal"));
  uMMap.insert(pair<string, string>("IND", "Mumbai"));
  uMMap.insert(pair<string, string>("IND", "Delhi"));
  uMMap.insert(pair<string, string>("USA", "New York"));
  uMMap.insert(pair<string, string>("USA", "Washington"));  

  cout<<"uMMap contains:\n";
  for(it = uMMap.begin(); it != uMMap.end(); ++it)
    cout<<it->first<<"  "<<it->second<<"\n";

  //finding bound range of key='USA'
  pair<unordered_multimap<string, string>::iterator,
       unordered_multimap<string, string>::iterator> pit;
  pit = uMMap.equal_range("USA");

  cout<<"\nLower bound - "<<pit.first->first<<":"<<pit.first->second<<"\n";
  cout<<"Upper bound - "<<pit.second->first<<":"<<pit.second->second<<"\n";

  return 0;
}

The output of the above code will be:

uMMap contains:
USA  Washington
USA  New York
IND  Delhi
IND  Mumbai
CAN  Montreal

Lower bound - USA:Washington
Upper bound - IND:Delhi

Example:

Lets consider another example where equal_range() function is used to specify bound range to delete elements from the unordered_multimap.

#include <iostream>
#include <unordered_map>
using namespace std;
 
int main (){
  unordered_multimap<string, string> uMMap;
  unordered_multimap<string, string>::iterator it;

  uMMap.insert(pair<string, string>("CAN", "Montreal"));
  uMMap.insert(pair<string, string>("IND", "Mumbai"));
  uMMap.insert(pair<string, string>("IND", "Delhi"));
  uMMap.insert(pair<string, string>("USA", "New York"));
  uMMap.insert(pair<string, string>("USA", "Washington"));  

  cout<<"uMMap contains:\n";
  for(it = uMMap.begin(); it != uMMap.end(); ++it)
    cout<<it->first<<"  "<<it->second<<"\n";

  //finding bound range of key='USA'
  pair<unordered_multimap<string, string>::iterator,
       unordered_multimap<string, string>::iterator> pit;
  pit = uMMap.equal_range("USA");

  //erasing the elements from the multimap
  uMMap.erase(pit.first, pit.second);

  cout<<"\nuMMap contains:\n";
  for(it = uMMap.begin(); it != uMMap.end(); ++it)
    cout<<it->first<<"  "<<it->second<<"\n";

  return 0;
}

The output of the above code will be:

uMMap contains:
USA  Washington
USA  New York
IND  Delhi
IND  Mumbai
CAN  Montreal

uMMap contains:
IND  Delhi
IND  Mumbai
CAN  Montreal

❮ C++ <unordered_map> Library