std::unordered_map<Key,T,Hash,KeyEqual,Allocator>::insert

std::pair<iterator, bool> insert( const value_type& value );	(1)	(C++11以降)
std::pair<iterator, bool> insert( value_type&& value );	(2)	(C++17以降)
template< class P > std::pair<iterator, bool> insert( P&& value );	(3)	(C++11以降)
iterator insert( const_iterator hint, const value_type& value );	(4)	(C++11以降)
iterator insert( const_iterator hint, value_type&& value );	(5)	(C++17以降)
template< class P > iterator insert( const_iterator hint, P&& value );	(6)	(C++11以降)
template< class InputIt > void insert( InputIt first, InputIt last );	(7)	(C++11以降)
void insert( std::initializer_list<value_type> ilist );	(8)	(C++11以降)
insert_return_type insert( node_type&& nh );	(9)	(C++17以降)
iterator insert( const_iterator hint, node_type&& nh );	(10)	(C++17以降)

コンテナに要素を挿入します。コンテナが既に同等のキーを持つ要素を格納している場合は、挿入は行われません。

1-3) value を挿入します。

overload (3) は emplace(std::forward<P>(value)) と同等であり、std::is_constructible<value_type, P&&>::value == true の場合のみオーバーロード解決に参加します。

4-6) value を挿入します。検索を開始する場所として hint を非拘束のヒントとして使用します。

overload (6) は emplace_hint(hint, std::forward<P>(value)) と同等であり、std::is_constructible<value_type, P&&>::value == true の場合のみオーバーロード解決に参加します。

7) 範囲 [first, last) から要素を挿入します。範囲内の複数の要素のキーが等価である場合、どの要素が挿入されるかは未指定です（LWG2844 参照）。

[first, last) が有効な範囲でない場合、または first および/または last が *this へのイテレータである場合、動作は未定義です。

8) 初期化リスト ilist から要素を挿入します。範囲内の複数の要素のキーが等価である場合、どの要素が挿入されるかは未指定です（LWG2844 参照）。

9) nh が空のノードハンドルの場合、何もしません。それ以外の場合、コンテナに nh によって所有されている要素を挿入します。ただし、コンテナがすでに nh.key() と等価なキーを持つ要素をすでに含んでいる場合は挿入されません。nh が空でなく、get_allocator() != nh.get_allocator() の場合、動作は未定義です。

10) nh が空のノードハンドルの場合、何もしませんが、エンドイテレータを返します。それ以外の場合、コンテナに nh によって所有されている要素を挿入します。ただし、コンテナがすでに nh.key() と等価なキーを持つ要素をすでに含んでいる場合は挿入されません。挿入が成功したか失敗したかに関わらず、nh.key() と等価なキーを持つ要素を指すイテレータを返します。挿入が成功した場合、nh はムーブされ、そうでない場合は要素の所有権を保持します。hint は検索を開始する場所として非拘束のヒントとして使用されます。nh が空でなく、get_allocator() != nh.get_allocator() の場合、動作は未定義です。

操作後、要素の新しい数が古い max_load_factor() * bucket_count() より大きい場合、リハッシュが行われる。
挿入による再ハッシュが発生した場合、すべてのイテレータは無効になります。それ以外の場合（再ハッシュが発生しない場合）、イテレータは無効になりません。挿入が成功した場合、ノードハンドル内で保持されている間、その要素へのポインタと参照は無効になります。また、要素がノードハンドルから抽出される前に取得したその要素へのポインタと参照は有効になります。(C++17 以降)

hint	-	挿入するコンテンツのヒントとして使用されるイテレータ
value	-	挿入する要素の値
first, last	-	挿入する要素のソース範囲を定義するイテレータのペア
ilist	-	挿入する値の初期化子リスト
nh	-	互換性のある node handle
型要件
- `InputIt` は LegacyInputIterator の要件を満たす必要があります。

[編集] 戻り値

1-3) 挿入された要素（または挿入を妨げた要素）へのイテレータと、挿入が行われた場合にのみ true に設定される bool 値からなるペア。

4-6) 挿入された要素、または挿入を妨げた要素へのイテレータ。

7,8) (なし)

9) insert_return_type のオブジェクト。メンバは次のように初期化されます。

nh が空の場合、inserted は false、position は end()、node は空になります。
それ以外の場合で、挿入が行われた場合、inserted は true、position は挿入された要素を指し、node は空になります。
挿入が失敗した場合、inserted は false、node は nh の以前の値になり、position は nh.key() と同等のキーを持つ要素を指します。

10) nh が空だった場合はエンドイテレータ、挿入が行われた場合は挿入された要素を指すイテレータ、挿入が失敗した場合は nh.key() と等価なキーを持つ要素を指すイテレータ。

[編集] 例外

1-6) いかなる理由であっても例外がスローされた場合、これらの関数は影響を与えません（強力な例外安全性保証）。

7,8) 例外安全性保証はありません。

9,10) いかなる理由であっても例外がスローされた場合、これらの関数は影響を与えません（強力な例外安全性保証）。

[編集] 計算量

1-6) 平均ケース: O(1)、最悪ケース: O(size())。

7,8) 平均ケース: 挿入する要素数 N に対し O(N)。最悪ケース: O(N * size() + N)。

9,10) 平均ケース: O(1)、最悪ケース: O(size())。

[編集] 注記

ヒント付き挿入 (4-6) は、std::vector::insert のようなシーケンシャルコンテナの位置挿入とシグネチャ互換性を持たせるために、ブール値を返しません。これにより、std::inserter のようなジェネリックインサータを作成することが可能になります。ヒント付き挿入の成功を確認する一つの方法は、挿入前後の size() を比較することです。

[編集] 例

このコードを実行

#include <iostream>
#include <string>
#include <unordered_map>
 
int main ()
{
    std::unordered_map<int, std::string> dict = {{1, "one"}, {2, "two"}};
    dict.insert({3, "three"});
    dict.insert(std::make_pair(4, "four"));
    dict.insert({{4, "another four"}, {5, "five"}});
 
    const bool ok = dict.insert({1, "another one"}).second;
    std::cout << "inserting 1 => \"another one\" "
              << (ok ? "succeeded" : "failed") << '\n';
 
    std::cout << "contents:\n";
    for (auto& p : dict)
        std::cout << ' ' << p.first << " => " << p.second << '\n';
}

実行結果の例

inserting 1 => "another one" failed
contents:
 5 => five
 1 => one
 2 => two
 3 => three
 4 => four

[編集] 不具合報告

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

DR	適用対象	公開された動作	正しい動作
LWG 2005	C++11	overloads (3,6) は、オーバーロードにのみ参加する `P` が `value_type` に暗黙的に変換可能な場合	`value_type` が `P&&` から構築可能な場合のみ参加する

[編集] 関連項目

emplace	要素を直接構築する (公開メンバ関数) [編集]
emplace_hint	ヒントを使用して要素を直接構築する (公開メンバ関数) [編集]
insert_or_assign (C++17)	要素を挿入するか、キーが既に存在する場合は現在の要素に代入する (public member function) [編集]
inserter	引数から推論された型の std::insert_iterator を作成する (関数テンプレート) [編集]

コンパイラサポート
フリースタンディングとホスト
言語
標準ライブラリ
標準ライブラリヘッダー
名前付き要件
機能テストマクロ (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

名前空間

変種

表示

操作