Namespaces
Variants

std::set<Key,Compare,Allocator>:: insert

From cppreference.net
C++
Containers library
std::set
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
std:: pair < iterator, bool > insert ( const value_type & value ) ;
(1) (constexpr depuis C++26)
std:: pair < iterator, bool > insert ( value_type && value ) ;
(2) (depuis C++11)
(constexpr depuis C++26)
(3)
iterator insert ( iterator pos, const value_type & value ) ;
(jusqu'à C++11)
iterator insert ( const_iterator pos, const value_type & value ) ;
(depuis C++11)
(constexpr depuis C++26)
iterator insert ( const_iterator pos, value_type && value ) ;
(4) (depuis C++11)
(constexpr depuis C++26)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(5) (constexpr depuis C++26)
void insert ( std:: initializer_list < value_type > ilist ) ;
(6) (depuis C++11)
(constexpr depuis C++26)
insert_return_type insert ( node_type && nh ) ;
(7) (depuis C++17)
(constexpr depuis C++26)
iterator insert ( const_iterator pos, node_type && nh ) ;
(8) (depuis C++17)
(constexpr depuis C++26)
template < class K >
std:: pair < iterator, bool > insert ( K && x ) ;
(9) (depuis C++23)
(constexpr depuis C++26)
template < class K >
iterator insert ( const_iterator pos, K && x ) ;
(10) (depuis C++23)
(constexpr depuis C++26)

Tente d'insérer un ou plusieurs éléments dans * this .

  • Si * this contient déjà un élément avec une clé équivalente, ne fait rien.
  • Sinon, insère l'élément (ou les éléments) dans * this .
1-4) Insère value . Si pos est fourni, value sera inséré aussi près que possible de la position juste avant pos .
1,3) Si value_type n'est pas CopyInsertable dans set , le comportement est indéfini.
2,4) Si value_type n'est pas MoveInsertable dans set , le comportement est indéfini.
(depuis C++11)
5) Insère les éléments de la plage [ first , last ) .
Si l'une des conditions suivantes est satisfaite, le comportement est indéfini :
(depuis C++11)
  • first ou last est un itérateur pointant vers * this .
6) Insère des éléments à partir d'une liste d'initialisation ilist .
Équivalent à insert ( ilist. begin ( ) , ilist. end ( ) ) .
7) 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 ( ) .
8) 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 ( ) .
9,10) Construit un objet u de type value_type avec std:: forward < K > ( x ) puis insère u dans * this . L'existence d'une clé équivalente est déterminée de manière transparente en utilisant x avant la construction de u .
Si l'une des conditions suivantes est satisfaite, le comportement est indéfini :
9) Cette surcharge participe à la résolution de surcharge uniquement si Compare est transparent .
10) u sera inséré aussi près que possible de la position juste avant pos .
Cette surcharge participe à la résolution de surcharge seulement si toutes les conditions suivantes sont satisfaites :

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 gestionnaire de nœud compatible
x - une valeur de tout type pouvant être comparée de manière transparente avec une clé
Exigences de type
-
InputIt doit satisfaire aux exigences de LegacyInputIterator .

Valeur de retour

1,2) 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.
3,4) Un itérateur vers l'élément inséré, ou vers l'élément qui a empêché l'insertion.
7) Un objet de type insert_return_type avec les membres initialisés comme suit :
  • Si nh est vide, inserted vaut false , position est end ( ) , et node est vide.
  • Sinon, si l'insertion a eu lieu, inserted vaut true , position pointe vers l'élément inséré, et node est vide.
  • Si l'insertion a échoué, inserted vaut false , node conserve la valeur précédente de nh , et position pointe vers un élément avec une clé équivalente à nh. key ( ) .
8) 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é.
9) 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 d'une bool valeur définie à true si et seulement si l'insertion a eu lieu.
10) Un itérateur vers l'élément inséré, ou vers l'élément qui a empêché l'insertion.

Exceptions

Si une exception est levée par une opération quelconque lors de l'insertion d'un seul élément, l'insertion n'a aucun effet.

Complexité

Étant donné N comme size ( ) :

1,2) log(N)
3,4) Amorti constant si l'insertion se produit à la position juste après (until C++11) avant (since C++11) pos , log(N) sinon.
5,6) log(N+M) , où M est le nombre d'éléments à insérer.
7) log(N)
8) Amorti constant si l'insertion se produit à la position juste avant pos , log(N) sinon.
9) log(N)
10) Amorti constant si l'insertion se produit à la position juste avant pos , log(N) sinon.

Notes

L'insertion avec indice ( ( 3,4 ) , ( 8 ) 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 comme std::inserter . Une manière de vérifier le succès d'une insertion avec indice est de comparer size() avant et après.

Les surcharges ( 5,6 ) sont souvent implémentées sous forme de boucle appelant la surcharge ( 3 ) avec end() comme indicateur de position ; elles sont optimisées pour l'ajout d'une séquence triée (comme un autre std::set ) dont le plus petit élément est supérieur au dernier élément dans * this .

Si plusieurs éléments de la plage ont des clés équivalentes, il n'est pas spécifié quel élément est inséré (en attente de LWG2844 ).

Macro de test de fonctionnalité Valeur Std Fonctionnalité
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) Surcharges hétérogènes pour les fonctions membres restantes dans les conteneurs associatifs ordonnés et les conteneurs associatifs non ordonnés . ( 9,10 )

Exemple

Exécuter ce code 
#include <cassert>
#include <iostream>
#include <set>
int main()
{
    std::set<int> set;
    auto result_1 = set.insert(3);
    assert(result_1.first != set.end()); // c'est un itérateur valide
    assert(*result_1.first == 3);
    if (result_1.second)
        std::cout << "insert done\n";
    auto result_2 = set.insert(3);
    assert(result_2.first == result_1.first); // même itérateur
    assert(*result_2.first == 3);
    if (!result_2.second)
        std::cout << "no insertion\n";
}

Sortie : 

insert done
no insertion

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 corrigé
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 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

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 du type déduit de l'argument
(fonction template)