std::map<Key,T,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::map

Memberfunktionen

map::map map::~map               map::operator= map::get_allocator

Elementzugriff map::at map::operator[] Iteratoren map::beginmap::cbegin (C++11) map::endmap::cend (C++11) map::rbeginmap::crbegin (C++11)      map::rendmap::crend (C++11) Kapazität map::size map::max_size map::empty Observer map::key_comp map::value_comp Modifizierer map::clear map::insert map::erase map::swap map::extract (C++17) map::merge (C++17) map::insert_range (C++23) map::insert_or_assign (C++17) map::emplace (C++11) map::emplace_hint (C++11) map::try_emplace (C++17) Suche map::count map::find map::contains (C++20) map::equal_range map::lower_bound map::upper_bound

Nicht-Member-Funktionen

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

Leitfaden zur Ableitung (C++17)

 

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

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

1-3) Fügt value ein.

Überladung (2) ist äquivalent zu emplace(std::forward<P>(value)) und nimmt nur an der Auflösung von Überladungen teil, wenn std::is_constructible<value_type, P&&>::value == true.

4-6) Fügt value an einer Position ein, die der Position unmittelbar vor pos so nahe wie möglich ist.

Überladung (5) ist äquivalent zu emplace_hint(hint, std::forward<P>(value)) und nimmt nur an der Auflösung von Überladungen teil, wenn std::is_constructible<value_type, P&&>::value == true.

7) Fügt Elemente aus dem Bereich [first, last) ein. Wenn mehrere Elemente im Bereich Schlüssel haben, die als äquivalent verglichen werden, ist nicht spezifiziert, welches Element eingefügt wird (vorbehaltlich LWG2844).

8) Fügt Elemente aus der Initialisierungsliste ilist ein. Wenn mehrere Elemente im Bereich Schlüssel haben, die als äquivalent verglichen werden, ist nicht spezifiziert, welches Element eingefügt wird (vorbehaltlich LWG2844).

9) Wenn nh ein leeres Knoten-Handle ist, tut es nichts. Andernfalls wird das von nh gehaltene Element in den Container eingefügt, wenn 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().

10) Wenn nh ein leeres Knoten-Handle ist, tut es nichts und gibt den End-Iterator zurück. Andernfalls wird das von nh gehaltene Element in den Container eingefügt, wenn 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 einem Schlüssel zeigt, der äquivalent zu nh.key() ist (unabhängig davon, ob die Einfügung erfolgreich war oder fehlgeschlagen ist). Wenn die Einfügung erfolgreich ist, wird nh von dort verschoben, andernfalls behält es den Besitz des Elements. Das Element wird so nahe wie möglich an der Position unmittelbar vor pos eingefügt. Das Verhalten ist undefiniert, wenn nh nicht leer ist und get_allocator() != nh.get_allocator().

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 Paar von Iteratoren, die den Bereich der einzufügenden Elemente definieren
ilist	-	Initialisierungsliste, aus der die Werte eingefügt werden sollen
nh	-	ein kompatibler Node Handle
Typanforderungen
- InputIt muss die Anforderungen von LegacyInputIterator erfüllen.

Rückgabewert

1-3) 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.

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

7,8) (keiner)

9) Ein Objekt vom Typ insert_return_type mit den folgenden Initialisierungen der Member

• 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.

10) End-Iterator, wenn nh leer war, Iterator auf das eingefügte Element, wenn die Einfügung stattfand, und Iterator auf ein Element mit einem Schlüssel, der äquivalent zu nh.key() ist, wenn sie fehlschlug.

Ausnahmen

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

Komplexität

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

4-6) Amortisiert konstant, wenn die Einfügung an der Position unmittelbar danach(bis C++11)davor(seit C++11) pos erfolgt, ansonsten logarithmisch zur Größe des Containers.

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

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

10) Amortisiert konstant, wenn die Einfügung an der Position unmittelbar vor pos erfolgt, ansonsten logarithmisch zur Größe des Containers.

Anmerkungen

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

Beispiel

Führen Sie diesen Code aus

#include <iomanip>
#include <iostream>
#include <map>
#include <string>
using namespace std::literals;
 
template<typename It>
void print_insertion_status(It it, bool success)
{
    std::cout << "Insertion of " << it->first
              << (success ? " succeeded\n" : " failed\n");
}
 
int main()
{
    std::map<std::string, float> heights;
 
    // Overload 3: insert from rvalue reference
    const auto [it_hinata, success] = heights.insert({"Hinata"s, 162.8});
    print_insertion_status(it_hinata, success);
 
    {
        // Overload 1: insert from lvalue reference
        const auto [it, success2] = heights.insert(*it_hinata);
        print_insertion_status(it, success2);
    }
    {
        // Overload 2: insert via forwarding to emplace
        const auto [it, success] = heights.insert(std::pair{"Kageyama", 180.6});
        print_insertion_status(it, success);
    }
    {
        // Overload 6: insert from rvalue reference with positional hint
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, {"Azumane"s, 184.7});
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // Overload 4: insert from lvalue reference with positional hint
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, *it_hinata);
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // Overload 5: insert via forwarding to emplace with positional hint
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, std::pair{"Tsukishima", 188.3});
        print_insertion_status(it, std::size(heights) != n);
    }
 
    auto node_hinata = heights.extract(it_hinata);
    std::map<std::string, float> heights2;
 
    // Overload 7: insert from iterator range
    heights2.insert(std::begin(heights), std::end(heights));
 
    // Overload 8: insert from initializer_list
    heights2.insert({{"Kozume"s, 169.2}, {"Kuroo", 187.7}});
 
    // Overload 9: insert node
    const auto status = heights2.insert(std::move(node_hinata));
    print_insertion_status(status.position, status.inserted);
 
    node_hinata = heights2.extract(status.position);
    {
        // Overload 10: insert node with positional hint
        const std::size_t n = std::size(heights2);
        const auto it = heights2.insert(std::begin(heights2), std::move(node_hinata));
        print_insertion_status(it, std::size(heights2) != n);
    }
 
    // Print resulting map
    std::cout << std::left << '\n';
    for (const auto& [name, height] : heights2)
        std::cout << std::setw(10) << name << " | " << height << "cm\n";
}

Ausgabe

Insertion of Hinata succeeded
Insertion of Hinata failed
Insertion of Kageyama succeeded
Insertion of Azumane succeeded
Insertion of Hinata failed
Insertion of Tsukishima succeeded
Insertion of Hinata succeeded
Insertion of Hinata succeeded
 
Azumane    | 184.7cm
Hinata     | 162.8cm
Kageyama   | 180.6cm
Kozume     | 169.2cm
Kuroo      | 187.7cm
Tsukishima | 188.3cm

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 (7) war als linear gefordert, 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
LWG 2005	C++11	die Überladungen (2,5) waren schlecht beschrieben	verbesserte die Beschreibung

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)
insert_or_assign (C++17)	fügt ein Element ein oder weist einem vorhandenen Element einen Wert zu, falls der Schlüssel bereits existiert (public member function)
inserter	erstellt einen std::insert_iterator vom Typ, der aus dem Argument abgeleitet wird (Funktionsvorlage)