std::deque<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.

Все итераторы (включая итератор end()) становятся недействительными. Ссылки также становятся недействительными, за исключением случаев pos == begin() или pos == end(), в которых они не становятся недействительными.

Параметры

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

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

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

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

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

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

Сложность

1,2) Постоянная плюс линейная, в зависимости от меньшего из расстояний между pos и любым из концов контейнера.

3) Линейная от count плюс линейная от меньшего из расстояний между pos и любым из концов контейнера.

4) Линейная от std::distance(first, last) плюс линейная от меньшего из расстояний между pos и любым из концов контейнера.

5) Линейная от ilist.size() плюс линейная от меньшего из расстояний между pos и любым из концов контейнера.

Исключения

Если исключение выбрасывается, кроме

конструктора копирования T,

конструктора перемещения T,

(с C++11)

оператора присваивания копирования T,

оператора присваивания перемещения T,

(с C++11)

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

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

(с C++11)

Пример

#include <iostream>
#include <iterator>
#include <deque>
 
void print(int id, const std::deque<int>& container)
{
    std::cout << id << ". ";
    for (const int x : container)
        std::cout << x << ' ';
    std::cout << '\n';
}
 
int main ()
{
    std::deque<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::deque<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) ничего не возвращали	возвращает итератор
LWG 247	C++98	сложность была указана только для вставки одного элемента	также указана для вставки нескольких элементов

См. также

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