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，則程式格式錯誤。

與標準庫中的大多數類模板不同，依賴於至少一個程式定義型別的 out_ptr_t 的程式定義特化不需要滿足主模板的要求。

此許可允許程式定義特化將儲存在非標準智慧指標中的原始指標暴露給外部函式。

(建構函式) (C++23)	構造一個 `out_ptr_t` (公開成員函式)
operator= [已刪除](C++23)	`out_ptr_t` 不可賦值 (公開成員函式)
(解構函式) (C++23)	重置適配的智慧指標 (公開成員函式)
operator Pointeroperator void* (C++23)	將 `out_ptr_t` 轉換為輸出儲存的地址 (公開成員函式)

(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)	具有共享物件所有權語義的智慧指標 (類模板) [編輯]

目錄