std::unordered_map

ヘッダ `<unordered_map>` で定義
template< class Key, class T, class Hash = std::hash<Key>, class KeyEqual = std::equal_to<Key>, class Allocator = std::allocator<std::pair<const Key, T>> > class unordered_map;	(1)	(C++11以降)
namespace pmr { template< class Key, class T, class Hash = std::hash<Key>, class KeyEqual = std::equal_to<Key> > using unordered_map = std::unordered_map<Key, T, Hash, KeyEqual, std::pmr::polymorphic_allocator<std::pair<const Key, T>>>; }	(2)	(C++17以降)

std::unordered_map は、一意なキーを持つキーと値のペアを格納する連想コンテナです。要素の検索、挿入、削除の平均計算量は定数時間です。

内部的には、要素は特定の順序でソートされず、バケットに編成されます。要素がどのバケットに配置されるかは、そのキーのハッシュ値に完全に依存します。同じハッシュコードを持つキーは同じバケットに現れます。これにより、ハッシュが計算されると、要素が配置されている正確なバケットを参照するため、個々の要素への高速なアクセスが可能になります。

2つのキーは、マップのキー等価性判定述語がそれらのキーを渡されたときに true を返す場合、等価であると見なされます。2つのキーが等価である場合、ハッシュ関数は両方のキーに対して同じ値を返さなければなりません。

std::unordered_map はコンテナ (Container)、アロケータ認識コンテナ (AllocatorAwareContainer)、非順序連想コンテナ (UnorderedAssociativeContainer) の要件を満たします。

std::unordered_map の全てのメンバ関数は constexpr です。定数式の評価中に std::unordered_map オブジェクトを作成して使用することが可能です。

しかし、動的に割り当てられたストレージは同じ定数式の評価中に解放されなければならないため、std::unordered_map オブジェクトは一般的に constexpr にはなれません。

(C++26以降)

操作	無効になる条件
全ての読み取り専用操作、swap、std::swap	決して無効化されない
clear、rehash、reserve、operator=	常に無効化される
insert、emplace、emplace_hint、operator[]	リハッシュを引き起こした場合のみ
erase	削除された要素へのもののみ

[編集] 備考

swap 関数はコンテナ内のどのイテレータも無効化しませんが、swap 領域の終わりを示すイテレータは無効化します。

コンテナに格納されているキーまたはデータのいずれかへの参照およびポインタは、対応するイテレータが無効化された場合でも、その要素が削除されることによってのみ無効化されます。

[編集] テンプレートパラメータ

[編集] メンバ型

型	定義
`key_type`	`Key`[編集]
`mapped_type`	`T`[編集]
`value_type`	std::pair<const Key, T>[編集]
`size_type`	符号なし整数型 (通常は std::size_t)[編集]
`difference_type`	符号付き整数型 (通常は std::ptrdiff_t)[編集]
`hasher`	`Hash`[編集]
`key_equal`	`KeyEqual`[編集]
`allocator_type`	`Allocator`[編集]
`reference`	value_type&[編集]
`const_reference`	const value_type&[編集]
`pointer`	std::allocator_traits<Allocator>::pointer[編集]
`const_pointer`	std::allocator_traits<Allocator>::const_pointer[編集]
`iterator`	`value_type` への旧前方イテレータ (LegacyForwardIterator) および定数式イテレータ (ConstexprIterator)(C++26から)[編集]
`const_iterator`	const value_type への LegacyForwardIteratorおよび ConstexprIterator(C++26 以降)[編集]
`local_iterator`	カテゴリ、値、差分、ポインタ、および参照型が `iterator` と同じイテレータ型。このイテレータは、単一のバケットを走査するために使用できるが、バケットをまたいで使用することはできない[編集]
`const_local_iterator`	カテゴリ、値、差分、ポインタ、および参照型が `const_iterator` と同じ。このイテレータは、単一のバケットを走査するために使用できるが、バケットをまたいで使用することはできない[編集]
`node_type` (C++17以降)	コンテナのノードを表すノードハンドルの特殊化[編集]
`insert_return_type` (C++17 以降)	`node_type` の挿入結果を記述する型。以下の特殊化である template<class Iter, class NodeType> struct /未規定/ { Iter position; bool inserted; NodeType node; }; テンプレート引数 `iterator` と `node_type` でインスタンス化される。[編集]

[編集] メンバ関数

(コンストラクタ)	`unordered_map` を構築する (公開メンバ関数) [編集]
(デストラクタ)	`unordered_map` を破棄する (公開メンバ関数) [編集]
operator=	コンテナに値を代入する (公開メンバ関数) [編集]
get_allocator	関連付けられたアロケータを返す (公開メンバ関数) [編集]
イテレータ
begincbegin	先頭へのイテレータを返す (public メンバ関数) [編集]
endcend	末尾へのイテレータを返す (public メンバ関数) [編集]
容量
empty	コンテナが空かどうかをチェックする (public メンバ関数) [編集]
size	要素数を返す (public メンバ関数) [編集]
max_size	可能な最大要素数を返す (public メンバ関数) [編集]
変更
clear	内容をクリアする (公開メンバ関数) [編集]
insert	要素またはノード(C++17以降)を挿入する (公開メンバ関数) [編集]
insert_range (C++23)	要素の範囲を挿入する (公開メンバ関数) [編集]
insert_or_assign (C++17)	要素を挿入するか、キーが既に存在する場合は現在の要素に代入する (public member function) [編集]
emplace	要素を直接構築する (公開メンバ関数) [編集]
emplace_hint	ヒントを使用して要素を直接構築する (公開メンバ関数) [編集]
try_emplace (C++17)	キーが存在しない場合はインプレースで挿入し、キーが存在する場合は何もしない (public member function) [編集]
erase	要素を削除する (公開メンバ関数) [編集]
swap	内容を交換する (public メンバ関数) [編集]
extract (C++17)	コンテナからノードを抽出する (公開メンバ関数) [編集]
merge (C++17)	他のコンテナからノードを連結する (公開メンバ関数) [編集]
検索
at	境界チェック付きで指定された要素にアクセスする (public メンバ関数) [編集]
operator[]	指定された要素にアクセスまたは挿入する (public メンバ関数) [編集]
count	特定のキーに一致する要素の数を返す (公開メンバ関数) [編集]
find	特定のキーを持つ要素を検索する (公開メンバ関数) [編集]
contains (C++20)	コンテナが特定のキーを持つ要素を含むか確認する (公開メンバ関数) [編集]
equal_range	特定のキーに一致する要素の範囲を返す (公開メンバ関数) [編集]
バケットインターフェース
begin(size_type)cbegin(size_type)	指定されたバケットの先頭を指すイテレータを返す (public member function) [編集]
end(size_type)cend(size_type)	指定されたバケットの末尾を指すイテレータを返す (public member function) [編集]
bucket_count	バケット数を返す (public member function) [編集]
max_bucket_count	バケットの最大数を返す (public member function) [編集]
bucket_size	特定のバケット内の要素数を返す (public member function) [編集]
bucket	特定のキーに対するバケットを返す (public member function) [編集]
ハッシュポリシー
load_factor	バケットあたりの平均要素数を返す (public member function) [編集]
max_load_factor	バケットあたりの最大平均要素数を管理する (public member function) [編集]
rehash	少なくとも指定された数のバケットを確保し、ハッシュテーブルを再生成する (public member function) [編集]
reserve	少なくとも指定された数の要素のためのスペースを確保し、ハッシュテーブルを再生成する (public member function) [編集]
監視
hash_function	キーのハッシュに使用される関数を返す (public member function) [編集]
key_eq	キーの等価性比較に使用される関数を返す (public member function) [編集]

[編集] 非メンバ関数

operator==operator!= (C++11)(C++11)(C++20で削除)	unordered_map 内の値を比較する (function template) [編集]
std::swap(std::unordered_map) (C++11)	std::swap アルゴリズムを特殊化する (関数テンプレート) [編集]
erase_if(std::unordered_map) (C++20)	特定の基準を満たすすべての要素を削除する (関数テンプレート) [編集]

推論補助

(C++17以降)

[編集] 備考

機能テストマクロ	値	規格	機能
`__cpp_lib_containers_ranges`	`202202L`	(C++23)	コンテナのRangeコンストラクタとRange挿入
`__cpp_lib_constexpr_containers`	`202502L`	(C++26)	constexpr `std::unordered_map`

[編集] 例

このコードを実行

#include <iostream>
#include <string>
#include <unordered_map>
 
int main()
{
    // Create an unordered_map of three strings (that map to strings)
    std::unordered_map<std::string, std::string> u =
    {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    };
 
    // Helper lambda function to print key-value pairs
    auto print_key_value = [](const auto& key, const auto& value)
    {
        std::cout << "Key:[" << key << "] Value:[" << value << "]\n";
    };
 
    std::cout << "Iterate and print key-value pairs of unordered_map, being\n"
                 "explicit with their types:\n";
    for (const std::pair<const std::string, std::string>& n : u)
        print_key_value(n.first, n.second);
 
    std::cout << "\nIterate and print key-value pairs using C++17 structured binding:\n";
    for (const auto& [key, value] : u)
        print_key_value(key, value);
 
    // Add two new entries to the unordered_map
    u["BLACK"] = "#000000";
    u["WHITE"] = "#FFFFFF";
 
    std::cout << "\nOutput values by key:\n"
                 "The HEX of color RED is:[" << u["RED"] << "]\n"
                 "The HEX of color BLACK is:[" << u["BLACK"] << "]\n\n";
 
    std::cout << "Use operator[] with non-existent key to insert a new key-value pair:\n";
    print_key_value("new_key", u["new_key"]);
 
    std::cout << "\nIterate and print key-value pairs, using `auto`;\n"
                 "new_key is now one of the keys in the map:\n";
    for (const auto& n : u)
        print_key_value(n.first, n.second);
}

実行結果の例

Iterate and print key-value pairs of unordered_map, being
explicit with their types:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
 
Iterate and print key-value pairs using C++17 structured binding:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
 
Output values by key:
The HEX of color RED is:[#FF0000]
The HEX of color BLACK is:[#000000]
 
Use operator[] with non-existent key to insert a new key-value pair:
Key:[new_key] Value:[]
 
Iterate and print key-value pairs, using `auto`;
new_key is now one of the keys in the map:
Key:[new_key] Value:[]
Key:[WHITE] Value:[#FFFFFF]
Key:[BLACK] Value:[#000000]
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]

[編集] 欠陥報告

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

DR	適用対象	公開された動作	正しい動作
LWG 2050	C++11	`reference`、`const_reference`、`pointer`、および `const_pointer` の定義が `allocator_type` に基づいていた	`value_type` および std::allocator_traits に基づくように変更

[編集] 関連項目

unordered_multimap (C++11)	キーでハッシュ化されたキーと値のペアのコレクション (クラステンプレート) [編集]
map	キーでソートされたキーと値のペアのコレクション、キーは一意 (クラステンプレート) [編集]
flat_map (C++23)	ユニークなキーによってソートされたキーと値のペアのコレクションを提供するために2つのコンテナを適合させる (クラステンプレート) [編集]

コンパイラサポート
フリースタンディングとホスト
言語
標準ライブラリ
標準ライブラリヘッダー
名前付き要件
機能テストマクロ (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)
表
イテレータの無効化
メンバ関数テーブル
非メンバ関数テーブル

cppreference.com

名前空間

変種

表示

操作

std::unordered_map

目次

[編集] イテレータの無効化

[編集] 備考

[編集] テンプレートパラメータ

[編集] メンバ型

[編集] メンバ関数

イテレータ

容量

変更

検索

バケットインターフェース

ハッシュポリシー

監視

[編集] 非メンバ関数

推論補助

[編集] 備考

[編集] 例

[編集] 欠陥報告

[編集] 関連項目

ナビゲーション

ツールボックス