名前空間
変種
操作

std::set<Key,Compare,Allocator>::insert

提供: cppreference.com
< cpp‎ | container‎ | set
 
C++
 
コンテナライブラリ
 
std::set
 
std::pair<iterator,bool> insert( const value_type& value );
 (1)
std::pair<iterator,bool> insert( value_type&& value );
 (2) (C++11以上)
(3)
iterator insert( iterator hint, const value_type& value );
 (C++11未満)
iterator insert( const_iterator hint, const value_type& value );
 (C++11以上)
iterator insert( const_iterator hint, value_type&& value );
 (4) (C++11以上)
template< class InputIt >
void insert( InputIt first, InputIt last );
 (5)
void insert( std::initializer_list<value_type> ilist );
 (6) (C++11以上)
insert_return_type insert(node_type&& nh);
 (7) (C++17以上)
iterator insert(const_iterator hint, node_type&& nh);
 (8) (C++17以上)

等しいキーを持つ要素がコンテナになければ、要素をコンテナに挿入します。

1-2) value を挿入します。
3-4) hint (の直前(C++11以上)) に可能な限り近い位置に value を挿入します。
5) 範囲 [first, last) から要素を挿入します。 指定範囲内の複数の要素が等しいキーを持っている場合、どの要素が挿入されるかは未規定です (未解決の LWG2844)。
6) 初期化子リスト ilist から要素を挿入します。 指定範囲内の複数の要素が等しいキーを持っている場合、どの要素が挿入されるかは未規定です (未解決の LWG2844)。
7) nh が空のノードハンドルの場合は、何もしません。 そうでなければ、nh.key() と等しいキーを持つ要素がコンテナ内にすでに格納されていない場合、nh によって所有されている要素がコンテナに挿入されます。 nh が空でなく、 get_allocator() != nh.get_allocator() の場合、動作は未定義です。
8) 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-2) 挿入された要素 (または挿入を妨げた要素) を指すイテレータと、挿入が行われた場合は true に設定される bool 値から構成される、ペアを返します。
3-4) 挿入された要素 (または挿入を妨げた要素) を指すイテレータを返します。
5-6) (なし)
7) 以下のように初期化されたメンバを持つ insert_return_type が返されます。 nh が空の場合、 inserted は false に、 position は end() に、 node は空に設定されます。 そうでなく、挿入が行われた場合、 inserted は true に、 position は挿入された要素を指すように、 node は空に設定されます。 挿入が失敗した場合、 inserted は false に、 node は nh の以前の値を持つように、 position は　nh.key() と等しいキーを持つ要素を指すように設定されます。
8) nh が空の場合は終端イテレータ、挿入が行われた場合は挿入された要素を指すイテレータ、失敗した場合は nh.key() と等しいキーを持つ要素を指すイテレータ。

[編集] 例外

1-4) 何らかの操作によって例外が投げられた場合、挿入は効果を持ちません。
This section is incomplete
Reason: cases 5-8

[編集] 計算量

1-2) コンテナのサイズの対数、 O(log(size()))。
3-4) 挿入が hint の直後の位置に行われた場合、償却定数時間。 そうでなければ、コンテナのサイズの対数。
(C++11未満)
3-4) 挿入が hint の直前の位置に行われた場合、償却定数時間。 そうでなければ、コンテナのサイズの対数。
(C++11以上)
5-6) O(N*log(size() + N))、ただし N は挿入する要素の数です。
7) コンテナのサイズの対数、 O(log(size()))。
8) 挿入が hint の直前の位置に行われた場合、償却定数時間。 そうでなければ、コンテナのサイズの対数。

[編集] ノート

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

オーバーロード (5,6) は、しばしば hint として end() を用いたオーバーロード (3) のループとして実装されます。 これは最も小さな要素が *this の最後の要素より大きいソート済みのシーケンス (別の set など) を追加することに対して最適化されています。

[編集] 例

Run this code
#include <set>
#include <cassert>
#include <iostream>
 
int main()
{
  std::set<int> set;
 
  auto result_1 = set.insert(3);
  assert(result_1.first != set.end()); // 有効なイテレータです。
  assert(*result_1.first == 3);
  if (result_1.second)
    std::cout << "insert done\n";
 
  auto result_2 = set.insert(3);
  assert(result_2.first == result_1.first); // 同じイテレータです。
  assert(*result_2.first == 3);
  if (!result_2.second)
    std::cout << "no insertion\n";
}

出力: 

insert done
no insertion

[編集] 関連項目

(C++11)
 要素をその場で構築します
(パブリックメンバ関数) [edit]
(C++11)
 ヒントを使用して要素をその場で構築します
(パブリックメンバ関数) [edit]
「https://ja.cppreference.com/mwiki/index.php?title=cpp/container/set/insert&oldid=44285」から取得