Namespaces
Variants

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

From cppreference.net

C++
Containers library
std::list
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
iterator insert ( const_iterator pos, const T & value ) ;
(1) (constexpr начиная с C++26)
iterator insert ( const_iterator pos, T && value ) ;
(2) (начиная с C++11)
(constexpr начиная с C++26)
iterator insert ( const_iterator pos,
size_type count, const T & value ) ;
(3) (constexpr начиная с C++26)
template < class InputIt >
iterator insert ( const_iterator pos, InputIt first, InputIt last ) ;
(4) (constexpr начиная с C++26)
iterator insert ( const_iterator pos, std:: initializer_list < T > ilist ) ;
(5) (начиная с C++11)
(constexpr начиная с C++26)

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

1) Вставляет копию value перед pos .

Если T не является CopyInsertable в list , поведение не определено.

(начиная с C++11)
2) Вставляет value перед pos , возможно используя семантику перемещения.
Если T не является MoveInsertable для list , поведение не определено.
3) Вставляет count копий значения value перед позицией pos .
Если удовлетворяется любое из следующих условий, поведение не определено:
(начиная с C++11)
4) Вставляет элементы из диапазона [ first , last ) перед pos .

Эта перегрузка имеет тот же эффект, что и перегрузка (3) , если InputIt является целочисленным типом.

(до C++11)

Эта перегрузка участвует в разрешении перегрузки только если InputIt удовлетворяет требованиям LegacyInputIterator .

(начиная с C++11)
Если удовлетворяется любое из следующих условий, поведение не определено:
(начиная с C++11)
  • first или last являются итераторами на * this .
5) Вставляет элементы из списка инициализации ilist перед pos .
Эквивалентно insert ( pos, ilist. begin ( ) , ilist. end ( ) ) .


Никакие итераторы или ссылки не инвалидируются.

Содержание

Параметры

pos - итератор, перед которым будет вставлено содержимое
value - значение элемента для вставки
count - количество элементов для вставки
first, last - пара итераторов, определяющая диапазон элементов для вставки
ilist - std::initializer_list для вставки значений из

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

1,2) Итератор, указывающий на вставленное value .
3-5) Итератор, указывающий на первый вставленный элемент, или pos если ни один элемент не был вставлен.

Сложность

Линейно по количеству вставленных элементов.

Исключения

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

Пример

Запустить этот код 
#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); // перегрузка (1)
    stq::println("2. {}", c1);
    c1.insert(pos, 2, 300); // перегрузка (3)
    stq::println("3. {}", c1);
    // сбросить pos в начало:
    pos = c1.begin();
    std::list<int> c2(2, 400);
    c1.insert(std::next(pos, 2), c2.begin(), c2.end()); // перегрузка (4)
    stq::println("4. {}", c1);
    int arr[] = {501, 502, 503};
    c1.insert(c1.begin(), arr, arr + std::size(arr)); // перегрузка (4)
    stq::println("5. {}", c1);
    c1.insert(c1.end(), {601, 602, 603}); // перегрузка (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 Applied to Behavior as published Correct behavior
LWG 149 C++98 перегрузки ( 3 ) и ( 4 ) ничего не возвращали возвращают итератор

Смотрите также

(C++11)
создаёт элемент на месте
(public member function)
вставляет элемент в начало
(public member function)
добавляет элемент в конец
(public member function)
создаёт std::insert_iterator типа, выведенного из аргумента
(function template)