std::unordered_map::operator[] - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::unordered_map::operator[]

From cppreference.com
< cpp‎ | container‎ | unordered map

[edit template]

T& operator[]( const Key& key ); | (1) | (since C++11)
T& operator[]( Key&& key ); | (2) | (since C++11)

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.

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;. (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. This function is 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`.

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().

### [edit] Parameters

key | - | the key of the element to find

### [edit] 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`.

### [edit] Exceptions

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

### [edit] Complexity

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

### [edit] 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.

### [edit] Example

Run this code

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

    int main()
    {
        std::unordered_map<char, int> letter_counts {{'a', 27}, {'b', 3}, {'c', 1}};

        std::cout << "initially:\n";
        for (const auto &pair : letter_counts) {
            std::cout << pair.first << ": " << pair.second << '\n';
        }

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

        std::cout << "after modifications:\n";
        for (const auto &pair : letter_counts) {
            std::cout << pair.first << ": " << pair.second << '\n';
        }

        // count the number of occurrences of each word
        // (the first call to operator[] initialized the counter with zero)
        std::unordered_map<std::string, size_t>  word_map;
        for (const auto &w : { "this", "sentence", "is", "not", "a", "sentence",
                               "this", "sentence", "is", "a", "hoax"}) {
            ++word_map[w];
        }

        for (const auto &pair : word_map) {
            std::cout << pair.second << " occurrences of word '" << pair.first << "'\n";
        }
    }

Possible output:

    initially:
    a: 27
    b: 3
    c: 1
    after modifications:
    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'
    2 occurrences of word 'this'

### [edit] See also

at | access specified element with bounds checking (public member function) [edit]
insert_or_assign (C++17) | inserts an element or assigns to the current element if the key already exists (public member function) [edit]
try_emplace (C++17) | inserts in-place if the key does not exist, does nothing if the key exists (public member function) [edit]

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/container/unordered_map/operator_at&oldid=73772"