Reference
C Library
IOstream Library
Strings library
STL Containers
STL Algorithms
Miscellaneous

IOstream Library
manipulators
classes:
filebuf
fstream
ifstream
ios
iostream
ios_base
istream
istringstream
ofstream
ostream
ostringstream
streambuf
stringbuf
stringstream
objects:
cerr
cin
clog
cout
types:
fpos
streamoff
streampos
streamsize

istream
istream::istream
istream::~istream
member classes:
istream::sentry
member functions:
istream::gcount
istream::get
istream::getline
istream::ignore
istream::operator>>
istream::peek
istream::putback
istream::read
istream::readsome
istream::seekg
istream::sync
istream::tellg
istream::unget

istream::operator>>

public member function

istream& operator>> (bool& val );
istream& operator>> (short& val );
istream& operator>> (unsigned short& val );
istream& operator>> (int& val );
istream& operator>> (unsigned int& val );
istream& operator>> (long& val );
istream& operator>> (unsigned long& val );
istream& operator>> (float& val );
istream& operator>> (double& val );
istream& operator>> (long double& val );
istream& operator>> (void*& val );
 
istream& operator>> (streambuf* sb );
 
istream& operator>> (istream& ( *pf )(istream&));
istream& operator>> (ios& ( *pf )(ios&));
istream& operator>> (ios_base& ( *pf )(ios_base&));

*** the following functions are not members but GLOBAL functions:
 
istream& operator>> (istream& is, char& ch );
istream& operator>> (istream& is, signed char& ch );
istream& operator>> (istream& is, unsigned char& ch );
 
istream& operator>> (istream& is, char* str );
istream& operator>> (istream& is, signed char* str );
istream& operator>> (istream& is, unsigned char* str );

Extract formatted data

This operator (>>) applied to an input stream is known as extraction operator. It performs an input operation on a stream generally involving some sort of interpretation of the data (like translating a sequence of numerical characters to a value of a given numerical type).

Three groups of member functions and one group of global functions overload this "extraction operator" (>>) applied to istream objects:

The first group of member functions are arithmetic extractors. These read characters from the input data, and parse them to interpret them as a value of the specific type of its parameter. The resulting value is stored in the variable passed as parameter.
The streambuf version copies as many characters as possible to the stream buffer object used as right-hand parameter, either until an error happens or until there are no more characters to copy.
Those in the last group of member functions have a pointer to a function as parameter. These are designed to be used with manipulator functions.
Manipulator functions are functions specifically designed to be easily used with this operator.
The global functions overload the operator when the parameter is either a character or a c-string, and, as expected they extract either one character or a sequence of characters from the input stream.

See the description of the parameters for more details on how each group of functions work.

Because these functions are operator overloading functions, the usual way in which they are called is:

strm >> variable;

Where strm is the identifier of a istream object and variable is an object of any type supported as right parameter. It is also possible to call a succession of extraction operations as:

strm >> variable1 >> variable2 >> variable3; //...

which is the same as performing successive extractions from the same object strm.

The manipulators which have an effect when used on standard istream objects are:

boolalpha

Alphanumerical bool values (manipulator function)

noboolalpha

No alphanumerical bool values (manipulator function)

skipws

Skip whitespaces (manipulator function)

noskipws

Do not skip whitespaces (manipulator function)

dec

Use decimal base (manipulator function)

hex

Use hexadecimal base (manipulator function)

oct

Use octal base (manipulator function)

ws	Extract whitespaces (manipulator function)

Other manipulators may be applicable to standard istream objects, but have no effect.

The following parameterized manipulators also have an effect on istream objects (these require the explicit inlcusion of the <iomanip> header file):

setiosflags

Set format flags (manipulator function)

resetiosflags

Reset format flags (manipulator function)

setbase

Set basefield flag (manipulator function)

Parameters

val: Extracts characters from the input sequence and tries to interpret them as a numeric value of the given parameter's type. If successful the value is stored in val. The specific way in which the data is parsed depends on the manipulators previously used on the stream and on its associated locale.
sb: Extracts characters from the input sequence and stores them in sb until the End-Of-File is reached or until the buffer fails to successfully insert a character (in which case this last character is not extracted).
pf: Calls pf(*this), which generally is a manipulator function.
ch: A single character is extracted and stored in ch.
str: Extracts characters and stores them as a c-string (i.e. in succesive locations starting at location pointed by str and terminated by a null-character). Extraction ends when the next character is either a valid whitespace or a null character, or if the End-Of-File is reached.
The terminating null character is automatically appended after the extracted characters.
The extraction operation can be limited to a certain number of characters (thus avoiding the possibility of buffer overflow) if the field width (which can be set with ios_base::width or setw) is set to a value greater than zero. In this case, the extraction ends one character before the count of characters extracted reaches the value of field width, leaving space for the ending null character. After a call to this extraction operation the value of the field width is automatically reset to zero.
is: stream object on which the action is performed. This is the first parameter of the global functions, and represents the object to the left of the operator, i.e. the object on which the extraction operation is performed.

Return Value

The object itself (*this).
When a value is being "extracted" it is not returned, but directly stored in the variable used as parameter.

Errors are signaled by modifying the internal state flags:

flag	error
`eofbit`	The end of the source of characters is reached during its operations.
`failbit`	The input obtained could not be interpreted as an element of the appropriate type. Notice that some `eofbit` cases will also set `failbit`.
`badbit`	An error other than the above happened.

(see ios_base::iostate for more info on these)

Additionally, in any of these cases, if the appropriate flag has been set with member function ios::exceptions, an exception of type ios_base::failure is thrown.

Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

// example on extraction
#include <iostream>
using namespace std;
int main () {
  int n;
  char str[10];
  cout << "Enter a number: ";
  cin >> n;
  cout << "You have entered: " << n << endl;
  cout << "Enter a hexadecimal number: ";
  cin >> hex >> n;            // manipulator
  cout << "Its decimal equivalent is: " << n << endl;
  cout << "Enter a word: ";
  cin.width (10);        // limit width
  cin >> str;
  cout << "The first 9 chars of your word are: " << str << endl;
  return 0;
}

This code demonstrates the use of some of the overloaded operator>> functions shown above using the standard istream object cin.

Basic template member declarations

( basic_istream<charT,traits> )

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

basic_istream& operator>> (bool& val );
basic_istream& operator>> (short& val );
basic_istream& operator>> (unsigned short& val );
basic_istream& operator>> (int& val );
basic_istream& operator>> (unsigned int& val );
basic_istream& operator>> (long& val );
basic_istream& operator>> (unsigned long& val );
basic_istream& operator>> (float& val );
basic_istream& operator>> (double& val );
basic_istream& operator>> (long double& val );
basic_istream& operator>> (void*& val );
basic_istream& operator>> (basic_streambuf<charT,traits>* sb );
basic_istream& operator>> (basic_istream& ( *pf )(istream&));
basic_istream& operator>> (basic_ios<charT,traits>& ( *pf )(basic_ios<charT,traits>&));
basic_istream& operator>> (ios_base& ( *pf )(ios_base&));

Basic template global functions

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17