[istream.formatted]

# 31 Input/output library [[input.output]](./#input.output)

## 31.7 Formatting and manipulators [[iostream.format]](iostream.format#istream.formatted)

### 31.7.5 Input streams [[input.streams]](input.streams#istream.formatted)

#### 31.7.5.3 Formatted input functions [istream.formatted]

#### [31.7.5.3.1](#reqmts) Common requirements [[istream.formatted.reqmts]](istream.formatted.reqmts)

[1](#reqmts-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4655)

Each formatted input function begins execution by constructing
an object of type ios_base​::​iostate, termed the local error state, and
initializing it to ios_base​::​goodbit[.](#reqmts-1.sentence-1)

It then creates an object of classsentry with thenoskipws (second) argumentfalse[.](#reqmts-1.sentence-2)

If thesentry object returnstrue,
when converted to a value of typebool,
the function endeavors
to obtain the requested input[.](#reqmts-1.sentence-3)

Otherwise,
if the sentry constructor exits by throwing an exception or
if the sentry object produces false when converted to a value of type bool,
the function returns without attempting to obtain any input[.](#reqmts-1.sentence-4)

If rdbuf()->sbumpc() or rdbuf()->sgetc() returns traits​::​eof(), thenios_base​::​eofbit is set in the local error state and
the input function stops trying to obtain the requested input[.](#reqmts-1.sentence-5)

If an exception is thrown during input thenios_base​::​badbit is set in the local error state,*this's error state is set to the local error state, and
the exception is rethrown if (exceptions() & badbit) != 0[.](#reqmts-1.sentence-6)

After extraction is done, the input function calls setstate, which
sets *this's error state to the local error state, and
may throw an exception[.](#reqmts-1.sentence-7)

In any case, the formatted input function destroys thesentry object[.](#reqmts-1.sentence-8)

If no exception has been thrown, it returns*this[.](#reqmts-1.sentence-9)

#### [31.7.5.3.2](#arithmetic) Arithmetic extractors [[istream.formatted.arithmetic]](istream.formatted.arithmetic)

[🔗](#lib:operator%3e%3e,basic_istream)

`basic_istream& operator>>(unsigned short& val);
basic_istream& operator>>(unsigned int& val);
basic_istream& operator>>(long& val);
basic_istream& operator>>(unsigned long& val);
basic_istream& operator>>(long long& val);
basic_istream& operator>>(unsigned long long& val);
basic_istream& operator>>(float& val);
basic_istream& operator>>(double& val);
basic_istream& operator>>(long double& val);
basic_istream& operator>>(bool& val);
basic_istream& operator>>(void*& val);
`

[1](#arithmetic-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4713)

As in the case of the inserters, these extractors depend on the
locale's[num_get<>](locale.num.get "28.3.4.3.2 Class template num_­get [locale.num.get]") object to perform parsing the input
stream data[.](#arithmetic-1.sentence-1)

These extractors behave as formatted input functions (as described in [[istream.formatted.reqmts]](#reqmts "31.7.5.3.1 Common requirements"))[.](#arithmetic-1.sentence-2)

After a sentry object is constructed, the
conversion occurs as if performed by the following code fragment,
where state represents the input function's local error state:using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
use_facet<numget>(loc).get(*this, 0, *this, state, val);

In the above fragment,loc stands for the private member of thebasic_ios class[.](#arithmetic-1.sentence-4)

[*Note [1](#arithmetic-note-1)*:

The first argument provides an object of theistreambuf_iterator class which is an iterator pointed to an input stream[.](#arithmetic-1.sentence-5)

It bypasses istreams and uses streambufs directly[.](#arithmetic-1.sentence-6)

— *end note*]

Classlocale relies on this
type as its interface toistream,
so that it does not need to depend directly onistream[.](#arithmetic-1.sentence-7)

[🔗](#lib:operator%3e%3e,basic_istream_)

`basic_istream& operator>>(short& val);
`

[2](#arithmetic-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4751)

The conversion occurs as if performed by the following code fragment
(using the same notation as for the preceding code fragment):using numget = num_get<charT, istreambuf_iterator<charT, traits>>;long lval;
use_facet<numget>(loc).get(*this, 0, *this, state, lval);if (lval < numeric_limits<short>::min()) { state |= ios_base::failbit;
 val = numeric_limits<short>::min();} else if (numeric_limits<short>::max() < lval) { state |= ios_base::failbit;
 val = numeric_limits<short>::max();} else val = static_cast<short>(lval);

[🔗](#lib:operator%3e%3e,basic_istream__)

`basic_istream& operator>>(int& val);
`

[3](#arithmetic-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4775)

The conversion occurs as if performed by the following code fragment
(using the same notation as for the preceding code fragment):using numget = num_get<charT, istreambuf_iterator<charT, traits>>;long lval;
use_facet<numget>(loc).get(*this, 0, *this, state, lval);if (lval < numeric_limits<int>::min()) { state |= ios_base::failbit;
 val = numeric_limits<int>::min();} else if (numeric_limits<int>::max() < lval) { state |= ios_base::failbit;
 val = numeric_limits<int>::max();} else val = static_cast<int>(lval);

[🔗](#arithmetic-itemdecl:4)

`basic_istream& operator>>(extended-floating-point-type& val);
`

[4](#arithmetic-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4798)

If
the floating-point conversion rank of *extended-floating-point-type* is not less than or equal to that of long double,
then an invocation of the operator function is conditionally supported
with implementation-defined
semantics[.](#arithmetic-4.sentence-1)

[5](#arithmetic-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4806)

Otherwise, let FP be a standard floating-point type:

- [(5.1)](#arithmetic-5.1)

if the floating-point conversion rank of *extended-floating-point-type* is less than or equal to that of float,
then FP is float,

- [(5.2)](#arithmetic-5.2)

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,

- [(5.3)](#arithmetic-5.3)

otherwise, FP is long double[.](#arithmetic-5.sentence-1)

[6](#arithmetic-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4822)

The conversion occurs as if performed by the following code fragment
(using the same notation as for the preceding code fragment):using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
FP fval;
use_facet<numget>(loc).get(*this, 0, *this, state, fval);if (fval < -numeric_limits<*extended-floating-point-type*>::max()) { state |= ios_base::failbit;
 val = -numeric_limits<*extended-floating-point-type*>::max();} else if (numeric_limits<*extended-floating-point-type*>::max() < fval) { state |= ios_base::failbit;
 val = numeric_limits<*extended-floating-point-type*>::max();} else { val = static_cast<*extended-floating-point-type*>(fval);}

[*Note [2](#arithmetic-note-2)*:

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[.](#arithmetic-6.sentence-1)

from_chars can be used in situations
where maximum accuracy is important[.](#arithmetic-6.sentence-2)

— *end note*]

#### [31.7.5.3.3](#istream.extractors) basic_istream​::​operator>> [[istream.extractors]](istream.extractors)

[🔗](#lib:operator%3e%3e,basic_istream___)

`basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
`

[1](#istream.extractors-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4857)

*Effects*: None[.](#istream.extractors-1.sentence-1)

This extractor does not behave as a formatted input function
(as described in [[istream.formatted.reqmts]](#reqmts "31.7.5.3.1 Common requirements"))[.](#istream.extractors-1.sentence-2)

[2](#istream.extractors-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4863)

*Returns*: pf(*this)[.](#istream.extractors-2.sentence-1)

[274](#footnote-274 "See, for example, the function signature ws(basic_­istream&amp;) ([istream.manip]).")

[🔗](#lib:operator%3e%3e,basic_istream____)

`basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
`

[3](#istream.extractors-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4879)

*Effects*: Callspf(*this)[.](#istream.extractors-3.sentence-1)

This extractor does not behave as a formatted input function
(as described in [[istream.formatted.reqmts]](#reqmts "31.7.5.3.1 Common requirements"))[.](#istream.extractors-3.sentence-2)

[4](#istream.extractors-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4886)

*Returns*: *this[.](#istream.extractors-4.sentence-1)

[🔗](#lib:operator%3e%3e,basic_istream_____)

`basic_istream& operator>>(ios_base& (*pf)(ios_base&));
`

[5](#istream.extractors-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4897)

*Effects*: Callspf(*this)[.](#istream.extractors-5.sentence-1)[275](#footnote-275 "See, for example, the function signature dec(ios_­base&amp;) ([basefield.manip]).")

This extractor does not behave as a formatted input function
(as described in [[istream.formatted.reqmts]](#reqmts "31.7.5.3.1 Common requirements"))[.](#istream.extractors-5.sentence-2)

[6](#istream.extractors-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4908)

*Returns*: *this[.](#istream.extractors-6.sentence-1)

[🔗](#lib:operator%3e%3e,basic_istream______)

`template<class charT, class traits, size_t N>
  basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT (&s)[N]);
template<class traits, size_t N>
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char (&s)[N]);
template<class traits, size_t N>
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char (&s)[N]);
`

[7](#istream.extractors-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4924)

*Effects*: Behaves like a formatted input member (as described in [[istream.formatted.reqmts]](#reqmts "31.7.5.3.1 Common requirements"))
of in[.](#istream.extractors-7.sentence-1)

After asentry object is constructed,operator>> extracts characters and stores them intos[.](#istream.extractors-7.sentence-2)

Ifwidth() is greater than zero, n ismin(size_t(width()), N)[.](#istream.extractors-7.sentence-3)

Otherwise n is N[.](#istream.extractors-7.sentence-4)

n is the maximum number of characters stored[.](#istream.extractors-7.sentence-5)

[8](#istream.extractors-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4941)

Characters are extracted and stored until any of the following occurs:

- [(8.1)](#istream.extractors-8.1)

n - 1 characters are stored;

- [(8.2)](#istream.extractors-8.2)

end of file occurs on the input sequence;

- [(8.3)](#istream.extractors-8.3)

letting ct be use_facet<ctype<charT>>(in.getloc()),ct.is(ct.space, c) is true[.](#istream.extractors-8.sentence-1)

[9](#istream.extractors-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4950)

operator>> then stores a null byte
(charT())
in the next position, which may be the first position if no characters
were extracted[.](#istream.extractors-9.sentence-1)

operator>> then callswidth(0)[.](#istream.extractors-9.sentence-2)

[10](#istream.extractors-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4960)

If the function extracted no characters,ios_base​::​failbit is set in the input function's local error state
before setstate is called[.](#istream.extractors-10.sentence-1)

[11](#istream.extractors-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4965)

*Returns*: in[.](#istream.extractors-11.sentence-1)

[🔗](#lib:operator%3e%3e,basic_istream_______)

`template<class charT, class traits>
  basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT& c);
template<class traits>
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char& c);
template<class traits>
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
`

[12](#istream.extractors-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4981)

*Effects*: Behaves like a formatted input member (as described in [[istream.formatted.reqmts]](#reqmts "31.7.5.3.1 Common requirements"))
of in[.](#istream.extractors-12.sentence-1)

A character is extracted from in, if one is available, and stored in c[.](#istream.extractors-12.sentence-2)

Otherwise,ios_base​::​failbit is set in the input function's local error state
before setstate is called[.](#istream.extractors-12.sentence-3)

[13](#istream.extractors-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4990)

*Returns*: in[.](#istream.extractors-13.sentence-1)

[🔗](#lib:operator%3e%3e,basic_istream________)

`basic_istream& operator>>(basic_streambuf<charT, traits>* sb);
`

[14](#istream.extractors-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L5001)

*Effects*: Behaves as an [unformatted input function](istream.unformatted "31.7.5.4 Unformatted input functions [istream.unformatted]")[.](#istream.extractors-14.sentence-1)

If sb is null, callssetstate(failbit),
which may throwios_base​::​failure ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions"))[.](#istream.extractors-14.sentence-2)

After a sentry object is constructed, extracts
characters from*this and inserts them in the output sequence controlled by sb[.](#istream.extractors-14.sentence-3)

Characters are extracted and inserted until any of the following occurs:

- [(14.1)](#istream.extractors-14.1)

end-of-file occurs on the input sequence;

- [(14.2)](#istream.extractors-14.2)

inserting in the output sequence fails
(in which case the character to be inserted is not extracted);

- [(14.3)](#istream.extractors-14.3)

an exception occurs (in which case the exception is caught)[.](#istream.extractors-14.sentence-4)

[15](#istream.extractors-15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L5023)

If the function inserts no characters,ios_base​::​failbit is set in the input function's local error state
before setstate is called[.](#istream.extractors-15.sentence-1)

[16](#istream.extractors-16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L5028)

*Returns*: *this[.](#istream.extractors-16.sentence-1)

[274)](#footnote-274)[274)](#footnoteref-274)

See, for example, the function signaturews(basic_istream&) ([[istream.manip]](istream.manip "31.7.5.5 Standard basic_­istream manipulators"))[.](#footnote-274.sentence-1)

[275)](#footnote-275)[275)](#footnoteref-275)

See, for example, the function signaturedec(ios_base&) ([[basefield.manip]](basefield.manip "31.5.5.3 basefield manipulators"))[.](#footnote-275.sentence-1)