Node handle (C++17)
template</* unspecified */> class /*node-handle*/; |
(C++17以降) (説明用*) |
|
連想コンテナである std::set、std::map、std::multiset、std::multimap、std::unordered_set、std::unordered_map、std::unordered_multiset、std::unordered_multimap はノードベースのデータ構造であり、そのノードは node handle と呼ばれる、型が未指定のオブジェクトとして抽出できます。
Node handle は、ノードに格納されている要素（value_type）を所有し、それにアクセスするための、移動専用の型です。また、要素のキー部分（key_type）とマッピング部分（mapped_type）への非constアクセスを提供します。ノードハンドルがノードを保持したまま破棄されると、コンテナの適切なアロケータを使用してノードが適切に破棄されます。ノードハンドルには、コンテナのアロケータのコピーが含まれます。これは、ノードハンドルがコンテナよりも長く生存する必要があるため、必要です。
Node handle の正確な型（ここでは /*node-handle*/ と表示されています）は未指定ですが、各コンテナは自身のノードハンドル型をメンバ node_type として公開します。
Node handles は、キー、値、アロケータの型が同じ（比較またはハッシュ/等価性は無視）な2つの連想コンテナ間で、コンテナ要素のコピー/移動操作を呼び出さずに要素の所有権を転送するために使用できます（この種の操作は「スプライシング」として知られています）。ユニークコンテナと非ユニークコンテナ間での転送も許可されます。例えば、std::map からのノードハンドルは、std::multimap に挿入できますが、std::unordered_map や std::set には挿入できません。
Node handle は空の場合があり、その場合、要素もアロケータも保持しません。デフォルト構築されたノードハンドルと移動元となったノードハンドルは空です。さらに、コンテナメンバ関数 extract の呼び出しに失敗した場合に、空のノードハンドルが生成されることがあります。
Node handle によって所有されている要素へのポインタや参照は、要素が正常にコンテナに挿入された場合、無効になります。
key_type が K で mapped_type が T であるすべてのマップコンテナ（std::map、std::multimap、std::unordered_map、std::unordered_multimap）において、std::pair のユーザー定義特殊化が std::pair<K, T> または std::pair<const K, T> に対して存在する場合、ノードハンドルに関連する操作の動作は未定義となります。
目次 |
[edit] メンバ型
| 型 | 定義 |
key_type (mapコンテナのみ) |
ノードに格納されているキー |
mapped_type (mapコンテナのみ) |
ノードに格納されている要素のマッピング部分 |
value_type (setコンテナのみ) |
ノードに格納されている要素 |
allocator_type
|
要素の破棄に使用されるアロケータ |
container_node_type (private) |
コンテナノード、型は未指定 (説明専用メンバ型*) |
ator_traits (private) |
std::allocator_traits<allocator_type> 型のアロケータ特性 (説明専用メンバ型*) |
[edit] データメンバ
| メンバ | 定義 |
| typename ator_traits::template rebind_traits<container_node_type>::pointer ptr_(条件付きで存在) |
TODO (説明用のメンバオブジェクト*) |
std::optional<allocator_type> alloc_(条件付きで存在) |
TODO (説明用のメンバオブジェクト*) |
[edit] メンバ関数
コンストラクタ
| constexpr /*node-handle*/() noexcept; |
(1) | |
| /*node-handle*/(/*node-handle*/&& nh) noexcept; |
(2) | |
パラメータ
| nh | - | 同じ型のノードハンドル（必ずしも同じコンテナではない） |
注釈
Node handles は移動専用であり、コピーコンストラクタは定義されていません。
operator=
| /*node-handle*/& operator=(/*node-handle*/&& nh); |
||
- ノードハンドルが空でない場合、
- このノードハンドルによって管理されているコンテナ要素オブジェクト内の
value_typeサブオブジェクトをator_traits::destroyを呼び出して破棄します。 - コンテナ要素を ator_traits::rebind_traits</*container-node-type*/>::deallocate を呼び出して解放します。
- このノードハンドルによって管理されているコンテナ要素オブジェクト内の
- nh からコンテナ要素の所有権を取得します。
- ノードハンドルが空だった場合（したがってアロケータを含んでいなかった場合）、または ator_traits::propagate_on_container_move_assignment が true の場合、nh からアロケータをムーブ代入します。
- nh を空の状態に設定します。
ノードが空でなく、ator_traits::propagate_on_container_move_assignment が false で、かつアロケータが等しくない場合、動作は未定義です。
パラメータ
| nh | - | 同じ型のノードハンドル（必ずしも同じコンテナではない） |
戻り値
*this
例外
何もスローしません。
注釈
Node handles は移動専用であり、コピー代入は定義されていません。
デストラクタ
| ~/*node-handle*/(); |
||
- ノードハンドルが空でない場合、
- このノードハンドルによって管理されているコンテナ要素オブジェクト内の
value_typeサブオブジェクトを ator_traits::destroy を呼び出して破棄します。 - コンテナ要素を ator_traits::rebind_traits</*container-node-type*/>::deallocate を呼び出して解放します。
- このノードハンドルによって管理されているコンテナ要素オブジェクト内の
empty
| bool empty() const noexcept; |
||
ノードハンドルが空の場合は true を、そうでない場合は false を返します。
operator bool
| explicit operator bool() const noexcept; |
||
ノードハンドルが空の場合は false に、そうでない場合は true に変換されます。
get_allocator
| allocator_type get_allocator() const; |
||
格納されているアロケータのコピー（ソースコンテナのアロケータのコピー）を返します。ノードハンドルが空の場合、動作は未定義です。
例外
何もスローしません。
value
| value_type& value() const; |
(setコンテナのみ) | |
このノードハンドルによって管理されているコンテナ要素オブジェクト内の value_type サブオブジェクトへの参照を返します。ノードハンドルが空の場合、動作は未定義です。
例外
何もスローしません。
key
| key_type& key() const; |
(mapコンテナのみ) | |
このノードハンドルによって管理されているコンテナ要素オブジェクトの value_type サブオブジェクトの key_type メンバへの非const参照を返します。ノードハンドルが空の場合、動作は未定義です。
例外
何もスローしません。
注釈
この関数により、マップから抽出されたノードのキーを変更し、要素のコピーや移動を一切行わずにマップに再挿入することが可能になります。
mapped
| mapped_type& mapped() const; |
(mapコンテナのみ) | |
このノードハンドルによって管理されているコンテナ要素オブジェクトの value_type サブオブジェクトの mapped_type メンバへの参照を返します。ノードハンドルが空の場合、動作は未定義です。
例外
何もスローしません。
swap
| void swap(/*node-handle*/& nh) noexcept(/* see below */); |
||
- コンテナノードの所有権を交換します。
- 一方のノードが空である場合、または両方のノードが空でなく、かつ ator_traits::propagate_on_container_swap が true の場合、アロケータも交換します。
両方のノードが空でなく、ator_traits::propagate_on_container_swap が false で、かつアロケータが等しくない場合、動作は未定義です。
例外
ator_traits::is_always_equal::value)
[edit] 非メンバ関数
swap
| friend void swap(/*node-handle*/& x, /*node-handle*/& y) noexcept(noexcept(x.swap(y))); |
||
x.swap(y) を実行します。
この関数は通常の非修飾または修飾ルックアップからは見えず、引数に関連するクラスが node-handle である場合の引数依存ルックアップによってのみ見つけることができます。
