std::multiset<Key,Compare,Allocator>::insert

iterator insert( const value_type& value );	(1)
iterator insert( value_type&& value );	(2)	(начиная с C++11)
iterator insert( iterator pos, const value_type& value );	(3)	(до C++11)
iterator insert( const_iterator pos, const value_type& value );	(3)		(начиная с C++11)
iterator insert( const_iterator pos, value_type&& value );	(4)	(начиная с C++11)
template< class InputIt > void insert( InputIt first, InputIt last );	(5)
void insert( std::initializer_list<value_type> ilist );	(6)	(начиная с C++11)
iterator insert( node_type&& nh );	(7)	(начиная с C++17)
iterator insert( const_iterator pos, node_type&& nh );	(8)	(начиная с C++17)

Вставляет элемент(ы) в контейнер. Порядок оставшихся эквивалентных элементов сохраняется.

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

3,4) Вставляет value в позицию, максимально близкую к позиции непосредственно перед pos.

5) Вставляет элементы из диапазона [first, last).

6) Вставляет элементы из списка инициализации ilist.

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

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

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

Параметры

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

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

1-4) Итератор на вставленный элемент.

5,6) Нет.

7,8) Итератор end, если nh был пуст; в противном случае итератор, указывающий на вставленный элемент.

Исключения

1-4,7,8) Если любая операция выбрасывает исключение, вставка не оказывает никакого эффекта.

5,6) Гарантия безопасности при исключениях не предоставляется.

Сложность

1,2,7) O(log(size()))

3,4,8) Амортизированная константная, если вставка выполняется в позицию непосредственно перед pos; в противном случае O(log(size())).

5,6) O(N·log(size() + N)), где N — количество вставляемых элементов.

Пример

Отчёты об исправлении дефектов

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

DR	Применяется к	Поведение согласно опубликованному стандарту	Правильное поведение
LWG 233	C++98	`pos` был лишь подсказкой и мог быть полностью проигнорирован	требуется, чтобы вставка выполнялась в позицию, максимально близкую к позиции непосредственно перед `pos`
LWG 264	C++98	сложность перегрузки (5) должна была быть линейной, если диапазон `[first, last)` отсортирован согласно `Compare`	требование линейной сложности в этом особом случае удалено
LWG 371	C++98	сохранение порядка эквивалентных элементов не гарантировалось	требуется сохранять порядок

См. также

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/cpp/container/multiset/insert