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

From cppreference.com

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

[edit]

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)

[edit]

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)

[edit]

basic_istream& operator>>(unsignedshort& value);	(1)
basic_istream& operator>>(unsignedint& value);	(2)
basic_istream& operator>>(long& value);	(3)
basic_istream& operator>>(unsignedlong& value);	(4)
basic_istream& operator>>(longlong& value);	(5)	(since C++11)
basic_istream& operator>>(unsignedlonglong& value);	(6)	(since C++11)
basic_istream& operator>>(float& value);	(7)
basic_istream& operator>>(double& value);	(8)
basic_istream& operator>>(longdouble& 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 */& value);	(14)	(since C++23)
basic_istream& operator>>(std::ios_base&(*func)(std::ios_base&));	(15)
basic_istream& operator>>(std::basic_ios<CharT, Traits>& (*func)(std::basic_ios<CharT, Traits>&));	(16)
basic_istream& operator>>( basic_istream&(*func)(basic_istream&));	(17)
basic_istream& operator>>(std::basic_streambuf<CharT, Traits>* sb);	(18)

Extracts values from an input stream.

1-11) Extracts a value potentially skipping preceding whitespace. The value is stored to a given referencevalue.

This function behaves as aFormattedInputFunction. After constructing and checking the sentry object, which may skip leading whitespace, extracts a value by callingstd::num_get::get().

12) Extracts ashort value potentially skipping preceding whitespace. The value is stored to a given referencevalue.

This function behaves as aFormattedInputFunction. After constructing and checking the sentry object, which may skip leading whitespace, extracts along valuelval by callingstd::num_get::get(). After that:

Iflval<std::numeric_limits<short>::min(), setsfailbit and storesstd::numeric_limits<short>::min() toval.
Otherwise, ifstd::numeric_limits<short>::max()< lval, setsfailbit and storesstd::numeric_limits<short>::max() toval.
Otherwise, storesstatic_cast<short>(lval) toval.

13) Extracts anint value potentially skipping preceding whitespace. The value is stored to a given referencevalue.

Iflval<std::numeric_limits<int>::min(), setsfailbit and storesstd::numeric_limits<int>::min() toval.
Otherwise, ifstd::numeric_limits<int>::max()< lval, setsfailbit and storesstd::numeric_limits<int>::max() toval.
Otherwise, storesstatic_cast<int>(lval) toval.

14) Extracts an extended floating-point value potentially skipping preceding whitespace. The value is stored to a given referencevalue. The library provides overloads for all cv-unqualifiedextended floating-point types as the referenced type of the parametervalue.

Determines the standard floating-point typeFP as follows:

If thefloating-point conversion rank of/* extended-floating-point-type */ is less than or equal to that offloat, thenFP isfloat.
Otherwise, if the floating-point conversion rank of/* extended-floating-point-type */ is less than or equal to that ofdouble, thenFP isdouble.
Otherwise,FP islongdouble.

This function behaves as aFormattedInputFunction. After constructing and checking the sentry object, which may skip leading whitespace, extracts anFP valuefval by callingstd::num_get::get(). After that:

Iffval<-std::numeric_limits</* extended-floating-point-type */>::max(), setsfailbit and stores-std::numeric_limits</* extended-floating-point-type */>::max() toval.
Otherwise, ifstd::numeric_limits</* extended-floating-point-type */>::max()< fval, setsfailbit and storesstd::numeric_limits</* extended-floating-point-type */>::max() toval.
Otherwise, storesstatic_cast</* extended-floating-point-type */>(fval) toval.

15-17) Callsfunc(*this), wherefunc is an I/O manipulator.

18) Behaves as anUnformattedInputFunction. After constructing and checking the sentry object, extracts all data from*this and stores it tosb. 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 andfailbit is enabled inexceptions()).

In either case, stores the number of characters extracted in the member variable accessed by subsequent calls togcount(). Ifsb is a null pointer or if no characters were inserted intosb, callssetstate(failbit) (which may throwstd::ios_base::failure if enabled).

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

[edit]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

[edit]Return value

1-16,18)*this

17)func(*this)

[edit]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.

[edit]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 = 41f = 3.14b = falsehello world

[edit]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 64	C++98	it was unclear whether overload(18) can only rethrow the std::ios_base::failure thrown by callingsetstate(failbit)	all exceptions caught can be rethrown
LWG 118	C++98	overload(12,13) delegated the extraction to`num_get::get`, but it does not have overloads forshort andint	along value is extracted instead ofshort orint
LWG 413	C++98	overload(18) only rethrew exceptions thrown while extracting characters fromsb, but characters are extracted from*this	correctedsb to*this
LWG 567	C++98	overload(18) behaved as aFormattedInputFunction because of the resolution ofLWG issue 60	it behaves as an UnformattedInputFunction
LWG 661	C++98	overloads(12,13) did not store the extracted number tovalue due to the resolution ofLWG issue 118	stores the number if no overflow occurs
LWG 696	C++98	value was unchanged on extraction failure	set to zero or minimum/ maximum values

[edit]See also

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