map::insert

Article
06/09/2015

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

// (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 map sauf si elle contient déjà un élément dont la clé est classée de manière équivalente.
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 map 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 à un élément, (1) et (2), retournent une paire dont le composant bool a la valeur true si une insertion a été effectuée, et false si la classe map contenait déjà un élément dont la clé avait une valeur équivalente dans le classement. Le composant itérateur de la paire de valeurs de retour pointe sur l'élément nouvellement inséré si le composant bool a la valeur true ou sur l'élément existant si le composant bool a la valeur false.

Les fonctions membres à un élément avec indicateur, (3) et (4), retournent un itérateur qui pointe sur la position où le nouvel élément a été inséré dans la classe map ou, si un élément avec une clé équivalente existe déjà, sur l'élément existant.

Notes

Aucun itérateur, pointeur ou référence n'est invalidé par cette fonction.

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.

Pour accéder au composant itérateur d'une pair pr qui est retournée par les fonctions membres à un élément, utilisez pr.first ; pour déréférencer l'itérateur dans la paire retournée, utilisez *pr.first, qui vous donne un élément. Pour accéder au composant bool, utilisez pr.second. Pour obtenir un exemple, voir l'exemple de code plus loin dans cet article.

La value_type d'un conteneur est un typedef qui appartient au conteneur et, pour la classe map, map<K, V>::value_type est pair<const K, V>. La valeur d'un élément est une paire ordonnée dans laquelle le premier composant est égal à la valeur de clé et le second composant est égal à la valeur de données de l'élément.

La fonction membre de plage (5) insère la séquence de valeurs d'éléments dans une classe map 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 m.insert(v.begin(), v.end()); tente d'insérer tous les éléments de v dans m. Seuls les éléments qui ont des valeurs uniques dans la plage sont insérés. Les doublons sont ignorés. Pour savoir quels éléments sont rejetés, utilisez les versions à un élément de insert.

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

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 map::emplace et map::emplace_hint.

Exemple

// map_insert.cpp
// compile with: /EHsc
#include <map>
#include <iostream>
#include <string>
#include <vector>
#include <utility>  // make_pair()

using namespace std;

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

    for (const auto& p : m) {
        cout << "(" << p.first << ", " << p.second << ") ";
    }

    cout << endl;
}

int main()
{

    // insert single values 
    map<int, int> m1;
    // call insert(const value_type&) version
    m1.insert({ 1, 10 });
    // call insert(ValTy&&) version 
    m1.insert(make_pair(2, 20));

    cout << "The original key and mapped values of m1 are:" << endl;
    print(m1);

    // intentionally attempt a duplicate, single element
    auto ret = m1.insert(make_pair(1, 111));
    if (!ret.second){
        auto pr = *ret.first;
        cout << "Insert failed, element with key value 1 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
    }
    else{
        cout << "The modified key and mapped values of m1 are:" << endl;
        print(m1);
    }
    cout << endl;

    // single element, with hint
    m1.insert(m1.end(), make_pair(3, 30));
    cout << "The modified key and mapped values of m1 are:" << endl;
    print(m1);
    cout << endl;


    // The templatized version inserting a jumbled range
    map<int, int> m2;
    vector<pair<int, int>> v;
    v.push_back(make_pair(43, 294));
    v.push_back(make_pair(41, 262));
    v.push_back(make_pair(45, 330));
    v.push_back(make_pair(42, 277));
    v.push_back(make_pair(44, 311));

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

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

    cout << "The modified key and mapped values of m2 are:" << endl;
    print(m2);
    cout << endl;

    // The templatized versions move-constructing elements
    map<int, string>  m3;
    pair<int, string> ip1(475, "blue"), ip2(510, "green");

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

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

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

Sortie

The original key and mapped values of m1 are:
2 elements: (1, 10) (2, 20)
Insert failed, element with key value 1 already exists.
  The existing element is (1, 10)

The modified key and mapped values of m1 are:
3 elements: (1, 10) (2, 20) (3, 30)

Inserting the following vector data into m2:
5 elements: (43, 294) (41, 262) (45, 330) (42, 277) (44, 311)
The modified key and mapped values of m2 are:
5 elements: (41, 262) (42, 277) (43, 294) (44, 311) (45, 330)

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

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