std::unordered_map operator[] method

od C++11

// (1) Non const version only
T& operator[]( const Key& key );

// (2) Non const version only
T& operator[]( Key&& key );

Returns a reference to the value that is mapped to a key equivalent to key, performing an insertion if such key does not already exist.

od C++17

• (1) Inserts a value_type object constructed in-place from std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>() if the key does not exist. This function is equivalent to return this->try_emplace(key).first->second; When the default allocator is used, this results in the key being copy constructed from key and the mapped value being value-initialized.

  Type requirements

  • value_type must be EmplaceConstructible from std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>(). When the default allocator is used, this means that key_type must be CopyConstructible and mapped_type must be DefaultConstructible.

• (2) Inserts a value_type object constructed in-place from std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>() if the key does not exist. This function is equivalent to return this->try_emplace(std::move(key)).first->second; When the default allocator is used, this results in the key being move constructed from key and the mapped value being value-initialized.

  Type requirements

  • value_type must be EmplaceConstructible from std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>(). When the default allocator is used, this means that key_type must be MoveConstructible and mapped_type must be DefaultConstructible.

do C++17

• (1) Inserts a value_type object constructed in-place from std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>() if the key does not exist. When the default allocator is used, this results in the key being copy constructed from key and the mapped value being value-initialized.

  Type requirements

  • value_type must be EmplaceConstructible from std::piecewise_construct, std::forward_as_tuple(key), std::tuple<>(). When the default allocator is used, this means that key_type must be CopyConstructible and mapped_type must be DefaultConstructible.

• (2) Inserts a value_type object constructed in-place from std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>() if the key does not exist. When the default allocator is used, this results in the key being move constructed from key and the mapped value being value-initialized.

  Type requirements

  • value_type must be EmplaceConstructible from std::piecewise_construct, std::forward_as_tuple(std::move(key)), std::tuple<>(). When the default allocator is used, this means that key_type must be MoveConstructible and mapped_type must be DefaultConstructible.

Invalidation

If an insertion occurs and results in a rehashing of the container, all iterators are invalidated.

Otherwise iterators are not affected. References are not invalidated.

Rehashing occurs only if the new number of elements is greater than max_load_factor() * bucket_count().

Parameters

• key - the key of the element to find

Return value

Reference to the mapped value of the new element if no element with key key existed.

Otherwise a reference to the mapped value of the existing element whose key is equivalent to key.

Complexity

Average case, constant - O(1).
Worst case, linear in the size of the container - O(size()).

Exceptions

If an exception is thrown by any operation, the insertion has no effect

Notes

important

operator[] is non-const because it inserts the key if it doesn't exist.
If this behavior is undesirable or if the container is const, at() may be used.

In the published C++11 and C++14 standards, this function was specified to require mapped_type to be DefaultInsertable and key_type to be CopyInsertable or MoveInsertable into *this. This specification was defective and was fixed by LWG 2469, and the description above incorporates the resolution of that issue.

However, one implementation (libc++) is known to construct the key_type and mapped_type objects via two separate allocator construct() calls, as arguably required by the standards as published, rather than emplacing a value_type object.

od C++17

insert_or_assign() returns more information than operator[] and does not require default-constructibility of the mapped type.

Example

Main.cpp

#include <iostream>
#include <string>
#include <unordered_map>
 
auto print = [](auto const comment, auto const& map) {
    std::cout << comment << "{";
    for (const auto &pair : map) {
        std::cout << "{" << pair.first << ": " << pair.second << "}";
    }
    std::cout << "}\n";
};
 
int main()
{
    std::unordered_map<char, int> letter_counts {{'a', 27}, {'b', 3}, {'c', 1}};
    print("letter_counts initially contains: ", letter_counts);
 
    letter_counts['b'] = 42;  // updates an existing value
    letter_counts['x'] = 9;  // inserts a new value
 
    print("after modifications it contains: ", letter_counts);
 
    // count the number of occurrences of each word
    // (the first call to operator[] initialized the counter with zero)
    std::unordered_map<std::string, int>  word_map;
    for (const auto &w : { "this", "sentence", "is", "not", "a", "sentence",
                           "this", "sentence", "is", "a", "hoax"}) {
        ++word_map[w];
    }
    word_map["that"]; // just inserts the pair {"that", 0}
 
    for (const auto &[word, count] : word_map) {
        std::cout << count << " occurrences of word '" << word << "'\n";
    }
}

Output

letter_counts initially contains: {{a: 27}{b: 3}{c: 1}}
after modifications it contains: {{a: 27}{b: 42}{c: 1}{x: 9}}
2 occurrences of word 'a'
1 occurrences of word 'hoax'
2 occurrences of word 'is'
1 occurrences of word 'not'
3 occurrences of word 'sentence'
0 occurrences of word 'that'
2 occurrences of word 'this'