(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& at(const Key& key); | (1) | |
const T& at(const Key& key)const; | (2) | |
template<class K> T& at(const K& x); | (3) | (since C++26) |
template<class K> const T& at(const K& x)const; | (4) | (since C++26) |
Returns a reference to the mapped value of the element with specified key. If no such element exists, an exception of typestd::out_of_range is thrown.
Compare
istransparent. It allows calling this function without constructing an instance ofKey
.Contents |
key | - | the key of the element to find |
x | - | a value of any type that can be transparently compared with a key |
A reference to the mapped value of the requested element.
Logarithmic in the size of the container.
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,4) |
#include <cassert>#include <iostream>#include <map> struct LightKey{int o;};struct HeavyKey{int o[1000];}; // The container must use std::less<> (or other transparent Comparator) to// access overloads (3,4). This includes standard overloads, such as// comparison between std::string and std::string_view.bool operator<(const HeavyKey& x,const LightKey& y){return x.o[0]< y.o;}bool operator<(const LightKey& x,const HeavyKey& y){return x.o< y.o[0];}bool operator<(const HeavyKey& x,const HeavyKey& y){return x.o[0]< y.o[0];} int main(){std::map<int,char> map{{1,'a'},{2,'b'}};assert(map.at(1)=='a');assert(map.at(2)=='b');try{ map.at(13);}catch(conststd::out_of_range& ex){std::cout<<"1) out_of_range::what(): "<< ex.what()<<'\n';} #ifdef __cpp_lib_associative_heterogeneous_insertion// Transparent comparison demo.std::map<HeavyKey,char,std::less<>> map2{{{1},'a'},{{2},'b'}};assert(map2.at(LightKey{1})=='a');assert(map2.at(LightKey{2})=='b');try{ map2.at(LightKey{13});}catch(conststd::out_of_range& ex){std::cout<<"2) out_of_range::what(): "<< ex.what()<<'\n';}#endif}
Possible output:
1) out_of_range::what(): map::at: key not found2) out_of_range::what(): map::at: key not found
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 464 | C++98 | map did not have this member function | added |
LWG 703 | C++98 | the complexity requirement was missing | added |
LWG 2007 | C++98 | the return value referred to the requested element | refers to its mapped value |
access or insert specified element (public member function)[edit] | |
finds element with specific key (public member function)[edit] |