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

iterator insert( const_iterator pos, const T& value );	(1)
iterator insert( const_iterator pos, T&& value );	(2)	(начиная с C++11)
iterator insert( const_iterator pos, size_type count, const T& value );	(3)
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) Вставляет копию value перед pos.

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	-	`std::initializer_list` для вставки значений из
Требования к типам
-`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 <string_view>
#include <list>

namespace stq {
void println(std::string_view rem, const std::list<int>& container)
{
    std::cout << rem.substr(0, rem.size() - 2) << '[';
    bool first{true};
    for (const int x : container)
        std::cout << (first ? first = false, "" : ", ") << x;
    std::cout << "]\n";
}
}

int main()
{
    std::list<int> c1(3, 100);
    stq::println("1. {}", c1);

    auto pos = c1.begin();
    pos = c1.insert(pos, 200); // overload (1)
    stq::println("2. {}", c1);

    c1.insert(pos, 2, 300); // overload (3)
    stq::println("3. {}", c1);

    // reset pos to the begin:
    pos = c1.begin();

    std::list<int> c2(2, 400);
    c1.insert(std::next(pos, 2), c2.begin(), c2.end()); // overload (4)
    stq::println("4. {}", c1);

    int arr[] = {501, 502, 503};
    c1.insert(c1.begin(), arr, arr + std::size(arr)); // overload (4)
    stq::println("5. {}", c1);

    c1.insert(c1.end(), {601, 602, 603}); // overload (5)
    stq::println("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	создаёт `std::insert_iterator` типа, выводимого из аргумента (шаблон функции)

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