From Jason Turner

[istream.formatted]

C++20 → C++23 11.3 KB 163 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp172z7uzb/{from.md → to.md} +101 -56
tmp/tmp172z7uzb/{from.md → to.md} RENAMED
@@ -1,47 +1,56 @@
1
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2
 
3
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
4
 
5
  Each formatted input function begins execution by constructing an object
6
- of class `sentry` with the `noskipws` (second) argument `false`. If the
 
 
7
  `sentry` object returns `true`, when converted to a value of type
8
- `bool`, the function endeavors to obtain the requested input. If an
9
- exception is thrown during input then `ios_base::badbit` is turned
10
- on[^20] in `*this`’s error state. If `(exceptions()&badbit) != 0` then
11
- the exception is rethrown. In any case, the formatted input function
12
- destroys the `sentry` object. If no exception has been thrown, it
13
- returns `*this`.
 
 
 
 
 
 
 
 
14
 
15
  ##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
16
 
17
  ``` cpp
18
- operator>>(unsigned short& val);
19
- operator>>(unsigned int& val);
20
- operator>>(long& val);
21
- operator>>(unsigned long& val);
22
- operator>>(long long& val);
23
- operator>>(unsigned long long& val);
24
- operator>>(float& val);
25
- operator>>(double& val);
26
- operator>>(long double& val);
27
- operator>>(bool& val);
28
- operator>>(void*& val);
29
  ```
30
 
31
  As in the case of the inserters, these extractors depend on the locale’s
32
  `num_get<>` [[locale.num.get]] object to perform parsing the input
33
  stream data. These extractors behave as formatted input functions (as
34
- described in  [[istream.formatted.reqmts]]). After a sentry object is
35
  constructed, the conversion occurs as if performed by the following code
36
- fragment:
 
37
 
38
  ``` cpp
39
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
40
- iostate err = iostate::goodbit;
41
- use_facet<numget>(loc).get(*this, 0, *this, err, val);
42
- setstate(err);
43
  ```
44
 
45
  In the above fragment, `loc` stands for the private member of the
46
  `basic_ios` class.
47
 
@@ -52,85 +61,123 @@ directly. — *end note*]
52
 
53
  Class `locale` relies on this type as its interface to `istream`, so
54
  that it does not need to depend directly on `istream`.
55
 
56
  ``` cpp
57
- operator>>(short& val);
58
  ```
59
 
60
  The conversion occurs as if performed by the following code fragment
61
  (using the same notation as for the preceding code fragment):
62
 
63
  ``` cpp
64
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
65
- iostate err = ios_base::goodbit;
66
  long lval;
67
- use_facet<numget>(loc).get(*this, 0, *this, err, lval);
68
  if (lval < numeric_limits<short>::min()) {
69
- err |= ios_base::failbit;
70
  val = numeric_limits<short>::min();
71
  } else if (numeric_limits<short>::max() < lval) {
72
- err |= ios_base::failbit;
73
  val = numeric_limits<short>::max();
74
  } else
75
  val = static_cast<short>(lval);
76
- setstate(err);
77
  ```
78
 
79
  ``` cpp
80
- operator>>(int& val);
81
  ```
82
 
83
  The conversion occurs as if performed by the following code fragment
84
  (using the same notation as for the preceding code fragment):
85
 
86
  ``` cpp
87
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
88
- iostate err = ios_base::goodbit;
89
  long lval;
90
- use_facet<numget>(loc).get(*this, 0, *this, err, lval);
91
  if (lval < numeric_limits<int>::min()) {
92
- err |= ios_base::failbit;
93
  val = numeric_limits<int>::min();
94
  } else if (numeric_limits<int>::max() < lval) {
95
- err |= ios_base::failbit;
96
  val = numeric_limits<int>::max();
97
  } else
98
  val = static_cast<int>(lval);
99
- setstate(err);
100
  ```
101
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
102
  ##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
103
 
104
  ``` cpp
105
- basic_istream<charT, traits>&
106
- operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
107
  ```
108
 
109
  *Effects:* None. This extractor does not behave as a formatted input
110
  function (as described in  [[istream.formatted.reqmts]]).
111
 
112
- *Returns:* `pf(*this)`.[^21]
113
 
114
  ``` cpp
115
- basic_istream<charT, traits>&
116
- operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
117
  ```
118
 
119
  *Effects:* Calls `pf(*this)`. This extractor does not behave as a
120
  formatted input function (as described
121
  in  [[istream.formatted.reqmts]]).
122
 
123
  *Returns:* `*this`.
124
 
125
  ``` cpp
126
- basic_istream<charT, traits>& operator>>(ios_base& (*pf)(ios_base&));
127
  ```
128
 
129
- *Effects:* Calls `pf(*this)`.[^22] This extractor does not behave as a
130
- formatted input function (as described
131
- in  [[istream.formatted.reqmts]]).
 
132
 
133
  *Returns:* `*this`.
134
 
135
  ``` cpp
136
  template<class charT, class traits, size_t N>
@@ -156,12 +203,12 @@ Characters are extracted and stored until any of the following occurs:
156
 
157
  `operator>>` then stores a null byte (`charT()`) in the next position,
158
  which may be the first position if no characters were extracted.
159
  `operator>>` then calls `width(0)`.
160
 
161
- If the function extracted no characters, it calls `setstate(failbit)`,
162
- which may throw `ios_base::failure` [[iostate.flags]].
163
 
164
  *Returns:* `in`.
165
 
166
  ``` cpp
167
  template<class charT, class traits>
@@ -171,36 +218,34 @@ template<class traits>
171
  template<class traits>
172
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
173
  ```
174
 
175
  *Effects:* Behaves like a formatted input member (as described
176
- in  [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
177
- constructed a character is extracted from `in`, if one is available, and
178
- stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
 
179
 
180
  *Returns:* `in`.
181
 
182
  ``` cpp
183
- basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
184
  ```
185
 
186
  *Effects:* Behaves as an unformatted input
187
  function [[istream.unformatted]]. If `sb` is null, calls
188
  `setstate(failbit)`, which may throw `ios_base::failure`
189
- [[iostate.flags]]. After a sentry object is constructed, extracts
190
  characters from `*this` and inserts them in the output sequence
191
  controlled by `sb`. Characters are extracted and inserted until any of
192
  the following occurs:
193
 
194
  - end-of-file occurs on the input sequence;
195
  - inserting in the output sequence fails (in which case the character to
196
  be inserted is not extracted);
197
  - an exception occurs (in which case the exception is caught).
198
 
199
- If the function inserts no characters, it calls `setstate(failbit)`,
200
- which may throw `ios_base::failure` [[iostate.flags]]. If it inserted no
201
- characters because it caught an exception thrown while extracting
202
- characters from `*this` and `failbit` is set in `exceptions()`
203
- [[iostate.flags]], then the caught exception is rethrown.
204
 
205
  *Returns:* `*this`.
206
 
 
1
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2
 
3
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
4
 
5
  Each formatted input function begins execution by constructing an object
6
+ of type `ios_base::iostate`, termed the local error state, and
7
+ initializing it to `ios_base::goodbit`. It then creates an object of
8
+ class `sentry` with the `noskipws` (second) argument `false`. If the
9
  `sentry` object returns `true`, when converted to a value of type
10
+ `bool`, the function endeavors to obtain the requested input. Otherwise,
11
+ if the `sentry` constructor exits by throwing an exception or if the
12
+ `sentry` object produces `false` when converted to a value of type
13
+ `bool`, the function returns without attempting to obtain any input. If
14
+ `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`, then
15
+ `ios_base::eofbit` is set in the local error state and the input
16
+ function stops trying to obtain the requested input. If an exception is
17
+ thrown during input then `ios_base::badbit` is set in the local error
18
+ state, `*this`’s error state is set to the local error state, and the
19
+ exception is rethrown if `(exceptions() & badbit) != 0`. After
20
+ extraction is done, the input function calls `setstate`, which sets
21
+ `*this`’s error state to the local error state, and may throw an
22
+ exception. In any case, the formatted input function destroys the
23
+ `sentry` object. If no exception has been thrown, it returns `*this`.
24
 
25
  ##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
26
 
27
  ``` cpp
28
+ basic_istream& operator>>(unsigned short& val);
29
+ basic_istream& operator>>(unsigned int& val);
30
+ basic_istream& operator>>(long& val);
31
+ basic_istream& operator>>(unsigned long& val);
32
+ basic_istream& operator>>(long long& val);
33
+ basic_istream& operator>>(unsigned long long& val);
34
+ basic_istream& operator>>(float& val);
35
+ basic_istream& operator>>(double& val);
36
+ basic_istream& operator>>(long double& val);
37
+ basic_istream& operator>>(bool& val);
38
+ basic_istream& operator>>(void*& val);
39
  ```
40
 
41
  As in the case of the inserters, these extractors depend on the locale’s
42
  `num_get<>` [[locale.num.get]] object to perform parsing the input
43
  stream data. These extractors behave as formatted input functions (as
44
+ described in  [[istream.formatted.reqmts]]). After a `sentry` object is
45
  constructed, the conversion occurs as if performed by the following code
46
+ fragment, where `state` represents the input function’s local error
47
+ state:
48
 
49
  ``` cpp
50
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
51
+ use_facet<numget>(loc).get(*this, 0, *this, state, val);
 
 
52
  ```
53
 
54
  In the above fragment, `loc` stands for the private member of the
55
  `basic_ios` class.
56
 
 
61
 
62
  Class `locale` relies on this type as its interface to `istream`, so
63
  that it does not need to depend directly on `istream`.
64
 
65
  ``` cpp
66
+ basic_istream& operator>>(short& val);
67
  ```
68
 
69
  The conversion occurs as if performed by the following code fragment
70
  (using the same notation as for the preceding code fragment):
71
 
72
  ``` cpp
73
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
 
74
  long lval;
75
+ use_facet<numget>(loc).get(*this, 0, *this, state, lval);
76
  if (lval < numeric_limits<short>::min()) {
77
+ state |= ios_base::failbit;
78
  val = numeric_limits<short>::min();
79
  } else if (numeric_limits<short>::max() < lval) {
80
+ state |= ios_base::failbit;
81
  val = numeric_limits<short>::max();
82
  } else
83
  val = static_cast<short>(lval);
 
84
  ```
85
 
86
  ``` cpp
87
+ basic_istream& operator>>(int& val);
88
  ```
89
 
90
  The conversion occurs as if performed by the following code fragment
91
  (using the same notation as for the preceding code fragment):
92
 
93
  ``` cpp
94
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
 
95
  long lval;
96
+ use_facet<numget>(loc).get(*this, 0, *this, state, lval);
97
  if (lval < numeric_limits<int>::min()) {
98
+ state |= ios_base::failbit;
99
  val = numeric_limits<int>::min();
100
  } else if (numeric_limits<int>::max() < lval) {
101
+ state |= ios_base::failbit;
102
  val = numeric_limits<int>::max();
103
  } else
104
  val = static_cast<int>(lval);
 
105
  ```
106
 
107
+ ``` cpp
108
+ basic_istream& operator>>(extended-floating-point-type& val);
109
+ ```
110
+
111
+ If the floating-point conversion rank of
112
+ *`extended-floating-point-type`* is not less than or equal to that of
113
+ `long double`, then an invocation of the operator function is
114
+ conditionally supported with *implementation-defined* semantics.
115
+
116
+ Otherwise, let `FP` be a standard floating-point type:
117
+
118
+ - if the floating-point conversion rank of
119
+ *`extended-floating-point-type`* is less than or equal to that of
120
+ `float`, then `FP` is `float`,
121
+ - otherwise, if the floating-point conversion rank of
122
+ *`extended-floating-point-type`* is less than or equal to that of
123
+ `double`, then `FP` is `double`,
124
+ - otherwise, `FP` is `long double`.
125
+
126
+ The conversion occurs as if performed by the following code fragment
127
+ (using the same notation as for the preceding code fragment):
128
+
129
+ ``` cpp
130
+ using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
131
+ FP fval;
132
+ use_facet<numget>(loc).get(*this, 0, *this, state, fval);
133
+ if (fval < -numeric_limits<extended-floating-point-type>::max()) {
134
+ state |= ios_base::failbit;
135
+ val = -numeric_limits<extended-floating-point-type>::max();
136
+ } else if (numeric_limits<extended-floating-point-type>::max() < fval) {
137
+ state |= ios_base::failbit;
138
+ val = numeric_limits<extended-floating-point-type>::max();
139
+ } else {
140
+ val = static_cast<extended-floating-point-type>(fval);
141
+ }
142
+ ```
143
+
144
+ [*Note 2*: When the extended floating-point type has a floating-point
145
+ conversion rank that is not equal to the rank of any standard
146
+ floating-point type, then double rounding during the conversion can
147
+ result in inaccurate results. `from_chars` can be used in situations
148
+ where maximum accuracy is important. — *end note*]
149
+
150
  ##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
151
 
152
  ``` cpp
153
+ basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
 
154
  ```
155
 
156
  *Effects:* None. This extractor does not behave as a formatted input
157
  function (as described in  [[istream.formatted.reqmts]]).
158
 
159
+ *Returns:* `pf(*this)`. [^20]
160
 
161
  ``` cpp
162
+ basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
 
163
  ```
164
 
165
  *Effects:* Calls `pf(*this)`. This extractor does not behave as a
166
  formatted input function (as described
167
  in  [[istream.formatted.reqmts]]).
168
 
169
  *Returns:* `*this`.
170
 
171
  ``` cpp
172
+ basic_istream& operator>>(ios_base& (*pf)(ios_base&));
173
  ```
174
 
175
+ *Effects:* Calls `pf(*this)`.[^21]
176
+
177
+ This extractor does not behave as a formatted input function (as
178
+ described in  [[istream.formatted.reqmts]]).
179
 
180
  *Returns:* `*this`.
181
 
182
  ``` cpp
183
  template<class charT, class traits, size_t N>
 
203
 
204
  `operator>>` then stores a null byte (`charT()`) in the next position,
205
  which may be the first position if no characters were extracted.
206
  `operator>>` then calls `width(0)`.
207
 
208
+ If the function extracted no characters, `ios_base::failbit` is set in
209
+ the input function’s local error state before `setstate` is called.
210
 
211
  *Returns:* `in`.
212
 
213
  ``` cpp
214
  template<class charT, class traits>
 
218
  template<class traits>
219
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
220
  ```
221
 
222
  *Effects:* Behaves like a formatted input member (as described
223
+ in  [[istream.formatted.reqmts]]) of `in`. A character is extracted from
224
+ `in`, if one is available, and stored in `c`. Otherwise,
225
+ `ios_base::failbit` is set in the input function’s local error state
226
+ before `setstate` is called.
227
 
228
  *Returns:* `in`.
229
 
230
  ``` cpp
231
+ basic_istream& operator>>(basic_streambuf<charT, traits>* sb);
232
  ```
233
 
234
  *Effects:* Behaves as an unformatted input
235
  function [[istream.unformatted]]. If `sb` is null, calls
236
  `setstate(failbit)`, which may throw `ios_base::failure`
237
+ [[iostate.flags]]. After a `sentry` object is constructed, extracts
238
  characters from `*this` and inserts them in the output sequence
239
  controlled by `sb`. Characters are extracted and inserted until any of
240
  the following occurs:
241
 
242
  - end-of-file occurs on the input sequence;
243
  - inserting in the output sequence fails (in which case the character to
244
  be inserted is not extracted);
245
  - an exception occurs (in which case the exception is caught).
246
 
247
+ If the function inserts no characters, `ios_base::failbit` is set in the
248
+ input function’s local error state before `setstate` is called.
 
 
 
249
 
250
  *Returns:* `*this`.
251