std::basic_...buf::setbuf(3)

💅 std::basic_...buf::setbuf(3) — from the C++ Standard Libary manual, bestie 💅

okay so this is the glow-up of the C++ Standard Libary page for std::basic_...buf::setbuf(3) (and yes, “Libary” is literally how it’s spelled in the manual — we keep the lore 💀). It’s giving “buffer setup but make it virtual,” and we are keeping every single deet.

🎀 NAME 🎀

• std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf — and the description is, no cap, the exact same string again: std::basic_streambuf::pubsetbuf,std::basic_streambuf::setbuf.

✨ Synopsis ✨

okay so here’s the signature situation, bestie:

public:
(1)
basic_streambuf<CharT, Traits>* pubsetbuf( char_type* s,
std::streamsize n )
protected:
virtual basic_streambuf<CharT, Traits>* setbuf( char_type* s,
std::streamsize n (2)
)

1. Calls setbuf(s, n) of the most derived class.
2. The base class version of this function has no effect. The derived classes may override this function to allow removal or replacement of the controlled character sequence (the buffer) with a user-provided array, or for any other implementation-specific purpose.

🫶 Parameters 🫶

• s — pointer to the first CharT in the user-provided buffer
• n — the number of CharT elements in the user-provided buffer

🔁 Return value 🔁

1. The return value of setbuf(s, n).
2. this

🌸 Example 🌸

Provides a 10k buffer for reading. On linux, the strace utility may be used to observe the actual number of bytes read.

// Run this code

#include <fstream>
#include <iostream>
#include <string>

int main()
{
    int cnt = 0;
    std::ifstream file;
    char buf[1024 * 10 + 1];

    file.rdbuf()->pubsetbuf(buf, sizeof buf);

    file.open("/usr/share/dict/words");

    for (std::string line; getline(file, line);)
        ++cnt;

    std::cout << cnt << '\n';
}

💬 Possible output 💬

356010

🩹 Defect reports 🩹

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

• DR: LWG 158
• Applied to: C++98
• Behavior as published: the default behavior of setbuf was only specified as no-op
• Correct behavior: specified for all cases if gptr() is not null and not equal to egptr()

👀 See also 👀

• setbuf — attempts to replace the controlled character sequence with an array [virtual] (virtual protected member function of std::basic_stringbuf<CharT,Traits,Allocator>)
• setbuf — provides user-supplied buffer or turns this filebuf unbuffered [virtual] (virtual protected member function of std::basic_filebuf<CharT,Traits>)
• setbuf — attempts to replace the controlled character sequence with an array [virtual] (virtual protected member function of std::strstreambuf)
• setbuf — sets the buffer for a file stream (function)

source/version + date, bb: http://cppreference.com, 2024.06.10, std::basic_...buf::setbuf(3) — mwah 💋✨