T& at(const key_type& x);           // (1) C++11
constexpr T& at(const key_type& x); // (1) C++26

const T& at(const key_type& x) const;           // (2) C++11
constexpr const T& at(const key_type& x) const; // (2) C++26

template<class K>
constexpr T& at(const K& x); // (3) C++26

template<class K>
constexpr const T& at(const K& x) const; // (4) C++26

概要

参照のためのメソッドで、取り出す時にキーの存在チェックをする。

• (1), (2) : クラスのテンプレートパラメータkey_type型のキーに対応する要素を取得する
• (3), (4) : key_typeと比較可能なK型のキーに対応する要素を取得する

テンプレートパラメータ制約

• (3), (4) : Hash::is_transparentおよびPred::is_transparentが妥当な式であること

事前条件

• (3), (4) : find(x)が妥当な式であり、定義された動作をすること

戻り値

キーxに対応する値を返す。

例外

• 指定されたキーに対応する要素が存在しない場合、std::out_of_range例外を送出する

計算量

• 平均： 定数時間
• 最悪： size について線形時間

備考

• (3), (4) :
  • is_transparentは、HashとPredの両方がメンバ型として持つ必要がある。Predにはis_transparentを定義するstd::equal_to<>が使えるが、Hashには標準ライブラリに該当するものがないため、利用者が定義する必要がある。詳細はstd::hashクラスのページを参照。
  • これらのオーバーロードは、unordered_map<string, int>のようなコンテナに対し、検索操作で文字列リテラルを渡した際に、キー型の一時オブジェクトが生成されるコストを減らすためにある。

例

#include <iostream>
#include <unordered_map>

template<class Container, class T>
void at_wrap(Container &c, T v) {

  try{
    std::cout << c.at(v) << std::endl;
  }
  catch(std::out_of_range&) {
    std::cout << "exception std::out_of_range" << std::endl;
  }
}

int main()
{
  std::unordered_map<int, char> um;
  um.insert(std::make_pair(1,'a'));

  at_wrap(um, 1);
  at_wrap(um, 2);

  return 0;
}

出力

a
exception std::out_of_range

バージョン

言語

• C++11

処理系

• Clang: 9.0.1 ✅
• GCC: ??
• Visual C++: 2012 ✅

関連項目

参照

• LWG Issue 761. unordered_map needs an at() member function
• P2363R5 Extending associative containers with the remaining heterogeneous overloads
  • C++26でtemplate <class K>のバージョンが追加された
• P3372R3 constexpr containers and adaptors