std::out_ptr

From cppreference.com
< cpp‎ | memory‎ | out ptr t
C++
Memory management library
(exposition only*)
Uninitialized memory algorithms
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++17)
(C++17)
(C++17)
(C++20)
Constrained uninitialized
memory algorithms
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
C Library
Allocators
(C++11)
(C++23)
(C++11)
(C++11)
(C++20)
(C++20)
(C++20)
(C++11)
(C++17)
Memory resources
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
Garbage collection support
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
Uninitialized storage
(until C++20*)
(until C++20*)
(until C++20*)
Explicit lifetime management
(C++23)(C++23)
std::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

  • 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
  • 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

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

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