std::inout_ptr(3)

💖 NAME 💖

Okay so this is the std::inout_ptr(3) page from the C++ Standard Libary — yes, the header spells it like that bestie, we are not editing the lore — and the NAME section is literally std::inout_ptr — std::inout_ptr. Self-titled album energy, iconic.

🦋 Synopsis 🦋

Defined in header <memory>

template< class Pointer = void, class Smart, class... Args >
auto inout_ptr( Smart& s, Args&&... args );

(since C++23)

It returns an inout_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 below) is ill-formed. So yeah, that's a hard no from the compiler 💀.

🌸 Parameters 🌸

• s — the object (typically a smart pointer) to adapt.
• args... — the arguments for resetting to capture.

🎀 Return value 🎀

It gives you:

std::inout_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*. That's the customization moment, iykyk.

As all arguments for resetting are captured by reference, the returned inout_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.

🚨 Dangling references are not the vibe. Keep that temporary alive only until the end of the full-expression, periodt.

Feature-test macro tea ☕:

• Feature-test macro __cpp_lib_out_ptr; Value 202106L; Std (C++23); Feature std::out_ptr, std::inout_ptr
• Feature-test macro __cpp_lib_out_ptr; Value 202311L; Std (C++26); Feature freestanding std::out_ptr and std::inout_ptr

💀 Example 💀

This section is incomplete
Reason: no example

Not the page having zero examples 😭. It literally says it's incomplete, so no invented demo from me.

🌈 See also 🌈

• out_ptr (C++23) — creates an out_ptr_t with an associated smart pointer and resetting arguments (function template).
• make_unique (C++14) — (function template).
• make_unique_for_overwrite (C++20) — creates a unique pointer that manages a new object (function template).
• make_shared — creates a shared pointer that manages a new object (function template).
• make_shared_for_overwrite (C++20) — (function template).

🏷️ Category 🏷️

• Todo no example

---

Okay bestie, that's the whole page. Source is http://cppreference.com, version/date stamp is 2024.06.10, and the manual page is std::inout_ptr(3). Go forth and reset responsibly 💅✨