[inout.ptr.t]

[Example 1: #include <memory> struct star_fish* star_fish_alloc(); int star_fish_populate(struct star_fish** ps, const char* description); struct star_fish_deleter { void operator() (struct star_fish* c) const noexcept; }; using star_fish_ptr = std::unique_ptr<star_fish, star_fish_deleter>; int main(int, char*[]) { star_fish_ptr peach(star_fish_alloc(); / ... / used, need to re-make int err = star_fish_populate(std::inout_ptr(peach), "caring clown-fish liker"); return err; }

A unique_ptr can be used with inout_ptr to be passed into an output pointer-style function.

The original value will be properly deleted according to the function it is used with and a new value reset in its place.

— end example]

🔗

namespace std { template<class Smart, class Pointer, class. Args> class inout_ptr_t { public: constexpr explicit inout_ptr_t(Smart&, Args..); inout_ptr_t(const inout_ptr_t&) = delete; constexpr ~inout_ptr_t(); constexpr operator Pointer*() const noexcept; operator void*() const noexcept; private: Smart& s; / exposition only tuple<Args..> a; / exposition only Pointer p; / exposition only }; }

Pointer shall meet the Cpp17NullablePointer requirements.

If Smart is a specialization of shared_ptr, the program is ill-formed.

[Note 1:

It is impossible to properly acquire unique ownership of the managed resource from a shared_ptr given its shared ownership model.

— end note]

Program-defined specializations of inout_ptr_t that depend on at least one program-defined type need not meet the requirements for the primary template.

Evaluations of the conversion functions on the same object may conflict ([intro.races]).

🔗

constexpr explicit inout_ptr_t(Smart& smart, Args.. args);

Effects: Initializes s with smart, a with std::forward<Args>(args)., and p to either

(6.1)
smart if is_pointer_v<Smart> is true,
(6.2)
otherwise, smart.get().

[Note 2:

The constructor is not noexcept to allow for a variety of non-terminating and safe implementation strategies.

For example, an intrusive pointer implementation with a control block can allocate in the constructor and safely fail with an exception.

— end note]

🔗

constexpr ~inout_ptr_t();

Let SP be POINTER_OF_OR(Smart, Pointer) ([memory.general]).

Let release-statement be s.release(); if an implementation does not call s.release() in the constructor.

Otherwise, it is empty.

Effects: Equivalent to:

(11.1)
apply([&](auto&. args) { s = Smart(static_cast<SP>(p), std::forward<Args>(args).); }, std::move(a)); if is_pointer_v<Smart> is true;
(11.2)
otherwise, release-statement; if (p) { apply([&](auto&. args) { s.reset(static_cast<SP>(p), std::forward<Args>(args).); }, std::move(a)); } if the expression s.reset(static_cast<SP>(p), std::forward<Args>(args).) is well-
formed;
(11.3)
otherwise, release-statement; if (p) { apply([&](auto&. args) { s = Smart(static_cast<SP>(p), std::forward<Args>(args).); }, std::move(a)); } if is_constructible_v<Smart, SP, Args..> is true;
(11.4)
otherwise, the program is ill-formed.

🔗

constexpr operator Pointer*() const noexcept;

Returns: addressof(const_cast<Pointer&>(p)).

🔗

operator void*() const noexcept;

Returns: A pointer value v such that:

(17.1)
the initial value *v is equivalent to static_cast<void*>(p) and
(17.2)
any modification of *v that is not followed by subsequent modification of *this affects the value of p during the destruction of *this, such that static_cast<void*>(p) == *v.

Remarks: Accessing *v outside the lifetime of *this has undefined behavior.

[Note 3:

reinterpret_cast<void*>(static_cast<Pointer*>(*this) can be a viable implementation strategy for some implementations.

— end note]