std::return...rary_buffer(3)

💖 NAME 💖

okay bestie, this is std::return...rary_buffer(3) from the C++ Standard Libary manual — yes, the header really spells it “Libary,” and we are respecting the canon. The NAME entry is:

std::return_temporary_buffer - std::return_temporary_buffer

which is giving “I contain multitudes (the same name twice)” energy. Slay.

✨ Synopsis ✨

Defined in header <memory>:

template< class T >                    (deprecated in C++17)
void return_temporary_buffer( T* p );  (removed in C++20)

Deallocates the storage referenced by p. That’s the whole job, and it does it.

⚠️ If p is not a pointer value returned by an earlier call to std::get_temporary_buffer, or has been invalidated by an intervening std::return_temporary_buffer call, the behavior is undefined. Not me messing around with random pointers 💀

🌸 Parameters 🌸

• p — the pointer referring to the storage to be deallocated (the page literally says declloated, and honestly same 😭).

🫶 Return value 🫶

(none) — it’s a whole lot of nothing, bestie. No return value, no drama.

💀 Exceptions 💀

Throws nothing. Not a single throw. calm.

🎀 Example 🎀

       // Run this code

        #include <algorithm>
        #include <iostream>
        #include <iterator>
        #include <memory>
        #include <string>

        int main()
        {
            const std::string s[] = {"string", "1", "test", "..."};
            const auto p = std::get_temporary_buffer<std::string>(4);
            // requires that p.first is passed to return_temporary_buffer
            // (beware of early exit points and exceptions), or better use:
            std::unique_ptr<std::string, void(*)(std::string*)>
       on_exit(p.first,
            [](std::string* p)
            {
                std::cout << "returning temporary buffer...\n";
                std::return_temporary_buffer(p);
            });

            std::copy(s, s + p.second,
                      std::raw_storage_iterator<std::string*,
       std::string>(p.first));
            // has same effect as: std::uninitialized_copy(s, s + p.second,
       p.first);
            // requires that each string in p is individually destroyed
            // (beware of early exit points and exceptions)

            std::copy(p.first, p.first + p.second,
                      std::ostream_iterator<std::string>{std::cout, "\n"});

            std::for_each(p.first, p.first + p.second, [](std::string& e)
            {
                e.~basic_string<char>();
            }); // same as: std::destroy(p.first, p.first + p.second);

            // manually reclaim memory if unique_ptr-like technique is not
       used:
            // std::return_temporary_buffer(p.first);
        }

This example is doing the absolute most: it grabs temporary storage, wraps the cleanup in a std::unique_ptr with a custom deleter so the buffer gets returned even if things go sideways, copies strings in with std::raw_storage_iterator, prints them, manually destroys each string with e.~basic_string<char>(); — same as std::destroy(p.first, p.first + p.second); — and comments that you’d manually reclaim memory with std::return_temporary_buffer(p.first); if you’re not using the unique_ptr-like technique. Responsible queen behavior.

🍓 Output 🍓

string
1
test
...
returning temporary buffer...

🧚 Defect reports 🧚

The following behavior-changing defect reports were applied retroactively to previously published C++ standards:

• DR LWG 2072 — Applied to: C++98. Behavior as published: the storage allocated by std::get_temporary_buffer could be deallocated multiple times. Correct behavior: the behavior is undefined in this case.

👑 See also 👑

• get_temporary_buffer — obtains uninitialized storage (deprecated in C++17) (function template) (removed in C++20).

that’s the page, bestie 🫶 source/version: http://cppreference.com; date: 2024.06.10. go forth and return those temporary buffers with main character energy ✨💅