Namespaces
Variants

std::multimap<Key,T,Compare,Allocator>:: extract

From cppreference.net

C++
Containers library
std::multimap
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) このオーバーロードは、 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 は再割り当てなしでマップ要素のキーを変更する唯一の方法です： 

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 <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::multimap<int, char> cont{{1, 'a'}, {2, 'b'}, {3, 'c'}};
    print("Start:", cont);
    // ノードハンドルを抽出してキーを変更
    auto nh = cont.extract(1);
    nh.key() = 4;
    print("After extract and before insert:", cont);
    // ノードハンドルを挿入し戻す
    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以降)
(公開メンバ関数)
要素を削除する
(公開メンバ関数)