Namespaces
Variants

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

From cppreference.net

C++
Containers library
std::list
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 T n'est pas CopyInsertable dans list , le comportement est indéfini.

(depuis C++11)
2) Insère value avant pos , en utilisant potentiellement la sémantique de déplacement.
Si T n'est pas MoveInsertable dans list , 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'à 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 ( ) ) .


Aucun itérateur ou référence n'est invalidé.

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 de

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.

Exceptions

Si une exception est levée pour quelque raison que ce soit, ces fonctions n'ont aucun effet ( strong exception safety guarantee ).

Exemple

Exécuter ce code 
#include <iostream>
#include <iterator>
#include <string_view>
#include <list>
namespace stq
{
    void println(std::string_view rem, const std::list<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::list<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::list<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 Applicable à Comportement publié Comportement corrigé
LWG 149 C++98 les surcharges ( 3 ) et ( 4 ) ne retournaient rien retourne un itérateur

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 dont le type est déduit de l'argument
(modèle de fonction)