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) (начиная с C++17)
(constexpr начиная с C++26)
node_type extract ( const Key & k ) ;
(2) (начиная с C++17)
(constexpr начиная с C++26)
template < class K >
node_type extract ( K && x ) ;
(3) (начиная с C++23)
(constexpr начиная с C++26)
1) Отсоединяет узел, содержащий элемент, на который указывает pos и возвращает node handle который владеет им.
2,3) Если контейнер содержит элемент с ключом, эквивалентным k или x (начиная с C++23) , отсоединяет узел, содержащий первый такой элемент, от контейнера и возвращает node handle , который им владеет. В противном случае возвращает пустой node handle.
3) Эта перегрузка участвует в разрешении перегрузки только если Hash и KeyEqual являются прозрачными , и ни iterator , ни const_iterator не являются неявно преобразуемыми из K . Предполагается, что такой Hash может быть вызван как с типом K , так и с типом Key , и что KeyEqual является прозрачным, что в совокупности позволяет вызывать эту функцию без создания экземпляра Key .

В любом случае элементы не копируются и не перемещаются, только внутренние указатели узлов контейнера перенаправляются.

Извлечение узла инвалидирует только итераторы на извлеченный элемент и сохраняет относительный порядок элементов, которые не были удалены. Указатели и ссылки на извлеченный элемент остаются действительными, но не могут использоваться, пока элемент принадлежит node handle: они становятся пригодными для использования, если элемент вставляется в контейнер.

Содержание

Параметры

pos - корректный итератор данного контейнера
k - ключ для идентификации извлекаемого узла
x - значение любого типа, которое может прозрачно сравниваться с ключом, идентифицирующим извлекаемый узел

Возвращаемое значение

Дескриптор узла node handle , владеющий извлеченным элементом, или пустой дескриптор узла, если элемент не найден в (2,3) .

Исключения

1) Ничего не выбрасывает.
2,3) Любые исключения, выбрасываемые объектами Hash и KeyEqual .

Сложность

1-3) В среднем O(1), в худшем случае O( size() ).

Примечания

extract — это единственный способ изменить ключ элемента map без перераспределения памяти: 

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"}}
Макрос тестирования возможностей Значение Стандарт Возможность
__cpp_lib_associative_heterogeneous_erasure 202110L (C++23) Гетерогенное удаление в ассоциативных контейнерах и неупорядоченных ассоциативных контейнерах , ( 3 )

Пример

Запустить код 
#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);
    // Extract node handle and change key
    auto nh = cont.extract(1);
    nh.key() = 4;
    print("After extract and before insert:", cont);
    // Insert node handle back
    cont.insert(std::move(nh));
    print("End:", cont);
}

Возможный вывод: 

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

Смотрите также

(C++17)
объединяет узлы из другого контейнера
(публичная функция-член)
вставляет элементы или узлы (начиная с C++17)
(публичная функция-член)
удаляет элементы
(публичная функция-член)