std::basic_stringbuf::pbackfail

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms 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 in C++98)

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 in C++98)

ostrstream (deprecated in C++98)

strstream (deprecated in C++98)

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 pbackfail( int_type c = Traits::eof() )

This protected virtual function is called by the public functions basic_streambuf::sungetc and basic_streambuf::sputbackc (which, in turn, are called by basic_istream::unget and basic_istream::putback).

1) The caller is requesting that the get area is backed up by one character (pbackfail() is called with no arguments or with Traits::eof() as the argument)

a) First, checks if there is a putback position, and if there really isn't, fails. (stringbuf has no external character source to re-read)

b) If the caller was wrong and the putback position is in fact available, simply decrements basic_streambuf::gptr(), e.g. by calling gbump(-1).

2) The caller attempts to putback a different character from the one retrieved earlier (pbackfail() is called with the character that needs to be put back), in which case

a) First, checks if there is a putback position, and if there isn't, fails.

b) Then checks what character is in the putback position. If the character held there is already equal to c, as determined by Traits::eq(to_char_type(c), gptr()[-1]), then simply decrements basic_streambuf::gptr().

c) Otherwise, if the buffer is open for reading only, fails.

d) Otherwise, if the buffer is open for writing (mode && std::ios_base::out is nonzero), then decrements basic_streambuf::gptr() and writes c to the location pointed to gptr() after adjustment.

Parameters

c

-

the character to put back, or Traits::eof() to indicate that backing up of the get area is requested

Return value

c on success except if c was Traits::eof(), in which case Traits::not_eof(c) is returned.

Traits::eof() on failure.

See also

pbackfail [virtual]	puts a character back into the input sequence, possibly modifying the input sequence (virtual protected member function of std::basic_streambuf)
sungetc	moves the next pointer in the input sequence back by one (public member function of std::basic_streambuf)
sputbackc	puts one character back in the input sequence (public member function of std::basic_streambuf)
unget	unextracts a character (public member function of std::basic_istream)
putback	puts character into input stream (public member function of std::basic_istream)