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

Inserta elementos en la ubicación especificada del contenedor.

1) Inserta una copia de value antes de pos .
Si se satisface cualquiera de las siguientes condiciones, el comportamiento es indefinido:
(desde C++11)
2) Inserta value antes de pos , posiblemente utilizando semántica de movimiento.
Si se satisface cualquiera de las siguientes condiciones, el comportamiento es indefinido:
3) Inserta count copias del value antes de pos .
Si se satisface cualquiera de las siguientes condiciones, el comportamiento es indefinido:
(desde C++11)
4) Inserta elementos del rango [ first , last ) antes de pos .

Esta sobrecarga tiene el mismo efecto que la sobrecarga (3) si InputIt es un tipo integral.

(until C++11)

Esta sobrecarga participa en la resolución de sobrecarga solo si InputIt cumple con los requisitos de LegacyInputIterator .

(since C++11)
Si se satisface cualquiera de las siguientes condiciones, el comportamiento es indefinido:
(desde C++11)
  • first o last son iteradores de * this .
5) Inserta elementos desde la lista de inicializadores ilist antes de pos .
Equivalente a insert ( pos, ilist. begin ( ) , ilist. end ( ) ) .


Todos los iteradores (incluyendo el end() iterator) quedan invalidados. Las referencias también quedan invalidadas, a menos que pos == begin() o pos == end() , en cuyo caso no quedan invalidados.

Contenidos

Parámetros

pos - iterador antes del cual se insertará el contenido
value - valor del elemento a insertar
count - número de elementos a insertar
first, last - el par de iteradores que define el rango de elementos a insertar
ilist - std::initializer_list para insertar los valores desde

Valor de retorno

1,2) Iterador que apunta al value insertado.
3-5) Iterador que apunta al primer elemento insertado, o pos si no se inserta ningún elemento.

Complejidad

Lineal en el número de elementos insertados más std:: min ( std:: distance ( begin ( ) , pos ) , std:: distance ( pos, end ( ) ) ) .

Excepciones

Si se lanza una excepción que no sea por

  • el constructor de copia de T ,
  • el constructor de movimiento de T ,
(since C++11)
  • el operador de asignación de copia de T ,
  • el operador de asignación de movimiento de T ,
(since C++11)

esta función no tiene efecto (garantía de excepción fuerte).

Si se lanza una excepción al insertar un único elemento en cualquiera de los extremos, esta función no tiene efecto (garantía fuerte de excepción). De lo contrario, si se lanza una excepción por el constructor de movimiento de un tipo T no- CopyInsertable T , los efectos no están especificados.

(since C++11)

Ejemplo

Ejecutar este código 
#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); // overload (1)
    stq::println("2. {}", c1);
    c1.insert(pos, 2, 300); // overload (3)
    stq::println("3. {}", c1);
    // reset pos to the begin:
    pos = c1.begin();
    std::deque<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);
}

Salida: 

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]

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares publicados anteriormente de C++.

DR Aplicado a Comportamiento publicado Comportamiento correcto
LWG 149 C++98 las sobrecargas ( 3 ) y ( 4 ) no retornaban nada retorna un iterador
LWG 247 C++98 la complejidad solo estaba especificada
para insertar un solo elemento 		también especificada para insertar
múltiples elementos

Véase también

(C++11)
construye un elemento en el lugar
(función miembro pública)
inserta un elemento al principio
(función miembro pública)
añade un elemento al final
(función miembro pública)
crea un std::insert_iterator del tipo inferido del argumento
(plantilla de función)