Init
This commit is contained in:
392
cppdraft/istream/formatted.md
Normal file
392
cppdraft/istream/formatted.md
Normal file
@@ -0,0 +1,392 @@
|
||||
[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&) ([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&) ([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)
|
||||
Reference in New Issue
Block a user