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 (C++23以降) と等価な要素を持つ場合、その要素を含むノードをコンテナから切り離し、それを所有する node handle を返します。それ以外の場合、空のnode handleを返します。
3) このオーバーロードは、 Compare が transparent であり、かつ iterator も const_iterator も K から暗黙的に変換可能でない場合にのみ、オーバーロード解決に参加します。これにより、 Key のインスタンスを構築せずにこの関数を呼び出すことが可能になります。

いずれの場合も、要素はコピーも移動もされず、コンテナノードの内部ポインタのみが再ポイントされます（ erase() と同様に、リバランシングが発生する可能性があります）。

ノードの抽出は、抽出された要素へのイテレータのみを無効化します。抽出された要素へのポインタと参照は有効なままですが、要素がノードハンドルによって所有されている間は使用できません。要素がコンテナに挿入されると、それらは使用可能になります。

目次

パラメータ

pos - このコンテナ内の有効なイテレータ
k - 抽出対象ノードを識別するキー
x - 抽出対象ノードを識別するキーと透過的に比較可能な任意の型の値

戻り値

抽出された要素を所有する node handle 、または要素が (2,3) 内で見つからなかった場合は空のnode handle。

例外

1) 何もスローしない。
2,3) Compare オブジェクトによってスローされる例外。

計算量

1) 償却定数時間。
2,3) log( size() )

注記

extract はムーブのみ可能なオブジェクトを set から取り出す唯一の方法です: 

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);
    // Extract node handle and change key
    auto nh = cont.extract(1);
    nh.value() = 4;
    print("After extract and before insert:", cont);
    // Insert node handle back
    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以降)
(公開メンバ関数)
要素を削除する
(公開メンバ関数)