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

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

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

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.

Если после операции новое значение size() больше старого capacity(), происходит перераспределение, в этом случае все итераторы (включая итератор 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` должен удовлетворять требованиям MoveAssignable и MoveInsertable для использования перегрузки (4). требуется только если `InputIt` удовлетворяет LegacyInputIterator, но не LegacyForwardIterator. (до C++17)
-`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)

любой InputIt операции,

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

Если исключение возникает при вставке одиночного элемента в конец, и T — CopyInsertable или std::is_nothrow_move_constructible<T>::value — true, эта функция не имеет эффекта (гарантия сильного исключения). В противном случае, если исключение возникает в конструкторе перемещения не-CopyInsertable T, последствия не определены.

(с C++11)

Пример

#include <iostream>
#include <iterator>
#include <vector>
 
void print(int id, const std::vector<int>& container)
{
    std::cout << id << ". ";
    for (const int x : container)
        std::cout << x << ' ';
    std::cout << '\n';
}
 
int main ()
{
    std::vector<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);
 
    // `it` no longer valid, get a new one:
    it = c1.begin();
 
    std::vector<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	сложность была указана только для перегрузки (3)	указана для всех перегрузок
LWG 406	C++98	гарантия сильного исключения также применялась, если исключение брошено при `InputIt` операции	гарантии нет в этом случае

См. также

emplace (C++11)	создаёт элемент на месте (публичный член-функция)
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/vector/insert