STD::BASIC_STREAMBUF(3cxx)

📦
version 14-20240412 · 22 versions
, in ubuntu noble

💖 NAME 💖

okay bestie, meet std::basic_streambuf< _CharT, _Traits >(3cxx) — literally the actual work of input and output (interface). iconic.

✨ SYNOPSIS ✨

Include this:

#include <streambuf>

Inherited by these absolute legends:

std::basic_filebuf< _CharT, encoding_char_traits< _CharT >
>, std::basic_filebuf< _CharT, std::char_traits< _CharT > >,
std::basic_filebuf< char_type, traits_type >,
__gnu_cxx::stdio_sync_filebuf< _CharT, _Traits >, std::basic_filebuf<
_CharT, _Traits >, std::basic_stringbuf< _CharT, _Traits, _Alloc >, and
std::wbuffer_convert< _Codecvt, _Elem, _Tr >.

🌸 Public Types 🌸

  • typedef _CharT char_type
  • typedef _Traits traits_type
  • typedef traits_type::int_type int_type
  • typedef traits_type::pos_type pos_type
  • typedef traits_type::off_type off_type
  • typedef basic_streambuf< char_type, traits_type > __streambuf_type — This is a non-standard type. noted, bestie.

💅 Public Member Functions 💅

  • virtual ~basic_streambuf () — the destructor, and it deallocates no buffer space.
  • locale getloc () const — locale access, iykyk.
  • streamsize in_avail () — looking ahead into the stream.
  • locale pubimbue (const locale &__loc) — the entry point for imbue().
  • int_type sbumpc () — getting the next character.
  • int_type sgetc () — getting the next character.
  • streamsize sgetn (char_type *__s, streamsize __n) — entry point for xsgetn.
  • int_type snextc () — getting the next character.
  • int_type sputbackc (char_type __c) — pushing characters back into the input stream.
  • int_type sputc (char_type __c) — entry point for all single-character output functions.
  • streamsize sputn (const char_type *__s, streamsize __n) — entry point for all single-character output functions.
  • int_type sungetc () — moving backwards in the input stream.
  • basic_streambuf * pubsetbuf (char_type *__s, streamsize __n) — entry point(s) for derived buffer functions.
  • pos_type pubseekoff (off_type __off, ios_base::seekdir __way, ios_base::openmode __mode=ios_base::in|ios_base::out) — alters the stream position.
  • pos_type pubseekpos (pos_type __sp, ios_base::openmode __mode=ios_base::in|ios_base::out) — alters the stream position.
  • int pubsync () — calls the virtual sync function.

🦋 Protected Member Functions 🦋

  • basic_streambuf () — base constructor.
  • basic_streambuf (const basic_streambuf &)
  • void __safe_gbump (streamsize __n)
  • void __safe_pbump (streamsize __n)
  • void gbump (int __n) — moving the read position.
  • virtual void imbue (const locale &__loc) — changes translations.
  • basic_streambuf & operator= (const basic_streambuf &)
  • virtual int_type overflow (int_type __c=traits_type::eof()) — consumes data from the buffer; writes to the controlled sequence.
  • virtual int_type pbackfail (int_type __c=traits_type::eof()) — tries to back up the input sequence.
  • void pbump (int __n) — moving the write position.
  • virtual pos_type seekoff (off_type, ios_base::seekdir, ios_base::openmode=ios_base::in|ios_base::out) — alters the stream positions.
  • virtual pos_type seekpos (pos_type, ios_base::openmode=ios_base::in|ios_base::out) — alters the stream positions.
  • virtual basic_streambuf< char_type, _Traits > * setbuf (char_type *, streamsize) — manipulates the buffer.
  • void setg (char_type *__gbeg, char_type *__gnext, char_type *__gend) — setting the three read area pointers.
  • void setp (char_type *__pbeg, char_type *__pend) — setting the three write area pointers.
  • virtual streamsize showmanyc () — investigating the data available.
  • void swap (basic_streambuf &__sb)
  • virtual int sync () — synchronizes the buffer arrays with the controlled sequences.
  • virtual int_type uflow () — fetches more data from the controlled sequence.
  • virtual int_type underflow () — fetches more data from the controlled sequence.
  • virtual streamsize xsgetn (char_type *__s, streamsize __n) — multiple character extraction.
  • virtual streamsize xsputn (const char_type *__s, streamsize __n) — multiple character insertion.
  • char_type * eback () const — access to the get area.
  • char_type * gptr () const — access to the get area.
  • char_type * egptr () const — access to the get area.
  • char_type * pbase () const — access to the put area.
  • char_type * pptr () const — access to the put area.
  • char_type * epptr () const — access to the put area.

🎀 Protected Attributes 🎀

  • locale _M_buf_locale — current locale setting.
  • char_type * _M_in_beg — start of get area.
  • char_type * _M_in_cur — current read area.
  • char_type * _M_in_end — end of get area.
  • char_type * _M_out_beg — start of put area.
  • char_type * _M_out_cur — current put area.
  • char_type * _M_out_end — end of put area.

💜 Friends 💜

these are the friend declarations, copied exactly so nobody loses a single character:

template<bool _IsMove, typename _CharT2 > __gnu_cxx::__enable_if<
    __is_char< _CharT2 >::__value, _CharT2 * >::__type __copy_move_a2
    (istreambuf_iterator< _CharT2 >, istreambuf_iterator< _CharT2 >,
    _CharT2 *)
streamsize __copy_streambufs_eof (basic_streambuf *, basic_streambuf *,
    bool &)
void __istream_extract (istream &, char *, streamsize)
template<typename _CharT2 , typename _Distance > __gnu_cxx::__enable_if<
    __is_char< _CharT2 >::__value, void >::__type advance
    (istreambuf_iterator< _CharT2 > &, _Distance)
class basic_ios< char_type, traits_type >
class basic_istream< char_type, traits_type >
class basic_ostream< char_type, traits_type >
template<typename _CharT2 > __gnu_cxx::__enable_if< __is_char< _CharT2
    >::__value, istreambuf_iterator< _CharT2 > >::__type find
    (istreambuf_iterator< _CharT2 >, istreambuf_iterator< _CharT2 >,
    const _CharT2 &)
template<typename _CharT2 , typename _Traits2 , typename _Alloc >
    basic_istream< _CharT2, _Traits2 > & getline (basic_istream<
    _CharT2, _Traits2 > &, basic_string< _CharT2, _Traits2, _Alloc > &,
    _CharT2)
class istreambuf_iterator< char_type, traits_type >
template<typename _CharT2 , typename _Traits2 , typename _Alloc >
    basic_istream< _CharT2, _Traits2 > & operator>> (basic_istream<
    _CharT2, _Traits2 > &, basic_string< _CharT2, _Traits2, _Alloc > &)
class ostreambuf_iterator< char_type, traits_type >

🌈 Detailed Description 🌈

template<typename _CharT, typename _Traits>
class std::basic_streambuf< _CharT, _Traits >"The actual work of input
and output (interface).

🌸 Template Parameters 🌸

  • _CharT — type of character stream.
  • _Traits — traits for character type, defaults to char_traits<_CharT>.
No cap: this is a base class. Derived stream buffers each control a pair of character sequences: one for input, and one for output.

Section [27.5.1] of the standard describes the requirements and behavior of stream buffer classes. That section (three paragraphs) is reproduced here, for simplicity and accuracy.

  1. Stream buffers can impose various constraints on the sequences they control. Some constraints are:
    • The controlled input sequence can be not readable.
    • The controlled output sequence can be not writable.
    • The controlled sequences can be associated with the contents of other representations for character sequences, such as external files.
    • The controlled sequences can support operations directly to or from associated sequences.
    • The controlled sequences can impose limitations on how the program can read characters from a sequence, write characters to a sequence, put characters back into an input sequence, or alter the stream position.
  2. Each sequence is characterized by three pointers which, if non-null, all point into the same charT array object. The array object represents, at any moment, a (sub)sequence of characters from the sequence. Operations performed on a sequence alter the values stored in these pointers, perform reads and writes directly to or from associated sequences, and alter the stream position and conversion state as needed to maintain this subsequence relationship. The three pointers are:
    • the beginning pointer, or lowest element address in the array (called xbeg here);
    • the next pointer, or next element address that is a current candidate for reading or writing (called xnext here);
    • the end pointer, or first element address beyond the end of the array (called xend here).
  3. The following semantic constraints shall always apply for any set of three pointers for a sequence, using the pointer names given immediately above:
    • If xnext is not a null pointer, then xbeg and xend shall also be non-null pointers into the same charT array, as described above; otherwise, xbeg and xend shall also be null.
    • If xnext is not a null pointer and xnext < xend for an output sequence, then a write position is available. In this case, *xnext shall be assignable as the next element to write (to put, or to store a character value, into the sequence).
    • If xnext is not a null pointer and xbeg < xnext for an input sequence, then a putback position is available. In this case, xnext[-1] shall have a defined value and is the next (preceding) element to store a character that is put back into the input sequence.
    • If xnext is not a null pointer and xnext< xend for an input sequence, then a read position is available. In this case, *xnext shall have a defined value and is the next element to read (to get, or to obtain a character value, from the sequence).

🎀 Member Typedef Documentation 🎀

okay bestie, these are the lil nickname handles the class uses for its types — like the contacts in your phone so you don't have to type the whole government name every time 💅 a bunch of them are literally just the template parameters wearing a cute outfit.

  • __streambuf_type — full signature is basic_streambuf<char_type, traits_type> std::basic_streambuf< _CharT, _Traits >::__streambuf_type. Heads up: this is a non-standard type 🙈
  • char_type — full signature is _CharT std::basic_streambuf< _CharT, _Traits >::char_type. This is one of the standard types — they exist so there's a standardized way of referring to names of (or names dependent on) the template parameters, which are specific to the implementation ✨
  • int_type — full signature is traits_type::int_type std::basic_streambuf< _CharT, _Traits >::int_type. Also a standard type, same slay: standardized way of referring to names of (or names dependent on) the template parameters, which are specific to the implementation 💖
  • off_type — full signature is traits_type::off_type std::basic_streambuf< _CharT, _Traits >::off_type. Another standard type, giving you that standardized way of referring to names of (or names dependent on) the template parameters, which are specific to the implementation 🫶
  • pos_type — full signature is traits_type::pos_type std::basic_streambuf< _CharT, _Traits >::pos_type. Yet another standard type — standardized way of referring to names of (or names dependent on) the template parameters, which are specific to the implementation 🌸
  • traits_type — full signature is _Traits std::basic_streambuf< _CharT, _Traits >::traits_type. Standard type again, bestie — standardized way of referring to names of (or names dependent on) the template parameters, which are specific to the implementation 🦋

🧚 Constructor & Destructor Documentation 🧚

virtual std::basic_streambuf< _CharT, _Traits >::~basic_streambuf () [inline], [virtual]

The destructor. And the whole personality? It deallocates no buffer space. That's it, that's the vibe 💀 nothing gets freed here, she just leaves the group chat.

std::basic_streambuf< _CharT, _Traits >::basic_streambuf () [inline], [protected]

The base constructor 👑 Only called from derived constructors, and it sets up all the buffer data to zero, including the pointers described in the basic_streambuf class description. And because of that, lowkey:

  • the class starts with no read nor write positions available, and
  • this is not an error ✨ (deep breaths, it's fine)

💜 Member Function Documentation 💜

char_type * std::basic_streambuf< _CharT, _Traits >::eback () const [inline], [protected]

Your access point to the get area. Quick vibe check: these functions are only available to other protected functions, including derived classes 🔒

  • eback() returns the beginning pointer for the input sequence
  • gptr() returns the next pointer for the input sequence
  • egptr() returns the end pointer for the input sequence

References std::basic_streambuf< _CharT, _Traits >::_M_in_beg.

Referenced by std::basic_streambuf< _CharT, _Traits >::sputbackc(), and std::basic_streambuf< _CharT, _Traits >::sungetc().

char_type * std::basic_streambuf< _CharT, _Traits >::egptr () const [inline], [protected]

Access to the get area again, bestie — same three-pointer situation, and again these are only available to other protected functions, including derived classes 🔒

  • eback() returns the beginning pointer for the input sequence
  • gptr() returns the next pointer for the input sequence
  • egptr() returns the end pointer for the input sequence

References std::basic_streambuf< _CharT, _Traits >::_M_in_end.

Referenced by std::basic_streambuf< _CharT, _Traits >::in_avail(), std::basic_streambuf< _CharT, _Traits >::sbumpc(), std::basic_streambuf< _CharT, _Traits >::sgetc(), std::basic_stringbuf< _CharT, _Traits, _Alloc >::showmanyc(), and std::wbuffer_convert< _Codecvt, _Elem, _Tr >::underflow().

char_type * std::basic_streambuf< _CharT, _Traits >::epptr () const [inline], [protected]

Now we're on the put area — the output side of the operation 💅 protected-only as always, derived classes included 🔒

  • pbase() returns the beginning pointer for the output sequence
  • pptr() returns the next pointer for the output sequence
  • epptr() returns the end pointer for the output sequence

References std::basic_streambuf< _CharT, _Traits >::_M_out_end.

Referenced by std::basic_streambuf< _CharT, _Traits >::sputc().

void std::basic_streambuf< _CharT, _Traits >::gbump (int __n) [inline], [protected]

Moving the read position 🕺

Parameters

  • __n — The delta by which to move.

This just advances the read position without returning any data. It's giving "walk forward, don't touch anything" 🚶‍♀️

References std::basic_streambuf< _CharT, _Traits >::_M_in_cur.

Referenced by std::basic_streambuf< _CharT, _Traits >::sbumpc(), std::basic_streambuf< _CharT, _Traits >::sputbackc(), std::basic_streambuf< _CharT, _Traits >::sungetc(), and std::basic_streambuf< _CharT, _Traits >::uflow().

locale std::basic_streambuf< _CharT, _Traits >::getloc () const [inline]

Locale access 🌍✨

Returns — The current locale in effect.

If pubimbue(loc) has been called, then the most recent loc is returned. Otherwise the global locale in effect at the time of construction is returned.

References std::basic_streambuf< _CharT, _Traits >::_M_buf_locale.

Referenced by std::basic_streambuf< _CharT, _Traits >::pubimbue().

char_type * std::basic_streambuf< _CharT, _Traits >::gptr () const [inline], [protected]

Back to the get area trio, protected-only as ever (derived classes count too) 🔒

  • eback() returns the beginning pointer for the input sequence
  • gptr() returns the next pointer for the input sequence
  • egptr() returns the end pointer for the input sequence

References std::basic_streambuf< _CharT, _Traits >::_M_in_cur.

Referenced by std::basic_streambuf< _CharT, _Traits >::in_avail(), std::basic_streambuf< _CharT, _Traits >::sbumpc(), std::basic_streambuf< _CharT, _Traits >::sgetc(), std::basic_stringbuf< _CharT, _Traits, _Alloc >::showmanyc(), std::basic_streambuf< _CharT, _Traits >::sputbackc(), std::basic_streambuf< _CharT, _Traits >::sungetc(), std::basic_streambuf< _CharT, _Traits >::uflow(), and std::wbuffer_convert< _Codecvt, _Elem, _Tr >::underflow().

virtual void std::basic_streambuf< _CharT, _Traits >::imbue (const locale & __loc) [inline], [protected], [virtual]

Changes translations 🔤✨

Parameters

  • __loc — A new locale.

Translations done during I/O which depend on the current locale are changed by this call. The standard adds — and I quote — "Between invocations of this function a class derived from streambuf can safely cache results of calls to locale functions and to members of facets so obtained." So like, cache it while it's fresh, bestie 🧠

Note — Base class version does nothing 💀

Reimplemented in std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, and std::basic_filebuf< char_type, traits_type >.

Referenced by std::basic_streambuf< _CharT, _Traits >::pubimbue().

streamsize std::basic_streambuf< _CharT, _Traits >::in_avail () [inline]

Looking ahead into the stream 👀✨

Returns — The number of characters available.

If a read position is available, returns the number of characters available for reading before the buffer must be refilled. Otherwise returns the derived showmanyc(). Either way, you get a number and you get on with your day 🫶

References std::basic_streambuf< _CharT, _Traits >::egptr(), std::basic_streambuf< _CharT, _Traits >::gptr(), and std::basic_streambuf< _CharT, _Traits >::showmanyc().

virtual int_type std::basic_streambuf< _CharT, _Traits >::overflow (int_type __c = traits_type::eof()) [inline], [protected], [virtual]

Consumes data from the buffer; writes to the controlled sequence 🚰

Parameters

  • __c — An additional character to consume.

Returns — eof() to indicate failure, something else (usually __c, or not_eof())

Informally — and this is the version you actually remember — this function is called when the output buffer is full (or does not exist, as buffering need not actually be done). If a buffer exists, it is consumed, with some effect on the controlled sequence. (Typically, the buffer is written out to the sequence verbatim.) In either case, the character c is also written out, if __c is not eof().

For a formal definition of this function, see a good text such as Langer & Kreft, or [27.5.2.4.5]/3-7 📚 no cap, go read it.

A functioning output streambuf can be created by overriding only this function (no buffer area will be used). That's the whole hack 👑

Note — Base class version does nothing, returns eof() 💀

Reimplemented in std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, std::basic_filebuf< char_type, traits_type >, __gnu_cxx::stdio_sync_filebuf< _CharT, _Traits >, std::basic_stringbuf< _CharT, _Traits, _Alloc >, and std::wbuffer_convert< _Codecvt, _Elem, _Tr >.

Referenced by std::basic_streambuf< _CharT, _Traits >::sputc().

virtual int_type std::basic_streambuf< _CharT, _Traits >::pbackfail (int_type __c = traits_type::eof()) [inline], [protected], [virtual]

Tries to back up the input sequence ⏪😭 (she tries, okay?)

Parameters

  • __c — The character to be inserted back into the sequence.

Returns — eof() on failure, some other value on success

Postcondition — The constraints of gptr(), eback(), and pptr() are the same as for underflow().

Note — Base class version does nothing, returns eof() 💀

Reimplemented in std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, std::basic_filebuf< char_type, traits_type >, __gnu_cxx::stdio_sync_filebuf< _CharT, _Traits >, and std::basic_stringbuf< _CharT, _Traits, _Alloc >.

Referenced by std::basic_streambuf< _CharT, _Traits >::sputbackc(), and std::basic_streambuf< _CharT, _Traits >::sungetc().

char_type * std::basic_streambuf< _CharT, _Traits >::pbase () const [inline], [protected]

Put area access, round one 🎀 again: only available to other protected functions, including derived classes 🔒

  • pbase() returns the beginning pointer for the output sequence
  • pptr() returns the next pointer for the output sequence
  • epptr() returns the end pointer for the output sequence

References std::basic_streambuf< _CharT, _Traits >::_M_out_beg.

Referenced by: std::basic_stringbuf< _CharT, _Traits, _Alloc >::str().

💅 pbump — moving the write position

template<typename _CharT , typename _Traits > void std::basic_streambuf< _CharT, _Traits >::pbump (int __n) [inline], [protected]

Okay so this one just advances the write position — it does not return any data. Literally just shifts where you're writing. ✨

  • __n — the delta by which to move. 💫

References: std::basic_streambuf< _CharT, _Traits >::_M_out_cur.

Referenced by: std::basic_streambuf< _CharT, _Traits >::sputc().

🫶 pptr — access to the put area

template<typename _CharT , typename _Traits > char_type * std::basic_streambuf< _CharT, _Traits >::pptr () const [inline], [protected]

Access to the put area, bestie. These functions are only available to other protected functions, including derived classes. 🔒

  • pbase() returns the beginning pointer for the output sequence
  • pptr() returns the next pointer for the output sequence
  • epptr() returns the end pointer for the output sequence

References: std::basic_streambuf< _CharT, _Traits >::_M_out_cur.

Referenced by: std::basic_streambuf< _CharT, _Traits >::sputc().

🌸 pubimbue — entry point for imbue()

template<typename _CharT , typename _Traits > locale std::basic_streambuf< _CharT, _Traits >::pubimbue (const locale & __loc) [inline]

This is the public entry point for imbue(). It calls the derived imbue(__loc). 🎀

  • __loc — the new locale.

Returns: the previous locale.

References: std::basic_streambuf< _CharT, _Traits >::_M_buf_locale, std::basic_streambuf< _CharT, _Traits >::getloc(), and std::basic_streambuf< _CharT, _Traits >::imbue().

🦋 pubseekoff — alters the stream position

template<typename _CharT , typename _Traits > pos_type std::basic_streambuf< _CharT, _Traits >::pubseekoff (off_type __off, ios_base::seekdir __way, ios_base::openmode __mode = ios_base::in | ios_base::out) [inline]

Alters the stream position. It calls the virtual seekoff function. ✨

  • __off — offset.
  • __way — value for ios_base::seekdir.
  • __mode — value for ios_base::openmode.

References: std::basic_streambuf< _CharT, _Traits >::seekoff().

🎀 pubseekpos — alters the stream position, position edition

template<typename _CharT , typename _Traits > pos_type std::basic_streambuf< _CharT, _Traits >::pubseekpos (pos_type __sp, ios_base::openmode __mode = ios_base::in | ios_base::out) [inline]

Alters the stream position. Calls the virtual seekpos function. 💫

  • __sp — position.
  • __mode — value for ios_base::openmode.

References: std::basic_streambuf< _CharT, _Traits >::seekpos().

🌈 pubsetbuf — entry points for derived buffer functions

template<typename _CharT , typename _Traits > basic_streambuf * std::basic_streambuf< _CharT, _Traits >::pubsetbuf (char_type * __s, streamsize __n) [inline]

Entry points for derived buffer functions. The public versions of pubfoo dispatch to the protected derived foo member functions, passing the arguments (if any) and returning the result unchanged. No cap. 🫶

References: std::basic_streambuf< _CharT, _Traits >::setbuf().

⭐ pubsync — calls virtual sync function

template<typename _CharT , typename _Traits > int std::basic_streambuf< _CharT, _Traits >::pubsync () [inline]

Calls the virtual sync function. Simple as that. 💅

References: std::basic_streambuf< _CharT, _Traits >::sync().

Referenced by: std::basic_istream< _CharT, _Traits >::sync().

🔥 sbumpc — getting the next character

template<typename _CharT , typename _Traits > int_type std::basic_streambuf< _CharT, _Traits >::sbumpc () [inline]

Getting the next character. If the input read position is available, it returns that character and increments the read pointer; otherwise it calls and returns uflow(). 😭

Returns: the next character, or eof.

References: std::basic_streambuf< _CharT, _Traits >::egptr(), std::basic_streambuf< _CharT, _Traits >::gbump(), std::basic_streambuf< _CharT, _Traits >::gptr(), and std::basic_streambuf< _CharT, _Traits >::uflow().

Referenced by: std::basic_istream< char >::get(), std::basic_istream< _CharT, _Traits >::ignore(), std::basic_streambuf< _CharT, _Traits >::snextc(), and std::basic_istream< char >::sync().

💀 seekoff — alters the stream positions

template<typename _CharT , typename _Traits > virtual pos_type std::basic_streambuf< _CharT, _Traits >::seekoff (off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out) [inline], [protected], [virtual]

Alters the stream positions. Each derived class provides its own appropriate behavior. 👑

Note: the base class version does nothing, returns a pos_type that represents an invalid stream position.

Reimplemented in: std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, std::basic_filebuf< char_type, traits_type >, and std::basic_stringbuf< _CharT, _Traits, _Alloc >.

Referenced by: std::basic_streambuf< _CharT, _Traits >::pubseekoff().

🌟 seekpos — alters the stream positions, position edition

template<typename _CharT , typename _Traits > virtual pos_type std::basic_streambuf< _CharT, _Traits >::seekpos (pos_type, ios_base::openmode = ios_base::in | ios_base::out) [inline], [protected], [virtual]

Alters the stream positions. Each derived class provides its own appropriate behavior. Same vibe as seekoff, different arg. 💫

Note: the base class version does nothing, returns a pos_type that represents an invalid stream position.

Reimplemented in: std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, std::basic_filebuf< char_type, traits_type >, and std::basic_stringbuf< _CharT, _Traits, _Alloc >.

Referenced by: std::basic_streambuf< _CharT, _Traits >::pubseekpos().

🧚 setbuf — manipulates the buffer

template<typename _CharT , typename _Traits > virtual basic_streambuf< char_type, _Traits > * std::basic_streambuf< _CharT, _Traits >::setbuf (char_type *, streamsize) [inline], [protected], [virtual]

Manipulates the buffer. Each derived class provides its own appropriate behavior. See the next-to-last paragraph of https://gcc.gnu.org/onlinedocs/libstdc++/manual/streambufs.html#io.streambuf.buffering for more on this function. 🫶

Note: the base class version does nothing, returns this.

Reimplemented in: std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, std::basic_filebuf< char_type, traits_type >, and std::basic_stringbuf< _CharT, _Traits, _Alloc >.

Referenced by: std::basic_streambuf< _CharT, _Traits >::pubsetbuf().

🍓 setg — setting the three read area pointers

template<typename _CharT , typename _Traits > void std::basic_streambuf< _CharT, _Traits >::setg (char_type * __gbeg, char_type * __gnext, char_type * __gend) [inline], [protected]

Sets the read area pointers. 📚

  • __gbeg — a pointer.
  • __gnext — a pointer.
  • __gend — a pointer.
Postcondition: __gbeg == eback(), __gnext == gptr(), and __gend == egptr()

References: std::basic_streambuf< _CharT, _Traits >::_M_in_beg, std::basic_streambuf< _CharT, _Traits >::_M_in_cur, and std::basic_streambuf< _CharT, _Traits >::_M_in_end.

Referenced by: std::wbuffer_convert< _Codecvt, _Elem, _Tr >::wbuffer_convert().

🎀 setp — setting the three write area pointers

template<typename _CharT , typename _Traits > void std::basic_streambuf< _CharT, _Traits >::setp (char_type * __pbeg, char_type * __pend) [inline], [protected]

Sets the write area pointers. Yes bestie, the original says “three” even though there are two args — we keep it exactly as written. 💅

  • __pbeg — a pointer.
  • __pend — a pointer.
Postcondition: __pbeg == pbase(), __pbeg == pptr(), and __pend == epptr()

References: std::basic_streambuf< _CharT, _Traits >::_M_out_beg, std::basic_streambuf< _CharT, _Traits >::_M_out_cur, and std::basic_streambuf< _CharT, _Traits >::_M_out_end.

Referenced by: std::wbuffer_convert< _Codecvt, _Elem, _Tr >::wbuffer_convert().

🦋 sgetc — getting the next character, but make it peek

template<typename _CharT , typename _Traits > int_type std::basic_streambuf< _CharT, _Traits >::sgetc () [inline]

Getting the next character. If the input read position is available, it returns that character; otherwise it calls and returns underflow(). It does not move the read position after fetching the character. 👀

Returns: the next character, or eof.

References: std::basic_streambuf< _CharT, _Traits >::egptr(), std::basic_streambuf< _CharT, _Traits >::gptr(), and std::basic_streambuf< _CharT, _Traits >::underflow().

Referenced by: std::basic_istream< char >::get(), std::basic_istream< _CharT, _Traits >::get(), std::basic_istream< _CharT, _Traits >::ignore(), std::basic_istream< char >::readsome(), and std::basic_streambuf< _CharT, _Traits >::snextc().

🌸 sgetn — entry point for xsgetn

template<typename _CharT , typename _Traits > streamsize std::basic_streambuf< _CharT, _Traits >::sgetn (char_type * __s, streamsize __n) [inline]

Entry point for xsgetn. 🫶

  • __s — a buffer area.
  • __n — a count.

Returns xsgetn(__s,__n). The effect is to fill __s[0] through __s[__n-1] with characters from the input sequence, if possible.

References: std::basic_streambuf< _CharT, _Traits >::xsgetn().

👑 showmanyc — investigating the data available

template<typename _CharT , typename _Traits > virtual streamsize std::basic_streambuf< _CharT, _Traits >::showmanyc () [inline], [protected], [virtual]

Investigating the data available. 🔍

Returns: an estimate of the number of characters available in the input sequence, or -1.

If it returns a positive value, then successive calls to underflow() will not return traits::eof() until at least that number of characters have been supplied. If showmanyc() returns -1, then calls to underflow() or uflow() will fail. [27.5.2.4.3]/1

Note: the base class version does nothing, returns zero. The standard adds that the intention is not only that the calls [to underflow or uflow] will not return eof() but that they will return immediately. The standard adds that the morphemes of showmanyc are es-how-many-see, not show-manic.

Reimplemented in: std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, std::basic_filebuf< char_type, traits_type >, and std::basic_stringbuf< _CharT, _Traits, _Alloc >.

Referenced by: std::basic_streambuf< _CharT, _Traits >::in_avail().

💫 snextc — getting the next character, next-next edition

template<typename _CharT , typename _Traits > int_type std::basic_streambuf< _CharT, _Traits >::snextc () [inline]

Getting the next character. Calls sbumpc(), and if that function returns traits::eof(), so does this function. Otherwise, sgetc(). 😭

Returns: the next character, or eof.

References: std::basic_streambuf< _CharT, _Traits >::sbumpc(), and std::basic_streambuf< _CharT, _Traits >::sgetc().

Referenced by: std::basic_istream< char >::get(), std::basic_istream< char >::ignore(), std::basic_istream< char >::operator>>(), and std::basic_istream< char >::putback().

🎀 sputbackc — pushing characters back into the input stream

template<typename _CharT , typename _Traits > int_type std::basic_streambuf< _CharT, _Traits >::sputbackc (char_type __c) [inline]

Pushing characters back into the input stream. Put it back, bestie. ↩️

  • __c — the character to push back.

Returns: the previous character, if possible.

Similar to sungetc(), but __c is pushed onto the stream instead of the previous character. So if this works, the next character fetched from the input stream is gonna be __c — that's it, that's the whole vibe ✨

References: std::basic_streambuf< _CharT, _Traits >::eback(), std::basic_streambuf< _CharT, _Traits >::gbump(), std::basic_streambuf< _CharT, _Traits >::gptr(), and std::basic_streambuf< _CharT, _Traits >::pbackfail().

Referenced by: std::basic_istream< _CharT, _Traits >::putback().

🍓 sputc

template<typename _CharT , typename _Traits > int_type std::basic_streambuf< _CharT, _Traits >::sputc (char_type __c) [inline]

The entry point for all single-character output functions. Iconic behavior, honestly. It's one of the two public output functions.

Parameters:

  • __c — a character to output, bestie.

Returns: __c, if possible.

So here's the tea 🫖: if a write position is available for the output sequence (i.e. the buffer is not full), it stores __c in that position, increments the position, and returns traits::to_int_type(__c). If a write position is not available, it hands things off and returns overflow(__c).

References: std::basic_streambuf< _CharT, _Traits >::epptr(), std::basic_streambuf< _CharT, _Traits >::overflow(), std::basic_streambuf< _CharT, _Traits >::pbump(), and std::basic_streambuf< _CharT, _Traits >::pptr().

Referenced by: std::wbuffer_convert< _Codecvt, _Elem, _Tr >::overflow().

💜 sputn

template<typename _CharT , typename _Traits > streamsize std::basic_streambuf< _CharT, _Traits >::sputn (const char_type * __s, streamsize __n) [inline]

The entry point for all single-character output functions — yes, that's literally what the docs say, even though it's the multi-character one 😭 we don't question the ancestors.

Parameters:

  • __s — a buffer read area.
  • __n — a count.

One of the two public output functions.

Returns: xsputn(__s,__n). The effect is to write __s[0] through __s[__n-1] to the output sequence, if possible. Slay.

References: std::basic_streambuf< _CharT, _Traits >::xsputn().

🦋 sungetc

template<typename _CharT , typename _Traits > int_type std::basic_streambuf< _CharT, _Traits >::sungetc () [inline]

Moving backwards in the input stream — time travel, but make it buffered 💫

Returns: the previous character, if possible.

If a putback position is available, it decrements the input pointer and returns that character. Otherwise it calls and returns pbackfail(). The effect: it ungets the last character gotten.

References: std::basic_streambuf< _CharT, _Traits >::eback(), std::basic_streambuf< _CharT, _Traits >::gbump(), std::basic_streambuf< _CharT, _Traits >::gptr(), and std::basic_streambuf< _CharT, _Traits >::pbackfail().

🌸 sync

template<typename _CharT , typename _Traits > virtual int std::basic_streambuf< _CharT, _Traits >::sync () [inline], [protected], [virtual]

Synchronizes the buffer arrays with the controlled sequences. Very "let me get my life together" of it.

Returns: -1 on failure.

Each derived class provides its own appropriate behavior — including the definition of what "failure" even means. Your fave is bespoke, ok?

Note: the base class version does nothing and returns zero. Literally no thoughts, head empty 🙈

Reimplemented in: std::wbuffer_convert< _Codecvt, _Elem, _Tr >, __gnu_cxx::stdio_sync_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, and std::basic_filebuf< char_type, traits_type >.

Referenced by: std::basic_streambuf< _CharT, _Traits >::pubsync().

🎀 uflow

template<typename _CharT , typename _Traits > virtual int_type std::basic_streambuf< _CharT, _Traits >::uflow () [inline], [protected], [virtual]

Fetches more data from the controlled sequence. Snack time 🍓

Returns: the first character from the pending sequence.

Informally, this does the same thing as underflow(), and in fact it's required to call that function. It also returns the new character, like underflow() does. But — plot twist — this one also moves the read position forward by one. Main character behavior honestly.

Reimplemented in: __gnu_cxx::stdio_sync_filebuf< _CharT, _Traits >.

References: std::basic_streambuf< _CharT, _Traits >::gbump(), std::basic_streambuf< _CharT, _Traits >::gptr(), and std::basic_streambuf< _CharT, _Traits >::underflow().

Referenced by: std::basic_streambuf< _CharT, _Traits >::sbumpc().

🔥 underflow

template<typename _CharT , typename _Traits > virtual int_type std::basic_streambuf< _CharT, _Traits >::underflow () [inline], [protected], [virtual]

Fetches more data from the controlled sequence — the OG.

Returns: the first character from the pending sequence.

Informally: this function gets called when the input buffer is exhausted (or doesn't even exist, because buffering need not actually be done — no cap, some buffers are just vibes). If a buffer exists, it gets refilled. Either way, the next available character is returned, or traits::eof() to indicate a null pending sequence.

For a formal definition of the pending sequence, go read a good text such as Langer & Kreft, or [27.5.2.4.3]/7-14. Academic queen 👑

A functioning input streambuf can be created by overriding only this function (no buffer area will be used, we're going minimal). For an example, see https://gcc.gnu.org/onlinedocs/libstdc++/manual/streambufs.html.

Note: the base class version does nothing and returns eof(). Again: no thoughts, head empty 💀

Reimplemented in: std::wbuffer_convert< _Codecvt, _Elem, _Tr >, __gnu_cxx::stdio_sync_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, std::basic_filebuf< char_type, traits_type >, and std::basic_stringbuf< _CharT, _Traits, _Alloc >.

Referenced by: std::basic_streambuf< _CharT, _Traits >::sgetc(), and std::basic_streambuf< _CharT, _Traits >::uflow().

🌈 xsgetn

template<typename _CharT , typename _Traits > streamsize std::basic_streambuf< _CharT, _Traits >::xsgetn (char_type * __s, streamsize __n) [protected], [virtual]

Multiple character extraction. We're grabbing several characters, not just one — glow up 💅

Parameters:

  • __s — a buffer area.
  • __n — maximum number of characters to assign.

Returns: the number of characters assigned.

It fills __s[0] through __s[__n-1] with characters from the input sequence, as if by sbumpc(). It stops when either __n characters have been copied, or when traits::eof() would be copied. Both conditions, no exceptions, bye.

It is expected that derived classes provide a more efficient implementation by overriding this definition — i.e. the base version is giving "good enough", and your derived class can absolutely do better.

Reimplemented in: std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, and std::basic_filebuf< char_type, traits_type >.

References: std::min().

Referenced by: std::basic_streambuf< _CharT, _Traits >::sgetn().

⭐ xsputn

template<typename _CharT , typename _Traits > streamsize std::basic_streambuf< _CharT, _Traits >::xsputn (const char_type * __s, streamsize __n) [protected], [virtual]

Multiple character insertion — the put-side sibling of xsgetn, and yes they're both icons.

Parameters:

  • __s — a buffer area.
  • __n — maximum number of characters to write.

Returns: the number of characters written.

It writes __s[0] through __s[__n-1] to the output sequence, as if by sputc(). It stops when either n characters have been copied, or when sputc() would return traits::eof(). (Note that it's a lowercase n right there in the docs — fr fr, character for character, we keep it 💖)

It is expected that derived classes provide a more efficient implementation by overriding this definition.

Reimplemented in: std::basic_filebuf< _CharT, _Traits >, std::basic_filebuf< _CharT, encoding_char_traits< _CharT > >, std::basic_filebuf< _CharT, std::char_traits< _CharT > >, and std::basic_filebuf< char_type, traits_type >.

References: std::min().

Referenced by: std::basic_streambuf< _CharT, _Traits >::sputn().

🗂️ Member Data Documentation

These are the [protected] data members — the backstage crew, the ones making everything work while the public functions get all the credit 🫶

_M_buf_locale

locale std::basic_streambuf< _CharT, _Traits >::_M_buf_locale — [protected]

Current locale setting. It's giving international queen 🌍

Referenced by: std::basic_filebuf< _CharT, _Traits >::basic_filebuf(), std::basic_streambuf< _CharT, _Traits >::getloc(), and std::basic_streambuf< _CharT, _Traits >::pubimbue().

_M_in_beg

char_type* std::basic_streambuf< _CharT, _Traits >::_M_in_beg — [protected]

Start of get area. The beginning of the reading era.

Referenced by: std::basic_streambuf< _CharT, _Traits >::eback(), and std::basic_streambuf< _CharT, _Traits >::setg().

_M_in_cur

char_type* std::basic_streambuf< _CharT, _Traits >::_M_in_cur — [protected]

Current read area. Where you're at right now, bestie 📍

Referenced by: std::basic_streambuf< _CharT, _Traits >::gbump(), std::basic_streambuf< _CharT, _Traits >::gptr(), and std::basic_streambuf< _CharT, _Traits >::setg().

_M_in_end

char_type* std::basic_streambuf< _CharT, _Traits >::_M_in_end — [protected]

End of get area. The limit, the boundary, the "that's enough reading for today" line.

Referenced by: std::basic_streambuf< _CharT, _Traits >::egptr(), and std::basic_streambuf< _CharT, _Traits >::setg().

_M_out_beg

char_type* std::basic_streambuf< _CharT, _Traits >::_M_out_beg — [protected]

Start of put area. The writing era begins here ✍️

Referenced by: std::basic_streambuf< _CharT, _Traits >::pbase(), and std::basic_streambuf< _CharT, _Traits >::setp().

_M_out_cur

char_type* std::basic_streambuf< _CharT, _Traits >::_M_out_cur — [protected]

Current put area. Where the pen is right now.

Referenced by: std::basic_streambuf< _CharT, _Traits >::pbump(), std::basic_streambuf< _CharT, _Traits >::pptr(), and std::basic_streambuf< _CharT, _Traits >::setp().

_M_out_end

char_type* std::basic_streambuf< _CharT, _Traits >::_M_out_end — [protected]

End of put area. The drop-dead "no more writing here" line, periodt.

Referenced by: std::basic_streambuf< _CharT, _Traits >::epptr(), and std::basic_streambuf< _CharT, _Traits >::setp().

👑 Author

Generated automatically by Doxygen for libstdc++ from the source code. Not a human author — a machine did this, and it still ate 💅

That's the whole page bestie, you made it to the end 🎉 The footer is the libstdc++ auto-Doxygen situation, 3cxx manpage, and the version string literally got chopped off mid-template-arguments — iconic truncation energy honestly 😭 Source and version are libstdc++'s own docs, straight from the source code, and the date is whatever Doxygen felt like stamping that day. Go forth and buffer responsibly 🌈🦋💖

📦 where this page comes from