std::strstr...::underflow(3)

Okay bestie, welcome to std::strstr...::underflow(3) from the C++ Standard Libary (yes, that’s the manual name, and we’re rolling with it 💅). This is the std::strstreambuf::underflow page, and it’s giving vintage-buffer energy fr fr.

🌸 NAME 🌸

std::strstreambuf::underflow — std::strstreambuf::underflow (the name is literally the name again, and honestly? iconic).

✨ Synopsis ✨

          protected:                     (deprecated in C++98)
          virtual int_type underflow();  (removed in C++26)

Big yikes: deprecated in C++98 and removed in C++26. But the vibe of the function is still this: it reads the next character from the get area of the buffer.

Okay so, if the input sequence has a read position available (gptr() < egptr()), it returns (unsigned char)(*gptr()). Slay.

Otherwise, if pptr() is not null and pptr() > egptr() — meaning there is a put area and it is located after the get area — it extends the end of the get area to include the characters that were recently written into the put area. How? By incrementing egptr() to some value between gptr() and pptr(), and then it returns (unsigned char)(*gptr()). No cap.

Otherwise, it returns EOF to indicate failure. Periodt. 💀

🎀 Parameters 🎀

• (none) — literally none, bestie. Zero. Nada. 🫶

💅 Return value 💅

The next character in the get area, (unsigned char)(*gptr()), on success. EOF on failure. That’s the whole vibe check.

🔥 Example 🔥

Here’s the code, bestie — exact and unbothered:

       // Run this code

        #include <iostream>
        #include <strstream>

        struct mybuf : std::strstreambuf
        {
            int_type overflow(int_type c)
            {
                std::cout << "Before overflow(): size of the get area is " <<
       egptr()-eback()
                          << " size of the put area is " << epptr()-pbase() <<
       '\n';
                int_type rc = std::strstreambuf::overflow(c);
                std::cout << "After overflow(): size of the get area is " <<
       egptr()-eback()
                          << " size of the put area is " << epptr()-pbase() <<
       '\n';
                return rc;
            }

            int_type underflow()
            {
                std::cout << "Before underflow(): size of the get area is " <<
       egptr()-eback()
                          << " size of the put area is " << epptr()-pbase() <<
       '\n';
                int_type ch = std::strstreambuf::underflow();
                std::cout << "After underflow(): size of the get area is " <<
       egptr()-eback()
                          << " size of the put area is " << epptr()-pbase() <<
       '\n';
                if (ch == EOF)
                    std::cout << "underflow() returns EOF\n";
                else
                    std::cout << "underflow() returns '" << char(ch) << "'\n";
                return ch;
            }
        };

        int main()
        {
            mybuf sbuf; // read-write dynamic strstreambuf
            std::iostream stream(&sbuf);

            int n;
            stream >> n;
            stream.clear();
            stream << "123";
            stream >> n;
            std::cout << n << '\n';
        }

🌈 Possible output: 🌈

        Before underflow(): size of the get area is 0 size of the put area is 0
        After underflow(): size of the get area is 0 size of the put area is 0
        underflow() returns EOF
        Before overflow(): size of the get area is 0 size of the put area is 0
        After overflow(): size of the get area is 0 size of the put area is 32
        Before underflow(): size of the get area is 0 size of the put area is
       32
        After underflow(): size of the get area is 3 size of the put area is 32
        underflow() returns '1'
        Before underflow(): size of the get area is 3 size of the put area is
       32
        After underflow(): size of the get area is 3 size of the put area is 32
        underflow() returns EOF
        123

👑 See also 👑

• underflow reads characters from the associated input sequence to the get area [virtual] (virtual protected member function of std::basic_streambuf<CharT,Traits>)
• underflow returns the next character available in the input sequence [virtual] (virtual protected member function of std::basic_stringbuf<CharT,Traits,Allocator>)
• underflow reads from the associated file [virtual] (virtual protected member function of std::basic_filebuf<CharT,Traits>)
• sgetc reads one character from the input sequence without advancing the sequence (public member function of std::basic_streambuf<CharT,Traits>)
• get extracts characters (public member function of std::basic_istream<CharT,Traits>)

💖 source/version: http://cppreference.com • date: 2024.06.10 💖