(C++17) | ||||
| Sequence | ||||
(C++11) | ||||
(C++26) | ||||
(C++26) | ||||
(C++11) | ||||
| Associative | ||||
| Unordered associative | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
(C++11) | ||||
| Adaptors | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
| Views | ||||
(C++20) | ||||
(C++23) | ||||
| Tables | ||||
| Iterator invalidation | ||||
| Member function table | ||||
| Non-member function table |
| Member types | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Non-member functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Deduction guides(C++17) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 tokey orx respectively, performing an insertion if such key does not already exist.
value_type object constructed in-place fromstd::piecewise_construct,std::forward_as_tuple(key),std::tuple<>() if the key does not exist.key and the mapped value beingvalue-initialized. -value_type must beEmplaceConstructible fromstd::piecewise_construct,std::forward_as_tuple(key),std::tuple<>(). When the default allocator is used, this means thatkey_type must beCopyConstructible andmapped_type must beDefaultConstructible. |
value_type object constructed in-place fromstd::piecewise_construct,std::forward_as_tuple(std::move(key)),std::tuple<>() if the key does not exist.key and the mapped value beingvalue-initialized. -value_type must beEmplaceConstructible fromstd::piecewise_construct,std::forward_as_tuple(std::move(key)),std::tuple<>(). When the default allocator is used, this means thatkey_type must beMoveConstructible andmapped_type must beDefaultConstructible. |
value_type object constructed in-place if there is no key that transparently comparesequivalent to the valuex.Hash andKeyEqual are bothtransparent. This assumes that suchHash is callable with bothK andKey type, and that theKeyEqual is transparent, which, together, allows calling this function without constructing an instance ofKey.If after the operation the new number of elements is greater than oldmax_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.
Contents |
| key | - | the key of the element to find |
| x | - | a value of any type that can be transparently compared with a key |
If an exception is thrown by any operation, the insertion has no effect.
Average case: constant, worst case: linear in size.
In the published C++11 and C++14 standards, this function was specified to requiremapped_type to beDefaultInsertable andkey_type to beCopyInsertable orMoveInsertable into*this. This specification was defective and was fixed byLWG issue 2469, and the description above incorporates the resolution of that issue.
However, one implementation (libc++) is known to construct thekey_type andmapped_type objects via two separate allocatorconstruct() calls, as arguably required by the standards as published, rather than emplacing avalue_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 isconst,at may be used.
| (since C++17) |
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_associative_heterogeneous_insertion | 202311L | (C++26) | Heterogeneous overloads for the remaining member functions inordered andunordered associativecontainers.(3) |
#include <iostream>#include <string>#include <unordered_map> void println(autoconst comment,autoconst& map){std::cout<< comment<<'{';for(constauto& 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(constauto& 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(constauto&[word, count]: word_map)std::cout<< count<<" occurrence(s) of word '"<< word<<"'\n";}
Possible output:
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'| 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] |
