std::inplace_vector<T,N>::insert

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

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

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

2) Вставляет value перед pos, при необходимости используя семантику перемещения.

3) Вставляет count копий value перед pos.

4) Вставляет элементы из диапазона [first, last) перед pos. Эта перегрузка участвует в разрешении перегрузки только в том случае, если InputIt является LegacyInputIterator (чтобы избежать неоднозначности с перегрузкой (3)).

Каждый итератор в [first, last) разыменовывается один раз.

Если first и last являются итераторами в *this, поведение не определено.

5) Вставляет элементы из списка инициализации ilist перед pos. Эквивалентно: insert(pos, ilist.begin(), ilist.end());.

Параметры

pos	-	итератор, перед которым будет вставлено содержимое (`pos` может быть итератором `end()`)
value	-	значение вставляемого элемента
count	-	количество вставляемых элементов
first, last	-	пара итераторов, задающая исходный диапазон вставляемых элементов
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 пуст.

Сложность

Линейна относительно количества вставляемых элементов плюс расстояния между pos и end() контейнера.

Исключения

Выбрасывает std::bad_alloc, если перед вызовом size() == capacity(). Функция не оказывает побочных эффектов (гарантия строгой безопасности исключений).
Любое исключение, выброшенное при инициализации вставляемого элемента или при выполнении любой операции LegacyInputIterator. Элементы в [0, pos) не изменяются.

Пример

#include <initializer_list>
#include <inplace_vector>
#include <iterator>
#include <new>
#include <print>

int main()
{
    std::inplace_vector<int, 14> v(3, 100);
    std::println("1. {}", v);

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

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

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

    v.insert(v.end(), {601, 602, 603}); // overload (5)
    std::println("5. {}", v);

    const auto list = {-13, -12, -11};
    try
    {
        v.insert(v.begin(), list); // throws: no space
    }
    catch(const std::bad_alloc&)
    {
        std::println("bad_alloc: v.capacity()={} < v.size()={} + list.size()={}",
                     v.capacity(), v.size(), list.size());
    }
}

Вывод:

1. [100, 100, 100]
2. [200, 100, 100, 100]
3. [300, 300, 200, 100, 100, 100]
4. [501, 502, 503, 300, 300, 200, 100, 100, 100]
5. [501, 502, 503, 300, 300, 200, 100, 100, 100, 601, 602, 603]
bad_alloc: v.capacity()=14 < v.size()=12 + list.size()=3

См. также

emplace	создаёт элемент непосредственно на месте (открытая функция-член)
insert_range	вставляет диапазон элементов (открытая функция-член)

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