std::strstreambuf::freeze(3)

💅 std::strstreambuf::freeze(3) 💅

C++ Standard Libary, bestie — this is the std::strstreambuf::freeze page, and it’s giving tiny toggle, big memory consequences. 👑

🌸 NAME 🌸

std::strstreambuf::freeze — okay so this is the freeze-status setter for a std::strstreambuf, and she is iconic but also a little retired.

✨ Synopsis ✨

void freeze( bool freezefl = true );  (deprecated in C++98)
                                      (removed in C++26)

Real talk: if the buffer uses dynamic allocation, this sets the frozen status of the stream to freezefl. 💖

While the stream is frozen, overflow() will not reallocate the buffer, and the destructor will not deallocate the buffer — which means a memory leak. 😭 Not a vibe.

🎀 Parameters 🎀

• freezefl — the new value to set the freeze status to.

🌈 Return value 🌈

(none) — no return value, periodt. 🫶

🦋 Notes 🦋

Every call to str() freezes the stream to preserve the validity of the pointer it returns. ✨ So if you want the destructor to deallocate the buffer, freeze(false) needs to be called explicitly. No cap.

🍓 Example 🍓

In this example, initial allocation of the underlying array was for 16 bytes. Run this code, bestie:

#include <iostream>
#include <strstream>

int main()
{
    {
        std::strstream dyn; // dynamically-allocated read/write buffer
        dyn << "Test: " << 1.23; // note: no std::ends to demonstrate append behavior
        std::cout << "dynamic buffer holds " << dyn.pcount() << " characters: '";
        std::cout.write(dyn.str(), dyn.pcount()) << "'\n";
        // the buffer is now frozen, further output will not make the buffer grow
        dyn << "more output, hopefully enough to run out of the allocated space"
            << std::ends;
        std::cout << "After more output, it holds "
                  << dyn.pcount() << " characters: '" << dyn.str() << "'\n";
        dyn.freeze(false); // unfreeze before destructor
    } // memory freed by the destructor

    {
        char arr[20];
        std::ostrstream st(arr, sizeof arr); // fixed-size buffer
        st << 1.23; // note: no std::ends to demonstrate append behavior
        std::cout << "static buffer holds "
                  << st.pcount() << " characters: '";
        std::cout.write(st.str(), st.pcount());
        std::cout << "'\n";
        st << "more output, hopefully enough to run out of the allocated space"
           << std::ends;
        std::cout << "static buffer holds "
                  << st.pcount() << " characters: '";
        std::cout.write(st.str(), st.pcount());
        std::cout << "'\n";
    } // nothing to deallocate, no need to unfreeze,
}

💜 Output 💜

dynamic buffer holds 10 characters: 'Test: 1.23'
After more output, it holds 16 characters: 'Test: 1.23more o'
static buffer holds 4 characters: '1.23'
static buffer holds 20 characters: '1.23more output, hop'

🔥 See also 🔥

• freeze — disables/enables automatic reallocation (public member function of std::strstream)
• freeze — disables/enables automatic reallocation (public member function of std::ostrstream)
• destructor [virtual] — destructs a strstreambuf object, optionally deallocating the character array (virtual public member function)
• overflow [virtual] — appends a character to the output sequence, may reallocate or initially allocate the buffer if dynamic and not frozen (virtual protected member function)

signed off with love from http://cppreference.com, version/date 2024.06.10, page std::strstreambuf::freeze(3) 🫶✨