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

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

コンテナライブラリ

シーケンス

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

hive (C++26)

deque

forward_list (C++11)

list

連想

set

multiset

map

multimap

非順序連想

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

アダプタ

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

表示

span (C++20)

mdspan (C++23)

表

イテレータの無効化

メンバ関数テーブル

非メンバ関数テーブル

 

std::map

メンバ関数

map::map map::~map               map::operator= map::get_allocator

要素アクセス map::at map::operator[] イテレータ map::beginmap::cbegin (C++11) map::endmap::cend (C++11) map::rbeginmap::crbegin (C++11)      map::rendmap::crend (C++11) 容量 map::size map::max_size map::empty 監視 map::key_comp map::value_comp 変更 map::clear map::insert map::erase map::swap map::extract (C++17) map::merge (C++17) map::insert_range (C++23) map::insert_or_assign (C++17) map::emplace (C++11) map::emplace_hint (C++11) map::try_emplace (C++17) 検索 map::count map::find map::contains (C++20) map::equal_range map::lower_bound map::upper_bound

非メンバ関数

operator==operator<=> (C++20) std::swap(std::map) erase_if(std::map) (C++20)   operator!=operator<operator>operator<=operator>= (C++20まで)(C++20まで)(C++20まで)(C++20まで)(C++20まで)

推論補助 (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)	(C++26以降)
template< class K > const T& at( const K& x ) const;	(4)	(C++26以降)

指定されたキーを持つ要素のマップ値への参照を返します。そのような要素が存在しない場合は、std::out_of_range 型の例外がスローされます。

1,2) キーは key と同値です。

3,4) キーは値 x と同値です。マップ値への参照は、式 this->find(x)->second を使って取得されます。

式 this->find(x) は、well-formed であり、well-defined な動作を持つ必要があります。そうでない場合、動作は未定義です。

これらのオーバーロードは、修飾ID Compare::is_transparent が有効で、型を指している場合にのみオーバーロード解決に参加します。これにより、Key のインスタンスを構築せずにこの関数を呼び出すことができます。

パラメータ

key	-	検索する要素のキー
x	-	キーと透過的に比較できる任意の型の値

戻り値

要求された要素のマップ値への参照。

例外

1,2) コンテナに指定された key を持つ要素が存在しない場合は、std::out_of_range。

3,4) コンテナに指定された要素が存在しない場合、つまり find(x) == end() が true の場合は、std::out_of_range。

計算量

コンテナのサイズに対して対数時間。

注釈

機能テストマクロ	値	規格	機能
__cpp_lib_associative_heterogeneous_insertion	202311L	(C++26)	順序付けられたおよび順序付けられていない連想コンテナの残りのメンバ関数に対する異種オーバーロード。(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(const std::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(const std::out_of_range& ex)
    {
        std::cout << "2) out_of_range::what(): " << ex.what() << '\n';
    }
#endif
}

実行結果の例

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

欠陥レポート

以下の動作変更を伴う欠陥報告が、以前に公開されたC++標準に遡って適用されました。

DR	適用対象	公開された動作	正しい動作
LWG 464	C++98	map にはこのメンバ関数がありませんでした。	追加された
LWG 703	C++98	複雑性要件が欠落していました。	追加された
LWG 2007	C++98	戻り値は要求された要素を参照していました。	対応する値を参照します。

関連項目

operator[]	指定された要素にアクセスまたは挿入する (public メンバ関数)
find	特定のキーを持つ要素を検索する (公開メンバ関数)