Namespaces
Variants

std::map<Key,T,Compare,Allocator>:: insert

From cppreference.net
std:: pair < iterator, bool > insert ( const value_type & value ) ;
(1)
template < class P >
std:: pair < iterator, bool > insert ( P && value ) ;
(2) (depuis C++11)
std:: pair < iterator, bool > insert ( value_type && value ) ;
(3) (depuis C++17)
(4)
iterator insert ( iterator pos, const value_type & value ) ;
(jusqu'à C++11)
iterator insert ( const_iterator pos, const value_type & value ) ;
(depuis C++11)
template < class P >
iterator insert ( const_iterator pos, P && value ) ;
(5) (depuis C++11)
iterator insert ( const_iterator pos, value_type && value ) ;
(6) (depuis C++17)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(7)
void insert ( std:: initializer_list < value_type > ilist ) ;
(8) (depuis C++11)
insert_return_type insert ( node_type && nh ) ;
(9) (depuis C++17)
iterator insert ( const_iterator pos, node_type && nh ) ;
(10) (depuis C++17)

Insère un ou plusieurs éléments dans le conteneur, si celui-ci ne contient pas déjà un élément avec une clé équivalente.

1-3) Insère value .
La surcharge (2) est équivalente à emplace ( std:: forward < P > ( value ) ) et ne participe à la résolution de surcharge que si std:: is_constructible < value_type, P && > :: value == true .
4-6) Insère value à la position la plus proche possible de la position juste avant pos .
La surcharge (5) est équivalente à emplace_hint ( pos, std:: forward < P > ( value ) ) et ne participe à la résolution de surcharge que si std:: is_constructible < value_type, P && > :: value == true .
7) Insère les éléments de la plage [ first , last ) . Si plusieurs éléments dans la plage ont des clés qui sont équivalentes, il n'est pas spécifié quel élément est inséré (en attente de LWG2844 ).
8) Insère les éléments de la liste d'initialisation ilist . Si plusieurs éléments dans la plage ont des clés qui sont équivalentes, il n'est pas spécifié quel élément est inséré (en attente de LWG2844 ).
9) Si nh est un node handle vide, ne fait rien. Sinon, insère l'élément possédé par nh dans le conteneur, si le conteneur ne contient pas déjà un élément avec une clé équivalente à nh. key ( ) . Le comportement est indéfini si nh n'est pas vide et get_allocator ( ) ! = nh. get_allocator ( ) .
10) Si nh est un node handle vide, ne fait rien et retourne l'itérateur de fin. Sinon, insère l'élément possédé par nh dans le conteneur, si le conteneur ne contient pas déjà un élément avec une clé équivalente à nh. key ( ) , et retourne l'itérateur pointant vers l'élément avec une clé équivalente à nh. key ( ) (que l'insertion ait réussi ou échoué). Si l'insertion réussit, nh est déplacé, sinon il conserve la possession de l'élément. L'élément est inséré aussi près que possible de la position juste avant pos . Le comportement est indéfini si nh n'est pas vide et get_allocator ( ) ! = nh. get_allocator ( ) .

Aucun itérateur ou référence n'est invalidé. Si l'insertion réussit, les pointeurs et références vers l'élément obtenus pendant qu'il est détenu dans le node handle sont invalidés, et les pointeurs et références obtenus vers cet élément avant son extraction redeviennent valides. (depuis C++17)

Table des matières

Paramètres

pos - itérateur vers la position avant laquelle le nouvel élément sera inséré
value - valeur de l'élément à insérer
first, last - la paire d'itérateurs définissant la plage des éléments à insérer
ilist - liste d'initialisation depuis laquelle insérer les valeurs
nh - un gestionnaire de nœud compatible
Exigences de type
-
InputIt doit satisfaire aux exigences de LegacyInputIterator .

Valeur de retour

1-3) Une paire constituée d'un itérateur vers l'élément inséré (ou vers l'élément qui a empêché l'insertion) et une valeur bool définie à true si et seulement si l'insertion a eu lieu.
4-6) Un itérateur vers l'élément inséré, ou vers l'élément qui a empêché l'insertion.
7,8) (aucun)
9) Un objet de insert_return_type avec les membres initialisés comme suit :
  • Si nh est vide, inserted est false , position est end ( ) , et node est vide.
  • Sinon, si l'insertion a eu lieu, inserted est true , position pointe vers l'élément inséré, et node est vide.
  • Si l'insertion a échoué, inserted est false , node a la valeur précédente de nh , et position pointe vers un élément avec une clé équivalente à nh. key ( ) .
10) Itérateur de fin si nh était vide, itérateur pointant vers l'élément inséré si l'insertion a eu lieu, et itérateur pointant vers un élément avec une clé équivalente à nh. key ( ) si elle a échoué.

Exceptions

1-6) Si une exception est levée par une opération quelconque, l'insertion n'a aucun effet.

Complexité

1-3) Logarithmique par rapport à la taille du conteneur, O(log(size())) .
4-6) Amorti constant si l'insertion se produit à la position juste après (until C++11) avant (since C++11) pos , logarithmique dans la taille du conteneur sinon.
7,8) O(N·log(size() + N)) , où N est le nombre d'éléments à insérer.
9) Logarithmique par rapport à la taille du conteneur, O(log(size())) .
10) Amorti constant si l'insertion se produit à la position juste avant pos , logarithmique dans la taille du conteneur sinon.

Notes

L'insertion avec indice ( ( 4-6 ) et ( 10 ) ) ne retourne pas un booléen afin d'être compatible en signature avec l'insertion positionnelle sur les conteneurs séquentiels, tels que std::vector::insert . Cela permet de créer des inserters génériques tels que std::inserter . Une manière de vérifier le succès d'une insertion avec indice est de comparer size() avant et après.

Exemple

#include <iomanip>
#include <iostream>
#include <map>
#include <string>
using namespace std::literals;
template<typename It>
void print_insertion_status(It it, bool success)
{
    std::cout << "Insertion de " << it->first
              << (success ? " a réussi\n" : " échec\n");
}
int main()
{
    std::map<std::string, float> heights;
    // Surcharge 3 : insertion à partir d'une référence rvalue
    const auto [it_hinata, success] = heights.insert({"Hinata"s, 162.8});
    print_insertion_status(it_hinata, success);
    {
        // Surcharge 1 : insertion à partir d'une référence lvalue
        const auto [it, success2] = heights.insert(*it_hinata);
        print_insertion_status(it, success2);
    }
    {
        // Surcharge 2 : insertion via transmission à emplace
        const auto [it, success] = heights.insert(std::pair{"Kageyama", 180.6});
        print_insertion_status(it, success);
    }
    {
        // Surcharge 6 : insertion à partir d'une référence rvalue avec indice de position
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, {"Azumane"s, 184.7});
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // Surcharge 4 : insertion à partir d'une référence lvalue avec indice de position
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, *it_hinata);
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // Surcharge 5 : insertion via délégation à emplace avec indice positionnel
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, std::pair{"Tsukishima", 188.3});
        print_insertion_status(it, std::size(heights) != n);
    }
    auto node_hinata = heights.extract(it_hinata);
    std::map<std::string, float> heights2;
    // Surcharge 7 : insertion à partir d'une plage d'itérateurs
    heights2.insert(std::begin(heights), std::end(heights));
    // Surcharge 8 : insertion depuis initializer_list
    heights2.insert({{"Kozume"s, 169.2}, {"Kuroo", 187.7}});
    // Surcharge 9 : insérer un nœud
    const auto status = heights2.insert(std::move(node_hinata));
    print_insertion_status(status.position, status.inséré);
    node_hinata = heights2.extract(status.position);
    {
        // Surcharge 10 : insertion de nœud avec indice positionnel
        const std::size_t n = std::size(heights2);
        const auto it = heights2.insert(std::begin(heights2), std::move(node_hinata));
        print_insertion_status(it, std::size(heights2) != n);
    }
    // Afficher la carte résultante
    std::cout << std::left << '\n';
    for (const auto& [name, height] : heights2)
        std::cout << std::setw(10) << name << " | " << height << "cm\n";
}

Sortie :

Insertion de Hinata réussie
Insertion de Hinata échouée
Insertion de Kageyama réussie
Insertion de Azumane réussie
Insertion de Hinata échouée
Insertion de Tsukishima réussie
Insertion de Hinata réussie
Insertion de Hinata réussie
Azumane    | 184.7cm
Hinata     | 162.8cm
Kageyama   | 180.6cm
Kozume     | 169.2cm
Kuroo      | 187.7cm
Tsukishima | 188.3cm

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 233 C++98 pos n'était qu'une indication, pouvant être totalement ignorée l'insertion doit être
aussi proche que possible
de la position juste avant pos
LWG 264 C++98 la complexité de la surcharge ( 7 ) devait être linéaire si
l'intervalle [ first , last ) est trié selon Compare
supprimé l'exigence linéaire
dans ce cas particulier
LWG 316 C++98 dans la valeur de retour de la surcharge ( 1 ) , il n'était pas spécifié
quelle valeur bool indique une insertion réussie
le succès est
indiqué par true
LWG 2005 C++11 les surcharges ( 2 ) et ( 5 ) étaient mal décrites description améliorée

Voir aussi

(C++11)
construit un élément en place
(fonction membre publique)
construit des éléments en place en utilisant un indice
(fonction membre publique)
insère un élément ou assigne à l'élément actuel si la clé existe déjà
(fonction membre publique)
crée un std::insert_iterator du type déduit de l'argument
(modèle de fonction)