Node handle (C++17)
template</* unbekannt */> class /*node-handle*/; |
(seit C++17) (nur Exposition*) |
|
Assoziative Container std::set, std::map, std::multiset, std::multimap, std::unordered_set, std::unordered_map, std::unordered_multiset, std::unordered_multimap sind knotenbasierte Datenstrukturen, und ihre Knoten können als ein Objekt eines unbekannten Typs, bekannt als node handle, extrahiert werden.
Node handle ist ein nur-verschiebbarer Typ, der das in dem Knoten gespeicherte Element (den value_type) besitzt und darauf Zugriff gewährt. Er bietet nicht-const-Zugriff auf den Schlüsselteil des Elements (den key_type) und den zugeordneten Teil des Elements (den mapped_type). Wenn das Node handle zerstört wird, während es den Knoten hält, wird der Knoten ordnungsgemäß unter Verwendung des entsprechenden Allokators für den Container zerstört. Das Node handle enthält eine Kopie des Allokators des Containers. Dies ist notwendig, damit das Node handle den Container überleben kann.
Der genaue Typ des Node handle (hier als /*node-handle*/ dargestellt) ist unbekannt, aber jeder Container stellt seinen Node-Handle-Typ als Mitglied node_type bereit.
Node handles können verwendet werden, um den Besitz eines Elements zwischen zwei assoziativen Containern mit demselben Schlüssel-, Wert- und Allokator-Typ (unter Ignorierung von Vergleichs- oder Hash-/Gleichheitskriterien) zu übertragen, ohne Kopier-/Verschiebeoperationen auf dem Containerelement aufzurufen (diese Art von Operation wird als "Splicing" bezeichnet). Die Übertragung zwischen eindeutigen und nicht-eindeutigen Containern ist ebenfalls gestattet: Ein Node handle von einem std::map kann in ein std::multimap eingefügt werden, aber nicht in ein std::unordered_map oder std::set.
Ein Node handle kann leer sein, in diesem Fall hält es kein Element und keinen Allokator. Das standardkonstruierte und aus-verschobene Node handle ist leer. Zusätzlich kann ein leeres Node handle durch einen fehlgeschlagenen Aufruf der Container-Mitgliedsfunktion extract erzeugt werden.
Zeiger und Referenzen auf ein Element, die erhalten werden, während es im Besitz eines Node handle ist, werden ungültig, wenn das Element erfolgreich in einen Container eingefügt wird.
Für alle Map-Container (std::map, std::multimap, std::unordered_map und std::unordered_multimap) mit key_type K und mapped_type T ist das Verhalten von Operationen, die Node handles beinhalten, undefiniert, wenn eine benutzerdefinierte Spezialisierung von std::pair für std::pair<K, T> oder std::pair<const K, T> existiert.
Inhalt |
[bearbeiten] Member types
| Typ | Definition |
key_type (nur Map-Container) |
der im Knoten gespeicherte Schlüssel |
mapped_type (nur Map-Container) |
der zugeordnete Teil des im Knoten gespeicherten Elements |
value_type (nur Set-Container) |
das im Knoten gespeicherte Element |
allocator_type
|
der beim Zerstören des Elements zu verwendende Allokator |
container_node_type (privat) |
ein Container-Knoten, der Typ ist unbekannt ((nur zur Veranschaulichung)*) |
ator_traits (privat) |
Allocator-Traits vom Typ std::allocator_traits<allocator_type> ((nur zur Veranschaulichung)*) |
[bearbeiten] Data members
| Mitglied | Definition |
| typename ator_traits::template rebind_traits<container_node_type>::pointer ptr_(bedingt vorhanden) |
ZU TUN ((exposition-only member object*) |
std::optional<allocator_type> alloc_(bedingt vorhanden) |
ZU TUN ((exposition-only member object*) |
[bearbeiten] Member functions
Konstruktoren
| constexpr /*node-handle*/() noexcept; |
(1) | |
| /*node-handle*/(/*node-handle*/&& nh) noexcept; |
(2) | |
Parameter
| nh | - | ein Node handle mit demselben Typ (nicht notwendigerweise demselben Container) |
Anmerkungen
Node handles sind nur-verschiebbar, der Kopierkonstruktor ist nicht definiert.
operator=
| /*node-handle*/& operator=(/*node-handle*/&& nh); |
||
- Wenn das Node handle nicht leer ist,
- zerstört das
value_type-Subobjekt im von diesem Node handle verwalteten Containerelement durch Aufruf vonator_traits::destroy; - deallokiert das Containerelement durch Aufruf von ator_traits::rebind_traits</*container-node-type*/>::deallocate;
- zerstört das
- Übernimmt den Besitz des Containerelements von nh;
- Wenn das Node handle leer war (und somit keinen Allokator enthielt) oder wenn ator_traits::propagate_on_container_move_assignment true ist, wird der Allokator von nh per Zuweisung verschoben;
- setzt nh in den leeren Zustand.
Das Verhalten ist undefiniert, wenn der Knoten nicht leer ist und ator_traits::propagate_on_container_move_assignment false ist und die Allokatoren nicht gleich sind.
Parameter
| nh | - | Node handle mit demselben Typ (nicht notwendigerweise demselben Container) |
Rückgabe
*this
Ausnahmen
Wirft nichts.
Anmerkungen
Node handles sind nur-verschiebbar, die Zuweisung per Kopie ist nicht definiert.
Destruktor
| ~/*node-handle*/(); |
||
- Wenn das Node handle nicht leer ist,
- zerstört das
value_type-Subobjekt im von diesem Node handle verwalteten Containerelement durch Aufruf von ator_traits::destroy; - deallokiert das Containerelement durch Aufruf von ator_traits::rebind_traits</*container-node-type*/>::deallocate.
- zerstört das
empty
| bool empty() const noexcept; |
||
Gibt true zurück, wenn das Node handle leer ist, andernfalls false.
operator bool
| explicit operator bool() const noexcept; |
||
Konvertiert zu false, wenn das Node handle leer ist, andernfalls zu true.
get_allocator
| allocator_type get_allocator() const; |
||
Gibt eine Kopie des gespeicherten Allokators zurück (welcher eine Kopie des Allokators des Quellcontainers ist). Das Verhalten ist undefiniert, wenn das Node handle leer ist.
Ausnahmen
Wirft nichts.
value
| value_type& value() const; |
(nur Set-Container) | |
Gibt eine Referenz auf das value_type-Subobjekt im von diesem Node handle verwalteten Containerelement zurück. Das Verhalten ist undefiniert, wenn das Node handle leer ist.
Ausnahmen
Wirft nichts.
key
| key_type& key() const; |
(nur Map-Container) | |
Gibt eine nicht-const-Referenz auf das key_type-Mitglied des value_type-Subobjekts im von diesem Node handle verwalteten Containerelement zurück. Das Verhalten ist undefiniert, wenn das Node handle leer ist.
Ausnahmen
Wirft nichts.
Anmerkungen
Diese Funktion ermöglicht es, den Schlüssel eines aus einer Map extrahierten Knotens zu ändern und ihn dann wieder in die Map einzufügen, ohne das Element jemals zu kopieren oder zu verschieben.
mapped
| mapped_type& mapped() const; |
(nur Map-Container) | |
Gibt eine Referenz auf das mapped_type-Mitglied des value_type-Subobjekts im von diesem Node handle verwalteten Containerelement zurück. Das Verhalten ist undefiniert, wenn das Node handle leer ist.
Ausnahmen
Wirft nichts.
swap
| void swap(/*node-handle*/& nh) noexcept(/* siehe unten */); |
||
- tauscht den Besitz von Container-Knoten;
- wenn ein Knoten leer ist oder wenn beide Knoten nicht leer sind und ator_traits::propagate_on_container_swap true ist, werden auch die Allokatoren getauscht.
Das Verhalten ist undefiniert, wenn beide Knoten nicht leer sind und ator_traits::propagate_on_container_swap false ist und die Allokatoren nicht gleich sind.
Ausnahmen
ator_traits::is_always_equal::value)
[bearbeiten] Nicht-Member-Funktionen
swap
| friend void swap(/*node-handle*/& x, /*node-handle*/& y) noexcept(noexcept(x.swap(y))); |
||
Führt effektiv x.swap(y) aus.
Diese Funktion ist für normale unqualifizierte oder qualifizierte Suche nicht sichtbar und kann nur durch argumentabhängige Suche gefunden werden, wenn node-handle eine assoziierte Klasse der Argumente ist.
