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

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 является пустым обработчиком узла, ничего не делает. В противном случае вставляет элемент, принадлежащий nh, в контейнер и возвращает итератор, указывающий на вставленный элемент. Если в контейнере существует диапазон, содержащий элементы с ключами, эквивалентными nh.key(), элемент вставляется в конец этого диапазона. Поведение не определено, если nh не пуст и get_allocator() != nh.get_allocator().

10) Если nh является пустым обработчиком узла, ничего не делает и возвращает итератор конца. В противном случае вставляет элемент, принадлежащий nh, в контейнер и возвращает итератор, указывающий на элемент с ключом, эквивалентным nh.key(). Элемент вставляется как можно ближе к позиции, предшествующей pos. Поведение не определено, если nh не пуст и get_allocator() != nh.get_allocator().

Никакие итераторы или ссылки не становятся недействительными. Если вставка выполняется успешно, указатели и ссылки на элемент, полученные, пока он хранился в обработчике узла, становятся недействительными, и указатели и ссылки, полученные на этот элемент до его извлечения, становятся действительными.(с C++17)

Параметры

pos	-	итератор на позицию перед которой будет вставлен новый элемент
value	-	значение элемента для вставки
first, last	-	диапазон элементов для вставки
ilist	-	список инициализации для вставки значений
nh	-	совместимый обработчик узла
Требования к типу
-`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()
{
    // list-initialize
    std::multimap<int, std::string, std::greater<int>> mmap
        {{2, "foo"}, {2, "bar"}, {3, "baz"}, {1, "abc"}, {5, "def"}};
    print("#1", mmap);
 
    // insert using value_type
    mmap.insert(decltype(mmap)::value_type(5, "pqr"));
    print("#2", mmap);
 
    // insert using pair
    mmap.insert(std::pair{6, "uvw"});
    print("#3", mmap);
 
    mmap.insert({7, "xyz"});
    print("#4", mmap);
 
    // insert using initializer_list
    mmap.insert({{5, "one"}, {5, "two"}});
    print("#5", mmap);
 
    // insert using a pair of iterators
    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	Применяется к	Поведение, как опубликовано	Правильное поведение
LWG 233	C++98	`pos` было просто подсказкой, его можно было полностью игнорировать	вставка должна быть как можно ближе к позиции, предшествующей `pos`
LWG 264	C++98	сложность перегрузки (5) должна была быть линейной, если диапазон `[first,` `last)` отсортирован согласно `Compare`	удалено линейное требование в этом особом случае
LWG 371	C++98	порядок эквивалентных элементов не гарантировалось сохранение	требовалось сохранить
LWG 2005	C++11	перегрузки (3,6) были плохо описаны	улучшено описание

См. также

emplace (C++11)	создаёт элемент на месте (публичный член-функция)
emplace_hint (C++11)	создаёт элементы на месте с подсказкой (публичный член-функция)
inserter	создаёт `std::insert_iterator` типа, выведенного из аргумента (шаблонная функция)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/container/multimap/insert