std:: unordered_map

From ja.cppreference.net

ヘッダーで定義 `<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以降)

型	定義
`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`	LegacyForwardIterator および ConstexprIterator（C++26以降）へ `value_type`
`const_iterator`	LegacyForwardIterator および ConstexprIterator（C++26以降）へ `const value_type`
`local_iterator`	そのカテゴリ、値、差、ポインタおよび参照型が`iterator`と同じであるイテレータ型。このイテレータは単一のバケット内を反復できるが、バケット間を反復することはできない
`const_local_iterator`	そのカテゴリ、値、差、ポインタおよび参照型が`const_iterator`と同じであるイテレータ型。このイテレータは単一のバケット内を反復できるが、バケット間を反復することはできない
`node_type` （C++17以降）	node handleの特殊化で、コンテナノードを表す
`insert_return_type` （C++17以降）	`node_type`を挿入した結果を記述する型。 template< class Iter, class NodeType > struct /* unspecified */ { Iter position; bool inserted; NodeType node; }; の特殊化で、テンプレート引数`iterator`と`node_type`でインスタンス化される。

メンバー関数

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

非メンバー関数

operator== operator!= (C++11) (C++11) (removed in C++20)	unordered_map内の値を比較する (関数テンプレート)
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)	コンテナのためのレンジ構築と挿入
`__cpp_lib_constexpr_unordered_map`	`202502L`	(C++26)	constexpr `std::unordered_map`

例

このコードを実行

#include <iostream>
#include <string>
#include <unordered_map>
int main()
{
    // 文字列から文字列へのunordered_mapを3要素で作成
    std::unordered_map<std::string, std::string> u =
    {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    };
    // キーと値のペアを出力するヘルパーラムダ関数
    auto print_key_value = [](const auto& key, const auto& value)
    {
        std::cout << "Key:[" << key << "] Value:[" << value << "]\n";
    };
    std::cout << "unordered_mapのキーと値のペアを反復処理して出力（型を明示的に指定）:\n"
                 "\n";
    for (const std::pair<const std::string, std::string>& n : u)
        print_key_value(n.first, n.second);
    std::cout << "\nC++17の構造化バインディングを使用してキーと値のペアを反復処理して出力:\n";
    for (const auto& [key, value] : u)
        print_key_value(key, value);
    // unordered_mapに2つの新しいエントリを追加
    u["BLACK"] = "#000000";
    u["WHITE"] = "#FFFFFF";
    std::cout << "\nキーによる値の出力:\n"
                 "色REDのHEX値は:[" << u["RED"] << "]\n"
                 "色BLACKのHEX値は:[" << u["BLACK"] << "]\n\n";
    std::cout << "存在しないキーでoperator[]を使用して新しいキーと値のペアを挿入:\n";
    print_key_value("new_key", u["new_key"]);
    std::cout << "\n`auto`を使用してキーと値のペアを反復処理して出力:\n"
                 "new_keyがマップ内のキーの1つになりました:\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 に基づく

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
Memory management library
Metaprogramming library (C++11)
General utilities library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Technical specifications
Symbols index
External libraries

node-handle (C++17)
Sequence
array (C++11)
vector
vector <bool>
inplace_vector (C++26)
hive (C++26)
deque
forward_list (C++11)
list
Associative
set
multiset
map
multimap
Unordered associative
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
Adaptors
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
Views
span (C++20)
mdspan (C++23)
Tables
Iterator invalidation
Member function table
Non-member function table

ja.cppreference.net

Namespaces

Variants

std:: unordered_map

目次

イテレータの無効化

注記

テンプレートパラメータ

メンバ型

メンバー関数

イテレータ

容量

修飾子

ルックアップ

Bucket インターフェース

ハッシュポリシー

オブザーバー

非メンバー関数

推論ガイド

注記

例

不具合報告

関連項目