std::out_ptr(3)

🦋 std::out_ptr(3) 🦋

Manual-name moment: this page lives in the C++ Standard Libary manual — yes, bestie, that's the manual name from the header folded in near the top, not the whole header line copied. 💅

✨ NAME ✨

std::out_ptr - std::out_ptr — periodt, that's the NAME section. Self-titled icon behavior, no cap. 👑

🌸 Synopsis 🌸

Defined in header <memory>
template< class Pointer = void, class Smart, class... Args >  (since C++23)
auto out_ptr( Smart& s, Args&&... args );

It returns an std::out_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. Keep that in your notes, bestie — it's giving “compiler said no” energy.

🎀 Parameters 🎀

• s — the object (typically a smart pointer) to adapt. Main character energy: it's the thing getting adapted, fr fr.
• args... — the arguments for resetting to capture. All the resetting lore goes here.

💅 Return value 💅

The return value is:

std::out_ptr_t<Smart, P, Args&&>(s, std::forward<Args>(args)...)

...where P is chosen like this, in order:

• 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 Pointer-slot lore, iykyk. ✨

As all arguments for resetting are captured by reference, the returned out_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. This is the serious part, bestie — do not let it hang around like an unread group chat. 😭

Feature-test macro tea ☕:

• __cpp_lib_out_ptr — value 202106L, std C++23, feature: std::out_ptr, std::inout_ptr.
• __cpp_lib_out_ptr — value 202311L, std C++26, feature: freestanding std::out_ptr and std::inout_ptr.

🌈 Example 🌈

Use std::out_ptr to adapt a smart pointer for sqlite3_open, which expects a sqlite3** as an out parameter. Slay, foreign-function interop. 🧚

// Run this code

#include <memory>
#include <sqlite3.h>

int main()
{
    auto close_db = [](sqlite3* db) { sqlite3_close(db); };

    {
        // open an in-memory database, and manage its lifetime with std::unique_ptr
        std::unique_ptr<sqlite3, decltype(close_db)> up;
        sqlite3_open(":memory:", std::out_ptr(up));

        sqlite3* db = up.get();
        // do something with db ...
    }
    {
        // same as above, but use a std::shared_ptr
        std::shared_ptr<sqlite3> sp;
        sqlite3_open(":memory:", std::out_ptr(sp, close_db));

        sqlite3* db = sp.get();
        // do something with db ...
    }
}

🌟 See also 🌟

• inout_ptr (C++23) — creates an inout_ptr_t with an associated smart pointer and resetting arguments (function template).
• make_unique (C++14) — creates a unique pointer that manages a new object (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) — creates a shared pointer that manages a new object (function template).

---

Okay bestie, that's the page. Footer tea for the very end: source/version http://cppreference.com, date 2024.06.10, page std::out_ptr(3) — mwah 💋✨