std::basic_stringbuf::underflow

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Input/output library

I/O manipulators

C-style I/O

Buffers

basic_streambuf

basic_filebuf

basic_stringbuf

strstreambuf (deprecated)

basic_syncbuf (C++20)

Streams

Abstractions

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

File I/O

basic_ifstream

basic_ofstream

basic_fstream

String I/O

basic_istringstream

basic_ostringstream

basic_stringstream

Array I/O

istrstream (deprecated)

ostrstream (deprecated)

strstream (deprecated)

Synchronized Output

basic_osyncstream (C++20)

Types

streamoff

streamsize

fpos

Error category interface

iostream_category (C++11)

io_errc (C++11)

std::basic_stringbuf

Public member functions

basic_stringbuf::basic_stringbuf

basic_stringbuf::operator= (C++11)

basic_stringbuf::swap (C++11)

basic_stringbuf::str

Protected member functions

basic_stringbuf::underflow

basic_stringbuf::pbackfail

basic_stringbuf::overflow

basic_stringbuf::setbuf

basic_stringbuf::seekoff

basic_stringbuf::seekpos

Non-member functions

swap(std::basic_stringbuf) (C++11)

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.

Parameters

(none)

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.

Example

Run this code

#include <sstream>
#include <iostream>

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';
    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';
}

Possible output:

Before underflow(): get area size is 3  put area size is 3
After underflow(): get area size is 3  put area size is 3
underflow() returns EOF
123
Before overflow(): get area size is 3  the put area size is 3
After overflow(): get area size is 4  put area size is 35
Before underflow(): get area size is 4  put area size is 35
After underflow(): get area size is 6  put area size is 35
underflow() returns '5'
Before underflow(): get area size is 6  put area size is 35
After underflow(): get area size is 6  put area size is 35
underflow() returns EOF
456

See also

underflow [virtual]	reads characters from the associated input sequence to the get area (virtual protected member function of std::basic_streambuf)
underflow [virtual]	reads from the associated file (virtual protected member function of std::basic_filebuf)
underflow [virtual]	reads a character from the input sequence without advancing the next pointer (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)