C++ unordered_multimap - reserve() Function

The C++ unordered_multimap::reserve function is used to request a capacity change in the unordered_multimap. It sets the number of buckets in the container such that the container contains at least specified number (n) of elements. If n is greater than the bucket_count multiplied by max_load_factor, the container's bucket_count is increased and a rehash is forced. If n is less than the bucket_count multiplied by max_load_factor, the function may have no effect. A rehash is the reconstruction of the hash table in which all elements of the container is rearranged according to their hash values into the new set of buckets.

As an unordered_multimap is implemented using hash table where a bucket is a slot in the container's internal hash table to which elements are assigned based on the hash value. The number of buckets directly influences the load_factor of the container's hash table. The container automatically increases the number of buckets to keep the load_factor below its max_load_factor which causes rehash whenever the number of buckets is increased.

Syntax

• C++11

void reserve (size_type n);

Parameters

Return Value

None.

Time Complexity

Average case: Linear i.e, Θ(n).
Worst case: Quadratic i.e, Θ(n²).

Example:

In the example below, the unordered_multimap::reserve function is used to request a capacity change of uMMap container.

#include <iostream>
#include <unordered_map>
using namespace std;
 
int main (){
  unordered_multimap<string, string> uMMap;
  uMMap = {{"CAN", "Ottawa"}, {"USA", "Washington"}, 
           {"IND", "Delhi"}, {"CAN", "Toronto"}};

  cout<<"uMMap contains "<<uMMap.bucket_count()<<" buckets:";
  for(unsigned int i = 0; i < uMMap.bucket_count(); i++) {
    cout<<"\nThe bucket #"<<i<<" contains: ";   
    for(auto it = uMMap.begin(i); it != uMMap.end(i); ++it) {
      cout<<it->first<<":"<<it->second<<" ";
    } 
  }  

  cout<<"\n\nCapacity is changed using reserve function.\n\n";
  uMMap.reserve(5);

  cout<<"uMMap contains "<<uMMap.bucket_count()<<" buckets:";
  for(unsigned int i = 0; i < uMMap.bucket_count(); i++) {
    cout<<"\nThe bucket #"<<i<<" contains: ";   
    for(auto it = uMMap.begin(i); it != uMMap.end(i); ++it) {
      cout<<it->first<<":"<<it->second<<" ";
    } 
  }  

  return 0;
}

The output of the above code will be:

uMMap contains 13 buckets:
The bucket #0 contains: 
The bucket #1 contains: 
The bucket #2 contains: 
The bucket #3 contains: 
The bucket #4 contains: 
The bucket #5 contains: 
The bucket #6 contains: 
The bucket #7 contains: 
The bucket #8 contains: 
The bucket #9 contains: 
The bucket #10 contains: USA:Washington 
The bucket #11 contains: IND:Delhi 
The bucket #12 contains: CAN:Toronto CAN:Ottawa 

Capacity is changed using reserve function.

uMMap contains 5 buckets:
The bucket #0 contains: 
The bucket #1 contains: 
The bucket #2 contains: CAN:Toronto CAN:Ottawa IND:Delhi 
The bucket #3 contains: USA:Washington 
The bucket #4 contains: