From Jason Turner

[istream.unformatted]

C++17 → C++20 8.3 KB 57 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp5bjxzzqh/{from.md → to.md} +22 -22
tmp/tmp5bjxzzqh/{from.md → to.md} RENAMED
@@ -9,14 +9,14 @@ an exception or if the sentry object returns `false`, when converted to
9
  a value of type `bool`, the function returns without attempting to
10
  obtain any input. In either case the number of extracted characters is
11
  set to 0; unformatted input functions taking a character array of
12
  nonzero size as an argument shall also store a null character (using
13
  `charT()`) in the first location of the array. If an exception is thrown
14
- during input then `ios::badbit` is turned on[^23] in `*this`’s error
15
- state. (Exceptions thrown from `basic_ios<>::clear()` are not caught or
16
- rethrown.) If `(exceptions()&badbit) != 0` then the exception is
17
- rethrown. It also counts the number of characters extracted. If no
18
  exception has been thrown it ends by storing the count in a member
19
  object and returning the value specified. In any event the `sentry`
20
  object is destroyed before leaving the unformatted input function.
21
 
22
  ``` cpp
@@ -34,23 +34,23 @@ int_type get();
34
  ```
35
 
36
  *Effects:* Behaves as an unformatted input function (as described
37
  above). After constructing a sentry object, extracts a character `c`, if
38
  one is available. Otherwise, the function calls `setstate(failbit)`,
39
- which may throw `ios_base::failure` ([[iostate.flags]]),
40
 
41
  *Returns:* `c` if available, otherwise `traits::eof()`.
42
 
43
  ``` cpp
44
  basic_istream<charT, traits>& get(char_type& c);
45
  ```
46
 
47
  *Effects:* Behaves as an unformatted input function (as described
48
  above). After constructing a sentry object, extracts a character, if one
49
  is available, and assigns it to `c`.[^24] Otherwise, the function calls
50
- `setstate(failbit)` (which may throw
51
- `ios_base::failure` ([[iostate.flags]])).
52
 
53
  *Returns:* `*this`.
54
 
55
  ``` cpp
56
  basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
@@ -67,13 +67,13 @@ the following occurs:
67
  calls `setstate(eofbit)`);
68
  - `traits::eq(c, delim)` for the next available input character `c` (in
69
  which case `c` is not extracted).
70
 
71
  If the function stores no characters, it calls `setstate(failbit)`
72
- (which may throw `ios_base::failure` ([[iostate.flags]])). In any case,
73
- if `n` is greater than zero it then stores a null character into the
74
- next successive location of the array.
75
 
76
  *Returns:* `*this`.
77
 
78
  ``` cpp
79
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
@@ -99,11 +99,11 @@ extracted and inserted until any of the following occurs:
99
  which case `c` is not extracted);
100
  - an exception occurs (in which case, the exception is caught but not
101
  rethrown).
102
 
103
  If the function inserts no characters, it calls `setstate(failbit)`,
104
- which may throw `ios_base::failure` ([[iostate.flags]]).
105
 
106
  *Returns:* `*this`.
107
 
108
  ``` cpp
109
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
@@ -132,11 +132,11 @@ the following occurs:
132
  the function calls `setstate(failbit)`).
133
 
134
  These conditions are tested in the order shown.[^28]
135
 
136
  If the function extracts no characters, it calls `setstate(failbit)`
137
- (which may throw `ios_base::failure` ([[iostate.flags]])).[^29]
138
 
139
  In any case, if `n` is greater than zero, it then stores a null
140
  character (using `charT()`) into the next successive location of the
141
  array.
142
 
@@ -184,15 +184,15 @@ basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::
184
  *Effects:* Behaves as an unformatted input function (as described
185
  above). After constructing a sentry object, extracts characters and
186
  discards them. Characters are extracted until any of the following
187
  occurs:
188
 
189
- - `n != numeric_limits<streamsize>::max()` ([[numeric.limits]]) and `n`
190
  characters have been extracted so far
191
  - end-of-file occurs on the input sequence (in which case the function
192
- calls `setstate(eofbit)`, which may throw
193
- `ios_base::failure` ([[iostate.flags]]));
194
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
195
  available input character `c` (in which case `c` is extracted).
196
 
197
  *Remarks:* The last condition will never occur if
198
  `traits::eq_int_type(delim, traits::eof())`.
@@ -222,11 +222,11 @@ array whose first element is designated by `s`.[^30] Characters are
222
  extracted and stored until either of the following occurs:
223
 
224
  - `n` characters are stored;
225
  - end-of-file occurs on the input sequence (in which case the function
226
  calls `setstate(failbit | eofbit)`, which may throw
227
- `ios_base::failure` ([[iostate.flags]])).
228
 
229
  *Returns:* `*this`.
230
 
231
  ``` cpp
232
  streamsize readsome(char_type* s, streamsize n);
@@ -236,11 +236,11 @@ streamsize readsome(char_type* s, streamsize n);
236
  above). After constructing a sentry object, if `!good()` calls
237
  `setstate(failbit)` which may throw an exception, and return. Otherwise
238
  extracts characters and stores them into successive locations of an
239
  array whose first element is designated by `s`. If
240
  `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
241
- `ios_base::failure` ([[iostate.flags]])), and extracts no characters;
242
 
243
  - If `rdbuf()->in_avail() == 0`, extracts no characters
244
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
245
 
246
  *Returns:* The number of characters extracted.
@@ -251,13 +251,13 @@ basic_istream<charT, traits>& putback(char_type c);
251
 
252
  *Effects:* Behaves as an unformatted input function (as described
253
  above), except that the function first clears `eofbit`. After
254
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
255
  which may throw an exception, and return. If `rdbuf()` is not null,
256
- calls `rdbuf->sputbackc()`. If `rdbuf()` is null, or if `sputbackc()`
257
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
258
- `ios_base::failure` ([[iostate.flags]])).
259
 
260
  [*Note 1*: This function extracts no characters, so the value returned
261
  by the next call to `gcount()` is 0. — *end note*]
262
 
263
  *Returns:* `*this`.
@@ -268,13 +268,13 @@ basic_istream<charT, traits>& unget();
268
 
269
  *Effects:* Behaves as an unformatted input function (as described
270
  above), except that the function first clears `eofbit`. After
271
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
272
  which may throw an exception, and return. If `rdbuf()` is not null,
273
- calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc()`
274
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
275
- `ios_base::failure` ([[iostate.flags]])).
276
 
277
  [*Note 2*: This function extracts no characters, so the value returned
278
  by the next call to `gcount()` is 0. — *end note*]
279
 
280
  *Returns:* `*this`.
@@ -287,11 +287,11 @@ int sync();
287
  above), except that it does not count the number of characters extracted
288
  and does not affect the value returned by subsequent calls to
289
  `gcount()`. After constructing a sentry object, if `rdbuf()` is a null
290
  pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
291
  that function returns `-1` calls `setstate(badbit)` (which may throw
292
- `ios_base::failure` ([[iostate.flags]]), and returns `-1`. Otherwise,
293
  returns zero.
294
 
295
  ``` cpp
296
  pos_type tellg();
297
  ```
 
9
  a value of type `bool`, the function returns without attempting to
10
  obtain any input. In either case the number of extracted characters is
11
  set to 0; unformatted input functions taking a character array of
12
  nonzero size as an argument shall also store a null character (using
13
  `charT()`) in the first location of the array. If an exception is thrown
14
+ during input then `ios_base::badbit` is turned on[^23] in `*this`’s
15
+ error state. (Exceptions thrown from `basic_ios<>::clear()` are not
16
+ caught or rethrown.) If `(exceptions()&badbit) != 0` then the exception
17
+ is rethrown. It also counts the number of characters extracted. If no
18
  exception has been thrown it ends by storing the count in a member
19
  object and returning the value specified. In any event the `sentry`
20
  object is destroyed before leaving the unformatted input function.
21
 
22
  ``` cpp
 
34
  ```
35
 
36
  *Effects:* Behaves as an unformatted input function (as described
37
  above). After constructing a sentry object, extracts a character `c`, if
38
  one is available. Otherwise, the function calls `setstate(failbit)`,
39
+ which may throw `ios_base::failure` [[iostate.flags]].
40
 
41
  *Returns:* `c` if available, otherwise `traits::eof()`.
42
 
43
  ``` cpp
44
  basic_istream<charT, traits>& get(char_type& c);
45
  ```
46
 
47
  *Effects:* Behaves as an unformatted input function (as described
48
  above). After constructing a sentry object, extracts a character, if one
49
  is available, and assigns it to `c`.[^24] Otherwise, the function calls
50
+ `setstate(failbit)` (which may throw `ios_base::failure`
51
+ [[iostate.flags]]).
52
 
53
  *Returns:* `*this`.
54
 
55
  ``` cpp
56
  basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
 
67
  calls `setstate(eofbit)`);
68
  - `traits::eq(c, delim)` for the next available input character `c` (in
69
  which case `c` is not extracted).
70
 
71
  If the function stores no characters, it calls `setstate(failbit)`
72
+ (which may throw `ios_base::failure` [[iostate.flags]]). In any case, if
73
+ `n` is greater than zero it then stores a null character into the next
74
+ successive location of the array.
75
 
76
  *Returns:* `*this`.
77
 
78
  ``` cpp
79
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
 
99
  which case `c` is not extracted);
100
  - an exception occurs (in which case, the exception is caught but not
101
  rethrown).
102
 
103
  If the function inserts no characters, it calls `setstate(failbit)`,
104
+ which may throw `ios_base::failure` [[iostate.flags]].
105
 
106
  *Returns:* `*this`.
107
 
108
  ``` cpp
109
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
 
132
  the function calls `setstate(failbit)`).
133
 
134
  These conditions are tested in the order shown.[^28]
135
 
136
  If the function extracts no characters, it calls `setstate(failbit)`
137
+ (which may throw `ios_base::failure` [[iostate.flags]]).[^29]
138
 
139
  In any case, if `n` is greater than zero, it then stores a null
140
  character (using `charT()`) into the next successive location of the
141
  array.
142
 
 
184
  *Effects:* Behaves as an unformatted input function (as described
185
  above). After constructing a sentry object, extracts characters and
186
  discards them. Characters are extracted until any of the following
187
  occurs:
188
 
189
+ - `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
190
  characters have been extracted so far
191
  - end-of-file occurs on the input sequence (in which case the function
192
+ calls `setstate(eofbit)`, which may throw `ios_base::failure`
193
+ [[iostate.flags]]);
194
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
195
  available input character `c` (in which case `c` is extracted).
196
 
197
  *Remarks:* The last condition will never occur if
198
  `traits::eq_int_type(delim, traits::eof())`.
 
222
  extracted and stored until either of the following occurs:
223
 
224
  - `n` characters are stored;
225
  - end-of-file occurs on the input sequence (in which case the function
226
  calls `setstate(failbit | eofbit)`, which may throw
227
+ `ios_base::failure` [[iostate.flags]]).
228
 
229
  *Returns:* `*this`.
230
 
231
  ``` cpp
232
  streamsize readsome(char_type* s, streamsize n);
 
236
  above). After constructing a sentry object, if `!good()` calls
237
  `setstate(failbit)` which may throw an exception, and return. Otherwise
238
  extracts characters and stores them into successive locations of an
239
  array whose first element is designated by `s`. If
240
  `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
241
+ `ios_base::failure` [[iostate.flags]]), and extracts no characters;
242
 
243
  - If `rdbuf()->in_avail() == 0`, extracts no characters
244
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
245
 
246
  *Returns:* The number of characters extracted.
 
251
 
252
  *Effects:* Behaves as an unformatted input function (as described
253
  above), except that the function first clears `eofbit`. After
254
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
255
  which may throw an exception, and return. If `rdbuf()` is not null,
256
+ calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
257
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
258
+ `ios_base::failure` [[iostate.flags]]).
259
 
260
  [*Note 1*: This function extracts no characters, so the value returned
261
  by the next call to `gcount()` is 0. — *end note*]
262
 
263
  *Returns:* `*this`.
 
268
 
269
  *Effects:* Behaves as an unformatted input function (as described
270
  above), except that the function first clears `eofbit`. After
271
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
272
  which may throw an exception, and return. If `rdbuf()` is not null,
273
+ calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
274
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
275
+ `ios_base::failure` [[iostate.flags]]).
276
 
277
  [*Note 2*: This function extracts no characters, so the value returned
278
  by the next call to `gcount()` is 0. — *end note*]
279
 
280
  *Returns:* `*this`.
 
287
  above), except that it does not count the number of characters extracted
288
  and does not affect the value returned by subsequent calls to
289
  `gcount()`. After constructing a sentry object, if `rdbuf()` is a null
290
  pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
291
  that function returns `-1` calls `setstate(badbit)` (which may throw
292
+ `ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
293
  returns zero.
294
 
295
  ``` cpp
296
  pos_type tellg();
297
  ```