C++ unordered_map

A C++ unordered_map is an STL container that stores key-value pairs. Use std::unordered_map when each key should be unique and you want fast lookup by key, without needing sorted order.

It is similar to std::map, but it does not keep keys sorted. Internally, it uses hashing to find keys quickly.

Including the Header

To use an unordered map, include the <unordered_map> header. The type is written as std::unordered_map<KeyType, ValueType>, where the first type is the key and the second type is the value.

#include <iostream>
#include <string>
#include <unordered_map>

int main(void) {
    std::unordered_map<std::string, int> scores;

    scores["Mia"] = 92;
    scores["Alex"] = 88;
    scores["Zoe"] = 95;
    scores["Alex"] = 90;

    std::cout << "Alex: " << scores["Alex"] << std::endl;
    std::cout << "Mia: " << scores["Mia"] << std::endl;
    std::cout << "Size: " << scores.size() << std::endl;

    return 0;
}

Output:

Alex: 90
Mia: 92
Size: 3

The key "Alex" is assigned twice, but the unordered map stores only one value for that key. The second assignment updates the existing value from 88 to 90.

Adding and Updating Values

The square bracket operator [] is a common way to add or update a key-value pair. If the key already exists, the value is changed. If the key does not exist, a new entry is created.

Be aware that reading with [] also creates an entry if the key is missing. If you only want to check whether a key exists, use find() or count() instead.

Finding and Removing Keys

The find() function searches for a key. If the key is found, it returns an iterator pointing to that entry. If the key is not found, it returns end(). The erase() function removes an entry by key.

#include <iostream>
#include <string>
#include <unordered_map>

int main(void) {
    std::unordered_map<std::string, int> inventory = {
        {"apples", 12},
        {"bananas", 8},
        {"oranges", 5}
    };

    inventory.insert({"pears", 6});
    inventory["bananas"] += 2;
    inventory.erase("oranges");

    auto found = inventory.find("bananas");
    if (found != inventory.end()) {
        std::cout << "Bananas: " << found->second << std::endl;
    }

    std::cout << "Has oranges: " << inventory.count("oranges") << std::endl;
    std::cout << "Total item types: " << inventory.size() << std::endl;

    return 0;
}

Output:

Bananas: 10
Has oranges: 0
Total item types: 3

This program adds pears, increases the value for bananas, and removes oranges. It uses find() before reading the banana count so the code does not accidentally create a missing key.

Order Is Not Guaranteed

An unordered map can be looped through with a range-based for loop, but the order of entries is not sorted and should not be relied on. If you need alphabetical or numeric key order when looping, use std::map instead.

Common unordered_map Functions

Function	What it does
map[key]	Adds a missing key with a default value, then returns its value
insert({key, value})	Adds a pair only if the key is not already present
erase(key)	Removes the entry with that key
find(key)	Returns an iterator to the entry or end()
count(key)	Returns 1 if the key exists, otherwise 0
size()	Returns the number of key-value pairs

When To Use unordered_map

Use std::unordered_map when you need unique keys and fast key-based lookup, and you do not care about the order of the keys. Use std::map when sorted order matters.

Takeaway: std::unordered_map connects unique keys to values and is a good default choice for fast lookups when sorted output is not required.