std::basic_...f::pbackfail(3)

💖 NAME 💖

okay so this page is std::basic_...f::pbackfail(3) in the C++ Standard Libary manual — yes, that spelling is what the manual says, we’re not fixing it, we’re just folding it in here like a cute lil sticky note 🫶. The actual main character is std::basic_stringbuf::pbackfail, and the NAME line is literally std::basic_stringbuf::pbackfail — std::basic_stringbuf::pbackfail, periodt 💅.

🦋 Synopsis 🦋

This protected virtual function is called by the public functions basic_streambuf::sungetc and basic_streambuf::sputbackc (which, in turn, are called by basic_istream::unget and basic_istream::putback).

protected:
virtual int_type pbackfail( int_type c = Traits::eof() )

1. The caller is requesting that the get area is backed up by one character (pbackfail() is called with no arguments or with Traits::eof() as the argument).
   • a) First, checks if there is a putback position, and if there really isn’t, fails. (stringbuf has no external character source to re-read.)
   • b) If the caller was wrong and the putback position is in fact available, simply decrements basic_streambuf::gptr(), e.g. by calling gbump(-1).
2. The caller attempts to putback a different character from the one retrieved earlier (pbackfail() is called with the character that needs to be put back), in which case:
   • a) First, checks if there is a putback position, and if there isn’t, fails.
   • b) Then checks what character is in the putback position. If the character held there is already equal to c, as determined by Traits::eq(to_char_type(c), gptr()[-1]), then simply decrements basic_streambuf::gptr().
   • c) Otherwise, if the buffer is open for reading only, fails.
   • d) Otherwise, if the buffer is open for writing (mode && std::ios_base::out is nonzero), then decrements basic_streambuf::gptr() and writes c to the location pointed to gptr() after adjustment.

🎀 Parameters 🎀

• c — the character to put back, or Traits::eof() to indicate that backing up of the get area is requested.

🌈 Return value 🌈

• c on success, except if c was Traits::eof(), in which case Traits::not_eof(c) is returned.
• Traits::eof() on failure.

💀 Example 💀

This section is incomplete Reason: no example

🔥 See also 🔥

• pbackfail — puts a character back into the input sequence, possibly modifying the input sequence. [virtual] (virtual protected member function of std::basic_streambuf<CharT,Traits>)
• sungetc — moves the next pointer in the input sequence back by one (public member function of std::basic_streambuf<CharT,Traits>)
• sputbackc — puts one character back in the input sequence (public member function of std::basic_streambuf<CharT,Traits>)
• unget — unextracts a character (public member function of std::basic_istream<CharT,Traits>)
• putback — puts a character into input stream (public member function of std::basic_istream<CharT,Traits>)

🏷️ Category 🏷️

• Todo — no example

source/version/date cuteness: http://cppreference.com · 2024.06.10 — bye bestie, slay your buffers 💅🫶