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

💜 std::basic_...f::underflow(3) 💜

okay so bestie, welcome to the C++ Standard Libary page for std::basic_...f::underflow(3) — yes, “Libary” with the typo, we are not fixing it, it's part of the lore. This one is a protected virtual member function, and it's lowkey iconic for the stringbuf girlies. Buckle up. 🦋

---

🌸 NAME 🌸

std::basic_stringbuf::underflow — std::basic_stringbuf::underflow

---

✨ Synopsis ✨

this is a protected virtual member function, so it's giving “for subclasses only” energy:

protected:
virtual int_type underflow()

Reads the next character from the get area of the buffer. Specifically:

1. If the input sequence has a read position available (egptr() > gptr()), returns Traits::to_int_type(*gptr()).
2. Otherwise, if pptr() > egptr() (some characters were inserted into the stream since the last time overflow() changed egptr()), then extends the end of the get area to include the most recently inserted characters, by changing egptr() to equal pptr(), and then returns Traits::to_int_type(*gptr()).
3. Otherwise, returns Traits::eof().

Any character in the buffer which has been initialized, regardless of whether it originated from the string passed in the constructor or was appended by overflow(), is considered to be part of the input sequence. no cap. 💅

---

🎀 Parameters 🎀

(none) — literally no parameters, bestie. 🫶

---

💖 Return value 💖

Traits::to_int_type(*gptr()) (the next character to read in the get area) in case of success, or Traits::eof() in case of failure. That's the whole return-value arc. ✅

---

🧚 Example 🧚

run this code, bestie:

       // Run this code

        #include <iostream>
        #include <sstream>

        struct mybuf : std::stringbuf
        {
            mybuf(const std::string& new_str,
                  std::ios_base::openmode which = std::ios_base::in |
       std::ios_base::out)
                : std::stringbuf(new_str, which) {}

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

            int_type underflow()
            {
                std::cout << "Before underflow(): get area size is " << egptr()
       - eback()
                          << ", put area size is " << epptr() - pbase() <<
       '\n';
                int_type ch = std::stringbuf::underflow();
                std::cout << "After underflow():  get area size is " << egptr()
       - eback()
                          << ", put area size 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("123"); // read-write stream
            std::iostream stream(&sbuf);
            int n;
            stream >> n; // calls sgetc() four times
                         // three calls return the characters '1', '2', '3'
                         // the fourth call, gptr() == egptr() and underflow()
       is called
                         // underflow returns EOF
            std::cout << "n = " << n << '\n';
            stream.clear(); // clear the eofbit

            stream << "123456"; // sputc() is called 6 times
                                // first three calls store "123" in the
       existing buffer
                                // 4th call finds that pptr() == epptr() and
       calls overflow()
                                // overflow() grows the buffer and sets egptr()
       to 4
                                // 5th and 6th calls store '5' and '6',
       advancing pptr()

            stream >> n; // calls sgetc() 4 times
                         // 1st call returns the '4' that was made available by
       overflow()
                         // on the 2nd call, egptr() == egptr() and underflow()
       is called
                         // underflow advances egptr() to equal pptr() (which
       is 6)
                         // 3rd sgetc() returns '6'
                         // 4th sgetc() finds gptr() == egptr(), calls
       underflow()
                         // underflow() returns EOF

            std::cout << "n = " << n << '\n';
        }

🌈 Possible output 🌈

Before underflow(): get area size is 3, put area size is 15
After underflow():  get area size is 3, put area size is 15
underflow() returns EOF
n = 123
Before underflow(): get area size is 3, put area size is 15
After underflow():  get area size is 6, put area size is 15
underflow() returns '4'
Before underflow(): get area size is 6, put area size is 15
After underflow():  get area size is 6, put area size is 15
underflow() returns EOF
n = 456

---

💀 Defect reports 💀

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. so yes, retroactive tea:

• LWG 432 — applied to C++98. Behavior as published: it was unclear whether characters appended by overflow() are considered to be part of the input sequence. Correct behavior: made clear.

---

👑 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 reads from the associated file — [virtual] (virtual protected member function of std::basic_filebuf<CharT,Traits>)
• underflow reads a character from the input sequence without advancing the next pointer — [virtual] (virtual protected member function of std::strstreambuf)
• sgetc reads one character from the input sequence without advancing the sequence — (public member function of std::basic_streambuf<CharT,Traits>)

---

okay that's the whole page, bestie! 💅 source: http://cppreference.com · version/date: 2024.06.10 · page: std::basic_...f::underflow(3) · bye 🫶