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；要在返回的配对中取消引用迭代器，请使用 *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)