# std::unordered_map<Key,T,Hash,KeyEqual,Allocator>::operator[]

> C++ Atlas: `cppatlas.com/w/cpp/container/unordered_map/operator_at` | Source: https://en.cppreference.com/w/cpp/container/unordered_map/operator_at | Domain: Containers | Standards: C++11, C++17, C++26

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

## Official Specification Summary (cppreference)

```cpp
T& operator[]( const Key& key ); // (1) (since C++11)

T& operator[]( Key&& key ); // (2) (since C++11)

template< class K >
T& operator[]( K&& x ); // (3) (since C++26)
```

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

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.

Equivalent to `return this->try_emplace(key).first->second;`. (since C++17) When the default allocator is used, this results in the key being copy constructed from `key` and the mapped value being value-initialized.

   - `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.

Equivalent to `return this->try_emplace(std::move(key)).first->second;`. (since C++17)
When the default allocator is used, this results in the key being move constructed from `key` and the mapped value being value-initialized.

   - `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*.

3) Inserts a `value_type` object constructed in-place if there is no key that transparently compares *equivalent* to the value `x`.

Equivalent to `return this->try_emplace(std::forward<K>(x)).first->second;`. This overload participates in overload resolution only if `Hash::is_transparent` and `KeyEqual::is_transparent` are valid and each denotes a type. This assumes that such `Hash` is callable with both `K` and `Key` type, and that the `KeyEqual` is transparent, which, together, allows calling this function without constructing an instance of `Key`.

If after the operation the new number of elements is greater than old `max_load_factor() * bucket_count()` a rehashing takes place.
If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise (no rehashing), iterators are not invalidated.

### Parameters

- `key` - the key of the element to find
- `x` - a value of any type that can be transparently compared with a key

### Return value

1,2) A 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`.

3) A reference to the mapped value of the new element if no element with key that compares equivalent to the value `x` existed. Otherwise, a reference to the mapped value of the existing element whose key compares equivalent to `x`.

### Exceptions

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

### Complexity

Average case: constant, worst case: linear in size.

### Notes

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 issue 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.

`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.

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

| Feature-test macro | Value | Std | Feature |
| --- | --- | --- | --- |
| `__cpp_lib_associative_heterogeneous_insertion` | `202311L` | (C++26) | Heterogeneous overloads for the remaining member functions in ordered and unordered associative containers. (3) |

### Example

```cpp
#include <iostream>
#include <string>
#include <unordered_map>

void println(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}};

    println("letter_counts initially contains: ", letter_counts);

    letter_counts['b'] = 42; // updates an existing value
    letter_counts['x'] = 9;  // inserts a new value

    println("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 << " occurrence(s) of word '" << word << "'\n";
}
```

Possible output:

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

### See also

- [`at`](https://en.cppreference.com/w/cpp/container/unordered_map/at): access specified element with bounds checking (public member function)
- [`insert_or_assign`](https://en.cppreference.com/w/cpp/container/unordered_map/insert_or_assign) (C++17): inserts an element or assigns to the current element if the key already exists (public member function)
- [`try_emplace`](https://en.cppreference.com/w/cpp/container/unordered_map/try_emplace) (C++17): inserts in-place if the key does not exist, does nothing if the key exists (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/container/unordered_map/operator_at (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.