# std::out_ptr

From cppreference.com
< cpp‎ | memory‎ | out ptr t

Defined in header `<memory>` |  |
template< class Pointer = void, class Smart, class... Args > auto out_ptr( Smart& s, Args&&... args ); |  | (since C++23)

Returns an `std::out_ptr_t` with deduced template arguments that captures arguments for resetting by reference.

The program is ill-formed if construction of the return value (see below) is ill-formed.

### Parameters

s | - | the object (typically a smart pointer) to adapt
args... | - | the arguments for resetting to capture

### Return value

std::out_ptr_t<Smart, P, Args&&>(s, std::forward<Args>(args)...), where `P` is

- `Pointer`, if `Pointer` is not same as void. Otherwise,
- Smart::pointer, if it is valid and denotes a type. Otherwise,
- Smart::element_type*, if Smart::element_type is valid and denotes a type. Otherwise,
- std::pointer_traits<Smart>::element_type*.

### Notes

Users may specify the template argument for the template parameter `Pointer`, in order to interoperate with foreign functions that take a Pointer*.

As all arguments for resetting are captured by reference, the returned `out_ptr_t` should be a temporary object destroyed at the end of the full-expression containing the call to the foreign function, in order to avoid dangling references.

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

### Example

Use `std::out_ptr` to adapt a smart pointer for `sqlite3_open`, which expects a `sqlite3**` as an out parameter.

Run this code

    #include <memory>
    #include <sqlite3.h>

    int main()
    {
        auto close_db = [](sqlite3* db) { sqlite3_close(db); };

        {
            // open an in-memory database, and manage its lifetime with std::unique_ptr
            std::unique_ptr<sqlite3, decltype(close_db)> up;
            sqlite3_open(":memory:", std::out_ptr(up));

            sqlite3* db = up.get();
            // do something with db ...
        }
        {
            // same as above, but use a std::shared_ptr
            std::shared_ptr<sqlite3> sp;
            sqlite3_open(":memory:", std::out_ptr(sp, close_db));

            sqlite3* db = sp.get();
            // do something with db ...
        }
    }

### See also

inout_ptr (C++23) | creates an `inout_ptr_t` with an associated smart pointer and resetting arguments (function template)
make_uniquemake_unique_for_overwrite (C++14)(C++20) | creates a unique pointer that manages a new object (function template)
make_sharedmake_shared_for_overwrite (C++20) | creates a shared pointer that manages a new object (function template)

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