std::basic_...eam::putback(3)

okay so bestie, welcome to the C++ Standard Libary manual 💖 — this is the std::basic_...eam::putback(3) page, and it's all about the std::basic_istream::putback member function. no cap, it's giving “put a character back” energy. 🫶

👑 NAME 👑

std::basic_istream::putback — literally std::basic_istream::putback; that's the name, bestie. 💅

📜 Synopsis 📜

Here's the signature, copy it exactly:

basic_istream& putback( char_type ch );

Okay so what it does: puts the character ch back to the input stream so the next extracted character will be ch. ✨

First clears eofbit, then behaves as UnformattedInputFunction. After constructing and checking the sentry object, if rdbuf() is not null, calls rdbuf()->sputbackc(ch), which calls rdbuf()->pbackfail(ch) if ch does not equal the most recently extracted character.

If rdbuf() is null or if rdbuf->sputbackc(ch) returns Traits::eof(), calls setstate(badbit).

In any case, sets the gcount() counter to zero. periodt. 💀

🎀 Parameters 🎀

• ch — character to put into input stream.

🫶 Return value 🫶

It returns *this. that's it, that's the return value, slay. ✨

😭 Exceptions 😭

failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state.

If an internal operation throws an exception, it is caught and badbit is set. If exceptions() is set for badbit, the exception is rethrown.

⚠️ bestie, this is the “things went bad and exceptions are configured to yell” zone. read the flags, okay? 🫡

💻 Example 💻

Demonstrates the difference between modifying and non-modifying putback(). 🦋

// Run this code

#include <iostream>
#include <sstream>

int main()
{
    std::stringstream s1("Hello, world"); // IO stream
    s1.get();
    if (s1.putback('Y')) // modifies the buffer
        std::cout << s1.rdbuf() << '\n';
    else
        std::cout << "putback failed\n";

    std::cout << "--\n";

    std::istringstream s2("Hello, world"); // input-only stream
    s2.get();
    if (s2.putback('Y')) // cannot modify input-only buffer
        std::cout << s2.rdbuf() << '\n';
    else
        std::cout << "putback failed\n";
    s2.clear();

    std::cout << "--\n";

    if (s2.putback('H')) // non-modifying putback
        std::cout << s2.rdbuf() << '\n';
    else
        std::cout << "putback failed\n";
}

📤 Output 📤

Yello, world
--
putback failed
--
Hello, world

👀 See also 👀

• 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).
• peek — reads the next character without extracting it (public member function).

okay bye bestie 💖 source/version: http://cppreference.com · date: 2024.06.10 · page: std::basic_...eam::putback(3) 💅✨