map::insert

發行項
06/09/2015

將某個項目或項目範圍插入對應中。

// (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	除非其中包含了索引鍵已經過對等地排序的項目，否則為要插入對應中的項目值。
Where	要開始搜尋正確的插入點的地方 (若該點緊接於 Where 之前，則可能會在分攤常數時間插入，而不是對數時間)。
ValTy	範本參數，指定對應可用於建構 value_type 的項目的引數類型，並將 Val 作為引數完美轉送。
First	要複製之第一個項目的位置。
Last	要複製之最後一個項目之後的位置。
InputIterator	範本函式引數，符合輸入迭代器的需求，而迭代器會指向可用於建構 value_type 物件之類型的項目。
IList	要從中複製項目的 initializer_list。

傳回值

單一項目成員函式 (1) 和 (2) 會傳回 pair，其中 bool 元件為 True (若執行插入)，若對應已包含其中索引鍵具有依順序排列的對等值的項目，則為 False。若 bool 元件為 True，傳回值組的迭代器元件會指向最新插入的項目；若 bool 元件為 False，則會指向現有項目。

具有提示的單一項目成員函式 (3) 及 (4) 會傳回指向位置的迭代器，該位置是新項目插入對應中的位置，或者，若對等索引鍵已存在，則指向現有項目。

備註

此函式不會使任何迭代器、指標或參考無效。

在只插入一個項目的期間，若擲出例外狀況，則不會修改容器的狀態。在插入多個項目期間，若擲出例外狀況，則容器會處於未指定但有效的狀態。

若要存取 pair pr 的迭代器元件 (由單一項目成員函式傳回)，請使用 pr.first；若要對傳回的 pair 取值，請使用 *pr.first (提供您項目)。若要存取 bool 元件，請使用 pr.second。例如，請參閱本文中稍後的範例程式碼。

容器的 value_type 是屬於容器的 typedef，而針對對應，map<K, V>::value_type 是 pair<const K, V>。項目的值是已排序的組，其中第一個元件等於索引鍵值，而第二個元件等於項目的資料值。

範圍成員函式 (5) 會將項目值的序列插入對應至每個項目的對應，而這些項目是由範圍 [First, Last) 中的迭代器指定；因此不會插入 Last。容器成員函式 end() 會參考容器中最後一個項目之後的位置。例如陳述式 m.insert(v.begin(), v.end()); 嘗試將 v 的所有項目插入 m。只會插入具有範圍中唯一值的項目；若重複則會忽略。若要觀察哪些項目會遭到拒絕，請使用單一項目版本的 insert。

初始設定式清單成員函式 (6) 使用 initializer_list 將項目複製到對應。

如需插入就地建構的項目 (換言之即為未執行複製或移動作業)，請參閱 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)