Namespaces
Variants

std::multimap<Key,T,Compare,Allocator>:: insert

From cppreference.net
C++
Containers library
std::multimap
Member functions
Non-member functions
Deduction guides (C++17)
iterator insert ( const value_type & value ) ;
(1)
iterator insert ( value_type && value ) ;
(2) (начиная с C++17)
template < class P >
iterator insert ( P && value ) ;
(3) (начиная с C++11)
(4)
iterator insert ( iterator pos, const value_type & value ) ;
(до C++11)
iterator insert ( const_iterator pos, const value_type & value ) ;
(начиная с C++11)
iterator insert ( const_iterator pos, value_type && value ) ;
(5) (начиная с C++17)
template < class P >
iterator insert ( const_iterator pos, P && value ) ;
(6) (начиная с C++11)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(7)
void insert ( std:: initializer_list < value_type > ilist ) ;
(8) (начиная с C++11)
iterator insert ( node_type && nh ) ;
(9) (начиная с C++17)
iterator insert ( const_iterator pos, node_type && nh ) ;
(10) (начиная с C++17)

Вставляет элемент(ы) в контейнер.

1-3) Вставляет value . Если контейнер содержит элементы с эквивалентным ключом, вставляет в верхнюю границу этого диапазона.
Перегрузка (3) эквивалентна emplace ( std:: forward < P > ( value ) ) и участвует в разрешении перегрузки только если std:: is_constructible < value_type, P && > :: value == true .
4-6) Вставляет value в позицию, максимально близкую к позиции непосредственно перед pos .
Перегрузка (6) эквивалентна emplace_hint ( hint, std:: forward < P > ( value ) ) и участвует в разрешении перегрузки только если std:: is_constructible < value_type, P && > :: value == true .
7) Вставляет элементы из диапазона [ first , last ) .
8) Вставляет элементы из списка инициализации ilist .
9) Если nh является пустым node handle , не выполняет никаких действий. В противном случае вставляет элемент, принадлежащий nh , в контейнер и возвращает итератор, указывающий на вставленный элемент. Если в контейнере существует диапазон, содержащий элементы с ключами, эквивалентными nh. key ( ) , элемент вставляется в конец этого диапазона. Поведение не определено, если nh не пуст и get_allocator ( ) ! = nh. get_allocator ( ) .
10) Если nh является пустым node handle , не выполняет никаких действий и возвращает конечный итератор. В противном случае вставляет элемент, принадлежащий nh , в контейнер и возвращает итератор, указывающий на элемент с ключом, эквивалентным nh. key ( ) . Элемент вставляется как можно ближе к позиции непосредственно перед pos . Поведение не определено, если nh не пуст и get_allocator ( ) ! = nh. get_allocator ( ) .

Никакие итераторы или ссылки не инвалидируются. Если вставка успешна, указатели и ссылки на элемент, полученные пока он содержался в node handle, инвалидируются, а указатели и ссылки, полученные на этот элемент до его извлечения, становятся валидными. (since C++17)

Содержание

Параметры

pos - итератор на позицию, перед которой будет вставлен новый элемент
value - значение элемента для вставки
first, last - пара итераторов, определяющая исходный диапазон элементов для вставки
ilist - список инициализации для вставки значений
nh - совместимый node handle
Требования к типам
-
InputIt должен удовлетворять требованиям LegacyInputIterator .

Возвращаемое значение

1-6) Итератор на вставленный элемент.
7,8) (нет)
9,10) Конечный итератор, если nh был пустым, итератор указывающий на вставленный элемент в противном случае.

Исключения

1-6) Если при выполнении любой операции возникает исключение, вставка не производится.
7,8) Гарантия безопасности исключений отсутствует.
9,10) Если при выполнении любой операции возникает исключение, вставка не производится.

Сложность

1-3) O(log(size()))
4-6) Амортизированная константа, если вставка происходит в позицию непосредственно перед pos , O(log(size())) в противном случае.
7,8) O(N·log(size() + N)) , где N - количество вставляемых элементов.
9) O(log(size()))
10) Амортизированная константа, если вставка происходит в позицию непосредственно перед pos , O(log(size())) в противном случае.

Пример

Запустить этот код 
#include <functional>
#include <iostream>
#include <map>
#include <string>
#include <string_view>
#include <utility>
template<class M>
void print(const std::string_view rem, const M& mmap)
{
    std::cout << rem << ' ';
    for (const auto& e : mmap)
        std::cout << '{' << e.first << ',' << e.second << "} ";
    std::cout << '\n';
}
int main()
{
    // инициализация списком
    std::multimap<int, std::string, std::greater<int>> mmap
        {{2, "foo"}, {2, "bar"}, {3, "baz"}, {1, "abc"}, {5, "def"}};
    print("#1", mmap);
    // вставка с использованием value_type
    mmap.insert(decltype(mmap)::value_type(5, "pqr"));
    print("#2", mmap);
    // вставка с использованием pair
    mmap.insert(std::pair{6, "uvw"});
    print("#3", mmap);
    mmap.insert({7, "xyz"});
    print("#4", mmap);
    // вставка с использованием initializer_list
    mmap.insert({{5, "one"}, {5, "two"}});
    print("#5", mmap);
    // вставка с использованием пары итераторов
    mmap.clear();
    const auto il = {std::pair{1, "ä"}, {2, "ё"}, {2, "ö"}, {3, "ü"}};
    mmap.insert(il.begin(), il.end());
    print("#6", mmap);
}

Вывод: 

#1 {5,def} {3,baz} {2,foo} {2,bar} {1,abc}
#2 {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#3 {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#4 {7,xyz} {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#5 {7,xyz} {6,uvw} {5,def} {5,pqr} {5,one} {5,two} {3,baz} {2,foo} {2,bar} {1,abc}
#6 {3,ü} {2,ё} {2,ö} {1,ä}

Отчеты о дефектах

Следующие отчеты об изменениях поведения, влияющие на дефекты, были применены ретроактивно к ранее опубликованным стандартам C++.

DR Applied to Behavior as published Correct behavior
LWG 233 C++98 pos был просто подсказкой, его можно было полностью игнорировать вставка должна быть
как можно ближе к
позиции непосредственно перед pos
LWG 264 C++98 сложность перегрузки (5) требовалась линейной, если
диапазон [ first , last ) отсортирован согласно Compare 		убрано требование линейности
в этом специальном случае
LWG 371 C++98 порядок эквивалентных элементов
не гарантировался сохраненным 		требуется сохранять
LWG 2005 C++11 перегрузки (3,6) были плохо описаны улучшено описание

Смотрите также

(C++11)
создаёт элемент на месте
(public member function)
(C++11)
создаёт элементы на месте с использованием подсказки
(public member function)
создаёт std::insert_iterator типа, выведенного из аргумента
(function template)