Namespaces
Variants

std::unordered_multimap<Key,T,Hash,KeyEqual,Allocator>:: extract

From cppreference.net

C++
Containers library
std::unordered_multimap
Member types
Member functions
Non-member functions
Deduction guides (C++17)
node_type extract ( const_iterator pos ) ;
(1) (desde C++17)
(constexpr desde C++26)
node_type extract ( const Key & k ) ;
(2) (desde C++17)
(constexpr desde C++26)
template < class K >
node_type extract ( K && x ) ;
(3) (desde C++23)
(constexpr desde C++26)
1) Desvincula el nodo que contiene el elemento apuntado por pos y devuelve un node handle que lo posee.
2,3) Si el contenedor tiene un elemento con clave equivalente a k o x (desde C++23) , desvincula el nodo que contiene el primer elemento de este tipo del contenedor y devuelve un node handle que lo posee. De lo contrario, devuelve un node handle vacío.
3) Esta sobrecarga participa en la resolución de sobrecarga solo si Hash y KeyEqual son ambos transparentes , y ni iterator ni const_iterator son convertibles implícitamente desde K . Esto asume que dicho Hash puede ser invocado tanto con el tipo K como con el tipo Key , y que el KeyEqual es transparente, lo que, en conjunto, permite llamar a esta función sin construir una instancia de Key .

En cualquier caso, no se copian ni mueven elementos, solo se redirigen los punteros internos de los nodos del contenedor.

Extraer un nodo solo invalida los iteradores al elemento extraído, y preserva el orden relativo de los elementos que no son borrados. Los punteros y referencias al elemento extraído permanecen válidos, pero no pueden usarse mientras el elemento es propiedad de un manejador de nodo: se vuelven utilizables si el elemento se inserta en un contenedor.

Contenidos

Parámetros

pos - un iterador válido dentro de este contenedor
k - una clave para identificar el nodo a extraer
x - un valor de cualquier tipo que pueda compararse de forma transparente con una clave que identifique el nodo a extraer

Valor de retorno

Un node handle que posee el elemento extraído, o un node handle vacío en caso de que el elemento no se encuentre en (2,3) .

Excepciones

1) No lanza nada.
2,3) Cualquier excepción lanzada por los objetos Hash y KeyEqual .

Complejidad

1-3) Caso promedio O(1), caso peor O( size() ).

Notas

extract es la única forma de cambiar una clave de un elemento de mapa sin reasignación: 

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 prueba de características Valor Estándar Característica
__cpp_lib_associative_heterogeneous_erasure 202110L (C++23) Borrado heterogéneo en contenedores asociativos y contenedores asociativos no ordenados , ( 3 )

Ejemplo

Ejecutar este código 
#include <algorithm>
#include <iostream>
#include <string_view>
#include <unordered_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::unordered_multimap<int, char> cont{{1, 'a'}, {2, 'b'}, {3, 'c'}};
    print("Start:", cont);
    // Extraer manejador de nodo y cambiar clave
    auto nh = cont.extract(1);
    nh.key() = 4;
    print("After extract and before insert:", cont);
    // Insertar manejador de nodo de vuelta
    cont.insert(std::move(nh));
    print("End:", cont);
}

Salida posible: 

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

Véase también

(C++17)
empalma nodos de otro contenedor
(función miembro pública)
inserta elementos o nodos (desde C++17)
(función miembro pública)
borra elementos
(función miembro pública)