|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
| Non-member functions | ||||
Defined in header <memory> | ||
template<class Smart,class Pointer,class...Args> class out_ptr_t; | (since C++23) | |
out_ptr_t is used to adapt types such as smart pointers for foreign functions that output their results via aPointer* (usuallyT** for some object typeT) orvoid** parameter.
out_ptr_t captures additional arguments on construction, provides storage for the result to which such an aforementioned foreign function writes, and finally resets the adaptedSmart 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:
Smart& reference, which is bound to the adapted object on construction,T inArgs..., a member of typeT, which is an argument captured on construction and used for resetting while destruction, andPointer within it and providing avoid* object, where thePointer orvoid* 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 inArgs... respectively.
Contents |
| Smart | - | the type of the object (typically a smart pointer) to adapt |
| Pointer | - | type of the object (typically a raw pointer) to which a foreign function writes its result |
| Args... | - | type of captured arguments used for resetting the adapted object |
| Type requirements | ||
-Pointer must meet the requirements ofNullablePointer. | ||
-The program is ill-formed ifSmart is astd::shared_ptr specialization andsizeof...(Args)==0. | ||
Unlike most class templates in the standard library,program-defined specializations ofout_ptr_t that depend on at least oneprogram-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.
(C++23) | constructs anout_ptr_t(public member function) |
operator= [deleted](C++23) | out_ptr_t is not assignable(public member function) |
(C++23) | resets the adapted smart pointer (public member function) |
converts theout_ptr_t to the address of the storage for output(public member function) |
(C++23) | creates anout_ptr_t with an associated smart pointer and resetting arguments(function template)[edit] |
out_ptr_t expects that the foreign functions do not used the value of the pointed-toPointer, and only re-initialize it. The value of the smart pointer before adaption is not used.
The typical usage ofout_ptr_t is creating its temporary objects bystd::out_ptr, which resets the adapted smart pointer immediately. E.g. given a setter function and a smart pointer of appropriate type declared withint foreign_setter(T**); andstd::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 anout_ptr_t object of astorage duration other than automatic storage duration, because such code is likely to produce dangling references and result in undefined behavior on destruction.
out_ptr_t forbids the usage that would reset astd::shared_ptr without specifying a deleter, because it would callstd::shared_ptr::reset and replace a custom deleter later.
Captured arguments are typically packed into astd::tuple<Args...>. Implementations may use different mechanism to provide thePointer orvoid* 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) | freestandingstd::out_ptr andstd::inout_ptr |
| This section is incomplete Reason: no example |
(C++23) | interoperates with foreign pointer setters, obtains the initial pointer value from a smart pointer, and resets it on destruction (class template)[edit] |
(C++11) | smart pointer with unique object ownership semantics (class template)[edit] |
(C++11) | smart pointer with shared object ownership semantics (class template)[edit] |
