Namespaces
Variants

std::map<Key,T,Compare,Allocator>:: at

From cppreference.net

C++
Containers library
std::map
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
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) (depuis C++26)
template < class K >
const T & at ( const K & x ) const ;
(4) (depuis C++26)

Retourne une référence à la valeur mappée de l'élément avec la clé spécifiée. Si aucun élément de ce type n'existe, une exception de type std::out_of_range est levée.

1,2) La clé est équivalente à key .
3,4) La clé est équivalente à la valeur x . La référence à la valeur mappée est obtenue comme par l'expression this - > find ( x ) - > second .
L'expression this - > find ( x ) doit être bien formée et avoir un comportement bien défini, sinon le comportement est indéfini.
Ces surcharges participent à la résolution de surcharge seulement si Compare est transparent . Cela permet d'appeler cette fonction sans construire une instance de Key .

Table des matières

Paramètres

key - la clé de l'élément à trouver
x - une valeur de type quelconque pouvant être comparée de manière transparente avec une clé

Valeur de retour

Une référence à la valeur mappée de l'élément demandé.

Exceptions

1,2) std::out_of_range si le conteneur ne possède pas d'élément avec la key spécifiée.
3,4) std::out_of_range si le conteneur ne possède pas l'élément spécifié, c'est-à-dire si find ( x ) == end ( ) est true .

Complexité

Logarithmique par rapport à la taille du conteneur.

Notes

Macro de test de fonctionnalité Valeur Std Fonctionnalité
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) Surcharges hétérogènes pour les fonctions membres restantes dans les conteneurs associatifs ordonnés et non ordonnés . ( 3,4 )

Exemple

Exécuter ce code 
#include <cassert>
#include <iostream>
#include <map>
struct LightKey { int o; };
struct HeavyKey { int o[1000]; };
// Le conteneur doit utiliser std::less<> (ou autre comparateur transparent) pour
// accéder aux surcharges (3,4). Cela inclut les surcharges standards, telles que
// la comparaison entre std::string et 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(const std::out_of_range& ex)
    {
        std::cout << "1) out_of_range::what(): " << ex.what() << '\n';
    }
#ifdef __cpp_lib_associative_heterogeneous_insertion
    // Démonstration de comparaison transparente.
    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(const std::out_of_range& ex)
    {
        std::cout << "2) out_of_range::what(): " << ex.what() << '\n';
    }
#endif
}

Sortie possible : 

1) out_of_range::what(): map::at:  key not found
2) out_of_range::what(): map::at:  key not found

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR Appliqué à Comportement publié Comportement corrigé
LWG 464 C++98 map ne possédait pas cette fonction membre ajoutée
LWG 703 C++98 l'exigence de complexité était manquante ajoutée
LWG 2007 C++98 la valeur de retour référait à l'élément demandé réfère à sa valeur mappée

Voir aussi

accéder ou insérer un élément spécifié
(fonction membre publique)
trouve un élément avec une clé spécifique
(fonction membre publique)