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

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

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

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.

Если после выполнения операции новый size() больше старого capacity(), происходит перераспределение памяти. В этом случае все итераторы (включая итератор end()) и все ссылки на элементы становятся недействительными. В противном случае остаются действительными только итераторы и ссылки, находящиеся до точки вставки.

Параметры

pos	-	итератор, перед которым будет вставлено содержимое (`pos` может быть итератором `end()`)
value	-	значение вставляемого элемента
count	-	количество вставляемых элементов
first, last	-	пара итераторов, задающая диапазон вставляемых элементов (не могут быть итераторами в контейнер, для которого вызывается insert)
ilist	-	`std::initializer_list`, из которого вставляются значения
Требования к типам
-`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 в *this или std::is_nothrow_move_constructible<T>::value является true, эта функция не оказывает никакого эффекта (строгая гарантия безопасности исключений). В противном случае, если исключение возникает в конструкторе перемещения некопируемого T, последствия не определены.

(начиная с C++11)

Пример

#include <iostream>
#include <iterator>
#include <string_view>
#include <vector>

namespace stq {
void println(std::string_view rem, const std::vector<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::vector<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);

    // pos no longer valid, get a new one:
    pos = c1.begin();

    std::vector<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++.

Отчёт об ошибке	Применяется к	Опубликованное поведение	Корректное поведение
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/cpp/container/vector/insert