Namespaces
Variants

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

From cppreference.net
C++
Containers library
std::multimap
Member functions
Non-member functions
Deduction guides (C++17)
iterator insert ( const value_type & value ) ;
(1)
iterator insert ( value_type && value ) ;
(2) (depuis C++17)
template < class P >
iterator insert ( P && value ) ;
(3) (depuis C++11)
(4)
iterator insert ( iterator pos, const value_type & value ) ;
(jusqu'à C++11)
iterator insert ( const_iterator pos, const value_type & value ) ;
(depuis C++11)
iterator insert ( const_iterator pos, value_type && value ) ;
(5) (depuis C++17)
template < class P >
iterator insert ( const_iterator pos, P && value ) ;
(6) (depuis C++11)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(7)
void insert ( std:: initializer_list < value_type > ilist ) ;
(8) (depuis C++11)
iterator 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.

1-3) Insère value . Si le conteneur a des éléments avec une clé équivalente, insère à la limite supérieure de cette plage.
La surcharge (3) 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 aussi proche que possible de la position juste avant pos .
La surcharge (6) est équivalente à emplace_hint ( hint, 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 ) .
8) Insère des éléments depuis la liste d'initialisation ilist .
9) Si nh est un node handle vide, ne fait rien. Sinon, insère l'élément possédé par nh dans le conteneur et retourne un itérateur pointant vers l'élément inséré. Si une plage contenant des éléments avec des clés équivalentes à nh. key ( ) existe dans le conteneur, l'élément est inséré à la fin de cette plage. 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, et retourne l'itérateur pointant vers l'élément avec une clé équivalente à nh. key ( ) . 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 ni 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 source des éléments à insérer
ilist - liste d'initialisation depuis laquelle insérer les valeurs
nh - un node handle compatible
Exigences de type
-
InputIt doit satisfaire aux exigences de LegacyInputIterator .

Valeur de retour

1-6) Un itérateur vers l'élément inséré.
7,8) (aucun)
9,10) Itérateur de fin si nh était vide, itérateur pointant vers l'élément inséré sinon.

Exceptions

1-6) Si une exception est levée par une opération quelconque, l'insertion n'a aucun effet.
7,8) Aucune garantie de sûreté face aux exceptions.
9,10) Si une exception est levée par une opération quelconque, l'insertion n'a aucun effet.

Complexité

1-3) O(log(size()))
4-6) Amorti constant si l'insertion se produit à la position juste avant pos , O(log(size())) sinon.
7,8) O(N·log(size() + N)) , où N est le nombre d'éléments à insérer.
9) O(log(size()))
10) Amorti constant si l'insertion se produit à la position juste avant pos , O(log(size())) sinon.

Exemple

Exécuter ce code 
#include <functional>
#include <iostream>
#include <map>
#include <string>
#include <string_view>
#include <utility>
template<class M>
void print(const std::string_view rem, const M& mmap)
{
    std::cout << rem << ' ';
    for (const auto& e : mmap)
        std::cout << '{' << e.first << ',' << e.second << "} ";
    std::cout << '\n';
}
int main()
{
    // initialisation par liste
    std::multimap<int, std::string, std::greater<int>> mmap
        {{2, "foo"}, {2, "bar"}, {3, "baz"}, {1, "abc"}, {5, "def"}};
    print("#1", mmap);
    // insertion en utilisant value_type
    mmap.insert(decltype(mmap)::value_type(5, "pqr"));
    print("#2", mmap);
    // insertion en utilisant pair
    mmap.insert(std::pair{6, "uvw"});
    print("#3", mmap);
    mmap.insert({7, "xyz"});
    print("#4", mmap);
    // insertion en utilisant initializer_list
    mmap.insert({{5, "one"}, {5, "two"}});
    print("#5", mmap);
    // insertion en utilisant une paire d'itérateurs
    mmap.clear();
    const auto il = {std::pair{1, "ä"}, {2, "ё"}, {2, "ö"}, {3, "ü"}};
    mmap.insert(il.begin(), il.end());
    print("#6", mmap);
}

Sortie : 

#1 {5,def} {3,baz} {2,foo} {2,bar} {1,abc}
#2 {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#3 {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#4 {7,xyz} {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#5 {7,xyz} {6,uvw} {5,def} {5,pqr} {5,one} {5,two} {3,baz} {2,foo} {2,bar} {1,abc}
#6 {3,ü} {2,ё} {2,ö} {1,ä}

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 tel que publié Comportement correct
LWG 233 C++98 pos n'était qu'une indication, elle pouvait ê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 (5) devait être linéaire si
la plage [ first , last ) est triée selon Compare 		supprimé l'exigence de linéarité
dans ce cas particulier
LWG 371 C++98 l'ordre des éléments équivalents
n'était pas garanti d'être préservé 		doit être préservé
LWG 2005 C++11 les surcharges (3,6) étaient mal décrites amélioré la description

Voir aussi

(C++11)
construit un élément en place
(fonction membre publique)
(C++11)
construit des éléments en place en utilisant un indice
(fonction membre publique)
crée un std::insert_iterator dont le type est déduit de l'argument
(modèle de fonction)