From Jason Turner

[istream.unformatted]

C++20 → C++23 17.3 KB 197 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/tmpanwgs4qk/{from.md → to.md} +99 -89
tmp/tmpanwgs4qk/{from.md → to.md} RENAMED
@@ -1,96 +1,104 @@
1
  #### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
2
 
3
  Each unformatted input function begins execution by constructing an
4
- object of class `sentry` with the default argument `noskipws` (second)
5
- argument `true`. If the `sentry` object returns `true`, when converted
6
- to a value of type `bool`, the function endeavors to obtain the
7
- requested input. Otherwise, if the sentry constructor exits by throwing
8
- 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_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
23
  streamsize gcount() const;
24
  ```
25
 
26
  *Effects:* None. This member function does not behave as an unformatted
27
  input function (as described above).
28
 
29
  *Returns:* The number of characters extracted by the last unformatted
30
- input member function called for the object.
 
31
 
32
  ``` cpp
33
  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 `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);
57
  ```
58
 
59
  *Effects:* Behaves as an unformatted input function (as described
60
- above). After constructing a sentry object, extracts characters and
61
  stores them into successive locations of an array whose first element is
62
- designated by `s`.[^25] Characters are extracted and stored until any of
63
- the following occurs:
 
64
 
65
  - `n` is less than one or `n - 1` characters are stored;
66
- - end-of-file occurs on the input sequence (in which case the function
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);
80
  ```
81
 
82
  *Effects:* Calls `get(s, n, widen(’\n’))`.
83
 
84
  *Returns:* Value returned by the call.
85
 
86
  ``` cpp
87
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
88
  ```
89
 
90
  *Effects:* Behaves as an unformatted input function (as described
91
- above). After constructing a sentry object, extracts characters and
92
  inserts them in the output sequence controlled by `sb`. Characters are
93
  extracted and inserted until any of the following occurs:
94
 
95
  - end-of-file occurs on the input sequence;
96
  - inserting in the output sequence fails (in which case the character to
@@ -98,45 +106,45 @@ extracted and inserted until any of the following occurs:
98
  - `traits::eq(c, delim)` for the next available input character `c` (in
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);
110
  ```
111
 
112
  *Effects:* Calls `get(sb, widen(’\n’))`.
113
 
114
  *Returns:* Value returned by the call.
115
 
116
  ``` cpp
117
- basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
118
  ```
119
 
120
  *Effects:* Behaves as an unformatted input function (as described
121
- above). After constructing a sentry object, extracts characters and
122
  stores them into successive locations of an array whose first element is
123
- designated by `s`.[^26] Characters are extracted and stored until one of
124
- the following occurs:
125
 
126
- 1. end-of-file occurs on the input sequence (in which case the function
127
- calls `setstate(eofbit)`);
 
128
  2. `traits::eq(c, delim)` for the next available input character `c`
129
  (in which case the input character is extracted but not
130
- stored);[^27]
131
  3. `n` is less than one or `n - 1` characters are stored (in which case
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
 
@@ -170,21 +178,21 @@ int main() {
170
  ```
171
 
172
  — *end example*]
173
 
174
  ``` cpp
175
- basic_istream<charT, traits>& getline(char_type* s, streamsize n);
176
  ```
177
 
178
  *Returns:* `getline(s, n, widen(’\n’))`
179
 
180
  ``` cpp
181
- basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
182
  ```
183
 
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
@@ -192,36 +200,38 @@ occurs:
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())`.
199
 
200
  *Returns:* `*this`.
201
 
202
  ``` cpp
203
  int_type peek();
204
  ```
205
 
206
  *Effects:* Behaves as an unformatted input function (as described
207
- above). After constructing a sentry object, reads but does not extract
208
  the current input character.
209
 
210
  *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
211
  `rdbuf()->sgetc()`.
212
 
213
  ``` cpp
214
- basic_istream<charT, traits>& read(char_type* s, streamsize n);
215
  ```
216
 
217
  *Effects:* Behaves as an unformatted input function (as described
218
- above). After constructing a sentry object, if `!good()` calls
219
  `setstate(failbit)` which may throw an exception, and return. Otherwise
220
  extracts characters and stores them into successive locations of an
221
- 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]]).
@@ -231,11 +241,11 @@ extracted and stored until either of the following occurs:
231
  ``` cpp
232
  streamsize readsome(char_type* s, streamsize n);
233
  ```
234
 
235
  *Effects:* Behaves as an unformatted input function (as described
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;
@@ -244,51 +254,51 @@ array whose first element is designated by `s`. If
244
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
245
 
246
  *Returns:* The number of characters extracted.
247
 
248
  ``` cpp
249
- basic_istream<charT, traits>& putback(char_type c);
250
  ```
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`.
264
-
265
- ``` cpp
266
- basic_istream<charT, traits>& unget();
267
- ```
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`.
281
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
282
  ``` cpp
283
  int sync();
284
  ```
285
 
286
  *Effects:* Behaves as an unformatted input function (as described
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
 
@@ -299,38 +309,38 @@ pos_type tellg();
299
  *Effects:* Behaves as an unformatted input function (as described
300
  above), except that it does not count the number of characters extracted
301
  and does not affect the value returned by subsequent calls to
302
  `gcount()`.
303
 
304
- *Returns:* After constructing a sentry object, if `fail() != false`,
305
  returns `pos_type(-1)` to indicate failure. Otherwise, returns
306
  `rdbuf()->pubseekoff(0, cur, in)`.
307
 
308
  ``` cpp
309
- basic_istream<charT, traits>& seekg(pos_type pos);
310
  ```
311
 
312
  *Effects:* Behaves as an unformatted input function (as described
313
  above), except that the function first clears `eofbit`, it does not
314
  count the number of characters extracted, and it does not affect the
315
  value returned by subsequent calls to `gcount()`. After constructing a
316
- sentry object, if `fail() != true`, executes
317
  `rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
318
  function calls `setstate(failbit)` (which may throw
319
  `ios_base::failure`).
320
 
321
  *Returns:* `*this`.
322
 
323
  ``` cpp
324
- basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
325
  ```
326
 
327
  *Effects:* Behaves as an unformatted input function (as described
328
  above), except that the function first clears `eofbit`, does not count
329
  the number of characters extracted, and does not affect the value
330
- returned by subsequent calls to `gcount()`. After constructing a sentry
331
- object, if `fail() != true`, executes
332
  `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
333
  function calls `setstate(failbit)` (which may throw
334
  `ios_base::failure`).
335
 
336
  *Returns:* `*this`.
 
1
  #### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
2
 
3
  Each unformatted input function begins execution by constructing an
4
+ object of type `ios_base::iostate`, termed the local error state, and
5
+ initializing it to `ios_base::goodbit`. It then creates an object of
6
+ class `sentry` with the default argument `noskipws` (second) argument
7
+ `true`. If the `sentry` object returns `true`, when converted to a value
8
+ of type `bool`, the function endeavors to obtain the requested input.
9
+ Otherwise, if the `sentry` constructor exits by throwing an exception or
10
+ if the `sentry` object produces `false`, when converted to a value of
11
+ type `bool`, the function returns without attempting to obtain any
12
+ input. In either case the number of extracted characters is set to 0;
13
+ unformatted input functions taking a character array of nonzero size as
14
+ an argument shall also store a null character (using `charT()`) in the
15
+ first location of the array. If `rdbuf()->sbumpc()` or
16
+ `rdbuf()->sgetc()` returns `traits::eof()`, then `ios_base::eofbit` is
17
+ set in the local error state and the input function stops trying to
18
+ obtain the requested input. If an exception is thrown during input then
19
+ `ios_base::badbit` is set in the local error state, `*this`’s error
20
+ state is set to the local error state, and the exception is rethrown if
21
+ `(exceptions() & badbit) != 0`. If no exception has been thrown it
22
+ stores the number of characters extracted in a member object. After
23
+ extraction is done, the input function calls `setstate`, which sets
24
+ `*this`’s error state to the local error state, and may throw an
25
+ exception. In any event the `sentry` object is destroyed before leaving
26
+ the unformatted input function.
27
 
28
  ``` cpp
29
  streamsize gcount() const;
30
  ```
31
 
32
  *Effects:* None. This member function does not behave as an unformatted
33
  input function (as described above).
34
 
35
  *Returns:* The number of characters extracted by the last unformatted
36
+ input member function called for the object. If the number cannot be
37
+ represented, returns `numeric_limits<streamsize>::max()`.
38
 
39
  ``` cpp
40
  int_type get();
41
  ```
42
 
43
  *Effects:* Behaves as an unformatted input function (as described
44
+ above). After constructing a `sentry` object, extracts a character `c`,
45
+ if one is available. Otherwise, `ios_base::failbit` is set in the input
46
+ function’s local error state before `setstate` is called.
47
 
48
  *Returns:* `c` if available, otherwise `traits::eof()`.
49
 
50
  ``` cpp
51
+ basic_istream& get(char_type& c);
52
  ```
53
 
54
  *Effects:* Behaves as an unformatted input function (as described
55
+ above). After constructing a `sentry` object, extracts a character, if
56
+ one is available, and assigns it to `c`.[^22]
57
+
58
+ Otherwise, `ios_base::failbit` is set in the input function’s local
59
+ error state before `setstate` is called.
60
 
61
  *Returns:* `*this`.
62
 
63
  ``` cpp
64
+ basic_istream& get(char_type* s, streamsize n, char_type delim);
65
  ```
66
 
67
  *Effects:* Behaves as an unformatted input function (as described
68
+ above). After constructing a `sentry` object, extracts characters and
69
  stores them into successive locations of an array whose first element is
70
+ designated by `s`.[^23]
71
+
72
+ Characters are extracted and stored until any of the following occurs:
73
 
74
  - `n` is less than one or `n - 1` characters are stored;
75
+ - end-of-file occurs on the input sequence;
 
76
  - `traits::eq(c, delim)` for the next available input character `c` (in
77
  which case `c` is not extracted).
78
 
79
+ If the function stores no characters, `ios_base::failbit` is set in the
80
+ input function’s local error state before `setstate` is called. In any
81
+ case, if `n` is greater than zero it then stores a null character into
82
+ the next successive location of the array.
83
 
84
  *Returns:* `*this`.
85
 
86
  ``` cpp
87
+ basic_istream& get(char_type* s, streamsize n);
88
  ```
89
 
90
  *Effects:* Calls `get(s, n, widen(’\n’))`.
91
 
92
  *Returns:* Value returned by the call.
93
 
94
  ``` cpp
95
+ basic_istream& get(basic_streambuf<char_type, traits>& sb, char_type delim);
96
  ```
97
 
98
  *Effects:* Behaves as an unformatted input function (as described
99
+ above). After constructing a `sentry` object, extracts characters and
100
  inserts them in the output sequence controlled by `sb`. Characters are
101
  extracted and inserted until any of the following occurs:
102
 
103
  - end-of-file occurs on the input sequence;
104
  - inserting in the output sequence fails (in which case the character to
 
106
  - `traits::eq(c, delim)` for the next available input character `c` (in
107
  which case `c` is not extracted);
108
  - an exception occurs (in which case, the exception is caught but not
109
  rethrown).
110
 
111
+ If the function inserts no characters, `ios_base::failbit` is set in the
112
+ input function’s local error state before `setstate` is called.
113
 
114
  *Returns:* `*this`.
115
 
116
  ``` cpp
117
+ basic_istream& get(basic_streambuf<char_type, traits>& sb);
118
  ```
119
 
120
  *Effects:* Calls `get(sb, widen(’\n’))`.
121
 
122
  *Returns:* Value returned by the call.
123
 
124
  ``` cpp
125
+ basic_istream& getline(char_type* s, streamsize n, char_type delim);
126
  ```
127
 
128
  *Effects:* Behaves as an unformatted input function (as described
129
+ above). After constructing a `sentry` object, extracts characters and
130
  stores them into successive locations of an array whose first element is
131
+ designated by `s`.[^24]
 
132
 
133
+ Characters are extracted and stored until one of the following occurs:
134
+
135
+ 1. end-of-file occurs on the input sequence;
136
  2. `traits::eq(c, delim)` for the next available input character `c`
137
  (in which case the input character is extracted but not
138
+ stored);[^25]
139
  3. `n` is less than one or `n - 1` characters are stored (in which case
140
  the function calls `setstate(failbit)`).
141
 
142
+ These conditions are tested in the order shown.[^26]
143
 
144
+ If the function extracts no characters, `ios_base::failbit` is set in
145
+ the input function’s local error state before `setstate` is called.[^27]
146
 
147
  In any case, if `n` is greater than zero, it then stores a null
148
  character (using `charT()`) into the next successive location of the
149
  array.
150
 
 
178
  ```
179
 
180
  — *end example*]
181
 
182
  ``` cpp
183
+ basic_istream& getline(char_type* s, streamsize n);
184
  ```
185
 
186
  *Returns:* `getline(s, n, widen(’\n’))`
187
 
188
  ``` cpp
189
+ basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
190
  ```
191
 
192
  *Effects:* Behaves as an unformatted input function (as described
193
+ above). After constructing a `sentry` object, extracts characters and
194
  discards them. Characters are extracted until any of the following
195
  occurs:
196
 
197
  - `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
198
  characters have been extracted so far
 
200
  calls `setstate(eofbit)`, which may throw `ios_base::failure`
201
  [[iostate.flags]]);
202
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
203
  available input character `c` (in which case `c` is extracted).
204
 
205
+ [*Note 1*: The last condition will never occur if
206
+ `traits::eq_int_type(delim, traits::eof())`. — *end note*]
207
 
208
  *Returns:* `*this`.
209
 
210
  ``` cpp
211
  int_type peek();
212
  ```
213
 
214
  *Effects:* Behaves as an unformatted input function (as described
215
+ above). After constructing a `sentry` object, reads but does not extract
216
  the current input character.
217
 
218
  *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
219
  `rdbuf()->sgetc()`.
220
 
221
  ``` cpp
222
+ basic_istream& read(char_type* s, streamsize n);
223
  ```
224
 
225
  *Effects:* Behaves as an unformatted input function (as described
226
+ above). After constructing a `sentry` object, if `!good()` calls
227
  `setstate(failbit)` which may throw an exception, and return. Otherwise
228
  extracts characters and stores them into successive locations of an
229
+ array whose first element is designated by `s`.[^28]
230
+
231
+ Characters are extracted and stored until either of the following
232
+ occurs:
233
 
234
  - `n` characters are stored;
235
  - end-of-file occurs on the input sequence (in which case the function
236
  calls `setstate(failbit | eofbit)`, which may throw
237
  `ios_base::failure` [[iostate.flags]]).
 
241
  ``` cpp
242
  streamsize readsome(char_type* s, streamsize n);
243
  ```
244
 
245
  *Effects:* Behaves as an unformatted input function (as described
246
+ above). After constructing a `sentry` object, if `!good()` calls
247
  `setstate(failbit)` which may throw an exception, and return. Otherwise
248
  extracts characters and stores them into successive locations of an
249
  array whose first element is designated by `s`. If
250
  `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
251
  `ios_base::failure` [[iostate.flags]]), and extracts no characters;
 
254
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
255
 
256
  *Returns:* The number of characters extracted.
257
 
258
  ``` cpp
259
+ basic_istream& putback(char_type c);
260
  ```
261
 
262
  *Effects:* Behaves as an unformatted input function (as described
263
  above), except that the function first clears `eofbit`. After
264
+ constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
265
  which may throw an exception, and return. If `rdbuf()` is not null,
266
  calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
267
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
268
  `ios_base::failure` [[iostate.flags]]).
269
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
270
  [*Note 2*: This function extracts no characters, so the value returned
271
  by the next call to `gcount()` is 0. — *end note*]
272
 
273
  *Returns:* `*this`.
274
 
275
+ ``` cpp
276
+ basic_istream& unget();
277
+ ```
278
+
279
+ *Effects:* Behaves as an unformatted input function (as described
280
+ above), except that the function first clears `eofbit`. After
281
+ constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
282
+ which may throw an exception, and return. If `rdbuf()` is not null,
283
+ calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
284
+ returns `traits::eof()`, calls `setstate(badbit)` (which may throw
285
+ `ios_base::failure` [[iostate.flags]]).
286
+
287
+ [*Note 3*: This function extracts no characters, so the value returned
288
+ by the next call to `gcount()` is 0. — *end note*]
289
+
290
+ *Returns:* `*this`.
291
+
292
  ``` cpp
293
  int sync();
294
  ```
295
 
296
  *Effects:* Behaves as an unformatted input function (as described
297
  above), except that it does not count the number of characters extracted
298
  and does not affect the value returned by subsequent calls to
299
+ `gcount()`. After constructing a `sentry` object, if `rdbuf()` is a null
300
  pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
301
  that function returns `-1` calls `setstate(badbit)` (which may throw
302
  `ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
303
  returns zero.
304
 
 
309
  *Effects:* Behaves as an unformatted input function (as described
310
  above), except that it does not count the number of characters extracted
311
  and does not affect the value returned by subsequent calls to
312
  `gcount()`.
313
 
314
+ *Returns:* After constructing a `sentry` object, if `fail() != false`,
315
  returns `pos_type(-1)` to indicate failure. Otherwise, returns
316
  `rdbuf()->pubseekoff(0, cur, in)`.
317
 
318
  ``` cpp
319
+ basic_istream& seekg(pos_type pos);
320
  ```
321
 
322
  *Effects:* Behaves as an unformatted input function (as described
323
  above), except that the function first clears `eofbit`, it does not
324
  count the number of characters extracted, and it does not affect the
325
  value returned by subsequent calls to `gcount()`. After constructing a
326
+ `sentry` object, if `fail() != true`, executes
327
  `rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
328
  function calls `setstate(failbit)` (which may throw
329
  `ios_base::failure`).
330
 
331
  *Returns:* `*this`.
332
 
333
  ``` cpp
334
+ basic_istream& seekg(off_type off, ios_base::seekdir dir);
335
  ```
336
 
337
  *Effects:* Behaves as an unformatted input function (as described
338
  above), except that the function first clears `eofbit`, does not count
339
  the number of characters extracted, and does not affect the value
340
+ returned by subsequent calls to `gcount()`. After constructing a
341
+ `sentry` object, if `fail() != true`, executes
342
  `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
343
  function calls `setstate(failbit)` (which may throw
344
  `ios_base::failure`).
345
 
346
  *Returns:* `*this`.