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) возвращают пару, компонент bool которой имеет значение true, если была осуществлена вставка, и значение false, если сопоставление уже содержало элемент с эквивалентным порядковым значением ключа. Компонент итератора пары возвращаемых значений указывает на вставленный элемент, если значение компонента bool равно true, или на существующий элемент, если значение компонента bool равно false.

Одноэлементные функции-члены с подсказкой (3) и (4) возвращают итератор, который указывает на позицию, где новый элемент был вставлен, или, если элемент с эквивалентным ключом уже существует, указывает на существующий элемент.

Заметки

Эта функция не делает никакие итераторы, указатели или ссылки недействительными.

Если во время вставки одного элемента вызывается исключение, состояние контейнера не изменяется. Если во время вставки нескольких элементов вызывается исключение, контейнер остается в неопределенном, но допустимом состоянии.

Для доступа к компоненту итератора pair pr, возвращаемого одноэлементными функциями-членами, используйте pr.first. Для разыменования итератора в возвращенной паре используйте *pr.first, чтобы получить элемент. Для доступа к компоненту bool используйте pr.second. См. пример кода далее в этой статье.

value_type контейнера — это определение типа, которое принадлежит контейнеру, а для сопоставления 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)