std::basic_istream<CharT,Traits>::putback

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros(C++20)

Language support library

Concepts library(C++20)

Diagnostics library

Memory management library

Metaprogramming library(C++11)

General utilities library

Containers library

Iterators library

Ranges library(C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library(C++17)

Concurrency support library(C++11)

Execution control library(C++26)

Technical specifications

Symbols index

External libraries

 

Input/output library

I/O manipulators

Print functions(C++23)

C-style I/O

Buffers

basic_streambuf

basic_filebuf

basic_stringbuf

basic_spanbuf (C++23)

strstreambuf (C++98/26*)

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

basic_ispanstream (C++23)

basic_ospanstream (C++23)

basic_spanstream (C++23)

istrstream (C++98/26*)

ostrstream (C++98/26*)

strstream (C++98/26*)

Synchronized Output

basic_osyncstream (C++20)

Types

streamoff

streamsize

fpos

Error category interface

iostream_category (C++11)

io_errc (C++11)

 

std::basic_istream

Global objects

cinwcin

Member functions

basic_istream::basic_istream

basic_istream::~basic_istream

basic_istream::operator= (C++11)

Formatted input

basic_istream::operator>>

Unformatted input

basic_istream::get

basic_istream::peek

basic_istream::unget

basic_istream::putback

basic_istream::getline

basic_istream::ignore

basic_istream::read

basic_istream::readsome

basic_istream::gcount

Positioning

basic_istream::tellg

basic_istream::seekg

Miscellaneous

basic_istream::sync

basic_istream::swap (C++11)

Member classes

basic_istream::sentry

Non-member functions

operator>>(std::basic_istream)

 

basic_istream& putback( char_type ch );

Puts the character ch back to the input stream so the next extracted character will be ch.

First clears eofbit, then behaves as UnformattedInputFunction. After constructing and checking the sentry object, if rdbuf() is not null, calls rdbuf()->sputbackc(ch), which calls rdbuf()->pbackfail(ch) if ch does not equal the most recently extracted character.

If rdbuf() is null or if rdbuf->sputbackc(ch) returns Traits::eof(), calls setstate(badbit).

In any case, sets the gcount() counter to zero.

Parameters

ch

-

character to put into input stream

Return value

*this

Exceptions

failure if an error occurred (the error state flag is not goodbit) and exceptions() is set to throw for that state.

If an internal operation throws an exception, it is caught and badbit is set. If exceptions() is set for badbit, the exception is rethrown.

Example

Demonstrates the difference between modifying and non-modifying putback().

Run this code

#include <iostream>#include <sstream>   int main(){std::stringstream s1("Hello, world");// IO stream s1.get();if(s1.putback('Y'))// modifies the bufferstd::cout<< s1.rdbuf()<<'\n';elsestd::cout<<"putback failed\n";   std::cout<<"--\n";   std::istringstream s2("Hello, world");// input-only stream s2.get();if(s2.putback('Y'))// cannot modify input-only bufferstd::cout<< s2.rdbuf()<<'\n';elsestd::cout<<"putback failed\n"; s2.clear();   std::cout<<"--\n";   if(s2.putback('H'))// non-modifying putbackstd::cout<< s2.rdbuf()<<'\n';elsestd::cout<<"putback failed\n";}

Output:

Yello, world -- putback failed -- Hello, world

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 2243	C++98	sputbackc() was called without any argument	called with ch

See also

sputbackc	puts one character back in the input sequence (public member function of std::basic_streambuf<CharT,Traits>)
unget	unextracts a character (public member function)
peek	reads the next character without extracting it (public member function)