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

iterator insert( const value_type& value );	(1)
iterator insert( value_type&& value );	(2)	(с C++11)
	(3)
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 );	(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 — пустой узел-обработчик, ничего не делает и возвращает итератор конца. В противном случае вставляет элемент, принадлежащий 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) Итератор конца, если 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/w/cpp/container/multiset/insert