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

💅 NAME 💅

std::basic_filebuf::pbackfail — yes bestie, that's literally the whole name, it's giving "I am the function and I know it" ✨

So before we even get into it: this page lives in the C++ Standard Libary manual (that spelling? not mine, I'm just the messenger 🫶), and it's page std::basic_...f::pbackfail(3). Periodt.

---

✨ SYNOPSIS ✨

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

🌸 DESCRIPTION 🌸

Okay so, this is a protected virtual function, and the way it gets summoned is lowkey indirect: the public functions basic_streambuf::sungetc and basic_streambuf::sputbackc call it — and those, in turn, get called by basic_istream::unget and basic_istream::putback. It's giving backstage crew energy: never on stage, runs everything. 👑

Here's the vibe check on the two situations:

1. The caller wants the get area backed up by one character, and pbackfail() gets called with no arguments. In that case, this function re-reads the file starting one byte earlier and decrements basic_streambuf::gptr(), e.g. by calling gbump(-1).
2. The caller is trying to put back a different character from the one retrieved earlier — so pbackfail() is called with the character that needs to be put back. Then:
   • First, it checks if there's a putback position, and if there isn't, it backs up the get area by re-reading the file starting one byte earlier.
   • Then it checks what character is actually sitting 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 it simply decrements basic_streambuf::gptr(). Easy. Slay. 💅
   • Otherwise, if the buffer is allowed to modify its own get area, it decrements basic_streambuf::gptr() and writes c to the location pointed to by gptr() after the adjustment.

🫶 Big important note: this function never modifies the file — only the get area of the in-memory buffer. The file itself stays untouched, unbothered, flourishing.

😭 Also: if the file is not open (is_open()==false), this function returns Traits::eof() immediately. No file, no service, no discussion.

---

🎀 PARAMETERS 🎀

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

⭐ RETURN VALUE ⭐

• c on success — except when c was Traits::eof(), in which case Traits::not_eof(c) is what comes back at you.
• Traits::eof() on failure. 🙈

🦋 EXAMPLE 🦋

This section is incomplete.

Reason: no example.

(yeah. that's it. that's the example section. we move. 💀)

🌈 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

---

okay that's the whole page bestie, go put those characters back 💜

🧚 Sign-off time: this was std::basic_...f::pbackfail(3) from http://cppreference.com, dated 2024.06.10. Iconic. No cap. ✨👑