From Jason Turner

[iostreams.base]

C++20 → C++23 12.6 KB 122 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/tmpfobv6_38/{from.md → to.md} +47 -56
tmp/tmpfobv6_38/{from.md → to.md} RENAMED
@@ -62,30 +62,14 @@ namespace std {
62
  error_condition make_error_condition(io_errc e) noexcept;
63
  const error_category& iostream_category() noexcept;
64
  }
65
  ```
66
 
67
- ### Types <a id="stream.types">[[stream.types]]</a>
68
-
69
- ``` cpp
70
- using streamoff = implementation-defined;
71
- ```
72
-
73
- The type `streamoff` is a synonym for one of the signed basic integral
74
- types of sufficient size to represent the maximum possible file size for
75
- the operating system.[^4]
76
-
77
- ``` cpp
78
- using streamsize = implementation-defined;
79
- ```
80
-
81
- The type `streamsize` is a synonym for one of the signed basic integral
82
- types. It is used to represent the number of characters transferred in
83
- an I/O operation, or the size of I/O buffers.[^5]
84
-
85
  ### Class `ios_base` <a id="ios.base">[[ios.base]]</a>
86
 
 
 
87
  ``` cpp
88
  namespace std {
89
  class ios_base {
90
  public:
91
  class failure; // see below
@@ -122,10 +106,11 @@ namespace std {
122
  using openmode = T3;
123
  static constexpr openmode app = unspecified;
124
  static constexpr openmode ate = unspecified;
125
  static constexpr openmode binary = unspecified;
126
  static constexpr openmode in = unspecified;
 
127
  static constexpr openmode out = unspecified;
128
  static constexpr openmode trunc = unspecified;
129
 
130
  // [ios.seekdir], seekdir
131
  using seekdir = T4;
@@ -335,15 +320,16 @@ The type `openmode` is a bitmask type [[bitmask.types]]. It contains the
335
  elements indicated in [[ios.openmode]].
336
 
337
  **Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
338
 
339
  | Element | Effect(s) if set |
340
- | -------- | ----------------------------------------------------------------- |
341
  | `app` | seek to end before each write |
342
  | `ate` | open and seek to end immediately after opening |
343
  | `binary` | perform input and output in binary mode (as opposed to text mode) |
344
  | `in` | open for input |
 
345
  | `out` | open for output |
346
  | `trunc` | truncate an existing stream when opening |
347
 
348
 
349
  ##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
@@ -372,10 +358,11 @@ namespace std {
372
  public:
373
  Init();
374
  Init(const Init&) = default;
375
  ~Init();
376
  Init& operator=(const Init&) = default;
 
377
  private:
378
  static int init_cnt; // exposition only
379
  };
380
  }
381
  ```
@@ -501,22 +488,22 @@ and output operations.
501
 
502
  ``` cpp
503
  static bool sync_with_stdio(bool sync = true);
504
  ```
505
 
506
- *Returns:* `true` if the previous state of the standard iostream
507
- objects [[iostream.objects]] was synchronized and otherwise returns
508
- `false`. The first time it is called, the function returns `true`.
509
-
510
  *Effects:* If any input or output operation has occurred using the
511
  standard streams prior to the call, the effect is
512
  *implementation-defined*. Otherwise, called with a `false` argument, it
513
  allows the standard streams to operate independently of the standard C
514
  streams.
515
 
516
- When a standard iostream object `str` is *synchronized* with a standard
517
- stdio stream `f`, the effect of inserting a character `c` by
 
 
 
 
518
 
519
  ``` cpp
520
  fputc(f, c);
521
  ```
522
 
@@ -550,11 +537,11 @@ is the same as the effect of
550
 
551
  ``` cpp
552
  str.rdbuf()->sputbackc(c);
553
  ```
554
 
555
- for any sequence of characters.[^6]
556
 
557
  #### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
558
 
559
  ``` cpp
560
  static int xalloc();
@@ -574,17 +561,20 @@ long& iword(int idx);
574
  *Effects:* If `iarray` is a null pointer, allocates an array of `long`
575
  of unspecified size and stores a pointer to its first element in
576
  `iarray`. The function then extends the array pointed at by `iarray` as
577
  necessary to include the element `iarray[idx]`. Each newly allocated
578
  element of the array is initialized to zero. The reference returned is
579
- invalid after any other operations on the object.[^7] However, the value
580
- of the storage referred to is retained, so that until the next call to
581
- `copyfmt`, calling `iword` with the same index yields another reference
582
- to the same value. If the function fails[^8] and `*this` is a base class
583
- subobject of a `basic_ios<>` object or subobject, the effect is
584
- equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
585
- object (which may throw `failure`).
 
 
 
586
 
587
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
588
  initialized to 0.
589
 
590
  ``` cpp
@@ -596,17 +586,19 @@ void*& pword(int idx);
596
  *Effects:* If `parray` is a null pointer, allocates an array of pointers
597
  to `void` of unspecified size and stores a pointer to its first element
598
  in `parray`. The function then extends the array pointed at by `parray`
599
  as necessary to include the element `parray[idx]`. Each newly allocated
600
  element of the array is initialized to a null pointer. The reference
601
- returned is invalid after any other operations on the object. However,
602
  the value of the storage referred to is retained, so that until the next
603
  call to `copyfmt`, calling `pword` with the same index yields another
604
- reference to the same value. If the function fails[^9] and `*this` is a
605
- base class subobject of a `basic_ios<>` object or subobject, the effect
606
- is equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
607
- object (which may throw `failure`).
 
 
608
 
609
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
610
  initialized to 0.
611
 
612
  *Remarks:* After a subsequent call to `pword(int)` for the same object,
@@ -646,22 +638,23 @@ destroyed, whichever comes first; otherwise the behavior is undefined.
646
  ```
647
 
648
  *Effects:* Calls each registered callback pair `(fn, idx)`
649
  [[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
650
  that any `ios_base` member function called from within `fn` has
651
- well-defined results.
652
 
653
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
654
 
655
  ``` cpp
656
  namespace std {
657
  template<class stateT> class fpos {
658
  public:
659
  // [fpos.members], members
660
  stateT state() const;
661
  void state(stateT);
662
- private;
 
663
  stateT st; // exposition only
664
  };
665
  }
666
  ```
667
 
@@ -688,25 +681,25 @@ object whose type is equal to the template parameter `stateT`. Type
688
  [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
689
  [[cpp17.copyassignable]]), and *Cpp17Destructible* (
690
  [[cpp17.destructible]]) requirements. If
691
  `is_trivially_copy_constructible_v<stateT>` is `true`, then
692
  `fpos<stateT>` has a trivial copy constructor. If
693
- `is_trivially_copy_assignable<stateT>` is `true`, then `fpos<stateT>`
694
  has a trivial copy assignment operator. If
695
  `is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
696
  a trivial destructor. All specializations of `fpos` meet the
697
  *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
698
  *Cpp17CopyAssignable*, *Cpp17Destructible*, and
699
  *Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
700
  In addition, the expressions shown in [[fpos.operations]] are valid and
701
  have the indicated semantics. In that table,
702
 
703
- - `P` refers to an instance of `fpos`,
704
  - `p` and `q` refer to values of type `P` or `const P`,
705
  - `pl` and `ql` refer to modifiable lvalues of type `P`,
706
  - `O` refers to type `streamoff`, and
707
- - `o` refers to a value of type `streamoff` or `const streamoff`.
708
 
709
  Stream operations that return a value of type `traits::pos_type` return
710
  `P(O(-1))` as an invalid value to signal an error. If this value is used
711
  as an argument to any `istream`, `ostream`, or `streambuf` member that
712
  accepts a value of type `traits::pos_type` then the behavior of that
@@ -770,11 +763,10 @@ namespace std {
770
  void init(basic_streambuf<charT, traits>* sb);
771
  void move(basic_ios& rhs);
772
  void move(basic_ios&& rhs);
773
  void swap(basic_ios& rhs) noexcept;
774
  void set_rdbuf(basic_streambuf<charT, traits>* sb);
775
-
776
  };
777
  }
778
  ```
779
 
780
  #### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
@@ -910,11 +902,11 @@ member objects of `rhs` as follows:
910
  `(*fn)(erase_event, *this, idx)`;
911
  - then, assigns to the member objects of `*this` the corresponding
912
  member objects of `rhs`, except that
913
  - `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
914
  - the contents of arrays pointed at by `pword` and `iword` are copied,
915
- not the pointers themselves;[^10] and
916
  - if any newly stored pointer values in `*this` point at objects
917
  stored outside the object `rhs` and those objects are destroyed when
918
  `rhs` is destroyed, the newly stored pointer values are altered to
919
  point at newly constructed copies of the objects;
920
  - then, calls each callback pair that was copied from `rhs` as
@@ -999,19 +991,19 @@ iostate rdstate() const;
999
 
1000
  ``` cpp
1001
  void clear(iostate state = goodbit);
1002
  ```
1003
 
1004
- *Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
1005
- `rdstate() == (state | ios_base::badbit)`.
1006
-
1007
  *Effects:* If
1008
  `((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
1009
  Otherwise, the function throws an object of class `ios_base::failure`
1010
  [[ios.failure]], constructed with *implementation-defined* argument
1011
  values.
1012
 
 
 
 
1013
  ``` cpp
1014
  void setstate(iostate state);
1015
  ```
1016
 
1017
  *Effects:* Calls `clear(rdstate() | state)` (which may throw
@@ -1031,11 +1023,11 @@ bool eof() const;
1031
 
1032
  ``` cpp
1033
  bool fail() const;
1034
  ```
1035
 
1036
- *Returns:* `true` if `failbit` or `badbit` is set in `rdstate()`.[^11]
1037
 
1038
  ``` cpp
1039
  bool bad() const;
1040
  ```
1041
 
@@ -1050,14 +1042,14 @@ exceptions to be thrown.
1050
 
1051
  ``` cpp
1052
  void exceptions(iostate except);
1053
  ```
1054
 
1055
- *Ensures:* `except == exceptions()`.
1056
-
1057
  *Effects:* Calls `clear(rdstate())`.
1058
 
 
 
1059
  ### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
1060
 
1061
  #### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
1062
 
1063
  Each function specified in this subclause is a designated addressable
@@ -1213,11 +1205,11 @@ function [[namespace.std]].
1213
  ios_base& dec(ios_base& str);
1214
  ```
1215
 
1216
  *Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
1217
 
1218
- *Returns:* `str`[^12].
1219
 
1220
  ``` cpp
1221
  ios_base& hex(ios_base& str);
1222
  ```
1223
 
@@ -1261,14 +1253,13 @@ ios_base& hexfloat(ios_base& str);
1261
  *Effects:* Calls
1262
  `str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
1263
 
1264
  *Returns:* `str`.
1265
 
1266
- [*Note 1*: The more obvious use of `ios_base::hex` to specify
1267
- hexadecimal floating-point format would change the meaning of existing
1268
- well-defined programs. C++03 gives no meaning to the combination of
1269
- `fixed` and `scientific`. — *end note*]
1270
 
1271
  ``` cpp
1272
  ios_base& defaultfloat(ios_base& str);
1273
  ```
1274
 
 
62
  error_condition make_error_condition(io_errc e) noexcept;
63
  const error_category& iostream_category() noexcept;
64
  }
65
  ```
66
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
67
  ### Class `ios_base` <a id="ios.base">[[ios.base]]</a>
68
 
69
+ #### General <a id="ios.base.general">[[ios.base.general]]</a>
70
+
71
  ``` cpp
72
  namespace std {
73
  class ios_base {
74
  public:
75
  class failure; // see below
 
106
  using openmode = T3;
107
  static constexpr openmode app = unspecified;
108
  static constexpr openmode ate = unspecified;
109
  static constexpr openmode binary = unspecified;
110
  static constexpr openmode in = unspecified;
111
+ static constexpr openmode noreplace = unspecified;
112
  static constexpr openmode out = unspecified;
113
  static constexpr openmode trunc = unspecified;
114
 
115
  // [ios.seekdir], seekdir
116
  using seekdir = T4;
 
320
  elements indicated in [[ios.openmode]].
321
 
322
  **Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
323
 
324
  | Element | Effect(s) if set |
325
+ | ----------- | ----------------------------------------------------------------- |
326
  | `app` | seek to end before each write |
327
  | `ate` | open and seek to end immediately after opening |
328
  | `binary` | perform input and output in binary mode (as opposed to text mode) |
329
  | `in` | open for input |
330
+ | `noreplace` | open in exclusive mode |
331
  | `out` | open for output |
332
  | `trunc` | truncate an existing stream when opening |
333
 
334
 
335
  ##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
 
358
  public:
359
  Init();
360
  Init(const Init&) = default;
361
  ~Init();
362
  Init& operator=(const Init&) = default;
363
+
364
  private:
365
  static int init_cnt; // exposition only
366
  };
367
  }
368
  ```
 
488
 
489
  ``` cpp
490
  static bool sync_with_stdio(bool sync = true);
491
  ```
492
 
 
 
 
 
493
  *Effects:* If any input or output operation has occurred using the
494
  standard streams prior to the call, the effect is
495
  *implementation-defined*. Otherwise, called with a `false` argument, it
496
  allows the standard streams to operate independently of the standard C
497
  streams.
498
 
499
+ *Returns:* `true` if the previous state of the standard iostream
500
+ objects [[iostream.objects]] was synchronized and otherwise returns
501
+ `false`. The first time it is called, the function returns `true`.
502
+
503
+ *Remarks:* When a standard iostream object `str` is *synchronized* with
504
+ a standard stdio stream `f`, the effect of inserting a character `c` by
505
 
506
  ``` cpp
507
  fputc(f, c);
508
  ```
509
 
 
537
 
538
  ``` cpp
539
  str.rdbuf()->sputbackc(c);
540
  ```
541
 
542
+ for any sequence of characters.[^5]
543
 
544
  #### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
545
 
546
  ``` cpp
547
  static int xalloc();
 
561
  *Effects:* If `iarray` is a null pointer, allocates an array of `long`
562
  of unspecified size and stores a pointer to its first element in
563
  `iarray`. The function then extends the array pointed at by `iarray` as
564
  necessary to include the element `iarray[idx]`. Each newly allocated
565
  element of the array is initialized to zero. The reference returned is
566
+ invalid after any other operation on the object.[^6]
567
+
568
+ However, the value of the storage referred to is retained, so that until
569
+ the next call to `copyfmt`, calling `iword` with the same index yields
570
+ another reference to the same value. If the function fails[^7]
571
+
572
+ and `*this` is a base class subobject of a `basic_ios<>` object or
573
+ subobject, the effect is equivalent to calling
574
+ `basic_ios<>::setstate(badbit)` on the derived object (which may throw
575
+ `failure`).
576
 
577
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
578
  initialized to 0.
579
 
580
  ``` cpp
 
586
  *Effects:* If `parray` is a null pointer, allocates an array of pointers
587
  to `void` of unspecified size and stores a pointer to its first element
588
  in `parray`. The function then extends the array pointed at by `parray`
589
  as necessary to include the element `parray[idx]`. Each newly allocated
590
  element of the array is initialized to a null pointer. The reference
591
+ returned is invalid after any other operation on the object. However,
592
  the value of the storage referred to is retained, so that until the next
593
  call to `copyfmt`, calling `pword` with the same index yields another
594
+ reference to the same value. If the function fails[^8]
595
+
596
+ and `*this` is a base class subobject of a `basic_ios<>` object or
597
+ subobject, the effect is equivalent to calling
598
+ `basic_ios<>::setstate(badbit)` on the derived object (which may throw
599
+ `failure`).
600
 
601
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
602
  initialized to 0.
603
 
604
  *Remarks:* After a subsequent call to `pword(int)` for the same object,
 
638
  ```
639
 
640
  *Effects:* Calls each registered callback pair `(fn, idx)`
641
  [[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
642
  that any `ios_base` member function called from within `fn` has
643
+ well-defined results. Then, any memory obtained is deallocated.
644
 
645
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
646
 
647
  ``` cpp
648
  namespace std {
649
  template<class stateT> class fpos {
650
  public:
651
  // [fpos.members], members
652
  stateT state() const;
653
  void state(stateT);
654
+
655
+ private:
656
  stateT st; // exposition only
657
  };
658
  }
659
  ```
660
 
 
681
  [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
682
  [[cpp17.copyassignable]]), and *Cpp17Destructible* (
683
  [[cpp17.destructible]]) requirements. If
684
  `is_trivially_copy_constructible_v<stateT>` is `true`, then
685
  `fpos<stateT>` has a trivial copy constructor. If
686
+ `is_trivially_copy_assignable_v<stateT>` is `true`, then `fpos<stateT>`
687
  has a trivial copy assignment operator. If
688
  `is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
689
  a trivial destructor. All specializations of `fpos` meet the
690
  *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
691
  *Cpp17CopyAssignable*, *Cpp17Destructible*, and
692
  *Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
693
  In addition, the expressions shown in [[fpos.operations]] are valid and
694
  have the indicated semantics. In that table,
695
 
696
+ - `P` refers to a specialization of `fpos`,
697
  - `p` and `q` refer to values of type `P` or `const P`,
698
  - `pl` and `ql` refer to modifiable lvalues of type `P`,
699
  - `O` refers to type `streamoff`, and
700
+ - `o` and `o2` refer to values of type `streamoff` or `const streamoff`.
701
 
702
  Stream operations that return a value of type `traits::pos_type` return
703
  `P(O(-1))` as an invalid value to signal an error. If this value is used
704
  as an argument to any `istream`, `ostream`, or `streambuf` member that
705
  accepts a value of type `traits::pos_type` then the behavior of that
 
763
  void init(basic_streambuf<charT, traits>* sb);
764
  void move(basic_ios& rhs);
765
  void move(basic_ios&& rhs);
766
  void swap(basic_ios& rhs) noexcept;
767
  void set_rdbuf(basic_streambuf<charT, traits>* sb);
 
768
  };
769
  }
770
  ```
771
 
772
  #### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
 
902
  `(*fn)(erase_event, *this, idx)`;
903
  - then, assigns to the member objects of `*this` the corresponding
904
  member objects of `rhs`, except that
905
  - `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
906
  - the contents of arrays pointed at by `pword` and `iword` are copied,
907
+ not the pointers themselves;[^9] and
908
  - if any newly stored pointer values in `*this` point at objects
909
  stored outside the object `rhs` and those objects are destroyed when
910
  `rhs` is destroyed, the newly stored pointer values are altered to
911
  point at newly constructed copies of the objects;
912
  - then, calls each callback pair that was copied from `rhs` as
 
991
 
992
  ``` cpp
993
  void clear(iostate state = goodbit);
994
  ```
995
 
 
 
 
996
  *Effects:* If
997
  `((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
998
  Otherwise, the function throws an object of class `ios_base::failure`
999
  [[ios.failure]], constructed with *implementation-defined* argument
1000
  values.
1001
 
1002
+ *Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
1003
+ `rdstate() == (state | ios_base::badbit)`.
1004
+
1005
  ``` cpp
1006
  void setstate(iostate state);
1007
  ```
1008
 
1009
  *Effects:* Calls `clear(rdstate() | state)` (which may throw
 
1023
 
1024
  ``` cpp
1025
  bool fail() const;
1026
  ```
1027
 
1028
+ *Returns:* `true` if `failbit` or `badbit` is set in `rdstate()`.[^10]
1029
 
1030
  ``` cpp
1031
  bool bad() const;
1032
  ```
1033
 
 
1042
 
1043
  ``` cpp
1044
  void exceptions(iostate except);
1045
  ```
1046
 
 
 
1047
  *Effects:* Calls `clear(rdstate())`.
1048
 
1049
+ *Ensures:* `except == exceptions()`.
1050
+
1051
  ### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
1052
 
1053
  #### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
1054
 
1055
  Each function specified in this subclause is a designated addressable
 
1205
  ios_base& dec(ios_base& str);
1206
  ```
1207
 
1208
  *Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
1209
 
1210
+ *Returns:* `str`.[^11]
1211
 
1212
  ``` cpp
1213
  ios_base& hex(ios_base& str);
1214
  ```
1215
 
 
1253
  *Effects:* Calls
1254
  `str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
1255
 
1256
  *Returns:* `str`.
1257
 
1258
+ [*Note 1*: `ios_base::hex` cannot be used to specify a hexadecimal
1259
+ floating-point format, because it is not part of `ios_base::floatfield`
1260
+ ([[ios.fmtflags.const]]). — *end note*]
 
1261
 
1262
  ``` cpp
1263
  ios_base& defaultfloat(ios_base& str);
1264
  ```
1265