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

Insère des éléments à l'emplacement spécifié dans le conteneur.

1) Insère une copie de value avant pos .
Si l'une des conditions suivantes est satisfaite, le comportement est indéfini :
(depuis C++11)
2) Insère value avant pos , en utilisant potentiellement la sémantique de déplacement.
Si l'une des conditions suivantes est satisfaite, le comportement est indéfini :
3) Insère count copies de la value avant pos .
Si l'une des conditions suivantes est satisfaite, le comportement est indéfini :
(depuis C++11)
4) Insère les éléments de l'intervalle [ first , last ) avant pos .

Cette surcharge a le même effet que la surcharge (3) si InputIt est un type entier.

(jusqu'en C++11)

Cette surcharge participe à la résolution de surcharge seulement si InputIt satisfait aux exigences de LegacyInputIterator .

(depuis C++11)
Si l'une des conditions suivantes est satisfaite, le comportement est indéfini :
(depuis C++11)
  • first ou last sont des itérateurs vers * this .
5) Insère les éléments de la liste d'initialisation ilist avant pos .
Équivalent à insert ( pos, ilist. begin ( ) , ilist. end ( ) ) .


Tous les itérateurs (y compris l'itérateur end() ) sont invalidés. Les références sont également invalidées, sauf si pos == begin() ou pos == end() , auquel cas elles ne sont pas invalidées.

Table des matières

Paramètres

pos - itérateur avant lequel le contenu sera inséré
value - valeur de l'élément à insérer
count - nombre d'éléments à insérer
first, last - la paire d'itérateurs définissant la plage d'éléments à insérer
ilist - std::initializer_list pour insérer les valeurs

Valeur de retour

1,2) Itérateur pointant vers la value insérée.
3-5) Itérateur pointant vers le premier élément inséré, ou pos si aucun élément n'est inséré.

Complexité

Linéaire dans le nombre d'éléments insérés plus std:: min ( std:: distance ( begin ( ) , pos ) , std:: distance ( pos, end ( ) ) ) .

Exceptions

Si une exception est levée autrement que par

  • le constructeur de copie de T ,
  • le constructeur de déplacement de T ,
(depuis C++11)
  • l'opérateur d'affectation par copie de T ,
  • l'opérateur d'affectation par déplacement de T ,
(depuis C++11)

cette fonction n'a aucun effet (garantie d'exception forte).

Si une exception est levée lors de l'insertion d'un seul élément à l'une ou l'autre extrémité, cette fonction n'a aucun effet (garantie d'exception forte). Sinon, si une exception est levée par le constructeur de déplacement d'un CopyInsertable T non-, les effets ne sont pas spécifiés.

(depuis C++11)

Exemple

Exécuter ce code 
#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); // surcharge (1)
    stq::println("2. {}", c1);
    c1.insert(pos, 2, 300); // surcharge (3)
    stq::println("3. {}", c1);
    // réinitialiser pos au début :
    pos = c1.begin();
    std::deque<int> c2(2, 400);
    c1.insert(std::next(pos, 2), c2.begin(), c2.end()); // surcharge (4)
    stq::println("4. {}", c1);
    int arr[] = {501, 502, 503};
    c1.insert(c1.begin(), arr, arr + std::size(arr)); // surcharge (4)
    stq::println("5. {}", c1);
    c1.insert(c1.end(), {601, 602, 603}); // surcharge (5)
    stq::println("6. {}", c1);
}

Sortie : 

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]

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR Appliqué à Comportement tel que publié Comportement correct
LWG 149 C++98 les surcharges ( 3 ) et ( 4 ) ne retournaient rien retourne un itérateur
LWG 247 C++98 la complexité n'était spécifiée
que pour l'insertion d'un seul élément 		également spécifiée pour l'insertion
de multiples éléments

Voir aussi

(C++11)
construit un élément en place
(fonction membre publique)
insère un élément au début
(fonction membre publique)
ajoute un élément à la fin
(fonction membre publique)
crée un std::insert_iterator du type déduit de l'argument
(fonction template)