Namespaces
Variants

std::unordered_multiset<Key,Hash,KeyEqual,Allocator>:: extract

From cppreference.net

C++
Containers library
std::unordered_multiset
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 — это единственный способ извлечь move-only объект из множества: 

std::set<move_only_type> s;
s.emplace(...);
move_only_type mot = std::move(s.extract(s.begin()).value());
Feature-test macro Value Std Feature
__cpp_lib_associative_heterogeneous_erasure 202110L (C++23) Гетерогенное удаление в ассоциативных контейнерах и неупорядоченных ассоциативных контейнерах , ( 3 )

Пример

Запустить этот код 
#include <algorithm>
#include <iostream>
#include <string_view>
#include <unordered_set>
void print(std::string_view comment, const auto& data)
{
    std::cout << comment;
    for (auto datum : data)
        std::cout << ' ' << datum;
    std::cout << '\n';
}
int main()
{
    std::unordered_multiset<int> cont{1, 2, 3};
    print("Start:", cont);
    // Извлечение node handle и изменение ключа
    auto nh = cont.extract(1);
    nh.value() = 4;
    print("After extract and before insert:", cont);
    // Вставка node handle обратно
    cont.insert(std::move(nh));
    print("End:", cont);
}

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

Start: 1 2 3
After extract and before insert: 2 3
End: 2 3 4

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

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