Namespaces
Variants

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

From cppreference.net

C++
Containers library
std::deque
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++26)
iterator insert ( const_iterator pos, T && value ) ;
(2) (начиная с C++11)
(constexpr начиная с C++26)
iterator insert ( const_iterator pos,
size_type count, const T & value ) ;
(3) (constexpr начиная с C++26)
template < class InputIt >
iterator insert ( const_iterator pos, InputIt first, InputIt last ) ;
(4) (constexpr начиная с C++26)
iterator insert ( const_iterator pos, std:: initializer_list < T > ilist ) ;
(5) (начиная с C++11)
(constexpr начиная с C++26)

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

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


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

Содержание

Параметры

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

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

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

Сложность

Линейно по количеству вставленных элементов плюс std:: min ( std:: distance ( begin ( ) , pos ) , std:: distance ( pos, end ( ) ) ) .

Исключения

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

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

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

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

(since C++11)

Пример

Запустить этот код 
#include <iostream>
#include <iterator>
#include <string_view>
#include <deque>
namespace stq
{
    void println(std::string_view rem, const std::deque<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::deque<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::deque<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 сложность была указана только
для вставки одного элемента 		также указана для вставки
нескольких элементов

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

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