(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 |
std::map| Member functions | |||||||
| Non-member functions | |||||||
| |||||||
| Deduction guides(C++17) | |||||||
T& operator[](const Key& key); | (1) | |
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.
1) Insertsvalue_type(key, T()) if the key does not exist.
| (until C++11) | ||||||
1) Inserts a value_type object constructed in-place fromstd::piecewise_construct,std::forward_as_tuple(key),std::tuple<>() if the key does not exist.Equivalent toreturn 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 beingvalue-initialized.
2) Inserts a value_type object constructed in-place fromstd::piecewise_construct,std::forward_as_tuple(std::move(key)),std::tuple<>() if the key does not exist.Equivalent toreturn 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 beingvalue-initialized.
| (since C++11) | ||||||
value_type object constructed in-place if there is no key that transparently comparesequivalent to the valuex.Compare istransparent. It allows calling this function without constructing an instance ofKey.No iterators or references are 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.
Logarithmic in the size of the container.
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 <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::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::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";}
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'The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 334 | C++98 | the effect of overload(1) was simply returning (*((insert(std::make_pair(x, T()))).first)).second | provided its own description instead |
| 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] |
