std::unordered_map

std::unordered_map is an associative container that stores key-value pairs with unique keys.

Elements are organized into buckets according to the hash of the key, so lookup, insertion, and erasure have average constant-time complexity.

# Declarations

template<
class Key,
class T,
class Hash = std::hash<Key>,
class KeyEqual = std::equal_to<Key>,
class Allocator = std::allocator<std::pair<const Key, T>>
> class unordered_map;

(since C++11)

namespace pmr {
template<
class Key,
class T,
class Hash = std::hash<Key>,
class KeyEqual = std::equal_to<Key>
> using unordered_map =
std::unordered_map<Key, T, Hash, KeyEqual,
std::pmr::polymorphic_allocator<std::pair<const Key, T>>>;
}

(since C++17)

# Template parameters

• Key: key type.
• T: mapped value type.
• Hash: hash function object used to place keys into buckets. Equivalent keys must produce the same hash value.
• KeyEqual: equality predicate used to test whether two keys are equivalent.
• Allocator: allocator used to manage the stored std::pair<const Key, T> objects. It must satisfy the Allocator requirements.

# Semantics

unordered_map meets the requirements of Container, AllocatorAwareContainer, and UnorderedAssociativeContainer.

Keys are unique: for any key-equivalence class, at most one element is present.

Hash-based lookup relies on both Hash and KeyEqual. If KeyEqual(a, b) is true, then Hash(a) and Hash(b) must yield the same value.

Iteration order is not sorted and does not have the stability guarantees of ordered associative containers such as std::map. Rehashing may move elements between buckets and change iteration order.

# Example

#include <iostream>
#include <string>
#include <unordered_map>
 
int main()
{
    std::unordered_map<std::string, int> word_count{
        {"red", 2},
        {"green", 4},
        {"blue", 1}
    };
 
    word_count["red"] += 1;
    word_count["black"] = 3;
 
    for (const auto& [word, count] : word_count)
        std::cout << word << ": " << count << '\n';
}

This is the typical unordered_map usage pattern: key-based lookup with unique keys, average constant-time updates, and no meaningful sort order.

# Member types

# Iterator invalidation

The end() iterator is invalidated by swap, even though iterators referring to elements remain valid.

References and pointers to stored key-value pairs remain valid across rehashing and swap; they are invalidated only when the referenced element is erased.

# Reference map

# Deduction guides

The class has deduction guides so constructor arguments can infer Key, T, and related policy types where the selected constructor permits it.

# Notes

unordered_map is usually the right default when keys are unique and fast average-case lookup matters more than sorted traversal.

If stable ordering, lower-bound queries, or ordered iteration are important, std::map is the better fit.

# Feature-test macros

# Defect reports

# See also

• unordered_multimap
• map
• flat_map