From Jason Turner

[input.output]

Large diff (174.4 KB) - rendering may be slow on some devices

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpy4juhgm7/{from.md → to.md} +950 -507
tmp/tmpy4juhgm7/{from.md → to.md} RENAMED
@@ -71,13 +71,13 @@ as noted explicitly below, their behavior when `traits::pos_type` and
71
  `pos_type` denotes `fpos<mbstate_t>`, and `off_type` denotes
72
  `streamoff`. — *end note*]
73
 
74
  In the classes of [[input.output]], a template parameter with name
75
  `charT` represents a member of the set of types containing `char`,
76
- `wchar_t`, and any other *implementation-defined* character types that
77
- meet the requirements for a character on which any of the iostream
78
- components can be instantiated.
79
 
80
  ### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
81
 
82
  Concurrent access to a stream object
83
  [[string.streams]], [[file.streams]], stream buffer object
@@ -117,21 +117,17 @@ namespace std {
117
  template<class charT, class traits = char_traits<charT>>
118
  class basic_ostream;
119
  template<class charT, class traits = char_traits<charT>>
120
  class basic_iostream;
121
 
122
- template<class charT, class traits = char_traits<charT>,
123
- class Allocator = allocator<charT>>
124
  class basic_stringbuf;
125
- template<class charT, class traits = char_traits<charT>,
126
- class Allocator = allocator<charT>>
127
  class basic_istringstream;
128
- template<class charT, class traits = char_traits<charT>,
129
- class Allocator = allocator<charT>>
130
  class basic_ostringstream;
131
- template<class charT, class traits = char_traits<charT>,
132
- class Allocator = allocator<charT>>
133
  class basic_stringstream;
134
 
135
  template<class charT, class traits = char_traits<charT>>
136
  class basic_spanbuf;
137
  template<class charT, class traits = char_traits<charT>>
@@ -148,15 +144,13 @@ namespace std {
148
  template<class charT, class traits = char_traits<charT>>
149
  class basic_ofstream;
150
  template<class charT, class traits = char_traits<charT>>
151
  class basic_fstream;
152
 
153
- template<class charT, class traits = char_traits<charT>,
154
- class Allocator = allocator<charT>>
155
  class basic_syncbuf;
156
- template<class charT, class traits = char_traits<charT>,
157
- class Allocator = allocator<charT>>
158
  class basic_osyncstream;
159
 
160
  template<class charT, class traits = char_traits<charT>>
161
  class istreambuf_iterator;
162
  template<class charT, class traits = char_traits<charT>>
@@ -294,11 +288,14 @@ namespace std {
294
  In this Clause, the type name `FILE` refers to the type `FILE` declared
295
  in `<cstdio>`.
296
 
297
  The header `<iostream>` declares objects that associate objects with the
298
  standard C streams provided for by the functions declared in `<cstdio>`,
299
- and includes all the headers necessary to use these objects.
 
 
 
300
 
301
  The objects are constructed and the associations are established at some
302
  time prior to or during the first time an object of class
303
  `ios_base::Init` is constructed, and in any case before the body of
304
  `main` [[basic.start.main]] begins execution. The objects are not
@@ -330,11 +327,11 @@ iostream object’s formatted and unformatted input [[istream]] and output
330
  not result in a data race [[intro.multithread]].
331
 
332
  [*Note 2*: Unsynchronized concurrent use of these objects and streams
333
  by multiple threads can result in interleaved characters. — *end note*]
334
 
335
- See also: ISO C 7.21.2
336
 
337
  ### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
338
 
339
  ``` cpp
340
  istream cin;
@@ -416,15 +413,19 @@ the object `stderr`, declared in `<cstdio>`.
416
 
417
  ``` cpp
418
  #include <iosfwd> // see [iosfwd.syn]
419
 
420
  namespace std {
 
421
  using streamoff = implementation-defined;
422
  using streamsize = implementation-defined;
 
423
  template<class stateT> class fpos;
424
 
 
425
  class ios_base;
 
426
  template<class charT, class traits = char_traits<charT>>
427
  class basic_ios;
428
 
429
  // [std.ios.manip], manipulators
430
  ios_base& boolalpha (ios_base& str);
@@ -626,11 +627,11 @@ namespace std {
626
  An implementation is permitted to define `ios_base::failure` as a
627
  synonym for a class with equivalent functionality to class
628
  `ios_base::failure` shown in this subclause.
629
 
630
  [*Note 1*: When `ios_base::failure` is a synonym for another type, that
631
- type is required to provide a nested type `failure` to emulate the
632
  injected-class-name. — *end note*]
633
 
634
  The class `failure` defines the base class for the types of all objects
635
  thrown as exceptions, by functions in the iostreams library, to report
636
  errors detected during stream buffer operations.
@@ -770,27 +771,19 @@ namespace std {
770
  public:
771
  Init();
772
  Init(const Init&) = default;
773
  ~Init();
774
  Init& operator=(const Init&) = default;
775
-
776
- private:
777
- static int init_cnt; // exposition only
778
  };
779
  }
780
  ```
781
 
782
  The class `Init` describes an object whose construction ensures the
783
  construction of the eight objects declared in `<iostream>`
784
  [[iostream.objects]] that associate file stream buffers with the
785
  standard C streams provided for by the functions declared in `<cstdio>`.
786
 
787
- For the sake of exposition, the maintained data is presented here as:
788
-
789
- - `static int init_cnt`, counts the number of constructor and destructor
790
- calls for class `Init`, initialized to zero.
791
-
792
  ``` cpp
793
  Init();
794
  ```
795
 
796
  *Effects:* Constructs and initializes the objects `cin`, `cout`, `cerr`,
@@ -957,25 +950,25 @@ for any sequence of characters.[^5]
957
 
958
  ``` cpp
959
  static int xalloc();
960
  ```
961
 
962
- *Returns:* `index` `++`.
963
 
964
  *Remarks:* Concurrent access to this function by multiple threads does
965
  not result in a data race [[intro.multithread]].
966
 
967
  ``` cpp
968
  long& iword(int idx);
969
  ```
970
 
971
  *Preconditions:* `idx` is a value obtained by a call to `xalloc`.
972
 
973
- *Effects:* If `iarray` is a null pointer, allocates an array of `long`
974
  of unspecified size and stores a pointer to its first element in
975
- `iarray`. The function then extends the array pointed at by `iarray` as
976
- necessary to include the element `iarray[idx]`. Each newly allocated
977
  element of the array is initialized to zero. The reference returned is
978
  invalid after any other operation on the object.[^6]
979
 
980
  However, the value of the storage referred to is retained, so that until
981
  the next call to `copyfmt`, calling `iword` with the same index yields
@@ -984,28 +977,28 @@ another reference to the same value. If the function fails[^7]
984
  and `*this` is a base class subobject of a `basic_ios<>` object or
985
  subobject, the effect is equivalent to calling
986
  `basic_ios<>::setstate(badbit)` on the derived object (which may throw
987
  `failure`).
988
 
989
- *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
990
  initialized to 0.
991
 
992
  ``` cpp
993
  void*& pword(int idx);
994
  ```
995
 
996
  *Preconditions:* `idx` is a value obtained by a call to `xalloc`.
997
 
998
- *Effects:* If `parray` is a null pointer, allocates an array of pointers
999
  to `void` of unspecified size and stores a pointer to its first element
1000
- in `parray`. The function then extends the array pointed at by `parray`
1001
- as necessary to include the element `parray[idx]`. Each newly allocated
1002
- element of the array is initialized to a null pointer. The reference
1003
- returned is invalid after any other operation on the object. However,
1004
- the value of the storage referred to is retained, so that until the next
1005
- call to `copyfmt`, calling `pword` with the same index yields another
1006
- reference to the same value. If the function fails[^8]
1007
 
1008
  and `*this` is a base class subobject of a `basic_ios<>` object or
1009
  subobject, the effect is equivalent to calling
1010
  `basic_ios<>::setstate(badbit)` on the derived object (which may throw
1011
  `failure`).
@@ -1054,10 +1047,12 @@ destroyed, whichever comes first; otherwise the behavior is undefined.
1054
  that any `ios_base` member function called from within `fn` has
1055
  well-defined results. Then, any memory obtained is deallocated.
1056
 
1057
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
1058
 
 
 
1059
  ``` cpp
1060
  namespace std {
1061
  template<class stateT> class fpos {
1062
  public:
1063
  // [fpos.members], members
@@ -1074,17 +1069,17 @@ namespace std {
1074
 
1075
  ``` cpp
1076
  void state(stateT s);
1077
  ```
1078
 
1079
- *Effects:* Assigns `s` to `st`.
1080
 
1081
  ``` cpp
1082
  stateT state() const;
1083
  ```
1084
 
1085
- *Returns:* Current value of `st`.
1086
 
1087
  #### Requirements <a id="fpos.operations">[[fpos.operations]]</a>
1088
 
1089
  An `fpos` type specifies file position information. It holds a state
1090
  object whose type is equal to the template parameter `stateT`. Type
@@ -1125,13 +1120,13 @@ function is undefined.
1125
  namespace std {
1126
  template<class charT, class traits = char_traits<charT>>
1127
  class basic_ios : public ios_base {
1128
  public:
1129
  using char_type = charT;
1130
- using int_type = typename traits::int_type;
1131
- using pos_type = typename traits::pos_type;
1132
- using off_type = typename traits::off_type;
1133
  using traits_type = traits;
1134
 
1135
  // [iostate.flags], flags functions
1136
  explicit operator bool() const;
1137
  bool operator!() const;
@@ -1277,17 +1272,17 @@ locale imbue(const locale& loc);
1277
 
1278
  ``` cpp
1279
  char narrow(char_type c, char dfault) const;
1280
  ```
1281
 
1282
- *Returns:* `use_facet<ctype<char_type>>(getloc()).narrow(c, dfault)`
1283
 
1284
  ``` cpp
1285
  char_type widen(char c) const;
1286
  ```
1287
 
1288
- *Returns:* `use_facet<ctype<char_type>>(getloc()).widen(c)`
1289
 
1290
  ``` cpp
1291
  char_type fill() const;
1292
  ```
1293
 
@@ -1423,11 +1418,11 @@ void setstate(iostate state);
1423
 
1424
  ``` cpp
1425
  bool good() const;
1426
  ```
1427
 
1428
- *Returns:* `rdstate() == 0`
1429
 
1430
  ``` cpp
1431
  bool eof() const;
1432
  ```
1433
 
@@ -1709,10 +1704,11 @@ object’s `name` virtual function shall return a pointer to the string
1709
 
1710
  ### Header `<streambuf>` synopsis <a id="streambuf.syn">[[streambuf.syn]]</a>
1711
 
1712
  ``` cpp
1713
  namespace std {
 
1714
  template<class charT, class traits = char_traits<charT>>
1715
  class basic_streambuf;
1716
  using streambuf = basic_streambuf<char>;
1717
  using wstreambuf = basic_streambuf<wchar_t>;
1718
  }
@@ -1780,13 +1776,13 @@ above:
1780
  namespace std {
1781
  template<class charT, class traits = char_traits<charT>>
1782
  class basic_streambuf {
1783
  public:
1784
  using char_type = charT;
1785
- using int_type = typename traits::int_type;
1786
- using pos_type = typename traits::pos_type;
1787
- using off_type = typename traits::off_type;
1788
  using traits_type = traits;
1789
 
1790
  virtual ~basic_streambuf();
1791
 
1792
  // [streambuf.locales], locales
@@ -1868,13 +1864,13 @@ namespace std {
1868
  virtual int_type overflow(int_type c = traits::eof());
1869
  };
1870
  }
1871
  ```
1872
 
1873
- The class template `basic_streambuf` serves as an abstract base class
1874
- for deriving various *stream buffers* whose objects each control two
1875
- *character sequences*:
1876
 
1877
  - a character *input sequence*;
1878
  - a character *output sequence*.
1879
 
1880
  #### Constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
@@ -2097,10 +2093,13 @@ void gbump(int n);
2097
 
2098
  ``` cpp
2099
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
2100
  ```
2101
 
 
 
 
2102
  *Ensures:* `gbeg == eback()`, `gnext == gptr()`, and `gend == egptr()`
2103
  are all `true`.
2104
 
2105
  ##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
2106
 
@@ -2130,10 +2129,12 @@ void pbump(int n);
2130
 
2131
  ``` cpp
2132
  void setp(char_type* pbeg, char_type* pend);
2133
  ```
2134
 
 
 
2135
  *Ensures:* `pbeg == pbase()`, `pbeg == pptr()`, and `pend == epptr()`
2136
  are all `true`.
2137
 
2138
  #### Virtual functions <a id="streambuf.virtuals">[[streambuf.virtuals]]</a>
2139
 
@@ -2389,40 +2390,46 @@ accommodate the argument character sequence.
2389
 
2390
  ### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
2391
 
2392
  ``` cpp
2393
  namespace std {
 
2394
  template<class charT, class traits = char_traits<charT>>
2395
  class basic_istream;
2396
 
2397
  using istream = basic_istream<char>;
2398
  using wistream = basic_istream<wchar_t>;
2399
 
 
2400
  template<class charT, class traits = char_traits<charT>>
2401
  class basic_iostream;
2402
 
2403
  using iostream = basic_iostream<char>;
2404
  using wiostream = basic_iostream<wchar_t>;
2405
 
 
2406
  template<class charT, class traits>
2407
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
2408
 
 
2409
  template<class Istream, class T>
2410
  Istream&& operator>>(Istream&& is, T&& x);
2411
  }
2412
  ```
2413
 
2414
  ### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
2415
 
2416
  ``` cpp
2417
  namespace std {
 
2418
  template<class charT, class traits = char_traits<charT>>
2419
  class basic_ostream;
2420
 
2421
  using ostream = basic_ostream<char>;
2422
  using wostream = basic_ostream<wchar_t>;
2423
 
 
2424
  template<class charT, class traits>
2425
  basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
2426
  template<class charT, class traits>
2427
  basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
2428
  template<class charT, class traits>
@@ -2433,39 +2440,45 @@ namespace std {
2433
  template<class charT, class traits>
2434
  basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
2435
  template<class charT, class traits>
2436
  basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
2437
 
 
2438
  template<class Ostream, class T>
2439
  Ostream&& operator<<(Ostream&& os, const T& x);
2440
 
2441
  // [ostream.formatted.print], print functions
2442
  template<class... Args>
2443
  void print(ostream& os, format_string<Args...> fmt, Args&&... args);
2444
  template<class... Args>
2445
  void println(ostream& os, format_string<Args...> fmt, Args&&... args);
 
2446
 
2447
  void vprint_unicode(ostream& os, string_view fmt, format_args args);
2448
  void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
2449
  }
2450
  ```
2451
 
2452
  ### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
2453
 
2454
  ``` cpp
2455
  namespace std {
 
2456
  unspecified resetiosflags(ios_base::fmtflags mask);
2457
  unspecified setiosflags (ios_base::fmtflags mask);
2458
  unspecified setbase(int base);
2459
  template<class charT> unspecified setfill(charT c);
2460
  unspecified setprecision(int n);
2461
  unspecified setw(int n);
 
 
2462
  template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
2463
  template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
2464
  template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
2465
  template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
2466
 
 
2467
  template<class charT>
2468
  unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
2469
 
2470
  template<class charT, class traits, class Allocator>
2471
  unspecified quoted(const basic_string<charT, traits, Allocator>& s,
@@ -2491,18 +2504,22 @@ namespace std {
2491
  template<class... Args>
2492
  void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
2493
 
2494
  template<class... Args>
2495
  void println(format_string<Args...> fmt, Args&&... args);
 
2496
  template<class... Args>
2497
  void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
 
2498
 
2499
  void vprint_unicode(string_view fmt, format_args args);
2500
  void vprint_unicode(FILE* stream, string_view fmt, format_args args);
 
2501
 
2502
  void vprint_nonunicode(string_view fmt, format_args args);
2503
  void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
 
2504
  }
2505
  ```
2506
 
2507
  ### Input streams <a id="input.streams">[[input.streams]]</a>
2508
 
@@ -2526,13 +2543,13 @@ namespace std {
2526
  template<class charT, class traits = char_traits<charT>>
2527
  class basic_istream : virtual public basic_ios<charT, traits> {
2528
  public:
2529
  // types (inherited from basic_ios[ios])
2530
  using char_type = charT;
2531
- using int_type = typename traits::int_type;
2532
- using pos_type = typename traits::pos_type;
2533
- using off_type = typename traits::off_type;
2534
  using traits_type = traits;
2535
 
2536
  // [istream.cons], constructor/destructor
2537
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2538
  virtual ~basic_istream();
@@ -2573,10 +2590,11 @@ namespace std {
2573
 
2574
  basic_istream& getline(char_type* s, streamsize n);
2575
  basic_istream& getline(char_type* s, streamsize n, char_type delim);
2576
 
2577
  basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
 
2578
  int_type peek();
2579
  basic_istream& read (char_type* s, streamsize n);
2580
  streamsize readsome(char_type* s, streamsize n);
2581
 
2582
  basic_istream& putback(char_type c);
@@ -2654,11 +2672,11 @@ virtual ~basic_istream();
2654
 
2655
  ``` cpp
2656
  basic_istream& operator=(basic_istream&& rhs);
2657
  ```
2658
 
2659
- *Effects:* Equivalent to: `swap(rhs)`.
2660
 
2661
  *Returns:* `*this`.
2662
 
2663
  ``` cpp
2664
  void swap(basic_istream& rhs);
@@ -2726,12 +2744,12 @@ const ctype<charT>& ctype = use_facet<ctype<charT>>(is.getloc());
2726
  if (ctype.is(ctype.space, c) != 0)
2727
  // c is a whitespace character.
2728
  ```
2729
 
2730
  If, after any preparation is completed, `is.good()` is `true`,
2731
- `ok_ != false` otherwise, `ok_ == false`. During preparation, the
2732
- constructor may call `setstate(failbit)` (which may throw
2733
  `ios_base::failure` [[iostate.flags]]).[^19]
2734
 
2735
  ``` cpp
2736
  ~sentry();
2737
  ```
@@ -2740,11 +2758,11 @@ constructor may call `setstate(failbit)` (which may throw
2740
 
2741
  ``` cpp
2742
  explicit operator bool() const;
2743
  ```
2744
 
2745
- *Returns:* `ok_`.
2746
 
2747
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2748
 
2749
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
2750
 
@@ -3178,11 +3196,11 @@ int main() {
3178
 
3179
  ``` cpp
3180
  basic_istream& getline(char_type* s, streamsize n);
3181
  ```
3182
 
3183
- *Returns:* `getline(s, n, widen(’\n’))`
3184
 
3185
  ``` cpp
3186
  basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
3187
  ```
3188
 
@@ -3190,11 +3208,11 @@ basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
3190
  above). After constructing a `sentry` object, extracts characters and
3191
  discards them. Characters are extracted until any of the following
3192
  occurs:
3193
 
3194
  - `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
3195
- characters have been extracted so far
3196
  - end-of-file occurs on the input sequence (in which case the function
3197
  calls `setstate(eofbit)`, which may throw `ios_base::failure`
3198
  [[iostate.flags]]);
3199
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
3200
  available input character `c` (in which case `c` is extracted).
@@ -3202,10 +3220,19 @@ occurs:
3202
  [*Note 1*: The last condition will never occur if
3203
  `traits::eq_int_type(delim, traits::eof())`. — *end note*]
3204
 
3205
  *Returns:* `*this`.
3206
 
 
 
 
 
 
 
 
 
 
3207
  ``` cpp
3208
  int_type peek();
3209
  ```
3210
 
3211
  *Effects:* Behaves as an unformatted input function (as described
@@ -3393,13 +3420,13 @@ namespace std {
3393
  class basic_iostream
3394
  : public basic_istream<charT, traits>,
3395
  public basic_ostream<charT, traits> {
3396
  public:
3397
  using char_type = charT;
3398
- using int_type = typename traits::int_type;
3399
- using pos_type = typename traits::pos_type;
3400
- using off_type = typename traits::off_type;
3401
  using traits_type = traits;
3402
 
3403
  // [iostream.cons], constructor
3404
  explicit basic_iostream(basic_streambuf<charT, traits>* sb);
3405
 
@@ -3454,11 +3481,11 @@ virtual ~basic_iostream();
3454
 
3455
  ``` cpp
3456
  basic_iostream& operator=(basic_iostream&& rhs);
3457
  ```
3458
 
3459
- *Effects:* Equivalent to: `swap(rhs)`.
3460
 
3461
  ``` cpp
3462
  void swap(basic_iostream& rhs);
3463
  ```
3464
 
@@ -3485,13 +3512,13 @@ namespace std {
3485
  template<class charT, class traits = char_traits<charT>>
3486
  class basic_ostream : virtual public basic_ios<charT, traits> {
3487
  public:
3488
  // types (inherited from basic_ios[ios])
3489
  using char_type = charT;
3490
- using int_type = typename traits::int_type;
3491
- using pos_type = typename traits::pos_type;
3492
- using off_type = typename traits::off_type;
3493
  using traits_type = traits;
3494
 
3495
  // [ostream.cons], constructor/destructor
3496
  explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
3497
  virtual ~basic_ostream();
@@ -3663,11 +3690,11 @@ virtual ~basic_ostream();
3663
 
3664
  ``` cpp
3665
  basic_ostream& operator=(basic_ostream&& rhs);
3666
  ```
3667
 
3668
- *Effects:* Equivalent to: `swap(rhs)`.
3669
 
3670
  *Returns:* `*this`.
3671
 
3672
  ``` cpp
3673
  void swap(basic_ostream& rhs);
@@ -3703,28 +3730,29 @@ explicit sentry(basic_ostream& os);
3703
 
3704
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
3705
  If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
3706
 
3707
  If, after any preparation is completed, `os.good()` is `true`,
3708
- `ok_ == true` otherwise, `ok_ == false`. During preparation, the
3709
  constructor may call `setstate(failbit)` (which may throw
3710
  `ios_base::failure` [[iostate.flags]]).[^30]
3711
 
3712
  ``` cpp
3713
  ~sentry();
3714
  ```
3715
 
3716
  If
3717
  `(os.flags() & ios_base::unitbuf) && !uncaught_exceptions() && os.good()`
3718
- is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1,
3719
- sets `badbit` in `os.rdstate()` without propagating an exception.
 
3720
 
3721
  ``` cpp
3722
  explicit operator bool() const;
3723
  ```
3724
 
3725
- *Effects:* Returns `ok_`.
3726
 
3727
  ##### Seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
3728
 
3729
  Each seek member function begins execution by constructing an object of
3730
  class `sentry`. It returns by destroying the `sentry` object.
@@ -3779,16 +3807,16 @@ function is `*this`.
3779
  The descriptions of the individual formatted output functions describe
3780
  how they perform output and do not mention the `sentry` object.
3781
 
3782
  If a formatted output function of a stream `os` determines padding, it
3783
  does so as follows. Given a `charT` character sequence `seq` where
3784
- `charT` is the character type of the stream, if the length of `seq` is
3785
- less than `os.width()`, then enough copies of `os.fill()` are added to
3786
- this sequence as necessary to pad to a width of `os.width()` characters.
3787
- If `(os.flags() & ios_base::adjustfield) == ios_base::left` is `true`,
3788
- the fill characters are placed after the character sequence; otherwise,
3789
- they are placed before the character sequence.
3790
 
3791
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
3792
 
3793
  ``` cpp
3794
  basic_ostream& operator<<(bool val);
@@ -3813,59 +3841,52 @@ When `val` is of type `bool`, `long`, `unsigned long`, `long long`,
3813
  `unsigned long long`, `double`, `long double`, or `const void*`, the
3814
  formatting conversion occurs as if it performed the following code
3815
  fragment:
3816
 
3817
  ``` cpp
3818
- bool failed = use_facet<
3819
- num_put<charT, ostreambuf_iterator<charT, traits>>
3820
- >(getloc()).put(*this, *this, fill(), val).failed();
3821
  ```
3822
 
3823
  When `val` is of type `short` the formatting conversion occurs as if it
3824
  performed the following code fragment:
3825
 
3826
  ``` cpp
3827
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
3828
- bool failed = use_facet<
3829
- num_put<charT, ostreambuf_iterator<charT, traits>>
3830
- >(getloc()).put(*this, *this, fill(),
3831
  baseflags == ios_base::oct || baseflags == ios_base::hex
3832
  ? static_cast<long>(static_cast<unsigned short>(val))
3833
  : static_cast<long>(val)).failed();
3834
  ```
3835
 
3836
  When `val` is of type `int` the formatting conversion occurs as if it
3837
  performed the following code fragment:
3838
 
3839
  ``` cpp
3840
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
3841
- bool failed = use_facet<
3842
- num_put<charT, ostreambuf_iterator<charT, traits>>
3843
- >(getloc()).put(*this, *this, fill(),
3844
  baseflags == ios_base::oct || baseflags == ios_base::hex
3845
  ? static_cast<long>(static_cast<unsigned int>(val))
3846
  : static_cast<long>(val)).failed();
3847
  ```
3848
 
3849
  When `val` is of type `unsigned short` or `unsigned int` the formatting
3850
  conversion occurs as if it performed the following code fragment:
3851
 
3852
  ``` cpp
3853
- bool failed = use_facet<
3854
- num_put<charT, ostreambuf_iterator<charT, traits>>
3855
- >(getloc()).put(*this, *this, fill(),
3856
- static_cast<unsigned long>(val)).failed();
3857
  ```
3858
 
3859
  When `val` is of type `float` the formatting conversion occurs as if it
3860
  performed the following code fragment:
3861
 
3862
  ``` cpp
3863
- bool failed = use_facet<
3864
- num_put<charT, ostreambuf_iterator<charT, traits>>
3865
- >(getloc()).put(*this, *this, fill(),
3866
- static_cast<double>(val)).failed();
3867
  ```
3868
 
3869
  The first argument provides an object of the `ostreambuf_iterator<>`
3870
  class which is an iterator for class `basic_ostream<>`. It bypasses
3871
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
@@ -3893,26 +3914,22 @@ basic_ostream& operator<<(extended-floating-point-type val);
3893
  *`extended-floating-point-type`* is less than or equal to that of
3894
  `double`, the formatting conversion occurs as if it performed the
3895
  following code fragment:
3896
 
3897
  ``` cpp
3898
- bool failed = use_facet<
3899
- num_put<charT, ostreambuf_iterator<charT, traits>>
3900
- >(getloc()).put(*this, *this, fill(),
3901
- static_cast<double>(val)).failed();
3902
  ```
3903
 
3904
  Otherwise, if the floating-point conversion rank of
3905
  *`extended-floating-point-type`* is less than or equal to that of
3906
  `long double`, the formatting conversion occurs as if it performed the
3907
  following code fragment:
3908
 
3909
  ``` cpp
3910
- bool failed = use_facet<
3911
- num_put<charT, ostreambuf_iterator<charT, traits>>
3912
- >(getloc()).put(*this, *this, fill(),
3913
- static_cast<long double>(val)).failed();
3914
  ```
3915
 
3916
  Otherwise, an invocation of the operator function is conditionally
3917
  supported with *implementation-defined* semantics.
3918
 
@@ -4006,15 +4023,15 @@ template<class traits>
4006
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
4007
  ```
4008
 
4009
  *Effects:* Behaves as a formatted output
4010
  function [[ostream.formatted.reqmts]] of `out`. Constructs a character
4011
- sequence `seq`. If `c` has type `char` and the character type of the
4012
- stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
4013
- `seq` consists of `c`. Determines padding for `seq` as described
4014
- in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
4015
- `os.width(0)`.
4016
 
4017
  *Returns:* `out`.
4018
 
4019
  ``` cpp
4020
  template<class charT, class traits>
@@ -4064,28 +4081,38 @@ template<class... Args>
4064
 
4065
  *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
4066
  equivalent to:
4067
 
4068
  ``` cpp
4069
- vprint_unicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
4070
  ```
4071
 
4072
  Otherwise, equivalent to:
4073
 
4074
  ``` cpp
4075
- vprint_nonunicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
4076
  ```
4077
 
4078
  ``` cpp
4079
  template<class... Args>
4080
  void println(ostream& os, format_string<Args...> fmt, Args&&... args);
4081
  ```
4082
 
4083
  *Effects:* Equivalent to:
4084
 
4085
  ``` cpp
4086
- print(os, "{}\n", format(fmt, std::forward<Args>(args)...));
 
 
 
 
 
 
 
 
 
 
4087
  ```
4088
 
4089
  ``` cpp
4090
  void vprint_unicode(ostream& os, string_view fmt, format_args args);
4091
  void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
@@ -4097,28 +4124,29 @@ function [[ostream.formatted.reqmts]] of `os`, except that:
4097
  - failure to generate output is reported as specified below, and
4098
  - any exception thrown by the call to `vformat` is propagated without
4099
  regard to the value of `os.exceptions()` and without turning on
4100
  `ios_base::badbit` in the error state of `os`.
4101
 
4102
- After constructing a `sentry` object, the function initializes an
4103
- automatic variable via
4104
 
4105
  ``` cpp
4106
  string out = vformat(os.getloc(), fmt, args);
4107
  ```
4108
 
4109
- If the function is `vprint_unicode` and `os` is a stream that refers to
4110
- a terminal capable of displaying Unicode which is determined in an
4111
- implementation-defined manner, writes `out` to the terminal using the
4112
- native Unicode API; if `out` contains invalid code units, the behavior
4113
- is undefined and implementations are encouraged to diagnose it. If the
4114
- native Unicode API is used, the function flushes `os` before writing
4115
- `out`. Otherwise (if `os` is not such a stream or the function is
4116
- `vprint_nonunicode`), inserts the character sequence \[`out.begin()`,
4117
- `out.end()`) into `os`. If writing to the terminal or inserting into
4118
- `os` fails, calls `os.setstate(ios_base::badbit)` (which may throw
4119
- `ios_base::failure`).
 
4120
 
4121
  *Recommended practice:* For `vprint_unicode`, if invoking the native
4122
  Unicode API requires transcoding, implementations should substitute
4123
  invalid code units with U+fffd (replacement character) per the Unicode
4124
  Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
@@ -4179,11 +4207,11 @@ object. If that object returns `true` when converted to a value of type
4179
  [[iostate.flags]]). Otherwise, if the `sentry` object returns `false`,
4180
  does nothing.
4181
 
4182
  *Returns:* `*this`.
4183
 
4184
- #### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
4185
 
4186
  Each instantiation of any of the function templates specified in this
4187
  subclause is a designated addressable function [[namespace.std]].
4188
 
4189
  ``` cpp
@@ -4225,11 +4253,11 @@ of exposition, calls `buf->set_emit_on_sync(true)`. Otherwise this
4225
  manipulator has no effect.
4226
 
4227
  [*Note 1*: To work around the issue that the `Allocator` template
4228
  argument cannot be deduced, implementations can introduce an
4229
  intermediate base class to `basic_syncbuf` that manages its
4230
- `emit_on_sync` flag. — *end note*]
4231
 
4232
  *Returns:* `os`.
4233
 
4234
  ``` cpp
4235
  template<class charT, class traits>
@@ -4642,21 +4670,27 @@ print(stdout, fmt, std::forward<Args>(args)...);
4642
  ``` cpp
4643
  template<class... Args>
4644
  void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
4645
  ```
4646
 
4647
- *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
4648
- equivalent to:
 
 
4649
 
4650
  ``` cpp
4651
- vprint_unicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
 
 
4652
  ```
4653
 
4654
  Otherwise, equivalent to:
4655
 
4656
  ``` cpp
4657
- vprint_nonunicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
 
 
4658
  ```
4659
 
4660
  ``` cpp
4661
  template<class... Args>
4662
  void println(format_string<Args...> fmt, Args&&... args);
@@ -4666,19 +4700,39 @@ template<class... Args>
4666
 
4667
  ``` cpp
4668
  println(stdout, fmt, std::forward<Args>(args)...);
4669
  ```
4670
 
 
 
 
 
 
 
 
 
 
 
4671
  ``` cpp
4672
  template<class... Args>
4673
  void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
4674
  ```
4675
 
4676
  *Effects:* Equivalent to:
4677
 
4678
  ``` cpp
4679
- print(stream, "{}\n", format(fmt, std::forward<Args>(args)...));
 
 
 
 
 
 
 
 
 
 
4680
  ```
4681
 
4682
  ``` cpp
4683
  void vprint_unicode(string_view fmt, format_args args);
4684
  ```
@@ -4687,37 +4741,47 @@ void vprint_unicode(string_view fmt, format_args args);
4687
 
4688
  ``` cpp
4689
  vprint_unicode(stdout, fmt, args);
4690
  ```
4691
 
 
 
 
 
 
 
 
 
 
 
 
4692
  ``` cpp
4693
  void vprint_unicode(FILE* stream, string_view fmt, format_args args);
4694
  ```
4695
 
4696
  *Preconditions:* `stream` is a valid pointer to an output C stream.
4697
 
4698
- *Effects:* The function initializes an automatic variable via
 
 
4699
 
4700
- ``` cpp
4701
- string out = vformat(fmt, args);
4702
- ```
 
 
 
4703
 
4704
- If `stream` refers to a terminal capable of displaying Unicode, writes
4705
- `out` to the terminal using the native Unicode API; if `out` contains
4706
- invalid code units, the behavior is undefined and implementations are
4707
- encouraged to diagnose it. Otherwise writes `out` to `stream` unchanged.
4708
- If the native Unicode API is used, the function flushes `stream` before
4709
- writing `out`.
4710
 
4711
- [*Note 1*: On POSIX and Windows, `stream` referring to a terminal means
4712
- that, respectively, `isatty(fileno(stream))` and
4713
- `GetConsoleMode(_get_osfhandle(_fileno(stream)), ...)` return
 
 
4714
  nonzero. — *end note*]
4715
 
4716
- [*Note 2*: On Windows, the native Unicode API is
4717
- `WriteConsoleW`. — *end note*]
4718
-
4719
  *Throws:* Any exception thrown by the call to `vformat`
4720
  [[format.err.report]]. `system_error` if writing to the terminal or
4721
  `stream` fails. May throw `bad_alloc`.
4722
 
4723
  *Recommended practice:* If invoking the native Unicode API requires
@@ -4733,17 +4797,30 @@ void vprint_nonunicode(string_view fmt, format_args args);
4733
 
4734
  ``` cpp
4735
  vprint_nonunicode(stdout, fmt, args);
4736
  ```
4737
 
 
 
 
 
 
 
 
 
 
 
 
4738
  ``` cpp
4739
  void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
4740
  ```
4741
 
4742
  *Preconditions:* `stream` is a valid pointer to an output C stream.
4743
 
4744
- *Effects:* Writes the result of `vformat(fmt, args)` to `stream`.
 
 
4745
 
4746
  *Throws:* Any exception thrown by the call to `vformat`
4747
  [[format.err.report]]. `system_error` if writing to `stream` fails. May
4748
  throw `bad_alloc`.
4749
 
@@ -4751,45 +4828,45 @@ throw `bad_alloc`.
4751
 
4752
  ### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
4753
 
4754
  ``` cpp
4755
  namespace std {
4756
- template<class charT, class traits = char_traits<charT>,
4757
- class Allocator = allocator<charT>>
4758
  class basic_stringbuf;
4759
 
4760
  template<class charT, class traits, class Allocator>
4761
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
4762
  basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
4763
 
4764
  using stringbuf = basic_stringbuf<char>;
4765
  using wstringbuf = basic_stringbuf<wchar_t>;
4766
 
4767
- template<class charT, class traits = char_traits<charT>,
4768
- class Allocator = allocator<charT>>
4769
  class basic_istringstream;
4770
 
4771
  template<class charT, class traits, class Allocator>
4772
  void swap(basic_istringstream<charT, traits, Allocator>& x,
4773
  basic_istringstream<charT, traits, Allocator>& y);
4774
 
4775
  using istringstream = basic_istringstream<char>;
4776
  using wistringstream = basic_istringstream<wchar_t>;
4777
 
4778
- template<class charT, class traits = char_traits<charT>,
4779
- class Allocator = allocator<charT>>
4780
  class basic_ostringstream;
4781
 
4782
  template<class charT, class traits, class Allocator>
4783
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
4784
  basic_ostringstream<charT, traits, Allocator>& y);
4785
 
4786
  using ostringstream = basic_ostringstream<char>;
4787
  using wostringstream = basic_ostringstream<wchar_t>;
4788
 
4789
- template<class charT, class traits = char_traits<charT>,
4790
- class Allocator = allocator<charT>>
4791
  class basic_stringstream;
4792
 
4793
  template<class charT, class traits, class Allocator>
4794
  void swap(basic_stringstream<charT, traits, Allocator>& x,
4795
  basic_stringstream<charT, traits, Allocator>& y);
@@ -4807,18 +4884,17 @@ described in  [[string.classes]].
4807
 
4808
  #### General <a id="stringbuf.general">[[stringbuf.general]]</a>
4809
 
4810
  ``` cpp
4811
  namespace std {
4812
- template<class charT, class traits = char_traits<charT>,
4813
- class Allocator = allocator<charT>>
4814
  class basic_stringbuf : public basic_streambuf<charT, traits> {
4815
  public:
4816
  using char_type = charT;
4817
- using int_type = typename traits::int_type;
4818
- using pos_type = typename traits::pos_type;
4819
- using off_type = typename traits::off_type;
4820
  using traits_type = traits;
4821
  using allocator_type = Allocator;
4822
 
4823
  // [stringbuf.cons], constructors
4824
  basic_stringbuf() : basic_stringbuf(ios_base::in | ios_base::out) {}
@@ -4842,10 +4918,17 @@ namespace std {
4842
  ios_base::openmode which, const Allocator& a);
4843
  template<class SAlloc>
4844
  explicit basic_stringbuf(
4845
  const basic_string<charT, traits, SAlloc>& s,
4846
  ios_base::openmode which = ios_base::in | ios_base::out);
 
 
 
 
 
 
 
4847
  basic_stringbuf(const basic_stringbuf&) = delete;
4848
  basic_stringbuf(basic_stringbuf&& rhs);
4849
  basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
4850
 
4851
  // [stringbuf.assign], assignment and swap
@@ -4864,10 +4947,12 @@ namespace std {
4864
 
4865
  void str(const basic_string<charT, traits, Allocator>& s);
4866
  template<class SAlloc>
4867
  void str(const basic_string<charT, traits, SAlloc>& s);
4868
  void str(basic_string<charT, traits, Allocator>&& s);
 
 
4869
 
4870
  protected:
4871
  // [stringbuf.virtuals], overridden virtual functions
4872
  int_type underflow() override;
4873
  int_type pbackfail(int_type c = traits::eof()) override;
@@ -4882,11 +4967,11 @@ namespace std {
4882
  = ios_base::in | ios_base::out) override;
4883
 
4884
  private:
4885
  ios_base::openmode mode; // exposition only
4886
  basic_string<charT, traits, Allocator> buf; // exposition only
4887
- void init_buf_ptrs(); // exposition only
4888
  };
4889
  }
4890
  ```
4891
 
4892
  The class `basic_stringbuf` is derived from `basic_streambuf` to
@@ -4900,22 +4985,22 @@ initialization is presented here as:
4900
 
4901
  - `ios_base::openmode mode`, has `in` set if the input sequence can be
4902
  read, and `out` set if the output sequence can be written.
4903
  - `basic_string<charT, traits, Allocator> buf` contains the underlying
4904
  character sequence.
4905
- - `init_buf_ptrs()` sets the base class’ get area [[streambuf.get.area]]
4906
  and put area [[streambuf.put.area]] pointers after initializing,
4907
- moving from, or assigning to `buf` accordingly.
4908
 
4909
  #### Constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
4910
 
4911
  ``` cpp
4912
  explicit basic_stringbuf(ios_base::openmode which);
4913
  ```
4914
 
4915
  *Effects:* Initializes the base class with `basic_streambuf()`
4916
- [[streambuf.cons]], and `mode` with `which`. It is
4917
  *implementation-defined* whether the sequence pointers (`eback()`,
4918
  `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) are initialized to
4919
  null pointers.
4920
 
4921
  *Ensures:* `str().empty()` is `true`.
@@ -4925,43 +5010,43 @@ explicit basic_stringbuf(
4925
  const basic_string<charT, traits, Allocator>& s,
4926
  ios_base::openmode which = ios_base::in | ios_base::out);
4927
  ```
4928
 
4929
  *Effects:* Initializes the base class with `basic_streambuf()`
4930
- [[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
4931
- `init_buf_ptrs()`.
4932
 
4933
  ``` cpp
4934
  basic_stringbuf(ios_base::openmode which, const Allocator& a);
4935
  ```
4936
 
4937
  *Effects:* Initializes the base class with `basic_streambuf()`
4938
- [[streambuf.cons]], `mode` with `which`, and `buf` with `a`, then calls
4939
- `init_buf_ptrs()`.
4940
 
4941
  *Ensures:* `str().empty()` is `true`.
4942
 
4943
  ``` cpp
4944
  explicit basic_stringbuf(
4945
  basic_string<charT, traits, Allocator>&& s,
4946
  ios_base::openmode which = ios_base::in | ios_base::out);
4947
  ```
4948
 
4949
  *Effects:* Initializes the base class with `basic_streambuf()`
4950
- [[streambuf.cons]], `mode` with `which`, and `buf` with `std::move(s)`,
4951
- then calls `init_buf_ptrs()`.
4952
 
4953
  ``` cpp
4954
  template<class SAlloc>
4955
  basic_stringbuf(
4956
  const basic_string<charT, traits, SAlloc>& s,
4957
  ios_base::openmode which, const Allocator& a);
4958
  ```
4959
 
4960
  *Effects:* Initializes the base class with `basic_streambuf()`
4961
- [[streambuf.cons]], `mode` with `which`, and `buf` with `{s,a}`, then
4962
- calls `init_buf_ptrs()`.
4963
 
4964
  ``` cpp
4965
  template<class SAlloc>
4966
  explicit basic_stringbuf(
4967
  const basic_string<charT, traits, SAlloc>& s,
@@ -4969,21 +5054,44 @@ template<class SAlloc>
4969
  ```
4970
 
4971
  *Constraints:* `is_same_v<SAlloc, Allocator>` is `false`.
4972
 
4973
  *Effects:* Initializes the base class with `basic_streambuf()`
4974
- [[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
4975
- `init_buf_ptrs()`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4976
 
4977
  ``` cpp
4978
  basic_stringbuf(basic_stringbuf&& rhs);
4979
  basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
4980
  ```
4981
 
4982
  *Effects:* Copy constructs the base class from `rhs` and initializes
4983
- `mode` with `rhs.mode`. In the first form `buf` is initialized from
4984
- `std::move(rhs).str()`. In the second form `buf` is initialized from
4985
  `{std::move(rhs).str(), a}`. It is *implementation-defined* whether the
4986
  sequence pointers in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`,
4987
  `pptr()`, `epptr()`) obtain the values which `rhs` had.
4988
 
4989
  *Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
@@ -5026,19 +5134,19 @@ void swap(basic_stringbuf& rhs) noexcept(see below);
5026
 
5027
  *Effects:* Exchanges the state of `*this` and `rhs`.
5028
 
5029
  *Remarks:* The exception specification is equivalent to:
5030
  `allocator_traits<Allocator>::propagate_on_container_swap::value ||`
5031
- `allocator_traits<Allocator>::is_always_equal::value`.
5032
 
5033
  ``` cpp
5034
  template<class charT, class traits, class Allocator>
5035
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
5036
  basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
5037
  ```
5038
 
5039
- *Effects:* Equivalent to: `x.swap(y)`.
5040
 
5041
  #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
5042
 
5043
  The member functions getting the underlying character sequence all refer
5044
  to a `high_mark` value, where `high_mark` represents the position one
@@ -5049,39 +5157,42 @@ of the `str` member functions passing a `basic_string` as an argument.
5049
  In the latter case, all characters initialized prior to the call are now
5050
  considered uninitialized (except for those characters re-initialized by
5051
  the new `basic_string`).
5052
 
5053
  ``` cpp
5054
- void init_buf_ptrs(); // exposition only
5055
  ```
5056
 
5057
- *Effects:* Initializes the input and output sequences from `buf`
5058
- according to `mode`.
5059
 
5060
  *Ensures:*
5061
 
5062
- - If `ios_base::out` is set in `mode`, `pbase()` points to `buf.front()`
5063
- and `epptr() >= pbase() + buf.size()` is `true`;
5064
- - in addition, if `ios_base::ate` is set in `mode`,
5065
- `pptr() == pbase() + buf.size()` is `true`,
 
5066
  - otherwise `pptr() == pbase()` is `true`.
5067
- - If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
5068
- and `(gptr() == eback() && egptr() == eback() + buf.size())` is
 
5069
  `true`.
5070
 
5071
  [*Note 1*: For efficiency reasons, stream buffer operations can violate
5072
- invariants of `buf` while it is held encapsulated in the
5073
  `basic_stringbuf`, e.g., by writing to characters in the range
5074
- \[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
5075
- operations retrieving a `basic_string` from `buf` ensure that the
5076
- `basic_string` invariants hold on the returned value. — *end note*]
 
5077
 
5078
  ``` cpp
5079
  allocator_type get_allocator() const noexcept;
5080
  ```
5081
 
5082
- *Returns:* `buf.get_allocator()`.
5083
 
5084
  ``` cpp
5085
  basic_string<charT, traits, Allocator> str() const &;
5086
  ```
5087
 
@@ -5095,11 +5206,11 @@ return basic_string<charT, traits, Allocator>(view(), get_allocator());
5095
  template<class SAlloc>
5096
  basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
5097
  ```
5098
 
5099
  *Constraints:* `SAlloc` is a type that qualifies as an
5100
- allocator [[container.requirements.general]].
5101
 
5102
  *Effects:* Equivalent to:
5103
 
5104
  ``` cpp
5105
  return basic_string<charT, traits, SAlloc>(view(), sa);
@@ -5109,11 +5220,11 @@ return basic_string<charT, traits, SAlloc>(view(), sa);
5109
  basic_string<charT, traits, Allocator> str() &&;
5110
  ```
5111
 
5112
  *Ensures:* The underlying character sequence `buf` is empty and
5113
  `pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
5114
- initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
5115
 
5116
  *Returns:* A `basic_string<charT, traits, Allocator>` object move
5117
  constructed from the `basic_stringbuf`’s underlying character sequence
5118
  in `buf`. This can be achieved by first adjusting `buf` to have the same
5119
  content as `view()`.
@@ -5125,13 +5236,13 @@ basic_string_view<charT, traits> view() const noexcept;
5125
  Let `sv` be `basic_string_view<charT, traits>`.
5126
 
5127
  *Returns:* A `sv` object referring to the `basic_stringbuf`’s underlying
5128
  character sequence in `buf`:
5129
 
5130
- - If `ios_base::out` is set in `mode`, then
5131
  `sv(pbase(), high_mark - pbase())` is returned.
5132
- - Otherwise, if `ios_base::in` is set in `mode`, then
5133
  `sv(eback(), egptr() - eback())` is returned.
5134
  - Otherwise, `sv()` is returned.
5135
 
5136
  [*Note 2*: Using the returned `sv` object after destruction or
5137
  invalidation of the character sequence underlying `*this` is undefined
@@ -5143,11 +5254,11 @@ void str(const basic_string<charT, traits, Allocator>& s);
5143
 
5144
  *Effects:* Equivalent to:
5145
 
5146
  ``` cpp
5147
  buf = s;
5148
- init_buf_ptrs();
5149
  ```
5150
 
5151
  ``` cpp
5152
  template<class SAlloc>
5153
  void str(const basic_string<charT, traits, SAlloc>& s);
@@ -5157,22 +5268,39 @@ template<class SAlloc>
5157
 
5158
  *Effects:* Equivalent to:
5159
 
5160
  ``` cpp
5161
  buf = s;
5162
- init_buf_ptrs();
5163
  ```
5164
 
5165
  ``` cpp
5166
  void str(basic_string<charT, traits, Allocator>&& s);
5167
  ```
5168
 
5169
  *Effects:* Equivalent to:
5170
 
5171
  ``` cpp
5172
  buf = std::move(s);
5173
- init_buf_ptrs();
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5174
  ```
5175
 
5176
  #### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
5177
 
5178
  ``` cpp
@@ -5194,11 +5322,11 @@ sequence, if possible, in one of three ways:
5194
  - If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
5195
  input sequence has a putback position available, and if
5196
  `traits::eq(to_char_type(c), gptr()[-1])` returns `true`, assigns
5197
  `gptr() - 1` to `gptr()`. Returns: `c`.
5198
  - If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
5199
- input sequence has a putback position available, and if `mode` `&`
5200
  `ios_base::out` is nonzero, assigns `c` to `*–gptr()`. Returns: `c`.
5201
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
5202
  input sequence has a putback position available, assigns `gptr() - 1`
5203
  to `gptr()`. Returns: `traits::not_eof(c)`.
5204
 
@@ -5226,14 +5354,14 @@ sequence, if possible, in one of two ways:
5226
 
5227
  *Remarks:* The function can alter the number of write positions
5228
  available as a result of any call.
5229
 
5230
  The function can make a write position available only if `ios_base::out`
5231
- is set in `mode`. To make a write position available, the function
5232
  reallocates (or initially allocates) an array object with a sufficient
5233
  number of elements to hold the current array object (if any), plus at
5234
- least one additional write position. If `ios_base::in` is set in `mode`,
5235
  the function alters the read end pointer `egptr()` to point just past
5236
  the new write position.
5237
 
5238
  ``` cpp
5239
  pos_type seekoff(off_type off, ios_base::seekdir way,
@@ -5303,18 +5431,17 @@ effect.
5303
 
5304
  #### General <a id="istringstream.general">[[istringstream.general]]</a>
5305
 
5306
  ``` cpp
5307
  namespace std {
5308
- template<class charT, class traits = char_traits<charT>,
5309
- class Allocator = allocator<charT>>
5310
  class basic_istringstream : public basic_istream<charT, traits> {
5311
  public:
5312
  using char_type = charT;
5313
- using int_type = typename traits::int_type;
5314
- using pos_type = typename traits::pos_type;
5315
- using off_type = typename traits::off_type;
5316
  using traits_type = traits;
5317
  using allocator_type = Allocator;
5318
 
5319
  // [istringstream.cons], constructors
5320
  basic_istringstream() : basic_istringstream(ios_base::in) {}
@@ -5336,10 +5463,16 @@ namespace std {
5336
  ios_base::openmode which, const Allocator& a);
5337
  template<class SAlloc>
5338
  explicit basic_istringstream(
5339
  const basic_string<charT, traits, SAlloc>& s,
5340
  ios_base::openmode which = ios_base::in);
 
 
 
 
 
 
5341
  basic_istringstream(const basic_istringstream&) = delete;
5342
  basic_istringstream(basic_istringstream&& rhs);
5343
 
5344
  basic_istringstream& operator=(const basic_istringstream&) = delete;
5345
  basic_istringstream& operator=(basic_istringstream&& rhs);
@@ -5357,10 +5490,12 @@ namespace std {
5357
 
5358
  void str(const basic_string<charT, traits, Allocator>& s);
5359
  template<class SAlloc>
5360
  void str(const basic_string<charT, traits, SAlloc>& s);
5361
  void str(basic_string<charT, traits, Allocator>&& s);
 
 
5362
 
5363
  private:
5364
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5365
  };
5366
  }
@@ -5370,51 +5505,54 @@ The class `basic_istringstream<charT, traits, Allocator>` supports
5370
  reading objects of class `basic_string<{}charT, traits, Allocator>`. It
5371
  uses a `basic_stringbuf<charT, traits, Allocator>` object to control the
5372
  associated storage. For the sake of exposition, the maintained data is
5373
  presented here as:
5374
 
5375
- - `sb`, the `stringbuf` object.
5376
 
5377
  #### Constructors <a id="istringstream.cons">[[istringstream.cons]]</a>
5378
 
5379
  ``` cpp
5380
  explicit basic_istringstream(ios_base::openmode which);
5381
  ```
5382
 
5383
  *Effects:* Initializes the base class with
5384
- `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5385
- `basic_stringbuf<charT, traits, Allocator>(which | ios_base::in)`
5386
  [[stringbuf.cons]].
5387
 
5388
  ``` cpp
5389
  explicit basic_istringstream(
5390
  const basic_string<charT, traits, Allocator>& s,
5391
  ios_base::openmode which = ios_base::in);
5392
  ```
5393
 
5394
  *Effects:* Initializes the base class with
5395
- `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
 
5396
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
5397
  [[stringbuf.cons]].
5398
 
5399
  ``` cpp
5400
  basic_istringstream(ios_base::openmode which, const Allocator& a);
5401
  ```
5402
 
5403
  *Effects:* Initializes the base class with
5404
- `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
 
5405
  `basic_stringbuf<charT, traits, Allocator>(which | ios_base::in, a)`
5406
  [[stringbuf.cons]].
5407
 
5408
  ``` cpp
5409
  explicit basic_istringstream(
5410
  basic_string<charT, traits, Allocator>&& s,
5411
  ios_base::openmode which = ios_base::in);
5412
  ```
5413
 
5414
  *Effects:* Initializes the base class with
5415
- `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
 
5416
  `basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::in)`
5417
  [[stringbuf.cons]].
5418
 
5419
  ``` cpp
5420
  template<class SAlloc>
@@ -5422,35 +5560,59 @@ template<class SAlloc>
5422
  const basic_string<charT, traits, SAlloc>& s,
5423
  ios_base::openmode which, const Allocator& a);
5424
  ```
5425
 
5426
  *Effects:* Initializes the base class with
5427
- `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
 
5428
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`
5429
  [[stringbuf.cons]].
5430
 
5431
  ``` cpp
5432
  template<class SAlloc>
5433
  explicit basic_istringstream(
5434
  const basic_string<charT, traits, SAlloc>& s,
5435
  ios_base::openmode which = ios_base::in);
5436
  ```
5437
 
 
 
5438
  *Effects:* Initializes the base class with
5439
- `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
 
5440
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
5441
  [[stringbuf.cons]].
5442
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5443
  ``` cpp
5444
  basic_istringstream(basic_istringstream&& rhs);
5445
  ```
5446
 
5447
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5448
  by move constructing the base class, and the contained
5449
  `basic_stringbuf`. Then calls
5450
- `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5451
- contained `basic_stringbuf`.
5452
 
5453
  #### Swap <a id="istringstream.swap">[[istringstream.swap]]</a>
5454
 
5455
  ``` cpp
5456
  void swap(basic_istringstream& rhs);
@@ -5467,20 +5629,20 @@ sb.swap(rhs.sb);
5467
  template<class charT, class traits, class Allocator>
5468
  void swap(basic_istringstream<charT, traits, Allocator>& x,
5469
  basic_istringstream<charT, traits, Allocator>& y);
5470
  ```
5471
 
5472
- *Effects:* Equivalent to: `x.swap(y)`.
5473
 
5474
  #### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
5475
 
5476
  ``` cpp
5477
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5478
  ```
5479
 
5480
  *Returns:*
5481
- `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
5482
 
5483
  ``` cpp
5484
  basic_string<charT, traits, Allocator> str() const &;
5485
  ```
5486
 
@@ -5522,24 +5684,34 @@ template<class SAlloc>
5522
  void str(basic_string<charT, traits, Allocator>&& s);
5523
  ```
5524
 
5525
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5526
 
 
 
 
 
 
 
 
 
 
 
 
5527
  ### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
5528
 
5529
  #### General <a id="ostringstream.general">[[ostringstream.general]]</a>
5530
 
5531
  ``` cpp
5532
  namespace std {
5533
- template<class charT, class traits = char_traits<charT>,
5534
- class Allocator = allocator<charT>>
5535
  class basic_ostringstream : public basic_ostream<charT, traits> {
5536
  public:
5537
  using char_type = charT;
5538
- using int_type = typename traits::int_type;
5539
- using pos_type = typename traits::pos_type;
5540
- using off_type = typename traits::off_type;
5541
  using traits_type = traits;
5542
  using allocator_type = Allocator;
5543
 
5544
  // [ostringstream.cons], constructors
5545
  basic_ostringstream() : basic_ostringstream(ios_base::out) {}
@@ -5561,10 +5733,16 @@ namespace std {
5561
  ios_base::openmode which, const Allocator& a);
5562
  template<class SAlloc>
5563
  explicit basic_ostringstream(
5564
  const basic_string<charT, traits, SAlloc>& s,
5565
  ios_base::openmode which = ios_base::out);
 
 
 
 
 
 
5566
  basic_ostringstream(const basic_ostringstream&) = delete;
5567
  basic_ostringstream(basic_ostringstream&& rhs);
5568
 
5569
  basic_ostringstream& operator=(const basic_ostringstream&) = delete;
5570
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
@@ -5583,10 +5761,12 @@ namespace std {
5583
 
5584
  void str(const basic_string<charT, traits, Allocator>& s);
5585
  template<class SAlloc>
5586
  void str(const basic_string<charT, traits, SAlloc>& s);
5587
  void str(basic_string<charT, traits, Allocator>&& s);
 
 
5588
 
5589
  private:
5590
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5591
  };
5592
  }
@@ -5595,51 +5775,54 @@ namespace std {
5595
  The class `basic_ostringstream<charT, traits, Allocator>` supports
5596
  writing objects of class `basic_string<{}charT, traits, Allocator>`. It
5597
  uses a `basic_stringbuf` object to control the associated storage. For
5598
  the sake of exposition, the maintained data is presented here as:
5599
 
5600
- - `sb`, the `stringbuf` object.
5601
 
5602
  #### Constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
5603
 
5604
  ``` cpp
5605
  explicit basic_ostringstream(ios_base::openmode which);
5606
  ```
5607
 
5608
  *Effects:* Initializes the base class with
5609
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5610
- `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out)`
5611
  [[stringbuf.cons]].
5612
 
5613
  ``` cpp
5614
  explicit basic_ostringstream(
5615
  const basic_string<charT, traits, Allocator>& s,
5616
  ios_base::openmode which = ios_base::out);
5617
  ```
5618
 
5619
  *Effects:* Initializes the base class with
5620
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
 
5621
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
5622
  [[stringbuf.cons]].
5623
 
5624
  ``` cpp
5625
  basic_ostringstream(ios_base::openmode which, const Allocator& a);
5626
  ```
5627
 
5628
  *Effects:* Initializes the base class with
5629
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
 
5630
  `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`
5631
  [[stringbuf.cons]].
5632
 
5633
  ``` cpp
5634
  explicit basic_ostringstream(
5635
  basic_string<charT, traits, Allocator>&& s,
5636
  ios_base::openmode which = ios_base::out);
5637
  ```
5638
 
5639
  *Effects:* Initializes the base class with
5640
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
 
5641
  `basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::out)`
5642
  [[stringbuf.cons]].
5643
 
5644
  ``` cpp
5645
  template<class SAlloc>
@@ -5647,11 +5830,12 @@ template<class SAlloc>
5647
  const basic_string<charT, traits, SAlloc>& s,
5648
  ios_base::openmode which, const Allocator& a);
5649
  ```
5650
 
5651
  *Effects:* Initializes the base class with
5652
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
 
5653
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`
5654
  [[stringbuf.cons]].
5655
 
5656
  ``` cpp
5657
  template<class SAlloc>
@@ -5661,23 +5845,44 @@ template<class SAlloc>
5661
  ```
5662
 
5663
  *Constraints:* `is_same_v<SAlloc, Allocator>` is `false`.
5664
 
5665
  *Effects:* Initializes the base class with
5666
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
 
5667
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
5668
  [[stringbuf.cons]].
5669
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5670
  ``` cpp
5671
  basic_ostringstream(basic_ostringstream&& rhs);
5672
  ```
5673
 
5674
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5675
  by move constructing the base class, and the contained
5676
  `basic_stringbuf`. Then calls
5677
- `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5678
- contained `basic_stringbuf`.
5679
 
5680
  #### Swap <a id="ostringstream.swap">[[ostringstream.swap]]</a>
5681
 
5682
  ``` cpp
5683
  void swap(basic_ostringstream& rhs);
@@ -5694,20 +5899,20 @@ sb.swap(rhs.sb);
5694
  template<class charT, class traits, class Allocator>
5695
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
5696
  basic_ostringstream<charT, traits, Allocator>& y);
5697
  ```
5698
 
5699
- *Effects:* Equivalent to: `x.swap(y)`.
5700
 
5701
  #### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
5702
 
5703
  ``` cpp
5704
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5705
  ```
5706
 
5707
  *Returns:*
5708
- `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
5709
 
5710
  ``` cpp
5711
  basic_string<charT, traits, Allocator> str() const &;
5712
  ```
5713
 
@@ -5749,24 +5954,34 @@ template<class SAlloc>
5749
  void str(basic_string<charT, traits, Allocator>&& s);
5750
  ```
5751
 
5752
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5753
 
 
 
 
 
 
 
 
 
 
 
 
5754
  ### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
5755
 
5756
  #### General <a id="stringstream.general">[[stringstream.general]]</a>
5757
 
5758
  ``` cpp
5759
  namespace std {
5760
- template<class charT, class traits = char_traits<charT>,
5761
- class Allocator = allocator<charT>>
5762
  class basic_stringstream : public basic_iostream<charT, traits> {
5763
  public:
5764
  using char_type = charT;
5765
- using int_type = typename traits::int_type;
5766
- using pos_type = typename traits::pos_type;
5767
- using off_type = typename traits::off_type;
5768
  using traits_type = traits;
5769
  using allocator_type = Allocator;
5770
 
5771
  // [stringstream.cons], constructors
5772
  basic_stringstream() : basic_stringstream(ios_base::out | ios_base::in) {}
@@ -5788,10 +6003,17 @@ namespace std {
5788
  ios_base::openmode which, const Allocator& a);
5789
  template<class SAlloc>
5790
  explicit basic_stringstream(
5791
  const basic_string<charT, traits, SAlloc>& s,
5792
  ios_base::openmode which = ios_base::out | ios_base::in);
 
 
 
 
 
 
 
5793
  basic_stringstream(const basic_stringstream&) = delete;
5794
  basic_stringstream(basic_stringstream&& rhs);
5795
 
5796
  basic_stringstream& operator=(const basic_stringstream&) = delete;
5797
  basic_stringstream& operator=(basic_stringstream&& rhs);
@@ -5810,13 +6032,15 @@ namespace std {
5810
 
5811
  void str(const basic_string<charT, traits, Allocator>& s);
5812
  template<class SAlloc>
5813
  void str(const basic_string<charT, traits, SAlloc>& s);
5814
  void str(basic_string<charT, traits, Allocator>&& s);
 
 
5815
 
5816
  private:
5817
- basic_stringbuf<charT, traits> sb; // exposition only
5818
  };
5819
  }
5820
  ```
5821
 
5822
  The class template `basic_stringstream<charT, traits>` supports reading
@@ -5824,50 +6048,50 @@ and writing from objects of class
5824
  `basic_string<charT, traits, Allocator>`. It uses a
5825
  `basic_stringbuf<charT, traits, Allocator>` object to control the
5826
  associated sequence. For the sake of exposition, the maintained data is
5827
  presented here as
5828
 
5829
- - `sb`, the `stringbuf` object.
5830
 
5831
  #### Constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
5832
 
5833
  ``` cpp
5834
  explicit basic_stringstream(ios_base::openmode which);
5835
  ```
5836
 
5837
  *Effects:* Initializes the base class with
5838
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5839
- `sb` with `basic_stringbuf<charT, traits, Allocator>(which)`.
5840
 
5841
  ``` cpp
5842
  explicit basic_stringstream(
5843
  const basic_string<charT, traits, Allocator>& s,
5844
  ios_base::openmode which = ios_base::out | ios_base::in);
5845
  ```
5846
 
5847
  *Effects:* Initializes the base class with
5848
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5849
- `sb` with `basic_stringbuf<charT, traits, Allocator>(s, which)`.
5850
 
5851
  ``` cpp
5852
  basic_stringstream(ios_base::openmode which, const Allocator& a);
5853
  ```
5854
 
5855
  *Effects:* Initializes the base class with
5856
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5857
- `sb` with `basic_stringbuf<charT, traits, Allocator>(which, a)`
5858
  [[stringbuf.cons]].
5859
 
5860
  ``` cpp
5861
  explicit basic_stringstream(
5862
  basic_string<charT, traits, Allocator>&& s,
5863
  ios_base::openmode which = ios_base::out | ios_base::in);
5864
  ```
5865
 
5866
  *Effects:* Initializes the base class with
5867
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5868
- `sb` with
5869
  `basic_stringbuf<charT, traits, Allocator>(std::move(s), which)`
5870
  [[stringbuf.cons]].
5871
 
5872
  ``` cpp
5873
  template<class SAlloc>
@@ -5875,12 +6099,12 @@ template<class SAlloc>
5875
  const basic_string<charT, traits, SAlloc>& s,
5876
  ios_base::openmode which, const Allocator& a);
5877
  ```
5878
 
5879
  *Effects:* Initializes the base class with
5880
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5881
- `sb` with `basic_stringbuf<charT, traits, Allocator>(s, which, a)`
5882
  [[stringbuf.cons]].
5883
 
5884
  ``` cpp
5885
  template<class SAlloc>
5886
  explicit basic_stringstream(
@@ -5889,23 +6113,43 @@ template<class SAlloc>
5889
  ```
5890
 
5891
  *Constraints:* `is_same_v<SAlloc, Allocator>` is `false`.
5892
 
5893
  *Effects:* Initializes the base class with
5894
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5895
- `sb` with `basic_stringbuf<charT, traits, Allocator>(s, which)`
5896
  [[stringbuf.cons]].
5897
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5898
  ``` cpp
5899
  basic_stringstream(basic_stringstream&& rhs);
5900
  ```
5901
 
5902
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5903
  by move constructing the base class, and the contained
5904
  `basic_stringbuf`. Then calls
5905
- `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5906
- contained `basic_stringbuf`.
5907
 
5908
  #### Swap <a id="stringstream.swap">[[stringstream.swap]]</a>
5909
 
5910
  ``` cpp
5911
  void swap(basic_stringstream& rhs);
@@ -5922,20 +6166,20 @@ sb.swap(rhs.sb);
5922
  template<class charT, class traits, class Allocator>
5923
  void swap(basic_stringstream<charT, traits, Allocator>& x,
5924
  basic_stringstream<charT, traits, Allocator>& y);
5925
  ```
5926
 
5927
- *Effects:* Equivalent to: `x.swap(y)`.
5928
 
5929
  #### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
5930
 
5931
  ``` cpp
5932
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5933
  ```
5934
 
5935
  *Returns:*
5936
- `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
5937
 
5938
  ``` cpp
5939
  basic_string<charT, traits, Allocator> str() const &;
5940
  ```
5941
 
@@ -5977,57 +6221,72 @@ template<class SAlloc>
5977
  void str(basic_string<charT, traits, Allocator>&& s);
5978
  ```
5979
 
5980
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5981
 
 
 
 
 
 
 
 
 
 
 
 
5982
  ## Span-based streams <a id="span.streams">[[span.streams]]</a>
5983
 
5984
  ### Overview <a id="span.streams.overview">[[span.streams.overview]]</a>
5985
 
5986
  The header `<spanstream>` defines class templates and types that
5987
  associate stream buffers with objects whose types are specializations of
5988
  `span` as described in [[views.span]].
5989
 
5990
  [*Note 1*: A user of these classes is responsible for ensuring that the
5991
  character sequence represented by the given `span` outlives the use of
5992
- the sequence by objects of the classes in subclause [[span.streams]].
5993
- Using multiple `basic_spanbuf` objects referring to overlapping
5994
- underlying sequences from different threads, where at least one
5995
- `basic_spanbuf` object is used for writing to the sequence, results in a
5996
- data race. — *end note*]
5997
 
5998
  ### Header `<spanstream>` synopsis <a id="spanstream.syn">[[spanstream.syn]]</a>
5999
 
6000
  ``` cpp
6001
  namespace std {
 
6002
  template<class charT, class traits = char_traits<charT>>
6003
  class basic_spanbuf;
6004
 
6005
  template<class charT, class traits>
6006
  void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
6007
 
6008
  using spanbuf = basic_spanbuf<char>;
6009
  using wspanbuf = basic_spanbuf<wchar_t>;
6010
 
 
6011
  template<class charT, class traits = char_traits<charT>>
6012
  class basic_ispanstream;
6013
 
6014
  template<class charT, class traits>
6015
  void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
6016
 
6017
  using ispanstream = basic_ispanstream<char>;
6018
  using wispanstream = basic_ispanstream<wchar_t>;
6019
 
 
6020
  template<class charT, class traits = char_traits<charT>>
6021
  class basic_ospanstream;
6022
 
6023
  template<class charT, class traits>
6024
  void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
6025
 
6026
  using ospanstream = basic_ospanstream<char>;
6027
  using wospanstream = basic_ospanstream<wchar_t>;
6028
 
 
6029
  template<class charT, class traits = char_traits<charT>>
6030
  class basic_spanstream;
6031
 
6032
  template<class charT, class traits>
6033
  void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
@@ -6046,13 +6305,13 @@ namespace std {
6046
  template<class charT, class traits = char_traits<charT>>
6047
  class basic_spanbuf
6048
  : public basic_streambuf<charT, traits> {
6049
  public:
6050
  using char_type = charT;
6051
- using int_type = typename traits::int_type;
6052
- using pos_type = typename traits::pos_type;
6053
- using off_type = typename traits::off_type;
6054
  using traits_type = traits;
6055
 
6056
  // [spanbuf.cons], constructors
6057
  basic_spanbuf() : basic_spanbuf(ios_base::in | ios_base::out) {}
6058
  explicit basic_spanbuf(ios_base::openmode which)
@@ -6229,11 +6488,11 @@ follows:
6229
  - `(pptr() - pbase())` for the output sequence, or `(gptr() - eback())`
6230
  for the input sequence when `way` is `ios_base::cur`;
6231
  - when `way` is `ios_base::end` :
6232
  - `(pptr() - pbase())` if `ios_base::out` is set in *mode* and
6233
  `ios_base::in` is not set in *mode*,
6234
- - `buf.size()` otherwise.
6235
 
6236
  If `baseoff` + `off` would overflow, or if `baseoff` + `off` is less
6237
  than zero, or if `baseoff` + `off` is greater than *`buf`*`.size()`, the
6238
  positioning operation fails. Otherwise, the function computes
6239
 
@@ -6276,13 +6535,13 @@ namespace std {
6276
  template<class charT, class traits = char_traits<charT>>
6277
  class basic_ispanstream
6278
  : public basic_istream<charT, traits> {
6279
  public:
6280
  using char_type = charT;
6281
- using int_type = typename traits::int_type;
6282
- using pos_type = typename traits::pos_type;
6283
- using off_type = typename traits::off_type;
6284
  using traits_type = traits;
6285
 
6286
  // [ispanstream.cons], constructors
6287
  explicit basic_ispanstream(std::span<charT> s,
6288
  ios_base::openmode which = ios_base::in);
@@ -6318,33 +6577,33 @@ includes the termination character `'\0'` in the underlying
6318
  ``` cpp
6319
  explicit basic_ispanstream(std::span<charT> s, ios_base::openmode which = ios_base::in);
6320
  ```
6321
 
6322
  *Effects:* Initializes the base class with
6323
- `basic_istream<charT, traits>(addressof(sb))` and `sb` with
6324
  `basic_spanbuf<charT, traits>(s, which | ios_base::in)`
6325
  [[spanbuf.cons]].
6326
 
6327
  ``` cpp
6328
  basic_ispanstream(basic_ispanstream&& rhs);
6329
  ```
6330
 
6331
- *Effects:* Initializes the base class with `std::move(rhs)` and `sb`
6332
- with `std::move(rhs.sb)`. Next,
6333
- `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` is called to
6334
- install the contained `basic_spanbuf`.
6335
 
6336
  ``` cpp
6337
  template<class ROS> explicit basic_ispanstream(ROS&& s)
6338
  ```
6339
 
6340
  *Constraints:* `ROS` models `ranges::borrowed_range`.
6341
  `!convertible_to<ROS, std::span<charT>> && convertible_to<ROS, std::span<charT const>>`
6342
  is `true`.
6343
 
6344
  *Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
6345
- Equivalent to
6346
 
6347
  ``` cpp
6348
  basic_ispanstream(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
6349
  ```
6350
 
@@ -6402,11 +6661,11 @@ is `true`.
6402
 
6403
  *Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
6404
  Equivalent to:
6405
 
6406
  ``` cpp
6407
- this->span(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
6408
  ```
6409
 
6410
  ### Class template `basic_ospanstream` <a id="ospanstream">[[ospanstream]]</a>
6411
 
6412
  #### General <a id="ospanstream.general">[[ospanstream.general]]</a>
@@ -6416,13 +6675,13 @@ namespace std {
6416
  template<class charT, class traits = char_traits<charT>>
6417
  class basic_ospanstream
6418
  : public basic_ostream<charT, traits> {
6419
  public:
6420
  using char_type = charT;
6421
- using int_type = typename traits::int_type;
6422
- using pos_type = typename traits::pos_type;
6423
- using off_type = typename traits::off_type;
6424
  using traits_type = traits;
6425
 
6426
  // [ospanstream.cons], constructors
6427
  explicit basic_ospanstream(std::span<charT> s,
6428
  ios_base::openmode which = ios_base::out);
@@ -6453,22 +6712,22 @@ namespace std {
6453
  explicit basic_ospanstream(std::span<charT> s,
6454
  ios_base::openmode which = ios_base::out);
6455
  ```
6456
 
6457
  *Effects:* Initializes the base class with
6458
- `basic_ostream<charT, traits>(addressof(sb))` and `sb` with
6459
  `basic_spanbuf<charT, traits>(s, which | ios_base::out)`
6460
  [[spanbuf.cons]].
6461
 
6462
  ``` cpp
6463
  basic_ospanstream(basic_ospanstream&& rhs) noexcept;
6464
  ```
6465
 
6466
- *Effects:* Initializes the base class with `std::move(rhs)` and `sb`
6467
- with `std::move(rhs.sb)`. Next,
6468
- `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` is called to
6469
- install the contained `basic_spanbuf`.
6470
 
6471
  #### Swap <a id="ospanstream.swap">[[ospanstream.swap]]</a>
6472
 
6473
  ``` cpp
6474
  void swap(basic_ospanstream& rhs);
@@ -6521,13 +6780,13 @@ namespace std {
6521
  template<class charT, class traits = char_traits<charT>>
6522
  class basic_spanstream
6523
  : public basic_iostream<charT, traits> {
6524
  public:
6525
  using char_type = charT;
6526
- using int_type = typename traits::int_type;
6527
- using pos_type = typename traits::pos_type;
6528
- using off_type = typename traits::off_type;
6529
  using traits_type = traits;
6530
 
6531
  // [spanstream.cons], constructors
6532
  explicit basic_spanstream(std::span<charT> s,
6533
  ios_base::openmode which = ios_base::out | ios_base::in);
@@ -6558,21 +6817,21 @@ namespace std {
6558
  explicit basic_spanstream(std::span<charT> s,
6559
  ios_base::openmode which = ios_base::out | ios_bas::in);
6560
  ```
6561
 
6562
  *Effects:* Initializes the base class with
6563
- `basic_iostream<charT, traits>(addressof(sb))` and `sb` with
6564
  `basic_spanbuf<charT, traits>(s, which)` [[spanbuf.cons]].
6565
 
6566
  ``` cpp
6567
  basic_spanstream(basic_spanstream&& rhs);
6568
  ```
6569
 
6570
- *Effects:* Initializes the base class with `std::move(rhs)` and `sb`
6571
- with `std::move(rhs.sb)`. Next,
6572
- `basic_iostream<charT, traits>::set_rdbuf(addressof(sb))` is called to
6573
- install the contained `basic_spanbuf`.
6574
 
6575
  #### Swap <a id="spanstream.swap">[[spanstream.swap]]</a>
6576
 
6577
  ``` cpp
6578
  void swap(basic_spanstream& rhs);
@@ -6620,37 +6879,41 @@ void span(std::span<charT> s) noexcept;
6620
 
6621
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
6622
 
6623
  ``` cpp
6624
  namespace std {
 
6625
  template<class charT, class traits = char_traits<charT>>
6626
  class basic_filebuf;
6627
 
6628
  template<class charT, class traits>
6629
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
6630
 
6631
  using filebuf = basic_filebuf<char>;
6632
  using wfilebuf = basic_filebuf<wchar_t>;
6633
 
 
6634
  template<class charT, class traits = char_traits<charT>>
6635
  class basic_ifstream;
6636
 
6637
  template<class charT, class traits>
6638
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
6639
 
6640
  using ifstream = basic_ifstream<char>;
6641
  using wifstream = basic_ifstream<wchar_t>;
6642
 
 
6643
  template<class charT, class traits = char_traits<charT>>
6644
  class basic_ofstream;
6645
 
6646
  template<class charT, class traits>
6647
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
6648
 
6649
  using ofstream = basic_ofstream<char>;
6650
  using wofstream = basic_ofstream<wchar_t>;
6651
 
 
6652
  template<class charT, class traits = char_traits<charT>>
6653
  class basic_fstream;
6654
 
6655
  template<class charT, class traits>
6656
  void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);
@@ -6675,24 +6938,38 @@ In subclause  [[file.streams]], member functions taking arguments of
6675
  `filesystem::path::value_type` [[fs.class.path]] is not `char`.
6676
 
6677
  [*Note 2*: These functions enable class `path` support for systems with
6678
  a wide native path character type, such as `wchar_t`. — *end note*]
6679
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6680
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
6681
 
6682
  #### General <a id="filebuf.general">[[filebuf.general]]</a>
6683
 
6684
  ``` cpp
6685
  namespace std {
6686
  template<class charT, class traits = char_traits<charT>>
6687
  class basic_filebuf : public basic_streambuf<charT, traits> {
6688
  public:
6689
  using char_type = charT;
6690
- using int_type = typename traits::int_type;
6691
- using pos_type = typename traits::pos_type;
6692
- using off_type = typename traits::off_type;
6693
  using traits_type = traits;
 
6694
 
6695
  // [filebuf.cons], constructors/destructor
6696
  basic_filebuf();
6697
  basic_filebuf(const basic_filebuf&) = delete;
6698
  basic_filebuf(basic_filebuf&& rhs);
@@ -6706,32 +6983,30 @@ namespace std {
6706
  // [filebuf.members], members
6707
  bool is_open() const;
6708
  basic_filebuf* open(const char* s, ios_base::openmode mode);
6709
  basic_filebuf* open(const filesystem::path::value_type* s,
6710
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
6711
- basic_filebuf* open(const string& s,
6712
- ios_base::openmode mode);
6713
- basic_filebuf* open(const filesystem::path& s,
6714
- ios_base::openmode mode);
6715
  basic_filebuf* close();
 
6716
 
6717
  protected:
6718
  // [filebuf.virtuals], overridden virtual functions
6719
  streamsize showmanyc() override;
6720
  int_type underflow() override;
6721
  int_type uflow() override;
6722
  int_type pbackfail(int_type c = traits::eof()) override;
6723
  int_type overflow (int_type c = traits::eof()) override;
6724
 
6725
- basic_streambuf<charT, traits>* setbuf(char_type* s,
6726
- streamsize n) override;
6727
  pos_type seekoff(off_type off, ios_base::seekdir way,
6728
- ios_base::openmode which
6729
- = ios_base::in | ios_base::out) override;
6730
  pos_type seekpos(pos_type sp,
6731
- ios_base::openmode which
6732
- = ios_base::in | ios_base::out) override;
6733
  int sync() override;
6734
  void imbue(const locale& loc) override;
6735
  };
6736
  }
6737
  ```
@@ -6753,10 +7028,19 @@ In particular:
6753
 
6754
  An instance of `basic_filebuf` behaves as described in  [[filebuf]]
6755
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
6756
  the behavior is undefined.
6757
 
 
 
 
 
 
 
 
 
 
6758
  In order to support file I/O and multibyte/wide character conversion,
6759
  conversions are performed using members of a facet, referred to as
6760
  `a_codecvt` in following subclauses, obtained as if by
6761
 
6762
  ``` cpp
@@ -6835,11 +7119,11 @@ void swap(basic_filebuf& rhs);
6835
  ``` cpp
6836
  template<class charT, class traits>
6837
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
6838
  ```
6839
 
6840
- *Effects:* Equivalent to: `x.swap(y)`.
6841
 
6842
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
6843
 
6844
  ``` cpp
6845
  bool is_open() const;
@@ -6852,11 +7136,11 @@ non-null value) and there has been no intervening call to close.
6852
  basic_filebuf* open(const char* s, ios_base::openmode mode);
6853
  basic_filebuf* open(const filesystem::path::value_type* s,
6854
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
6855
  ```
6856
 
6857
- *Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
6858
 
6859
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
6860
  initializes the `filebuf` as required. It then opens the file to which
6861
  `s` resolves, if possible, as if by a call to `fopen` with the second
6862
  argument determined from `mode & ~ios_base::ate` as indicated in
@@ -6929,10 +7213,18 @@ after closing the file.
6929
 
6930
  *Ensures:* `is_open() == false`.
6931
 
6932
  *Returns:* `this` on success, a null pointer otherwise.
6933
 
 
 
 
 
 
 
 
 
6934
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
6935
 
6936
  ``` cpp
6937
  streamsize showmanyc() override;
6938
  ```
@@ -6954,11 +7246,11 @@ that a sequence of characters is read from the input sequence as if by
6954
  reading from the associated file into an internal buffer (`extern_buf`)
6955
  and then as if by doing:
6956
 
6957
  ``` cpp
6958
  char extern_buf[XSIZE];
6959
- char* extern_end;
6960
  charT intern_buf[ISIZE];
6961
  charT* intern_end;
6962
  codecvt_base::result r =
6963
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
6964
  intern_buf, intern_buf+ISIZE, intern_end);
@@ -7019,11 +7311,11 @@ int_type overflow(int_type c = traits::eof()) override;
7019
  of “consuming characters” is performed by first converting as if by:
7020
 
7021
  ``` cpp
7022
  charT* b = pbase();
7023
  charT* p = pptr();
7024
- charT* end;
7025
  char xbuf[XSIZE];
7026
  char* xbuf_end;
7027
  codecvt_base::result r =
7028
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);
7029
  ```
@@ -7038,10 +7330,12 @@ and then
7038
  to `p`. If output fails, fail (without repeating).
7039
  - Otherwise output from `xbuf` to `xbuf_end`, and fail if output fails.
7040
  At this point if `b != p` and `b == end` (`xbuf` isn’t large enough)
7041
  then increase `XSIZE` and repeat from the beginning.
7042
 
 
 
7043
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
7044
  to indicate failure. If `is_open() == false`, the function always fails.
7045
 
7046
  ``` cpp
7047
  basic_streambuf* setbuf(char_type* s, streamsize n) override;
@@ -7072,11 +7366,11 @@ resultant stream position, if possible. If the positioning operation
7072
  fails, or if the object cannot represent the resultant stream position,
7073
  returns `pos_type(off_type(-1))`.
7074
 
7075
  *Remarks:* “The last operation was output” means either the last virtual
7076
  operation was overflow or the put buffer is non-empty. “Write any
7077
- unshift sequence” means, if `width` if less than zero then call
7078
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
7079
  resulting unshift sequence. The function determines one of three values
7080
  for the argument `whence`, of type `int`, as indicated in
7081
  [[filebuf.seekoff]].
7082
 
@@ -7147,14 +7441,15 @@ reconstruct the original contents of the file.
7147
  namespace std {
7148
  template<class charT, class traits = char_traits<charT>>
7149
  class basic_ifstream : public basic_istream<charT, traits> {
7150
  public:
7151
  using char_type = charT;
7152
- using int_type = typename traits::int_type;
7153
- using pos_type = typename traits::pos_type;
7154
- using off_type = typename traits::off_type;
7155
  using traits_type = traits;
 
7156
 
7157
  // [ifstream.cons], constructors
7158
  basic_ifstream();
7159
  explicit basic_ifstream(const char* s,
7160
  ios_base::openmode mode = ios_base::in);
@@ -7173,10 +7468,11 @@ namespace std {
7173
  // [ifstream.swap], swap
7174
  void swap(basic_ifstream& rhs);
7175
 
7176
  // [ifstream.members], members
7177
  basic_filebuf<charT, traits>* rdbuf() const;
 
7178
 
7179
  bool is_open() const;
7180
  void open(const char* s, ios_base::openmode mode = ios_base::in);
7181
  void open(const filesystem::path::value_type* s,
7182
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
@@ -7193,83 +7489,91 @@ namespace std {
7193
  The class `basic_ifstream<charT, traits>` supports reading from named
7194
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
7195
  associated sequence. For the sake of exposition, the maintained data is
7196
  presented here as:
7197
 
7198
- - `sb`, the `filebuf` object.
7199
 
7200
  #### Constructors <a id="ifstream.cons">[[ifstream.cons]]</a>
7201
 
7202
  ``` cpp
7203
  basic_ifstream();
7204
  ```
7205
 
7206
  *Effects:* Initializes the base class with
7207
- `basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
7208
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
7209
 
7210
  ``` cpp
7211
  explicit basic_ifstream(const char* s,
7212
  ios_base::openmode mode = ios_base::in);
7213
  explicit basic_ifstream(const filesystem::path::value_type* s,
7214
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
7215
  ```
7216
 
7217
  *Effects:* Initializes the base class with
7218
- `basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
7219
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
7220
  `rdbuf()->open(s, mode | ios_base::in)`. If that function returns a null
7221
  pointer, calls `setstate(failbit)`.
7222
 
7223
  ``` cpp
7224
  explicit basic_ifstream(const string& s,
7225
  ios_base::openmode mode = ios_base::in);
7226
  ```
7227
 
7228
- *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
7229
 
7230
  ``` cpp
7231
  template<class T>
7232
  explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
7233
  ```
7234
 
7235
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7236
 
7237
- *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
7238
 
7239
  ``` cpp
7240
  basic_ifstream(basic_ifstream&& rhs);
7241
  ```
7242
 
7243
  *Effects:* Move constructs the base class, and the contained
7244
  `basic_filebuf`. Then calls
7245
- `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
7246
- contained `basic_filebuf`.
7247
 
7248
  #### Swap <a id="ifstream.swap">[[ifstream.swap]]</a>
7249
 
7250
  ``` cpp
7251
  void swap(basic_ifstream& rhs);
7252
  ```
7253
 
7254
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7255
- `basic_istream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
7256
 
7257
  ``` cpp
7258
  template<class charT, class traits>
7259
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
7260
  ```
7261
 
7262
- *Effects:* Equivalent to: `x.swap(y)`.
7263
 
7264
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
7265
 
7266
  ``` cpp
7267
  basic_filebuf<charT, traits>* rdbuf() const;
7268
  ```
7269
 
7270
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
 
 
 
 
 
 
 
7271
 
7272
  ``` cpp
7273
  bool is_open() const;
7274
  ```
7275
 
@@ -7309,14 +7613,15 @@ pointer, calls `setstate(failbit)` (which may throw
7309
  namespace std {
7310
  template<class charT, class traits = char_traits<charT>>
7311
  class basic_ofstream : public basic_ostream<charT, traits> {
7312
  public:
7313
  using char_type = charT;
7314
- using int_type = typename traits::int_type;
7315
- using pos_type = typename traits::pos_type;
7316
- using off_type = typename traits::off_type;
7317
  using traits_type = traits;
 
7318
 
7319
  // [ofstream.cons], constructors
7320
  basic_ofstream();
7321
  explicit basic_ofstream(const char* s,
7322
  ios_base::openmode mode = ios_base::out);
@@ -7335,10 +7640,11 @@ namespace std {
7335
  // [ofstream.swap], swap
7336
  void swap(basic_ofstream& rhs);
7337
 
7338
  // [ofstream.members], members
7339
  basic_filebuf<charT, traits>* rdbuf() const;
 
7340
 
7341
  bool is_open() const;
7342
  void open(const char* s, ios_base::openmode mode = ios_base::out);
7343
  void open(const filesystem::path::value_type* s,
7344
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
@@ -7355,83 +7661,91 @@ namespace std {
7355
  The class `basic_ofstream<charT, traits>` supports writing to named
7356
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
7357
  associated sequence. For the sake of exposition, the maintained data is
7358
  presented here as:
7359
 
7360
- - `sb`, the `filebuf` object.
7361
 
7362
  #### Constructors <a id="ofstream.cons">[[ofstream.cons]]</a>
7363
 
7364
  ``` cpp
7365
  basic_ofstream();
7366
  ```
7367
 
7368
  *Effects:* Initializes the base class with
7369
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
7370
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
7371
 
7372
  ``` cpp
7373
  explicit basic_ofstream(const char* s,
7374
  ios_base::openmode mode = ios_base::out);
7375
  explicit basic_ofstream(const filesystem::path::value_type* s,
7376
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
7377
  ```
7378
 
7379
  *Effects:* Initializes the base class with
7380
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
7381
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
7382
  `rdbuf()->open(s, mode | ios_base::out)`. If that function returns a
7383
  null pointer, calls `setstate(failbit)`.
7384
 
7385
  ``` cpp
7386
  explicit basic_ofstream(const string& s,
7387
  ios_base::openmode mode = ios_base::out);
7388
  ```
7389
 
7390
- *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
7391
 
7392
  ``` cpp
7393
  template<class T>
7394
  explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
7395
  ```
7396
 
7397
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7398
 
7399
- *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
7400
 
7401
  ``` cpp
7402
  basic_ofstream(basic_ofstream&& rhs);
7403
  ```
7404
 
7405
  *Effects:* Move constructs the base class, and the contained
7406
  `basic_filebuf`. Then calls
7407
- `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
7408
- contained `basic_filebuf`.
7409
 
7410
  #### Swap <a id="ofstream.swap">[[ofstream.swap]]</a>
7411
 
7412
  ``` cpp
7413
  void swap(basic_ofstream& rhs);
7414
  ```
7415
 
7416
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7417
- `basic_ostream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
7418
 
7419
  ``` cpp
7420
  template<class charT, class traits>
7421
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
7422
  ```
7423
 
7424
- *Effects:* Equivalent to: `x.swap(y)`.
7425
 
7426
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
7427
 
7428
  ``` cpp
7429
  basic_filebuf<charT, traits>* rdbuf() const;
7430
  ```
7431
 
7432
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
 
 
 
 
 
 
 
7433
 
7434
  ``` cpp
7435
  bool is_open() const;
7436
  ```
7437
 
@@ -7471,14 +7785,15 @@ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
7471
  namespace std {
7472
  template<class charT, class traits = char_traits<charT>>
7473
  class basic_fstream : public basic_iostream<charT, traits> {
7474
  public:
7475
  using char_type = charT;
7476
- using int_type = typename traits::int_type;
7477
- using pos_type = typename traits::pos_type;
7478
- using off_type = typename traits::off_type;
7479
  using traits_type = traits;
 
7480
 
7481
  // [fstream.cons], constructors
7482
  basic_fstream();
7483
  explicit basic_fstream(
7484
  const char* s,
@@ -7500,10 +7815,12 @@ namespace std {
7500
  // [fstream.swap], swap
7501
  void swap(basic_fstream& rhs);
7502
 
7503
  // [fstream.members], members
7504
  basic_filebuf<charT, traits>* rdbuf() const;
 
 
7505
  bool is_open() const;
7506
  void open(
7507
  const char* s,
7508
  ios_base::openmode mode = ios_base::in | ios_base::out);
7509
  void open(
@@ -7526,21 +7843,21 @@ namespace std {
7526
  The class template `basic_fstream<charT, traits>` supports reading and
7527
  writing from named files. It uses a `basic_filebuf<charT, traits>`
7528
  object to control the associated sequences. For the sake of exposition,
7529
  the maintained data is presented here as:
7530
 
7531
- - `sb`, the `basic_filebuf` object.
7532
 
7533
  #### Constructors <a id="fstream.cons">[[fstream.cons]]</a>
7534
 
7535
  ``` cpp
7536
  basic_fstream();
7537
  ```
7538
 
7539
  *Effects:* Initializes the base class with
7540
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
7541
- `sb` with `basic_filebuf<charT, traits>()`.
7542
 
7543
  ``` cpp
7544
  explicit basic_fstream(
7545
  const char* s,
7546
  ios_base::openmode mode = ios_base::in | ios_base::out);
@@ -7548,65 +7865,73 @@ explicit basic_fstream(
7548
  const filesystem::path::value_type* s,
7549
  ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
7550
  ```
7551
 
7552
  *Effects:* Initializes the base class with
7553
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
7554
- `sb` with `basic_filebuf<charT, traits>()`. Then calls
7555
  `rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
7556
  `setstate(failbit)`.
7557
 
7558
  ``` cpp
7559
  explicit basic_fstream(
7560
  const string& s,
7561
  ios_base::openmode mode = ios_base::in | ios_base::out);
7562
  ```
7563
 
7564
- *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
7565
 
7566
  ``` cpp
7567
  template<class T>
7568
  explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
7569
  ```
7570
 
7571
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7572
 
7573
- *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
7574
 
7575
  ``` cpp
7576
  basic_fstream(basic_fstream&& rhs);
7577
  ```
7578
 
7579
  *Effects:* Move constructs the base class, and the contained
7580
  `basic_filebuf`. Then calls
7581
- `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
7582
- contained `basic_filebuf`.
7583
 
7584
  #### Swap <a id="fstream.swap">[[fstream.swap]]</a>
7585
 
7586
  ``` cpp
7587
  void swap(basic_fstream& rhs);
7588
  ```
7589
 
7590
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7591
- `basic_iostream<charT,traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
7592
 
7593
  ``` cpp
7594
  template<class charT, class traits>
7595
  void swap(basic_fstream<charT, traits>& x,
7596
  basic_fstream<charT, traits>& y);
7597
  ```
7598
 
7599
- *Effects:* Equivalent to: `x.swap(y)`.
7600
 
7601
  #### Member functions <a id="fstream.members">[[fstream.members]]</a>
7602
 
7603
  ``` cpp
7604
  basic_filebuf<charT, traits>* rdbuf() const;
7605
  ```
7606
 
7607
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
 
 
 
 
 
 
 
7608
 
7609
  ``` cpp
7610
  bool is_open() const;
7611
  ```
7612
 
@@ -7651,10 +7976,11 @@ pointer, calls `setstate(failbit)` (which may throw
7651
 
7652
  ``` cpp
7653
  #include <ostream> // see [ostream.syn]
7654
 
7655
  namespace std {
 
7656
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7657
  class basic_syncbuf;
7658
 
7659
  // [syncstream.syncbuf.special], specialized algorithms
7660
  template<class charT, class traits, class Allocator>
@@ -7662,10 +7988,11 @@ namespace std {
7662
  basic_syncbuf<charT, traits, Allocator>&);
7663
 
7664
  using syncbuf = basic_syncbuf<char>;
7665
  using wsyncbuf = basic_syncbuf<wchar_t>;
7666
 
 
7667
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7668
  class basic_osyncstream;
7669
 
7670
  using osyncstream = basic_osyncstream<char>;
7671
  using wosyncstream = basic_osyncstream<wchar_t>;
@@ -7683,13 +8010,13 @@ agents writing to the same stream.
7683
  namespace std {
7684
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7685
  class basic_syncbuf : public basic_streambuf<charT, traits> {
7686
  public:
7687
  using char_type = charT;
7688
- using int_type = typename traits::int_type;
7689
- using pos_type = typename traits::pos_type;
7690
- using off_type = typename traits::off_type;
7691
  using traits_type = traits;
7692
  using allocator_type = Allocator;
7693
 
7694
  using streambuf_type = basic_streambuf<charT, traits>;
7695
 
@@ -7716,11 +8043,11 @@ namespace std {
7716
  // [syncstream.syncbuf.virtuals], overridden virtual functions
7717
  int sync() override;
7718
 
7719
  private:
7720
  streambuf_type* wrapped; // exposition only
7721
- bool emit_on_sync{}; // exposition only
7722
  };
7723
  }
7724
  ```
7725
 
7726
  Class template `basic_syncbuf` stores character data written to it,
@@ -7735,11 +8062,11 @@ wrapped stream buffer object.
7735
 
7736
  ``` cpp
7737
  basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
7738
  ```
7739
 
7740
- *Effects:* Sets `wrapped` to `obuf`.
7741
 
7742
  *Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
7743
  are `true`.
7744
 
7745
  *Throws:* Nothing unless an exception is thrown by the construction of a
@@ -7810,13 +8137,13 @@ void swap(basic_syncbuf& other);
7810
  ``` cpp
7811
  bool emit();
7812
  ```
7813
 
7814
  *Effects:* Atomically transfers the associated output of `*this` to the
7815
- stream buffer `*wrapped`, so that it appears in the output stream as a
7816
- contiguous sequence of characters. `wrapped->pubsync()` is called if and
7817
- only if a call was made to `sync()` since the most recent call to
7818
  `emit()`, if any.
7819
 
7820
  *Synchronization:* All `emit()` calls transferring characters to the
7821
  same stream buffer object appear to execute in a total order consistent
7822
  with the “happens before” relation [[intro.races]], where each `emit()`
@@ -7825,23 +8152,23 @@ call synchronizes with subsequent `emit()` calls in that total order.
7825
  *Ensures:* On success, the associated output is empty.
7826
 
7827
  *Returns:* `true` if all of the following conditions hold; otherwise
7828
  `false`:
7829
 
7830
- - `wrapped == nullptr` is `false`.
7831
  - All of the characters in the associated output were successfully
7832
  transferred.
7833
- - The call to `wrapped->pubsync()` (if any) succeeded.
7834
 
7835
- *Remarks:* May call member functions of `wrapped` while holding a lock
7836
- uniquely associated with `wrapped`.
7837
 
7838
  ``` cpp
7839
  streambuf_type* get_wrapped() const noexcept;
7840
  ```
7841
 
7842
- *Returns:* `wrapped`.
7843
 
7844
  ``` cpp
7845
  allocator_type get_allocator() const noexcept;
7846
  ```
7847
 
@@ -7850,22 +8177,22 @@ assignment operator.
7850
 
7851
  ``` cpp
7852
  void set_emit_on_sync(bool b) noexcept;
7853
  ```
7854
 
7855
- *Effects:* `emit_on_sync = b`.
7856
 
7857
  #### Overridden virtual functions <a id="syncstream.syncbuf.virtuals">[[syncstream.syncbuf.virtuals]]</a>
7858
 
7859
  ``` cpp
7860
  int sync() override;
7861
  ```
7862
 
7863
  *Effects:* Records that the wrapped stream buffer is to be flushed.
7864
- Then, if `emit_on_sync` is `true`, calls `emit()`.
7865
 
7866
- [*Note 1*: If `emit_on_sync` is `false`, the actual flush is delayed
7867
  until a call to `emit()`. — *end note*]
7868
 
7869
  *Returns:* If `emit()` was called and returned `false`, returns `-1`;
7870
  otherwise `0`.
7871
 
@@ -7887,13 +8214,13 @@ template<class charT, class traits, class Allocator>
7887
  namespace std {
7888
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7889
  class basic_osyncstream : public basic_ostream<charT, traits> {
7890
  public:
7891
  using char_type = charT;
7892
- using int_type = typename traits::int_type;
7893
- using pos_type = typename traits::pos_type;
7894
- using off_type = typename traits::off_type;
7895
  using traits_type = traits;
7896
 
7897
  using allocator_type = Allocator;
7898
  using streambuf_type = basic_streambuf<charT, traits>;
7899
  using syncbuf_type = basic_syncbuf<charT, traits, Allocator>;
@@ -7958,12 +8285,12 @@ In this example, `cout` is not flushed.
7958
 
7959
  ``` cpp
7960
  basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
7961
  ```
7962
 
7963
- *Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
7964
- base class with `basic_ostream<charT, traits>(addressof(sb))`.
7965
 
7966
  [*Note 1*: The member functions of the provided stream buffer can be
7967
  called from `emit()` while a lock is held, which might result in a
7968
  deadlock if used incautiously. — *end note*]
7969
 
@@ -7971,13 +8298,13 @@ deadlock if used incautiously. — *end note*]
7971
 
7972
  ``` cpp
7973
  basic_osyncstream(basic_osyncstream&& other) noexcept;
7974
  ```
7975
 
7976
- *Effects:* Move constructs the base class and `sb` from the
7977
  corresponding subobjects of `other`, and calls
7978
- `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
7979
 
7980
  *Ensures:* The value returned by `get_wrapped()` is the value returned
7981
  by `other.get_wrapped()` prior to calling this constructor.
7982
  `nullptr == other.get_wrapped()` is `true`.
7983
 
@@ -7987,11 +8314,11 @@ by `other.get_wrapped()` prior to calling this constructor.
7987
  void emit();
7988
  ```
7989
 
7990
  *Effects:* Behaves as an unformatted output
7991
  function [[ostream.unformatted]]. After constructing a `sentry` object,
7992
- calls `sb.emit()`. If that call returns `false`, calls
7993
  `setstate(ios_base::badbit)`.
7994
 
7995
  [*Example 1*:
7996
 
7997
  A flush on a `basic_osyncstream` does not flush immediately:
@@ -8030,11 +8357,11 @@ on the underlying stream.
8030
 
8031
  ``` cpp
8032
  streambuf_type* get_wrapped() const noexcept;
8033
  ```
8034
 
8035
- *Returns:* `sb.get_wrapped()`.
8036
 
8037
  [*Example 3*:
8038
 
8039
  Obtaining the wrapped stream buffer with `get_wrapped()` allows wrapping
8040
  it again with an `osyncstream`. For example,
@@ -8387,26 +8714,29 @@ namespace std::filesystem {
8387
 
8388
  path weakly_canonical(const path& p);
8389
  path weakly_canonical(const path& p, error_code& ec);
8390
  }
8391
 
 
 
 
 
8392
  // [fs.path.hash], hash support
8393
- namespace std {
8394
  template<class T> struct hash;
8395
  template<> struct hash<filesystem::path>;
8396
  }
8397
 
8398
  namespace std::ranges {
8399
  template<>
8400
- inline constexpr bool enable_borrowed_range<filesystem::directory_iterator> = true;
8401
  template<>
8402
- inline constexpr bool enable_borrowed_range<filesystem::recursive_directory_iterator> = true;
8403
 
8404
  template<>
8405
- inline constexpr bool enable_view<filesystem::directory_iterator> = true;
8406
  template<>
8407
- inline constexpr bool enable_view<filesystem::recursive_directory_iterator> = true;
8408
  }
8409
  ```
8410
 
8411
  Implementations should ensure that the resolution and range of
8412
  `file_time_type` reflect the operating system dependent resolution and
@@ -8496,12 +8826,12 @@ Pathnames are formatted according to the generic pathname format grammar
8496
 
8497
  *Pathname resolution* is the operating system dependent mechanism for
8498
  resolving a pathname to a particular file in a file hierarchy. There may
8499
  be multiple pathnames that resolve to the same file.
8500
 
8501
- [*Example 1*: POSIX specifies the mechanism in section 4.12, Pathname
8502
- resolution. — *end example*]
8503
 
8504
  ``` cpp
8505
  namespace std::filesystem {
8506
  class path {
8507
  public:
@@ -8584,22 +8914,24 @@ namespace std::filesystem {
8584
 
8585
  template<class EcharT, class traits = char_traits<EcharT>,
8586
  class Allocator = allocator<EcharT>>
8587
  basic_string<EcharT, traits, Allocator>
8588
  string(const Allocator& a = Allocator()) const;
8589
- std::string string() const;
 
8590
  std::wstring wstring() const;
8591
  std::u8string u8string() const;
8592
  std::u16string u16string() const;
8593
  std::u32string u32string() const;
8594
 
8595
  // [fs.path.generic.obs], generic format observers
8596
  template<class EcharT, class traits = char_traits<EcharT>,
8597
  class Allocator = allocator<EcharT>>
8598
  basic_string<EcharT, traits, Allocator>
8599
  generic_string(const Allocator& a = Allocator()) const;
8600
- std::string generic_string() const;
 
8601
  std::wstring generic_wstring() const;
8602
  std::u8string generic_u8string() const;
8603
  std::u16string generic_u16string() const;
8604
  std::u32string generic_u32string() const;
8605
 
@@ -8618,11 +8950,11 @@ namespace std::filesystem {
8618
  path filename() const;
8619
  path stem() const;
8620
  path extension() const;
8621
 
8622
  // [fs.path.query], query
8623
- [[nodiscard]] bool empty() const noexcept;
8624
  bool has_root_name() const;
8625
  bool has_root_directory() const;
8626
  bool has_root_path() const;
8627
  bool has_relative_path() const;
8628
  bool has_parent_path() const;
@@ -8812,12 +9144,12 @@ generic format and is not acceptable to the operating system as a native
8812
  path.
8813
 
8814
  [*Note 2*: Some operating systems have no unambiguous way to
8815
  distinguish between native format and generic format arguments. This is
8816
  by design as it simplifies use for operating systems that do not require
8817
- disambiguation. An implementation for an operating system where
8818
- disambiguation is required is permitted to distinguish between the
8819
  formats. — *end note*]
8820
 
8821
  Pathnames are converted as needed between the generic and native formats
8822
  in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
8823
  mathematical sense be the implementation’s functions that convert
@@ -8903,16 +9235,16 @@ named `Source` shall be one of:
8903
  \[`source.begin()`, `source.end()`).
8904
  - `basic_string_view<EcharT, traits>`. A function argument
8905
  `const Source&` `source` shall have an effective range
8906
  \[`source.begin()`, `source.end()`).
8907
  - A type meeting the *Cpp17InputIterator* requirements that iterates
8908
- over a NTCTS. The value type shall be an encoded character type. A
8909
  function argument `const Source&` `source` shall have an effective
8910
  range \[`source`, `end`) where `end` is the first iterator value with
8911
  an element value equal to `iterator_traits<Source>::value_type()`.
8912
  - A character array that after array-to-pointer decay results in a
8913
- pointer to the start of a NTCTS. The value type shall be an encoded
8914
  character type. A function argument `const Source&` `source` shall
8915
  have an effective range \[`source`, `end`) where `end` is the first
8916
  iterator value with an element value equal to
8917
  `iterator_traits<decay_t<Source>>::value_type()`.
8918
 
@@ -8938,11 +9270,11 @@ Arguments of type `Source` shall not be null pointers.
8938
 
8939
  ``` cpp
8940
  path() noexcept;
8941
  ```
8942
 
8943
- *Ensures:* `empty() == true`.
8944
 
8945
  ``` cpp
8946
  path(const path& p);
8947
  path(path&& p) noexcept;
8948
  ```
@@ -9186,11 +9518,11 @@ template<class InputIterator>
9186
 
9187
  ``` cpp
9188
  void clear() noexcept;
9189
  ```
9190
 
9191
- *Ensures:* `empty() == true`.
9192
 
9193
  ``` cpp
9194
  path& make_preferred();
9195
  ```
9196
 
@@ -9315,24 +9647,22 @@ operator string_type() const;
9315
  ```
9316
 
9317
  *Returns:* `native()`.
9318
 
9319
  ``` cpp
9320
- template<class EcharT, class traits = char_traits<EcharT>,
9321
- class Allocator = allocator<EcharT>>
9322
- basic_string<EcharT, traits, Allocator>
9323
- string(const Allocator& a = Allocator()) const;
9324
  ```
9325
 
9326
  *Returns:* `native()`.
9327
 
9328
  *Remarks:* All memory allocation, including for the return value, shall
9329
  be performed by `a`. Conversion, if any, is specified by
9330
  [[fs.path.cvt]].
9331
 
9332
  ``` cpp
9333
- std::string string() const;
9334
  std::wstring wstring() const;
9335
  std::u8string u8string() const;
9336
  std::u16string u16string() const;
9337
  std::u32string u32string() const;
9338
  ```
@@ -9340,10 +9670,20 @@ std::u32string u32string() const;
9340
  *Returns:* `native()`.
9341
 
9342
  *Remarks:* Conversion, if any, is performed as specified by
9343
  [[fs.path.cvt]].
9344
 
 
 
 
 
 
 
 
 
 
 
9345
  ##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
9346
 
9347
  Generic format observer functions return strings formatted according to
9348
  the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
9349
  character is used as the *directory-separator*.
@@ -9359,34 +9699,42 @@ path("foo\\bar").generic_string()
9359
  returns `"foo/bar"`.
9360
 
9361
  — *end example*]
9362
 
9363
  ``` cpp
9364
- template<class EcharT, class traits = char_traits<EcharT>,
9365
- class Allocator = allocator<EcharT>>
9366
- basic_string<EcharT, traits, Allocator>
9367
- generic_string(const Allocator& a = Allocator()) const;
9368
  ```
9369
 
9370
  *Returns:* The pathname in the generic format.
9371
 
9372
  *Remarks:* All memory allocation, including for the return value, shall
9373
  be performed by `a`. Conversion, if any, is specified by
9374
  [[fs.path.cvt]].
9375
 
9376
  ``` cpp
9377
- std::string generic_string() const;
9378
  std::wstring generic_wstring() const;
9379
  std::u8string generic_u8string() const;
9380
  std::u16string generic_u16string() const;
9381
  std::u32string generic_u32string() const;
9382
  ```
9383
 
9384
  *Returns:* The pathname in the generic format.
9385
 
9386
  *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]].
9387
 
 
 
 
 
 
 
 
 
 
 
9388
  ##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
9389
 
9390
  ``` cpp
9391
  int compare(const path& p) const noexcept;
9392
  ```
@@ -9517,22 +9865,22 @@ path(".bar").extension(); // yields "" and stem() is ".bar"
9517
  path("..bar").extension(); // yields ".bar" and stem() is "."
9518
  ```
9519
 
9520
  — *end example*]
9521
 
9522
- [*Note 3*: The period is included in the return value so that it is
9523
  possible to distinguish between no extension and an empty
9524
  extension. — *end note*]
9525
 
9526
- [*Note 4*: On non-POSIX operating systems, for a path `p`, it is
9527
  possible that `p.stem() + p.extension() == p.filename()` is `false`,
9528
  even though the generic format pathnames are the same. — *end note*]
9529
 
9530
  ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
9531
 
9532
  ``` cpp
9533
- [[nodiscard]] bool empty() const noexcept;
9534
  ```
9535
 
9536
  *Returns:* `true` if the pathname in the generic format is empty,
9537
  otherwise `false`.
9538
 
@@ -9636,11 +9984,11 @@ path lexically_relative(const path& base) const;
9636
  - any *filename* in `relative_path()` or `base.relative_path()` can be
9637
  interpreted as a *root-name*,
9638
 
9639
  returns `path()`.
9640
 
9641
- [*Note 5*: On a POSIX implementation, no *filename* in a
9642
  *relative-path* is acceptable as a *root-name*. — *end note*]
9643
 
9644
  Determines the first mismatched element of `*this` and `base` as if by:
9645
 
9646
  ``` cpp
@@ -9679,28 +10027,28 @@ The above assertions will succeed. On Windows, the returned path’s
9679
  *directory-separator* characters will be backslashes rather than
9680
  slashes, but that does not affect `path` equality.
9681
 
9682
  — *end example*]
9683
 
9684
- [*Note 6*: If symlink following semantics are desired, use the
9685
  operational function `relative()`. — *end note*]
9686
 
9687
- [*Note 7*: If normalization [[fs.path.generic]] is needed to ensure
9688
  consistent matching of elements, apply `lexically_normal()` to `*this`,
9689
  `base`, or both. — *end note*]
9690
 
9691
  ``` cpp
9692
  path lexically_proximate(const path& base) const;
9693
  ```
9694
 
9695
  *Returns:* If the value of `lexically_relative(base)` is not an empty
9696
  path, return it. Otherwise return `*this`.
9697
 
9698
- [*Note 8*: If symlink following semantics are desired, use the
9699
  operational function `proximate()`. — *end note*]
9700
 
9701
- [*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
9702
  consistent matching of elements, apply `lexically_normal()` to `*this`,
9703
  `base`, or both. — *end note*]
9704
 
9705
  #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
9706
 
@@ -9718,13 +10066,13 @@ iterators referring to elements of that object.
9718
 
9719
  For the elements of the pathname in the generic format, the forward
9720
  traversal order is as follows:
9721
 
9722
  - The *root-name* element, if present.
9723
- - The *root-directory* element, if present. \[*Note 1*: The generic
9724
- format is required to ensure lexicographical comparison works
9725
- correctly. — *end note*]
9726
  - Each successive *filename* element, if present.
9727
  - An empty element, if a trailing non-root *directory-separator* is
9728
  present.
9729
 
9730
  The backward traversal order is the reverse of forward traversal.
@@ -9819,10 +10167,79 @@ friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
9819
  friend path operator/(const path& lhs, const path& rhs);
9820
  ```
9821
 
9822
  *Effects:* Equivalent to: `return path(lhs) /= rhs;`
9823
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9824
  #### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
9825
 
9826
  ``` cpp
9827
  template<> struct hash<filesystem::path>;
9828
  ```
@@ -9865,25 +10282,27 @@ with an error.
9865
  filesystem_error(const string& what_arg, error_code ec);
9866
  ```
9867
 
9868
  *Ensures:*
9869
 
9870
- - `code() == ec`,
9871
- - `path1().empty() == true`,
9872
- - `path2().empty() == true`, and
9873
- - `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
 
9874
 
9875
  ``` cpp
9876
  filesystem_error(const string& what_arg, const path& p1, error_code ec);
9877
  ```
9878
 
9879
  *Ensures:*
9880
 
9881
- - `code() == ec`,
9882
  - `path1()` returns a reference to the stored copy of `p1`,
9883
- - `path2().empty() == true`, and
9884
- - `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
 
9885
 
9886
  ``` cpp
9887
  filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
9888
  ```
9889
 
@@ -9940,11 +10359,11 @@ the meanings listed in [[fs.enum.file.type]]. The values of the
9940
  constants are distinct.
9941
 
9942
  **Table: Enum class `file_type`** <a id="fs.enum.file.type">[fs.enum.file.type]</a>
9943
 
9944
  | Constant | Meaning |
9945
- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9946
  | `none` | The type of the file has not been determined or an error occurred while trying to determine the type. |
9947
  | `not_found` | Pseudo-type indicating the file was not found. *The file not being found is not considered an error while determining the type of a file.* |
9948
  | `regular` | Regular file |
9949
  | `directory` | Directory file |
9950
  | `symlink` | Symbolic link file |
@@ -9967,11 +10386,11 @@ exposition; implementations shall provide only a single definition.
9967
  Every other constant in the table represents a distinct bitmask element.
9968
 
9969
  **Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
9970
 
9971
  | Constant | Meaning |
9972
- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
9973
  | `none` | (Default) Error; file already exists. |
9974
  | `skip_existing` | Do not overwrite existing file, do not report an error. |
9975
  | `overwrite_existing` | Overwrite the existing file. |
9976
  | `update_existing` | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for subdirectories} |
9977
  | `recursive` | Recursively copy subdirectories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links} |
@@ -9989,11 +10408,11 @@ specifies bitmask constants used to identify file permissions, with the
9989
  meanings listed in [[fs.enum.perms]].
9990
 
9991
  **Table: Enum class `perms`** <a id="fs.enum.perms">[fs.enum.perms]</a>
9992
 
9993
  | Name | Value (octal) | POSIX macro | Definition or notes |
9994
- | -------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
9995
  | `none` | `0` | | There are no permissions set for the file. |
9996
  | `owner_read` | `0400` | `S_IRUSR` | Read permission, owner |
9997
  | `owner_write` | `0200` | `S_IWUSR` | Write permission, owner |
9998
  | `owner_exec` | `0100` | `S_IXUSR` | Execute/search permission, owner |
9999
  | `owner_all` | `0700` | `S_IRWXU` | Read, write, execute/search by owner;<br> `owner_read | owner_write | owner_exec` |
@@ -10023,11 +10442,11 @@ permissions operations, with the meanings listed in
10023
  `permissions`.
10024
 
10025
  **Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
10026
 
10027
  | Name | Meaning |
10028
- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
10029
  | `replace` | `permissions` shall replace the file's permission bits with `perm` |
10030
  | `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{or} of `perm` and the file's current permission bits. |
10031
  | `remove` | `permissions` shall replace the file's permission bits with the bitwise \logop{and} of the complement of `perm` and the file's current permission bits. |
10032
  | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
10033
 
@@ -10041,11 +10460,11 @@ directory traversal options, with the meanings listed in
10041
  every other constant in the table represents a distinct bitmask element.
10042
 
10043
  **Table: Enum class `directory_options`** <a id="fs.enum.dir.opts">[fs.enum.dir.opts]</a>
10044
 
10045
  | Name | Meaning |
10046
- | -------------------------- | ------------------------------------------------------------------ |
10047
  | `none` | (Default) Skip directory symlinks, permission denied is an error. |
10048
  | `follow_directory_symlink` | Follow rather than skip directory symlinks. |
10049
  | `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
10050
 
10051
 
@@ -10190,12 +10609,11 @@ namespace std::filesystem {
10190
  template<class charT, class traits>
10191
  friend basic_ostream<charT, traits>&
10192
  operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
10193
 
10194
  private:
10195
- filesystem::path pathobject; // exposition only
10196
- friend class directory_iterator; // exposition only
10197
  };
10198
  }
10199
  ```
10200
 
10201
  A `directory_entry` object stores a `path` object and may store
@@ -10206,16 +10624,13 @@ Implementations should store such additional file attributes during
10206
  directory iteration if their values are available and storing the values
10207
  would allow the implementation to eliminate file system accesses by
10208
  `directory_entry` observer functions [[fs.op.funcs]]. Such stored file
10209
  attribute values are said to be *cached*.
10210
 
10211
- [*Note 1*: For purposes of exposition, class `directory_iterator`
10212
- [[fs.class.directory.iterator]] is shown above as a friend of class
10213
- `directory_entry`. Friendship allows the `directory_iterator`
10214
- implementation to cache already available attribute values directly into
10215
- a `directory_entry` object without the cost of an unneeded call to
10216
- `refresh()`. — *end note*]
10217
 
10218
  [*Example 1*:
10219
 
10220
  ``` cpp
10221
  using namespace std::filesystem;
@@ -10264,22 +10679,22 @@ directory_entry(const filesystem::path& p, error_code& ec);
10264
  ``` cpp
10265
  void assign(const filesystem::path& p);
10266
  void assign(const filesystem::path& p, error_code& ec);
10267
  ```
10268
 
10269
- *Effects:* Equivalent to `pathobject = p`, then `refresh()` or
10270
  `refresh(ec)`, respectively. If an error occurs, the values of any
10271
  cached attributes are unspecified.
10272
 
10273
  *Throws:* As specified in  [[fs.err.report]].
10274
 
10275
  ``` cpp
10276
  void replace_filename(const filesystem::path& p);
10277
  void replace_filename(const filesystem::path& p, error_code& ec);
10278
  ```
10279
 
10280
- *Effects:* Equivalent to `pathobject.replace_filename(p)`, then
10281
  `refresh()` or `refresh(ec)`, respectively. If an error occurs, the
10282
  values of any cached attributes are unspecified.
10283
 
10284
  *Throws:* As specified in  [[fs.err.report]].
10285
 
@@ -10309,11 +10724,11 @@ Unqualified function names in the *Returns:* elements of the
10309
  ``` cpp
10310
  const filesystem::path& path() const noexcept;
10311
  operator const filesystem::path&() const noexcept;
10312
  ```
10313
 
10314
- *Returns:* `pathobject`.
10315
 
10316
  ``` cpp
10317
  bool exists() const;
10318
  bool exists(error_code& ec) const noexcept;
10319
  ```
@@ -10457,17 +10872,17 @@ file_status symlink_status(error_code& ec) const noexcept;
10457
 
10458
  ``` cpp
10459
  bool operator==(const directory_entry& rhs) const noexcept;
10460
  ```
10461
 
10462
- *Returns:* `pathobject == rhs.pathobject`.
10463
 
10464
  ``` cpp
10465
  strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
10466
  ```
10467
 
10468
- *Returns:* `pathobject <=> rhs.pathobject`.
10469
 
10470
  #### Inserter <a id="fs.dir.entry.io">[[fs.dir.entry.io]]</a>
10471
 
10472
  ``` cpp
10473
  template<class charT, class traits>
@@ -10558,13 +10973,11 @@ the values of any cached attributes [[fs.class.directory.entry]] in the
10558
  `directory_entry` element returned by `operator*()`.
10559
  `directory_iterator` member functions shall not directly or indirectly
10560
  call any `directory_entry` `refresh` function.
10561
 
10562
  [*Note 2*: The exact mechanism for storing cached attribute values is
10563
- not exposed to users. For exposition, class `directory_iterator` is
10564
- shown in [[fs.class.directory.entry]] as a friend of class
10565
- `directory_entry`. — *end note*]
10566
 
10567
  [*Note 3*: A path obtained by dereferencing a directory iterator might
10568
  not actually exist; it could be a symbolic link to a non-existent file.
10569
  Recursively walking directory trees for purposes of removing and
10570
  renaming entries might invalidate symbolic links that are being
@@ -10896,11 +11309,11 @@ required to be dereferenceable nor to be in the domain of `==`.
10896
  void disable_recursion_pending();
10897
  ```
10898
 
10899
  *Ensures:* `recursion_pending() == false`.
10900
 
10901
- [*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
10902
  recursion into a directory. — *end note*]
10903
 
10904
  #### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
10905
 
10906
  These functions enable use of `recursive_directory_iterator` with
@@ -11026,11 +11439,11 @@ group [[fs.enum.copy.opts]] is set in `options`.
11026
  Effects are then as follows:
11027
 
11028
  - If `f.type()` or `t.type()` is an implementation-defined file
11029
  type [[fs.enum.file.type]], then the effects are
11030
  *implementation-defined*.
11031
- - Otherwise, an error is reported as specified in  [[fs.err.report]] if:
11032
  - `exists(f)` is `false`, or
11033
  - `equivalent(from, to)` is `true`, or
11034
  - `is_other(f) || is_other(t)` is `true`, or
11035
  - `is_directory(f) && is_regular_file(t)` is `true`.
11036
  - Otherwise, if `is_symlink(f)`, then:
@@ -11093,21 +11506,21 @@ applicable.
11093
 
11094
  [*Example 1*:
11095
 
11096
  Given this directory structure:
11097
 
11098
- ``` cpp
11099
  /dir1
11100
  file1
11101
  file2
11102
  dir2
11103
  file3
11104
  ```
11105
 
11106
  Calling `copy("/dir1", "/dir3")` would result in:
11107
 
11108
- ``` cpp
11109
  /dir1
11110
  file1
11111
  file2
11112
  dir2
11113
  file3
@@ -11117,11 +11530,11 @@ Calling `copy("/dir1", "/dir3")` would result in:
11117
  ```
11118
 
11119
  Alternatively, calling `copy("/dir1", "/dir3", copy_options::recursive)`
11120
  would result in:
11121
 
11122
- ``` cpp
11123
  /dir1
11124
  file1
11125
  file2
11126
  dir2
11127
  file3
@@ -11155,22 +11568,22 @@ bool filesystem::copy_file(const path& from, const path& to, copy_options option
11155
  *Preconditions:* At most one element from each option
11156
  group [[fs.enum.copy.opts]] is set in `options`.
11157
 
11158
  *Effects:* As follows:
11159
 
11160
- - Report an error as specified in  [[fs.err.report]] if:
11161
  - `is_regular_file(from)` is `false`, or
11162
  - `exists(to)` is `true` and `is_regular_file(to)` is `false`, or
11163
  - `exists(to)` is `true` and `equivalent(from, to)` is `true`, or
11164
  - `exists(to)` is `true` and
11165
  ``` cpp
11166
  (options & (copy_options::skip_existing |
11167
  copy_options::overwrite_existing |
11168
  copy_options::update_existing)) == copy_options::none
11169
  ```
11170
  - Otherwise, copy the contents and attributes of the file `from`
11171
- resolves to, to the file `to` resolves to, if:
11172
  - `exists(to)` is `false`, or
11173
  - `(options & copy_options::overwrite_existing) != copy_options::none`,
11174
  or
11175
  - `(options & copy_options::update_existing) `` `` != copy_options::none`
11176
  and `from` is more recent than `to`, determined as if by use of the
@@ -11205,11 +11618,11 @@ respectively, where in each case *`function`* is `create_symlink` or
11205
  ``` cpp
11206
  bool filesystem::create_directories(const path& p);
11207
  bool filesystem::create_directories(const path& p, error_code& ec);
11208
  ```
11209
 
11210
- *Effects:* Calls `create_directory()` for each element of `p` that does
11211
  not exist.
11212
 
11213
  *Returns:* `true` if a new directory was created for the directory `p`
11214
  resolves to, otherwise `false`.
11215
 
@@ -11262,21 +11675,21 @@ from directory `existing_p`, otherwise `false`.
11262
  void filesystem::create_directory_symlink(const path& to, const path& new_symlink);
11263
  void filesystem::create_directory_symlink(const path& to, const path& new_symlink,
11264
  error_code& ec) noexcept;
11265
  ```
11266
 
11267
- *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
11268
 
11269
  *Ensures:* `new_symlink` resolves to a symbolic link file that contains
11270
  an unspecified representation of `to`.
11271
 
11272
  *Throws:* As specified in  [[fs.err.report]].
11273
 
11274
  [*Note 1*: Some operating systems require symlink creation to identify
11275
- that the link is to a directory. Thus, `create_symlink()` (instead of
11276
- `create_directory_symlink()`) cannot be used reliably to create
11277
- directory symlinks. — *end note*]
11278
 
11279
  [*Note 2*: Some operating systems do not support symbolic links at all
11280
  or support them only for regular files. Some file systems (such as the
11281
  FAT file system) do not support symbolic links regardless of the
11282
  operating system. — *end note*]
@@ -11287,11 +11700,11 @@ operating system. — *end note*]
11287
  void filesystem::create_hard_link(const path& to, const path& new_hard_link);
11288
  void filesystem::create_hard_link(const path& to, const path& new_hard_link,
11289
  error_code& ec) noexcept;
11290
  ```
11291
 
11292
- *Effects:* Establishes the postcondition, as if by POSIX `link()`.
11293
 
11294
  *Ensures:*
11295
 
11296
  - `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
11297
  - The contents of the file or directory `to` resolves to are unchanged.
@@ -11310,11 +11723,11 @@ file. — *end note*]
11310
  void filesystem::create_symlink(const path& to, const path& new_symlink);
11311
  void filesystem::create_symlink(const path& to, const path& new_symlink,
11312
  error_code& ec) noexcept;
11313
  ```
11314
 
11315
- *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
11316
 
11317
  *Ensures:* `new_symlink` resolves to a symbolic link file that contains
11318
  an unspecified representation of `to`.
11319
 
11320
  *Throws:* As specified in  [[fs.err.report]].
@@ -11330,39 +11743,35 @@ operating system. — *end note*]
11330
  path filesystem::current_path();
11331
  path filesystem::current_path(error_code& ec);
11332
  ```
11333
 
11334
  *Returns:* The absolute path of the current working directory, whose
11335
- pathname in the native format is obtained as if by POSIX `getcwd()`. The
11336
  signature with argument `ec` returns `path()` if an error occurs.
11337
 
11338
  *Throws:* As specified in  [[fs.err.report]].
11339
 
11340
  *Remarks:* The current working directory is the directory, associated
11341
  with the process, that is used as the starting location in pathname
11342
  resolution for relative paths.
11343
 
11344
- [*Note 1*: The `current_path()` name was chosen to emphasize that the
11345
- returned value is a path, not just a single directory
11346
- name. — *end note*]
11347
-
11348
- [*Note 2*: The current path as returned by many operating systems is a
11349
  dangerous global variable and can be changed unexpectedly by third-party
11350
  or system library functions, or by another thread. — *end note*]
11351
 
11352
  ``` cpp
11353
  void filesystem::current_path(const path& p);
11354
  void filesystem::current_path(const path& p, error_code& ec) noexcept;
11355
  ```
11356
 
11357
- *Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
11358
 
11359
  *Ensures:* `equivalent(p, current_path())`.
11360
 
11361
  *Throws:* As specified in  [[fs.err.report]].
11362
 
11363
- [*Note 3*: The current path for many operating systems is a dangerous
11364
  global state and can be changed unexpectedly by third-party or system
11365
  library functions, or by another thread. — *end note*]
11366
 
11367
  #### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
11368
 
@@ -11373,11 +11782,11 @@ bool filesystem::equivalent(const path& p1, const path& p2, error_code& ec) noex
11373
 
11374
  Two paths are considered to resolve to the same file system entity if
11375
  two candidate entities reside on the same device at the same location.
11376
 
11377
  [*Note 1*: On POSIX platforms, this is determined as if by the values
11378
- of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
11379
  having equal `st_dev` values and equal `st_ino` values. — *end note*]
11380
 
11381
  *Returns:* `true`, if `p1` and `p2` resolve to the same file system
11382
  entity, otherwise `false`. The signature with argument `ec` returns
11383
  `false` if an error occurs.
@@ -11421,11 +11830,11 @@ reported [[fs.err.report]].
11421
 
11422
  *Returns:*
11423
 
11424
  - If `is_regular_file(p)`, the size in bytes of the file `p` resolves
11425
  to, determined as if by the value of the POSIX `stat` class member
11426
- `st_size` obtained as if by POSIX `stat()`.
11427
  - Otherwise, the result is *implementation-defined*.
11428
 
11429
  The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
11430
  an error occurs.
11431
 
@@ -11642,11 +12051,11 @@ file_time_type filesystem::last_write_time(const path& p);
11642
  file_time_type filesystem::last_write_time(const path& p, error_code& ec) noexcept;
11643
  ```
11644
 
11645
  *Returns:* The time of last data modification of `p`, determined as if
11646
  by the value of the POSIX `stat` class member `st_mtime` obtained as if
11647
- by POSIX `stat()`. The signature with argument `ec` returns
11648
  `file_time_type::min()` if an error occurs.
11649
 
11650
  *Throws:* As specified in  [[fs.err.report]].
11651
 
11652
  ``` cpp
@@ -11654,11 +12063,11 @@ void filesystem::last_write_time(const path& p, file_time_type new_time);
11654
  void filesystem::last_write_time(const path& p, file_time_type new_time,
11655
  error_code& ec) noexcept;
11656
  ```
11657
 
11658
  *Effects:* Sets the time of last data modification of the file resolved
11659
- to by `p` to `new_time`, as if by POSIX `futimens()`.
11660
 
11661
  *Throws:* As specified in  [[fs.err.report]].
11662
 
11663
  [*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
11664
  specified because it does not necessarily hold for file systems with
@@ -11676,11 +12085,11 @@ void filesystem::permissions(const path& p, perms prms, perm_options opts, error
11676
  `add`, or `remove` is present in `opts`.
11677
 
11678
  *Effects:* Applies the action specified by `opts` to the file `p`
11679
  resolves to, or to file `p` itself if `p` is a symbolic link and
11680
  `perm_options::nofollow` is set in `opts`. The action is applied as if
11681
- by POSIX `fchmodat()`.
11682
 
11683
  [*Note 1*: Conceptually permissions are viewed as bits, but the actual
11684
  implementation can use some other mechanism. — *end note*]
11685
 
11686
  *Throws:* As specified in  [[fs.err.report]].
@@ -11773,19 +12182,20 @@ or `path()` at the first error occurrence, if any.
11773
  bool filesystem::remove(const path& p);
11774
  bool filesystem::remove(const path& p, error_code& ec) noexcept;
11775
  ```
11776
 
11777
  *Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
11778
- as if by POSIX `remove()`.
11779
 
11780
  [*Note 1*: A symbolic link is itself removed, rather than the file it
11781
  resolves to. — *end note*]
11782
 
11783
  *Ensures:* `exists(symlink_status(p))` is `false`.
11784
 
11785
- *Returns:* `false` if `p` did not exist, otherwise `true`. The signature
11786
- with argument `ec` returns `false` if an error occurs.
 
11787
 
11788
  *Throws:* As specified in  [[fs.err.report]].
11789
 
11790
  #### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
11791
 
@@ -11793,11 +12203,11 @@ with argument `ec` returns `false` if an error occurs.
11793
  uintmax_t filesystem::remove_all(const path& p);
11794
  uintmax_t filesystem::remove_all(const path& p, error_code& ec);
11795
  ```
11796
 
11797
  *Effects:* Recursively deletes the contents of `p` if it exists, then
11798
- deletes file `p` itself, as if by POSIX `remove()`.
11799
 
11800
  [*Note 1*: A symbolic link is itself removed, rather than the file it
11801
  resolves to. — *end note*]
11802
 
11803
  *Ensures:* `exists(symlink_status(p))` is `false`.
@@ -11812,11 +12222,11 @@ returns `static_cast< uintmax_t>(-1)` if an error occurs.
11812
  ``` cpp
11813
  void filesystem::rename(const path& old_p, const path& new_p);
11814
  void filesystem::rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
11815
  ```
11816
 
11817
- *Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
11818
 
11819
  [*Note 1*:
11820
 
11821
  - If `old_p` and `new_p` resolve to the same existing file, no action is
11822
  taken.
@@ -11839,11 +12249,11 @@ A symbolic link is itself renamed, rather than the file it resolves to.
11839
  void filesystem::resize_file(const path& p, uintmax_t new_size);
11840
  void filesystem::resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
11841
  ```
11842
 
11843
  *Effects:* Causes the size that would be returned by `file_size(p)` to
11844
- be equal to `new_size`, as if by POSIX `truncate()`.
11845
 
11846
  *Throws:* As specified in  [[fs.err.report]].
11847
 
11848
  #### Space <a id="fs.op.space">[[fs.op.space]]</a>
11849
 
@@ -11872,11 +12282,11 @@ system dependent.
11872
 
11873
  ``` cpp
11874
  file_status filesystem::status(const path& p);
11875
  ```
11876
 
11877
- *Effects:* As if:
11878
 
11879
  ``` cpp
11880
  error_code ec;
11881
  file_status result = status(p, ec);
11882
  if (result.type() == file_type::none)
@@ -11895,17 +12305,17 @@ cause an exception to be thrown. — *end note*]
11895
  ``` cpp
11896
  file_status filesystem::status(const path& p, error_code& ec) noexcept;
11897
  ```
11898
 
11899
  *Effects:* If possible, determines the attributes of the file `p`
11900
- resolves to, as if by using POSIX `stat()` to obtain a POSIX
11901
  `struct stat`. If, during attribute determination, the underlying file
11902
  system API reports an error, sets `ec` to indicate the specific error
11903
  reported. Otherwise, `ec.clear()`.
11904
 
11905
  [*Note 2*: This allows users to inspect the specifics of underlying API
11906
- errors even when the value returned by `status()` is not
11907
  `file_status(file_type::none)`. — *end note*]
11908
 
11909
  Let `prms` denote the result of `(m & perms::mask)`, where `m` is
11910
  determined as if by converting the `st_mode` member of the obtained
11911
  `struct stat` to the type `perms`.
@@ -11968,19 +12378,19 @@ bool filesystem::status_known(file_status s) noexcept;
11968
  ``` cpp
11969
  file_status filesystem::symlink_status(const path& p);
11970
  file_status filesystem::symlink_status(const path& p, error_code& ec) noexcept;
11971
  ```
11972
 
11973
- *Effects:* Same as `status()`, above, except that the attributes of `p`
11974
- are determined as if by using POSIX `lstat()` to obtain a POSIX
11975
  `struct stat`.
11976
 
11977
  Let `prms` denote the result of `(m & perms::mask)`, where `m` is
11978
  determined as if by converting the `st_mode` member of the obtained
11979
  `struct stat` to the type `perms`.
11980
 
11981
- *Returns:* Same as `status()`, above, except that if the attributes
11982
  indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
11983
  `file_status(file_type::symlink, prms)`. The signature with argument
11984
  `ec` returns `file_status(file_type::none)` if an error occurs.
11985
 
11986
  *Throws:* As specified in  [[fs.err.report]].
@@ -12018,16 +12428,16 @@ path filesystem::weakly_canonical(const path& p);
12018
  path filesystem::weakly_canonical(const path& p, error_code& ec);
12019
  ```
12020
 
12021
  *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
12022
  determine existence, return a path composed by `operator/=` from the
12023
- result of calling `canonical()` with a path argument composed of the
12024
  leading elements of `p` that exist, if any, followed by the elements of
12025
- `p` that do not exist, if any. For the first form, `canonical()` is
12026
- called without an `error_code` argument. For the second form,
12027
- `canonical()` is called with `ec` as an `error_code` argument, and
12028
- `path()` is returned at the first error occurrence, if any.
12029
 
12030
  *Ensures:* The returned path is in normal form [[fs.path.generic]].
12031
 
12032
  *Returns:* `p` with symlinks resolved and the result
12033
  normalized [[fs.path.generic]].
@@ -12037,10 +12447,12 @@ normalized [[fs.path.generic]].
12037
  ## C library files <a id="c.files">[[c.files]]</a>
12038
 
12039
  ### Header `<cstdio>` synopsis <a id="cstdio.syn">[[cstdio.syn]]</a>
12040
 
12041
  ``` cpp
 
 
12042
  namespace std {
12043
  using size_t = see [support.types.layout];
12044
  using FILE = see below;
12045
  using fpos_t = see below;
12046
  }
@@ -12051,10 +12463,11 @@ namespace std {
12051
  #define _IONBF see below
12052
  #define BUFSIZ see below
12053
  #define EOF see below
12054
  #define FOPEN_MAX see below
12055
  #define FILENAME_MAX see below
 
12056
  #define L_tmpnam see below
12057
  #define SEEK_CUR see below
12058
  #define SEEK_END see below
12059
  #define SEEK_SET see below
12060
  #define TMP_MAX see below
@@ -12112,15 +12525,19 @@ namespace std {
12112
  ```
12113
 
12114
  The contents and meaning of the header `<cstdio>` are the same as the C
12115
  standard library header `<stdio.h>`.
12116
 
 
 
 
 
12117
  Calls to the function `tmpnam` with an argument that is a null pointer
12118
  value may introduce a data race [[res.on.data.races]] with other calls
12119
  to `tmpnam` with an argument that is a null pointer value.
12120
 
12121
- See also: ISO C 7.21
12122
 
12123
  ### Header `<cinttypes>` synopsis <a id="cinttypes.syn">[[cinttypes.syn]]</a>
12124
 
12125
  ``` cpp
12126
  #include <cstdint> // see [cstdint.syn]
@@ -12137,75 +12554,89 @@ namespace std {
12137
 
12138
  constexpr intmax_t abs(intmax_t); // optional, see below
12139
  constexpr imaxdiv_t div(intmax_t, intmax_t); // optional, see below
12140
  }
12141
 
 
 
12142
  #define PRIdN see below
12143
  #define PRIiN see below
12144
  #define PRIoN see below
12145
  #define PRIuN see below
12146
  #define PRIxN see below
12147
  #define PRIXN see below
 
 
12148
  #define SCNdN see below
12149
  #define SCNiN see below
12150
  #define SCNoN see below
12151
  #define SCNuN see below
12152
  #define SCNxN see below
 
12153
  #define PRIdLEASTN see below
12154
  #define PRIiLEASTN see below
12155
  #define PRIoLEASTN see below
12156
  #define PRIuLEASTN see below
12157
  #define PRIxLEASTN see below
12158
  #define PRIXLEASTN see below
 
 
12159
  #define SCNdLEASTN see below
12160
  #define SCNiLEASTN see below
12161
  #define SCNoLEASTN see below
12162
  #define SCNuLEASTN see below
12163
  #define SCNxLEASTN see below
 
12164
  #define PRIdFASTN see below
12165
  #define PRIiFASTN see below
12166
  #define PRIoFASTN see below
12167
  #define PRIuFASTN see below
12168
  #define PRIxFASTN see below
12169
  #define PRIXFASTN see below
 
 
12170
  #define SCNdFASTN see below
12171
  #define SCNiFASTN see below
12172
  #define SCNoFASTN see below
12173
  #define SCNuFASTN see below
12174
  #define SCNxFASTN see below
 
12175
  #define PRIdMAX see below
12176
  #define PRIiMAX see below
12177
  #define PRIoMAX see below
12178
  #define PRIuMAX see below
12179
  #define PRIxMAX see below
12180
  #define PRIXMAX see below
 
 
12181
  #define SCNdMAX see below
12182
  #define SCNiMAX see below
12183
  #define SCNoMAX see below
12184
  #define SCNuMAX see below
12185
  #define SCNxMAX see below
 
12186
  #define PRIdPTR see below
12187
  #define PRIiPTR see below
12188
  #define PRIoPTR see below
12189
  #define PRIuPTR see below
12190
  #define PRIxPTR see below
12191
  #define PRIXPTR see below
 
 
12192
  #define SCNdPTR see below
12193
  #define SCNiPTR see below
12194
  #define SCNoPTR see below
12195
  #define SCNuPTR see below
12196
  #define SCNxPTR see below
 
12197
  ```
12198
 
12199
  The contents and meaning of the header `<cinttypes>` are the same as the
12200
  C standard library header `<inttypes.h>`, with the following changes:
12201
 
12202
  - The header `<cinttypes>` includes the header `<cstdint>` instead of
12203
  `<stdint.h>`, and
12204
- - `intmax_t` and `uintmax_t` are not required to be able to represent
12205
- all values of extended integer types wider than `long long` and
12206
- `unsigned long long`, respectively, and
12207
  - if and only if the type `intmax_t` designates an extended integer type
12208
  [[basic.fundamental]], the following function signatures are added:
12209
  ``` cpp
12210
  constexpr intmax_t abs(intmax_t);
12211
  constexpr imaxdiv_t div(intmax_t, intmax_t);
@@ -12220,11 +12651,13 @@ See also: ISO C 7.8
12220
  Each of the `PRI` macros listed in this subclause is defined if and only
12221
  if the implementation defines the corresponding *typedef-name* in 
12222
  [[cstdint.syn]]. Each of the `SCN` macros listed in this subclause is
12223
  defined if and only if the implementation defines the corresponding
12224
  *typedef-name* in  [[cstdint.syn]] and has a suitable `fscanf` length
12225
- modifier for the type.
 
 
12226
 
12227
  <!-- Link reference definitions -->
12228
  [adjustfield.manip]: #adjustfield.manip
12229
  [allocator.requirements.general]: library.md#allocator.requirements.general
12230
  [basefield.manip]: #basefield.manip
@@ -12239,22 +12672,24 @@ modifier for the type.
12239
  [c.files]: #c.files
12240
  [char.traits]: strings.md#char.traits
12241
  [char.traits.specializations]: strings.md#char.traits.specializations
12242
  [character.seq]: library.md#character.seq
12243
  [cinttypes.syn]: #cinttypes.syn
12244
- [container.requirements.general]: containers.md#container.requirements.general
12245
  [cpp17.copyassignable]: #cpp17.copyassignable
12246
  [cpp17.copyconstructible]: #cpp17.copyconstructible
12247
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
12248
  [cpp17.destructible]: #cpp17.destructible
12249
  [cpp17.equalitycomparable]: #cpp17.equalitycomparable
12250
  [cstdint.syn]: support.md#cstdint.syn
12251
  [cstdio.syn]: #cstdio.syn
 
12252
  [defns.ntcts]: intro.md#defns.ntcts
12253
  [enumerated.types]: library.md#enumerated.types
12254
  [error.reporting]: #error.reporting
12255
  [ext.manip]: #ext.manip
 
12256
  [file.streams]: #file.streams
12257
  [filebuf]: #filebuf
12258
  [filebuf.assign]: #filebuf.assign
12259
  [filebuf.cons]: #filebuf.cons
12260
  [filebuf.general]: #filebuf.general
@@ -12264,12 +12699,16 @@ modifier for the type.
12264
  [filebuf.virtuals]: #filebuf.virtuals
12265
  [filesystems]: #filesystems
12266
  [floatfield.manip]: #floatfield.manip
12267
  [fmtflags.manip]: #fmtflags.manip
12268
  [fmtflags.state]: #fmtflags.state
12269
- [format.err.report]: utilities.md#format.err.report
 
 
 
12270
  [fpos]: #fpos
 
12271
  [fpos.members]: #fpos.members
12272
  [fpos.operations]: #fpos.operations
12273
  [fs.class.directory.entry]: #fs.class.directory.entry
12274
  [fs.class.directory.entry.general]: #fs.class.directory.entry.general
12275
  [fs.class.directory.iterator]: #fs.class.directory.iterator
@@ -12353,10 +12792,13 @@ modifier for the type.
12353
  [fs.path.concat]: #fs.path.concat
12354
  [fs.path.construct]: #fs.path.construct
12355
  [fs.path.cvt]: #fs.path.cvt
12356
  [fs.path.decompose]: #fs.path.decompose
12357
  [fs.path.fmt.cvt]: #fs.path.fmt.cvt
 
 
 
12358
  [fs.path.gen]: #fs.path.gen
12359
  [fs.path.generic]: #fs.path.generic
12360
  [fs.path.generic.obs]: #fs.path.generic.obs
12361
  [fs.path.hash]: #fs.path.hash
12362
  [fs.path.io]: #fs.path.io
@@ -12386,10 +12828,11 @@ modifier for the type.
12386
  [input.iterators]: iterators.md#input.iterators
12387
  [input.output]: #input.output
12388
  [input.output.general]: #input.output.general
12389
  [input.streams]: #input.streams
12390
  [input.streams.general]: #input.streams.general
 
12391
  [intro.multithread]: basic.md#intro.multithread
12392
  [intro.races]: basic.md#intro.races
12393
  [iomanip.syn]: #iomanip.syn
12394
  [ios]: #ios
12395
  [ios.base]: #ios.base
@@ -12450,12 +12893,12 @@ modifier for the type.
12450
  [istringstream.cons]: #istringstream.cons
12451
  [istringstream.general]: #istringstream.general
12452
  [istringstream.members]: #istringstream.members
12453
  [istringstream.swap]: #istringstream.swap
12454
  [lex.charset]: lex.md#lex.charset
12455
- [locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
12456
- [locale.num.get]: localization.md#locale.num.get
12457
  [namespace.std]: library.md#namespace.std
12458
  [narrow.stream.objects]: #narrow.stream.objects
12459
  [numeric.limits]: support.md#numeric.limits
12460
  [ofstream]: #ofstream
12461
  [ofstream.cons]: #ofstream.cons
@@ -12570,12 +13013,12 @@ modifier for the type.
12570
  [views.span]: containers.md#views.span
12571
  [wide.stream.objects]: #wide.stream.objects
12572
 
12573
  [^1]: Typically `long long`.
12574
 
12575
- [^2]: Most places where `streamsize` is used would use `size_t` in ISO
12576
- C, or `ssize_t` in POSIX.
12577
 
12578
  [^3]: It is the implementation’s responsibility to implement headers so
12579
  that including `<iosfwd>` and other headers does not violate the
12580
  rules about multiple occurrences of default arguments.
12581
 
@@ -12587,11 +13030,11 @@ modifier for the type.
12587
  mixed arbitrarily with operations on the corresponding stdio stream.
12588
  In practical terms, synchronization usually means that a standard
12589
  iostream object and a standard stdio object share a buffer.
12590
 
12591
  [^6]: An implementation is free to implement both the integer array
12592
- pointed at by `iarray` and the pointer array pointed at by `parray`
12593
  as sparse data structures, possibly with a one-element cache for
12594
  each.
12595
 
12596
  [^7]: For example, because it cannot allocate space.
12597
 
@@ -12624,11 +13067,11 @@ modifier for the type.
12624
  ways to implement `xsgetn()` and `xsputn()` by overriding these
12625
  definitions from the base class.
12626
 
12627
  [^16]: That is, for each class derived from a specialization of
12628
  `basic_streambuf` in this Clause [[stringbuf]], [[filebuf]],
12629
- a specification of how consuming a character effects the associated
12630
  output sequence is given. There is no requirement on a
12631
  program-defined class.
12632
 
12633
  [^17]: Typically, `overflow` returns `c` to indicate success, except
12634
  when `traits::eq_int_type(c, traits::eof())` returns `true`, in
 
71
  `pos_type` denotes `fpos<mbstate_t>`, and `off_type` denotes
72
  `streamoff`. — *end note*]
73
 
74
  In the classes of [[input.output]], a template parameter with name
75
  `charT` represents a member of the set of types containing `char`,
76
+ `wchar_t`, and any other *implementation-defined* character container
77
+ types [[defns.character.container]] that meet the requirements for a
78
+ character on which any of the iostream components can be instantiated.
79
 
80
  ### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
81
 
82
  Concurrent access to a stream object
83
  [[string.streams]], [[file.streams]], stream buffer object
 
117
  template<class charT, class traits = char_traits<charT>>
118
  class basic_ostream;
119
  template<class charT, class traits = char_traits<charT>>
120
  class basic_iostream;
121
 
122
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
123
  class basic_stringbuf;
124
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
125
  class basic_istringstream;
126
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
127
  class basic_ostringstream;
128
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
129
  class basic_stringstream;
130
 
131
  template<class charT, class traits = char_traits<charT>>
132
  class basic_spanbuf;
133
  template<class charT, class traits = char_traits<charT>>
 
144
  template<class charT, class traits = char_traits<charT>>
145
  class basic_ofstream;
146
  template<class charT, class traits = char_traits<charT>>
147
  class basic_fstream;
148
 
149
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
150
  class basic_syncbuf;
151
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
152
  class basic_osyncstream;
153
 
154
  template<class charT, class traits = char_traits<charT>>
155
  class istreambuf_iterator;
156
  template<class charT, class traits = char_traits<charT>>
 
288
  In this Clause, the type name `FILE` refers to the type `FILE` declared
289
  in `<cstdio>`.
290
 
291
  The header `<iostream>` declares objects that associate objects with the
292
  standard C streams provided for by the functions declared in `<cstdio>`,
293
+ and includes all the headers necessary to use these objects. The dynamic
294
+ types of the stream buffers initially associated with these objects are
295
+ unspecified, but they have the behavior specified for
296
+ `std::basic_filebuf<char>` or `std::basic_filebuf<wchar_t>`.
297
 
298
  The objects are constructed and the associations are established at some
299
  time prior to or during the first time an object of class
300
  `ios_base::Init` is constructed, and in any case before the body of
301
  `main` [[basic.start.main]] begins execution. The objects are not
 
327
  not result in a data race [[intro.multithread]].
328
 
329
  [*Note 2*: Unsynchronized concurrent use of these objects and streams
330
  by multiple threads can result in interleaved characters. — *end note*]
331
 
332
+ See also: ISO C 7.23.2
333
 
334
  ### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
335
 
336
  ``` cpp
337
  istream cin;
 
413
 
414
  ``` cpp
415
  #include <iosfwd> // see [iosfwd.syn]
416
 
417
  namespace std {
418
+ // [stream.types], types
419
  using streamoff = implementation-defined;
420
  using streamsize = implementation-defined;
421
+ // [fpos], class template fpos
422
  template<class stateT> class fpos;
423
 
424
+ // [ios.base], class ios_base
425
  class ios_base;
426
+ // [ios], class template basic_ios
427
  template<class charT, class traits = char_traits<charT>>
428
  class basic_ios;
429
 
430
  // [std.ios.manip], manipulators
431
  ios_base& boolalpha (ios_base& str);
 
627
  An implementation is permitted to define `ios_base::failure` as a
628
  synonym for a class with equivalent functionality to class
629
  `ios_base::failure` shown in this subclause.
630
 
631
  [*Note 1*: When `ios_base::failure` is a synonym for another type, that
632
+ type needs to provide a nested type `failure` to emulate the
633
  injected-class-name. — *end note*]
634
 
635
  The class `failure` defines the base class for the types of all objects
636
  thrown as exceptions, by functions in the iostreams library, to report
637
  errors detected during stream buffer operations.
 
771
  public:
772
  Init();
773
  Init(const Init&) = default;
774
  ~Init();
775
  Init& operator=(const Init&) = default;
 
 
 
776
  };
777
  }
778
  ```
779
 
780
  The class `Init` describes an object whose construction ensures the
781
  construction of the eight objects declared in `<iostream>`
782
  [[iostream.objects]] that associate file stream buffers with the
783
  standard C streams provided for by the functions declared in `<cstdio>`.
784
 
 
 
 
 
 
785
  ``` cpp
786
  Init();
787
  ```
788
 
789
  *Effects:* Constructs and initializes the objects `cin`, `cout`, `cerr`,
 
950
 
951
  ``` cpp
952
  static int xalloc();
953
  ```
954
 
955
+ *Returns:* *index* `++`.
956
 
957
  *Remarks:* Concurrent access to this function by multiple threads does
958
  not result in a data race [[intro.multithread]].
959
 
960
  ``` cpp
961
  long& iword(int idx);
962
  ```
963
 
964
  *Preconditions:* `idx` is a value obtained by a call to `xalloc`.
965
 
966
+ *Effects:* If *iarray* is a null pointer, allocates an array of `long`
967
  of unspecified size and stores a pointer to its first element in
968
+ *iarray*. The function then extends the array pointed at by *iarray* as
969
+ necessary to include the element *`iarray`*`[idx]`. Each newly allocated
970
  element of the array is initialized to zero. The reference returned is
971
  invalid after any other operation on the object.[^6]
972
 
973
  However, the value of the storage referred to is retained, so that until
974
  the next call to `copyfmt`, calling `iword` with the same index yields
 
977
  and `*this` is a base class subobject of a `basic_ios<>` object or
978
  subobject, the effect is equivalent to calling
979
  `basic_ios<>::setstate(badbit)` on the derived object (which may throw
980
  `failure`).
981
 
982
+ *Returns:* On success *`iarray`*`[idx]`. On failure, a valid `long&`
983
  initialized to 0.
984
 
985
  ``` cpp
986
  void*& pword(int idx);
987
  ```
988
 
989
  *Preconditions:* `idx` is a value obtained by a call to `xalloc`.
990
 
991
+ *Effects:* If *parray* is a null pointer, allocates an array of pointers
992
  to `void` of unspecified size and stores a pointer to its first element
993
+ in *parray*. The function then extends the array pointed at by *parray*
994
+ as necessary to include the element *`parray`*`[idx]`. Each newly
995
+ allocated element of the array is initialized to a null pointer. The
996
+ reference returned is invalid after any other operation on the object.
997
+ However, the value of the storage referred to is retained, so that until
998
+ the next call to `copyfmt`, calling `pword` with the same index yields
999
+ another reference to the same value. If the function fails[^8]
1000
 
1001
  and `*this` is a base class subobject of a `basic_ios<>` object or
1002
  subobject, the effect is equivalent to calling
1003
  `basic_ios<>::setstate(badbit)` on the derived object (which may throw
1004
  `failure`).
 
1047
  that any `ios_base` member function called from within `fn` has
1048
  well-defined results. Then, any memory obtained is deallocated.
1049
 
1050
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
1051
 
1052
+ #### General <a id="fpos.general">[[fpos.general]]</a>
1053
+
1054
  ``` cpp
1055
  namespace std {
1056
  template<class stateT> class fpos {
1057
  public:
1058
  // [fpos.members], members
 
1069
 
1070
  ``` cpp
1071
  void state(stateT s);
1072
  ```
1073
 
1074
+ *Effects:* Assigns `s` to *st*.
1075
 
1076
  ``` cpp
1077
  stateT state() const;
1078
  ```
1079
 
1080
+ *Returns:* Current value of *st*.
1081
 
1082
  #### Requirements <a id="fpos.operations">[[fpos.operations]]</a>
1083
 
1084
  An `fpos` type specifies file position information. It holds a state
1085
  object whose type is equal to the template parameter `stateT`. Type
 
1120
  namespace std {
1121
  template<class charT, class traits = char_traits<charT>>
1122
  class basic_ios : public ios_base {
1123
  public:
1124
  using char_type = charT;
1125
+ using int_type = traits::int_type;
1126
+ using pos_type = traits::pos_type;
1127
+ using off_type = traits::off_type;
1128
  using traits_type = traits;
1129
 
1130
  // [iostate.flags], flags functions
1131
  explicit operator bool() const;
1132
  bool operator!() const;
 
1272
 
1273
  ``` cpp
1274
  char narrow(char_type c, char dfault) const;
1275
  ```
1276
 
1277
+ *Returns:* `use_facet<ctype<char_type>>(getloc()).narrow(c, dfault)`.
1278
 
1279
  ``` cpp
1280
  char_type widen(char c) const;
1281
  ```
1282
 
1283
+ *Returns:* `use_facet<ctype<char_type>>(getloc()).widen(c)`.
1284
 
1285
  ``` cpp
1286
  char_type fill() const;
1287
  ```
1288
 
 
1418
 
1419
  ``` cpp
1420
  bool good() const;
1421
  ```
1422
 
1423
+ *Returns:* `rdstate() == 0`.
1424
 
1425
  ``` cpp
1426
  bool eof() const;
1427
  ```
1428
 
 
1704
 
1705
  ### Header `<streambuf>` synopsis <a id="streambuf.syn">[[streambuf.syn]]</a>
1706
 
1707
  ``` cpp
1708
  namespace std {
1709
+ // [streambuf], class template basic_streambuf
1710
  template<class charT, class traits = char_traits<charT>>
1711
  class basic_streambuf;
1712
  using streambuf = basic_streambuf<char>;
1713
  using wstreambuf = basic_streambuf<wchar_t>;
1714
  }
 
1776
  namespace std {
1777
  template<class charT, class traits = char_traits<charT>>
1778
  class basic_streambuf {
1779
  public:
1780
  using char_type = charT;
1781
+ using int_type = traits::int_type;
1782
+ using pos_type = traits::pos_type;
1783
+ using off_type = traits::off_type;
1784
  using traits_type = traits;
1785
 
1786
  virtual ~basic_streambuf();
1787
 
1788
  // [streambuf.locales], locales
 
1864
  virtual int_type overflow(int_type c = traits::eof());
1865
  };
1866
  }
1867
  ```
1868
 
1869
+ The class template `basic_streambuf` serves as a base class for deriving
1870
+ various *stream buffers* whose objects each control two *character
1871
+ sequences*:
1872
 
1873
  - a character *input sequence*;
1874
  - a character *output sequence*.
1875
 
1876
  #### Constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
 
2093
 
2094
  ``` cpp
2095
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
2096
  ```
2097
 
2098
+ *Preconditions:* \[`gbeg`, `gnext`), \[`gbeg`, `gend`), and \[`gnext`,
2099
+ `gend`) are all valid ranges.
2100
+
2101
  *Ensures:* `gbeg == eback()`, `gnext == gptr()`, and `gend == egptr()`
2102
  are all `true`.
2103
 
2104
  ##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
2105
 
 
2129
 
2130
  ``` cpp
2131
  void setp(char_type* pbeg, char_type* pend);
2132
  ```
2133
 
2134
+ *Preconditions:* \[`pbeg`, `pend`) is a valid range.
2135
+
2136
  *Ensures:* `pbeg == pbase()`, `pbeg == pptr()`, and `pend == epptr()`
2137
  are all `true`.
2138
 
2139
  #### Virtual functions <a id="streambuf.virtuals">[[streambuf.virtuals]]</a>
2140
 
 
2390
 
2391
  ### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
2392
 
2393
  ``` cpp
2394
  namespace std {
2395
+ // [istream], class template basic_istream
2396
  template<class charT, class traits = char_traits<charT>>
2397
  class basic_istream;
2398
 
2399
  using istream = basic_istream<char>;
2400
  using wistream = basic_istream<wchar_t>;
2401
 
2402
+ // [iostreamclass], class template basic_iostream
2403
  template<class charT, class traits = char_traits<charT>>
2404
  class basic_iostream;
2405
 
2406
  using iostream = basic_iostream<char>;
2407
  using wiostream = basic_iostream<wchar_t>;
2408
 
2409
+ // [istream.manip], standard basic_istream manipulators
2410
  template<class charT, class traits>
2411
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
2412
 
2413
+ // [istream.rvalue], rvalue stream extraction
2414
  template<class Istream, class T>
2415
  Istream&& operator>>(Istream&& is, T&& x);
2416
  }
2417
  ```
2418
 
2419
  ### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
2420
 
2421
  ``` cpp
2422
  namespace std {
2423
+ // [ostream], class template basic_ostream
2424
  template<class charT, class traits = char_traits<charT>>
2425
  class basic_ostream;
2426
 
2427
  using ostream = basic_ostream<char>;
2428
  using wostream = basic_ostream<wchar_t>;
2429
 
2430
+ // [ostream.manip], standard basic_ostream manipulators
2431
  template<class charT, class traits>
2432
  basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
2433
  template<class charT, class traits>
2434
  basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
2435
  template<class charT, class traits>
 
2440
  template<class charT, class traits>
2441
  basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
2442
  template<class charT, class traits>
2443
  basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
2444
 
2445
+ // [ostream.rvalue], rvalue stream insertion
2446
  template<class Ostream, class T>
2447
  Ostream&& operator<<(Ostream&& os, const T& x);
2448
 
2449
  // [ostream.formatted.print], print functions
2450
  template<class... Args>
2451
  void print(ostream& os, format_string<Args...> fmt, Args&&... args);
2452
  template<class... Args>
2453
  void println(ostream& os, format_string<Args...> fmt, Args&&... args);
2454
+ void println(ostream& os);
2455
 
2456
  void vprint_unicode(ostream& os, string_view fmt, format_args args);
2457
  void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
2458
  }
2459
  ```
2460
 
2461
  ### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
2462
 
2463
  ``` cpp
2464
  namespace std {
2465
+ // [std.manip], standard manipulators
2466
  unspecified resetiosflags(ios_base::fmtflags mask);
2467
  unspecified setiosflags (ios_base::fmtflags mask);
2468
  unspecified setbase(int base);
2469
  template<class charT> unspecified setfill(charT c);
2470
  unspecified setprecision(int n);
2471
  unspecified setw(int n);
2472
+
2473
+ // [ext.manip], extended manipulators
2474
  template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
2475
  template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
2476
  template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
2477
  template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
2478
 
2479
+ // [quoted.manip], quoted manipulators
2480
  template<class charT>
2481
  unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
2482
 
2483
  template<class charT, class traits, class Allocator>
2484
  unspecified quoted(const basic_string<charT, traits, Allocator>& s,
 
2504
  template<class... Args>
2505
  void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
2506
 
2507
  template<class... Args>
2508
  void println(format_string<Args...> fmt, Args&&... args);
2509
+ void println();
2510
  template<class... Args>
2511
  void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
2512
+ void println(FILE* stream);
2513
 
2514
  void vprint_unicode(string_view fmt, format_args args);
2515
  void vprint_unicode(FILE* stream, string_view fmt, format_args args);
2516
+ void vprint_unicode_buffered(FILE* stream, string_view fmt, format_args args);
2517
 
2518
  void vprint_nonunicode(string_view fmt, format_args args);
2519
  void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
2520
+ void vprint_nonunicode_buffered(FILE* stream, string_view fmt, format_args args);
2521
  }
2522
  ```
2523
 
2524
  ### Input streams <a id="input.streams">[[input.streams]]</a>
2525
 
 
2543
  template<class charT, class traits = char_traits<charT>>
2544
  class basic_istream : virtual public basic_ios<charT, traits> {
2545
  public:
2546
  // types (inherited from basic_ios[ios])
2547
  using char_type = charT;
2548
+ using int_type = traits::int_type;
2549
+ using pos_type = traits::pos_type;
2550
+ using off_type = traits::off_type;
2551
  using traits_type = traits;
2552
 
2553
  // [istream.cons], constructor/destructor
2554
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2555
  virtual ~basic_istream();
 
2590
 
2591
  basic_istream& getline(char_type* s, streamsize n);
2592
  basic_istream& getline(char_type* s, streamsize n, char_type delim);
2593
 
2594
  basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
2595
+ basic_istream& ignore(streamsize n, char_type delim);
2596
  int_type peek();
2597
  basic_istream& read (char_type* s, streamsize n);
2598
  streamsize readsome(char_type* s, streamsize n);
2599
 
2600
  basic_istream& putback(char_type c);
 
2672
 
2673
  ``` cpp
2674
  basic_istream& operator=(basic_istream&& rhs);
2675
  ```
2676
 
2677
+ *Effects:* Equivalent to `swap(rhs)`.
2678
 
2679
  *Returns:* `*this`.
2680
 
2681
  ``` cpp
2682
  void swap(basic_istream& rhs);
 
2744
  if (ctype.is(ctype.space, c) != 0)
2745
  // c is a whitespace character.
2746
  ```
2747
 
2748
  If, after any preparation is completed, `is.good()` is `true`,
2749
+ *`ok_`*` != false` otherwise, *`ok_`*` == false`. During preparation,
2750
+ the constructor may call `setstate(failbit)` (which may throw
2751
  `ios_base::failure` [[iostate.flags]]).[^19]
2752
 
2753
  ``` cpp
2754
  ~sentry();
2755
  ```
 
2758
 
2759
  ``` cpp
2760
  explicit operator bool() const;
2761
  ```
2762
 
2763
+ *Returns:* *ok\_*.
2764
 
2765
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2766
 
2767
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
2768
 
 
3196
 
3197
  ``` cpp
3198
  basic_istream& getline(char_type* s, streamsize n);
3199
  ```
3200
 
3201
+ *Returns:* `getline(s, n, widen(’\n’))`.
3202
 
3203
  ``` cpp
3204
  basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
3205
  ```
3206
 
 
3208
  above). After constructing a `sentry` object, extracts characters and
3209
  discards them. Characters are extracted until any of the following
3210
  occurs:
3211
 
3212
  - `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
3213
+ characters have been extracted so far;
3214
  - end-of-file occurs on the input sequence (in which case the function
3215
  calls `setstate(eofbit)`, which may throw `ios_base::failure`
3216
  [[iostate.flags]]);
3217
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
3218
  available input character `c` (in which case `c` is extracted).
 
3220
  [*Note 1*: The last condition will never occur if
3221
  `traits::eq_int_type(delim, traits::eof())`. — *end note*]
3222
 
3223
  *Returns:* `*this`.
3224
 
3225
+ ``` cpp
3226
+ basic_istream& ignore(streamsize n, char_type delim);
3227
+ ```
3228
+
3229
+ *Constraints:* `is_same_v<char_type, char>` is `true`.
3230
+
3231
+ *Effects:* Equivalent to:
3232
+ `return ignore(n, traits::to_int_type(delim));`
3233
+
3234
  ``` cpp
3235
  int_type peek();
3236
  ```
3237
 
3238
  *Effects:* Behaves as an unformatted input function (as described
 
3420
  class basic_iostream
3421
  : public basic_istream<charT, traits>,
3422
  public basic_ostream<charT, traits> {
3423
  public:
3424
  using char_type = charT;
3425
+ using int_type = traits::int_type;
3426
+ using pos_type = traits::pos_type;
3427
+ using off_type = traits::off_type;
3428
  using traits_type = traits;
3429
 
3430
  // [iostream.cons], constructor
3431
  explicit basic_iostream(basic_streambuf<charT, traits>* sb);
3432
 
 
3481
 
3482
  ``` cpp
3483
  basic_iostream& operator=(basic_iostream&& rhs);
3484
  ```
3485
 
3486
+ *Effects:* Equivalent to `swap(rhs)`.
3487
 
3488
  ``` cpp
3489
  void swap(basic_iostream& rhs);
3490
  ```
3491
 
 
3512
  template<class charT, class traits = char_traits<charT>>
3513
  class basic_ostream : virtual public basic_ios<charT, traits> {
3514
  public:
3515
  // types (inherited from basic_ios[ios])
3516
  using char_type = charT;
3517
+ using int_type = traits::int_type;
3518
+ using pos_type = traits::pos_type;
3519
+ using off_type = traits::off_type;
3520
  using traits_type = traits;
3521
 
3522
  // [ostream.cons], constructor/destructor
3523
  explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
3524
  virtual ~basic_ostream();
 
3690
 
3691
  ``` cpp
3692
  basic_ostream& operator=(basic_ostream&& rhs);
3693
  ```
3694
 
3695
+ *Effects:* Equivalent to `swap(rhs)`.
3696
 
3697
  *Returns:* `*this`.
3698
 
3699
  ``` cpp
3700
  void swap(basic_ostream& rhs);
 
3730
 
3731
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
3732
  If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
3733
 
3734
  If, after any preparation is completed, `os.good()` is `true`,
3735
+ *`ok_`*` == true` otherwise, *`ok_`*` == false`. During preparation, the
3736
  constructor may call `setstate(failbit)` (which may throw
3737
  `ios_base::failure` [[iostate.flags]]).[^30]
3738
 
3739
  ``` cpp
3740
  ~sentry();
3741
  ```
3742
 
3743
  If
3744
  `(os.flags() & ios_base::unitbuf) && !uncaught_exceptions() && os.good()`
3745
+ is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1 or
3746
+ exits via an exception, sets `badbit` in `os.rdstate()` without
3747
+ propagating an exception.
3748
 
3749
  ``` cpp
3750
  explicit operator bool() const;
3751
  ```
3752
 
3753
+ *Effects:* Returns *ok\_*.
3754
 
3755
  ##### Seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
3756
 
3757
  Each seek member function begins execution by constructing an object of
3758
  class `sentry`. It returns by destroying the `sentry` object.
 
3807
  The descriptions of the individual formatted output functions describe
3808
  how they perform output and do not mention the `sentry` object.
3809
 
3810
  If a formatted output function of a stream `os` determines padding, it
3811
  does so as follows. Given a `charT` character sequence `seq` where
3812
+ `charT` is the character container type of the stream, if the length of
3813
+ `seq` is less than `os.width()`, then enough copies of `os.fill()` are
3814
+ added to this sequence as necessary to pad to a width of `os.width()`
3815
+ characters. If `(os.flags() & ios_base::adjustfield) == ios_base::left`
3816
+ is `true`, the fill characters are placed after the character sequence;
3817
+ otherwise, they are placed before the character sequence.
3818
 
3819
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
3820
 
3821
  ``` cpp
3822
  basic_ostream& operator<<(bool val);
 
3841
  `unsigned long long`, `double`, `long double`, or `const void*`, the
3842
  formatting conversion occurs as if it performed the following code
3843
  fragment:
3844
 
3845
  ``` cpp
3846
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
3847
+ getloc()).put(*this, *this, fill(), val).failed();
 
3848
  ```
3849
 
3850
  When `val` is of type `short` the formatting conversion occurs as if it
3851
  performed the following code fragment:
3852
 
3853
  ``` cpp
3854
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
3855
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
3856
+ getloc()).put(*this, *this, fill(),
 
3857
  baseflags == ios_base::oct || baseflags == ios_base::hex
3858
  ? static_cast<long>(static_cast<unsigned short>(val))
3859
  : static_cast<long>(val)).failed();
3860
  ```
3861
 
3862
  When `val` is of type `int` the formatting conversion occurs as if it
3863
  performed the following code fragment:
3864
 
3865
  ``` cpp
3866
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
3867
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
3868
+ getloc()).put(*this, *this, fill(),
 
3869
  baseflags == ios_base::oct || baseflags == ios_base::hex
3870
  ? static_cast<long>(static_cast<unsigned int>(val))
3871
  : static_cast<long>(val)).failed();
3872
  ```
3873
 
3874
  When `val` is of type `unsigned short` or `unsigned int` the formatting
3875
  conversion occurs as if it performed the following code fragment:
3876
 
3877
  ``` cpp
3878
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
3879
+ getloc()).put(*this, *this, fill(), static_cast<unsigned long>(val)).failed();
 
 
3880
  ```
3881
 
3882
  When `val` is of type `float` the formatting conversion occurs as if it
3883
  performed the following code fragment:
3884
 
3885
  ``` cpp
3886
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
3887
+ getloc()).put(*this, *this, fill(), static_cast<double>(val)).failed();
 
 
3888
  ```
3889
 
3890
  The first argument provides an object of the `ostreambuf_iterator<>`
3891
  class which is an iterator for class `basic_ostream<>`. It bypasses
3892
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
 
3914
  *`extended-floating-point-type`* is less than or equal to that of
3915
  `double`, the formatting conversion occurs as if it performed the
3916
  following code fragment:
3917
 
3918
  ``` cpp
3919
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
3920
+ getloc()).put(*this, *this, fill(), static_cast<double>(val)).failed();
 
 
3921
  ```
3922
 
3923
  Otherwise, if the floating-point conversion rank of
3924
  *`extended-floating-point-type`* is less than or equal to that of
3925
  `long double`, the formatting conversion occurs as if it performed the
3926
  following code fragment:
3927
 
3928
  ``` cpp
3929
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
3930
+ getloc()).put(*this, *this, fill(), static_cast<long double>(val)).failed();
 
 
3931
  ```
3932
 
3933
  Otherwise, an invocation of the operator function is conditionally
3934
  supported with *implementation-defined* semantics.
3935
 
 
4023
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
4024
  ```
4025
 
4026
  *Effects:* Behaves as a formatted output
4027
  function [[ostream.formatted.reqmts]] of `out`. Constructs a character
4028
+ sequence `seq`. If `c` has type `char` and the character container type
4029
+ of the stream is not `char`, then `seq` consists of `out.widen(c)`;
4030
+ otherwise `seq` consists of `c`. Determines padding for `seq` as
4031
+ described in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`.
4032
+ Calls `os.width(0)`.
4033
 
4034
  *Returns:* `out`.
4035
 
4036
  ``` cpp
4037
  template<class charT, class traits>
 
4081
 
4082
  *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
4083
  equivalent to:
4084
 
4085
  ``` cpp
4086
+ vprint_unicode(os, fmt.str, make_format_args(args...));
4087
  ```
4088
 
4089
  Otherwise, equivalent to:
4090
 
4091
  ``` cpp
4092
+ vprint_nonunicode(os, fmt.str, make_format_args(args...));
4093
  ```
4094
 
4095
  ``` cpp
4096
  template<class... Args>
4097
  void println(ostream& os, format_string<Args...> fmt, Args&&... args);
4098
  ```
4099
 
4100
  *Effects:* Equivalent to:
4101
 
4102
  ``` cpp
4103
+ print(os, "{}\n", format(os.getloc(), fmt, std::forward<Args>(args)...));
4104
+ ```
4105
+
4106
+ ``` cpp
4107
+ void println(ostream& os);
4108
+ ```
4109
+
4110
+ *Effects:* Equivalent to:
4111
+
4112
+ ``` cpp
4113
+ print(os, "\n");
4114
  ```
4115
 
4116
  ``` cpp
4117
  void vprint_unicode(ostream& os, string_view fmt, format_args args);
4118
  void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
 
4124
  - failure to generate output is reported as specified below, and
4125
  - any exception thrown by the call to `vformat` is propagated without
4126
  regard to the value of `os.exceptions()` and without turning on
4127
  `ios_base::badbit` in the error state of `os`.
4128
 
4129
+ After constructing a `sentry` object, the function initializes a
4130
+ variable with automatic storage duration via
4131
 
4132
  ``` cpp
4133
  string out = vformat(os.getloc(), fmt, args);
4134
  ```
4135
 
4136
+ - If the function is `vprint_unicode` and `os` is a stream that refers
4137
+ to a terminal that is capable of displaying Unicode only via a native
4138
+ Unicode API, which is determined in an implementation-defined manner,
4139
+ flushes `os` and then writes `out` to the terminal using the native
4140
+ Unicode API; if `out` contains invalid code units, the behavior is
4141
+ undefined. Then establishes an observable
4142
+ checkpoint [[intro.abstract]].
4143
+ - Otherwise inserts the character sequence \[`out.begin()`, `out.end()`)
4144
+ into `os`.
4145
+
4146
+ If writing to the terminal or inserting into `os` fails, calls
4147
+ `os.setstate(ios_base::badbit)` (which may throw `ios_base::failure`).
4148
 
4149
  *Recommended practice:* For `vprint_unicode`, if invoking the native
4150
  Unicode API requires transcoding, implementations should substitute
4151
  invalid code units with U+fffd (replacement character) per the Unicode
4152
  Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
 
4207
  [[iostate.flags]]). Otherwise, if the `sentry` object returns `false`,
4208
  does nothing.
4209
 
4210
  *Returns:* `*this`.
4211
 
4212
+ #### Standard `basic_ostream` manipulators <a id="ostream.manip">[[ostream.manip]]</a>
4213
 
4214
  Each instantiation of any of the function templates specified in this
4215
  subclause is a designated addressable function [[namespace.std]].
4216
 
4217
  ``` cpp
 
4253
  manipulator has no effect.
4254
 
4255
  [*Note 1*: To work around the issue that the `Allocator` template
4256
  argument cannot be deduced, implementations can introduce an
4257
  intermediate base class to `basic_syncbuf` that manages its
4258
+ *emit-on-sync* flag. — *end note*]
4259
 
4260
  *Returns:* `os`.
4261
 
4262
  ``` cpp
4263
  template<class charT, class traits>
 
4670
  ``` cpp
4671
  template<class... Args>
4672
  void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
4673
  ```
4674
 
4675
+ *Effects:* Let `locksafe` be
4676
+ `(enable_nonlocking_formatter_optimization<remove_cvref_t<Args>> && ...)`.
4677
+ If the ordinary literal encoding [[lex.charset]] is UTF-8, equivalent
4678
+ to:
4679
 
4680
  ``` cpp
4681
+ locksafe
4682
+ ? vprint_unicode(stream, fmt.str, make_format_args(args...))
4683
+ : vprint_unicode_buffered(stream, fmt.str, make_format_args(args...));
4684
  ```
4685
 
4686
  Otherwise, equivalent to:
4687
 
4688
  ``` cpp
4689
+ locksafe
4690
+ ? vprint_nonunicode(stream, fmt.str, make_format_args(args...))
4691
+ : vprint_nonunicode_buffered(stream, fmt.str, make_format_args(args...));
4692
  ```
4693
 
4694
  ``` cpp
4695
  template<class... Args>
4696
  void println(format_string<Args...> fmt, Args&&... args);
 
4700
 
4701
  ``` cpp
4702
  println(stdout, fmt, std::forward<Args>(args)...);
4703
  ```
4704
 
4705
+ ``` cpp
4706
+ void println();
4707
+ ```
4708
+
4709
+ *Effects:* Equivalent to:
4710
+
4711
+ ``` cpp
4712
+ println(stdout);
4713
+ ```
4714
+
4715
  ``` cpp
4716
  template<class... Args>
4717
  void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
4718
  ```
4719
 
4720
  *Effects:* Equivalent to:
4721
 
4722
  ``` cpp
4723
+ print(stream, runtime_format(string(fmt.get()) + '\n'), std::forward<Args>(args)...);
4724
+ ```
4725
+
4726
+ ``` cpp
4727
+ void println(FILE* stream);
4728
+ ```
4729
+
4730
+ *Effects:* Equivalent to:
4731
+
4732
+ ``` cpp
4733
+ print(stream, "\n");
4734
  ```
4735
 
4736
  ``` cpp
4737
  void vprint_unicode(string_view fmt, format_args args);
4738
  ```
 
4741
 
4742
  ``` cpp
4743
  vprint_unicode(stdout, fmt, args);
4744
  ```
4745
 
4746
+ ``` cpp
4747
+ void vprint_unicode_buffered(FILE* stream, string_view fmt, format_args args);
4748
+ ```
4749
+
4750
+ *Effects:* Equivalent to:
4751
+
4752
+ ``` cpp
4753
+ string out = vformat(fmt, args);
4754
+ vprint_unicode(stream, "{}", make_format_args(out));
4755
+ ```
4756
+
4757
  ``` cpp
4758
  void vprint_unicode(FILE* stream, string_view fmt, format_args args);
4759
  ```
4760
 
4761
  *Preconditions:* `stream` is a valid pointer to an output C stream.
4762
 
4763
+ *Effects:* Locks `stream`. Let `out` denote the character representation
4764
+ of formatting arguments provided by `args` formatted according to
4765
+ specifications given in `fmt`.
4766
 
4767
+ - If `stream` refers to a terminal that is capable of displaying Unicode
4768
+ only via a native Unicode API, flushes `stream` and then writes `out`
4769
+ to the terminal using the native Unicode API; if `out` contains
4770
+ invalid code units, the behavior is undefined. Then establishes an
4771
+ observable checkpoint [[intro.abstract]].
4772
+ - Otherwise writes `out` to `stream` unchanged.
4773
 
4774
+ Unconditionally unlocks `stream` on function exit.
 
 
 
 
 
4775
 
4776
+ See also: ISO C 7.23.2.
4777
+
4778
+ [*Note 1*: On Windows the native Unicode API is `WriteConsoleW` and
4779
+ `stream` referring to a terminal means that
4780
+ `GetConsoleMode(_get_osfhandle(_fileno(stream)), ...)` returns
4781
  nonzero. — *end note*]
4782
 
 
 
 
4783
  *Throws:* Any exception thrown by the call to `vformat`
4784
  [[format.err.report]]. `system_error` if writing to the terminal or
4785
  `stream` fails. May throw `bad_alloc`.
4786
 
4787
  *Recommended practice:* If invoking the native Unicode API requires
 
4797
 
4798
  ``` cpp
4799
  vprint_nonunicode(stdout, fmt, args);
4800
  ```
4801
 
4802
+ ``` cpp
4803
+ void vprint_nonunicode_buffered(FILE* stream, string_view fmt, format_args args);
4804
+ ```
4805
+
4806
+ *Effects:* Equivalent to:
4807
+
4808
+ ``` cpp
4809
+ string out = vformat(fmt, args);
4810
+ vprint_nonunicode("{}", make_format_args(out));
4811
+ ```
4812
+
4813
  ``` cpp
4814
  void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
4815
  ```
4816
 
4817
  *Preconditions:* `stream` is a valid pointer to an output C stream.
4818
 
4819
+ *Effects:* While holding the lock on `stream`, writes the character
4820
+ representation of formatting arguments provided by `args` formatted
4821
+ according to specifications given in `fmt` to `stream`.
4822
 
4823
  *Throws:* Any exception thrown by the call to `vformat`
4824
  [[format.err.report]]. `system_error` if writing to `stream` fails. May
4825
  throw `bad_alloc`.
4826
 
 
4828
 
4829
  ### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
4830
 
4831
  ``` cpp
4832
  namespace std {
4833
+ // [stringbuf], class template basic_stringbuf
4834
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
4835
  class basic_stringbuf;
4836
 
4837
  template<class charT, class traits, class Allocator>
4838
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
4839
  basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
4840
 
4841
  using stringbuf = basic_stringbuf<char>;
4842
  using wstringbuf = basic_stringbuf<wchar_t>;
4843
 
4844
+ // [istringstream], class template basic_istringstream
4845
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
4846
  class basic_istringstream;
4847
 
4848
  template<class charT, class traits, class Allocator>
4849
  void swap(basic_istringstream<charT, traits, Allocator>& x,
4850
  basic_istringstream<charT, traits, Allocator>& y);
4851
 
4852
  using istringstream = basic_istringstream<char>;
4853
  using wistringstream = basic_istringstream<wchar_t>;
4854
 
4855
+ // [ostringstream], class template basic_ostringstream
4856
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
4857
  class basic_ostringstream;
4858
 
4859
  template<class charT, class traits, class Allocator>
4860
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
4861
  basic_ostringstream<charT, traits, Allocator>& y);
4862
 
4863
  using ostringstream = basic_ostringstream<char>;
4864
  using wostringstream = basic_ostringstream<wchar_t>;
4865
 
4866
+ // [stringstream], class template basic_stringstream
4867
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
4868
  class basic_stringstream;
4869
 
4870
  template<class charT, class traits, class Allocator>
4871
  void swap(basic_stringstream<charT, traits, Allocator>& x,
4872
  basic_stringstream<charT, traits, Allocator>& y);
 
4884
 
4885
  #### General <a id="stringbuf.general">[[stringbuf.general]]</a>
4886
 
4887
  ``` cpp
4888
  namespace std {
4889
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
4890
  class basic_stringbuf : public basic_streambuf<charT, traits> {
4891
  public:
4892
  using char_type = charT;
4893
+ using int_type = traits::int_type;
4894
+ using pos_type = traits::pos_type;
4895
+ using off_type = traits::off_type;
4896
  using traits_type = traits;
4897
  using allocator_type = Allocator;
4898
 
4899
  // [stringbuf.cons], constructors
4900
  basic_stringbuf() : basic_stringbuf(ios_base::in | ios_base::out) {}
 
4918
  ios_base::openmode which, const Allocator& a);
4919
  template<class SAlloc>
4920
  explicit basic_stringbuf(
4921
  const basic_string<charT, traits, SAlloc>& s,
4922
  ios_base::openmode which = ios_base::in | ios_base::out);
4923
+ template<class T>
4924
+ explicit basic_stringbuf(const T& t,
4925
+ ios_base::openmode which = ios_base::in | ios_base::out);
4926
+ template<class T>
4927
+ basic_stringbuf(const T& t, const Allocator& a);
4928
+ template<class T>
4929
+ basic_stringbuf(const T& t, ios_base::openmode which, const Allocator& a);
4930
  basic_stringbuf(const basic_stringbuf&) = delete;
4931
  basic_stringbuf(basic_stringbuf&& rhs);
4932
  basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
4933
 
4934
  // [stringbuf.assign], assignment and swap
 
4947
 
4948
  void str(const basic_string<charT, traits, Allocator>& s);
4949
  template<class SAlloc>
4950
  void str(const basic_string<charT, traits, SAlloc>& s);
4951
  void str(basic_string<charT, traits, Allocator>&& s);
4952
+ template<class T>
4953
+ void str(const T& t);
4954
 
4955
  protected:
4956
  // [stringbuf.virtuals], overridden virtual functions
4957
  int_type underflow() override;
4958
  int_type pbackfail(int_type c = traits::eof()) override;
 
4967
  = ios_base::in | ios_base::out) override;
4968
 
4969
  private:
4970
  ios_base::openmode mode; // exposition only
4971
  basic_string<charT, traits, Allocator> buf; // exposition only
4972
+ void init-buf-ptrs(); // exposition only
4973
  };
4974
  }
4975
  ```
4976
 
4977
  The class `basic_stringbuf` is derived from `basic_streambuf` to
 
4985
 
4986
  - `ios_base::openmode mode`, has `in` set if the input sequence can be
4987
  read, and `out` set if the output sequence can be written.
4988
  - `basic_string<charT, traits, Allocator> buf` contains the underlying
4989
  character sequence.
4990
+ - `init-buf-ptrs()` sets the base class’ get area [[streambuf.get.area]]
4991
  and put area [[streambuf.put.area]] pointers after initializing,
4992
+ moving from, or assigning to *`buf`* accordingly.
4993
 
4994
  #### Constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
4995
 
4996
  ``` cpp
4997
  explicit basic_stringbuf(ios_base::openmode which);
4998
  ```
4999
 
5000
  *Effects:* Initializes the base class with `basic_streambuf()`
5001
+ [[streambuf.cons]], and *mode* with `which`. It is
5002
  *implementation-defined* whether the sequence pointers (`eback()`,
5003
  `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) are initialized to
5004
  null pointers.
5005
 
5006
  *Ensures:* `str().empty()` is `true`.
 
5010
  const basic_string<charT, traits, Allocator>& s,
5011
  ios_base::openmode which = ios_base::in | ios_base::out);
5012
  ```
5013
 
5014
  *Effects:* Initializes the base class with `basic_streambuf()`
5015
+ [[streambuf.cons]], *mode* with `which`, and *buf* with `s`, then calls
5016
+ *`init-buf-ptrs`*`()`.
5017
 
5018
  ``` cpp
5019
  basic_stringbuf(ios_base::openmode which, const Allocator& a);
5020
  ```
5021
 
5022
  *Effects:* Initializes the base class with `basic_streambuf()`
5023
+ [[streambuf.cons]], *mode* with `which`, and *buf* with `a`, then calls
5024
+ *`init-buf-ptrs`*`()`.
5025
 
5026
  *Ensures:* `str().empty()` is `true`.
5027
 
5028
  ``` cpp
5029
  explicit basic_stringbuf(
5030
  basic_string<charT, traits, Allocator>&& s,
5031
  ios_base::openmode which = ios_base::in | ios_base::out);
5032
  ```
5033
 
5034
  *Effects:* Initializes the base class with `basic_streambuf()`
5035
+ [[streambuf.cons]], *mode* with `which`, and *buf* with `std::move(s)`,
5036
+ then calls *`init-buf-ptrs`*`()`.
5037
 
5038
  ``` cpp
5039
  template<class SAlloc>
5040
  basic_stringbuf(
5041
  const basic_string<charT, traits, SAlloc>& s,
5042
  ios_base::openmode which, const Allocator& a);
5043
  ```
5044
 
5045
  *Effects:* Initializes the base class with `basic_streambuf()`
5046
+ [[streambuf.cons]], *mode* with `which`, and *buf* with `{s,a}`, then
5047
+ calls *`init-buf-ptrs`*`()`.
5048
 
5049
  ``` cpp
5050
  template<class SAlloc>
5051
  explicit basic_stringbuf(
5052
  const basic_string<charT, traits, SAlloc>& s,
 
5054
  ```
5055
 
5056
  *Constraints:* `is_same_v<SAlloc, Allocator>` is `false`.
5057
 
5058
  *Effects:* Initializes the base class with `basic_streambuf()`
5059
+ [[streambuf.cons]], *mode* with `which`, and *buf* with `s`, then calls
5060
+ *`init-buf-ptrs`*`()`.
5061
+
5062
+ ``` cpp
5063
+ template<class T>
5064
+ explicit basic_stringbuf(const T& t, ios_base::openmode which = ios_base::in | ios_base::out);
5065
+ template<class T>
5066
+ basic_stringbuf(const T& t, const Allocator& a);
5067
+ template<class T>
5068
+ basic_stringbuf(const T& t, ios_base::openmode which, const Allocator& a);
5069
+ ```
5070
+
5071
+ Let `which` be `ios_base::in | ios_base::out` for the overload with no
5072
+ parameter `which`, and `a` be `Allocator()` for the overload with no
5073
+ parameter `a`.
5074
+
5075
+ *Constraints:*
5076
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
5077
+ `true`.
5078
+
5079
+ *Effects:* Creates a variable `sv` as if by
5080
+ `basic_string_view<charT, traits> sv = t`, then value-initializes the
5081
+ base class, initializes *mode* with `which`, and
5082
+ direct-non-list-initializes *buf* with `sv, a`, then calls
5083
+ *`init-buf-ptrs`*`()`.
5084
 
5085
  ``` cpp
5086
  basic_stringbuf(basic_stringbuf&& rhs);
5087
  basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
5088
  ```
5089
 
5090
  *Effects:* Copy constructs the base class from `rhs` and initializes
5091
+ *mode* with `rhs.mode`. In the first form `buf` is initialized from
5092
+ `std::move(rhs).str()`. In the second form *buf* is initialized from
5093
  `{std::move(rhs).str(), a}`. It is *implementation-defined* whether the
5094
  sequence pointers in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`,
5095
  `pptr()`, `epptr()`) obtain the values which `rhs` had.
5096
 
5097
  *Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
 
5134
 
5135
  *Effects:* Exchanges the state of `*this` and `rhs`.
5136
 
5137
  *Remarks:* The exception specification is equivalent to:
5138
  `allocator_traits<Allocator>::propagate_on_container_swap::value ||`
5139
+ `allocator_traits<Allocator>::is_always_equal::value`
5140
 
5141
  ``` cpp
5142
  template<class charT, class traits, class Allocator>
5143
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
5144
  basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
5145
  ```
5146
 
5147
+ *Effects:* Equivalent to `x.swap(y)`.
5148
 
5149
  #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
5150
 
5151
  The member functions getting the underlying character sequence all refer
5152
  to a `high_mark` value, where `high_mark` represents the position one
 
5157
  In the latter case, all characters initialized prior to the call are now
5158
  considered uninitialized (except for those characters re-initialized by
5159
  the new `basic_string`).
5160
 
5161
  ``` cpp
5162
+ void init-buf-ptrs();
5163
  ```
5164
 
5165
+ *Effects:* Initializes the input and output sequences from *buf*
5166
+ according to *mode*.
5167
 
5168
  *Ensures:*
5169
 
5170
+ - If `ios_base::out` is set in *mode*, `pbase()` points to
5171
+ *`buf`*`.front()` and `epptr() >= pbase() + `*`buf`*`.size()` is
5172
+ `true`;
5173
+ - in addition, if `ios_base::ate` is set in *mode*,
5174
+ `pptr() == pbase() + `*`buf`*`.size()` is `true`,
5175
  - otherwise `pptr() == pbase()` is `true`.
5176
+ - If `ios_base::in` is set in *mode*, `eback()` points to
5177
+ *`buf`*`.front()`, and
5178
+ `(gptr() == eback() && egptr() == eback() + `*`buf`*`.size())` is
5179
  `true`.
5180
 
5181
  [*Note 1*: For efficiency reasons, stream buffer operations can violate
5182
+ invariants of *buf* while it is held encapsulated in the
5183
  `basic_stringbuf`, e.g., by writing to characters in the range
5184
+ [*`buf`*`.data() + `*`buf`*`.size()`,
5185
+ *`buf`*`.data() + `*`buf`*`.capacity()`). All operations retrieving a
5186
+ `basic_string` from `buf` ensure that the `basic_string` invariants hold
5187
+ on the returned value. — *end note*]
5188
 
5189
  ``` cpp
5190
  allocator_type get_allocator() const noexcept;
5191
  ```
5192
 
5193
+ *Returns:* *`buf`*`.get_allocator()`.
5194
 
5195
  ``` cpp
5196
  basic_string<charT, traits, Allocator> str() const &;
5197
  ```
5198
 
 
5206
  template<class SAlloc>
5207
  basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
5208
  ```
5209
 
5210
  *Constraints:* `SAlloc` is a type that qualifies as an
5211
+ allocator [[container.reqmts]].
5212
 
5213
  *Effects:* Equivalent to:
5214
 
5215
  ``` cpp
5216
  return basic_string<charT, traits, SAlloc>(view(), sa);
 
5220
  basic_string<charT, traits, Allocator> str() &&;
5221
  ```
5222
 
5223
  *Ensures:* The underlying character sequence `buf` is empty and
5224
  `pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
5225
+ initialized as if by calling *`init-buf-ptrs`*`()` with an empty `buf`.
5226
 
5227
  *Returns:* A `basic_string<charT, traits, Allocator>` object move
5228
  constructed from the `basic_stringbuf`’s underlying character sequence
5229
  in `buf`. This can be achieved by first adjusting `buf` to have the same
5230
  content as `view()`.
 
5236
  Let `sv` be `basic_string_view<charT, traits>`.
5237
 
5238
  *Returns:* A `sv` object referring to the `basic_stringbuf`’s underlying
5239
  character sequence in `buf`:
5240
 
5241
+ - If `ios_base::out` is set in *mode*, then
5242
  `sv(pbase(), high_mark - pbase())` is returned.
5243
+ - Otherwise, if `ios_base::in` is set in *mode*, then
5244
  `sv(eback(), egptr() - eback())` is returned.
5245
  - Otherwise, `sv()` is returned.
5246
 
5247
  [*Note 2*: Using the returned `sv` object after destruction or
5248
  invalidation of the character sequence underlying `*this` is undefined
 
5254
 
5255
  *Effects:* Equivalent to:
5256
 
5257
  ``` cpp
5258
  buf = s;
5259
+ init-buf-ptrs();
5260
  ```
5261
 
5262
  ``` cpp
5263
  template<class SAlloc>
5264
  void str(const basic_string<charT, traits, SAlloc>& s);
 
5268
 
5269
  *Effects:* Equivalent to:
5270
 
5271
  ``` cpp
5272
  buf = s;
5273
+ init-buf-ptrs();
5274
  ```
5275
 
5276
  ``` cpp
5277
  void str(basic_string<charT, traits, Allocator>&& s);
5278
  ```
5279
 
5280
  *Effects:* Equivalent to:
5281
 
5282
  ``` cpp
5283
  buf = std::move(s);
5284
+ init-buf-ptrs();
5285
+ ```
5286
+
5287
+ ``` cpp
5288
+ template<class T>
5289
+ void str(const T& t);
5290
+ ```
5291
+
5292
+ *Constraints:*
5293
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
5294
+ `true`.
5295
+
5296
+ *Effects:* Equivalent to:
5297
+
5298
+ ``` cpp
5299
+ basic_string_view<charT, traits> sv = t;
5300
+ buf = sv;
5301
+ init-buf-ptrs();
5302
  ```
5303
 
5304
  #### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
5305
 
5306
  ``` cpp
 
5322
  - If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
5323
  input sequence has a putback position available, and if
5324
  `traits::eq(to_char_type(c), gptr()[-1])` returns `true`, assigns
5325
  `gptr() - 1` to `gptr()`. Returns: `c`.
5326
  - If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
5327
+ input sequence has a putback position available, and if *mode* `&`
5328
  `ios_base::out` is nonzero, assigns `c` to `*–gptr()`. Returns: `c`.
5329
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
5330
  input sequence has a putback position available, assigns `gptr() - 1`
5331
  to `gptr()`. Returns: `traits::not_eof(c)`.
5332
 
 
5354
 
5355
  *Remarks:* The function can alter the number of write positions
5356
  available as a result of any call.
5357
 
5358
  The function can make a write position available only if `ios_base::out`
5359
+ is set in *mode*. To make a write position available, the function
5360
  reallocates (or initially allocates) an array object with a sufficient
5361
  number of elements to hold the current array object (if any), plus at
5362
+ least one additional write position. If `ios_base::in` is set in *mode*,
5363
  the function alters the read end pointer `egptr()` to point just past
5364
  the new write position.
5365
 
5366
  ``` cpp
5367
  pos_type seekoff(off_type off, ios_base::seekdir way,
 
5431
 
5432
  #### General <a id="istringstream.general">[[istringstream.general]]</a>
5433
 
5434
  ``` cpp
5435
  namespace std {
5436
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
5437
  class basic_istringstream : public basic_istream<charT, traits> {
5438
  public:
5439
  using char_type = charT;
5440
+ using int_type = traits::int_type;
5441
+ using pos_type = traits::pos_type;
5442
+ using off_type = traits::off_type;
5443
  using traits_type = traits;
5444
  using allocator_type = Allocator;
5445
 
5446
  // [istringstream.cons], constructors
5447
  basic_istringstream() : basic_istringstream(ios_base::in) {}
 
5463
  ios_base::openmode which, const Allocator& a);
5464
  template<class SAlloc>
5465
  explicit basic_istringstream(
5466
  const basic_string<charT, traits, SAlloc>& s,
5467
  ios_base::openmode which = ios_base::in);
5468
+ template<class T>
5469
+ explicit basic_istringstream(const T& t, ios_base::openmode which = ios_base::in);
5470
+ template<class T>
5471
+ basic_istringstream(const T& t, const Allocator& a);
5472
+ template<class T>
5473
+ basic_istringstream(const T& t, ios_base::openmode which, const Allocator& a);
5474
  basic_istringstream(const basic_istringstream&) = delete;
5475
  basic_istringstream(basic_istringstream&& rhs);
5476
 
5477
  basic_istringstream& operator=(const basic_istringstream&) = delete;
5478
  basic_istringstream& operator=(basic_istringstream&& rhs);
 
5490
 
5491
  void str(const basic_string<charT, traits, Allocator>& s);
5492
  template<class SAlloc>
5493
  void str(const basic_string<charT, traits, SAlloc>& s);
5494
  void str(basic_string<charT, traits, Allocator>&& s);
5495
+ template<class T>
5496
+ void str(const T& t);
5497
 
5498
  private:
5499
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5500
  };
5501
  }
 
5505
  reading objects of class `basic_string<{}charT, traits, Allocator>`. It
5506
  uses a `basic_stringbuf<charT, traits, Allocator>` object to control the
5507
  associated storage. For the sake of exposition, the maintained data is
5508
  presented here as:
5509
 
5510
+ - *`sb`*, the `stringbuf` object.
5511
 
5512
  #### Constructors <a id="istringstream.cons">[[istringstream.cons]]</a>
5513
 
5514
  ``` cpp
5515
  explicit basic_istringstream(ios_base::openmode which);
5516
  ```
5517
 
5518
  *Effects:* Initializes the base class with
5519
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream]] and *sb*
5520
+ with `basic_stringbuf<charT, traits, Allocator>(which | ios_base::in)`
5521
  [[stringbuf.cons]].
5522
 
5523
  ``` cpp
5524
  explicit basic_istringstream(
5525
  const basic_string<charT, traits, Allocator>& s,
5526
  ios_base::openmode which = ios_base::in);
5527
  ```
5528
 
5529
  *Effects:* Initializes the base class with
5530
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream]] and *sb*
5531
+ with
5532
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
5533
  [[stringbuf.cons]].
5534
 
5535
  ``` cpp
5536
  basic_istringstream(ios_base::openmode which, const Allocator& a);
5537
  ```
5538
 
5539
  *Effects:* Initializes the base class with
5540
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream]] and *sb*
5541
+ with
5542
  `basic_stringbuf<charT, traits, Allocator>(which | ios_base::in, a)`
5543
  [[stringbuf.cons]].
5544
 
5545
  ``` cpp
5546
  explicit basic_istringstream(
5547
  basic_string<charT, traits, Allocator>&& s,
5548
  ios_base::openmode which = ios_base::in);
5549
  ```
5550
 
5551
  *Effects:* Initializes the base class with
5552
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream]] and *sb*
5553
+ with
5554
  `basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::in)`
5555
  [[stringbuf.cons]].
5556
 
5557
  ``` cpp
5558
  template<class SAlloc>
 
5560
  const basic_string<charT, traits, SAlloc>& s,
5561
  ios_base::openmode which, const Allocator& a);
5562
  ```
5563
 
5564
  *Effects:* Initializes the base class with
5565
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream]] and *sb*
5566
+ with
5567
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`
5568
  [[stringbuf.cons]].
5569
 
5570
  ``` cpp
5571
  template<class SAlloc>
5572
  explicit basic_istringstream(
5573
  const basic_string<charT, traits, SAlloc>& s,
5574
  ios_base::openmode which = ios_base::in);
5575
  ```
5576
 
5577
+ *Constraints:* `is_same_v<SAlloc, Allocator>` is `false`.
5578
+
5579
  *Effects:* Initializes the base class with
5580
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream]] and *sb*
5581
+ with
5582
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
5583
  [[stringbuf.cons]].
5584
 
5585
+ ``` cpp
5586
+ template<class T>
5587
+ explicit basic_istringstream(const T& t, ios_base::openmode which = ios_base::in);
5588
+ template<class T>
5589
+ basic_istringstream(const T& t, const Allocator& a);
5590
+ template<class T>
5591
+ basic_istringstream(const T& t, ios_base::openmode which, const Allocator& a);
5592
+ ```
5593
+
5594
+ Let `which` be `ios_base::in` for the overload with no parameter
5595
+ `which`, and `a` be `Allocator()` for the overload with no parameter
5596
+ `a`.
5597
+
5598
+ *Constraints:*
5599
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
5600
+ `true`.
5601
+
5602
+ *Effects:* Initializes the base class with `addressof(`*`sb`*`)`, and
5603
+ direct-non-list-initializes *sb* with `t, which | ios_base::in, a`.
5604
+
5605
  ``` cpp
5606
  basic_istringstream(basic_istringstream&& rhs);
5607
  ```
5608
 
5609
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5610
  by move constructing the base class, and the contained
5611
  `basic_stringbuf`. Then calls
5612
+ `basic_istream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
5613
+ install the contained `basic_stringbuf`.
5614
 
5615
  #### Swap <a id="istringstream.swap">[[istringstream.swap]]</a>
5616
 
5617
  ``` cpp
5618
  void swap(basic_istringstream& rhs);
 
5629
  template<class charT, class traits, class Allocator>
5630
  void swap(basic_istringstream<charT, traits, Allocator>& x,
5631
  basic_istringstream<charT, traits, Allocator>& y);
5632
  ```
5633
 
5634
+ *Effects:* Equivalent to `x.swap(y)`.
5635
 
5636
  #### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
5637
 
5638
  ``` cpp
5639
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5640
  ```
5641
 
5642
  *Returns:*
5643
+ `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(`*`sb`*`))`.
5644
 
5645
  ``` cpp
5646
  basic_string<charT, traits, Allocator> str() const &;
5647
  ```
5648
 
 
5684
  void str(basic_string<charT, traits, Allocator>&& s);
5685
  ```
5686
 
5687
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5688
 
5689
+ ``` cpp
5690
+ template<class T>
5691
+ void str(const T& t);
5692
+ ```
5693
+
5694
+ *Constraints:*
5695
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
5696
+ `true`.
5697
+
5698
+ *Effects:* Equivalent to: `rdbuf()->str(t);`
5699
+
5700
  ### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
5701
 
5702
  #### General <a id="ostringstream.general">[[ostringstream.general]]</a>
5703
 
5704
  ``` cpp
5705
  namespace std {
5706
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
5707
  class basic_ostringstream : public basic_ostream<charT, traits> {
5708
  public:
5709
  using char_type = charT;
5710
+ using int_type = traits::int_type;
5711
+ using pos_type = traits::pos_type;
5712
+ using off_type = traits::off_type;
5713
  using traits_type = traits;
5714
  using allocator_type = Allocator;
5715
 
5716
  // [ostringstream.cons], constructors
5717
  basic_ostringstream() : basic_ostringstream(ios_base::out) {}
 
5733
  ios_base::openmode which, const Allocator& a);
5734
  template<class SAlloc>
5735
  explicit basic_ostringstream(
5736
  const basic_string<charT, traits, SAlloc>& s,
5737
  ios_base::openmode which = ios_base::out);
5738
+ template<class T>
5739
+ explicit basic_ostringstream(const T& t, ios_base::openmode which = ios_base::out);
5740
+ template<class T>
5741
+ basic_ostringstream(const T& t, const Allocator& a);
5742
+ template<class T>
5743
+ basic_ostringstream(const T& t, ios_base::openmode which, const Allocator& a);
5744
  basic_ostringstream(const basic_ostringstream&) = delete;
5745
  basic_ostringstream(basic_ostringstream&& rhs);
5746
 
5747
  basic_ostringstream& operator=(const basic_ostringstream&) = delete;
5748
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
 
5761
 
5762
  void str(const basic_string<charT, traits, Allocator>& s);
5763
  template<class SAlloc>
5764
  void str(const basic_string<charT, traits, SAlloc>& s);
5765
  void str(basic_string<charT, traits, Allocator>&& s);
5766
+ template<class T>
5767
+ void str(const T& t);
5768
 
5769
  private:
5770
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5771
  };
5772
  }
 
5775
  The class `basic_ostringstream<charT, traits, Allocator>` supports
5776
  writing objects of class `basic_string<{}charT, traits, Allocator>`. It
5777
  uses a `basic_stringbuf` object to control the associated storage. For
5778
  the sake of exposition, the maintained data is presented here as:
5779
 
5780
+ - *`sb`*, the `stringbuf` object.
5781
 
5782
  #### Constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
5783
 
5784
  ``` cpp
5785
  explicit basic_ostringstream(ios_base::openmode which);
5786
  ```
5787
 
5788
  *Effects:* Initializes the base class with
5789
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream]] and *sb*
5790
+ with `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out)`
5791
  [[stringbuf.cons]].
5792
 
5793
  ``` cpp
5794
  explicit basic_ostringstream(
5795
  const basic_string<charT, traits, Allocator>& s,
5796
  ios_base::openmode which = ios_base::out);
5797
  ```
5798
 
5799
  *Effects:* Initializes the base class with
5800
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream]] and *sb*
5801
+ with
5802
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
5803
  [[stringbuf.cons]].
5804
 
5805
  ``` cpp
5806
  basic_ostringstream(ios_base::openmode which, const Allocator& a);
5807
  ```
5808
 
5809
  *Effects:* Initializes the base class with
5810
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream]] and *sb*
5811
+ with
5812
  `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`
5813
  [[stringbuf.cons]].
5814
 
5815
  ``` cpp
5816
  explicit basic_ostringstream(
5817
  basic_string<charT, traits, Allocator>&& s,
5818
  ios_base::openmode which = ios_base::out);
5819
  ```
5820
 
5821
  *Effects:* Initializes the base class with
5822
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream]] and *sb*
5823
+ with
5824
  `basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::out)`
5825
  [[stringbuf.cons]].
5826
 
5827
  ``` cpp
5828
  template<class SAlloc>
 
5830
  const basic_string<charT, traits, SAlloc>& s,
5831
  ios_base::openmode which, const Allocator& a);
5832
  ```
5833
 
5834
  *Effects:* Initializes the base class with
5835
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream]] and *sb*
5836
+ with
5837
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`
5838
  [[stringbuf.cons]].
5839
 
5840
  ``` cpp
5841
  template<class SAlloc>
 
5845
  ```
5846
 
5847
  *Constraints:* `is_same_v<SAlloc, Allocator>` is `false`.
5848
 
5849
  *Effects:* Initializes the base class with
5850
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream]] and *sb*
5851
+ with
5852
  `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
5853
  [[stringbuf.cons]].
5854
 
5855
+ ``` cpp
5856
+ template<class T>
5857
+ explicit basic_ostringstream(const T& t, ios_base::openmode which = ios_base::out);
5858
+ template<class T>
5859
+ basic_ostringstream(const T& t, const Allocator& a);
5860
+ template<class T>
5861
+ basic_ostringstream(const T& t, ios_base::openmode which, const Allocator& a);
5862
+ ```
5863
+
5864
+ Let `which` be `ios_base::out` for the overload with no parameter
5865
+ `which`, and `a` be `Allocator()` for the overload with no parameter
5866
+ `a`.
5867
+
5868
+ *Constraints:*
5869
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
5870
+ `true`.
5871
+
5872
+ *Effects:* Initializes the base class with `addressof(`*`sb`*`)`, and
5873
+ direct-non-list-initializes *sb* with `t, which | ios_base::out, a`.
5874
+
5875
  ``` cpp
5876
  basic_ostringstream(basic_ostringstream&& rhs);
5877
  ```
5878
 
5879
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5880
  by move constructing the base class, and the contained
5881
  `basic_stringbuf`. Then calls
5882
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
5883
+ install the contained `basic_stringbuf`.
5884
 
5885
  #### Swap <a id="ostringstream.swap">[[ostringstream.swap]]</a>
5886
 
5887
  ``` cpp
5888
  void swap(basic_ostringstream& rhs);
 
5899
  template<class charT, class traits, class Allocator>
5900
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
5901
  basic_ostringstream<charT, traits, Allocator>& y);
5902
  ```
5903
 
5904
+ *Effects:* Equivalent to `x.swap(y)`.
5905
 
5906
  #### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
5907
 
5908
  ``` cpp
5909
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5910
  ```
5911
 
5912
  *Returns:*
5913
+ `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(`*`sb`*`))`.
5914
 
5915
  ``` cpp
5916
  basic_string<charT, traits, Allocator> str() const &;
5917
  ```
5918
 
 
5954
  void str(basic_string<charT, traits, Allocator>&& s);
5955
  ```
5956
 
5957
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5958
 
5959
+ ``` cpp
5960
+ template<class T>
5961
+ void str(const T& t);
5962
+ ```
5963
+
5964
+ *Constraints:*
5965
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
5966
+ `true`.
5967
+
5968
+ *Effects:* Equivalent to: `rdbuf()->str(t);`
5969
+
5970
  ### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
5971
 
5972
  #### General <a id="stringstream.general">[[stringstream.general]]</a>
5973
 
5974
  ``` cpp
5975
  namespace std {
5976
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
5977
  class basic_stringstream : public basic_iostream<charT, traits> {
5978
  public:
5979
  using char_type = charT;
5980
+ using int_type = traits::int_type;
5981
+ using pos_type = traits::pos_type;
5982
+ using off_type = traits::off_type;
5983
  using traits_type = traits;
5984
  using allocator_type = Allocator;
5985
 
5986
  // [stringstream.cons], constructors
5987
  basic_stringstream() : basic_stringstream(ios_base::out | ios_base::in) {}
 
6003
  ios_base::openmode which, const Allocator& a);
6004
  template<class SAlloc>
6005
  explicit basic_stringstream(
6006
  const basic_string<charT, traits, SAlloc>& s,
6007
  ios_base::openmode which = ios_base::out | ios_base::in);
6008
+ template<class T>
6009
+ explicit basic_stringstream(const T& t,
6010
+ ios_base::openmode which = ios_base::out | ios_base::in);
6011
+ template<class T>
6012
+ basic_stringstream(const T& t, const Allocator& a);
6013
+ template<class T>
6014
+ basic_stringstream(const T& t, ios_base::openmode which, const Allocator& a);
6015
  basic_stringstream(const basic_stringstream&) = delete;
6016
  basic_stringstream(basic_stringstream&& rhs);
6017
 
6018
  basic_stringstream& operator=(const basic_stringstream&) = delete;
6019
  basic_stringstream& operator=(basic_stringstream&& rhs);
 
6032
 
6033
  void str(const basic_string<charT, traits, Allocator>& s);
6034
  template<class SAlloc>
6035
  void str(const basic_string<charT, traits, SAlloc>& s);
6036
  void str(basic_string<charT, traits, Allocator>&& s);
6037
+ template<class T>
6038
+ void str(const T& t);
6039
 
6040
  private:
6041
+ basic_stringbuf<charT, traits, Allocator> sb; // exposition only
6042
  };
6043
  }
6044
  ```
6045
 
6046
  The class template `basic_stringstream<charT, traits>` supports reading
 
6048
  `basic_string<charT, traits, Allocator>`. It uses a
6049
  `basic_stringbuf<charT, traits, Allocator>` object to control the
6050
  associated sequence. For the sake of exposition, the maintained data is
6051
  presented here as
6052
 
6053
+ - *`sb`*, the `stringbuf` object.
6054
 
6055
  #### Constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
6056
 
6057
  ``` cpp
6058
  explicit basic_stringstream(ios_base::openmode which);
6059
  ```
6060
 
6061
  *Effects:* Initializes the base class with
6062
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
6063
+ and *sb* with `basic_stringbuf<charT, traits, Allocator>(which)`.
6064
 
6065
  ``` cpp
6066
  explicit basic_stringstream(
6067
  const basic_string<charT, traits, Allocator>& s,
6068
  ios_base::openmode which = ios_base::out | ios_base::in);
6069
  ```
6070
 
6071
  *Effects:* Initializes the base class with
6072
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
6073
+ and *sb* with `basic_stringbuf<charT, traits, Allocator>(s, which)`.
6074
 
6075
  ``` cpp
6076
  basic_stringstream(ios_base::openmode which, const Allocator& a);
6077
  ```
6078
 
6079
  *Effects:* Initializes the base class with
6080
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
6081
+ and *sb* with `basic_stringbuf<charT, traits, Allocator>(which, a)`
6082
  [[stringbuf.cons]].
6083
 
6084
  ``` cpp
6085
  explicit basic_stringstream(
6086
  basic_string<charT, traits, Allocator>&& s,
6087
  ios_base::openmode which = ios_base::out | ios_base::in);
6088
  ```
6089
 
6090
  *Effects:* Initializes the base class with
6091
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
6092
+ and *sb* with
6093
  `basic_stringbuf<charT, traits, Allocator>(std::move(s), which)`
6094
  [[stringbuf.cons]].
6095
 
6096
  ``` cpp
6097
  template<class SAlloc>
 
6099
  const basic_string<charT, traits, SAlloc>& s,
6100
  ios_base::openmode which, const Allocator& a);
6101
  ```
6102
 
6103
  *Effects:* Initializes the base class with
6104
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
6105
+ and *sb* with `basic_stringbuf<charT, traits, Allocator>(s, which, a)`
6106
  [[stringbuf.cons]].
6107
 
6108
  ``` cpp
6109
  template<class SAlloc>
6110
  explicit basic_stringstream(
 
6113
  ```
6114
 
6115
  *Constraints:* `is_same_v<SAlloc, Allocator>` is `false`.
6116
 
6117
  *Effects:* Initializes the base class with
6118
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
6119
+ and *sb* with `basic_stringbuf<charT, traits, Allocator>(s, which)`
6120
  [[stringbuf.cons]].
6121
 
6122
+ ``` cpp
6123
+ template<class T>
6124
+ explicit basic_stringstream(const T& t, ios_base::openmode which = ios_base::out | ios_base::in);
6125
+ template<class T>
6126
+ basic_stringstream(const T& t, const Allocator& a);
6127
+ template<class T>
6128
+ basic_stringstream(const T& t, ios_base::openmode which, const Allocator& a);
6129
+ ```
6130
+
6131
+ Let `which` be `ios_base::out | ios_base::in` for the overload with no
6132
+ parameter `which`, and `a` be `Allocator()` for the overload with no
6133
+ parameter `a`.
6134
+
6135
+ *Constraints:*
6136
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
6137
+ `true`.
6138
+
6139
+ *Effects:* Initializes the base class with `addressof(`*`sb`*`)`, and
6140
+ direct-non-list-initializes *sb* with `t, which, a`.
6141
+
6142
  ``` cpp
6143
  basic_stringstream(basic_stringstream&& rhs);
6144
  ```
6145
 
6146
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
6147
  by move constructing the base class, and the contained
6148
  `basic_stringbuf`. Then calls
6149
+ `basic_istream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
6150
+ install the contained `basic_stringbuf`.
6151
 
6152
  #### Swap <a id="stringstream.swap">[[stringstream.swap]]</a>
6153
 
6154
  ``` cpp
6155
  void swap(basic_stringstream& rhs);
 
6166
  template<class charT, class traits, class Allocator>
6167
  void swap(basic_stringstream<charT, traits, Allocator>& x,
6168
  basic_stringstream<charT, traits, Allocator>& y);
6169
  ```
6170
 
6171
+ *Effects:* Equivalent to `x.swap(y)`.
6172
 
6173
  #### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
6174
 
6175
  ``` cpp
6176
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
6177
  ```
6178
 
6179
  *Returns:*
6180
+ `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(`*`sb`*`))`.
6181
 
6182
  ``` cpp
6183
  basic_string<charT, traits, Allocator> str() const &;
6184
  ```
6185
 
 
6221
  void str(basic_string<charT, traits, Allocator>&& s);
6222
  ```
6223
 
6224
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
6225
 
6226
+ ``` cpp
6227
+ template<class T>
6228
+ void str(const T& t);
6229
+ ```
6230
+
6231
+ *Constraints:*
6232
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
6233
+ `true`.
6234
+
6235
+ *Effects:* Equivalent to: `rdbuf()->str(t);`
6236
+
6237
  ## Span-based streams <a id="span.streams">[[span.streams]]</a>
6238
 
6239
  ### Overview <a id="span.streams.overview">[[span.streams.overview]]</a>
6240
 
6241
  The header `<spanstream>` defines class templates and types that
6242
  associate stream buffers with objects whose types are specializations of
6243
  `span` as described in [[views.span]].
6244
 
6245
  [*Note 1*: A user of these classes is responsible for ensuring that the
6246
  character sequence represented by the given `span` outlives the use of
6247
+ the sequence by objects of the classes in [[span.streams]]. Using
6248
+ multiple `basic_spanbuf` objects referring to overlapping underlying
6249
+ sequences from different threads, where at least one `basic_spanbuf`
6250
+ object is used for writing to the sequence, results in a data
6251
+ race. — *end note*]
6252
 
6253
  ### Header `<spanstream>` synopsis <a id="spanstream.syn">[[spanstream.syn]]</a>
6254
 
6255
  ``` cpp
6256
  namespace std {
6257
+ // [spanbuf], class template basic_spanbuf
6258
  template<class charT, class traits = char_traits<charT>>
6259
  class basic_spanbuf;
6260
 
6261
  template<class charT, class traits>
6262
  void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
6263
 
6264
  using spanbuf = basic_spanbuf<char>;
6265
  using wspanbuf = basic_spanbuf<wchar_t>;
6266
 
6267
+ // [ispanstream], class template basic_ispanstream
6268
  template<class charT, class traits = char_traits<charT>>
6269
  class basic_ispanstream;
6270
 
6271
  template<class charT, class traits>
6272
  void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
6273
 
6274
  using ispanstream = basic_ispanstream<char>;
6275
  using wispanstream = basic_ispanstream<wchar_t>;
6276
 
6277
+ // [ospanstream], class template basic_ospanstream
6278
  template<class charT, class traits = char_traits<charT>>
6279
  class basic_ospanstream;
6280
 
6281
  template<class charT, class traits>
6282
  void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
6283
 
6284
  using ospanstream = basic_ospanstream<char>;
6285
  using wospanstream = basic_ospanstream<wchar_t>;
6286
 
6287
+ // [spanstream], class template basic_spanstream
6288
  template<class charT, class traits = char_traits<charT>>
6289
  class basic_spanstream;
6290
 
6291
  template<class charT, class traits>
6292
  void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
 
6305
  template<class charT, class traits = char_traits<charT>>
6306
  class basic_spanbuf
6307
  : public basic_streambuf<charT, traits> {
6308
  public:
6309
  using char_type = charT;
6310
+ using int_type = traits::int_type;
6311
+ using pos_type = traits::pos_type;
6312
+ using off_type = traits::off_type;
6313
  using traits_type = traits;
6314
 
6315
  // [spanbuf.cons], constructors
6316
  basic_spanbuf() : basic_spanbuf(ios_base::in | ios_base::out) {}
6317
  explicit basic_spanbuf(ios_base::openmode which)
 
6488
  - `(pptr() - pbase())` for the output sequence, or `(gptr() - eback())`
6489
  for the input sequence when `way` is `ios_base::cur`;
6490
  - when `way` is `ios_base::end` :
6491
  - `(pptr() - pbase())` if `ios_base::out` is set in *mode* and
6492
  `ios_base::in` is not set in *mode*,
6493
+ - *`buf`*`.size()` otherwise.
6494
 
6495
  If `baseoff` + `off` would overflow, or if `baseoff` + `off` is less
6496
  than zero, or if `baseoff` + `off` is greater than *`buf`*`.size()`, the
6497
  positioning operation fails. Otherwise, the function computes
6498
 
 
6535
  template<class charT, class traits = char_traits<charT>>
6536
  class basic_ispanstream
6537
  : public basic_istream<charT, traits> {
6538
  public:
6539
  using char_type = charT;
6540
+ using int_type = traits::int_type;
6541
+ using pos_type = traits::pos_type;
6542
+ using off_type = traits::off_type;
6543
  using traits_type = traits;
6544
 
6545
  // [ispanstream.cons], constructors
6546
  explicit basic_ispanstream(std::span<charT> s,
6547
  ios_base::openmode which = ios_base::in);
 
6577
  ``` cpp
6578
  explicit basic_ispanstream(std::span<charT> s, ios_base::openmode which = ios_base::in);
6579
  ```
6580
 
6581
  *Effects:* Initializes the base class with
6582
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` and *sb* with
6583
  `basic_spanbuf<charT, traits>(s, which | ios_base::in)`
6584
  [[spanbuf.cons]].
6585
 
6586
  ``` cpp
6587
  basic_ispanstream(basic_ispanstream&& rhs);
6588
  ```
6589
 
6590
+ *Effects:* Initializes the base class with `std::move(rhs)` and *sb*
6591
+ with `std::move(rhs.`*`sb`*`)`. Next,
6592
+ `basic_istream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` is called
6593
+ to install the contained `basic_spanbuf`.
6594
 
6595
  ``` cpp
6596
  template<class ROS> explicit basic_ispanstream(ROS&& s)
6597
  ```
6598
 
6599
  *Constraints:* `ROS` models `ranges::borrowed_range`.
6600
  `!convertible_to<ROS, std::span<charT>> && convertible_to<ROS, std::span<charT const>>`
6601
  is `true`.
6602
 
6603
  *Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
6604
+ Equivalent to:
6605
 
6606
  ``` cpp
6607
  basic_ispanstream(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
6608
  ```
6609
 
 
6661
 
6662
  *Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
6663
  Equivalent to:
6664
 
6665
  ``` cpp
6666
+ this->span(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()));
6667
  ```
6668
 
6669
  ### Class template `basic_ospanstream` <a id="ospanstream">[[ospanstream]]</a>
6670
 
6671
  #### General <a id="ospanstream.general">[[ospanstream.general]]</a>
 
6675
  template<class charT, class traits = char_traits<charT>>
6676
  class basic_ospanstream
6677
  : public basic_ostream<charT, traits> {
6678
  public:
6679
  using char_type = charT;
6680
+ using int_type = traits::int_type;
6681
+ using pos_type = traits::pos_type;
6682
+ using off_type = traits::off_type;
6683
  using traits_type = traits;
6684
 
6685
  // [ospanstream.cons], constructors
6686
  explicit basic_ospanstream(std::span<charT> s,
6687
  ios_base::openmode which = ios_base::out);
 
6712
  explicit basic_ospanstream(std::span<charT> s,
6713
  ios_base::openmode which = ios_base::out);
6714
  ```
6715
 
6716
  *Effects:* Initializes the base class with
6717
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` and *sb* with
6718
  `basic_spanbuf<charT, traits>(s, which | ios_base::out)`
6719
  [[spanbuf.cons]].
6720
 
6721
  ``` cpp
6722
  basic_ospanstream(basic_ospanstream&& rhs) noexcept;
6723
  ```
6724
 
6725
+ *Effects:* Initializes the base class with `std::move(rhs)` and *sb*
6726
+ with `std::move(rhs.`*`sb`*`)`. Next,
6727
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` is called
6728
+ to install the contained `basic_spanbuf`.
6729
 
6730
  #### Swap <a id="ospanstream.swap">[[ospanstream.swap]]</a>
6731
 
6732
  ``` cpp
6733
  void swap(basic_ospanstream& rhs);
 
6780
  template<class charT, class traits = char_traits<charT>>
6781
  class basic_spanstream
6782
  : public basic_iostream<charT, traits> {
6783
  public:
6784
  using char_type = charT;
6785
+ using int_type = traits::int_type;
6786
+ using pos_type = traits::pos_type;
6787
+ using off_type = traits::off_type;
6788
  using traits_type = traits;
6789
 
6790
  // [spanstream.cons], constructors
6791
  explicit basic_spanstream(std::span<charT> s,
6792
  ios_base::openmode which = ios_base::out | ios_base::in);
 
6817
  explicit basic_spanstream(std::span<charT> s,
6818
  ios_base::openmode which = ios_base::out | ios_bas::in);
6819
  ```
6820
 
6821
  *Effects:* Initializes the base class with
6822
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` and *sb* with
6823
  `basic_spanbuf<charT, traits>(s, which)` [[spanbuf.cons]].
6824
 
6825
  ``` cpp
6826
  basic_spanstream(basic_spanstream&& rhs);
6827
  ```
6828
 
6829
+ *Effects:* Initializes the base class with `std::move(rhs)` and *sb*
6830
+ with `std::move(rhs.`*`sb`*`)`. Next,
6831
+ `basic_iostream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` is
6832
+ called to install the contained `basic_spanbuf`.
6833
 
6834
  #### Swap <a id="spanstream.swap">[[spanstream.swap]]</a>
6835
 
6836
  ``` cpp
6837
  void swap(basic_spanstream& rhs);
 
6879
 
6880
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
6881
 
6882
  ``` cpp
6883
  namespace std {
6884
+ // [filebuf], class template basic_filebuf
6885
  template<class charT, class traits = char_traits<charT>>
6886
  class basic_filebuf;
6887
 
6888
  template<class charT, class traits>
6889
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
6890
 
6891
  using filebuf = basic_filebuf<char>;
6892
  using wfilebuf = basic_filebuf<wchar_t>;
6893
 
6894
+ // [ifstream], class template basic_ifstream
6895
  template<class charT, class traits = char_traits<charT>>
6896
  class basic_ifstream;
6897
 
6898
  template<class charT, class traits>
6899
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
6900
 
6901
  using ifstream = basic_ifstream<char>;
6902
  using wifstream = basic_ifstream<wchar_t>;
6903
 
6904
+ // [ofstream], class template basic_ofstream
6905
  template<class charT, class traits = char_traits<charT>>
6906
  class basic_ofstream;
6907
 
6908
  template<class charT, class traits>
6909
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
6910
 
6911
  using ofstream = basic_ofstream<char>;
6912
  using wofstream = basic_ofstream<wchar_t>;
6913
 
6914
+ // [fstream], class template basic_fstream
6915
  template<class charT, class traits = char_traits<charT>>
6916
  class basic_fstream;
6917
 
6918
  template<class charT, class traits>
6919
  void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);
 
6938
  `filesystem::path::value_type` [[fs.class.path]] is not `char`.
6939
 
6940
  [*Note 2*: These functions enable class `path` support for systems with
6941
  a wide native path character type, such as `wchar_t`. — *end note*]
6942
 
6943
+ ### Native handles <a id="file.native">[[file.native]]</a>
6944
+
6945
+ Several classes described in [[file.streams]] have a member
6946
+ `native_handle_type`.
6947
+
6948
+ The type `native_handle_type` represents a platform-specific
6949
+ *native handle* to a file. It is trivially copyable and models
6950
+ `semiregular`.
6951
+
6952
+ [*Note 1*: For operating systems based on POSIX, `native_handle_type`
6953
+ is `int`. For Windows-based operating systems, `native_handle_type` is
6954
+ `HANDLE`. — *end note*]
6955
+
6956
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
6957
 
6958
  #### General <a id="filebuf.general">[[filebuf.general]]</a>
6959
 
6960
  ``` cpp
6961
  namespace std {
6962
  template<class charT, class traits = char_traits<charT>>
6963
  class basic_filebuf : public basic_streambuf<charT, traits> {
6964
  public:
6965
  using char_type = charT;
6966
+ using int_type = traits::int_type;
6967
+ using pos_type = traits::pos_type;
6968
+ using off_type = traits::off_type;
6969
  using traits_type = traits;
6970
+ using native_handle_type = implementation-defined // type of native_handle_type; // see [file.native]
6971
 
6972
  // [filebuf.cons], constructors/destructor
6973
  basic_filebuf();
6974
  basic_filebuf(const basic_filebuf&) = delete;
6975
  basic_filebuf(basic_filebuf&& rhs);
 
6983
  // [filebuf.members], members
6984
  bool is_open() const;
6985
  basic_filebuf* open(const char* s, ios_base::openmode mode);
6986
  basic_filebuf* open(const filesystem::path::value_type* s,
6987
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
6988
+ basic_filebuf* open(const string& s, ios_base::openmode mode);
6989
+ basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
 
 
6990
  basic_filebuf* close();
6991
+ native_handle_type native_handle() const noexcept;
6992
 
6993
  protected:
6994
  // [filebuf.virtuals], overridden virtual functions
6995
  streamsize showmanyc() override;
6996
  int_type underflow() override;
6997
  int_type uflow() override;
6998
  int_type pbackfail(int_type c = traits::eof()) override;
6999
  int_type overflow (int_type c = traits::eof()) override;
7000
 
7001
+ basic_streambuf<charT, traits>* setbuf(char_type* s, streamsize n) override;
7002
+
7003
  pos_type seekoff(off_type off, ios_base::seekdir way,
7004
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
 
7005
  pos_type seekpos(pos_type sp,
7006
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
7007
+
7008
  int sync() override;
7009
  void imbue(const locale& loc) override;
7010
  };
7011
  }
7012
  ```
 
7028
 
7029
  An instance of `basic_filebuf` behaves as described in  [[filebuf]]
7030
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
7031
  the behavior is undefined.
7032
 
7033
+ The file associated with a `basic_filebuf` has an associated value of
7034
+ type `native_handle_type`, called the native handle [[file.native]] of
7035
+ that file. This native handle can be obtained by calling the member
7036
+ function `native_handle`.
7037
+
7038
+ For any opened `basic_filebuf f`, the native handle returned by
7039
+ `f.native_handle()` is invalidated when `f.close()` is called, or `f` is
7040
+ destroyed.
7041
+
7042
  In order to support file I/O and multibyte/wide character conversion,
7043
  conversions are performed using members of a facet, referred to as
7044
  `a_codecvt` in following subclauses, obtained as if by
7045
 
7046
  ``` cpp
 
7119
  ``` cpp
7120
  template<class charT, class traits>
7121
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
7122
  ```
7123
 
7124
+ *Effects:* Equivalent to `x.swap(y)`.
7125
 
7126
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
7127
 
7128
  ``` cpp
7129
  bool is_open() const;
 
7136
  basic_filebuf* open(const char* s, ios_base::openmode mode);
7137
  basic_filebuf* open(const filesystem::path::value_type* s,
7138
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
7139
  ```
7140
 
7141
+ *Preconditions:* `s` points to an NTCTS [[defns.ntcts]].
7142
 
7143
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
7144
  initializes the `filebuf` as required. It then opens the file to which
7145
  `s` resolves, if possible, as if by a call to `fopen` with the second
7146
  argument determined from `mode & ~ios_base::ate` as indicated in
 
7213
 
7214
  *Ensures:* `is_open() == false`.
7215
 
7216
  *Returns:* `this` on success, a null pointer otherwise.
7217
 
7218
+ ``` cpp
7219
+ native_handle_type native_handle() const noexcept;
7220
+ ```
7221
+
7222
+ *Preconditions:* `is_open()` is `true`.
7223
+
7224
+ *Returns:* The native handle associated with `*this`.
7225
+
7226
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
7227
 
7228
  ``` cpp
7229
  streamsize showmanyc() override;
7230
  ```
 
7246
  reading from the associated file into an internal buffer (`extern_buf`)
7247
  and then as if by doing:
7248
 
7249
  ``` cpp
7250
  char extern_buf[XSIZE];
7251
+ const char* extern_end;
7252
  charT intern_buf[ISIZE];
7253
  charT* intern_end;
7254
  codecvt_base::result r =
7255
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
7256
  intern_buf, intern_buf+ISIZE, intern_end);
 
7311
  of “consuming characters” is performed by first converting as if by:
7312
 
7313
  ``` cpp
7314
  charT* b = pbase();
7315
  charT* p = pptr();
7316
+ const charT* end;
7317
  char xbuf[XSIZE];
7318
  char* xbuf_end;
7319
  codecvt_base::result r =
7320
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);
7321
  ```
 
7330
  to `p`. If output fails, fail (without repeating).
7331
  - Otherwise output from `xbuf` to `xbuf_end`, and fail if output fails.
7332
  At this point if `b != p` and `b == end` (`xbuf` isn’t large enough)
7333
  then increase `XSIZE` and repeat from the beginning.
7334
 
7335
+ Then establishes an observable checkpoint [[intro.abstract]].
7336
+
7337
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
7338
  to indicate failure. If `is_open() == false`, the function always fails.
7339
 
7340
  ``` cpp
7341
  basic_streambuf* setbuf(char_type* s, streamsize n) override;
 
7366
  fails, or if the object cannot represent the resultant stream position,
7367
  returns `pos_type(off_type(-1))`.
7368
 
7369
  *Remarks:* “The last operation was output” means either the last virtual
7370
  operation was overflow or the put buffer is non-empty. “Write any
7371
+ unshift sequence” means, if `width` is less than zero then call
7372
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
7373
  resulting unshift sequence. The function determines one of three values
7374
  for the argument `whence`, of type `int`, as indicated in
7375
  [[filebuf.seekoff]].
7376
 
 
7441
  namespace std {
7442
  template<class charT, class traits = char_traits<charT>>
7443
  class basic_ifstream : public basic_istream<charT, traits> {
7444
  public:
7445
  using char_type = charT;
7446
+ using int_type = traits::int_type;
7447
+ using pos_type = traits::pos_type;
7448
+ using off_type = traits::off_type;
7449
  using traits_type = traits;
7450
+ using native_handle_type = basic_filebuf<charT, traits>::native_handle_type;
7451
 
7452
  // [ifstream.cons], constructors
7453
  basic_ifstream();
7454
  explicit basic_ifstream(const char* s,
7455
  ios_base::openmode mode = ios_base::in);
 
7468
  // [ifstream.swap], swap
7469
  void swap(basic_ifstream& rhs);
7470
 
7471
  // [ifstream.members], members
7472
  basic_filebuf<charT, traits>* rdbuf() const;
7473
+ native_handle_type native_handle() const noexcept;
7474
 
7475
  bool is_open() const;
7476
  void open(const char* s, ios_base::openmode mode = ios_base::in);
7477
  void open(const filesystem::path::value_type* s,
7478
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
 
7489
  The class `basic_ifstream<charT, traits>` supports reading from named
7490
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
7491
  associated sequence. For the sake of exposition, the maintained data is
7492
  presented here as:
7493
 
7494
+ - *`sb`*, the `filebuf` object.
7495
 
7496
  #### Constructors <a id="ifstream.cons">[[ifstream.cons]]</a>
7497
 
7498
  ``` cpp
7499
  basic_ifstream();
7500
  ```
7501
 
7502
  *Effects:* Initializes the base class with
7503
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream.cons]] and
7504
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
7505
 
7506
  ``` cpp
7507
  explicit basic_ifstream(const char* s,
7508
  ios_base::openmode mode = ios_base::in);
7509
  explicit basic_ifstream(const filesystem::path::value_type* s,
7510
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
7511
  ```
7512
 
7513
  *Effects:* Initializes the base class with
7514
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream.cons]] and
7515
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
7516
  `rdbuf()->open(s, mode | ios_base::in)`. If that function returns a null
7517
  pointer, calls `setstate(failbit)`.
7518
 
7519
  ``` cpp
7520
  explicit basic_ifstream(const string& s,
7521
  ios_base::openmode mode = ios_base::in);
7522
  ```
7523
 
7524
+ *Effects:* Equivalent to `basic_ifstream(s.c_str(), mode)`.
7525
 
7526
  ``` cpp
7527
  template<class T>
7528
  explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
7529
  ```
7530
 
7531
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7532
 
7533
+ *Effects:* Equivalent to `basic_ifstream(s.c_str(), mode)`.
7534
 
7535
  ``` cpp
7536
  basic_ifstream(basic_ifstream&& rhs);
7537
  ```
7538
 
7539
  *Effects:* Move constructs the base class, and the contained
7540
  `basic_filebuf`. Then calls
7541
+ `basic_istream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
7542
+ install the contained `basic_filebuf`.
7543
 
7544
  #### Swap <a id="ifstream.swap">[[ifstream.swap]]</a>
7545
 
7546
  ``` cpp
7547
  void swap(basic_ifstream& rhs);
7548
  ```
7549
 
7550
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7551
+ `basic_istream<charT, traits>::swap(rhs)` and
7552
+ *`sb`*`.swap(rhs.`*`sb`*`)`.
7553
 
7554
  ``` cpp
7555
  template<class charT, class traits>
7556
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
7557
  ```
7558
 
7559
+ *Effects:* Equivalent to `x.swap(y)`.
7560
 
7561
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
7562
 
7563
  ``` cpp
7564
  basic_filebuf<charT, traits>* rdbuf() const;
7565
  ```
7566
 
7567
+ *Returns:*
7568
+ `const_cast<basic_filebuf<charT, traits>*>(addressof(`*`sb`*`))`.
7569
+
7570
+ ``` cpp
7571
+ native_handle_type native_handle() const noexcept;
7572
+ ```
7573
+
7574
+ *Effects:* Equivalent to: `return rdbuf()->native_handle();`
7575
 
7576
  ``` cpp
7577
  bool is_open() const;
7578
  ```
7579
 
 
7613
  namespace std {
7614
  template<class charT, class traits = char_traits<charT>>
7615
  class basic_ofstream : public basic_ostream<charT, traits> {
7616
  public:
7617
  using char_type = charT;
7618
+ using int_type = traits::int_type;
7619
+ using pos_type = traits::pos_type;
7620
+ using off_type = traits::off_type;
7621
  using traits_type = traits;
7622
+ using native_handle_type = basic_filebuf<charT, traits>::native_handle_type;
7623
 
7624
  // [ofstream.cons], constructors
7625
  basic_ofstream();
7626
  explicit basic_ofstream(const char* s,
7627
  ios_base::openmode mode = ios_base::out);
 
7640
  // [ofstream.swap], swap
7641
  void swap(basic_ofstream& rhs);
7642
 
7643
  // [ofstream.members], members
7644
  basic_filebuf<charT, traits>* rdbuf() const;
7645
+ native_handle_type native_handle() const noexcept;
7646
 
7647
  bool is_open() const;
7648
  void open(const char* s, ios_base::openmode mode = ios_base::out);
7649
  void open(const filesystem::path::value_type* s,
7650
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
 
7661
  The class `basic_ofstream<charT, traits>` supports writing to named
7662
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
7663
  associated sequence. For the sake of exposition, the maintained data is
7664
  presented here as:
7665
 
7666
+ - *`sb`*, the `filebuf` object.
7667
 
7668
  #### Constructors <a id="ofstream.cons">[[ofstream.cons]]</a>
7669
 
7670
  ``` cpp
7671
  basic_ofstream();
7672
  ```
7673
 
7674
  *Effects:* Initializes the base class with
7675
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream.cons]] and
7676
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
7677
 
7678
  ``` cpp
7679
  explicit basic_ofstream(const char* s,
7680
  ios_base::openmode mode = ios_base::out);
7681
  explicit basic_ofstream(const filesystem::path::value_type* s,
7682
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
7683
  ```
7684
 
7685
  *Effects:* Initializes the base class with
7686
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream.cons]] and
7687
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
7688
  `rdbuf()->open(s, mode | ios_base::out)`. If that function returns a
7689
  null pointer, calls `setstate(failbit)`.
7690
 
7691
  ``` cpp
7692
  explicit basic_ofstream(const string& s,
7693
  ios_base::openmode mode = ios_base::out);
7694
  ```
7695
 
7696
+ *Effects:* Equivalent to `basic_ofstream(s.c_str(), mode)`.
7697
 
7698
  ``` cpp
7699
  template<class T>
7700
  explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
7701
  ```
7702
 
7703
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7704
 
7705
+ *Effects:* Equivalent to `basic_ofstream(s.c_str(), mode)`.
7706
 
7707
  ``` cpp
7708
  basic_ofstream(basic_ofstream&& rhs);
7709
  ```
7710
 
7711
  *Effects:* Move constructs the base class, and the contained
7712
  `basic_filebuf`. Then calls
7713
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
7714
+ install the contained `basic_filebuf`.
7715
 
7716
  #### Swap <a id="ofstream.swap">[[ofstream.swap]]</a>
7717
 
7718
  ``` cpp
7719
  void swap(basic_ofstream& rhs);
7720
  ```
7721
 
7722
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7723
+ `basic_ostream<charT, traits>::swap(rhs)` and
7724
+ *`sb`*`.swap(rhs.`*`sb`*`)`.
7725
 
7726
  ``` cpp
7727
  template<class charT, class traits>
7728
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
7729
  ```
7730
 
7731
+ *Effects:* Equivalent to `x.swap(y)`.
7732
 
7733
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
7734
 
7735
  ``` cpp
7736
  basic_filebuf<charT, traits>* rdbuf() const;
7737
  ```
7738
 
7739
+ *Returns:*
7740
+ `const_cast<basic_filebuf<charT, traits>*>(addressof(`*`sb`*`))`.
7741
+
7742
+ ``` cpp
7743
+ native_handle_type native_handle() const noexcept;
7744
+ ```
7745
+
7746
+ *Effects:* Equivalent to: `return rdbuf()->native_handle();`
7747
 
7748
  ``` cpp
7749
  bool is_open() const;
7750
  ```
7751
 
 
7785
  namespace std {
7786
  template<class charT, class traits = char_traits<charT>>
7787
  class basic_fstream : public basic_iostream<charT, traits> {
7788
  public:
7789
  using char_type = charT;
7790
+ using int_type = traits::int_type;
7791
+ using pos_type = traits::pos_type;
7792
+ using off_type = traits::off_type;
7793
  using traits_type = traits;
7794
+ using native_handle_type = basic_filebuf<charT, traits>::native_handle_type;
7795
 
7796
  // [fstream.cons], constructors
7797
  basic_fstream();
7798
  explicit basic_fstream(
7799
  const char* s,
 
7815
  // [fstream.swap], swap
7816
  void swap(basic_fstream& rhs);
7817
 
7818
  // [fstream.members], members
7819
  basic_filebuf<charT, traits>* rdbuf() const;
7820
+ native_handle_type native_handle() const noexcept;
7821
+
7822
  bool is_open() const;
7823
  void open(
7824
  const char* s,
7825
  ios_base::openmode mode = ios_base::in | ios_base::out);
7826
  void open(
 
7843
  The class template `basic_fstream<charT, traits>` supports reading and
7844
  writing from named files. It uses a `basic_filebuf<charT, traits>`
7845
  object to control the associated sequences. For the sake of exposition,
7846
  the maintained data is presented here as:
7847
 
7848
+ - *`sb`*, the `basic_filebuf` object.
7849
 
7850
  #### Constructors <a id="fstream.cons">[[fstream.cons]]</a>
7851
 
7852
  ``` cpp
7853
  basic_fstream();
7854
  ```
7855
 
7856
  *Effects:* Initializes the base class with
7857
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
7858
+ and *sb* with `basic_filebuf<charT, traits>()`.
7859
 
7860
  ``` cpp
7861
  explicit basic_fstream(
7862
  const char* s,
7863
  ios_base::openmode mode = ios_base::in | ios_base::out);
 
7865
  const filesystem::path::value_type* s,
7866
  ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
7867
  ```
7868
 
7869
  *Effects:* Initializes the base class with
7870
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
7871
+ and *sb* with `basic_filebuf<charT, traits>()`. Then calls
7872
  `rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
7873
  `setstate(failbit)`.
7874
 
7875
  ``` cpp
7876
  explicit basic_fstream(
7877
  const string& s,
7878
  ios_base::openmode mode = ios_base::in | ios_base::out);
7879
  ```
7880
 
7881
+ *Effects:* Equivalent to `basic_fstream(s.c_str(), mode)`.
7882
 
7883
  ``` cpp
7884
  template<class T>
7885
  explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
7886
  ```
7887
 
7888
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7889
 
7890
+ *Effects:* Equivalent to `basic_fstream(s.c_str(), mode)`.
7891
 
7892
  ``` cpp
7893
  basic_fstream(basic_fstream&& rhs);
7894
  ```
7895
 
7896
  *Effects:* Move constructs the base class, and the contained
7897
  `basic_filebuf`. Then calls
7898
+ `basic_istream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
7899
+ install the contained `basic_filebuf`.
7900
 
7901
  #### Swap <a id="fstream.swap">[[fstream.swap]]</a>
7902
 
7903
  ``` cpp
7904
  void swap(basic_fstream& rhs);
7905
  ```
7906
 
7907
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7908
+ `basic_iostream<charT,traits>::swap(rhs)` and
7909
+ *`sb`*`.swap(rhs.`*`sb`*`)`.
7910
 
7911
  ``` cpp
7912
  template<class charT, class traits>
7913
  void swap(basic_fstream<charT, traits>& x,
7914
  basic_fstream<charT, traits>& y);
7915
  ```
7916
 
7917
+ *Effects:* Equivalent to `x.swap(y)`.
7918
 
7919
  #### Member functions <a id="fstream.members">[[fstream.members]]</a>
7920
 
7921
  ``` cpp
7922
  basic_filebuf<charT, traits>* rdbuf() const;
7923
  ```
7924
 
7925
+ *Returns:*
7926
+ `const_cast<basic_filebuf<charT, traits>*>(addressof(`*`sb`*`))`.
7927
+
7928
+ ``` cpp
7929
+ native_handle_type native_handle() const noexcept;
7930
+ ```
7931
+
7932
+ *Effects:* Equivalent to: `return rdbuf()->native_handle();`
7933
 
7934
  ``` cpp
7935
  bool is_open() const;
7936
  ```
7937
 
 
7976
 
7977
  ``` cpp
7978
  #include <ostream> // see [ostream.syn]
7979
 
7980
  namespace std {
7981
+ // [syncstream.syncbuf], class template basic_syncbuf
7982
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7983
  class basic_syncbuf;
7984
 
7985
  // [syncstream.syncbuf.special], specialized algorithms
7986
  template<class charT, class traits, class Allocator>
 
7988
  basic_syncbuf<charT, traits, Allocator>&);
7989
 
7990
  using syncbuf = basic_syncbuf<char>;
7991
  using wsyncbuf = basic_syncbuf<wchar_t>;
7992
 
7993
+ // [syncstream.osyncstream], class template basic_osyncstream
7994
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7995
  class basic_osyncstream;
7996
 
7997
  using osyncstream = basic_osyncstream<char>;
7998
  using wosyncstream = basic_osyncstream<wchar_t>;
 
8010
  namespace std {
8011
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
8012
  class basic_syncbuf : public basic_streambuf<charT, traits> {
8013
  public:
8014
  using char_type = charT;
8015
+ using int_type = traits::int_type;
8016
+ using pos_type = traits::pos_type;
8017
+ using off_type = traits::off_type;
8018
  using traits_type = traits;
8019
  using allocator_type = Allocator;
8020
 
8021
  using streambuf_type = basic_streambuf<charT, traits>;
8022
 
 
8043
  // [syncstream.syncbuf.virtuals], overridden virtual functions
8044
  int sync() override;
8045
 
8046
  private:
8047
  streambuf_type* wrapped; // exposition only
8048
+ bool emit-on-sync{}; // exposition only
8049
  };
8050
  }
8051
  ```
8052
 
8053
  Class template `basic_syncbuf` stores character data written to it,
 
8062
 
8063
  ``` cpp
8064
  basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
8065
  ```
8066
 
8067
+ *Effects:* Sets *wrapped* to `obuf`.
8068
 
8069
  *Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
8070
  are `true`.
8071
 
8072
  *Throws:* Nothing unless an exception is thrown by the construction of a
 
8137
  ``` cpp
8138
  bool emit();
8139
  ```
8140
 
8141
  *Effects:* Atomically transfers the associated output of `*this` to the
8142
+ stream buffer `*`*`wrapped`*, so that it appears in the output stream as
8143
+ a contiguous sequence of characters. *`wrapped`*`->pubsync()` is called
8144
+ if and only if a call was made to `sync()` since the most recent call to
8145
  `emit()`, if any.
8146
 
8147
  *Synchronization:* All `emit()` calls transferring characters to the
8148
  same stream buffer object appear to execute in a total order consistent
8149
  with the “happens before” relation [[intro.races]], where each `emit()`
 
8152
  *Ensures:* On success, the associated output is empty.
8153
 
8154
  *Returns:* `true` if all of the following conditions hold; otherwise
8155
  `false`:
8156
 
8157
+ - *`wrapped`*` == nullptr` is `false`.
8158
  - All of the characters in the associated output were successfully
8159
  transferred.
8160
+ - The call to *`wrapped`*`->pubsync()` (if any) succeeded.
8161
 
8162
+ *Remarks:* May call member functions of *wrapped* while holding a lock
8163
+ uniquely associated with *wrapped*.
8164
 
8165
  ``` cpp
8166
  streambuf_type* get_wrapped() const noexcept;
8167
  ```
8168
 
8169
+ *Returns:* *wrapped*.
8170
 
8171
  ``` cpp
8172
  allocator_type get_allocator() const noexcept;
8173
  ```
8174
 
 
8177
 
8178
  ``` cpp
8179
  void set_emit_on_sync(bool b) noexcept;
8180
  ```
8181
 
8182
+ *Effects:* *`emit-on-sync`*` = b`.
8183
 
8184
  #### Overridden virtual functions <a id="syncstream.syncbuf.virtuals">[[syncstream.syncbuf.virtuals]]</a>
8185
 
8186
  ``` cpp
8187
  int sync() override;
8188
  ```
8189
 
8190
  *Effects:* Records that the wrapped stream buffer is to be flushed.
8191
+ Then, if *emit-on-sync* is `true`, calls `emit()`.
8192
 
8193
+ [*Note 1*: If *emit-on-sync* is `false`, the actual flush is delayed
8194
  until a call to `emit()`. — *end note*]
8195
 
8196
  *Returns:* If `emit()` was called and returned `false`, returns `-1`;
8197
  otherwise `0`.
8198
 
 
8214
  namespace std {
8215
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
8216
  class basic_osyncstream : public basic_ostream<charT, traits> {
8217
  public:
8218
  using char_type = charT;
8219
+ using int_type = traits::int_type;
8220
+ using pos_type = traits::pos_type;
8221
+ using off_type = traits::off_type;
8222
  using traits_type = traits;
8223
 
8224
  using allocator_type = Allocator;
8225
  using streambuf_type = basic_streambuf<charT, traits>;
8226
  using syncbuf_type = basic_syncbuf<charT, traits, Allocator>;
 
8285
 
8286
  ``` cpp
8287
  basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
8288
  ```
8289
 
8290
+ *Effects:* Initializes *sb* from `buf` and `allocator`. Initializes the
8291
+ base class with `basic_ostream<charT, traits>(addressof(`*`sb`*`))`.
8292
 
8293
  [*Note 1*: The member functions of the provided stream buffer can be
8294
  called from `emit()` while a lock is held, which might result in a
8295
  deadlock if used incautiously. — *end note*]
8296
 
 
8298
 
8299
  ``` cpp
8300
  basic_osyncstream(basic_osyncstream&& other) noexcept;
8301
  ```
8302
 
8303
+ *Effects:* Move constructs the base class and *sb* from the
8304
  corresponding subobjects of `other`, and calls
8305
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))`.
8306
 
8307
  *Ensures:* The value returned by `get_wrapped()` is the value returned
8308
  by `other.get_wrapped()` prior to calling this constructor.
8309
  `nullptr == other.get_wrapped()` is `true`.
8310
 
 
8314
  void emit();
8315
  ```
8316
 
8317
  *Effects:* Behaves as an unformatted output
8318
  function [[ostream.unformatted]]. After constructing a `sentry` object,
8319
+ calls *`sb`*`.emit()`. If that call returns `false`, calls
8320
  `setstate(ios_base::badbit)`.
8321
 
8322
  [*Example 1*:
8323
 
8324
  A flush on a `basic_osyncstream` does not flush immediately:
 
8357
 
8358
  ``` cpp
8359
  streambuf_type* get_wrapped() const noexcept;
8360
  ```
8361
 
8362
+ *Returns:* *`sb`*`.get_wrapped()`.
8363
 
8364
  [*Example 3*:
8365
 
8366
  Obtaining the wrapped stream buffer with `get_wrapped()` allows wrapping
8367
  it again with an `osyncstream`. For example,
 
8714
 
8715
  path weakly_canonical(const path& p);
8716
  path weakly_canonical(const path& p, error_code& ec);
8717
  }
8718
 
8719
+ namespace std {
8720
+ // [fs.path.fmtr], formatting support
8721
+ template<class charT> struct formatter<filesystem::path, charT>;
8722
+
8723
  // [fs.path.hash], hash support
 
8724
  template<class T> struct hash;
8725
  template<> struct hash<filesystem::path>;
8726
  }
8727
 
8728
  namespace std::ranges {
8729
  template<>
8730
+ inline constexpr bool \libspec{enable_borrowed_range}{directory_iterator}<filesystem::directory_iterator> = true;
8731
  template<>
8732
+ inline constexpr bool \libspec{enable_borrowed_range}{recursive_directory_iterator}<filesystem::recursive_directory_iterator> = true;
8733
 
8734
  template<>
8735
+ inline constexpr bool \libspec{enable_view}{directory_iterator}<filesystem::directory_iterator> = true;
8736
  template<>
8737
+ inline constexpr bool \libspec{enable_view}{recursive_directory_iterator}<filesystem::recursive_directory_iterator> = true;
8738
  }
8739
  ```
8740
 
8741
  Implementations should ensure that the resolution and range of
8742
  `file_time_type` reflect the operating system dependent resolution and
 
8826
 
8827
  *Pathname resolution* is the operating system dependent mechanism for
8828
  resolving a pathname to a particular file in a file hierarchy. There may
8829
  be multiple pathnames that resolve to the same file.
8830
 
8831
+ [*Example 1*: For POSIX-based operating systems, this mechanism is
8832
+ specified in POSIX, section 4.12, Pathname resolution. — *end example*]
8833
 
8834
  ``` cpp
8835
  namespace std::filesystem {
8836
  class path {
8837
  public:
 
8914
 
8915
  template<class EcharT, class traits = char_traits<EcharT>,
8916
  class Allocator = allocator<EcharT>>
8917
  basic_string<EcharT, traits, Allocator>
8918
  string(const Allocator& a = Allocator()) const;
8919
+ std::string display_string() const;
8920
+ std::string system_encoded_string() const;
8921
  std::wstring wstring() const;
8922
  std::u8string u8string() const;
8923
  std::u16string u16string() const;
8924
  std::u32string u32string() const;
8925
 
8926
  // [fs.path.generic.obs], generic format observers
8927
  template<class EcharT, class traits = char_traits<EcharT>,
8928
  class Allocator = allocator<EcharT>>
8929
  basic_string<EcharT, traits, Allocator>
8930
  generic_string(const Allocator& a = Allocator()) const;
8931
+ std::string generic_display_string() const;
8932
+ std::string generic_system_encoded_string() const;
8933
  std::wstring generic_wstring() const;
8934
  std::u8string generic_u8string() const;
8935
  std::u16string generic_u16string() const;
8936
  std::u32string generic_u32string() const;
8937
 
 
8950
  path filename() const;
8951
  path stem() const;
8952
  path extension() const;
8953
 
8954
  // [fs.path.query], query
8955
+ bool empty() const noexcept;
8956
  bool has_root_name() const;
8957
  bool has_root_directory() const;
8958
  bool has_root_path() const;
8959
  bool has_relative_path() const;
8960
  bool has_parent_path() const;
 
9144
  path.
9145
 
9146
  [*Note 2*: Some operating systems have no unambiguous way to
9147
  distinguish between native format and generic format arguments. This is
9148
  by design as it simplifies use for operating systems that do not require
9149
+ disambiguation. It is possible that an implementation for an operating
9150
+ system where disambiguation is needed distinguishes between the
9151
  formats. — *end note*]
9152
 
9153
  Pathnames are converted as needed between the generic and native formats
9154
  in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
9155
  mathematical sense be the implementation’s functions that convert
 
9235
  \[`source.begin()`, `source.end()`).
9236
  - `basic_string_view<EcharT, traits>`. A function argument
9237
  `const Source&` `source` shall have an effective range
9238
  \[`source.begin()`, `source.end()`).
9239
  - A type meeting the *Cpp17InputIterator* requirements that iterates
9240
+ over an NTCTS. The value type shall be an encoded character type. A
9241
  function argument `const Source&` `source` shall have an effective
9242
  range \[`source`, `end`) where `end` is the first iterator value with
9243
  an element value equal to `iterator_traits<Source>::value_type()`.
9244
  - A character array that after array-to-pointer decay results in a
9245
+ pointer to the start of an NTCTS. The value type shall be an encoded
9246
  character type. A function argument `const Source&` `source` shall
9247
  have an effective range \[`source`, `end`) where `end` is the first
9248
  iterator value with an element value equal to
9249
  `iterator_traits<decay_t<Source>>::value_type()`.
9250
 
 
9270
 
9271
  ``` cpp
9272
  path() noexcept;
9273
  ```
9274
 
9275
+ *Ensures:* `empty()` is `true`.
9276
 
9277
  ``` cpp
9278
  path(const path& p);
9279
  path(path&& p) noexcept;
9280
  ```
 
9518
 
9519
  ``` cpp
9520
  void clear() noexcept;
9521
  ```
9522
 
9523
+ *Ensures:* `empty()` is `true`.
9524
 
9525
  ``` cpp
9526
  path& make_preferred();
9527
  ```
9528
 
 
9647
  ```
9648
 
9649
  *Returns:* `native()`.
9650
 
9651
  ``` cpp
9652
+ template<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>>
9653
+ basic_string<EcharT, traits, Allocator> string(const Allocator& a = Allocator()) const;
 
 
9654
  ```
9655
 
9656
  *Returns:* `native()`.
9657
 
9658
  *Remarks:* All memory allocation, including for the return value, shall
9659
  be performed by `a`. Conversion, if any, is specified by
9660
  [[fs.path.cvt]].
9661
 
9662
  ``` cpp
9663
+ std::string system_encoded_string() const;
9664
  std::wstring wstring() const;
9665
  std::u8string u8string() const;
9666
  std::u16string u16string() const;
9667
  std::u32string u32string() const;
9668
  ```
 
9670
  *Returns:* `native()`.
9671
 
9672
  *Remarks:* Conversion, if any, is performed as specified by
9673
  [[fs.path.cvt]].
9674
 
9675
+ ``` cpp
9676
+ std::string display_string() const;
9677
+ ```
9678
+
9679
+ *Returns:* `std::format("{}", *this)`.
9680
+
9681
+ [*Note 3*: The returned string is suitable for use with
9682
+ formatting [[format.functions]] and print
9683
+ functions [[print.fun]]. — *end note*]
9684
+
9685
  ##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
9686
 
9687
  Generic format observer functions return strings formatted according to
9688
  the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
9689
  character is used as the *directory-separator*.
 
9699
  returns `"foo/bar"`.
9700
 
9701
  — *end example*]
9702
 
9703
  ``` cpp
9704
+ template<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>>
9705
+ basic_string<EcharT, traits, Allocator> generic_string(const Allocator& a = Allocator()) const;
 
 
9706
  ```
9707
 
9708
  *Returns:* The pathname in the generic format.
9709
 
9710
  *Remarks:* All memory allocation, including for the return value, shall
9711
  be performed by `a`. Conversion, if any, is specified by
9712
  [[fs.path.cvt]].
9713
 
9714
  ``` cpp
9715
+ std::string generic_system_encoded_string() const;
9716
  std::wstring generic_wstring() const;
9717
  std::u8string generic_u8string() const;
9718
  std::u16string generic_u16string() const;
9719
  std::u32string generic_u32string() const;
9720
  ```
9721
 
9722
  *Returns:* The pathname in the generic format.
9723
 
9724
  *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]].
9725
 
9726
+ ``` cpp
9727
+ std::string generic_display_string() const;
9728
+ ```
9729
+
9730
+ *Returns:* `std::format("{:g}", *this)`.
9731
+
9732
+ [*Note 4*: The returned string is suitable for use with
9733
+ formatting [[format.functions]] and print
9734
+ functions [[print.fun]]. — *end note*]
9735
+
9736
  ##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
9737
 
9738
  ``` cpp
9739
  int compare(const path& p) const noexcept;
9740
  ```
 
9865
  path("..bar").extension(); // yields ".bar" and stem() is "."
9866
  ```
9867
 
9868
  — *end example*]
9869
 
9870
+ [*Note 5*: The period is included in the return value so that it is
9871
  possible to distinguish between no extension and an empty
9872
  extension. — *end note*]
9873
 
9874
+ [*Note 6*: On non-POSIX operating systems, for a path `p`, it is
9875
  possible that `p.stem() + p.extension() == p.filename()` is `false`,
9876
  even though the generic format pathnames are the same. — *end note*]
9877
 
9878
  ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
9879
 
9880
  ``` cpp
9881
+ bool empty() const noexcept;
9882
  ```
9883
 
9884
  *Returns:* `true` if the pathname in the generic format is empty,
9885
  otherwise `false`.
9886
 
 
9984
  - any *filename* in `relative_path()` or `base.relative_path()` can be
9985
  interpreted as a *root-name*,
9986
 
9987
  returns `path()`.
9988
 
9989
+ [*Note 7*: On a POSIX implementation, no *filename* in a
9990
  *relative-path* is acceptable as a *root-name*. — *end note*]
9991
 
9992
  Determines the first mismatched element of `*this` and `base` as if by:
9993
 
9994
  ``` cpp
 
10027
  *directory-separator* characters will be backslashes rather than
10028
  slashes, but that does not affect `path` equality.
10029
 
10030
  — *end example*]
10031
 
10032
+ [*Note 8*: If symlink following semantics are desired, use the
10033
  operational function `relative()`. — *end note*]
10034
 
10035
+ [*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
10036
  consistent matching of elements, apply `lexically_normal()` to `*this`,
10037
  `base`, or both. — *end note*]
10038
 
10039
  ``` cpp
10040
  path lexically_proximate(const path& base) const;
10041
  ```
10042
 
10043
  *Returns:* If the value of `lexically_relative(base)` is not an empty
10044
  path, return it. Otherwise return `*this`.
10045
 
10046
+ [*Note 10*: If symlink following semantics are desired, use the
10047
  operational function `proximate()`. — *end note*]
10048
 
10049
+ [*Note 11*: If normalization [[fs.path.generic]] is needed to ensure
10050
  consistent matching of elements, apply `lexically_normal()` to `*this`,
10051
  `base`, or both. — *end note*]
10052
 
10053
  #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
10054
 
 
10066
 
10067
  For the elements of the pathname in the generic format, the forward
10068
  traversal order is as follows:
10069
 
10070
  - The *root-name* element, if present.
10071
+ - The *root-directory* element, if present. \[*Note 1*: It is possible
10072
+ that the use of the generic format is needed to ensure correct
10073
+ lexicographical comparison. — *end note*]
10074
  - Each successive *filename* element, if present.
10075
  - An empty element, if a trailing non-root *directory-separator* is
10076
  present.
10077
 
10078
  The backward traversal order is the reverse of forward traversal.
 
10167
  friend path operator/(const path& lhs, const path& rhs);
10168
  ```
10169
 
10170
  *Effects:* Equivalent to: `return path(lhs) /= rhs;`
10171
 
10172
+ #### Formatting support <a id="fs.path.fmtr">[[fs.path.fmtr]]</a>
10173
+
10174
+ ##### Formatting support overview <a id="fs.path.fmtr.general">[[fs.path.fmtr.general]]</a>
10175
+
10176
+ ``` cpp
10177
+ namespace std {
10178
+ template<class charT> struct formatter<filesystem::path, charT> {
10179
+ constexpr void set_debug_format();
10180
+
10181
+ constexpr typename basic_format_parse_context<charT>::iterator
10182
+ parse(basic_format_parse_context<charT>& ctx);
10183
+
10184
+ template<class FormatContext>
10185
+ typename FormatContext::iterator
10186
+ format(const filesystem::path& path, FormatContext& ctx) const;
10187
+ };
10188
+ }
10189
+ ```
10190
+
10191
+ ##### Formatting support functions <a id="fs.path.fmtr.funcs">[[fs.path.fmtr.funcs]]</a>
10192
+
10193
+ Formatting of paths uses formatting specifiers of the form
10194
+
10195
+ ``` bnf
10196
+ path-format-spec:
10197
+ fill-and-alignₒₚₜ widthₒₚₜ '?'ₒₚₜ 'g'ₒₚₜ
10198
+ ```
10199
+
10200
+ where the productions *fill-and-align* and *width* are described in
10201
+ [[format.string]]. If the `?` option is used then the path is formatted
10202
+ as an escaped string [[format.string.escaped]].
10203
+
10204
+ ``` cpp
10205
+ constexpr void set_debug_format();
10206
+ ```
10207
+
10208
+ *Effects:* Modifies the state of the `formatter` to be as if the
10209
+ *path-format-spec* parsed by the last call to `parse` contained the `?`
10210
+ option.
10211
+
10212
+ ``` cpp
10213
+ constexpr typename basic_format_parse_context<charT>::iterator
10214
+ parse(basic_format_parse_context<charT>& ctx);
10215
+ ```
10216
+
10217
+ *Effects:* Parses the format specifier as a *path-format-spec* and
10218
+ stores the parsed specifiers in `*this`.
10219
+
10220
+ *Returns:* An iterator past the end of the *path-format-spec*.
10221
+
10222
+ ``` cpp
10223
+ template<class FormatContext>
10224
+ typename FormatContext::iterator
10225
+ format(const filesystem::path& p, FormatContext& ctx) const;
10226
+ ```
10227
+
10228
+ *Effects:* Let `s` be `p.generic_string<filesystem::path::value_type>()`
10229
+ if the `g` option is used, otherwise `p.native()`. Writes `s` into
10230
+ `ctx.out()`, adjusted according to the *path-format-spec*. If `charT` is
10231
+ `char`, `path::value_type` is `wchar_t`, and the literal encoding is
10232
+ UTF-8, then the escaped path is transcoded from the native encoding for
10233
+ wide character strings to UTF-8 with maximal subparts of ill-formed
10234
+ subsequences substituted with ‘U+fffd‘ replacement character per the
10235
+ Unicode Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion. If
10236
+ `charT` and `path::value_type` are the same then no transcoding is
10237
+ performed. Otherwise, transcoding is *implementation-defined*.
10238
+
10239
+ *Returns:* An iterator past the end of the output range.
10240
+
10241
  #### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
10242
 
10243
  ``` cpp
10244
  template<> struct hash<filesystem::path>;
10245
  ```
 
10282
  filesystem_error(const string& what_arg, error_code ec);
10283
  ```
10284
 
10285
  *Ensures:*
10286
 
10287
+ - `code() == ec` is `true`,
10288
+ - `path1().empty()` is `true`,
10289
+ - `path2().empty()` is `true`, and
10290
+ - `string_view(what()).find(what_arg.c_str())` `!= string_view::npos` is
10291
+ `true`.
10292
 
10293
  ``` cpp
10294
  filesystem_error(const string& what_arg, const path& p1, error_code ec);
10295
  ```
10296
 
10297
  *Ensures:*
10298
 
10299
+ - `code() == ec` is `true`,
10300
  - `path1()` returns a reference to the stored copy of `p1`,
10301
+ - `path2().empty()` is `true`, and
10302
+ - `string_view(what()).find(what_arg.c_str())` `!= string_view::npos` is
10303
+ `true`.
10304
 
10305
  ``` cpp
10306
  filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
10307
  ```
10308
 
 
10359
  constants are distinct.
10360
 
10361
  **Table: Enum class `file_type`** <a id="fs.enum.file.type">[fs.enum.file.type]</a>
10362
 
10363
  | Constant | Meaning |
10364
+ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10365
  | `none` | The type of the file has not been determined or an error occurred while trying to determine the type. |
10366
  | `not_found` | Pseudo-type indicating the file was not found. *The file not being found is not considered an error while determining the type of a file.* |
10367
  | `regular` | Regular file |
10368
  | `directory` | Directory file |
10369
  | `symlink` | Symbolic link file |
 
10386
  Every other constant in the table represents a distinct bitmask element.
10387
 
10388
  **Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
10389
 
10390
  | Constant | Meaning |
10391
+ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
10392
  | `none` | (Default) Error; file already exists. |
10393
  | `skip_existing` | Do not overwrite existing file, do not report an error. |
10394
  | `overwrite_existing` | Overwrite the existing file. |
10395
  | `update_existing` | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for subdirectories} |
10396
  | `recursive` | Recursively copy subdirectories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links} |
 
10408
  meanings listed in [[fs.enum.perms]].
10409
 
10410
  **Table: Enum class `perms`** <a id="fs.enum.perms">[fs.enum.perms]</a>
10411
 
10412
  | Name | Value (octal) | POSIX macro | Definition or notes |
10413
+ | --------------------------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
10414
  | `none` | `0` | | There are no permissions set for the file. |
10415
  | `owner_read` | `0400` | `S_IRUSR` | Read permission, owner |
10416
  | `owner_write` | `0200` | `S_IWUSR` | Write permission, owner |
10417
  | `owner_exec` | `0100` | `S_IXUSR` | Execute/search permission, owner |
10418
  | `owner_all` | `0700` | `S_IRWXU` | Read, write, execute/search by owner;<br> `owner_read | owner_write | owner_exec` |
 
10442
  `permissions`.
10443
 
10444
  **Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
10445
 
10446
  | Name | Meaning |
10447
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
10448
  | `replace` | `permissions` shall replace the file's permission bits with `perm` |
10449
  | `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{or} of `perm` and the file's current permission bits. |
10450
  | `remove` | `permissions` shall replace the file's permission bits with the bitwise \logop{and} of the complement of `perm` and the file's current permission bits. |
10451
  | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
10452
 
 
10460
  every other constant in the table represents a distinct bitmask element.
10461
 
10462
  **Table: Enum class `directory_options`** <a id="fs.enum.dir.opts">[fs.enum.dir.opts]</a>
10463
 
10464
  | Name | Meaning |
10465
+ | --------------------------------------------------------- | ------------------------------------------------------------------ |
10466
  | `none` | (Default) Skip directory symlinks, permission denied is an error. |
10467
  | `follow_directory_symlink` | Follow rather than skip directory symlinks. |
10468
  | `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
10469
 
10470
 
 
10609
  template<class charT, class traits>
10610
  friend basic_ostream<charT, traits>&
10611
  operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
10612
 
10613
  private:
10614
+ filesystem::path path-object; // exposition only
 
10615
  };
10616
  }
10617
  ```
10618
 
10619
  A `directory_entry` object stores a `path` object and may store
 
10624
  directory iteration if their values are available and storing the values
10625
  would allow the implementation to eliminate file system accesses by
10626
  `directory_entry` observer functions [[fs.op.funcs]]. Such stored file
10627
  attribute values are said to be *cached*.
10628
 
10629
+ [*Note 1*: `directory_iterator` can cache already available attribute
10630
+ values directly into a `directory_entry` object without the cost of a
10631
+ call to `refresh()`. *end note*]
 
 
 
10632
 
10633
  [*Example 1*:
10634
 
10635
  ``` cpp
10636
  using namespace std::filesystem;
 
10679
  ``` cpp
10680
  void assign(const filesystem::path& p);
10681
  void assign(const filesystem::path& p, error_code& ec);
10682
  ```
10683
 
10684
+ *Effects:* Equivalent to *`path-object`*` = p`, then `refresh()` or
10685
  `refresh(ec)`, respectively. If an error occurs, the values of any
10686
  cached attributes are unspecified.
10687
 
10688
  *Throws:* As specified in  [[fs.err.report]].
10689
 
10690
  ``` cpp
10691
  void replace_filename(const filesystem::path& p);
10692
  void replace_filename(const filesystem::path& p, error_code& ec);
10693
  ```
10694
 
10695
+ *Effects:* Equivalent to *`path-object`*`.replace_filename(p)`, then
10696
  `refresh()` or `refresh(ec)`, respectively. If an error occurs, the
10697
  values of any cached attributes are unspecified.
10698
 
10699
  *Throws:* As specified in  [[fs.err.report]].
10700
 
 
10724
  ``` cpp
10725
  const filesystem::path& path() const noexcept;
10726
  operator const filesystem::path&() const noexcept;
10727
  ```
10728
 
10729
+ *Returns:* *path-object*.
10730
 
10731
  ``` cpp
10732
  bool exists() const;
10733
  bool exists(error_code& ec) const noexcept;
10734
  ```
 
10872
 
10873
  ``` cpp
10874
  bool operator==(const directory_entry& rhs) const noexcept;
10875
  ```
10876
 
10877
+ *Returns:* *`path-object`*` == rhs.`*`path-object`*.
10878
 
10879
  ``` cpp
10880
  strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
10881
  ```
10882
 
10883
+ *Returns:* *`path-object`*` <=> rhs.`*`path-object`*.
10884
 
10885
  #### Inserter <a id="fs.dir.entry.io">[[fs.dir.entry.io]]</a>
10886
 
10887
  ``` cpp
10888
  template<class charT, class traits>
 
10973
  `directory_entry` element returned by `operator*()`.
10974
  `directory_iterator` member functions shall not directly or indirectly
10975
  call any `directory_entry` `refresh` function.
10976
 
10977
  [*Note 2*: The exact mechanism for storing cached attribute values is
10978
+ not exposed to users. *end note*]
 
 
10979
 
10980
  [*Note 3*: A path obtained by dereferencing a directory iterator might
10981
  not actually exist; it could be a symbolic link to a non-existent file.
10982
  Recursively walking directory trees for purposes of removing and
10983
  renaming entries might invalidate symbolic links that are being
 
11309
  void disable_recursion_pending();
11310
  ```
11311
 
11312
  *Ensures:* `recursion_pending() == false`.
11313
 
11314
+ [*Note 4*: `disable_recursion_pending()` is used to prevent unwanted
11315
  recursion into a directory. — *end note*]
11316
 
11317
  #### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
11318
 
11319
  These functions enable use of `recursive_directory_iterator` with
 
11439
  Effects are then as follows:
11440
 
11441
  - If `f.type()` or `t.type()` is an implementation-defined file
11442
  type [[fs.enum.file.type]], then the effects are
11443
  *implementation-defined*.
11444
+ - Otherwise, an error is reported as specified in  [[fs.err.report]] if
11445
  - `exists(f)` is `false`, or
11446
  - `equivalent(from, to)` is `true`, or
11447
  - `is_other(f) || is_other(t)` is `true`, or
11448
  - `is_directory(f) && is_regular_file(t)` is `true`.
11449
  - Otherwise, if `is_symlink(f)`, then:
 
11506
 
11507
  [*Example 1*:
11508
 
11509
  Given this directory structure:
11510
 
11511
+ ``` text
11512
  /dir1
11513
  file1
11514
  file2
11515
  dir2
11516
  file3
11517
  ```
11518
 
11519
  Calling `copy("/dir1", "/dir3")` would result in:
11520
 
11521
+ ``` text
11522
  /dir1
11523
  file1
11524
  file2
11525
  dir2
11526
  file3
 
11530
  ```
11531
 
11532
  Alternatively, calling `copy("/dir1", "/dir3", copy_options::recursive)`
11533
  would result in:
11534
 
11535
+ ``` text
11536
  /dir1
11537
  file1
11538
  file2
11539
  dir2
11540
  file3
 
11568
  *Preconditions:* At most one element from each option
11569
  group [[fs.enum.copy.opts]] is set in `options`.
11570
 
11571
  *Effects:* As follows:
11572
 
11573
+ - Report an error as specified in  [[fs.err.report]] if
11574
  - `is_regular_file(from)` is `false`, or
11575
  - `exists(to)` is `true` and `is_regular_file(to)` is `false`, or
11576
  - `exists(to)` is `true` and `equivalent(from, to)` is `true`, or
11577
  - `exists(to)` is `true` and
11578
  ``` cpp
11579
  (options & (copy_options::skip_existing |
11580
  copy_options::overwrite_existing |
11581
  copy_options::update_existing)) == copy_options::none
11582
  ```
11583
  - Otherwise, copy the contents and attributes of the file `from`
11584
+ resolves to, to the file `to` resolves to, if
11585
  - `exists(to)` is `false`, or
11586
  - `(options & copy_options::overwrite_existing) != copy_options::none`,
11587
  or
11588
  - `(options & copy_options::update_existing) `` `` != copy_options::none`
11589
  and `from` is more recent than `to`, determined as if by use of the
 
11618
  ``` cpp
11619
  bool filesystem::create_directories(const path& p);
11620
  bool filesystem::create_directories(const path& p, error_code& ec);
11621
  ```
11622
 
11623
+ *Effects:* Calls `create_directory` for each element of `p` that does
11624
  not exist.
11625
 
11626
  *Returns:* `true` if a new directory was created for the directory `p`
11627
  resolves to, otherwise `false`.
11628
 
 
11675
  void filesystem::create_directory_symlink(const path& to, const path& new_symlink);
11676
  void filesystem::create_directory_symlink(const path& to, const path& new_symlink,
11677
  error_code& ec) noexcept;
11678
  ```
11679
 
11680
+ *Effects:* Establishes the postcondition, as if by POSIX `symlink`.
11681
 
11682
  *Ensures:* `new_symlink` resolves to a symbolic link file that contains
11683
  an unspecified representation of `to`.
11684
 
11685
  *Throws:* As specified in  [[fs.err.report]].
11686
 
11687
  [*Note 1*: Some operating systems require symlink creation to identify
11688
+ that the link is to a directory. Thus, `create_symlink` (instead of
11689
+ `create_directory_symlink`) cannot be used reliably to create directory
11690
+ symlinks. — *end note*]
11691
 
11692
  [*Note 2*: Some operating systems do not support symbolic links at all
11693
  or support them only for regular files. Some file systems (such as the
11694
  FAT file system) do not support symbolic links regardless of the
11695
  operating system. — *end note*]
 
11700
  void filesystem::create_hard_link(const path& to, const path& new_hard_link);
11701
  void filesystem::create_hard_link(const path& to, const path& new_hard_link,
11702
  error_code& ec) noexcept;
11703
  ```
11704
 
11705
+ *Effects:* Establishes the postcondition, as if by POSIX `link`.
11706
 
11707
  *Ensures:*
11708
 
11709
  - `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
11710
  - The contents of the file or directory `to` resolves to are unchanged.
 
11723
  void filesystem::create_symlink(const path& to, const path& new_symlink);
11724
  void filesystem::create_symlink(const path& to, const path& new_symlink,
11725
  error_code& ec) noexcept;
11726
  ```
11727
 
11728
+ *Effects:* Establishes the postcondition, as if by POSIX `symlink`.
11729
 
11730
  *Ensures:* `new_symlink` resolves to a symbolic link file that contains
11731
  an unspecified representation of `to`.
11732
 
11733
  *Throws:* As specified in  [[fs.err.report]].
 
11743
  path filesystem::current_path();
11744
  path filesystem::current_path(error_code& ec);
11745
  ```
11746
 
11747
  *Returns:* The absolute path of the current working directory, whose
11748
+ pathname in the native format is obtained as if by POSIX `getcwd`. The
11749
  signature with argument `ec` returns `path()` if an error occurs.
11750
 
11751
  *Throws:* As specified in  [[fs.err.report]].
11752
 
11753
  *Remarks:* The current working directory is the directory, associated
11754
  with the process, that is used as the starting location in pathname
11755
  resolution for relative paths.
11756
 
11757
+ [*Note 1*: The current path as returned by many operating systems is a
 
 
 
 
11758
  dangerous global variable and can be changed unexpectedly by third-party
11759
  or system library functions, or by another thread. — *end note*]
11760
 
11761
  ``` cpp
11762
  void filesystem::current_path(const path& p);
11763
  void filesystem::current_path(const path& p, error_code& ec) noexcept;
11764
  ```
11765
 
11766
+ *Effects:* Establishes the postcondition, as if by POSIX `chdir`.
11767
 
11768
  *Ensures:* `equivalent(p, current_path())`.
11769
 
11770
  *Throws:* As specified in  [[fs.err.report]].
11771
 
11772
+ [*Note 2*: The current path for many operating systems is a dangerous
11773
  global state and can be changed unexpectedly by third-party or system
11774
  library functions, or by another thread. — *end note*]
11775
 
11776
  #### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
11777
 
 
11782
 
11783
  Two paths are considered to resolve to the same file system entity if
11784
  two candidate entities reside on the same device at the same location.
11785
 
11786
  [*Note 1*: On POSIX platforms, this is determined as if by the values
11787
+ of the POSIX `stat` class, obtained as if by `stat` for the two paths,
11788
  having equal `st_dev` values and equal `st_ino` values. — *end note*]
11789
 
11790
  *Returns:* `true`, if `p1` and `p2` resolve to the same file system
11791
  entity, otherwise `false`. The signature with argument `ec` returns
11792
  `false` if an error occurs.
 
11830
 
11831
  *Returns:*
11832
 
11833
  - If `is_regular_file(p)`, the size in bytes of the file `p` resolves
11834
  to, determined as if by the value of the POSIX `stat` class member
11835
+ `st_size` obtained as if by POSIX `stat`.
11836
  - Otherwise, the result is *implementation-defined*.
11837
 
11838
  The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
11839
  an error occurs.
11840
 
 
12051
  file_time_type filesystem::last_write_time(const path& p, error_code& ec) noexcept;
12052
  ```
12053
 
12054
  *Returns:* The time of last data modification of `p`, determined as if
12055
  by the value of the POSIX `stat` class member `st_mtime` obtained as if
12056
+ by POSIX `stat`. The signature with argument `ec` returns
12057
  `file_time_type::min()` if an error occurs.
12058
 
12059
  *Throws:* As specified in  [[fs.err.report]].
12060
 
12061
  ``` cpp
 
12063
  void filesystem::last_write_time(const path& p, file_time_type new_time,
12064
  error_code& ec) noexcept;
12065
  ```
12066
 
12067
  *Effects:* Sets the time of last data modification of the file resolved
12068
+ to by `p` to `new_time`, as if by POSIX `futimens`.
12069
 
12070
  *Throws:* As specified in  [[fs.err.report]].
12071
 
12072
  [*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
12073
  specified because it does not necessarily hold for file systems with
 
12085
  `add`, or `remove` is present in `opts`.
12086
 
12087
  *Effects:* Applies the action specified by `opts` to the file `p`
12088
  resolves to, or to file `p` itself if `p` is a symbolic link and
12089
  `perm_options::nofollow` is set in `opts`. The action is applied as if
12090
+ by POSIX `fchmodat`.
12091
 
12092
  [*Note 1*: Conceptually permissions are viewed as bits, but the actual
12093
  implementation can use some other mechanism. — *end note*]
12094
 
12095
  *Throws:* As specified in  [[fs.err.report]].
 
12182
  bool filesystem::remove(const path& p);
12183
  bool filesystem::remove(const path& p, error_code& ec) noexcept;
12184
  ```
12185
 
12186
  *Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
12187
+ as if by POSIX `remove`.
12188
 
12189
  [*Note 1*: A symbolic link is itself removed, rather than the file it
12190
  resolves to. — *end note*]
12191
 
12192
  *Ensures:* `exists(symlink_status(p))` is `false`.
12193
 
12194
+ *Returns:* `true` if a file `p` has been removed and `false` otherwise.
12195
+
12196
+ [*Note 2*: Absence of a file `p` is not an error. — *end note*]
12197
 
12198
  *Throws:* As specified in  [[fs.err.report]].
12199
 
12200
  #### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
12201
 
 
12203
  uintmax_t filesystem::remove_all(const path& p);
12204
  uintmax_t filesystem::remove_all(const path& p, error_code& ec);
12205
  ```
12206
 
12207
  *Effects:* Recursively deletes the contents of `p` if it exists, then
12208
+ deletes file `p` itself, as if by POSIX `remove`.
12209
 
12210
  [*Note 1*: A symbolic link is itself removed, rather than the file it
12211
  resolves to. — *end note*]
12212
 
12213
  *Ensures:* `exists(symlink_status(p))` is `false`.
 
12222
  ``` cpp
12223
  void filesystem::rename(const path& old_p, const path& new_p);
12224
  void filesystem::rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
12225
  ```
12226
 
12227
+ *Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename`.
12228
 
12229
  [*Note 1*:
12230
 
12231
  - If `old_p` and `new_p` resolve to the same existing file, no action is
12232
  taken.
 
12249
  void filesystem::resize_file(const path& p, uintmax_t new_size);
12250
  void filesystem::resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
12251
  ```
12252
 
12253
  *Effects:* Causes the size that would be returned by `file_size(p)` to
12254
+ be equal to `new_size`, as if by POSIX `truncate`.
12255
 
12256
  *Throws:* As specified in  [[fs.err.report]].
12257
 
12258
  #### Space <a id="fs.op.space">[[fs.op.space]]</a>
12259
 
 
12282
 
12283
  ``` cpp
12284
  file_status filesystem::status(const path& p);
12285
  ```
12286
 
12287
+ *Effects:* As if by:
12288
 
12289
  ``` cpp
12290
  error_code ec;
12291
  file_status result = status(p, ec);
12292
  if (result.type() == file_type::none)
 
12305
  ``` cpp
12306
  file_status filesystem::status(const path& p, error_code& ec) noexcept;
12307
  ```
12308
 
12309
  *Effects:* If possible, determines the attributes of the file `p`
12310
+ resolves to, as if by using POSIX `stat` to obtain a POSIX
12311
  `struct stat`. If, during attribute determination, the underlying file
12312
  system API reports an error, sets `ec` to indicate the specific error
12313
  reported. Otherwise, `ec.clear()`.
12314
 
12315
  [*Note 2*: This allows users to inspect the specifics of underlying API
12316
+ errors even when the value returned by `status` is not
12317
  `file_status(file_type::none)`. — *end note*]
12318
 
12319
  Let `prms` denote the result of `(m & perms::mask)`, where `m` is
12320
  determined as if by converting the `st_mode` member of the obtained
12321
  `struct stat` to the type `perms`.
 
12378
  ``` cpp
12379
  file_status filesystem::symlink_status(const path& p);
12380
  file_status filesystem::symlink_status(const path& p, error_code& ec) noexcept;
12381
  ```
12382
 
12383
+ *Effects:* Same as `status`, above, except that the attributes of `p`
12384
+ are determined as if by using POSIX `lstat` to obtain a POSIX
12385
  `struct stat`.
12386
 
12387
  Let `prms` denote the result of `(m & perms::mask)`, where `m` is
12388
  determined as if by converting the `st_mode` member of the obtained
12389
  `struct stat` to the type `perms`.
12390
 
12391
+ *Returns:* Same as `status`, above, except that if the attributes
12392
  indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
12393
  `file_status(file_type::symlink, prms)`. The signature with argument
12394
  `ec` returns `file_status(file_type::none)` if an error occurs.
12395
 
12396
  *Throws:* As specified in  [[fs.err.report]].
 
12428
  path filesystem::weakly_canonical(const path& p, error_code& ec);
12429
  ```
12430
 
12431
  *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
12432
  determine existence, return a path composed by `operator/=` from the
12433
+ result of calling `canonical` with a path argument composed of the
12434
  leading elements of `p` that exist, if any, followed by the elements of
12435
+ `p` that do not exist, if any. For the first form, `canonical` is called
12436
+ without an `error_code` argument. For the second form, `canonical` is
12437
+ called with `ec` as an `error_code` argument, and `path()` is returned
12438
+ at the first error occurrence, if any.
12439
 
12440
  *Ensures:* The returned path is in normal form [[fs.path.generic]].
12441
 
12442
  *Returns:* `p` with symlinks resolved and the result
12443
  normalized [[fs.path.generic]].
 
12447
  ## C library files <a id="c.files">[[c.files]]</a>
12448
 
12449
  ### Header `<cstdio>` synopsis <a id="cstdio.syn">[[cstdio.syn]]</a>
12450
 
12451
  ``` cpp
12452
+ #define __STDC_VERSION_STDIO_H__ 202311L
12453
+
12454
  namespace std {
12455
  using size_t = see [support.types.layout];
12456
  using FILE = see below;
12457
  using fpos_t = see below;
12458
  }
 
12463
  #define _IONBF see below
12464
  #define BUFSIZ see below
12465
  #define EOF see below
12466
  #define FOPEN_MAX see below
12467
  #define FILENAME_MAX see below
12468
+ #define _PRINTF_NAN_LEN_MAX see below
12469
  #define L_tmpnam see below
12470
  #define SEEK_CUR see below
12471
  #define SEEK_END see below
12472
  #define SEEK_SET see below
12473
  #define TMP_MAX see below
 
12525
  ```
12526
 
12527
  The contents and meaning of the header `<cstdio>` are the same as the C
12528
  standard library header `<stdio.h>`.
12529
 
12530
+ The return from each function call that delivers data to the host
12531
+ environment to be written to a file (See also: ISO C 7.23.3) is an
12532
+ observable checkpoint [[intro.abstract]].
12533
+
12534
  Calls to the function `tmpnam` with an argument that is a null pointer
12535
  value may introduce a data race [[res.on.data.races]] with other calls
12536
  to `tmpnam` with an argument that is a null pointer value.
12537
 
12538
+ See also: ISO C 7.23
12539
 
12540
  ### Header `<cinttypes>` synopsis <a id="cinttypes.syn">[[cinttypes.syn]]</a>
12541
 
12542
  ``` cpp
12543
  #include <cstdint> // see [cstdint.syn]
 
12554
 
12555
  constexpr intmax_t abs(intmax_t); // optional, see below
12556
  constexpr imaxdiv_t div(intmax_t, intmax_t); // optional, see below
12557
  }
12558
 
12559
+ #define __STDC_VERSION_INTTYPES_H__ 202311L
12560
+
12561
  #define PRIdN see below
12562
  #define PRIiN see below
12563
  #define PRIoN see below
12564
  #define PRIuN see below
12565
  #define PRIxN see below
12566
  #define PRIXN see below
12567
+ #define PRIbN see below
12568
+ #define PRIBN see below
12569
  #define SCNdN see below
12570
  #define SCNiN see below
12571
  #define SCNoN see below
12572
  #define SCNuN see below
12573
  #define SCNxN see below
12574
+ #define SCNbN see below
12575
  #define PRIdLEASTN see below
12576
  #define PRIiLEASTN see below
12577
  #define PRIoLEASTN see below
12578
  #define PRIuLEASTN see below
12579
  #define PRIxLEASTN see below
12580
  #define PRIXLEASTN see below
12581
+ #define PRIbLEASTN see below
12582
+ #define PRIBLEASTN see below
12583
  #define SCNdLEASTN see below
12584
  #define SCNiLEASTN see below
12585
  #define SCNoLEASTN see below
12586
  #define SCNuLEASTN see below
12587
  #define SCNxLEASTN see below
12588
+ #define SCNbLEASTN see below
12589
  #define PRIdFASTN see below
12590
  #define PRIiFASTN see below
12591
  #define PRIoFASTN see below
12592
  #define PRIuFASTN see below
12593
  #define PRIxFASTN see below
12594
  #define PRIXFASTN see below
12595
+ #define PRIbFASTN see below
12596
+ #define PRIBFASTN see below
12597
  #define SCNdFASTN see below
12598
  #define SCNiFASTN see below
12599
  #define SCNoFASTN see below
12600
  #define SCNuFASTN see below
12601
  #define SCNxFASTN see below
12602
+ #define SCNbFASTN see below
12603
  #define PRIdMAX see below
12604
  #define PRIiMAX see below
12605
  #define PRIoMAX see below
12606
  #define PRIuMAX see below
12607
  #define PRIxMAX see below
12608
  #define PRIXMAX see below
12609
+ #define PRIbMAX see below
12610
+ #define PRIBMAX see below
12611
  #define SCNdMAX see below
12612
  #define SCNiMAX see below
12613
  #define SCNoMAX see below
12614
  #define SCNuMAX see below
12615
  #define SCNxMAX see below
12616
+ #define SCNbMAX see below
12617
  #define PRIdPTR see below
12618
  #define PRIiPTR see below
12619
  #define PRIoPTR see below
12620
  #define PRIuPTR see below
12621
  #define PRIxPTR see below
12622
  #define PRIXPTR see below
12623
+ #define PRIbPTR see below
12624
+ #define PRIBPTR see below
12625
  #define SCNdPTR see below
12626
  #define SCNiPTR see below
12627
  #define SCNoPTR see below
12628
  #define SCNuPTR see below
12629
  #define SCNxPTR see below
12630
+ #define SCNbPTR see below
12631
  ```
12632
 
12633
  The contents and meaning of the header `<cinttypes>` are the same as the
12634
  C standard library header `<inttypes.h>`, with the following changes:
12635
 
12636
  - The header `<cinttypes>` includes the header `<cstdint>` instead of
12637
  `<stdint.h>`, and
 
 
 
12638
  - if and only if the type `intmax_t` designates an extended integer type
12639
  [[basic.fundamental]], the following function signatures are added:
12640
  ``` cpp
12641
  constexpr intmax_t abs(intmax_t);
12642
  constexpr imaxdiv_t div(intmax_t, intmax_t);
 
12651
  Each of the `PRI` macros listed in this subclause is defined if and only
12652
  if the implementation defines the corresponding *typedef-name* in 
12653
  [[cstdint.syn]]. Each of the `SCN` macros listed in this subclause is
12654
  defined if and only if the implementation defines the corresponding
12655
  *typedef-name* in  [[cstdint.syn]] and has a suitable `fscanf` length
12656
+ modifier for the type. Each of the `PRIB` macros listed in this
12657
+ subclause is defined if and only if `fprintf` supports the `B`
12658
+ conversion specifier.
12659
 
12660
  <!-- Link reference definitions -->
12661
  [adjustfield.manip]: #adjustfield.manip
12662
  [allocator.requirements.general]: library.md#allocator.requirements.general
12663
  [basefield.manip]: #basefield.manip
 
12672
  [c.files]: #c.files
12673
  [char.traits]: strings.md#char.traits
12674
  [char.traits.specializations]: strings.md#char.traits.specializations
12675
  [character.seq]: library.md#character.seq
12676
  [cinttypes.syn]: #cinttypes.syn
12677
+ [container.reqmts]: containers.md#container.reqmts
12678
  [cpp17.copyassignable]: #cpp17.copyassignable
12679
  [cpp17.copyconstructible]: #cpp17.copyconstructible
12680
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
12681
  [cpp17.destructible]: #cpp17.destructible
12682
  [cpp17.equalitycomparable]: #cpp17.equalitycomparable
12683
  [cstdint.syn]: support.md#cstdint.syn
12684
  [cstdio.syn]: #cstdio.syn
12685
+ [defns.character.container]: intro.md#defns.character.container
12686
  [defns.ntcts]: intro.md#defns.ntcts
12687
  [enumerated.types]: library.md#enumerated.types
12688
  [error.reporting]: #error.reporting
12689
  [ext.manip]: #ext.manip
12690
+ [file.native]: #file.native
12691
  [file.streams]: #file.streams
12692
  [filebuf]: #filebuf
12693
  [filebuf.assign]: #filebuf.assign
12694
  [filebuf.cons]: #filebuf.cons
12695
  [filebuf.general]: #filebuf.general
 
12699
  [filebuf.virtuals]: #filebuf.virtuals
12700
  [filesystems]: #filesystems
12701
  [floatfield.manip]: #floatfield.manip
12702
  [fmtflags.manip]: #fmtflags.manip
12703
  [fmtflags.state]: #fmtflags.state
12704
+ [format.err.report]: text.md#format.err.report
12705
+ [format.functions]: text.md#format.functions
12706
+ [format.string]: text.md#format.string
12707
+ [format.string.escaped]: text.md#format.string.escaped
12708
  [fpos]: #fpos
12709
+ [fpos.general]: #fpos.general
12710
  [fpos.members]: #fpos.members
12711
  [fpos.operations]: #fpos.operations
12712
  [fs.class.directory.entry]: #fs.class.directory.entry
12713
  [fs.class.directory.entry.general]: #fs.class.directory.entry.general
12714
  [fs.class.directory.iterator]: #fs.class.directory.iterator
 
12792
  [fs.path.concat]: #fs.path.concat
12793
  [fs.path.construct]: #fs.path.construct
12794
  [fs.path.cvt]: #fs.path.cvt
12795
  [fs.path.decompose]: #fs.path.decompose
12796
  [fs.path.fmt.cvt]: #fs.path.fmt.cvt
12797
+ [fs.path.fmtr]: #fs.path.fmtr
12798
+ [fs.path.fmtr.funcs]: #fs.path.fmtr.funcs
12799
+ [fs.path.fmtr.general]: #fs.path.fmtr.general
12800
  [fs.path.gen]: #fs.path.gen
12801
  [fs.path.generic]: #fs.path.generic
12802
  [fs.path.generic.obs]: #fs.path.generic.obs
12803
  [fs.path.hash]: #fs.path.hash
12804
  [fs.path.io]: #fs.path.io
 
12828
  [input.iterators]: iterators.md#input.iterators
12829
  [input.output]: #input.output
12830
  [input.output.general]: #input.output.general
12831
  [input.streams]: #input.streams
12832
  [input.streams.general]: #input.streams.general
12833
+ [intro.abstract]: intro.md#intro.abstract
12834
  [intro.multithread]: basic.md#intro.multithread
12835
  [intro.races]: basic.md#intro.races
12836
  [iomanip.syn]: #iomanip.syn
12837
  [ios]: #ios
12838
  [ios.base]: #ios.base
 
12893
  [istringstream.cons]: #istringstream.cons
12894
  [istringstream.general]: #istringstream.general
12895
  [istringstream.members]: #istringstream.members
12896
  [istringstream.swap]: #istringstream.swap
12897
  [lex.charset]: lex.md#lex.charset
12898
+ [locale.codecvt.virtuals]: text.md#locale.codecvt.virtuals
12899
+ [locale.num.get]: text.md#locale.num.get
12900
  [namespace.std]: library.md#namespace.std
12901
  [narrow.stream.objects]: #narrow.stream.objects
12902
  [numeric.limits]: support.md#numeric.limits
12903
  [ofstream]: #ofstream
12904
  [ofstream.cons]: #ofstream.cons
 
13013
  [views.span]: containers.md#views.span
13014
  [wide.stream.objects]: #wide.stream.objects
13015
 
13016
  [^1]: Typically `long long`.
13017
 
13018
+ [^2]: Most places where `streamsize` is used would use `size_t` in C, or
13019
+ `ssize_t` in POSIX.
13020
 
13021
  [^3]: It is the implementation’s responsibility to implement headers so
13022
  that including `<iosfwd>` and other headers does not violate the
13023
  rules about multiple occurrences of default arguments.
13024
 
 
13030
  mixed arbitrarily with operations on the corresponding stdio stream.
13031
  In practical terms, synchronization usually means that a standard
13032
  iostream object and a standard stdio object share a buffer.
13033
 
13034
  [^6]: An implementation is free to implement both the integer array
13035
+ pointed at by *iarray* and the pointer array pointed at by *parray*
13036
  as sparse data structures, possibly with a one-element cache for
13037
  each.
13038
 
13039
  [^7]: For example, because it cannot allocate space.
13040
 
 
13067
  ways to implement `xsgetn()` and `xsputn()` by overriding these
13068
  definitions from the base class.
13069
 
13070
  [^16]: That is, for each class derived from a specialization of
13071
  `basic_streambuf` in this Clause [[stringbuf]], [[filebuf]],
13072
+ a specification of how consuming a character affects the associated
13073
  output sequence is given. There is no requirement on a
13074
  program-defined class.
13075
 
13076
  [^17]: Typically, `overflow` returns `c` to indicate success, except
13077
  when `traits::eq_int_type(c, traits::eof())` returns `true`, in