map::insert

[アーティクル]
06/09/2015

map に要素または要素範囲を挿入します。

// (1) single element pair<iterator, bool> insert(     const value_type& Val );   // (2) single element, perfect forwarded template<class ValTy> pair<iterator, bool> insert(     ValTy&& Val );  // (3) single element with hint iterator insert(     const_iterator Where,     const value_type& Val );   // (4) single element, perfect forwarded, with hint template<class ValTy> iterator insert(     const_iterator Where,     ValTy&& Val );  // (5) range  template<class InputIterator>  void insert(     InputIterator First,     InputIterator Last );   // (6) initializer list void insert(     initializer_list<value_type> IList );

パラメーター

パラメーター	説明
Val	キーが同じ順序付けになる要素が map にまだ含まれていない場合に、map に挿入される要素の値。
Where	正しい挿入ポイントの検索を開始する場所 (その位置が Where の直前にある場合、挿入処理は対数時間ではなく償却定数時間で実行できます)。
ValTy	map が value_type の要素を構築するために使用できる引数の型を指定し、Val を引数として完全転送するテンプレートパラメーター。
First	コピーされる最初の要素の位置。
Last	コピーされる最後の要素の次の位置。
InputIterator	入力反復子の要件を満たすテンプレート関数の引数。この反復子は、value_type オブジェクトの作成に使用できる型の要素を指し示します。
IList	要素のコピー元の initializer_list。

戻り値

単一要素のメンバー関数 (1) と (2) は、ペアを返します。このペアの bool コンポーネントは、挿入が行われた場合は true になり、順序の値が同じキーを持つ要素が map に既に含まれている場合は false になります。戻り値であるペアの反復子コンポーネントは、bool コンポーネントが true の場合は新しく挿入される要素を指し、bool コンポーネントが false の場合は既存の要素を指します。

単一要素とヒントのメンバー関数 (3) と (4) は、map に挿入された新しい要素の位置を指す反復子を返します。ただし、同じキーを持つ要素が既に存在する場合、この反復子は既存の要素を指します。

解説

この関数では、反復子、ポインター、参照は無効になりません。

要素を 1 つだけ挿入するとき、例外がスローされるとコンテナーの状態は変更されません。複数の要素を挿入するときに例外がスローされた場合、コンテナーの状態は未指定ですが、有効な状態になっています。

単一要素のメンバー関数によって返される pair pr の反復子コンポーネントにアクセスするには、pr.first を使用します。返されるペアに含まれる反復子を逆参照するには、要素を指定して、*pr.first を使用します。 bool コンポーネントにアクセスするには、pr.second を使用します。例については、この記事で後ほど説明するサンプルコードを参照してください。

コンテナーの value_type は、コンテナーに属する typedef であり、map の場合、map<K, V>::value_type は pair<const K, V> になります。要素の値は順序付けされたペアになり、このペアの最初のコンポーネントはキー値と同じで、2 番目のコンポーネントは要素のデータ値と同じになります。

範囲のメンバー関数 (5) は、map に要素値のシーケンスを挿入します。このシーケンスは、範囲 [First, Last) の反復子によってアドレス指定された各要素に対応します。したがって、Last は挿入されません。コンテナーのメンバー関数 end() は、コンテナー内にある最後の要素の直後の位置を参照します。たとえば、ステートメント m.insert(v.begin(), v.end()); は、v のすべての要素を m に挿入しようとします。範囲内で一意の値を持つ要素だけが挿入されますが、値が重複する要素は無視されます。拒否される要素を確認するには、1 つの要素が指定された insert を使用します。

初期化子リストのメンバー関数 (6) は、initializer_list を使用して map に要素をコピーします。

インプレースで構築された (つまり、コピーまたは移動操作が実行されない) 要素の挿入については、「map::emplace」および「map::emplace_hint」を参照してください。

使用例

// map_insert.cpp
// compile with: /EHsc
#include <map>
#include <iostream>
#include <string>
#include <vector>
#include <utility>  // make_pair()

using namespace std;

template <typename M> void print(const M& m) {
    cout << m.size() << " elements: ";

    for (const auto& p : m) {
        cout << "(" << p.first << ", " << p.second << ") ";
    }

    cout << endl;
}

int main()
{

    // insert single values 
    map<int, int> m1;
    // call insert(const value_type&) version
    m1.insert({ 1, 10 });
    // call insert(ValTy&&) version 
    m1.insert(make_pair(2, 20));

    cout << "The original key and mapped values of m1 are:" << endl;
    print(m1);

    // intentionally attempt a duplicate, single element
    auto ret = m1.insert(make_pair(1, 111));
    if (!ret.second){
        auto pr = *ret.first;
        cout << "Insert failed, element with key value 1 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
    }
    else{
        cout << "The modified key and mapped values of m1 are:" << endl;
        print(m1);
    }
    cout << endl;

    // single element, with hint
    m1.insert(m1.end(), make_pair(3, 30));
    cout << "The modified key and mapped values of m1 are:" << endl;
    print(m1);
    cout << endl;


    // The templatized version inserting a jumbled range
    map<int, int> m2;
    vector<pair<int, int>> v;
    v.push_back(make_pair(43, 294));
    v.push_back(make_pair(41, 262));
    v.push_back(make_pair(45, 330));
    v.push_back(make_pair(42, 277));
    v.push_back(make_pair(44, 311));

    cout << "Inserting the following vector data into m2:" << endl;
    print(v);

    m2.insert(v.begin(), v.end());

    cout << "The modified key and mapped values of m2 are:" << endl;
    print(m2);
    cout << endl;

    // The templatized versions move-constructing elements
    map<int, string>  m3;
    pair<int, string> ip1(475, "blue"), ip2(510, "green");

    // single element
    m3.insert(move(ip1));
    cout << "After the first move insertion, m3 contains:" << endl;
    print(m3);

    // single element with hint
    m3.insert(m3.end(), move(ip2));
    cout << "After the second move insertion, m3 contains:" << endl;
    print(m3);
    cout << endl;

    map<int, int> m4;
    // Insert the elements from an initializer_list
    m4.insert({ { 4, 44 }, { 2, 22 }, { 3, 33 }, { 1, 11 }, { 5, 55 } });
    cout << "After initializer_list insertion, m4 contains:" << endl;
    print(m4);
    cout << endl;
}

出力

The original key and mapped values of m1 are:
2 elements: (1, 10) (2, 20)
Insert failed, element with key value 1 already exists.
  The existing element is (1, 10)

The modified key and mapped values of m1 are:
3 elements: (1, 10) (2, 20) (3, 30)

Inserting the following vector data into m2:
5 elements: (43, 294) (41, 262) (45, 330) (42, 277) (44, 311)
The modified key and mapped values of m2 are:
5 elements: (41, 262) (42, 277) (43, 294) (44, 311) (45, 330)

After the first move insertion, m3 contains:
1 elements: (475, blue)
After the second move insertion, m3 contains:
2 elements: (475, blue) (510, green)

After initializer_list insertion, m4 contains:
5 elements: (1, 11) (2, 22) (3, 33) (4, 44) (5, 55)

必要条件

ヘッダー: <map>

名前空間: std

次の方法で共有

map::insert

パラメーター

戻り値

解説

使用例

出力

必要条件

参照

関連項目

その他のリソース