From cppreference.com
T&at(constKey&key); (1) constT&at(constKey&key)const; (2) template<classK>T&at(constK&x); (3)(since C++26)template<classK>constT&at(constK&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 type
is thrown.
1,2) The key is equivalent to key.
3,4) The key compares equivalent to the value x. The reference to the mapped value is obtained as if by expression this->find(x)->second.
The expression this->find(x) must be well-formed and have well-defined behavior, otherwise the behavior is undefined.
These overloads participate in overload resolution only if the qualified-id Compare::is_transparent is valid and denotes a type. It allows calling this function without constructing an instance of Key.
Parameters
key - the key of the element to find x - a value of any type that can be transparently compared with a key Return value
A reference to the mapped value of the requested element.
Exceptions
1,2)
if the container does not have an element with the specified key.
3,4)
if the container does not have the specified element, that is, if find(x)==end() is true.
Complexity
Logarithmic in the size of the container.
Notes
macro ValueStdFeature
__cpp_lib_associative_heterogeneous_insertion
(C++26)Heterogeneous overloads for the remaining member functions in
and
associative
. (
)Example
Run this code
#include<cassert>#include<iostream>#include<map>structLightKey{into;};structHeavyKey{into[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.booloperator<(constHeavyKey&x,constLightKey&y){returnx.o[0]<y.o;}booloperator<(constLightKey&x,constHeavyKey&y){returnx.o<y.o[0];}booloperator<(constHeavyKey&x,constHeavyKey&y){returnx.o[0]<y.o[0];}intmain(){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 found 2) out_of_range::what(): map::at: key not found Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 map did not have this member function added
C++98 the complexity requirement was missing added
C++98 the return value referred to the requested element refers to its mapped value See also
access or insert specified element
(public member function)
finds element with specific key
(public member function)