C++

Reference

<istream>

basic_istream

public member function
<istream> <iostream>

std::operator>> (basic_istream)

single character (1)
template<class charT, class traits>basic_istream<charT,traits>& operator>> (basic_istream<charT,traits>& is, charT& c);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  signed char& c);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  unsigned char& c);
character sequence (2)
template<class charT, class traits>basic_istream<charT,traits>& operator>> (basic_istream<charT,traits>& is, charT* s);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  signed char* s);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  unsigned char* s);
single character (1)
template<class charT, class traits>basic_istream<charT,traits>& operator>> (basic_istream<charT,traits>& is, charT& c);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  signed char& c);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  unsigned char& c);
character sequence (2)
template<class charT, class traits>basic_istream<charT,traits>& operator>> (basic_istream<charT,traits>& is, charT* s);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  signed char* s);template<class traits>basic_istream<char,traits>&  operator>> (basic_istream<char,traits>& is,  unsigned char* s);
rvalue extraction (3)
template<class charT, class traits, class T>basic_istream<charT,traits>& operator>> (basic_istream<charT,traits>&& is, T& val);
Extract characters
This operator (>>) applied to an input stream is known as extraction operator, and performs formatted input:

(1) single character
Extracts the next character from is and stores it as the value of c.
(2) character sequence
Extracts characters from is and stores them in s as a c-string, stopping as soon as either a whitespace character is encountered or (width()-1) characters have been extracted (if width is not zero).
A null character (charT()) is automatically appended to the written sequence.
The function then resets width to zero.
(3) rvalue extraction
Allows extracting from rvalue basic_istream objects, with the same effect as from lvalues: It effectively calls: is>>val.

Internally, the function accesses the input sequence of is by first constructing a sentry with noskipws set to false: this may flush its tied stream and/or discard leading whitespaces (see basic_istream::sentry). Then (if good), it extracts characters from is's associated stream buffer object (as if calling its member functions sbumpc or sgetc), and finally destroys the sentry object before returning.

Notice that if this function extracts the last character of a stream when extracting a single character (1), it does not set its eofbit flag, but attempting to extract beyond it does.

Calling this function does not alter the value returned by gcount on is.

Parameters

is
Input stream object from which characters are extracted.
c
Object where the extracted character is stored.
s
Pointer to an array of characters where extracted characters are stored as a c-string.
is's member function width may be used to specify a limit on the number of characters to write.
val
Object where content is stored.
T shall be a type supported as right-hand side argument either by this function or by is's member function operator>>.
charT and traits are the class template parameters of is (see basic_istream).

Return Value

The basic_istream object (is).

The extracted value or sequence is not returned, but directly stored in the variable passed as argument.

Errors are signaled by modifying the internal state flags:
flagerror
eofbitThe function stopped extracting characters because the input sequence controlled by is has no more characters available (end-of-file reached).
failbitEither no characters were extracted, or these could not be interpreted as a valid value of the appropriate type.
badbitError on stream (such as when this function catches an exception thrown by an internal operation).
When set, the integrity of the stream may have been affected.
Multiple flags may be set by a single operation.

If the operation sets an internal state flag that was registered with is's member exceptions, the function throws an exception of is's failure member type.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
 
// example on extraction
#include <iostream>     // std::cin, std::cout

int main () {
  char str[10];

  std::cout << "Enter a word: ";
  std::cin.width (10);               // limit width
  std::cin >> str;
  std::cout << "The first 9 chars of your word are: " << str << '\n';

  return 0;
}

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

Data races

Modifies c or the elements of the array pointed by s.
Modifies is.
Concurrent access to the same stream object may cause data races, except for the standard stream objects cin and wcin when these are synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which extracted characters are attributed to threads).

Exception safety

Basic guarantee: if an exception is thrown, all objects involved are in valid states.
It throws an exception of member type failure if the resulting error state flag for is is not goodbit and member exceptions was set to throw for that state in is.
Any exception thrown by an internal operation is caught and handled by the function, setting is's badbit flag. If badbit was set on the last call to exceptions for is, the function rethrows the caught exception.

See also

basic_istream::get
Get characters (public member function)
basic_istream::getline
Get line (public member function)
basic_ostream::operator<<
Insert formatted output (public member function)
basic_istream::sentry
Prepare stream for input (public member class)