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

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'à 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 pointant vers * this .
5) Insère les éléments de la liste d'initialisation ilist avant pos .
Équivalent à insert ( pos, ilist. begin ( ) , ilist. end ( ) ) .


Si après l'opération la nouvelle size() est supérieure à l'ancienne capacity() , une réallocation a lieu, auquel cas tous les itérateurs (y compris l'itérateur end() ) et toutes les références aux éléments sont invalidés. Sinon, seuls les itérateurs et références avant le point d'insertion restent valides.

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é

Si une réallocation se produit, linéaire dans le nombre d'éléments du vector après l'insertion ; sinon, linéaire dans le nombre d'éléments insérés plus 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)
  • tout InputIt opération,

ces fonctions n'ont aucun effet ( strong exception safety guarantee ).

Si une exception est levée lors de l'insertion d'un seul élément à la fin, et que T est CopyInsertable dans * this ou que std:: is_nothrow_move_constructible < T > :: value est true , cette fonction n'a aucun effet (garantie d'exception forte). Sinon, si une exception est levée par le constructeur par déplacement d'un T non- CopyInsertable , les effets sont non spécifiés.

(depuis C++11)

Exemple

Exécuter ce code 
#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); // surcharge (1)
    stq::println("2. {}", c1);
    c1.insert(pos, 2, 300); // surcharge (3)
    stq::println("3. {}", c1);
    // pos n'est plus valide, obtenir un nouveau :
    pos = c1.begin();
    std::vector<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 publié Comportement corrigé
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 la surcharge ( 3 ) spécifiée pour toutes les surcharges
LWG 406 C++98 la garantie forte d'exception s'appliquait également si
l'exception est levée par une opération InputIt 		aucune garantie dans ce cas

Voir aussi

(C++11)
construit un élément en place
(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
(fonction template)