NAME¶

std::out_ptr - std::out_ptr

Synopsis¶

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

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 creates an inout_ptr_t with an associated smart pointer
(C++23) and resetting arguments
(function template)
make_unique
make_unique_for_overwrite creates a unique pointer that manages a new object
(C++14) (function template)
(C++20)
make_shared creates a shared pointer that manages a new object
make_shared_for_overwrite (function template)
(C++20)