multiset::insert

Article
06/09/2015

Insère un élément ou une plage d'éléments dans une classe multiset.

// (1) single element pair<iterator, bool> insert(     const value_type& Val );   // (2) single element, perfect forwarded template<class ValTy> pair<iterator, bool> insert(     ValTy&& Val );  // (3) single element with hint iterator insert(     const_iterator Where,     const value_type& Val );   // (4) single element, perfect forwarded, with hint template<class ValTy> iterator insert(     const_iterator Where,     ValTy&& Val );  // (5) range  template<class InputIterator>  void insert(     InputIterator First,     InputIterator Last );   // (6) initializer list void insert(     initializer_list<value_type> IList );

Paramètres

Paramètre	Description
Val	Valeur d'un élément à insérer dans la classe multiset.
Where	Emplacement où commencer à rechercher le point d'insertion correct. (Si ce point précède immédiatement Where, l'insertion peut se produire dans le temps fixe amorti plutôt que dans le temps logarithmique.)
ValTy	Paramètre de modèle qui spécifie le type d'argument que la classe multiset peut utiliser pour construire un élément de value_type et effectue un transfert parfait de Val comme argument.
First	Position du premier élément à copier.
Last	Position juste au-delà du dernier élément à copier.
InputIterator	Argument de fonction avec modèle qui remplit les conditions requises par un itérateur d'entrée qui pointe vers des éléments d'un type pouvant servir à construire des objets value_type.
IList	initializer_list depuis laquelle copier les éléments.

Valeur de retour

Les fonctions membres d'insertion à un élément, (1) et (2), retournent un itérateur vers l'emplacement où le nouvel élément a été inséré dans la classe multiset.

Les fonctions membres à un élément avec indicateur, (3) et (4), retournent un itérateur qui pointe vers l'emplacement où le nouvel élément a été inséré dans la classe multiset.

Notes

Aucun pointeur ou référence n'est invalidé par cette fonction, mais elle peut invalider tous les itérateurs du conteneur.

Durant l'insertion d'un seul élément, si une exception est levée, l'état du conteneur n'est pas modifié. Durant l'insertion de plusieurs éléments, si une exception est levée, le conteneur reste dans un état non spécifié mais valide.

La value_type d'un conteneur est un typedef qui appartient au conteneur et, pour la classe set, multiset<V>::value_type est de type const V.

La fonction membre de plage (5) insère la séquence de valeurs d'éléments dans une classe multiset qui correspond à chaque élément traité par un itérateur dans la plage [First, Last) ; ainsi, Last n'est pas inséré. La fonction membre de conteneur end() fait référence à la position qui suit le dernier élément du conteneur. Par exemple, l'instruction s.insert(v.begin(), v.end()); insère tous les éléments de v dans s.

La fonction membre de liste d'initialiseurs (6) utilise une initializer_list pour copier des éléments dans la classe multiset.

Pour plus d'informations sur l'insertion d'un élément construit sur place (autrement dit, aucune opération de copie ni de déplacement n'est effectuée), voir multiset::emplace et multiset::emplace_hint.

Exemple

// multiset_insert.cpp
// compile with: /EHsc
#include <set>
#include <iostream>
#include <string>
#include <vector>

using namespace std;

template <typename S> void print(const S& s) {
    cout << s.size() << " elements: ";

    for (const auto& p : s) {
        cout << "(" << p << ") ";
    }

    cout << endl;
}

int main()
{

    // insert single values 
    multiset<int> s1;
    // call insert(const value_type&) version
    s1.insert({ 1, 10 });
    // call insert(ValTy&&) version 
    s1.insert(20);

    cout << "The original multiset values of s1 are:" << endl;
    print(s1);

    // intentionally attempt a duplicate, single element
    s1.insert(1);
    cout << "The modified multiset values of s1 are:" << endl;
    print(s1);
    cout << endl;

    // single element, with hint
    s1.insert(s1.end(), 30);
    cout << "The modified multiset values of s1 are:" << endl;
    print(s1);
    cout << endl;


    // The templatized version inserting a jumbled range
    multiset<int> s2;
    vector<int> v;
    v.push_back(43);
    v.push_back(294);
    v.push_back(41);
    v.push_back(330);
    v.push_back(42);
    v.push_back(45);

    cout << "Inserting the following vector data into s2:" << endl;
    print(v);

    s2.insert(v.begin(), v.end());

    cout << "The modified multiset values of s2 are:" << endl;
    print(s2);
    cout << endl;

    // The templatized versions move-constructing elements
    multiset<string>  s3;
    string str1("blue"), str2("green");

    // single element
    s3.insert(move(str1));
    cout << "After the first move insertion, s3 contains:" << endl;
    print(s3);

    // single element with hint
    s3.insert(s3.end(), move(str2));
    cout << "After the second move insertion, s3 contains:" << endl;
    print(s3);
    cout << endl;

    multiset<int> s4;
    // Insert the elements from an initializer_list
    s4.insert({ 4, 44, 2, 22, 3, 33, 1, 11, 5, 55 });
    cout << "After initializer_list insertion, s4 contains:" << endl;
    print(s4);
    cout << endl;
}

Sortie

The original multiset values of s1 are:
3 elements: (1) (10) (20)
The modified multiset values of s1 are:
4 elements: (1) (1) (10) (20)

The modified multiset values of s1 are:
5 elements: (1) (1) (10) (20) (30)

Inserting the following vector data into s2:
6 elements: (43) (294) (41) (330) (42) (45)
The modified multiset values of s2 are:
6 elements: (41) (42) (43) (45) (294) (330)

After the first move insertion, s3 contains:
1 elements: (blue)
After the second move insertion, s3 contains:
2 elements: (blue) (green)

After initializer_list insertion, s4 contains:
10 elements: (1) (2) (3) (4) (5) (11) (22) (33) (44) (55)