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	-	要适配的对象（通常是智能指针）的类型
Pointer	-	外部函数向其写入结果的对象（通常是原始指针）的类型
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 创建其临时对象，这会立即重置适配的智能指针。例如，给定一个 setter 函数和一个使用 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* 对象。

特性测试宏	值	Std	特性
`__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)	与外部指针 setter 互操作，从智能指针获取初始指针值，并在销毁时重置它 (类模板) [编辑]
unique_ptr (C++11)	具有唯一对象所有权语义的智能指针 (类模板) [编辑]
shared_ptr (C++11)	具有共享对象所有权语义的智能指针 (类模板) [编辑]