# std::out_ptr_t

From cppreference.com
< cpp‎ | memory

Defined in header `<memory>` |  |
template< class Smart, class Pointer, class... Args > class out_ptr_t; |  | (since C++23)

`out_ptr_t` is used to adapt types such as smart pointers for foreign functions that output their results via a Pointer* (usually T** for some object type `T`) or void** parameter.

`out_ptr_t` captures additional arguments on construction, provides a storage for the result to which such an aforementioned foreign function writes, and finally resets the adapted `Smart` object with the result and the captured arguments when it is destroyed.

`out_ptr_t` behaves as if it holds following non-static data members:

- a Smart& reference, which is bound to the adapted object on construction,
- for every `T` in `Args...`, a member of type `T`, which is an argument captured on construction and used for resetting while destruction, and
- a member subobject that suitable for storing a `Pointer` within it and providing a void* object, where the `Pointer` or void* object is generally exposed to a foreign function for re-initialization.

Users can control whether each argument for resetting is captured by copy or by reference, by specifying an object type or a reference type in `Args...` respectively.

### Template parameters

Smart | - | the type of the object (typically a smart pointer) to adapt
Pointer | - | type of the object (typically a raw pointer) to which a foreign function writes its result
Args... | - | type of captured arguments used for resetting the adapted object
Type requirements
- `Pointer` must meet the requirements of NullablePointer.
- The program is ill-formed if `Smart` is a std::shared_ptr specialization and sizeof...(Args) == 0.

### Specializations

Unlike most class templates in the standard library, program-defined specializations of `out_ptr_t` that depend on at least one program-defined type need not meet the requirements for the primary template.

This license allows a program-defined specialization to expose the raw pointer stored within a non-standard smart pointer to foreign functions.

### Member functions

(constructor) (C++23) | constructs an `out_ptr_t` (public member function)
operator= [deleted](C++23) | `out_ptr_t` is not assignable (public member function)
(destructor) (C++23) | resets the adapted smart pointer (public member function)
operator Pointer*operator void** (C++23) | converts the `out_ptr_t` to the address of the storage for output (public member function)

### Non-member functions

out_ptr (C++23) | creates an `out_ptr_t` with an associated smart pointer and resetting arguments (function template)

### Notes

`out_ptr_t` expects that the foreign functions do not used the value of the pointed-to `Pointer`, and only re-initialize it. The value of the smart pointer before adaption is not used.

The typical usage of `out_ptr_t` is creating its temporary objects by std::out_ptr, which resets the adapted smart pointer immediately. E.g. given a setter function and a smart pointer of appropriate type declared with int foreign_setter(T**); and std::unique_ptr<T, D> up; respectively,

    int foreign_setter(T**);
    std::unique_ptr<T, D> up;

    if (int ec = foreign_setter(std::out_ptr(up)))
        return ec;

is roughly equivalent to

    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;

It is not recommended to create an `out_ptr_t` object of a storage duration other than automatic storage duration, because such code is likely to produce dangling references and result in undefined behavior on destruction.

`out_ptr_t` forbids the usage that would reset a std::shared_ptr without specifying a deleter, because it would call std::shared_ptr::reset and replace a custom deleter later.

Captured arguments are typically packed into a std::tuple<Args...>. Implementations may use different mechanism to provide the `Pointer` or void* object they need hold.

Feature-test macro | Value | Std | Comment
--- | --- | --- | ---
`__cpp_lib_out_ptr` | 202106L | (C++23) | `std::out_ptr`, std::inout_ptr

### Example

| This section is incomplete Reason: no example

### See also

inout_ptr_t (C++23) | interoperates with foreign pointer setters, obtains the initial pointer value from a smart pointer, and resets it on destruction (class template)
unique_ptr (C++11) | smart pointer with unique object ownership semantics (class template)
shared_ptr (C++11) | smart pointer with shared object ownership semantics (class template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/memory/out_ptr_t&oldid=151350"