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

 

C++

言語

標準ライブラリヘッダ

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

名前付き要件

言語サポートライブラリ

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

診断ライブラリ

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

文字列ライブラリ

コンテナライブラリ

イテレータライブラリ

範囲ライブラリ(C++20)

アルゴリズムライブラリ

数値演算ライブラリ

ローカライゼーションライブラリ

入出力ライブラリ

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

正規表現ライブラリ(C++11)

アトミック操作ライブラリ(C++11)

スレッドサポートライブラリ(C++11)

技術仕様書

 

コンテナライブラリ

array (C++11)

vector

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

span (C++20)

 

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::empty

map::size

map::max_size

変更

map::clear

map::insert

map::insert_or_assign (C++17)

map::emplace (C++11)

map::emplace_hint (C++11)

map::try_emplace (C++17)

map::erase

map::swap

map::extract (C++17)

map::merge (C++17)

検索

map::count

map::find

map::contains (C++20)

map::equal_range

map::lower_bound

map::upper_bound

観察

map::key_comp

map::value_comp

推定ガイド(C++17)

 

std::pair<iterator,bool> insert(const value_type& value );	(1)
template<class P > std::pair<iterator,bool> insert( P&& value );	(2)	(C++11以上)
std::pair<iterator,bool> insert( value_type&& value );	(3)	(C++17以上)
	(4)
iterator insert( iterator hint, const value_type& value );			(C++11未満)
iterator insert( const_iterator hint, const value_type& value );			(C++11以上)
template<class P > iterator insert( const_iterator hint, P&& value );		(5)	(C++11以上)
iterator insert( const_iterator hint, value_type&& value );		(6)	(C++17以上)
template<class InputIt > void insert( InputIt first, InputIt last );		(7)
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 を挿入します。 オーバーロード (2) は emplace(std::forward<P>(value)) と同等であり、 std::is_constructible<value_type, P&&>::value==true の場合にのみ、オーバーロード解決に参加します。

4-6)hintの直前(C++11以上)に可能な限り近い位置に value を挿入します。 オーバーロード (5) は emplace_hint(hint, std::forward<P>(value)) と同等であり、 std::is_constructible<value_type, P&&>::value==true の場合にのみ、オーバーロード解決に参加します。

7) 範囲 [first, last) から要素を挿入します。 指定範囲内の複数の要素が等しいキーを持っている場合、どの要素が挿入されるかは未規定です (未解決の LWG2844)。

8) 初期化子リスト ilist から要素を挿入します。 指定範囲内の複数の要素が等しいキーを持っている場合、どの要素が挿入されるかは未規定です (未解決の LWG2844)。

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

10)nh が空のノードハンドルの場合は、何もせず、終端イテレータを返します。 そうでなければ、nh.key() と等しいキーを持つ要素がコンテナ内にすでに格納されていない場合、 nh によって所有されている要素をコンテナに挿入し、挿入が成功したか失敗したかに関わらず、 nh.key() と等しいキーを持つ要素を指すイテレータを返します。 挿入が成功すれば nh は移動され、そうでなければ要素の所有権は残ります。 要素は hint の直前の位置に可能な限り近い位置に挿入されます。 nh が空でなく、 get_allocator()!= nh.get_allocator() の場合、動作は未定義です。

どのイテレータも参照も無効化されません。 挿入が成功した場合、ノードハンドルに保持されている間に取得された要素へのポインタおよび参照は無効化され、抽出する前に取得された要素へのポインタおよび参照は有効なまま残されます。(C++17以上)

引数

hint	-	検索を開始する位置の提案として使用されるイテレータ (C++11未満) 前に新しい要素が挿入される位置を指すイテレータ (C++11以上)
value	-	挿入する要素の値
first, last	-	挿入する要素の範囲
ilist	-	挿入する値の初期化子リスト
nh	-	互換性のあるノードハンドル
型の要件
- InputIt は LegacyInputIterator の要件を満たさなければなりません。

戻り値

1-3) 挿入された要素 (または挿入を妨げた要素) を指すイテレータと、挿入が行われたかどうかを表す 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) 何らかの操作によって例外が投げられた場合、挿入は効果を持ちません。

計算量

1-3) コンテナのサイズの対数、O(log(size()))。

4-6) 挿入が hint の直後の位置に行われた場合、償却定数時間。 そうでなければ、コンテナのサイズの対数。	(C++11未満)
4-6) 挿入が hint の直前の位置に行われた場合、償却定数時間。 そうでなければ、コンテナのサイズの対数。	(C++11以上)

7-8)O(N*log(size() + N))、ただし N は挿入する要素の数です。

9) コンテナのサイズの対数、O(log(size()))。

10) 挿入が hint の直前の位置に行われた場合、償却定数時間。 そうでなければ、コンテナのサイズの対数。

ノート

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

例

Run this code

#include <iomanip>#include <iostream>#include <map>#include <string>   usingnamespace std::literals;   template<typename It>void printInsertionStatus(It it, bool success){std::cout<<"Insertion of "<< it->first <<(success ?" succeeded\n":" failed\n");}   int main(){std::map<std::string, float> karasunoPlayerHeights;   // オーバーロード3: 右辺値参照からの insertconstauto[it_hinata, success]= karasunoPlayerHeights.insert({"Hinata"s, 162.8}); printInsertionStatus(it_hinata, success);   {// オーバーロード1: 左辺値参照からの insertconstauto[it, success2]= karasunoPlayerHeights.insert(*it_hinata); printInsertionStatus(it, success2);}{// オーバーロード2: emplace への転送を介した insertconstauto[it, success]= karasunoPlayerHeights.insert({"Kageyama", 180.6}); printInsertionStatus(it, success);}   {// オーバーロード6: 位置ヒント付きの右辺値参照からの insertconststd::size_t n =std::size(karasunoPlayerHeights);constauto it = karasunoPlayerHeights.insert(it_hinata, {"Azumane"s, 184.7}); printInsertionStatus(it, std::size(karasunoPlayerHeights)!= n);}{// オーバーロード4: 位置ヒント付きの左辺値参照からの insertconststd::size_t n =std::size(karasunoPlayerHeights);constauto it = karasunoPlayerHeights.insert(it_hinata, *it_hinata); printInsertionStatus(it, std::size(karasunoPlayerHeights)!= n);}{// オーバーロード5: 位置ヒント付きの emplace への転送を介した insertconststd::size_t n =std::size(karasunoPlayerHeights);constauto it = karasunoPlayerHeights.insert(it_hinata, {"Tsukishima", 188.3}); printInsertionStatus(it, std::size(karasunoPlayerHeights)!= n);}   auto node_hinata = karasunoPlayerHeights.extract(it_hinata);std::map<std::string, float> playerHeights;   // オーバーロード7: イテレータ範囲からの insert playerHeights.insert(std::begin(karasunoPlayerHeights), std::end(karasunoPlayerHeights));   // オーバーロード8: initializer_list からの insert playerHeights.insert({{"Kozume"s, 169.2}, {"Kuroo", 187.7}});     // オーバーロード9: ノードの insertconstauto status = playerHeights.insert(std::move(node_hinata)); printInsertionStatus(status.position, status.inserted);   node_hinata = playerHeights.extract(status.position);{// オーバーロード10: 位置ヒント付きのノードの insertconststd::size_t n =std::size(playerHeights);constauto it = playerHeights.insert(std::begin(playerHeights), std::move(node_hinata)); printInsertionStatus(it, std::size(playerHeights)!= n);}     // 結果の map を表示します。std::cout<<std::left<<'\n';for(constauto&[name, height]: playerHeights)std::cout<<std::setw(10)<< name <<" | "<< height <<"cm\n";}

出力:

Insertion of Hinata succeeded Insertion of Hinata failed Insertion of Kageyama succeeded Insertion of Azumane succeeded Insertion of Hinata failed Insertion of Tsukishima succeeded Insertion of Hinata succeeded Insertion of Hinata succeeded   Azumane | 184.7cm Hinata | 162.8cm Kageyama | 180.6cm Kozume | 169.2cm Kuroo | 187.7cm Tsukishima | 188.3cm

関連項目

emplace (C++11)	要素をその場で構築します (パブリックメンバ関数)
emplace_hint (C++11)	ヒントを使用して要素をその場で構築します (パブリックメンバ関数)
insert_or_assign (C++17)	要素を挿入します。 キーがすでに存在している場合は現在の要素に代入します (パブリックメンバ関数)