home | help 
std::out_ptr(3) 	       C++ Standard Libary		 std::out_ptr(3)

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 be-
     low) 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 ex-
     pects 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)

http://cppreference.com 	   2024.06.10			 std::out_ptr(3)
home | help