Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C++

std::unordered_map — a hash map with unique keys

std::unordered_map stores key–value pairs without a guaranteed order. Learn non-inserting lookup, the difference between operator[] and at, and how bucket management affects iterator validity.

Version: C++23; repository compiler flag, production runtime not attested

Syntax

#include <unordered_map>
std::unordered_map<Key, T> map;

std::unordered_map<Key, T> from <unordered_map> stores at most one value for each equivalent key. Iteration order is unspecified. Lookup and insertion cost O(1) on average and O(n) in the worst case. Equivalent keys must have the same hash; matching hashes do not imply equivalent keys.

find(key) does not insert: it returns an iterator or end(), the past-the-end iterator, which must not be dereferenced. operator[] returns a reference to the value and inserts a missing key; with the default allocator, the new value is value-initialized, giving 0 for int. at(key) does not insert and throws std::out_of_range for a missing key. emplace(...) returns an iterator and insertion flag as a pair; a duplicate does not overwrite the value.

size() reports the element count, bucket_count() the bucket count, and load_factor() the average number of elements per bucket. max_load_factor() reads the load threshold; max_load_factor(z) requires positive z. Set the threshold before reserve(n), which plans for n total elements, not n additional elements. It is equivalent to rehash(ceil(n / max_load_factor())). rehash(n) ensures at least n buckets and enough buckets for the current elements and threshold; the exact count depends on the implementation.

Rehashing invalidates iterators but not pointers or references to elements. Insertion, including through operator[], can trigger it. clear() removes every element, makes size() equal to 0, and invalidates handles to removed elements; do not treat it as a guarantee that all container memory is released.

Entry scope: C++23. A repository compiler flag does not attest the production runtime. The source is an evolving working draft rather than frozen C++23 text; this entry does not rely on the newer extensions shown there.

Reference identifiers covered by this entry: std::unordered_map::find, std::unordered_map::end, std::unordered_map::clear, std::unordered_map::operator[], std::unordered_map::max_load_factor, std::unordered_map::reserve, std::unordered_map::rehash, std::unordered_map::size, std::unordered_map::load_factor, std::unordered_map::bucket_count, std::unordered_map::at, std::unordered_map::emplace.

Examples

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

int main() {
    std::unordered_map<std::string, int> counts;
    counts.max_load_factor(0.75f);
    counts.reserve(8);

    counts.emplace("apple", 2);
    ++counts["apple"];
    ++counts["pear"];
    const bool inserted = counts.emplace("apple", 99).second;

    if (auto it = counts.find("apple"); it != counts.end()) {
        std::cout << "apple=" << it->second << '\n';
    }
    std::cout << std::boolalpha << "duplicate inserted=" << inserted << '\n';
    std::cout << "pear=" << counts.at("pear") << '\n';
    std::cout << "size=" << counts.size() << '\n';

    counts.rehash(32);
    std::cout << "buckets>=32=" << (counts.bucket_count() >= 32) << '\n';
    std::cout << "load within limit="
              << (counts.load_factor() <= counts.max_load_factor()) << '\n';

    counts.clear();
    std::cout << "size after clear=" << counts.size() << '\n';
}

Result

apple=3
duplicate inserted=false
pear=1
size=2
buckets>=32=true
load within limit=true
size after clear=0

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources