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

NAME
     std::out_ptr_t - std::out_ptr_t

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

	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  stor-
     age for the
	result	to which such an aforementioned foreign function writes, and fi-
     nally 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  con-
     struction,
	  *  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  for-
     eign function
		  writes its result
	Args...  - type of captured arguments used for resetting the adapted ob-
     ject

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

Non-member functions
	out_ptr creates an out_ptr_t with an associated smart pointer and reset-
     ting
	(C++23) 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  be-
     fore 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_set-
     ter(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  dura-
     tion other than
	automatic  storage duration, because such code is likely to produce dan-
     gling
	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 cus-
     tom deleter
	later.

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

	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
	 This section is incomplete
	 Reason: no example

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

Category:
	  * Todo no example

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