From Jason Turner

[ios.base]

C++14 → C++17 11.3 KB 97 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmprn6ywm8u/{from.md → to.md} +46 -31
tmp/tmprn6ywm8u/{from.md → to.md} RENAMED
@@ -2,14 +2,14 @@
2
 
3
  ``` cpp
4
  namespace std {
5
  class ios_base {
6
  public:
7
- class failure;
8
 
9
- // [ios::fmtflags] fmtflags
10
- typedef T1 fmtflags;
11
  static constexpr fmtflags boolalpha = unspecified;
12
  static constexpr fmtflags dec = unspecified;
13
  static constexpr fmtflags fixed = unspecified;
14
  static constexpr fmtflags hex = unspecified;
15
  static constexpr fmtflags internal = unspecified;
@@ -25,35 +25,35 @@ namespace std {
25
  static constexpr fmtflags uppercase = unspecified;
26
  static constexpr fmtflags adjustfield = see below;
27
  static constexpr fmtflags basefield = see below;
28
  static constexpr fmtflags floatfield = see below;
29
 
30
- // [ios::iostate] iostate
31
- typedef T2 iostate;
32
  static constexpr iostate badbit = unspecified;
33
  static constexpr iostate eofbit = unspecified;
34
  static constexpr iostate failbit = unspecified;
35
  static constexpr iostate goodbit = see below;
36
 
37
- // [ios::openmode] openmode
38
- typedef T3 openmode;
39
  static constexpr openmode app = unspecified;
40
  static constexpr openmode ate = unspecified;
41
  static constexpr openmode binary = unspecified;
42
  static constexpr openmode in = unspecified;
43
  static constexpr openmode out = unspecified;
44
  static constexpr openmode trunc = unspecified;
45
 
46
- // [ios::seekdir] seekdir
47
- typedef T4 seekdir;
48
  static constexpr seekdir beg = unspecified;
49
  static constexpr seekdir cur = unspecified;
50
  static constexpr seekdir end = unspecified;
51
 
52
  class Init;
53
 
54
- // [fmtflags.state] fmtflags state:
55
  fmtflags flags() const;
56
  fmtflags flags(fmtflags fmtfl);
57
  fmtflags setf(fmtflags fmtfl);
58
  fmtflags setf(fmtflags fmtfl, fmtflags mask);
59
  void unsetf(fmtflags mask);
@@ -61,25 +61,25 @@ namespace std {
61
  streamsize precision() const;
62
  streamsize precision(streamsize prec);
63
  streamsize width() const;
64
  streamsize width(streamsize wide);
65
 
66
- // [ios.base.locales] locales:
67
  locale imbue(const locale& loc);
68
  locale getloc() const;
69
 
70
- // [ios.base.storage] storage:
71
  static int xalloc();
72
  long& iword(int index);
73
  void*& pword(int index);
74
 
75
- // destructor
76
  virtual ~ios_base();
77
 
78
- // [ios.base.callback] callbacks;
79
  enum event { erase_event, imbue_event, copyfmt_event };
80
- typedef void (*event_callback)(event, ios_base&, int index);
81
  void register_callback(event_callback fn, int index);
82
 
83
  ios_base(const ios_base&) = delete;
84
  ios_base& operator=(const ios_base&) = delete;
85
 
@@ -98,11 +98,12 @@ namespace std {
98
 
99
  `ios_base`
100
 
101
  defines several member types:
102
 
103
- - a class `failure` derived from `system_error`;
 
104
  - a class `Init`;
105
  - three bitmask types, `fmtflags`, `iostate`, and `openmode`;
106
  - an enumerated type, `seekdir`.
107
 
108
  It maintains several kinds of data:
@@ -111,20 +112,24 @@ It maintains several kinds of data:
111
  - control information that influences how to interpret (format) input
112
  sequences and how to generate (format) output sequences;
113
  - additional information that is stored by the program for its private
114
  use.
115
 
 
 
116
  For the sake of exposition, the maintained data is presented here as:
117
 
118
  - `static int index`, specifies the next available unique index for the
119
  integer or pointer arrays maintained for the private use of the
120
  program, initialized to an unspecified value;
121
  - `long* iarray`, points to the first element of an arbitrary-length
122
  `long` array maintained for the private use of the program;
123
  - `void** parray`, points to the first element of an arbitrary-length
124
  pointer array maintained for the private use of the program.
125
 
 
 
126
  #### Types <a id="ios.types">[[ios.types]]</a>
127
 
128
  ##### Class `ios_base::failure` <a id="ios::failure">[[ios::failure]]</a>
129
 
130
  ``` cpp
@@ -135,22 +140,32 @@ namespace std {
135
  explicit failure(const char* msg, const error_code& ec = io_errc::stream);
136
  };
137
  }
138
  ```
139
 
 
 
 
 
 
 
 
 
140
  The class `failure` defines the base class for the types of all objects
141
  thrown as exceptions, by functions in the iostreams library, to report
142
  errors detected during stream buffer operations.
143
 
144
  When throwing `ios_base::failure` exceptions, implementations should
145
  provide values of `ec` that identify the specific reason for the
146
- failure. Errors arising from the operating system would typically be
 
 
147
  reported as `system_category()` errors with an error value of the error
148
  number reported by the operating system. Errors arising from within the
149
  stream library would typically be reported as
150
  `error_code(io_errc::stream,
151
- iostream_category())`.
152
 
153
  ``` cpp
154
  explicit failure(const string& msg, const error_code& ec = io_errc::stream);
155
  ```
156
 
@@ -165,11 +180,11 @@ explicit failure(const char* msg, const error_code& ec = io_errc::stream);
165
  base class with `msg` and `ec`.
166
 
167
  ##### Type `ios_base::fmtflags` <a id="ios::fmtflags">[[ios::fmtflags]]</a>
168
 
169
  ``` cpp
170
- typedef T1 fmtflags;
171
  ```
172
 
173
  The type `fmtflags` is a bitmask type ([[bitmask.types]]). Setting its
174
  elements has the effects indicated in
175
  Table  [[tab:iostreams.fmtflags.effects]].
@@ -208,11 +223,11 @@ Table  [[tab:iostreams.fmtflags.constants]].
208
 
209
 
210
  ##### Type `ios_base::iostate` <a id="ios::iostate">[[ios::iostate]]</a>
211
 
212
  ``` cpp
213
- typedef T2 iostate;
214
  ```
215
 
216
  The type `iostate` is a bitmask type ([[bitmask.types]]) that contains
217
  the elements indicated in Table  [[tab:iostreams.iostate.effects]].
218
 
@@ -230,11 +245,11 @@ Type `iostate` also defines the constant:
230
  - `goodbit`, the value zero.
231
 
232
  ##### Type `ios_base::openmode` <a id="ios::openmode">[[ios::openmode]]</a>
233
 
234
  ``` cpp
235
- typedef T3 openmode;
236
  ```
237
 
238
  The type `openmode` is a bitmask type ([[bitmask.types]]). It contains
239
  the elements indicated in Table  [[tab:iostreams.openmode.effects]].
240
 
@@ -251,11 +266,11 @@ the elements indicated in Table  [[tab:iostreams.openmode.effects]].
251
 
252
 
253
  ##### Type `ios_base::seekdir` <a id="ios::seekdir">[[ios::seekdir]]</a>
254
 
255
  ``` cpp
256
- typedef T4 seekdir;
257
  ```
258
 
259
  The type `seekdir` is an enumerated type ([[enumerated.types]]) that
260
  contains the elements indicated in
261
  Table  [[tab:iostreams.seekdir.effects]].
@@ -285,11 +300,11 @@ namespace std {
285
 
286
  The class `Init` describes an object whose construction ensures the
287
  construction of the eight objects declared in `<iostream>` (
288
  [[iostream.objects]]) that associate file stream buffers with the
289
  standard C streams provided for by the functions declared in
290
- `<cstdio>` ([[c.files]]).
291
 
292
  For the sake of exposition, the maintained data is presented here as:
293
 
294
  - `static int init_cnt`, counts the number of constructor and destructor
295
  calls for class `Init`, initialized to zero.
@@ -322,11 +337,11 @@ fmtflags flags() const;
322
 
323
  ``` cpp
324
  fmtflags flags(fmtflags fmtfl);
325
  ```
326
 
327
- `fmtfl == flags()`.
328
 
329
  *Returns:* The previous value of `flags()`.
330
 
331
  ``` cpp
332
  fmtflags setf(fmtflags fmtfl);
@@ -358,11 +373,11 @@ streamsize precision() const;
358
 
359
  ``` cpp
360
  streamsize precision(streamsize prec);
361
  ```
362
 
363
- `prec == precision()`.
364
 
365
  *Returns:* The previous value of `precision()`.
366
 
367
  ``` cpp
368
  streamsize width() const;
@@ -373,11 +388,11 @@ certain output conversions.
373
 
374
  ``` cpp
375
  streamsize width(streamsize wide);
376
  ```
377
 
378
- `wide == width()`.
379
 
380
  *Returns:* The previous value of `width()`.
381
 
382
  #### `ios_base` functions <a id="ios.base.locales">[[ios.base.locales]]</a>
383
 
@@ -391,11 +406,11 @@ locale imbue(const locale& loc);
391
  `ios_base::getloc()` from within `fn` returns the new locale value
392
  `loc`.
393
 
394
  *Returns:* The previous value of `getloc()`.
395
 
396
- `loc == getloc()`.
397
 
398
  ``` cpp
399
  locale getloc() const;
400
  ```
401
 
@@ -414,11 +429,11 @@ bool sync_with_stdio(bool sync = true);
414
  objects ([[iostream.objects]]) was synchronized and otherwise returns
415
  `false`. The first time it is called, the function returns `true`.
416
 
417
  *Effects:* If any input or output operation has occurred using the
418
  standard streams prior to the call, the effect is
419
- *implementation-defined*. Otherwise, called with a false argument, it
420
  allows the standard streams to operate independently of the standard C
421
  streams.
422
 
423
  When a standard iostream object `str` is *synchronized* with a standard
424
  stdio stream `f`, the effect of inserting a character `c` by
@@ -482,11 +497,11 @@ of unspecified size and stores a pointer to its first element in
482
  necessary to include the element `iarray[idx]`. Each newly allocated
483
  element of the array is initialized to zero. The reference returned is
484
  invalid after any other operations on the object.[^7] However, the value
485
  of the storage referred to is retained, so that until the next call to
486
  `copyfmt`, calling `iword` with the same index yields another reference
487
- to the same value. If the function fails[^8] and `*this` is a base
488
  subobject of a `basic_ios<>` object or subobject, the effect is
489
  equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
490
  object (which may throw `failure`).
491
 
492
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
@@ -503,12 +518,12 @@ as necessary to include the element `parray[idx]`. Each newly allocated
503
  element of the array is initialized to a null pointer. The reference
504
  returned is invalid after any other operations on the object. However,
505
  the value of the storage referred to is retained, so that until the next
506
  call to `copyfmt`, calling `pword` with the same index yields another
507
  reference to the same value. If the function fails[^9] and `*this` is a
508
- base subobject of a `basic_ios<>` object or subobject, the effect is
509
- equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
510
  object (which may throw `failure`).
511
 
512
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
513
  initialized to 0.
514
 
 
2
 
3
  ``` cpp
4
  namespace std {
5
  class ios_base {
6
  public:
7
+ class failure; // see below
8
 
9
+ // [ios::fmtflags], fmtflags
10
+ using fmtflags = T1;
11
  static constexpr fmtflags boolalpha = unspecified;
12
  static constexpr fmtflags dec = unspecified;
13
  static constexpr fmtflags fixed = unspecified;
14
  static constexpr fmtflags hex = unspecified;
15
  static constexpr fmtflags internal = unspecified;
 
25
  static constexpr fmtflags uppercase = unspecified;
26
  static constexpr fmtflags adjustfield = see below;
27
  static constexpr fmtflags basefield = see below;
28
  static constexpr fmtflags floatfield = see below;
29
 
30
+ // [ios::iostate], iostate
31
+ using iostate = T2;
32
  static constexpr iostate badbit = unspecified;
33
  static constexpr iostate eofbit = unspecified;
34
  static constexpr iostate failbit = unspecified;
35
  static constexpr iostate goodbit = see below;
36
 
37
+ // [ios::openmode], openmode
38
+ using openmode = T3;
39
  static constexpr openmode app = unspecified;
40
  static constexpr openmode ate = unspecified;
41
  static constexpr openmode binary = unspecified;
42
  static constexpr openmode in = unspecified;
43
  static constexpr openmode out = unspecified;
44
  static constexpr openmode trunc = unspecified;
45
 
46
+ // [ios::seekdir], seekdir
47
+ using seekdir = T4;
48
  static constexpr seekdir beg = unspecified;
49
  static constexpr seekdir cur = unspecified;
50
  static constexpr seekdir end = unspecified;
51
 
52
  class Init;
53
 
54
+ // [fmtflags.state], fmtflags state
55
  fmtflags flags() const;
56
  fmtflags flags(fmtflags fmtfl);
57
  fmtflags setf(fmtflags fmtfl);
58
  fmtflags setf(fmtflags fmtfl, fmtflags mask);
59
  void unsetf(fmtflags mask);
 
61
  streamsize precision() const;
62
  streamsize precision(streamsize prec);
63
  streamsize width() const;
64
  streamsize width(streamsize wide);
65
 
66
+ // [ios.base.locales], locales
67
  locale imbue(const locale& loc);
68
  locale getloc() const;
69
 
70
+ // [ios.base.storage], storage
71
  static int xalloc();
72
  long& iword(int index);
73
  void*& pword(int index);
74
 
75
+ // destructor:
76
  virtual ~ios_base();
77
 
78
+ // [ios.base.callback], callbacks;
79
  enum event { erase_event, imbue_event, copyfmt_event };
80
+ using event_callback = void (*)(event, ios_base&, int index);
81
  void register_callback(event_callback fn, int index);
82
 
83
  ios_base(const ios_base&) = delete;
84
  ios_base& operator=(const ios_base&) = delete;
85
 
 
98
 
99
  `ios_base`
100
 
101
  defines several member types:
102
 
103
+ - a type `failure`, defined as either a class derived from
104
+ `system_error` or a synonym for a class derived from `system_error`;
105
  - a class `Init`;
106
  - three bitmask types, `fmtflags`, `iostate`, and `openmode`;
107
  - an enumerated type, `seekdir`.
108
 
109
  It maintains several kinds of data:
 
112
  - control information that influences how to interpret (format) input
113
  sequences and how to generate (format) output sequences;
114
  - additional information that is stored by the program for its private
115
  use.
116
 
117
+ [*Note 1*:
118
+
119
  For the sake of exposition, the maintained data is presented here as:
120
 
121
  - `static int index`, specifies the next available unique index for the
122
  integer or pointer arrays maintained for the private use of the
123
  program, initialized to an unspecified value;
124
  - `long* iarray`, points to the first element of an arbitrary-length
125
  `long` array maintained for the private use of the program;
126
  - `void** parray`, points to the first element of an arbitrary-length
127
  pointer array maintained for the private use of the program.
128
 
129
+ — *end note*]
130
+
131
  #### Types <a id="ios.types">[[ios.types]]</a>
132
 
133
  ##### Class `ios_base::failure` <a id="ios::failure">[[ios::failure]]</a>
134
 
135
  ``` cpp
 
140
  explicit failure(const char* msg, const error_code& ec = io_errc::stream);
141
  };
142
  }
143
  ```
144
 
145
+ An implementation is permitted to define `ios_base::failure` as a
146
+ synonym for a class with equivalent functionality to class
147
+ `ios_base::failure` shown in this subclause.
148
+
149
+ [*Note 1*: When `ios_base::failure` is a synonym for another type it
150
+ shall provide a nested type `failure`, to emulate the injected class
151
+ name. — *end note*]
152
+
153
  The class `failure` defines the base class for the types of all objects
154
  thrown as exceptions, by functions in the iostreams library, to report
155
  errors detected during stream buffer operations.
156
 
157
  When throwing `ios_base::failure` exceptions, implementations should
158
  provide values of `ec` that identify the specific reason for the
159
+ failure.
160
+
161
+ [*Note 2*: Errors arising from the operating system would typically be
162
  reported as `system_category()` errors with an error value of the error
163
  number reported by the operating system. Errors arising from within the
164
  stream library would typically be reported as
165
  `error_code(io_errc::stream,
166
+ iostream_category())`. — *end note*]
167
 
168
  ``` cpp
169
  explicit failure(const string& msg, const error_code& ec = io_errc::stream);
170
  ```
171
 
 
180
  base class with `msg` and `ec`.
181
 
182
  ##### Type `ios_base::fmtflags` <a id="ios::fmtflags">[[ios::fmtflags]]</a>
183
 
184
  ``` cpp
185
+ using fmtflags = T1;
186
  ```
187
 
188
  The type `fmtflags` is a bitmask type ([[bitmask.types]]). Setting its
189
  elements has the effects indicated in
190
  Table  [[tab:iostreams.fmtflags.effects]].
 
223
 
224
 
225
  ##### Type `ios_base::iostate` <a id="ios::iostate">[[ios::iostate]]</a>
226
 
227
  ``` cpp
228
+ using iostate = T2;
229
  ```
230
 
231
  The type `iostate` is a bitmask type ([[bitmask.types]]) that contains
232
  the elements indicated in Table  [[tab:iostreams.iostate.effects]].
233
 
 
245
  - `goodbit`, the value zero.
246
 
247
  ##### Type `ios_base::openmode` <a id="ios::openmode">[[ios::openmode]]</a>
248
 
249
  ``` cpp
250
+ using openmode = T3;
251
  ```
252
 
253
  The type `openmode` is a bitmask type ([[bitmask.types]]). It contains
254
  the elements indicated in Table  [[tab:iostreams.openmode.effects]].
255
 
 
266
 
267
 
268
  ##### Type `ios_base::seekdir` <a id="ios::seekdir">[[ios::seekdir]]</a>
269
 
270
  ``` cpp
271
+ using seekdir = T4;
272
  ```
273
 
274
  The type `seekdir` is an enumerated type ([[enumerated.types]]) that
275
  contains the elements indicated in
276
  Table  [[tab:iostreams.seekdir.effects]].
 
300
 
301
  The class `Init` describes an object whose construction ensures the
302
  construction of the eight objects declared in `<iostream>` (
303
  [[iostream.objects]]) that associate file stream buffers with the
304
  standard C streams provided for by the functions declared in
305
+ `<cstdio>` ([[cstdio.syn]]).
306
 
307
  For the sake of exposition, the maintained data is presented here as:
308
 
309
  - `static int init_cnt`, counts the number of constructor and destructor
310
  calls for class `Init`, initialized to zero.
 
337
 
338
  ``` cpp
339
  fmtflags flags(fmtflags fmtfl);
340
  ```
341
 
342
+ *Postconditions:* `fmtfl == flags()`.
343
 
344
  *Returns:* The previous value of `flags()`.
345
 
346
  ``` cpp
347
  fmtflags setf(fmtflags fmtfl);
 
373
 
374
  ``` cpp
375
  streamsize precision(streamsize prec);
376
  ```
377
 
378
+ *Postconditions:* `prec == precision()`.
379
 
380
  *Returns:* The previous value of `precision()`.
381
 
382
  ``` cpp
383
  streamsize width() const;
 
388
 
389
  ``` cpp
390
  streamsize width(streamsize wide);
391
  ```
392
 
393
+ *Postconditions:* `wide == width()`.
394
 
395
  *Returns:* The previous value of `width()`.
396
 
397
  #### `ios_base` functions <a id="ios.base.locales">[[ios.base.locales]]</a>
398
 
 
406
  `ios_base::getloc()` from within `fn` returns the new locale value
407
  `loc`.
408
 
409
  *Returns:* The previous value of `getloc()`.
410
 
411
+ *Postconditions:* `loc == getloc()`.
412
 
413
  ``` cpp
414
  locale getloc() const;
415
  ```
416
 
 
429
  objects ([[iostream.objects]]) was synchronized and otherwise returns
430
  `false`. The first time it is called, the function returns `true`.
431
 
432
  *Effects:* If any input or output operation has occurred using the
433
  standard streams prior to the call, the effect is
434
+ *implementation-defined*. Otherwise, called with a `false` argument, it
435
  allows the standard streams to operate independently of the standard C
436
  streams.
437
 
438
  When a standard iostream object `str` is *synchronized* with a standard
439
  stdio stream `f`, the effect of inserting a character `c` by
 
497
  necessary to include the element `iarray[idx]`. Each newly allocated
498
  element of the array is initialized to zero. The reference returned is
499
  invalid after any other operations on the object.[^7] However, the value
500
  of the storage referred to is retained, so that until the next call to
501
  `copyfmt`, calling `iword` with the same index yields another reference
502
+ to the same value. If the function fails[^8] and `*this` is a base class
503
  subobject of a `basic_ios<>` object or subobject, the effect is
504
  equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
505
  object (which may throw `failure`).
506
 
507
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
 
518
  element of the array is initialized to a null pointer. The reference
519
  returned is invalid after any other operations on the object. However,
520
  the value of the storage referred to is retained, so that until the next
521
  call to `copyfmt`, calling `pword` with the same index yields another
522
  reference to the same value. If the function fails[^9] and `*this` is a
523
+ base class subobject of a `basic_ios<>` object or subobject, the effect
524
+ is equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
525
  object (which may throw `failure`).
526
 
527
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
528
  initialized to 0.
529