basic_streambuf::underflow

Protected, virtual function to extract the current element from the input stream.

Syntax

virtual int_type underflow( );

Return Value

The current element.

Remarks

The protected virtual member function endeavors to extract the current element ch from the input stream, without advancing the current stream position, and return it as traits_type::to_int_type(ch). It can do so in various ways:

• If a read position is available, ch is the element stored in the read position. For more information on this, see the Remarks section of the basic_streambuf Class.

• It can make a read position available by allocating new or additional storage for the input buffer, then reading in, from some external source, one or more elements. For more information on this, see the Remarks section of the basic_streambuf Class.

If the function cannot succeed, it returns traits_type::eof() or throws an exception. Otherwise, it returns the current element in the input stream, converted as previously described. The default behavior is to return traits_type::eof().

The virtual underflow function, with the sync and overflow functions, defines the characteristics of the streambuf-derived class. Each derived class might implement underflow differently, but the interface with the calling stream class is the same.

The underflow function is most frequently called by public streambuf functions like sgetc and sgetn when the get area is empty, but other classes, including the stream classes, can call underflow anytime.

The underflow function supplies the get area with characters from the input source. If the get area contains characters, underflow returns the first character. If the get area is empty, it fills the get area and returns the next character (which it leaves in the get area). If there are no more characters available, then underflow returns EOF and leaves the get area empty.

In the strstreambuf class, underflow adjusts the egptr pointer to access storage that was dynamically allocated by a call to overflow.

Requirements

Header: <streambuf>

Namespace: std

See Also

basic_streambuf Class
iostream Programming
iostreams Conventions