std::list<T,Allocator>::insert

	(1)
iterator insert( const_iterator pos, const T& value );	(1)
iterator insert( const_iterator pos, T&& value );	(2)	(с C++11)
	(3)
iterator insert( const_iterator pos, size_type count, const T& value );	(3)
	(4)
template< class InputIt > iterator insert( const_iterator pos, InputIt first, InputIt last );	(4)
iterator insert( const_iterator pos, std::initializer_list<T> ilist );	(5)	(с C++11)

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

1,2) Вставляет value перед pos.

3) Вставляет count копий элемента value перед pos.

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

Этот перегрузчик имеет тот же эффект, что и перегрузка (3), если `InputIt` является целочисленным типом.	(до C++11)
Этот перегрузчик участвует в разрешении перегрузки только в том случае, если `InputIt` соответствует требованиям LegacyInputIterator, чтобы избежать неоднозначности с перегрузкой (3).	(с C++11)

Поведение не определено, если first и last являются итераторами в *this.

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

Ни один итератор или ссылка не становятся недействительными.

Параметры

pos	-	итератор перед которым будет вставлено содержимое (`pos` может быть итератором `end()`)
value	-	значение элемента для вставки
count	-	количество элементов для вставки
first, last	-	диапазон элементов для вставки, не может содержать итераторы в контейнер, для которого вызывается insert
ilist	-	список инициализации для вставки значений
Требования к типу
-`T` должно удовлетворять требованиям CopyInsertable для использования перегрузки (1).
-`T` должно удовлетворять требованиям MoveInsertable для использования перегрузки (2).
-`T` должно удовлетворять требованиям CopyAssignable и CopyInsertable для использования перегрузки (3).
-`T` должно удовлетворять требованиям EmplaceConstructible для использования перегрузки (4,5).

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

1,2) Итератор, указывающий на вставленный value.

3) Итератор, указывающий на первый вставленный элемент, или pos если count == 0.

4) Итератор, указывающий на первый вставленный элемент, или pos если first == last.

5) Итератор, указывающий на первый вставленный элемент, или pos если ilist пустой.

Сложность

1,2) Постоянная.

3) Линейная относительно count.

4) Линейная относительно std::distance(first, last).

5) Линейная относительно ilist.size().

Исключения

Если возникает исключение по любой причине, эти функции не имеют эффекта (гарантия сильной безопасности исключений).

Пример

#include <iostream>
#include <iterator>
#include <list>
 
void print(int id, const std::list<int>& container)
{
    std::cout << id << ". ";
    for (const int x : container)
        std::cout << x << ' ';
    std::cout << '\n';
}
 
int main ()
{
    std::list<int> c1(3, 100);
    print(1, c1);
 
    auto it = c1.begin();
    it = c1.insert(it, 200);
    print(2, c1);
 
    c1.insert(it, 2, 300);
    print(3, c1);
 
    // reset `it` to the begin:
    it = c1.begin();
 
    std::list<int> c2(2, 400);
    c1.insert(std::next(it, 2), c2.begin(), c2.end());
    print(4, c1);
 
    int arr[] = {501, 502, 503};
    c1.insert(c1.begin(), arr, arr + std::size(arr));
    print(5, c1);
 
    c1.insert(c1.end(), {601, 602, 603});
    print(6, c1);
}

Вывод:

1. 100 100 100
2. 200 100 100 100
3. 300 300 200 100 100 100
4. 300 300 400 400 200 100 100 100
5. 501 502 503 300 300 400 400 200 100 100 100
6. 501 502 503 300 300 400 400 200 100 100 100 601 602 603

Отчеты об ошибках

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

DR	Применяется к	Поведение, как опубликовано	Корректное поведение
LWG 149	C++98	перегрузки (3) и (4) не возвращали ничего	возвращает итератор

См. также

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

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