unordered_map equal_range in C++

The unordered_map::equal_range() is an inbuilt function in C++ STL which is used to return the bounds of a range that includes all the elements in the container with a key that compares equal to k. The unordered_map containers are the container where keys are unique, the range will include one element at most. The range is defined by two iterators,

• The first one pointing to the first element of the range.
• The second one pointing past the last element of the range.

Parameters: This function accepts single parameter key which is used to hold the value to be compared.

Return Value: It returns a pair which contains a pair of iterators defining the wanted range. Where its members are pair::first and pair::second. The first one is an iterator to the lower bound of the range and the second one is an iterator to its upper bound. The elements in the range are those between these two iterators, including first pair, but not second.

Below programs illustrates the unordered_map::equal_range() function in C++ STL:

Example 1:

// C++ program to implement
// unordered_map::equal_range() function
#include <iostream>
#include <unordered_map>
using namespace std;

// main program
int main()
{
    unordered_map <int, int> map = { { 1, 3 },
                                     { 1, 2 },
                                     { 3, 1 },
                                     { 2, 3 } };
    for (int j = 1; j <= 3; j++) {
        auto range = map.equal_range(j);

        //'auto' is a keyword
        for (auto i = range.first; i != range.second; i++) {

            // iterates first to last
            cout << "first : " << i->first;
            cout << "\nsecond : " << i->second << endl
                << endl;
        }
    }
}

Output:

first : 1
second : 3

first : 2
second : 3

first : 3
second : 1

Program 2:

// C++ program to search 'unordered map' container
#include <iostream>
#include <unordered_map>
using namespace std;

// Rename 'unordered_map<int, char>' as 'gfg'
typedef unordered_map<char, char> gfg;


int main()
{
    // 'g' is object
    gfg g;

    // Container values
    // Contents are look like [a, b] [c, d] [e, f]
    g.insert(gfg::value_type('a', 'b'));
    g.insert(gfg::value_type('b', 'd'));
    g.insert(gfg::value_type('e', 'f'));

    // Look into the syntax part above
    // here 'f' is key
    pair<gfg::iterator, gfg::iterator> p1 = g.equal_range('f');

    // 'f' is not exits, so no output for 'f'
    cout << "search for 'f' :";
    for (; p1.first != p1.second; ++p1.first) {
        cout << p1.first->first << ", " << p1.first->second << endl;
    }

    // Successful search
    // Here 'a' is key
    p1 = g.equal_range('a');

    // 'a' is exits, so it searched successfully
    cout << "\nsearch for 'a' : [";
    for (; p1.first != p1.second; ++p1.first) {
        cout << p1.first->first << ", " << p1.first->second << "]";
    }

    return 0;
}

Output:

search for 'f' :
search for 'a' : [a, b]

Complexity:

• Average case: Linear in the number of elements with the key k, which is constant.
• worst case: Linear in the size of the container.