NAME¶

std::basic_istream::operator>> - std::basic_istream::operator>>

Synopsis¶

basic_istream& operator>>( unsigned short& value ); (1)
basic_istream& operator>>( unsigned int& value ); (2)
basic_istream& operator>>( long& value ); (3)
basic_istream& operator>>( unsigned long& value ); (4)
basic_istream& operator>>( long long& value ); (5) (since C++11)
basic_istream& operator>>( unsigned long long& value ); (6) (since C++11)
basic_istream& operator>>( float& value ); (7)
basic_istream& operator>>( double& value ); (8)
basic_istream& operator>>( long double& value ); (9)
basic_istream& operator>>( bool& value ); (10)
basic_istream& operator>>( void*& value ); (11)
basic_istream& operator>>( short& value ); (12)
basic_istream& operator>>( int& value ); (13)
basic_istream& operator>>( /* extended-floating-point-type */& (14) (since C++23)
value );
basic_istream& operator>>( std::ios_base& (*func)(std::ios_base&) (15)
);
basic_istream& operator>>( std::basic_ios<CharT, Traits>&
(*func)(std::basic_ios<CharT, (16)
Traits>&) );
basic_istream& operator>>( basic_istream& (*func)(basic_istream&) (17)
);
basic_istream& operator>>( std::basic_streambuf<CharT, Traits>* (18)
sb );

Extracts values from an input stream.

1-11) Extracts a value potentially skipping preceding whitespace. The value is
stored to a given reference value.
This function behaves as a FormattedInputFunction. After constructing and checking
the sentry object, which may skip leading whitespace, extracts a value by calling
std::num_get::get().
12) Extracts a short value potentially skipping preceding whitespace. The value is
stored to a given reference value.
This function behaves as a FormattedInputFunction. After constructing and checking
the sentry object, which may skip leading whitespace, extracts a long value lval by
calling std::num_get::get(). After that:
* If lval < std::numeric_limits<short>::min(), sets failbit and stores
std::numeric_limits<short>::min() to val.
* Otherwise, if std::numeric_limits<short>::max() < lval, sets failbit and stores
std::numeric_limits<short>::max() to val.
* Otherwise, stores static_cast<short>(lval) to val.
13) Extracts an int value potentially skipping preceding whitespace. The value is
stored to a given reference value.
This function behaves as a FormattedInputFunction. After constructing and checking
the sentry object, which may skip leading whitespace, extracts a long value lval by
calling std::num_get::get(). After that:
* If lval < std::numeric_limits<int>::min(), sets failbit and stores
std::numeric_limits<int>::min() to val.
* Otherwise, if std::numeric_limits<int>::max() < lval, sets failbit and stores
std::numeric_limits<int>::max() to val.
* Otherwise, stores static_cast<int>(lval) to val.
14) Extracts an extended floating-point value potentially skipping preceding
whitespace. The value is stored to a given reference value. The library provides
overloads for all cv-unqualified extended floating-point types as the referenced
type of the parameter value.
Determines the standard floating-point type FP as follows:
* If the floating-point conversion rank of /* extended-floating-point-type */ is
less than or equal to that of float, then FP is float.
* Otherwise, if the floating-point conversion rank of /*
extended-floating-point-type */ is less than or equal to that of double, then FP
is double.
* Otherwise, FP is long double.
This function behaves as a FormattedInputFunction. After constructing and checking
the sentry object, which may skip leading whitespace, extracts an FP value fval by
calling std::num_get::get(). After that:
* If fval < -std::numeric_limits</* extended-floating-point-type */>::max(), sets
failbit and stores -std::numeric_limits</* extended-floating-point-type
*/>::max() to val.
* Otherwise, if std::numeric_limits</* extended-floating-point-type */>::max() <
fval, sets failbit and stores std::numeric_limits</*
extended-floating-point-type */>::max() to val.
* Otherwise, stores static_cast</* extended-floating-point-type */>(fval) to val.
15-17) Calls func(*this), where func is an I/O manipulator.
18) Behaves as an UnformattedInputFunction. After constructing and checking the
sentry object, extracts all data from *this and stores it to sb. The extraction
stops if one of the following conditions are met:

* end-of-file occurs on the input sequence;
* inserting in the output sequence fails (in which case the character to be
inserted is not extracted);
* an exception occurs (in which case the exception is caught, and only rethrown if
it inserted no characters and failbit is enabled in exceptions()).
In either case, stores the number of characters extracted in the member variable
accessed by subsequent calls to gcount(). If sb is a null pointer or if no
characters were inserted into sb, calls setstate(failbit) (which may throw
std::ios_base::failure if enabled).

If extraction fails (e.g. if a letter was entered where a digit is expected), zero
is written to value and failbit is set. For signed integers, if extraction results
in the value too large or too small to fit in value, std::numeric_limits<T>::max()
or std::numeric_limits<T>::min() (respectively) is written and failbit flag is set.
For unsigned integers, if extraction results in the value too large or too small to
fit in value, std::numeric_limits<T>::max() is written and failbit flag is set.

Parameters¶

value - reference to an integer or floating-point value to store the extracted value
to
func - pointer to I/O manipulator function
sb - pointer to the stream buffer to write all the data to

Return value¶

1-16,18) *this
17) func(*this)

Notes¶

For overload (14), when the extended floating-point type has a floating-point
conversion rank that is not equal to the rank of any standard floating-point type,
then double rounding during the conversion can result in inaccurate results.
std::from_chars() can be used in situations where maximum accuracy is important.

Example¶

// Run this code

#include <iomanip>
#include <iostream>
#include <sstream>

int main()
{
std::string input = "41 3.14 false hello world";
std::istringstream stream(input);

int n;
double f;
bool b;

stream >> n >> f >> std::boolalpha >> b;
std::cout << "n = " << n << '\n'
<< "f = " << f << '\n'
<< "b = " << std::boolalpha << b << '\n';

// extract the rest using the streambuf overload
stream >> std::cout.rdbuf();
std::cout << '\n';
}

Output:¶

n = 41
f = 3.14
b = false
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
it was unclear whether overload (18)
LWG 64 C++98 can only rethrow the all exceptions caught
std::ios_base::failure thrown by can be rethrown
calling setstate(failbit)
overload (12,13) delegated the
LWG 118 C++98 extraction to num_get::get, a long value is extracted
but it does not have overloads for instead of short or int
short and int
overload (18) only rethrew exceptions
LWG 413 C++98 thrown while extracting corrected sb to *this
characters from sb, but characters are
extracted from *this
overload (18) behaved as a
LWG 567 C++98 FormattedInputFunction it behaves as an
because of the resolution of LWG issue UnformattedInputFunction
60
overloads (12,13) did not store the
LWG 661 C++98 extracted number stores the number if
to value due to the resolution of LWG no overflow occurs
issue 118
LWG 696 C++98 value was unchanged on extraction set to zero or minimum/
failure maximum values

See also¶

operator>>(std::basic_istream) extracts characters and character arrays
(function template)
operator<< performs stream input and output on strings
operator>> (function template)
operator<< performs stream input and output of bitsets
operator>> (function template)
operator<< serializes and deserializes a complex number
operator>> (function template)
operator<< performs stream input and output on pseudo-random
operator>> number engine
(C++11) (function template)
operator<< performs stream input and output on pseudo-random
operator>> number distribution
(C++11) (function template)
read extracts blocks of characters
(public member function)
readsome extracts already available blocks of characters
(public member function)
get extracts characters
(public member function)
extracts characters until the given character is
getline found
(public member function)
from_chars converts a character sequence to an integer or
(C++17) floating-point value
(function)