std::out_ptr_t(3)

🦋 std::out_ptr_t(3) — C++ Standard Libary 🦋

💖 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;

okay bestie, so out_ptr_t is here to adapt types like smart pointers for foreign functions that output their results through a Pointer* parameter (usually T** for some object type T) or a void** parameter. it's giving "bridge between my cute smart pointer and this raw C API" energy.

out_ptr_t captures extra arguments on construction, provides storage for the result that the foreign function writes into, and finally resets the adapted Smart object with that result plus the captured arguments when it gets destroyed. iconic cleanup behavior, honestly.

out_ptr_t behaves as if it holds these non-static data members:

• a Smart& reference, which is bound to the adapted object on construction,
• for every T in Args..., a member of type T, which is an argument captured on construction and used for resetting during destruction, and
• a member subobject 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. cute little control knob, no cap.

🧚 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 foreign function writes its result
• Args... — type of captured arguments used for resetting the adapted object

🛡️ 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. slay for custom smart pointer girlies 💅

🎀 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 (public member function)
• operator void** — (public member function) (C++23)

🫶 NON-MEMBER FUNCTIONS 🫶

• out_ptr — creates an out_ptr_t with an associated smart pointer and resetting arguments (C++23) (function template)

📝 NOTES 📝

out_ptr_t expects that the foreign functions do not use the value of the pointed-to Pointer, and only re-initialize it. The value of the smart pointer before adaption is not used. so don't expect it to peek at the old pointer, bestie.

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_setter(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 duration other than automatic storage duration, because such code is likely to produce dangling references and result in undefined behavior on destruction. bestie please keep it automatic, this is not the vibe for dangling references 😭

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 custom deleter later.

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

Feature-test macro tea ☕:

• __cpp_lib_out_ptr — 202106L — (C++23) — std::out_ptr, std::inout_ptr
• __cpp_lib_out_ptr — 202311L — (C++26) — freestanding std::out_ptr and std::inout_ptr

🍓 EXAMPLE 🍓

This section is incomplete. Reason: no example. yes bestie, the example section is literally empty, we love a mysterious icon 💀

👀 SEE ALSO 👀

• inout_ptr_t — interoperates with foreign pointer setters, obtains the initial pointer value from a smart pointer, and resets it on destruction (C++23) (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

mwah 💋 — from http://cppreference.com, dated 2024.06.10, for std::out_ptr_t(3) 🫶