Namespaces
Variants

std::multimap<Key,T,Compare,Allocator>:: extract

From cppreference.net

C++
Containers library
std::multimap
Member functions
Non-member functions
Deduction guides (C++17)
node_type extract ( const_iterator pos ) ;
(1) (depuis C++17)
(constexpr depuis C++26)
node_type extract ( const Key & k ) ;
(2) (depuis C++17)
(constexpr depuis C++26)
template < class K >
node_type extract ( K && x ) ;
(3) (depuis C++23)
(constexpr depuis C++26)
1) Détache le nœud qui contient l'élément pointé par pos et retourne un node handle qui en est propriétaire.
2,3) Si le conteneur possède un élément avec une clé équivalente à k ou x (depuis C++23) , délie le nœud qui contient le premier de ces éléments du conteneur et retourne un node handle qui le possède. Sinon, retourne un node handle vide.
3) Cette surcharge participe à la résolution de surcharge uniquement si Compare est transparent , et si ni iterator ni const_iterator ne sont implicitement convertibles à partir de K . Cela permet d'appeler cette fonction sans construire une instance de Key .

Dans les deux cas, aucun élément n'est copié ou déplacé, seuls les pointeurs internes des nœuds du conteneur sont redirigés (un rééquilibrage peut survenir, comme avec erase() ).

L'extraction d'un nœud n'invalide que les itérateurs vers l'élément extrait. Les pointeurs et références vers l'élément extrait restent valides, mais ne peuvent pas être utilisés tant que l'élément est détenu par un gestionnaire de nœud : ils redeviennent utilisables si l'élément est inséré dans un conteneur.

Table des matières

Paramètres

pos - un itérateur valide dans ce conteneur
k - une clé pour identifier le nœud à extraire
x - une valeur de tout type pouvant être comparée de manière transparente avec une clé identifiant le nœud à extraire

Valeur de retour

Un node handle qui possède l'élément extrait, ou un node handle vide si l'élément n'est pas trouvé dans (2,3) .

Exceptions

1) Ne lance rien.
2,3) Toute exception levée par l'objet Compare .

Complexité

1) Amorti constant.
2,3) log( size() )

Notes

extract est le seul moyen de modifier la clé d'un élément de map sans réallocation : 

std::map<int, std::string> m{{1, "mango"}, {2, "papaya"}, {3, "guava"}};
auto nh = m.extract(2);
nh.key() = 4;
m.insert(std::move(nh));
// m == {{1, "mango"}, {3, "guava"}, {4, "papaya"}}
Macro de test de fonctionnalité Valeur Norme Fonctionnalité
__cpp_lib_associative_heterogeneous_erasure 202110L (C++23) Effacement hétérogène dans les conteneurs associatifs et conteneurs associatifs non ordonnés , ( 3 )

Exemple

Exécuter ce code 
#include <algorithm>
#include <iostream>
#include <string_view>
#include <map>
void print(std::string_view comment, const auto& data)
{
    std::cout << comment;
    for (auto [k, v] : data)
        std::cout << ' ' << k << '(' << v << ')';
    std::cout << '\n';
}
int main()
{
    std::multimap<int, char> cont{{1, 'a'}, {2, 'b'}, {3, 'c'}};
    print("Start:", cont);
    // Extraire le handle de nœud et modifier la clé
    auto nh = cont.extract(1);
    nh.key() = 4;
    print("Après extraction et avant insertion:", cont);
    // Réinsérer le handle de nœud
    cont.insert(std::move(nh));
    print("Fin:", cont);
}

Sortie : 

Start: 1(a) 2(b) 3(c)
After extract and before insert: 2(b) 3(c)
End: 2(b) 3(c) 4(a)

Voir aussi

(C++17)
épisse les nœuds d'un autre conteneur
(fonction membre publique)
insère des éléments ou des nœuds (depuis C++17)
(fonction membre publique)
efface des éléments
(fonction membre publique)