Namespaces
Variants

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

From cppreference.net

T & at ( const Key & key ) ;
(1)
const T & at ( const Key & key ) const ;
(2)
template < class K >
T & at ( const K & x ) ;
(3) (seit C++26)
template < class K >
const T & at ( const K & x ) const ;
(4) (seit C++26)

Gibt eine Referenz auf den abgebildeten Wert des Elements mit dem angegebenen Schlüssel zurück. Wenn kein solches Element existiert, wird eine Ausnahme vom Typ std::out_of_range ausgelöst.

1,2) Der Schlüssel entspricht key .
3,4) Der Schlüssel vergleicht sich äquivalent zum Wert x . Der Verweis auf den zugeordneten Wert wird erhalten wie durch den Ausdruck this - > find ( x ) - > second .
Der Ausdruck this - > find ( x ) muss wohlgeformt sein und ein wohldefiniertes Verhalten aufweisen, andernfalls ist das Verhalten undefiniert.
Diese Überladungen nehmen nur dann an der Überladungsauflösung teil, wenn Compare transparent ist. Dies erlaubt den Aufruf dieser Funktion ohne Konstruktion einer Instanz von Key .

Inhaltsverzeichnis

Parameter

key - der Schlüssel des zu findenden Elements
x - ein Wert beliebigen Typs, der transparent mit einem Schlüssel verglichen werden kann

Rückgabewert

Eine Referenz auf den abgebildeten Wert des angeforderten Elements.

Ausnahmen

1,2) std::out_of_range wenn der Container kein Element mit dem angegebenen key besitzt.
3,4) std::out_of_range falls der Container das angegebene Element nicht enthält, d.h. wenn find ( x ) == end ( ) gleich true ist.

Komplexität

Logarithmisch in der Größe des Containers.

Hinweise

Feature-Test Makro Wert Standard Funktion
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) Heterogene Überladungen für die verbleibenden Memberfunktionen in geordneten und ungeordneten assoziativen Containern . ( 3,4 )

Beispiel

#include <cassert>
#include <iostream>
#include <map>
struct LightKey { int o; };
struct HeavyKey { int o[1000]; };
// Der Container muss std::less<> (oder einen anderen transparenten Comparator) verwenden,
// um die Überladungen (3,4) zu nutzen. Dies beinhaltet Standardüberladungen, wie
// den Vergleich zwischen std::string und 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
    // Demonstration transparenter Vergleiche.
    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
}

Mögliche Ausgabe:

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

Fehlerberichte

Die folgenden verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR Angewendet auf Verhalten wie veröffentlicht Korrektes Verhalten
LWG 464 C++98 map hatte diese Memberfunktion nicht hinzugefügt
LWG 703 C++98 die Komplexitätsanforderung fehlte hinzugefügt
LWG 2007 C++98 der Rückgabewert bezog sich auf das angeforderte Element bezieht sich auf seinen zugeordneten Wert

Siehe auch

greift auf bestimmtes Element zu oder fügt es ein
(öffentliche Elementfunktion)
findet Element mit spezifischem Schlüssel
(öffentliche Elementfunktion)