Namespaces
Variants

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

From cppreference.net

C++
Containers library
std::vector
Member types
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++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 .
Если удовлетворяется любое из следующих условий, поведение не определено:
(начиная с C++11)
2) Вставляет value перед pos , возможно используя семантику перемещения.
Если удовлетворяется любое из следующих условий, поведение не определено:
3) Вставляет count копий значения value перед позицией pos .
Если удовлетворяется любое из следующих условий, поведение не определено:
(начиная с C++11)
4) Вставляет элементы из диапазона [ first , last ) перед pos .

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

(до C++11)

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

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


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

Содержание

Параметры

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

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

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

Сложность

Если происходит перераспределение памяти, линейно по количеству элементов в vector после вставки; в противном случае линейно по количеству вставленных элементов плюс std:: distance ( pos, end ( ) ) .

Исключения

Если исключение выброшено не с помощью

  • копирующий конструктор T ,
  • перемещающий конструктор T ,
(since C++11)
  • оператор копирующего присваивания T ,
  • оператор перемещающего присваивания T ,
(since C++11)
  • любой InputIt операцию,

эти функции не оказывают никакого эффекта ( strong exception safety guarantee ).

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

(since 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); // перегрузка (1)
    stq::println("2. {}", c1);
    c1.insert(pos, 2, 300); // перегрузка (3)
    stq::println("3. {}", c1);
    // pos больше не действителен, получаем новый:
    pos = c1.begin();
    std::vector<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 Применяется к Поведение в опубликованной версии Корректное поведение
LWG 149 C++98 перегрузки ( 3 ) и ( 4 ) не возвращали значение возвращают итератор
LWG 247 C++98 сложность была указана только для перегрузки ( 3 ) указана для всех перегрузок
LWG 406 C++98 строгая гарантия исключений также применялась, если
исключение было вызвано операцией InputIt 		гарантия отсутствует в этом случае

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

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