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

 

C++

Compiler-Unterstützung

Freestanding und gehostet

Sprache

Standardbibliothek

Header der Standardbibliothek

Benannte Anforderungen

Feature-Test-Makros (C++20)

Bibliothek für Sprachunterstützung

Konzepte-Bibliothek (C++20)

Diagnostik-Bibliothek

Speicherverwaltungsbibliothek

Metaprogrammierungsbibliothek (C++11)

Allgemeine Dienstprogramme-Bibliothek

Container-Bibliothek

Iterator-Bibliothek

Ranges-Bibliothek (C++20)

Algorithmen-Bibliothek

Bibliothek für Zeichenketten

Textverarbeitungsbibliothek

Numerik-Bibliothek

Datums- und Zeitbibliothek

Ein-/Ausgabe-Bibliothek

Dateisystembibliothek (C++17)

Unterstützung für nebenläufige Programmierung (C++11)

Ausführungssteuerungsbibliothek (C++26)

Technische Spezifikationen

Symbolverzeichnis

Externe Bibliotheken

 

Container-Bibliothek

Sequenz

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

hive (C++26)

deque

forward_list (C++11)

list

Assoziativ

setzt

multiset

map

multimap

Ungeordnete assoziative

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

Adapter

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

Ansichten

span (C++20)

mdspan (C++23)

Tabellen

Iterator-Invalidierung

Mitgliedsfunktionstabelle

Nicht-Mitgliedsfunktionstabelle

 

std::set

Memberfunktionen

set::set set::~set            set::operator= set::get_allocator

Iteratoren set::beginset::cbegin (C++11) set::endset::cend (C++11) set::rbeginset::crbegin (C++11)   set::rendset::crend (C++11) Kapazität set::size set::max_size set::empty Observer set::key_comp set::value_comp Modifizierer set::clear set::erase set::swap set::extract (C++17) set::merge (C++17) set::insert set::insert_range (C++23) set::emplace (C++11) set::emplace_hint (C++11) Suche set::count set::find set::contains (C++20)    set::equal_range set::lower_bound set::upper_bound

Nicht-Member-Funktionen

operator==operator<=> (C++20) std::swap(std::set) erase_if(std::set) (C++20)   operator!=operator<operator>operator<=operator>= (bis C++20)(bis C++20)(bis C++20)(bis C++20)(bis C++20)

Deduction guides(C++17)

 

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

Fügt Element(e) in den Container ein, falls der Container noch kein Element mit einem äquivalenten Schlüssel enthält.

1,2) Fügt value ein.

3,4) Fügt value an einer Position ein, die so nah wie möglich an der Position direkt vor pos liegt.

5) Fügt Elemente aus dem Bereich [first, last) ein. Wenn mehrere Elemente im Bereich Schlüssel haben, die äquivalent vergleichbar sind, ist es nicht spezifiziert, welches Element eingefügt wird (abhängig von LWG2844).

6) Fügt Elemente aus der Initialisierungsliste ilist ein. Wenn mehrere Elemente im Bereich Schlüssel haben, die äquivalent vergleichbar sind, ist es nicht spezifiziert, welches Element eingefügt wird (abhängig von LWG2844).

7) Wenn nh ein leerer Node Handle ist, wird nichts unternommen. Andernfalls wird das von nh gehaltene Element in den Container eingefügt, 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, wird nichts unternommen und der End-Iterator zurückgegeben. Andernfalls wird das von nh gehaltene Element in den Container eingefügt, falls der Container noch kein Element mit einem Schlüssel enthält, der äquivalent zu nh.key() ist, und der Iterator zurückgegeben, der auf das Element mit einem äquivalenten Schlüssel zu nh.key() zeigt (unabhängig davon, ob die Einfügung erfolgreich war oder nicht). Wenn die Einfügung erfolgreich ist, wird nh verschoben, andernfalls behält es den Besitz des Elements. 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) Wenn *this bereits ein Element enthält, das transparent äquivalent zu x vergleichbar ist, wird nichts unternommen. Andernfalls wird ein Objekt u vom value_type mit std::forward<K>(x) konstruiert und dann u in *this eingefügt. Wenn equal_range(u) == equal_range(x) false ist, ist das Verhalten undefiniert. Der value_type muss aus std::forward<K>(x) in set EmplaceConstructible sein. Dieser Überladungsaufruf nimmt nur an der Auflösung teil, wenn der qualifizierte Bezeichner Compare::is_transparent gültig ist und einen Typ bezeichnet. Er ermöglicht das Aufrufen dieser Funktion, ohne eine Instanz von Key zu konstruieren.

10) Wenn *this bereits ein Element enthält, das transparent äquivalent zu x vergleichbar ist, wird nichts unternommen. Andernfalls wird ein Objekt u vom value_type mit std::forward<K>(x) konstruiert und dann u in *this an einer Position eingefügt, die so nah wie möglich an der Position direkt vor pos liegt. Wenn equal_range(u) == equal_range(x) false ist, ist das Verhalten undefiniert. Der value_type muss aus std::forward<K>(x) in set EmplaceConstructible sein. Dieser Überladungsaufruf nimmt nur an der Auflösung teil, wenn

• std::is_convertible_v<K&&, const_iterator> und std::is_convertible_v<K&&, iterator> beide false sind, und
• der qualifizierte Bezeichner Compare::is_transparent gültig ist und einen Typ bezeichnet,

was zusammen das Aufrufen dieser Funktion ermöglicht, ohne eine Instanz von Key zu konstruieren.

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

Parameter

pos	-	Iterator zu der Position, vor der das neue Element eingefügt wird
value	-	Elementwert, der eingefügt werden soll
first, last	-	das Iteratorenpaar, das den Quell- Bereich der einzufügenden Elemente definiert
ilist	-	Initialisierungsliste, aus der die Werte eingefügt werden sollen
nh	-	ein kompatibler Node Handle
x	-	ein Wert eines 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, das aus einem Iterator auf das eingefügte Element (oder auf das Element, das die Einfügung verhindert hat) und einem bool-Wert besteht, der auf true gesetzt ist, wenn und nur wenn die Einfügung stattgefunden hat.

3,4) Ein Iterator auf das eingefügte Element oder auf das Element, das die Einfügung verhindert hat.

5,6) (keine)

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 sie fehlgeschlagen ist.

9) Ein Paar, das aus einem Iterator auf das eingefügte Element (oder auf das Element, das die Einfügung verhindert hat) und einem bool-Wert besteht, der auf true gesetzt ist, wenn und nur wenn die Einfügung stattgefunden hat.

10) Ein Iterator auf das eingefügte Element oder auf das Element, das die Einfügung verhindert hat.

Ausnahmen

1-4) Wenn durch eine Operation eine Ausnahme ausgelöst wird, hat die Einfügung keine Auswirkung.

Komplexität

1,2) Logarithmisch zur Größe des Containers, O(log(size())).

3,4) Amortisiert konstant, wenn die Einfügung an der Position direkt *nach*(bis C++11)*vor*(seit C++11) pos stattfindet, sonst logarithmisch zur Größe des Containers.

5,6) O(N·log(size() + N)), wobei N die Anzahl der einzufügenden Elemente ist.

7) Logarithmisch zur Größe des Containers, O(log(size())).

8) Amortisiert konstant, wenn die Einfügung an der Position direkt *vor* pos stattfindet, sonst logarithmisch zur Größe des Containers.

9) Logarithmisch zur Größe des Containers, O(log(size())).

10) Amortisiert konstant, wenn die Einfügung an der Position direkt *vor* pos stattfindet, sonst logarithmisch zur Größe des Containers.

Hinweise

Die mit einem Hinweis versehene Einfügung (3,4) gibt kein boolesches Ergebnis zurück, um signaturkompatibel mit positionsbasierter Einfügung in sequenzielle Container wie std::vector::insert zu sein. Dies ermöglicht die Erstellung generischer Einfüger wie std::inserter. Eine Möglichkeit, den Erfolg einer mit einem Hinweis versehenen Einfügung zu überprüfen, ist der Vergleich von size() vor und nach der Operation.

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

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

Führen Sie diesen Code aus

#include <cassert>
#include <iostream>
#include <set>
 
int main()
{
    std::set<int> set;
 
    auto result_1 = set.insert(3);
    assert(result_1.first != set.end()); // it is a valid 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); // same 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	Korrigiertes Verhalten
LWG 233	C++98	pos war nur ein Hinweis, er konnte komplett ignoriert werden	die Einfügung musste so nah wie möglich an der Position direkt vor pos erfolgen
LWG 264	C++98	die Komplexität der Überladung (5) sollte linear sein, wenn der Bereich [first, last) gemäß Compare sortiert ist.	die lineare Anforderung entfernt in diesem Sonderfall
LWG 316	C++98	im Rückgabewert der Überladung (1) war nicht spezifiziert, welcher bool-Wert eine erfolgreiche Einfügung anzeigt.	Erfolg wird durch true angezeigt.

Siehe auch

emplace (C++11)	konstruiert Elemente direkt (in-place) (public member function)
emplace_hint (C++11)	konstruiert Elemente "in place" unter Verwendung eines Hinweises (public member function)
inserter	erstellt einen std::insert_iterator vom Typ, der aus dem Argument abgeleitet wird (Funktionsvorlage)