std::out_ptr_t

ヘッダ `<memory>` で定義
template< class Smart, class Pointer, class... Args > class out_ptr_t;		(C++23から)

out_ptr_t は、スマートポインタのような型を、結果を Pointer*（通常は、あるオブジェクト型 T に対する T**）または void** パラメータ経由で出力する外部関数に適応させるために使用されます。

out_ptr_t は、構築時に追加の引数をキャプチャし、前述のような外部関数が書き込む結果のためのストレージを提供し、破棄時に適応された Smart オブジェクトを結果とキャプチャされた引数でリセットします。

out_ptr_t は、以下の非静的データメンバを持つかのように動作します。

構築時に適応されるオブジェクトにバインドされる Smart& 参照。
Args... の各 T に対して、構築時にキャプチャされ、破棄時のリセットに使用される引数である T 型のメンバ。
Pointer を格納するのに適しており、void* オブジェクトを提供するメンバサブオブジェクト。この Pointer または void* オブジェクトは、通常、再初期化のために外部関数に公開されます。

ユーザは、リセットのための各引数をコピーでキャプチャするか参照でキャプチャするかを、それぞれ Args... にオブジェクト型または参照型を指定することで制御できます。

Smart	-	適応されるオブジェクト（通常はスマートポインタ）の型。
ポインタ	-	外部関数がその結果を書き込むオブジェクト（通常は生ポインタ）の型。
Args...	-	適応されるオブジェクトのリセットに使用されるキャプチャされた引数の型。
型要件
- `Pointer` は NullablePointer の要件を満たす必要があります。
- `Smart` が std::shared_ptr の特殊化であり、かつ sizeof...(Args) == 0 の場合、プログラムは不正形式となります。

[編集] 特殊化

標準ライブラリのほとんどのクラステンプレートとは異なり、少なくとも1つのプログラム定義型に依存する out_ptr_t のプログラム定義特殊化は、プライマリテンプレートの要件を満たす必要はありません。

このライセンスにより、プログラム定義特殊化は、非標準スマートポインタに格納されている生ポインタを外部関数に公開することができます。

[編集] メンバ関数

(コンストラクタ) (C++23)	`out_ptr_t` を構築します。 (public member function)
operator= [deleted](C++23)	`out_ptr_t` は代入できません。 (public member function)
(デストラクタ) (C++23)	適応されたスマートポインタをリセットします。 (public member function)
operator Pointeroperator void* (C++23)	`out_ptr_t` を出力用ストレージのアドレスに変換します。 (public member function)

[編集] 非メンバ関数

out_ptr

(C++23)

関連付けられたスマートポインタとリセット引数を持つ out_ptr_t を作成します
(関数テンプレート) [編集]

[編集] 注意

out_ptr_t は、外部関数がポインタ先の Pointer の値を使用せず、それを再初期化するだけであることを期待します。適応前のスマートポインタの値は使用されません。

out_ptr_t の典型的な使用法は、std::out_ptr による一時オブジェクトの作成です。これは、適応されたスマートポインタを即座にリセットします。例として、適切な型のスマートポインタで宣言されたセッター関数 int foreign_setter(T**); と std::unique_ptr<T, D> up; がある場合、

int foreign_setter(T**);
std::unique_ptr<T, D> up;
 
if (int ec = foreign_setter(std::out_ptr(up)))
    return ec;

はおおよそ等価です。

int foreign_setter(T**);
std::unique_ptr<T, D> up;
T* raw_p{};
 
int ec = foreign_setter(&raw_p);
up.reset(raw_p);
if (ec != 0)
    return ec;

out_ptr_t オブジェクトを自動ストレージ期間以外のストレージ期間で作成することは推奨されません。なぜなら、そのようなコードはダングリング参照を生成し、破棄時に未定義の動作を引き起こす可能性が高いからです。

out_ptr_t は、デリータを指定せずに std::shared_ptr をリセットするような使用法を禁止します。なぜなら、それは std::shared_ptr::reset を呼び出し、後からカスタムデリータを置き換えることになるからです。

キャプチャされた引数は通常、std::tuple<Args...> にパックされます。実装によっては、保持する必要のある Pointer または void* オブジェクトを提供するために異なるメカニズムを使用する場合があります。

機能テストマクロ	値	規格	機能
`__cpp_lib_out_ptr`	`202106L`	(C++23)	`std::out_ptr`、std::inout_ptr
`__cpp_lib_out_ptr`	`202311L`	(C++26)	フリースタンディングな`std::out_ptr`とstd::inout_ptr

[編集] 例

[編集] 関連項目

inout_ptr_t (C++23)	外部のポインタセッターと相互運用し、スマートポインタから初期ポインタ値を取得し、破棄時にリセットします (クラステンプレート) [編集]
unique_ptr (C++11)	オブジェクトの所有権を唯一のものとするセマンティクスを持つスマートポインタ (クラステンプレート) [編集]
shared_ptr (C++11)	オブジェクトの所有権を共有するセマンティクスを持つスマートポインタ (クラステンプレート) [編集]

コンパイラサポート
フリースタンディングとホスト
言語
標準ライブラリ
標準ライブラリヘッダー
名前付き要件
機能テストマクロ (C++20)
言語サポートライブラリ
コンセプトライブラリ (C++20)
診断ライブラリ
メモリ管理ライブラリ
メタプログラミングライブラリ (C++11)
汎用ユーティリティライブラリ
コンテナライブラリ
イテレータライブラリ
Rangesライブラリ (C++20)
アルゴリズムライブラリ
文字列ライブラリ
テキスト処理ライブラリ
数値ライブラリ
日付と時刻ライブラリ
入出力ライブラリ
ファイルシステムライブラリ (C++17)
並行サポートライブラリ (C++11)
実行制御ライブラリ (C++26)
Technical specifications (技術仕様)
シンボルインデックス
外部ライブラリ

cppreference.com

名前空間

変種

表示

操作