C++ Standard Library C++ STL Library

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

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