multiset::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) возвращают итератор в позиции, где был вставлен новый элемент.

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

Заметки

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

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

value_type контейнера — это определение типа, которое принадлежит контейнеру, а для набора multiset<V>::value_type — это const V.

Функция-член с диапазоном (5) вставляет последовательность значений элементов в мультинабор, соответствующий каждому элементу, адресованному итератором в диапазоне [First, Last). Следовательно, Last не вставляется. Контейнер функции-члена end() ссылается на позицию сразу после последнего элемента в контейнере. Например, оператор s.insert(v.begin(), v.end()); пытается вставить все элементы v в s.

Функция-член списка инициализаторов (6) использует initializer_list для копирования элементов в мультинабор.

Сведения о вставке элемента, созданного на месте (т. е. без выполнения операций копирования или перемещения), см. в описании функций multiset::emplace и multiset::emplace_hint.

Пример

// multiset_insert.cpp
// compile with: /EHsc
#include <set>
#include <iostream>
#include <string>
#include <vector>

using namespace std;

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

    for (const auto& p : s) {
        cout << "(" << p << ") ";
    }

    cout << endl;
}

int main()
{

    // insert single values 
    multiset<int> s1;
    // call insert(const value_type&) version
    s1.insert({ 1, 10 });
    // call insert(ValTy&&) version 
    s1.insert(20);

    cout << "The original multiset values of s1 are:" << endl;
    print(s1);

    // intentionally attempt a duplicate, single element
    s1.insert(1);
    cout << "The modified multiset values of s1 are:" << endl;
    print(s1);
    cout << endl;

    // single element, with hint
    s1.insert(s1.end(), 30);
    cout << "The modified multiset values of s1 are:" << endl;
    print(s1);
    cout << endl;


    // The templatized version inserting a jumbled range
    multiset<int> s2;
    vector<int> v;
    v.push_back(43);
    v.push_back(294);
    v.push_back(41);
    v.push_back(330);
    v.push_back(42);
    v.push_back(45);

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

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

    cout << "The modified multiset values of s2 are:" << endl;
    print(s2);
    cout << endl;

    // The templatized versions move-constructing elements
    multiset<string>  s3;
    string str1("blue"), str2("green");

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

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

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

Вывод

The original multiset values of s1 are:
3 elements: (1) (10) (20)
The modified multiset values of s1 are:
4 elements: (1) (1) (10) (20)

The modified multiset values of s1 are:
5 elements: (1) (1) (10) (20) (30)

Inserting the following vector data into s2:
6 elements: (43) (294) (41) (330) (42) (45)
The modified multiset values of s2 are:
6 elements: (41) (42) (43) (45) (294) (330)

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

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