Namespaces
Variants

std::set<Key,Compare,Allocator>:: extract

From cppreference.net

C++
Containers library
std::set
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
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 (since C++23) , отсоединяет узел, содержащий этот элемент, от контейнера и возвращает node handle , который владеет им. В противном случае возвращает пустой node handle.
3) Эта перегрузка участвует в разрешении перегрузки только если Compare является прозрачным , и ни iterator , ни const_iterator не являются неявно преобразуемыми из K . Это позволяет вызывать данную функцию без создания экземпляра Key .

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

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

Содержание

Параметры

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

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

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

Исключения

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

Сложность

1) Амортизированная константа.
2,3) log( size() )

Примечания

extract — это единственный способ извлечь move-only объект из множества: 

std::set<move_only_type> s;
s.emplace(...);
move_only_type mot = std::move(s.extract(s.begin()).value());
Макрос тестирования возможностей Значение Стандарт Возможность
__cpp_lib_associative_heterogeneous_erasure 202110L (C++23) Гетерогенное удаление в ассоциативных контейнерах и неупорядоченных ассоциативных контейнерах , ( 3 )

Пример

Запустить этот код 
#include <algorithm>
#include <iostream>
#include <string_view>
#include <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::set<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)
(публичная функция-член)
удаляет элементы
(публичная функция-член)