Namespaces
Variants
Views
Actions

std::unordered_map::operator[]

From cppreference.com

[edit template]
 
C++
 
Containers library
 
std::unordered_map
Member functions
Iterators
Capacity
Modifiers
(C++17)
(C++17)
(C++17)
(C++17)
Lookup
unordered_map::operator[]
(C++20)
Bucket interface
Hash policy
Observers
Deduction guides(C++17)
 
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().

Contents

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

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

(since C++17)

[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

 access specified element with bounds checking
(public member function) [edit]
(C++17)
 inserts an element or assigns to the current element if the key already exists
(public member function) [edit]
(C++17)
 inserts in-place if the key does not exist, does nothing if the key exists
(public member function) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/unordered_map/operator_at&oldid=73772"