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 seit C++26)
std:: pair < iterator, bool > insert ( value_type && value ) ;
(2) (seit C++11)
(constexpr seit C++26)
(3)
iterator insert ( iterator pos, const value_type & value ) ;
(bis C++11)
iterator insert ( const_iterator pos, const value_type & value ) ;
(seit C++11)
(constexpr seit C++26)
iterator insert ( const_iterator pos, value_type && value ) ;
(4) (seit C++11)
(constexpr seit C++26)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(5) (constexpr seit C++26)
void insert ( std:: initializer_list < value_type > ilist ) ;
(6) (seit C++11)
(constexpr seit C++26)
insert_return_type insert ( node_type && nh ) ;
(7) (seit C++17)
(constexpr seit C++26)
iterator insert ( const_iterator pos, node_type && nh ) ;
(8) (seit C++17)
(constexpr seit C++26)
template < class K >
std:: pair < iterator, bool > insert ( K && x ) ;
(9) (seit C++23)
(constexpr seit C++26)
template < class K >
iterator insert ( const_iterator pos, K && x ) ;
(10) (seit C++23)
(constexpr seit C++26)

Versucht, Element(e) in * this einzufügen.

  • Wenn * this bereits ein Element mit einem äquivalenten Schlüssel enthält, erfolgt keine Aktion.
  • Andernfalls werden die Element(e) in * this eingefügt.
1-4) Fügt value ein. Falls pos angegeben ist, wird value so nah wie möglich an der Position direkt vor pos eingefügt.
1,3) Falls value_type nicht CopyInsertable in set ist, ist das Verhalten undefiniert.
2,4) Falls value_type nicht MoveInsertable in set ist, ist das Verhalten undefiniert.
(seit C++11)
5) Fügt Elemente aus dem Bereich [ first , last ) ein.
Wenn eine der folgenden Bedingungen erfüllt ist, ist das Verhalten undefiniert:
(seit C++11)
  • first oder last ist ein Iterator in * this .
6) Fügt Elemente aus der Initialisierungsliste ilist ein.
Entspricht insert ( ilist. begin ( ) , ilist. end ( ) ) .
7) Wenn nh ein leerer node handle ist, tut nichts. Andernfalls fügt das Element, das von nh besessen wird, in den Container ein, falls der Container noch kein Element mit einem Schlüssel enthält, der äquivalent zu nh. key ( ) ist. Das Verhalten ist undefiniert, wenn nh nicht leer ist und get_allocator ( ) ! = nh. get_allocator ( ) .
8) Wenn nh ein leerer node handle ist, tut nichts und gibt den End-Iterator zurück. Andernfalls fügt das Element, das von nh besessen wird, in den Container ein, falls der Container noch kein Element mit einem Schlüssel enthält, der äquivalent zu nh. key ( ) ist, und gibt den Iterator zurück, der auf das Element mit dem Schlüssel zeigt, der äquivalent zu nh. key ( ) ist (unabhängig davon, ob das Einfügen erfolgreich war oder fehlgeschlagen ist). Wenn das Einfügen erfolgreich ist, wird nh verschoben, andernfalls behält es das Eigentum am Element. Das Element wird so nah wie möglich an der Position direkt vor pos eingefügt. Das Verhalten ist undefiniert, wenn nh nicht leer ist und get_allocator ( ) ! = nh. get_allocator ( ) .
9,10) Konstruiert ein Objekt u vom Typ value_type mit std:: forward < K > ( x ) und fügt dann u in * this ein. Die Existenz eines äquivalenten Schlüssels wird transparent unter Verwendung von x bestimmt, bevor u konstruiert wird.
Wenn eine der folgenden Bedingungen erfüllt ist, ist das Verhalten undefiniert:
9) Diese Überladung nimmt nur dann an der Überladungsauflösung teil, wenn Compare transparent ist.
10) u wird so nah wie möglich an der Position unmittelbar vor pos eingefügt.
Diese Überladung nimmt nur dann an der Überladungsauflösung teil, wenn alle folgenden Bedingungen erfüllt sind:

Keine Iteratoren oder Referenzen werden ungültig. Wenn die Einfügung erfolgreich ist, werden Zeiger und Referenzen auf das Element, die während es im Node-Handle gehalten wurde, ungültig, und Zeiger und Referenzen, die vor dem Extrahieren auf dieses Element erhalten wurden, werden gültig. (seit C++17)

Inhaltsverzeichnis

Parameter

pos - Iterator auf die Position, vor der das neue Element eingefügt wird
value - Einzufügender Elementwert
first, last - Das Iteratorpaar, das den Quell- Bereich der einzufügenden Elemente definiert
ilist - Initialisierungsliste, aus der die Werte eingefügt werden
nh - Ein kompatibles Node Handle
x - Ein Wert beliebigen Typs, der transparent mit einem Schlüssel verglichen werden kann
Typanforderungen
-
InputIt muss die Anforderungen von LegacyInputIterator erfüllen.

Rückgabewert

1,2) Ein Paar bestehend aus einem Iterator zum eingefügten Element (oder zum Element, das die Einfügung verhindert hat) und einem bool -Wert, der auf true gesetzt ist, genau dann wenn die Einfügung stattgefunden hat.
3,4) Ein Iterator zum eingefügten Element oder zum Element, das die Einfügung verhindert hat.
7) Ein Objekt vom Typ insert_return_type mit den wie folgt initialisierten Mitgliedern:
  • Wenn nh leer ist, ist inserted false , position ist end ( ) , und node ist leer.
  • Andernfalls, wenn die Einfügung stattgefunden hat, ist inserted true , position zeigt auf das eingefügte Element, und node ist leer.
  • Wenn die Einfügung fehlgeschlagen ist, ist inserted false , node hat den vorherigen Wert von nh , und position zeigt auf ein Element mit einem Schlüssel, der äquivalent zu nh. key ( ) ist.
8) End-Iterator, wenn nh leer war, Iterator, der auf das eingefügte Element zeigt, wenn die Einfügung stattgefunden hat, und Iterator, der auf ein Element mit einem Schlüssel zeigt, der äquivalent zu nh. key ( ) ist, wenn es fehlgeschlagen ist.
9) Ein Paar bestehend aus einem Iterator zum eingefügten Element (oder zum Element, das die Einfügung verhindert hat) und einem bool -Wert, der auf true gesetzt ist, genau dann wenn die Einfügung stattgefunden hat.
10) Ein Iterator zum eingefügten Element oder zum Element, das die Einfügung verhindert hat.

Exceptions

Wenn eine Ausnahme von einer beliebigen Operation während des Einfügens eines einzelnen Elements ausgelöst wird, hat der Einfügevorgang keine Auswirkung.

Komplexität

Gegeben N als size ( ) :

1,2) log(N)
3,4) Amortisiert konstant, wenn die Einfügung an der Position direkt nach (until C++11) vor (since C++11) pos erfolgt, log(N) andernfalls.
5,6) log(N+M) , wobei M die Anzahl der einzufügenden Elemente ist.
7) log(N)
8) Amortisiert konstant, wenn die Einfügung an der Position unmittelbar vor pos erfolgt, log(N) andernfalls.
9) log(N)
10) Amortisiert konstant, wenn die Einfügung an der Position unmittelbar vor pos erfolgt, log(N) andernfalls.

Hinweise

Das angehinte Einfügen ( ( 3,4 ) , ( 8 ) und ( 10 ) ) gibt kein Boolean zurück, um signaturkompatibel mit positionellem Einfügen bei sequentiellen Containern wie std::vector::insert zu sein. Dies ermöglicht die Erstellung generischer Inserter wie std::inserter . Eine Möglichkeit, den Erfolg eines angehinten Einfügens zu überprüfen, ist der Vergleich von size() vor und nach dem Vorgang.

Die Überladungen ( 5,6 ) werden häufig als Schleife implementiert, die die Überladung ( 3 ) mit end() als Hinweis aufruft; sie sind für das Anhängen einer sortierten Sequenz (wie beispielsweise eines anderen std::set ) optimiert, deren kleinstes Element größer ist als das letzte Element in * this .

Wenn mehrere Elemente im Bereich Schlüssel haben, die äquivalent verglichen werden, ist nicht spezifiziert, welches Element eingefügt wird (ausstehend LWG2844 ).

Feature-Test Makro Wert Std Feature
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) Heterogene Überladungen für die verbleibenden Memberfunktionen in geordneten und ungeordneten assoziativen Containern. ( 9,10 )

Beispiel

Diesen Code ausführen 
#include <cassert>
#include <iostream>
#include <set>
int main()
{
    std::set<int> set;
    auto result_1 = set.insert(3);
    assert(result_1.first != set.end()); // es ist ein gültiger Iterator
    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); // gleicher Iterator
    assert(*result_2.first == 3);
    if (!result_2.second)
        std::cout << "no insertion\n";
}

Ausgabe: 

insert done
no insertion

Fehlerberichte

Die folgenden verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR Angewendet auf Verhalten wie veröffentlicht Korrektes Verhalten
LWG 233 C++98 pos war nur ein Hinweis, konnte komplett ignoriert werden Die Einfügung muss so nah wie möglich
an der Position direkt vor pos erfolgen
LWG 264 C++98 Die Komplexität der Überladung ( 5 ) musste linear sein, wenn
der Bereich [ first , last ) gemäß Compare sortiert ist 		Die lineare Anforderung wurde
für diesen Spezialfall entfernt
LWG 316 C++98 Beim Rückgabewert der Überladung ( 1 ) war nicht spezifiziert,
welcher bool -Wert eine erfolgreiche Einfügung anzeigt 		Erfolg wird durch true angezeigt

Siehe auch

(C++11)
Konstruiert Element direkt an Ort und Stelle
(öffentliche Elementfunktion)
(C++11)
Konstruiert Elemente direkt an Ort und Stelle mit Hinweis
(öffentliche Elementfunktion)
Erstellt einen std::insert_iterator vom aus dem Argument abgeleiteten Typ
(Funktionstemplate)