From Jason Turner

[input.output]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpq_l8sgxm/{from.md → to.md} +2590 -1776
tmp/tmpq_l8sgxm/{from.md → to.md} RENAMED
@@ -7,75 +7,74 @@ input/output operations.
7
 
8
  The following subclauses describe requirements for stream parameters,
9
  and components for forward declarations of iostreams, predefined
10
  iostreams objects, base iostreams classes, stream buffering, stream
11
  formatting and manipulators, string streams, and file streams, as
12
- summarized in Table  [[tab:iostreams.lib.summary]].
13
 
14
- **Table: Input/output library summary** <a id="tab:iostreams.lib.summary">[tab:iostreams.lib.summary]</a>
15
 
16
  | Subclause | | Header |
17
- | -------------------------- | --------------------------- | -------------- |
18
  | [[iostreams.requirements]] | Requirements | |
19
  | [[iostream.forward]] | Forward declarations | `<iosfwd>` |
20
  | [[iostream.objects]] | Standard iostream objects | `<iostream>` |
21
  | [[iostreams.base]] | Iostreams base classes | `<ios>` |
22
  | [[stream.buffers]] | Stream buffers | `<streambuf>` |
23
- | [[iostream.format]] | Formatting and manipulators | `<istream>` |
24
- | | | `<ostream>` |
25
- | | | `<iomanip>` |
26
  | [[string.streams]] | String streams | `<sstream>` |
27
  | [[file.streams]] | File streams | `<fstream>` |
 
28
  | [[filesystems]] | File systems | `<filesystem>` |
29
- | [[c.files]] | C library files | `<cstdio>` |
30
- | | | `<cinttypes>` |
31
 
32
 
33
- Figure  [[fig:streampos]] illustrates relationships among various types
34
- described in this clause. A line from **A** to **B** indicates that
35
- **A** is an alias (e.g. a typedef) for **B** or that **A** is defined in
36
- terms of **B**.
37
 
38
- <a id="fig:streampos"></a>
39
 
40
- ![Stream position, offset, and size types \[non-normative\] \[fig:streampos\]](images/figstreampos.svg)
 
 
41
 
42
  ## Iostreams requirements <a id="iostreams.requirements">[[iostreams.requirements]]</a>
43
 
44
  ### Imbue limitations <a id="iostream.limits.imbue">[[iostream.limits.imbue]]</a>
45
 
46
- No function described in Clause  [[input.output]] except for
47
- `ios_base::imbue` and `basic_filebuf::pubimbue` causes any instance of
48
- `basic_ios::imbue` or `basic_streambuf::imbue` to be called. If any user
49
- function called from a function declared in Clause  [[input.output]] or
50
- as an overriding virtual function of any class declared in Clause 
51
- [[input.output]] calls `imbue`, the behavior is undefined.
52
 
53
  ### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
54
 
55
- The classes of Clause  [[input.output]] with template arguments `charT`
56
- and `traits` behave as described if `traits::pos_type` and
57
  `traits::off_type` are `streampos` and `streamoff` respectively. Except
58
  as noted explicitly below, their behavior when `traits::pos_type` and
59
  `traits::off_type` are other types is *implementation-defined*.
60
 
61
- In the classes of Clause  [[input.output]], a template parameter with
62
- name `charT` represents a member of the set of types containing `char`,
63
  `wchar_t`, and any other *implementation-defined* character types that
64
- satisfy the requirements for a character on which any of the iostream
65
  components can be instantiated.
66
 
67
  ### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
68
 
69
- Concurrent access to a stream object ([[string.streams]], 
70
- [[file.streams]]), stream buffer object ([[stream.buffers]]), or C
71
- Library stream ([[c.files]]) by multiple threads may result in a data
72
- race ([[intro.multithread]]) unless otherwise specified (
73
- [[iostream.objects]]).
74
 
75
- [*Note 1*: Data races result in undefined behavior (
76
- [[intro.multithread]]). — *end note*]
77
 
78
  If one thread makes a library call *a* that writes a value to a stream
79
  and, as a result, another thread reads this value from the stream
80
  through a library call *b* such that this does not result in a data
81
  race, then *a*’s write synchronizes with *b*’s read.
@@ -84,15 +83,16 @@ race, then *a*’s write synchronizes with *b*’s read.
84
 
85
  ### Header `<iosfwd>` synopsis <a id="iosfwd.syn">[[iosfwd.syn]]</a>
86
 
87
  ``` cpp
88
  namespace std {
89
- template<class charT> class char_traits;
90
- template<> class char_traits<char>;
91
- template<> class char_traits<char16_t>;
92
- template<> class char_traits<char32_t>;
93
- template<> class char_traits<wchar_t>;
 
94
 
95
  template<class T> class allocator;
96
 
97
  template<class charT, class traits = char_traits<charT>>
98
  class basic_ios;
@@ -125,10 +125,17 @@ namespace std {
125
  template<class charT, class traits = char_traits<charT>>
126
  class basic_ofstream;
127
  template<class charT, class traits = char_traits<charT>>
128
  class basic_fstream;
129
 
 
 
 
 
 
 
 
130
  template<class charT, class traits = char_traits<charT>>
131
  class istreambuf_iterator;
132
  template<class charT, class traits = char_traits<charT>>
133
  class ostreambuf_iterator;
134
 
@@ -148,10 +155,13 @@ namespace std {
148
  using filebuf = basic_filebuf<char>;
149
  using ifstream = basic_ifstream<char>;
150
  using ofstream = basic_ofstream<char>;
151
  using fstream = basic_fstream<char>;
152
 
 
 
 
153
  using wstreambuf = basic_streambuf<wchar_t>;
154
  using wistream = basic_istream<wchar_t>;
155
  using wostream = basic_ostream<wchar_t>;
156
  using wiostream = basic_iostream<wchar_t>;
157
 
@@ -163,13 +173,19 @@ namespace std {
163
  using wfilebuf = basic_filebuf<wchar_t>;
164
  using wifstream = basic_ifstream<wchar_t>;
165
  using wofstream = basic_ofstream<wchar_t>;
166
  using wfstream = basic_fstream<wchar_t>;
167
 
 
 
 
168
  template<class state> class fpos;
169
  using streampos = fpos<char_traits<char>::state_type>;
170
  using wstreampos = fpos<char_traits<wchar_t>::state_type>;
 
 
 
171
  }
172
  ```
173
 
174
  Default template arguments are described as appearing both in `<iosfwd>`
175
  and in the synopsis of other headers but it is well-formed to include
@@ -182,52 +198,42 @@ virtual base class for the class templates `basic_istream`,
182
  `basic_ostream`, and class templates derived from them. `basic_iostream`
183
  is a class template derived from both `basic_istream<charT, traits>` and
184
  `basic_ostream<charT, traits>`.
185
 
186
  The class template specialization `basic_streambuf<charT, traits>`
187
- serves as a base class for class templates `basic_stringbuf` and
188
- `basic_filebuf`.
189
 
190
  The class template specialization `basic_istream<charT, traits>` serves
191
  as a base class for class templates `basic_istringstream` and
192
  `basic_ifstream`.
193
 
194
  The class template specialization `basic_ostream<charT, traits>` serves
195
- as a base class for class templates `basic_ostringstream` and
196
- `basic_ofstream`.
197
 
198
  The class template specialization `basic_iostream<charT, traits>` serves
199
  as a base class for class templates `basic_stringstream` and
200
  `basic_fstream`.
201
 
 
 
 
 
202
  Other *typedef-name*s define instances of class templates specialized
203
  for `char` or `wchar_t` types.
204
 
205
  Specializations of the class template `fpos` are used for specifying
206
  file position information.
207
 
208
- The types `streampos` and `wstreampos` are used for positioning streams
209
- specialized on `char` and `wchar_t` respectively.
 
210
 
211
- [*Note 1*:
212
-
213
- This synopsis suggests a circularity between `streampos` and
214
  `char_traits<char>`. An implementation can avoid this circularity by
215
- substituting equivalent types. One way to do this might be
216
-
217
- ``` cpp
218
- template<class stateT> class fpos { ... }; // depends on nothing
219
- using _STATE = ... ; // implementation private declaration of stateT
220
-
221
- using streampos = fpos<_STATE>;
222
-
223
- template<> struct char_traits<char> {
224
- using pos_type = streampos;
225
- }
226
- ```
227
-
228
- — *end note*]
229
 
230
  ## Standard iostream objects <a id="iostream.objects">[[iostream.objects]]</a>
231
 
232
  ### Header `<iostream>` synopsis <a id="iostream.syn">[[iostream.syn]]</a>
233
 
@@ -251,115 +257,114 @@ namespace std {
251
  ```
252
 
253
  ### Overview <a id="iostream.objects.overview">[[iostream.objects.overview]]</a>
254
 
255
  In this Clause, the type name `FILE` refers to the type `FILE` declared
256
- in `<cstdio>` ([[cstdio.syn]]).
257
 
258
  The header `<iostream>` declares objects that associate objects with the
259
- standard C streams provided for by the functions declared in
260
- `<cstdio>` ([[c.files]]), and includes all the headers necessary to use
261
- these objects.
262
 
263
  The objects are constructed and the associations are established at some
264
  time prior to or during the first time an object of class
265
  `ios_base::Init` is constructed, and in any case before the body of
266
- `main` ([[basic.start.main]]) begins execution.[^2] The objects are not
267
  destroyed during program execution.[^3] The results of including
268
  `<iostream>` in a translation unit shall be as if `<iostream>` defined
269
  an instance of `ios_base::Init` with static storage duration.
270
 
271
  Mixing operations on corresponding wide- and narrow-character streams
272
  follows the same semantics as mixing such operations on `FILE`s, as
273
  specified in the C standard library.
274
 
275
- Concurrent access to a synchronized ([[ios.members.static]]) standard
276
- iostream object’s formatted and unformatted input ([[istream]]) and
277
- output ([[ostream]]) functions or a standard C stream by multiple
278
- threads shall not result in a data race ([[intro.multithread]]).
279
 
280
  [*Note 1*: Users must still synchronize concurrent use of these objects
281
  and streams by multiple threads if they wish to avoid interleaved
282
  characters. — *end note*]
283
 
284
-  ISO C 7.21.2.
285
 
286
  ### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
287
 
288
  ``` cpp
289
  istream cin;
290
  ```
291
 
292
  The object `cin` controls input from a stream buffer associated with the
293
- object `stdin`, declared in `<cstdio>` ([[cstdio.syn]]).
294
 
295
  After the object `cin` is initialized, `cin.tie()` returns `&cout`. Its
296
- state is otherwise the same as required for
297
- `basic_ios<char>::init` ([[basic.ios.cons]]).
298
 
299
  ``` cpp
300
  ostream cout;
301
  ```
302
 
303
  The object `cout` controls output to a stream buffer associated with the
304
- object `stdout`, declared in `<cstdio>` ([[cstdio.syn]]).
305
 
306
  ``` cpp
307
  ostream cerr;
308
  ```
309
 
310
  The object `cerr` controls output to a stream buffer associated with the
311
- object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
312
 
313
  After the object `cerr` is initialized, `cerr.flags() & unitbuf` is
314
  nonzero and `cerr.tie()` returns `&cout`. Its state is otherwise the
315
- same as required for `basic_ios<char>::init` ([[basic.ios.cons]]).
316
 
317
  ``` cpp
318
  ostream clog;
319
  ```
320
 
321
  The object `clog` controls output to a stream buffer associated with the
322
- object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
323
 
324
  ### Wide stream objects <a id="wide.stream.objects">[[wide.stream.objects]]</a>
325
 
326
  ``` cpp
327
  wistream wcin;
328
  ```
329
 
330
  The object `wcin` controls input from a stream buffer associated with
331
- the object `stdin`, declared in `<cstdio>` ([[cstdio.syn]]).
332
 
333
  After the object `wcin` is initialized, `wcin.tie()` returns `&wcout`.
334
  Its state is otherwise the same as required for
335
- `basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
336
 
337
  ``` cpp
338
  wostream wcout;
339
  ```
340
 
341
  The object `wcout` controls output to a stream buffer associated with
342
- the object `stdout`, declared in `<cstdio>` ([[cstdio.syn]]).
343
 
344
  ``` cpp
345
  wostream wcerr;
346
  ```
347
 
348
  The object `wcerr` controls output to a stream buffer associated with
349
- the object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
350
 
351
  After the object `wcerr` is initialized, `wcerr.flags() & unitbuf` is
352
  nonzero and `wcerr.tie()` returns `&wcout`. Its state is otherwise the
353
- same as required for `basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
354
 
355
  ``` cpp
356
  wostream wclog;
357
  ```
358
 
359
  The object `wclog` controls output to a stream buffer associated with
360
- the object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
361
 
362
  ## Iostreams base classes <a id="iostreams.base">[[iostreams.base]]</a>
363
 
364
  ### Header `<ios>` synopsis <a id="ios.syn">[[ios.syn]]</a>
365
 
@@ -449,11 +454,11 @@ an I/O operation, or the size of I/O buffers.[^5]
449
  namespace std {
450
  class ios_base {
451
  public:
452
  class failure; // see below
453
 
454
- // [ios::fmtflags], fmtflags
455
  using fmtflags = T1;
456
  static constexpr fmtflags boolalpha = unspecified;
457
  static constexpr fmtflags dec = unspecified;
458
  static constexpr fmtflags fixed = unspecified;
459
  static constexpr fmtflags hex = unspecified;
@@ -470,27 +475,27 @@ namespace std {
470
  static constexpr fmtflags uppercase = unspecified;
471
  static constexpr fmtflags adjustfield = see below;
472
  static constexpr fmtflags basefield = see below;
473
  static constexpr fmtflags floatfield = see below;
474
 
475
- // [ios::iostate], iostate
476
  using iostate = T2;
477
  static constexpr iostate badbit = unspecified;
478
  static constexpr iostate eofbit = unspecified;
479
  static constexpr iostate failbit = unspecified;
480
  static constexpr iostate goodbit = see below;
481
 
482
- // [ios::openmode], openmode
483
  using openmode = T3;
484
  static constexpr openmode app = unspecified;
485
  static constexpr openmode ate = unspecified;
486
  static constexpr openmode binary = unspecified;
487
  static constexpr openmode in = unspecified;
488
  static constexpr openmode out = unspecified;
489
  static constexpr openmode trunc = unspecified;
490
 
491
- // [ios::seekdir], seekdir
492
  using seekdir = T4;
493
  static constexpr seekdir beg = unspecified;
494
  static constexpr seekdir cur = unspecified;
495
  static constexpr seekdir end = unspecified;
496
 
@@ -512,20 +517,20 @@ namespace std {
512
  locale imbue(const locale& loc);
513
  locale getloc() const;
514
 
515
  // [ios.base.storage], storage
516
  static int xalloc();
517
- long& iword(int index);
518
- void*& pword(int index);
519
 
520
- // destructor:
521
  virtual ~ios_base();
522
 
523
- // [ios.base.callback], callbacks;
524
  enum event { erase_event, imbue_event, copyfmt_event };
525
- using event_callback = void (*)(event, ios_base&, int index);
526
- void register_callback(event_callback fn, int index);
527
 
528
  ios_base(const ios_base&) = delete;
529
  ios_base& operator=(const ios_base&) = delete;
530
 
531
  static bool sync_with_stdio(bool sync = true);
@@ -573,11 +578,11 @@ For the sake of exposition, the maintained data is presented here as:
573
 
574
  — *end note*]
575
 
576
  #### Types <a id="ios.types">[[ios.types]]</a>
577
 
578
- ##### Class `ios_base::failure` <a id="ios::failure">[[ios::failure]]</a>
579
 
580
  ``` cpp
581
  namespace std {
582
  class ios_base::failure : public system_error {
583
  public:
@@ -589,13 +594,13 @@ namespace std {
589
 
590
  An implementation is permitted to define `ios_base::failure` as a
591
  synonym for a class with equivalent functionality to class
592
  `ios_base::failure` shown in this subclause.
593
 
594
- [*Note 1*: When `ios_base::failure` is a synonym for another type it
595
- shall provide a nested type `failure`, to emulate the injected class
596
- name. — *end note*]
597
 
598
  The class `failure` defines the base class for the types of all objects
599
  thrown as exceptions, by functions in the iostreams library, to report
600
  errors detected during stream buffer operations.
601
 
@@ -612,31 +617,28 @@ iostream_category())`. — *end note*]
612
 
613
  ``` cpp
614
  explicit failure(const string& msg, const error_code& ec = io_errc::stream);
615
  ```
616
 
617
- *Effects:* Constructs an object of class `failure` by constructing the
618
- base class with `msg` and `ec`.
619
 
620
  ``` cpp
621
  explicit failure(const char* msg, const error_code& ec = io_errc::stream);
622
  ```
623
 
624
- *Effects:* Constructs an object of class `failure` by constructing the
625
- base class with `msg` and `ec`.
626
 
627
- ##### Type `ios_base::fmtflags` <a id="ios::fmtflags">[[ios::fmtflags]]</a>
628
 
629
  ``` cpp
630
  using fmtflags = T1;
631
  ```
632
 
633
- The type `fmtflags` is a bitmask type ([[bitmask.types]]). Setting its
634
- elements has the effects indicated in
635
- Table  [[tab:iostreams.fmtflags.effects]].
636
 
637
- **Table: `fmtflags` effects** <a id="tab:iostreams.fmtflags.effects">[tab:iostreams.fmtflags.effects]</a>
638
 
639
  | Element | Effect(s) if set |
640
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
641
  | `boolalpha` | insert and extract `bool` type in alphabetic format |
642
  | `dec` | converts integer input or generates integer output in decimal base |
@@ -654,31 +656,31 @@ Table  [[tab:iostreams.fmtflags.effects]].
654
  | `unitbuf` | flushes output after each output operation |
655
  | `uppercase` | replaces certain lowercase letters with their uppercase equivalents in generated output |
656
 
657
 
658
  Type `fmtflags` also defines the constants indicated in
659
- Table  [[tab:iostreams.fmtflags.constants]].
660
 
661
- **Table: `fmtflags` constants** <a id="tab:iostreams.fmtflags.constants">[tab:iostreams.fmtflags.constants]</a>
662
 
663
  | Constant | Allowable values |
664
  | ------------- | ------------------------- |
665
  | `adjustfield` | `left | right | internal` |
666
  | `basefield` | `dec | oct | hex` |
667
  | `floatfield` | `scientific | fixed` |
668
 
669
 
670
- ##### Type `ios_base::iostate` <a id="ios::iostate">[[ios::iostate]]</a>
671
 
672
  ``` cpp
673
  using iostate = T2;
674
  ```
675
 
676
- The type `iostate` is a bitmask type ([[bitmask.types]]) that contains
677
- the elements indicated in Table  [[tab:iostreams.iostate.effects]].
678
 
679
- **Table: `iostate` effects** <a id="tab:iostreams.iostate.effects">[tab:iostreams.iostate.effects]</a>
680
 
681
  | Element | Effect(s) if set |
682
  | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
683
  | `badbit` | indicates a loss of integrity in an input or output sequence (such as an irrecoverable read error from a file); |
684
  | `eofbit` | indicates that an input operation reached the end of an input sequence; |
@@ -687,20 +689,20 @@ the elements indicated in Table  [[tab:iostreams.iostate.effects]].
687
 
688
  Type `iostate` also defines the constant:
689
 
690
  - `goodbit`, the value zero.
691
 
692
- ##### Type `ios_base::openmode` <a id="ios::openmode">[[ios::openmode]]</a>
693
 
694
  ``` cpp
695
  using openmode = T3;
696
  ```
697
 
698
- The type `openmode` is a bitmask type ([[bitmask.types]]). It contains
699
- the elements indicated in Table  [[tab:iostreams.openmode.effects]].
700
 
701
- **Table: `openmode` effects** <a id="tab:iostreams.openmode.effects">[tab:iostreams.openmode.effects]</a>
702
 
703
  | Element | Effect(s) if set |
704
  | -------- | ----------------------------------------------------------------- |
705
  | `app` | seek to end before each write |
706
  | `ate` | open and seek to end immediately after opening |
@@ -708,73 +710,71 @@ the elements indicated in Table  [[tab:iostreams.openmode.effects]].
708
  | `in` | open for input |
709
  | `out` | open for output |
710
  | `trunc` | truncate an existing stream when opening |
711
 
712
 
713
- ##### Type `ios_base::seekdir` <a id="ios::seekdir">[[ios::seekdir]]</a>
714
 
715
  ``` cpp
716
  using seekdir = T4;
717
  ```
718
 
719
- The type `seekdir` is an enumerated type ([[enumerated.types]]) that
720
- contains the elements indicated in
721
- Table  [[tab:iostreams.seekdir.effects]].
722
 
723
- **Table: `seekdir` effects** <a id="tab:iostreams.seekdir.effects">[tab:iostreams.seekdir.effects]</a>
724
 
725
  | Element | Meaning |
726
  | ------- | --------------------------------------------------------------------------------------- |
727
  | `beg` | request a seek (for subsequent input or output) relative to the beginning of the stream |
728
  | `cur` | request a seek relative to the current position within the sequence |
729
  | `end` | request a seek relative to the current end of the sequence |
730
 
731
 
732
- ##### Class `ios_base::Init` <a id="ios::Init">[[ios::Init]]</a>
733
 
734
  ``` cpp
735
  namespace std {
736
  class ios_base::Init {
737
  public:
738
  Init();
 
739
  ~Init();
 
740
  private:
741
  static int init_cnt; // exposition only
742
  };
743
  }
744
  ```
745
 
746
  The class `Init` describes an object whose construction ensures the
747
- construction of the eight objects declared in `<iostream>` (
748
- [[iostream.objects]]) that associate file stream buffers with the
749
- standard C streams provided for by the functions declared in
750
- `<cstdio>` ([[cstdio.syn]]).
751
 
752
  For the sake of exposition, the maintained data is presented here as:
753
 
754
  - `static int init_cnt`, counts the number of constructor and destructor
755
  calls for class `Init`, initialized to zero.
756
 
757
  ``` cpp
758
  Init();
759
  ```
760
 
761
- *Effects:* Constructs an object of class `Init`. Constructs and
762
- initializes the objects `cin`, `cout`, `cerr`, `clog`, `wcin`, `wcout`,
763
- `wcerr`, and `wclog` if they have not already been constructed and
764
- initialized.
765
 
766
  ``` cpp
767
  ~Init();
768
  ```
769
 
770
- *Effects:* Destroys an object of class `Init`. If there are no other
771
- instances of the class still in existence, calls `cout.flush()`,
772
- `cerr.flush()`, `clog.flush()`, `wcout.flush()`, `wcerr.flush()`,
773
- `wclog.flush()`.
774
 
775
- #### `ios_base` state functions <a id="fmtflags.state">[[fmtflags.state]]</a>
776
 
777
  ``` cpp
778
  fmtflags flags() const;
779
  ```
780
 
@@ -782,11 +782,11 @@ fmtflags flags() const;
782
 
783
  ``` cpp
784
  fmtflags flags(fmtflags fmtfl);
785
  ```
786
 
787
- *Postconditions:* `fmtfl == flags()`.
788
 
789
  *Returns:* The previous value of `flags()`.
790
 
791
  ``` cpp
792
  fmtflags setf(fmtflags fmtfl);
@@ -818,11 +818,11 @@ streamsize precision() const;
818
 
819
  ``` cpp
820
  streamsize precision(streamsize prec);
821
  ```
822
 
823
- *Postconditions:* `prec == precision()`.
824
 
825
  *Returns:* The previous value of `precision()`.
826
 
827
  ``` cpp
828
  streamsize width() const;
@@ -833,47 +833,46 @@ certain output conversions.
833
 
834
  ``` cpp
835
  streamsize width(streamsize wide);
836
  ```
837
 
838
- *Postconditions:* `wide == width()`.
839
 
840
  *Returns:* The previous value of `width()`.
841
 
842
- #### `ios_base` functions <a id="ios.base.locales">[[ios.base.locales]]</a>
843
 
844
  ``` cpp
845
  locale imbue(const locale& loc);
846
  ```
847
 
848
- *Effects:* Calls each registered callback pair
849
- `(fn, index)` ([[ios.base.callback]]) as
850
- `(*fn)(imbue_event, *this, index)` at such a time that a call to
851
- `ios_base::getloc()` from within `fn` returns the new locale value
852
- `loc`.
 
853
 
854
  *Returns:* The previous value of `getloc()`.
855
 
856
- *Postconditions:* `loc == getloc()`.
857
-
858
  ``` cpp
859
  locale getloc() const;
860
  ```
861
 
862
- *Returns:* If no locale has been imbued, a copy of the global C++locale,
863
- `locale()`, in effect at the time of construction. Otherwise, returns
864
- the imbued locale, to be used to perform locale-dependent input and
865
- output operations.
866
 
867
- #### `ios_base` static members <a id="ios.members.static">[[ios.members.static]]</a>
868
 
869
  ``` cpp
870
- bool sync_with_stdio(bool sync = true);
871
  ```
872
 
873
  *Returns:* `true` if the previous state of the standard iostream
874
- objects ([[iostream.objects]]) was synchronized and otherwise returns
875
  `false`. The first time it is called, the function returns `true`.
876
 
877
  *Effects:* If any input or output operation has occurred using the
878
  standard streams prior to the call, the effect is
879
  *implementation-defined*. Otherwise, called with a `false` argument, it
@@ -919,25 +918,27 @@ is the same as the effect of
919
  str.rdbuf()->sputbackc(c);
920
  ```
921
 
922
  for any sequence of characters.[^6]
923
 
924
- #### `ios_base` storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
925
 
926
  ``` cpp
927
  static int xalloc();
928
  ```
929
 
930
  *Returns:* `index` `++`.
931
 
932
- *Remarks:* Concurrent access to this function by multiple threads shall
933
- not result in a data race ([[intro.multithread]]).
934
 
935
  ``` cpp
936
  long& iword(int idx);
937
  ```
938
 
 
 
939
  *Effects:* If `iarray` is a null pointer, allocates an array of `long`
940
  of unspecified size and stores a pointer to its first element in
941
  `iarray`. The function then extends the array pointed at by `iarray` as
942
  necessary to include the element `iarray[idx]`. Each newly allocated
943
  element of the array is initialized to zero. The reference returned is
@@ -954,10 +955,12 @@ initialized to 0.
954
 
955
  ``` cpp
956
  void*& pword(int idx);
957
  ```
958
 
 
 
959
  *Effects:* If `parray` is a null pointer, allocates an array of pointers
960
  to `void` of unspecified size and stores a pointer to its first element
961
  in `parray`. The function then extends the array pointed at by `parray`
962
  as necessary to include the element `parray[idx]`. Each newly allocated
963
  element of the array is initialized to a null pointer. The reference
@@ -973,29 +976,29 @@ object (which may throw `failure`).
973
  initialized to 0.
974
 
975
  *Remarks:* After a subsequent call to `pword(int)` for the same object,
976
  the earlier return value may no longer be valid.
977
 
978
- #### `ios_base` callbacks <a id="ios.base.callback">[[ios.base.callback]]</a>
979
 
980
  ``` cpp
981
- void register_callback(event_callback fn, int index);
982
  ```
983
 
984
- *Effects:* Registers the pair `(fn, index)` such that during calls to
985
- `imbue()` ([[ios.base.locales]]), `copyfmt()`, or
986
- `~ios_base()` ([[ios.base.cons]]), the function `fn` is called with
987
- argument `index`. Functions registered are called when an event occurs,
988
- in opposite order of registration. Functions registered while a callback
989
- function is active are not called until the next event.
990
 
991
- *Requires:* The function `fn` shall not throw exceptions.
 
 
 
 
 
992
 
993
  *Remarks:* Identical pairs are not merged. A function registered twice
994
  will be called twice.
995
 
996
- #### `ios_base` constructors/destructor <a id="ios.base.cons">[[ios.base.cons]]</a>
997
 
998
  ``` cpp
999
  ios_base();
1000
  ```
1001
 
@@ -1006,14 +1009,14 @@ destroyed, whichever comes first; otherwise the behavior is undefined.
1006
 
1007
  ``` cpp
1008
  ~ios_base();
1009
  ```
1010
 
1011
- *Effects:* Destroys an object of class `ios_base`. Calls each registered
1012
- callback pair `(fn, index)` ([[ios.base.callback]]) as
1013
- `(*fn)(erase_event, *this, index)` at such time that any `ios_base`
1014
- member function called from within `fn` has well defined results.
1015
 
1016
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
1017
 
1018
  ``` cpp
1019
  namespace std {
@@ -1026,11 +1029,11 @@ namespace std {
1026
  stateT st; // exposition only
1027
  };
1028
  }
1029
  ```
1030
 
1031
- #### `fpos` members <a id="fpos.members">[[fpos.members]]</a>
1032
 
1033
  ``` cpp
1034
  void state(stateT s);
1035
  ```
1036
 
@@ -1040,27 +1043,36 @@ void state(stateT s);
1040
  stateT state() const;
1041
  ```
1042
 
1043
  *Returns:* Current value of `st`.
1044
 
1045
- #### `fpos` requirements <a id="fpos.operations">[[fpos.operations]]</a>
1046
 
1047
- Operations specified in Table  [[tab:iostreams.position.requirements]]
1048
- are permitted. In that table,
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1049
 
1050
  - `P` refers to an instance of `fpos`,
1051
- - `p` and `q` refer to values of type `P`,
1052
- - `O` refers to type `streamoff`,
1053
- - `o` refers to a value of type `streamoff`,
1054
- - `sz` refers to a value of type `streamsize` and
1055
- - `i` refers to a value of type `int`.
1056
-
1057
- [*Note 1*: Every implementation is required to supply overloaded
1058
- operators on `fpos` objects to satisfy the requirements of 
1059
- [[fpos.operations]]. It is unspecified whether these operators are
1060
- members of `fpos`, global operators, or provided in some other
1061
- way. — *end note*]
1062
 
1063
  Stream operations that return a value of type `traits::pos_type` return
1064
  `P(O(-1))` as an invalid value to signal an error. If this value is used
1065
  as an argument to any `istream`, `ostream`, or `streambuf` member that
1066
  accepts a value of type `traits::pos_type` then the behavior of that
@@ -1129,28 +1141,27 @@ namespace std {
1129
 
1130
  };
1131
  }
1132
  ```
1133
 
1134
- #### `basic_ios` constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
1135
 
1136
  ``` cpp
1137
  explicit basic_ios(basic_streambuf<charT, traits>* sb);
1138
  ```
1139
 
1140
- *Effects:* Constructs an object of class `basic_ios`, assigning initial
1141
- values to its member objects by calling `init(sb)`.
1142
 
1143
  ``` cpp
1144
  basic_ios();
1145
  ```
1146
 
1147
- *Effects:* Constructs an object of class
1148
- `basic_ios` ([[ios.base.cons]]) leaving its member objects
1149
- uninitialized. The object shall be initialized by calling
1150
- `basic_ios::init` before its first use or before it is destroyed,
1151
- whichever comes first; otherwise the behavior is undefined.
1152
 
1153
  ``` cpp
1154
  ~basic_ios();
1155
  ```
1156
 
@@ -1158,14 +1169,14 @@ whichever comes first; otherwise the behavior is undefined.
1158
 
1159
  ``` cpp
1160
  void init(basic_streambuf<charT, traits>* sb);
1161
  ```
1162
 
1163
- *Postconditions:* The postconditions of this function are indicated in
1164
- Table  [[tab:iostreams.basicios.init.effects]].
1165
 
1166
- **Table: `basic_ios::init()` effects** <a id="tab:iostreams.basicios.init.effects">[tab:iostreams.basicios.init.effects]</a>
1167
 
1168
  | Element | Value |
1169
  | -------------- | ------------------------------------------------------------ |
1170
  | `rdbuf()` | `sb` |
1171
  | `tie()` | `0` |
@@ -1191,15 +1202,15 @@ sequence controlled by the stream buffer.
1191
 
1192
  ``` cpp
1193
  basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
1194
  ```
1195
 
1196
- *Requires:* If `tiestr` is not null, `tiestr` must not be reachable by
1197
  traversing the linked list of tied stream objects starting from
1198
  `tiestr->tie()`.
1199
 
1200
- *Postconditions:* `tiestr == tie()`.
1201
 
1202
  *Returns:* The previous value of `tie()`.
1203
 
1204
  ``` cpp
1205
  basic_streambuf<charT, traits>* rdbuf() const;
@@ -1209,22 +1220,22 @@ basic_streambuf<charT, traits>* rdbuf() const;
1209
 
1210
  ``` cpp
1211
  basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
1212
  ```
1213
 
1214
- *Postconditions:* `sb == rdbuf()`.
1215
-
1216
  *Effects:* Calls `clear()`.
1217
 
 
 
1218
  *Returns:* The previous value of `rdbuf()`.
1219
 
1220
  ``` cpp
1221
  locale imbue(const locale& loc);
1222
  ```
1223
 
1224
- *Effects:* Calls `ios_base::imbue(loc)` ([[ios.base.locales]]) and if
1225
- `rdbuf() != 0` then `rdbuf()->pubimbue(loc)` ([[streambuf.locales]]).
1226
 
1227
  *Returns:* The prior value of `ios_base::imbue()`.
1228
 
1229
  ``` cpp
1230
  char narrow(char_type c, char dfault) const;
@@ -1247,45 +1258,45 @@ specified field width.
1247
 
1248
  ``` cpp
1249
  char_type fill(char_type fillch);
1250
  ```
1251
 
1252
- *Postconditions:* `traits::eq(fillch, fill())`.
1253
 
1254
  *Returns:* The previous value of `fill()`.
1255
 
1256
  ``` cpp
1257
  basic_ios& copyfmt(const basic_ios& rhs);
1258
  ```
1259
 
1260
- *Effects:* If `(this == &rhs)` does nothing. Otherwise assigns to the
1261
- member objects of `*this` the corresponding member objects of `rhs` as
1262
- follows:
1263
 
1264
- 1. calls each registered callback pair `(fn, index)` as
1265
- `(*fn)(erase_event, *this, index)`;
1266
- 2. assigns to the member objects of `*this` the corresponding member
1267
- objects of `rhs`, except that
1268
  - `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
1269
- - the contents of arrays pointed at by `pword` and `iword` are
1270
- copied, not the pointers themselves;[^10] and
1271
  - if any newly stored pointer values in `*this` point at objects
1272
- stored outside the object `rhs` and those objects are destroyed
1273
- when `rhs` is destroyed, the newly stored pointer values are
1274
- altered to point at newly constructed copies of the objects;
1275
- 3. calls each callback pair that was copied from `rhs` as
1276
- `(*fn)(copyfmt_event, *this, index)`;
1277
- 4. calls `exceptions(rhs.exceptions())`.
1278
 
1279
  [*Note 1*: The second pass through the callback pairs permits a copied
1280
  `pword` value to be zeroed, or to have its referent deep copied or
1281
  reference counted, or to have other special action taken. — *end note*]
1282
 
1283
- *Postconditions:* The postconditions of this function are indicated in
1284
- Table  [[tab:iostreams.copyfmt.effects]].
1285
 
1286
- **Table: `basic_ios::copyfmt()` effects** <a id="tab:iostreams.copyfmt.effects">[tab:iostreams.copyfmt.effects]</a>
1287
 
1288
  | Element | Value |
1289
  | -------------- | ------------------ |
1290
  | `rdbuf()` | unchanged |
1291
  | `tie()` | `rhs.tie()` |
@@ -1303,39 +1314,38 @@ Table  [[tab:iostreams.copyfmt.effects]].
1303
  ``` cpp
1304
  void move(basic_ios& rhs);
1305
  void move(basic_ios&& rhs);
1306
  ```
1307
 
1308
- *Postconditions:* `*this` shall have the state that `rhs` had before the
1309
- function call, except that `rdbuf()` shall return 0. `rhs` shall be in a
1310
- valid but unspecified state, except that `rhs.rdbuf()` shall return the
1311
- same value as it returned before the function call, and `rhs.tie()`
1312
- shall return 0.
1313
 
1314
  ``` cpp
1315
  void swap(basic_ios& rhs) noexcept;
1316
  ```
1317
 
1318
- *Effects:* The states of `*this` and `rhs` shall be exchanged, except
1319
- that `rdbuf()` shall return the same value as it returned before the
1320
- function call, and `rhs.rdbuf()` shall return the same value as it
1321
- returned before the function call.
1322
 
1323
  ``` cpp
1324
  void set_rdbuf(basic_streambuf<charT, traits>* sb);
1325
  ```
1326
 
1327
- *Requires:* `sb != nullptr`.
1328
 
1329
  *Effects:* Associates the `basic_streambuf` object pointed to by `sb`
1330
  with this stream without calling `clear()`.
1331
 
1332
- *Postconditions:* `rdbuf() == sb`.
1333
 
1334
  *Throws:* Nothing.
1335
 
1336
- #### `basic_ios` flags functions <a id="iostate.flags">[[iostate.flags]]</a>
1337
 
1338
  ``` cpp
1339
  explicit operator bool() const;
1340
  ```
1341
 
@@ -1355,25 +1365,25 @@ iostate rdstate() const;
1355
 
1356
  ``` cpp
1357
  void clear(iostate state = goodbit);
1358
  ```
1359
 
1360
- *Postconditions:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
1361
  `rdstate() == (state | ios_base::badbit)`.
1362
 
1363
  *Effects:* If
1364
  `((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
1365
- Otherwise, the function throws an object of class
1366
- `basic_ios::failure` ([[ios::failure]]), constructed with
1367
- *implementation-defined* argument values.
1368
 
1369
  ``` cpp
1370
  void setstate(iostate state);
1371
  ```
1372
 
1373
  *Effects:* Calls `clear(rdstate() | state)` (which may throw
1374
- `basic_ios::failure` ([[ios::failure]])).
1375
 
1376
  ``` cpp
1377
  bool good() const;
1378
  ```
1379
 
@@ -1406,18 +1416,21 @@ exceptions to be thrown.
1406
 
1407
  ``` cpp
1408
  void exceptions(iostate except);
1409
  ```
1410
 
1411
- *Postconditions:* `except == exceptions()`.
1412
 
1413
  *Effects:* Calls `clear(rdstate())`.
1414
 
1415
  ### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
1416
 
1417
  #### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
1418
 
 
 
 
1419
  ``` cpp
1420
  ios_base& boolalpha(ios_base& str);
1421
  ```
1422
 
1423
  *Effects:* Calls `str.setf(ios_base::boolalpha)`.
@@ -1528,10 +1541,13 @@ ios_base& nounitbuf(ios_base& str);
1528
 
1529
  *Returns:* `str`.
1530
 
1531
  #### `adjustfield` manipulators <a id="adjustfield.manip">[[adjustfield.manip]]</a>
1532
 
 
 
 
1533
  ``` cpp
1534
  ios_base& internal(ios_base& str);
1535
  ```
1536
 
1537
  *Effects:* Calls `str.setf(ios_base::internal, ios_base::adjustfield)`.
@@ -1554,10 +1570,13 @@ ios_base& right(ios_base& str);
1554
 
1555
  *Returns:* `str`.
1556
 
1557
  #### `basefield` manipulators <a id="basefield.manip">[[basefield.manip]]</a>
1558
 
 
 
 
1559
  ``` cpp
1560
  ios_base& dec(ios_base& str);
1561
  ```
1562
 
1563
  *Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
@@ -1580,10 +1599,13 @@ ios_base& oct(ios_base& str);
1580
 
1581
  *Returns:* `str`.
1582
 
1583
  #### `floatfield` manipulators <a id="floatfield.manip">[[floatfield.manip]]</a>
1584
 
 
 
 
1585
  ``` cpp
1586
  ios_base& fixed(ios_base& str);
1587
  ```
1588
 
1589
  *Effects:* Calls `str.setf(ios_base::fixed, ios_base::floatfield)`.
@@ -1607,22 +1629,22 @@ ios_base& hexfloat(ios_base& str);
1607
 
1608
  *Returns:* `str`.
1609
 
1610
  [*Note 1*: The more obvious use of `ios_base::hex` to specify
1611
  hexadecimal floating-point format would change the meaning of existing
1612
- well defined programs. C++03 gives no meaning to the combination of
1613
  `fixed` and `scientific`. — *end note*]
1614
 
1615
  ``` cpp
1616
  ios_base& defaultfloat(ios_base& str);
1617
  ```
1618
 
1619
  *Effects:* Calls `str.unsetf(ios_base::floatfield)`.
1620
 
1621
  *Returns:* `str`.
1622
 
1623
- #### Error reporting <a id="error.reporting">[[error.reporting]]</a>
1624
 
1625
  ``` cpp
1626
  error_code make_error_code(io_errc e) noexcept;
1627
  ```
1628
 
@@ -1740,11 +1762,11 @@ namespace std {
1740
  pos_type pubseekpos(pos_type sp,
1741
  ios_base::openmode which
1742
  = ios_base::in | ios_base::out);
1743
  int pubsync();
1744
 
1745
- // Get and put areas
1746
  // [streambuf.pub.get], get area
1747
  streamsize in_avail();
1748
  int_type snextc();
1749
  int_type sbumpc();
1750
  int_type sgetc();
@@ -1814,20 +1836,19 @@ for deriving various *stream buffers* whose objects each control two
1814
  *character sequences*:
1815
 
1816
  - a character *input sequence*;
1817
  - a character *output sequence*.
1818
 
1819
- #### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
1820
 
1821
  ``` cpp
1822
  basic_streambuf();
1823
  ```
1824
 
1825
- *Effects:* Constructs an object of class
1826
- `basic_streambuf<charT, traits>` and initializes:[^13]
1827
 
1828
- - all its pointer member objects to null pointers,
1829
  - the `getloc()` member to a copy the global locale, `locale()`, at the
1830
  time of construction.
1831
 
1832
  *Remarks:* Once the `getloc()` member is initialized, results of calling
1833
  locale member functions, and of members of facets so obtained, can
@@ -1835,13 +1856,11 @@ safely be cached until the next time the member `imbue` is called.
1835
 
1836
  ``` cpp
1837
  basic_streambuf(const basic_streambuf& rhs);
1838
  ```
1839
 
1840
- *Effects:* Constructs a copy of `rhs`.
1841
-
1842
- *Postconditions:*
1843
 
1844
  - `eback() == rhs.eback()`
1845
  - `gptr() == rhs.gptr()`
1846
  - `egptr() == rhs.egptr()`
1847
  - `pbase() == rhs.pbase()`
@@ -1853,22 +1872,22 @@ basic_streambuf(const basic_streambuf& rhs);
1853
  ~basic_streambuf();
1854
  ```
1855
 
1856
  *Effects:* None.
1857
 
1858
- #### `basic_streambuf` public member functions <a id="streambuf.members">[[streambuf.members]]</a>
1859
 
1860
  ##### Locales <a id="streambuf.locales">[[streambuf.locales]]</a>
1861
 
1862
  ``` cpp
1863
  locale pubimbue(const locale& loc);
1864
  ```
1865
 
1866
- *Postconditions:* `loc == getloc()`.
1867
-
1868
  *Effects:* Calls `imbue(loc)`.
1869
 
 
 
1870
  *Returns:* Previous value of `getloc()`.
1871
 
1872
  ``` cpp
1873
  locale getloc() const;
1874
  ```
@@ -1914,11 +1933,11 @@ int pubsync();
1914
  ``` cpp
1915
  streamsize in_avail();
1916
  ```
1917
 
1918
  *Returns:* If a read position is available, returns `egptr() - gptr()`.
1919
- Otherwise returns `showmanyc()` ([[streambuf.virt.get]]).
1920
 
1921
  ``` cpp
1922
  int_type snextc();
1923
  ```
1924
 
@@ -1929,11 +1948,11 @@ int_type snextc();
1929
 
1930
  ``` cpp
1931
  int_type sbumpc();
1932
  ```
1933
 
1934
- *Returns:* If the input sequence read position is not available, returns
1935
  `uflow()`. Otherwise, returns `traits::to_int_type(*gptr())` and
1936
  increments the next pointer for the input sequence.
1937
 
1938
  ``` cpp
1939
  int_type sgetc();
@@ -1952,52 +1971,50 @@ streamsize sgetn(char_type* s, streamsize n);
1952
 
1953
  ``` cpp
1954
  int_type sputbackc(char_type c);
1955
  ```
1956
 
1957
- *Returns:* If the input sequence putback position is not available, or
1958
  if `traits::eq(c, gptr()[-1])` is `false`, returns
1959
  `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
1960
  pointer for the input sequence and returns
1961
  `traits::to_int_type(*gptr())`.
1962
 
1963
  ``` cpp
1964
  int_type sungetc();
1965
  ```
1966
 
1967
- *Returns:* If the input sequence putback position is not available,
1968
  returns `pbackfail()`. Otherwise, decrements the next pointer for the
1969
  input sequence and returns `traits::to_int_type(*gptr())`.
1970
 
1971
  ##### Put area <a id="streambuf.pub.put">[[streambuf.pub.put]]</a>
1972
 
1973
  ``` cpp
1974
  int_type sputc(char_type c);
1975
  ```
1976
 
1977
- *Returns:* If the output sequence write position is not available,
1978
  returns `overflow(traits::to_int_type(c))`. Otherwise, stores `c` at the
1979
  next pointer for the output sequence, increments the pointer, and
1980
  returns `traits::to_int_type(c)`.
1981
 
1982
  ``` cpp
1983
  streamsize sputn(const char_type* s, streamsize n);
1984
  ```
1985
 
1986
  *Returns:* `xsputn(s, n)`.
1987
 
1988
- #### `basic_streambuf` protected member functions <a id="streambuf.protected">[[streambuf.protected]]</a>
1989
 
1990
  ##### Assignment <a id="streambuf.assign">[[streambuf.assign]]</a>
1991
 
1992
  ``` cpp
1993
  basic_streambuf& operator=(const basic_streambuf& rhs);
1994
  ```
1995
 
1996
- *Effects:* Assigns the data members of `rhs` to `*this`.
1997
-
1998
- *Postconditions:*
1999
 
2000
  - `eback() == rhs.eback()`
2001
  - `gptr() == rhs.gptr()`
2002
  - `egptr() == rhs.egptr()`
2003
  - `pbase() == rhs.pbase()`
@@ -2041,12 +2058,12 @@ void gbump(int n);
2041
 
2042
  ``` cpp
2043
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
2044
  ```
2045
 
2046
- *Postconditions:* `gbeg == eback()`, `gnext == gptr()`, and
2047
- `gend == egptr()`.
2048
 
2049
  ##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
2050
 
2051
  ``` cpp
2052
  char_type* pbase() const;
@@ -2074,14 +2091,14 @@ void pbump(int n);
2074
 
2075
  ``` cpp
2076
  void setp(char_type* pbeg, char_type* pend);
2077
  ```
2078
 
2079
- *Postconditions:* `pbeg == pbase()`, `pbeg == pptr()`, and
2080
- `pend == epptr()`.
2081
 
2082
- #### `basic_streambuf` virtual functions <a id="streambuf.virtuals">[[streambuf.virtuals]]</a>
2083
 
2084
  ##### Locales <a id="streambuf.virt.locales">[[streambuf.virt.locales]]</a>
2085
 
2086
  ``` cpp
2087
  void imbue(const locale&);
@@ -2142,11 +2159,11 @@ int sync();
2142
  is, if `pbase()` is non-null the characters between `pbase()` and
2143
  `pptr()` are written to the controlled sequence. The pointers may then
2144
  be reset as appropriate.
2145
 
2146
  *Returns:* `-1` on failure. What constitutes failure is determined by
2147
- each derived class ([[filebuf.virtuals]]).
2148
 
2149
  *Default behavior:* Returns zero.
2150
 
2151
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
2152
 
@@ -2183,11 +2200,11 @@ to `sbumpc()` would return `traits::eof()`.
2183
  ``` cpp
2184
  int_type underflow();
2185
  ```
2186
 
2187
  *Remarks:* The public members of `basic_streambuf` call this virtual
2188
- function only if `gptr()` is null or `gptr() >= egptr()`
2189
 
2190
  *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
2191
  of the *pending sequence*, without moving the input sequence position
2192
  past it. If the pending sequence is null then the function returns
2193
  `traits::eof()` to indicate failure.
@@ -2225,13 +2242,13 @@ that either
2225
 
2226
  ``` cpp
2227
  int_type uflow();
2228
  ```
2229
 
2230
- *Requires:* The constraints are the same as for `underflow()`, except
2231
- that the result character shall be transferred from the pending sequence
2232
- to the backup sequence, and the pending sequence shall not be empty
2233
  before the transfer.
2234
 
2235
  *Default behavior:* Calls `underflow()`. If `underflow()` returns
2236
  `traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
2237
  of `traits::to_int_type(*gptr())` and increment the value of the next
@@ -2258,11 +2275,11 @@ modifications that
2258
  is determined.
2259
  - If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
2260
  is prepended. Whether the input sequence is backed up or modified in
2261
  any other way is unspecified.
2262
 
2263
- *Postconditions:* On return, the constraints of `gptr()`, `eback()`, and
2264
  `pptr()` are the same as for `underflow()`.
2265
 
2266
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
2267
  because the input sequence could not be backed up, or if for some other
2268
  reason the pointers could not be set consistent with the constraints.
@@ -2294,32 +2311,32 @@ int_type overflow(int_type c = traits::eof());
2294
 
2295
  *Effects:* Consumes some initial subsequence of the characters of the
2296
  *pending sequence*. The pending sequence is defined as the concatenation
2297
  of
2298
 
2299
- - the empty sequence if `pbase()` is not null, otherwise the
2300
  `pptr() - pbase()` characters beginning at `pbase()`, followed by
2301
  - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
2302
  `true`, otherwise the sequence consisting of `c`.
2303
 
2304
  *Remarks:* The member functions `sputc()` and `sputn()` call this
2305
  function in case that no room can be found in the put buffer enough to
2306
  accommodate the argument character sequence.
2307
 
2308
- *Requires:* Every overriding definition of this virtual function shall
2309
- obey the following constraints:
2310
 
2311
- 1. The effect of consuming a character on the associated output
2312
- sequence is specified[^16]
2313
- 2. Let `r` be the number of characters in the pending sequence not
2314
- consumed. If `r` is nonzero then `pbase()` and `pptr()` shall be set
2315
- so that: `pptr() - pbase() == r` and the `r` characters starting at
2316
  `pbase()` are the associated output stream. In case `r` is zero (all
2317
  characters of the pending sequence have been consumed) then either
2318
- `pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both
2319
- set to the same non-null value.
2320
- 3. The function may fail if either appending some character to the
2321
  associated output stream fails or if it is unable to establish
2322
  `pbase()` and `pptr()` according to the above rules.
2323
 
2324
  *Returns:* `traits::eof()` or throws an exception if the function fails.
2325
 
@@ -2369,10 +2386,17 @@ namespace std {
2369
  template<class charT, class traits>
2370
  basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
2371
  template<class charT, class traits>
2372
  basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
2373
 
 
 
 
 
 
 
 
2374
  template<class charT, class traits, class T>
2375
  basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
2376
  }
2377
  ```
2378
 
@@ -2382,11 +2406,11 @@ namespace std {
2382
  namespace std {
2383
  // types T1, T2, ... are unspecified implementation types
2384
  T1 resetiosflags(ios_base::fmtflags mask);
2385
  T2 setiosflags (ios_base::fmtflags mask);
2386
  T3 setbase(int base);
2387
- template<charT> T4 setfill(charT c);
2388
  T5 setprecision(int n);
2389
  T6 setw(int n);
2390
  template<class moneyT> T7 get_money(moneyT& mon, bool intl = false);
2391
  template<class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
2392
  template<class charT> T9 get_time(struct tm* tmb, const charT* fmt);
@@ -2420,22 +2444,22 @@ extracts from stream rvalues.
2420
  ``` cpp
2421
  namespace std {
2422
  template<class charT, class traits = char_traits<charT>>
2423
  class basic_istream : virtual public basic_ios<charT, traits> {
2424
  public:
2425
- // types (inherited from basic_ios ([ios])):
2426
  using char_type = charT;
2427
  using int_type = typename traits::int_type;
2428
  using pos_type = typename traits::pos_type;
2429
  using off_type = typename traits::off_type;
2430
  using traits_type = traits;
2431
 
2432
  // [istream.cons], constructor/destructor
2433
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2434
  virtual ~basic_istream();
2435
 
2436
- // [istream::sentry], prefix/suffix
2437
  class sentry;
2438
 
2439
  // [istream.formatted], formatted input
2440
  basic_istream<charT, traits>&
2441
  operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
@@ -2485,15 +2509,15 @@ namespace std {
2485
  basic_istream<charT, traits>& seekg(pos_type);
2486
  basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
2487
 
2488
  protected:
2489
  // [istream.cons], copy/move constructor
2490
- basic_istream(const basic_istream& rhs) = delete;
2491
  basic_istream(basic_istream&& rhs);
2492
 
2493
  // [istream.assign], assign and swap
2494
- basic_istream& operator=(const basic_istream& rhs) = delete;
2495
  basic_istream& operator=(basic_istream&& rhs);
2496
  void swap(basic_istream& rhs);
2497
  };
2498
 
2499
  // [istream.extractors], character extraction templates
@@ -2502,16 +2526,16 @@ namespace std {
2502
  template<class traits>
2503
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char&);
2504
  template<class traits>
2505
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char&);
2506
 
2507
- template<class charT, class traits>
2508
- basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT*);
2509
- template<class traits>
2510
- basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char*);
2511
- template<class traits>
2512
- basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char*);
2513
  }
2514
  ```
2515
 
2516
  The class template `basic_istream` defines a number of member function
2517
  signatures that assist in reading and interpreting input from sequences
@@ -2524,72 +2548,67 @@ obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
2524
  or `rdbuf()->sgetc()`. They may use other public members of `istream`.
2525
 
2526
  If `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`,
2527
  then the input function, except as explicitly noted otherwise, completes
2528
  its actions and does `setstate(eofbit)`, which may throw
2529
- `ios_base::failure` ([[iostate.flags]]), before returning.
2530
 
2531
  If one of these called functions throws an exception, then unless
2532
- explicitly noted otherwise, the input function sets `badbit` in error
2533
- state. If `badbit` is on in `exceptions()`, the input function rethrows
2534
- the exception without completing its actions, otherwise it does not
2535
- throw anything and proceeds as if the called function had returned a
2536
  failure indication.
2537
 
2538
- ##### `basic_istream` constructors <a id="istream.cons">[[istream.cons]]</a>
2539
 
2540
  ``` cpp
2541
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2542
  ```
2543
 
2544
- *Effects:* Constructs an object of class `basic_istream`, initializing
2545
- the base class subobject with
2546
- `basic_ios::init(sb)` ([[basic.ios.cons]]).
2547
 
2548
- *Postconditions:* `gcount() == 0`.
2549
 
2550
  ``` cpp
2551
  basic_istream(basic_istream&& rhs);
2552
  ```
2553
 
2554
- *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
2555
- by default constructing the base class, copying the `gcount()` from
2556
- `rhs`, calling `basic_ios<charT, traits>::move(rhs)` to initialize the
2557
- base class, and setting the `gcount()` for `rhs` to 0.
2558
 
2559
  ``` cpp
2560
  virtual ~basic_istream();
2561
  ```
2562
 
2563
- *Effects:* Destroys an object of class `basic_istream`.
2564
-
2565
  *Remarks:* Does not perform any operations of `rdbuf()`.
2566
 
2567
- ##### Class `basic_istream` assign and swap <a id="istream.assign">[[istream.assign]]</a>
2568
 
2569
  ``` cpp
2570
  basic_istream& operator=(basic_istream&& rhs);
2571
  ```
2572
 
2573
- *Effects:* As if by `swap(rhs)`.
2574
 
2575
  *Returns:* `*this`.
2576
 
2577
  ``` cpp
2578
  void swap(basic_istream& rhs);
2579
  ```
2580
 
2581
  *Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`. Exchanges the
2582
  values returned by `gcount()` and `rhs.gcount()`.
2583
 
2584
- ##### Class `basic_istream::sentry` <a id="istream::sentry">[[istream::sentry]]</a>
2585
 
2586
  ``` cpp
2587
  namespace std {
2588
  template<class charT, class traits = char_traits<charT>>
2589
  class basic_istream<charT, traits>::sentry {
2590
- using traits_type = traits;
2591
  bool ok_; // exposition only
2592
  public:
2593
  explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
2594
  ~sentry();
2595
  explicit operator bool() const { return ok_; }
@@ -2640,11 +2659,11 @@ if (ctype.is(ctype.space, c) != 0)
2640
  ```
2641
 
2642
  If, after any preparation is completed, `is.good()` is `true`,
2643
  `ok_ != false` otherwise, `ok_ == false`. During preparation, the
2644
  constructor may call `setstate(failbit)` (which may throw
2645
- `ios_base::failure` ([[iostate.flags]]))[^19]
2646
 
2647
  ``` cpp
2648
  ~sentry();
2649
  ```
2650
 
@@ -2652,23 +2671,23 @@ constructor may call `setstate(failbit)` (which may throw
2652
 
2653
  ``` cpp
2654
  explicit operator bool() const;
2655
  ```
2656
 
2657
- *Effects:* Returns `ok_`.
2658
 
2659
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2660
 
2661
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
2662
 
2663
  Each formatted input function begins execution by constructing an object
2664
  of class `sentry` with the `noskipws` (second) argument `false`. If the
2665
  `sentry` object returns `true`, when converted to a value of type
2666
  `bool`, the function endeavors to obtain the requested input. If an
2667
- exception is thrown during input then `ios::badbit` is turned on[^20] in
2668
- `*this`’s error state. If `(exceptions()&badbit) != 0` then the
2669
- exception is rethrown. In any case, the formatted input function
2670
  destroys the `sentry` object. If no exception has been thrown, it
2671
  returns `*this`.
2672
 
2673
  ##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
2674
 
@@ -2685,11 +2704,11 @@ operator>>(long double& val);
2685
  operator>>(bool& val);
2686
  operator>>(void*& val);
2687
  ```
2688
 
2689
  As in the case of the inserters, these extractors depend on the locale’s
2690
- `num_get<>` ([[locale.num.get]]) object to perform parsing the input
2691
  stream data. These extractors behave as formatted input functions (as
2692
  described in  [[istream.formatted.reqmts]]). After a sentry object is
2693
  constructed, the conversion occurs as if performed by the following code
2694
  fragment:
2695
 
@@ -2789,26 +2808,23 @@ formatted input function (as described
2789
  in  [[istream.formatted.reqmts]]).
2790
 
2791
  *Returns:* `*this`.
2792
 
2793
  ``` cpp
2794
- template<class charT, class traits>
2795
- basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT* s);
2796
- template<class traits>
2797
- basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char* s);
2798
- template<class traits>
2799
- basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char* s);
2800
  ```
2801
 
2802
  *Effects:* Behaves like a formatted input member (as described
2803
  in  [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
2804
- constructed, `operator>>` extracts characters and stores them into
2805
- successive locations of an array whose first element is designated by
2806
- `s`. If `width()` is greater than zero, `n` is `width()`. Otherwise `n`
2807
- is the number of elements of the largest array of `char_type` that can
2808
- store a terminating `charT()`. `n` is the maximum number of characters
2809
- stored.
2810
 
2811
  Characters are extracted and stored until any of the following occurs:
2812
 
2813
  - `n-1` characters are stored;
2814
  - end of file occurs on the input sequence;
@@ -2818,11 +2834,11 @@ Characters are extracted and stored until any of the following occurs:
2818
  `operator>>` then stores a null byte (`charT()`) in the next position,
2819
  which may be the first position if no characters were extracted.
2820
  `operator>>` then calls `width(0)`.
2821
 
2822
  If the function extracted no characters, it calls `setstate(failbit)`,
2823
- which may throw `ios_base::failure` ([[iostate.flags]]).
2824
 
2825
  *Returns:* `in`.
2826
 
2827
  ``` cpp
2828
  template<class charT, class traits>
@@ -2842,28 +2858,28 @@ stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
2842
 
2843
  ``` cpp
2844
  basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
2845
  ```
2846
 
2847
- *Effects:* Behaves as an unformatted input function
2848
- ([[istream.unformatted]]). If `sb` is null, calls `setstate(failbit)`,
2849
- which may throw `ios_base::failure` ([[iostate.flags]]). After a sentry
2850
- object is constructed, extracts characters from `*this` and inserts them
2851
- in the output sequence controlled by `sb`. Characters are extracted and
2852
- inserted until any of the following occurs:
 
2853
 
2854
  - end-of-file occurs on the input sequence;
2855
  - inserting in the output sequence fails (in which case the character to
2856
  be inserted is not extracted);
2857
  - an exception occurs (in which case the exception is caught).
2858
 
2859
  If the function inserts no characters, it calls `setstate(failbit)`,
2860
- which may throw `ios_base::failure` ([[iostate.flags]]). If it inserted
2861
- no characters because it caught an exception thrown while extracting
2862
- characters from `*this` and `failbit` is on in
2863
- `exceptions()` ([[iostate.flags]]), then the caught exception is
2864
- rethrown.
2865
 
2866
  *Returns:* `*this`.
2867
 
2868
  #### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
2869
 
@@ -2876,14 +2892,14 @@ an exception or if the sentry object returns `false`, when converted to
2876
  a value of type `bool`, the function returns without attempting to
2877
  obtain any input. In either case the number of extracted characters is
2878
  set to 0; unformatted input functions taking a character array of
2879
  nonzero size as an argument shall also store a null character (using
2880
  `charT()`) in the first location of the array. If an exception is thrown
2881
- during input then `ios::badbit` is turned on[^23] in `*this`’s error
2882
- state. (Exceptions thrown from `basic_ios<>::clear()` are not caught or
2883
- rethrown.) If `(exceptions()&badbit) != 0` then the exception is
2884
- rethrown. It also counts the number of characters extracted. If no
2885
  exception has been thrown it ends by storing the count in a member
2886
  object and returning the value specified. In any event the `sentry`
2887
  object is destroyed before leaving the unformatted input function.
2888
 
2889
  ``` cpp
@@ -2901,23 +2917,23 @@ int_type get();
2901
  ```
2902
 
2903
  *Effects:* Behaves as an unformatted input function (as described
2904
  above). After constructing a sentry object, extracts a character `c`, if
2905
  one is available. Otherwise, the function calls `setstate(failbit)`,
2906
- which may throw `ios_base::failure` ([[iostate.flags]]),
2907
 
2908
  *Returns:* `c` if available, otherwise `traits::eof()`.
2909
 
2910
  ``` cpp
2911
  basic_istream<charT, traits>& get(char_type& c);
2912
  ```
2913
 
2914
  *Effects:* Behaves as an unformatted input function (as described
2915
  above). After constructing a sentry object, extracts a character, if one
2916
  is available, and assigns it to `c`.[^24] Otherwise, the function calls
2917
- `setstate(failbit)` (which may throw
2918
- `ios_base::failure` ([[iostate.flags]])).
2919
 
2920
  *Returns:* `*this`.
2921
 
2922
  ``` cpp
2923
  basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
@@ -2934,13 +2950,13 @@ the following occurs:
2934
  calls `setstate(eofbit)`);
2935
  - `traits::eq(c, delim)` for the next available input character `c` (in
2936
  which case `c` is not extracted).
2937
 
2938
  If the function stores no characters, it calls `setstate(failbit)`
2939
- (which may throw `ios_base::failure` ([[iostate.flags]])). In any case,
2940
- if `n` is greater than zero it then stores a null character into the
2941
- next successive location of the array.
2942
 
2943
  *Returns:* `*this`.
2944
 
2945
  ``` cpp
2946
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
@@ -2966,11 +2982,11 @@ extracted and inserted until any of the following occurs:
2966
  which case `c` is not extracted);
2967
  - an exception occurs (in which case, the exception is caught but not
2968
  rethrown).
2969
 
2970
  If the function inserts no characters, it calls `setstate(failbit)`,
2971
- which may throw `ios_base::failure` ([[iostate.flags]]).
2972
 
2973
  *Returns:* `*this`.
2974
 
2975
  ``` cpp
2976
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
@@ -2999,11 +3015,11 @@ the following occurs:
2999
  the function calls `setstate(failbit)`).
3000
 
3001
  These conditions are tested in the order shown.[^28]
3002
 
3003
  If the function extracts no characters, it calls `setstate(failbit)`
3004
- (which may throw `ios_base::failure` ([[iostate.flags]])).[^29]
3005
 
3006
  In any case, if `n` is greater than zero, it then stores a null
3007
  character (using `charT()`) into the next successive location of the
3008
  array.
3009
 
@@ -3051,15 +3067,15 @@ basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::
3051
  *Effects:* Behaves as an unformatted input function (as described
3052
  above). After constructing a sentry object, extracts characters and
3053
  discards them. Characters are extracted until any of the following
3054
  occurs:
3055
 
3056
- - `n != numeric_limits<streamsize>::max()` ([[numeric.limits]]) and `n`
3057
  characters have been extracted so far
3058
  - end-of-file occurs on the input sequence (in which case the function
3059
- calls `setstate(eofbit)`, which may throw
3060
- `ios_base::failure` ([[iostate.flags]]));
3061
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
3062
  available input character `c` (in which case `c` is extracted).
3063
 
3064
  *Remarks:* The last condition will never occur if
3065
  `traits::eq_int_type(delim, traits::eof())`.
@@ -3089,11 +3105,11 @@ array whose first element is designated by `s`.[^30] Characters are
3089
  extracted and stored until either of the following occurs:
3090
 
3091
  - `n` characters are stored;
3092
  - end-of-file occurs on the input sequence (in which case the function
3093
  calls `setstate(failbit | eofbit)`, which may throw
3094
- `ios_base::failure` ([[iostate.flags]])).
3095
 
3096
  *Returns:* `*this`.
3097
 
3098
  ``` cpp
3099
  streamsize readsome(char_type* s, streamsize n);
@@ -3103,11 +3119,11 @@ streamsize readsome(char_type* s, streamsize n);
3103
  above). After constructing a sentry object, if `!good()` calls
3104
  `setstate(failbit)` which may throw an exception, and return. Otherwise
3105
  extracts characters and stores them into successive locations of an
3106
  array whose first element is designated by `s`. If
3107
  `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
3108
- `ios_base::failure` ([[iostate.flags]])), and extracts no characters;
3109
 
3110
  - If `rdbuf()->in_avail() == 0`, extracts no characters
3111
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
3112
 
3113
  *Returns:* The number of characters extracted.
@@ -3118,13 +3134,13 @@ basic_istream<charT, traits>& putback(char_type c);
3118
 
3119
  *Effects:* Behaves as an unformatted input function (as described
3120
  above), except that the function first clears `eofbit`. After
3121
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
3122
  which may throw an exception, and return. If `rdbuf()` is not null,
3123
- calls `rdbuf->sputbackc()`. If `rdbuf()` is null, or if `sputbackc()`
3124
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3125
- `ios_base::failure` ([[iostate.flags]])).
3126
 
3127
  [*Note 1*: This function extracts no characters, so the value returned
3128
  by the next call to `gcount()` is 0. — *end note*]
3129
 
3130
  *Returns:* `*this`.
@@ -3135,13 +3151,13 @@ basic_istream<charT, traits>& unget();
3135
 
3136
  *Effects:* Behaves as an unformatted input function (as described
3137
  above), except that the function first clears `eofbit`. After
3138
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
3139
  which may throw an exception, and return. If `rdbuf()` is not null,
3140
- calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc()`
3141
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3142
- `ios_base::failure` ([[iostate.flags]])).
3143
 
3144
  [*Note 2*: This function extracts no characters, so the value returned
3145
  by the next call to `gcount()` is 0. — *end note*]
3146
 
3147
  *Returns:* `*this`.
@@ -3154,11 +3170,11 @@ int sync();
3154
  above), except that it does not count the number of characters extracted
3155
  and does not affect the value returned by subsequent calls to
3156
  `gcount()`. After constructing a sentry object, if `rdbuf()` is a null
3157
  pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
3158
  that function returns `-1` calls `setstate(badbit)` (which may throw
3159
- `ios_base::failure` ([[iostate.flags]]), and returns `-1`. Otherwise,
3160
  returns zero.
3161
 
3162
  ``` cpp
3163
  pos_type tellg();
3164
  ```
@@ -3202,45 +3218,49 @@ function calls `setstate(failbit)` (which may throw
3202
 
3203
  *Returns:* `*this`.
3204
 
3205
  #### Standard `basic_istream` manipulators <a id="istream.manip">[[istream.manip]]</a>
3206
 
 
 
 
3207
  ``` cpp
3208
  template<class charT, class traits>
3209
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
3210
  ```
3211
 
3212
- *Effects:* Behaves as an unformatted input function
3213
- ([[istream.unformatted]]), except that it does not count the number of
3214
- characters extracted and does not affect the value returned by
3215
- subsequent calls to is.gcount(). After constructing a sentry object
3216
  extracts characters as long as the next available character `c` is
3217
  whitespace or until there are no more characters in the sequence.
3218
  Whitespace characters are distinguished with the same criterion as used
3219
- by `sentry::sentry` ([[istream::sentry]]). If `ws` stops extracting
3220
  characters because there are no more available it sets `eofbit`, but not
3221
  `failbit`.
3222
 
3223
  *Returns:* `is`.
3224
 
3225
  #### Rvalue stream extraction <a id="istream.rvalue">[[istream.rvalue]]</a>
3226
 
3227
  ``` cpp
3228
- template <class charT, class traits, class T>
3229
- basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);
3230
  ```
3231
 
 
 
 
 
3232
  *Effects:* Equivalent to:
3233
 
3234
  ``` cpp
3235
  is >> std::forward<T>(x);
3236
- return is;
3237
  ```
3238
 
3239
- *Remarks:* This function shall not participate in overload resolution
3240
- unless the expression `is >> std::forward<T>(x)` is well-formed.
3241
-
3242
  #### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
3243
 
3244
  ``` cpp
3245
  namespace std {
3246
  template<class charT, class traits = char_traits<charT>>
@@ -3260,62 +3280,59 @@ namespace std {
3260
  // [iostream.dest], destructor
3261
  virtual ~basic_iostream();
3262
 
3263
  protected:
3264
  // [iostream.cons], constructor
3265
- basic_iostream(const basic_iostream& rhs) = delete;
3266
  basic_iostream(basic_iostream&& rhs);
3267
 
3268
  // [iostream.assign], assign and swap
3269
- basic_iostream& operator=(const basic_iostream& rhs) = delete;
3270
  basic_iostream& operator=(basic_iostream&& rhs);
3271
  void swap(basic_iostream& rhs);
3272
  };
3273
  }
3274
  ```
3275
 
3276
  The class template `basic_iostream` inherits a number of functions that
3277
  allow reading input and writing output to sequences controlled by a
3278
  stream buffer.
3279
 
3280
- ##### `basic_iostream` constructors <a id="iostream.cons">[[iostream.cons]]</a>
3281
 
3282
  ``` cpp
3283
  explicit basic_iostream(basic_streambuf<charT, traits>* sb);
3284
  ```
3285
 
3286
- *Effects:* Constructs an object of class `basic_iostream`, initializing
3287
- the base class subobjects with
3288
- `basic_istream<charT, traits>(sb)` ([[istream]]) and
3289
- `basic_ostream<charT, traits>(sb)` ([[ostream]]).
3290
 
3291
- *Postconditions:* `rdbuf() == sb` and `gcount() == 0`.
3292
 
3293
  ``` cpp
3294
  basic_iostream(basic_iostream&& rhs);
3295
  ```
3296
 
3297
  *Effects:* Move constructs from the rvalue `rhs` by constructing the
3298
  `basic_istream` base class with `move(rhs)`.
3299
 
3300
- ##### `basic_iostream` destructor <a id="iostream.dest">[[iostream.dest]]</a>
3301
 
3302
  ``` cpp
3303
  virtual ~basic_iostream();
3304
  ```
3305
 
3306
- *Effects:* Destroys an object of class `basic_iostream`.
3307
-
3308
  *Remarks:* Does not perform any operations on `rdbuf()`.
3309
 
3310
- ##### `basic_iostream` assign and swap <a id="iostream.assign">[[iostream.assign]]</a>
3311
 
3312
  ``` cpp
3313
  basic_iostream& operator=(basic_iostream&& rhs);
3314
  ```
3315
 
3316
- *Effects:* As if by `swap(rhs)`.
3317
 
3318
  ``` cpp
3319
  void swap(basic_iostream& rhs);
3320
  ```
3321
 
@@ -3332,22 +3349,22 @@ that inserts into stream rvalues.
3332
  ``` cpp
3333
  namespace std {
3334
  template<class charT, class traits = char_traits<charT>>
3335
  class basic_ostream : virtual public basic_ios<charT, traits> {
3336
  public:
3337
- // types (inherited from basic_ios ([ios])):
3338
  using char_type = charT;
3339
  using int_type = typename traits::int_type;
3340
  using pos_type = typename traits::pos_type;
3341
  using off_type = typename traits::off_type;
3342
  using traits_type = traits;
3343
 
3344
  // [ostream.cons], constructor/destructor
3345
  explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
3346
  virtual ~basic_ostream();
3347
 
3348
- // [ostream::sentry], prefix/suffix
3349
  class sentry;
3350
 
3351
  // [ostream.formatted], formatted output
3352
  basic_ostream<charT, traits>&
3353
  operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
@@ -3384,15 +3401,15 @@ namespace std {
3384
  basic_ostream<charT, traits>& seekp(pos_type);
3385
  basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
3386
 
3387
  protected:
3388
  // [ostream.cons], copy/move constructor
3389
- basic_ostream(const basic_ostream& rhs) = delete;
3390
  basic_ostream(basic_ostream&& rhs);
3391
 
3392
  // [ostream.assign], assign and swap
3393
- basic_ostream& operator=(const basic_ostream& rhs) = delete;
3394
  basic_ostream& operator=(basic_ostream&& rhs);
3395
  void swap(basic_ostream& rhs);
3396
  };
3397
 
3398
  // [ostream.inserters.character], character inserters
@@ -3406,10 +3423,28 @@ namespace std {
3406
  template<class traits>
3407
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, signed char);
3408
  template<class traits>
3409
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, unsigned char);
3410
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3411
  template<class charT, class traits>
3412
  basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const charT*);
3413
  template<class charT, class traits>
3414
  basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const char*);
3415
  template<class traits>
@@ -3417,10 +3452,32 @@ namespace std {
3417
 
3418
  template<class traits>
3419
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const signed char*);
3420
  template<class traits>
3421
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const unsigned char*);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3422
  }
3423
  ```
3424
 
3425
  The class template `basic_ostream` defines a number of member function
3426
  signatures that assist in formatting and writing output to output
@@ -3433,26 +3490,29 @@ output functions.* Both groups of output functions generate (or
3433
  `rdbuf()->sputc(int_type)`. They may use other public members of
3434
  `basic_ostream` except that they shall not invoke any virtual members of
3435
  `rdbuf()` except `overflow()`, `xsputn()`, and `sync()`.
3436
 
3437
  If one of these called functions throws an exception, then unless
3438
- explicitly noted otherwise the output function sets `badbit` in error
3439
- state. If `badbit` is on in `exceptions()`, the output function rethrows
3440
- the exception without completing its actions, otherwise it does not
3441
- throw anything and treat as an error.
 
3442
 
3443
- ##### `basic_ostream` constructors <a id="ostream.cons">[[ostream.cons]]</a>
 
 
 
3444
 
3445
  ``` cpp
3446
  explicit basic_ostream(basic_streambuf<charT, traits>* sb);
3447
  ```
3448
 
3449
- *Effects:* Constructs an object of class `basic_ostream`, initializing
3450
- the base class subobject with
3451
- `basic_ios<charT, traits>::init(sb)` ([[basic.ios.cons]]).
3452
 
3453
- *Postconditions:* `rdbuf() == sb`.
3454
 
3455
  ``` cpp
3456
  basic_ostream(basic_ostream&& rhs);
3457
  ```
3458
 
@@ -3462,31 +3522,29 @@ by default constructing the base class and calling
3462
 
3463
  ``` cpp
3464
  virtual ~basic_ostream();
3465
  ```
3466
 
3467
- *Effects:* Destroys an object of class `basic_ostream`.
3468
-
3469
  *Remarks:* Does not perform any operations on `rdbuf()`.
3470
 
3471
- ##### Class `basic_ostream` assign and swap <a id="ostream.assign">[[ostream.assign]]</a>
3472
 
3473
  ``` cpp
3474
  basic_ostream& operator=(basic_ostream&& rhs);
3475
  ```
3476
 
3477
- *Effects:* As if by `swap(rhs)`.
3478
 
3479
  *Returns:* `*this`.
3480
 
3481
  ``` cpp
3482
  void swap(basic_ostream& rhs);
3483
  ```
3484
 
3485
  *Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`.
3486
 
3487
- ##### Class `basic_ostream::sentry` <a id="ostream::sentry">[[ostream::sentry]]</a>
3488
 
3489
  ``` cpp
3490
  namespace std {
3491
  template<class charT, class traits = char_traits<charT>>
3492
  class basic_ostream<charT, traits>::sentry {
@@ -3513,11 +3571,11 @@ If `os.good()` is nonzero, prepares for formatted or unformatted output.
3513
  If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^31]
3514
 
3515
  If, after any preparation is completed, `os.good()` is `true`,
3516
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
3517
  constructor may call `setstate(failbit)` (which may throw
3518
- `ios_base::failure` ([[iostate.flags]]))[^32]
3519
 
3520
  ``` cpp
3521
  ~sentry();
3522
  ```
3523
 
@@ -3530,11 +3588,11 @@ sets `badbit` in `os.rdstate()` without propagating an exception.
3530
  explicit operator bool() const;
3531
  ```
3532
 
3533
  *Effects:* Returns `ok_`.
3534
 
3535
- ##### `basic_ostream` seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
3536
 
3537
  Each seek member function begins execution by constructing an object of
3538
  class `sentry`. It returns by destroying the `sentry` object.
3539
 
3540
  ``` cpp
@@ -3573,12 +3631,12 @@ function calls `setstate(failbit)` (which may throw
3573
  Each formatted output function begins execution by constructing an
3574
  object of class `sentry`. If this object returns `true` when converted
3575
  to a value of type `bool`, the function endeavors to generate the
3576
  requested output. If the generation fails, then the formatted output
3577
  function does `setstate(ios_base::failbit)`, which might throw an
3578
- exception. If an exception is thrown during output, then `ios::badbit`
3579
- is turned on[^33] in `*this`’s error state. If
3580
  `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
3581
  not an exception is thrown, the `sentry` object is destroyed before
3582
  leaving the formatted output function. If no exception is thrown, the
3583
  result of the formatted output function is `*this`.
3584
 
@@ -3719,13 +3777,13 @@ in  [[ostream.formatted.reqmts]]).
3719
 
3720
  ``` cpp
3721
  basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
3722
  ```
3723
 
3724
- *Effects:* Behaves as an unformatted output function
3725
- ([[ostream.unformatted]]). After the sentry object is constructed, if
3726
- `sb` is null calls `setstate(badbit)` (which may throw
3727
  `ios_base::failure`).
3728
 
3729
  Gets characters from `sb` and inserts them in `*this`. Characters are
3730
  read from `sb` and inserted until any of the following occurs:
3731
 
@@ -3733,14 +3791,14 @@ read from `sb` and inserted until any of the following occurs:
3733
  - inserting in the output sequence fails (in which case the character to
3734
  be inserted is not extracted);
3735
  - an exception occurs while getting a character from `sb`.
3736
 
3737
  If the function inserts no characters, it calls `setstate(failbit)`
3738
- (which may throw `ios_base::failure` ([[iostate.flags]])). If an
3739
- exception was thrown while extracting a character, the function sets
3740
- `failbit` in error state, and if `failbit` is on in `exceptions()` the
3741
- caught exception is rethrown.
3742
 
3743
  *Returns:* `*this`.
3744
 
3745
  ``` cpp
3746
  basic_ostream<charT, traits>& operator<<(nullptr_t);
@@ -3750,11 +3808,11 @@ basic_ostream<charT, traits>& operator<<(nullptr_t);
3750
 
3751
  ``` cpp
3752
  return *this << s;
3753
  ```
3754
 
3755
- where `s` is an *implementation-defined* NTCTS ([[defns.ntcts]]).
3756
 
3757
  ##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
3758
 
3759
  ``` cpp
3760
  template<class charT, class traits>
@@ -3770,16 +3828,16 @@ template<class traits>
3770
  template<class traits>
3771
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
3772
  ```
3773
 
3774
  *Effects:* Behaves as a formatted output
3775
- function ([[ostream.formatted.reqmts]]) of `out`. Constructs a
3776
- character sequence `seq`. If `c` has type `char` and the character type
3777
- of the stream is not `char`, then `seq` consists of `out.widen(c)`;
3778
- otherwise `seq` consists of `c`. Determines padding for `seq` as
3779
- described in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`.
3780
- Calls `os.width(0)`.
3781
 
3782
  *Returns:* `out`.
3783
 
3784
  ``` cpp
3785
  template<class charT, class traits>
@@ -3793,17 +3851,17 @@ template<class traits>
3793
  template<class traits>
3794
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
3795
  const unsigned char* s);
3796
  ```
3797
 
3798
- *Requires:* `s` shall not be a null pointer.
3799
 
3800
  *Effects:* Behaves like a formatted inserter (as described
3801
  in  [[ostream.formatted.reqmts]]) of `out`. Creates a character sequence
3802
  `seq` of `n` characters starting at `s`, each widened using
3803
- `out.widen()` ([[basic.ios.members]]), where `n` is the number that
3804
- would be computed as if by:
3805
 
3806
  - `traits::length(s)` for the overload where the first argument is of
3807
  type `basic_ostream<charT, traits>&` and the second is of type
3808
  `const charT*`, and also for the overload where the first argument is
3809
  of type `basic_ostream<char, traits>&` and the second is of type
@@ -3824,11 +3882,11 @@ in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
3824
 
3825
  Each unformatted output function begins execution by constructing an
3826
  object of class `sentry`. If this object returns `true`, while
3827
  converting to a value of type `bool`, the function endeavors to generate
3828
  the requested output. If an exception is thrown during output, then
3829
- `ios::badbit` is turned on[^36] in `*this`’s error state. If
3830
  `(exceptions() & badbit) != 0` then the exception is rethrown. In any
3831
  case, the unformatted output function ends by destroying the sentry
3832
  object, then, if no exception was thrown, returning the value specified
3833
  for the unformatted output function.
3834
 
@@ -3838,12 +3896,12 @@ basic_ostream<charT, traits>& put(char_type c);
3838
 
3839
  *Effects:* Behaves as an unformatted output function (as described
3840
  above). After constructing a sentry object, inserts the character `c`,
3841
  if possible.[^37]
3842
 
3843
- Otherwise, calls `setstate(badbit)` (which may throw
3844
- `ios_base::failure` ([[iostate.flags]])).
3845
 
3846
  *Returns:* `*this`.
3847
 
3848
  ``` cpp
3849
  basic_ostream& write(const char_type* s, streamsize n);
@@ -3855,12 +3913,12 @@ from successive locations of an array whose first element is designated
3855
  by `s`.[^38] Characters are inserted until either of the following
3856
  occurs:
3857
 
3858
  - `n` characters are inserted;
3859
  - inserting in the output sequence fails (in which case the function
3860
- calls `setstate(badbit)`, which may throw
3861
- `ios_base::failure` ([[iostate.flags]])).
3862
 
3863
  *Returns:* `*this`.
3864
 
3865
  ``` cpp
3866
  basic_ostream& flush();
@@ -3868,17 +3926,20 @@ basic_ostream& flush();
3868
 
3869
  *Effects:* Behaves as an unformatted output function (as described
3870
  above). If `rdbuf()` is not a null pointer, constructs a sentry object.
3871
  If this object returns `true` when converted to a value of type `bool`
3872
  the function calls `rdbuf()->pubsync()`. If that function returns -1
3873
- calls `setstate(badbit)` (which may throw
3874
- `ios_base::failure` ([[iostate.flags]])). Otherwise, if the sentry
3875
- object returns `false`, does nothing.
3876
 
3877
  *Returns:* `*this`.
3878
 
3879
- #### Standard `basic_ostream` manipulators <a id="ostream.manip">[[ostream.manip]]</a>
 
 
 
3880
 
3881
  ``` cpp
3882
  template<class charT, class traits>
3883
  basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
3884
  ```
@@ -3904,23 +3965,64 @@ template <class charT, class traits>
3904
 
3905
  *Effects:* Calls `os.flush()`.
3906
 
3907
  *Returns:* `os`.
3908
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3909
  #### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
3910
 
3911
  ``` cpp
3912
- template <class charT, class traits, class T>
3913
- basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
3914
  ```
3915
 
 
 
 
 
3916
  *Effects:* As if by: `os << x;`
3917
 
3918
- *Returns:* `os`.
3919
-
3920
- *Remarks:* This function shall not participate in overload resolution
3921
- unless the expression `os << x` is well-formed.
3922
 
3923
  ### Standard manipulators <a id="std.manip">[[std.manip]]</a>
3924
 
3925
  The header `<iomanip>` defines several functions that support extractors
3926
  and inserters that alter information maintained by class `ios_base` and
@@ -3942,14 +4044,14 @@ void f(ios_base& str, ios_base::fmtflags mask) {
3942
  // reset specified flags
3943
  str.setf(ios_base::fmtflags(0), mask);
3944
  }
3945
  ```
3946
 
3947
- The expression `out << resetiosflags(mask)` shall have type
3948
  `basic_ostream<charT, traits>&` and value `out`. The expression
3949
- `in >> resetiosflags(mask)` shall have type
3950
- `basic_istream<charT, traits>&` and value `in`.
3951
 
3952
  ``` cpp
3953
  unspecified setiosflags(ios_base::fmtflags mask);
3954
  ```
3955
 
@@ -3965,14 +4067,14 @@ void f(ios_base& str, ios_base::fmtflags mask) {
3965
  // set specified flags
3966
  str.setf(mask);
3967
  }
3968
  ```
3969
 
3970
- The expression `out << setiosflags(mask)` shall have type
3971
  `basic_ostream<charT, traits>&` and value `out`. The expression
3972
- `in >> setiosflags(mask)` shall have type `basic_istream<charT,`
3973
- `traits>&` and value `in`.
3974
 
3975
  ``` cpp
3976
  unspecified setbase(int base);
3977
  ```
3978
 
@@ -3991,14 +4093,14 @@ void f(ios_base& str, int base) {
3991
  base == 16 ? ios_base::hex :
3992
  ios_base::fmtflags(0), ios_base::basefield);
3993
  }
3994
  ```
3995
 
3996
- The expression `out << setbase(base)` shall have type
3997
  `basic_ostream<charT, traits>&` and value `out`. The expression
3998
- `in >> setbase(base)` shall have type `basic_istream<charT, traits>&`
3999
- and value `in`.
4000
 
4001
  ``` cpp
4002
  unspecified setfill(char_type c);
4003
  ```
4004
 
@@ -4013,11 +4115,11 @@ void f(basic_ios<charT, traits>& str, charT c) {
4013
  // set fill character
4014
  str.fill(c);
4015
  }
4016
  ```
4017
 
4018
- The expression `out << setfill(c)` shall have type
4019
  `basic_ostream<charT, traits>&` and value `out`.
4020
 
4021
  ``` cpp
4022
  unspecified setprecision(int n);
4023
  ```
@@ -4034,14 +4136,14 @@ void f(ios_base& str, int n) {
4034
  // set precision
4035
  str.precision(n);
4036
  }
4037
  ```
4038
 
4039
- The expression `out << setprecision(n)` shall have type
4040
  `basic_ostream<charT, traits>&` and value `out`. The expression
4041
- `in >> setprecision(n)` shall have type `basic_istream<charT, traits>&`
4042
- and value `in`.
4043
 
4044
  ``` cpp
4045
  unspecified setw(int n);
4046
  ```
4047
 
@@ -4057,14 +4159,13 @@ void f(ios_base& str, int n) {
4057
  // set width
4058
  str.width(n);
4059
  }
4060
  ```
4061
 
4062
- The expression `out << setw(n)` shall have type
4063
- `basic_ostream<charT, traits>&` and value `out`. The expression
4064
- `in >> setw(n)` shall have type `basic_istream<charT, traits>&` and
4065
- value `in`.
4066
 
4067
  ### Extended manipulators <a id="ext.manip">[[ext.manip]]</a>
4068
 
4069
  The header `<iomanip>` defines several functions that support extractors
4070
  and inserters that allow for the parsing and formatting of sequences and
@@ -4072,15 +4173,15 @@ values for money and time.
4072
 
4073
  ``` cpp
4074
  template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
4075
  ```
4076
 
4077
- *Requires:* The type `moneyT` shall be either `long double` or a
4078
- specialization of the `basic_string` template (Clause  [[strings]]).
4079
 
4080
  *Effects:* The expression `in >> get_money(mon, intl)` described below
4081
- behaves as a formatted input function ([[istream.formatted.reqmts]]).
4082
 
4083
  *Returns:* An object of unspecified type such that if `in` is an object
4084
  of type `basic_istream<charT, traits>` then the expression
4085
  `in >> get_money(mon, intl)` behaves as if it called `f(in, mon, intl)`,
4086
  where the function `f` is defined as:
@@ -4099,24 +4200,24 @@ void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
4099
  if (ios_base::goodbit != err)
4100
  str.setstate(err);
4101
  }
4102
  ```
4103
 
4104
- The expression `in >> get_money(mon, intl)` shall have type
4105
  `basic_istream<charT, traits>&` and value `in`.
4106
 
4107
  ``` cpp
4108
  template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
4109
  ```
4110
 
4111
- *Requires:* The type `moneyT` shall be either `long double` or a
4112
- specialization of the `basic_string` template (Clause  [[strings]]).
4113
 
4114
  *Returns:* An object of unspecified type such that if `out` is an object
4115
  of type `basic_ostream<charT, traits>` then the expression
4116
  `out << put_money(mon, intl)` behaves as a formatted output
4117
- function ([[ostream.formatted.reqmts]]) that calls `f(out, mon, intl)`,
4118
  where the function `f` is defined as:
4119
 
4120
  ``` cpp
4121
  template<class charT, class traits, class moneyT>
4122
  void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
@@ -4125,25 +4226,24 @@ void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
4125
 
4126
  const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
4127
  const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);
4128
 
4129
  if (end.failed())
4130
- str.setstate(ios::badbit);
4131
  }
4132
  ```
4133
 
4134
- The expression `out << put_money(mon, intl)` shall have type
4135
  `basic_ostream<charT, traits>&` and value `out`.
4136
 
4137
  ``` cpp
4138
  template<class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
4139
  ```
4140
 
4141
- *Requires:* The argument `tmb` shall be a valid pointer to an object of
4142
- type `struct tm`. The argument `fmt` shall be a valid pointer to an
4143
- array of objects of type `charT` with `char_traits<charT>::length(fmt)`
4144
- elements.
4145
 
4146
  *Returns:* An object of unspecified type such that if `in` is an object
4147
  of type `basic_istream<charT, traits>` then the expression
4148
  `in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
4149
  where the function `f` is defined as:
@@ -4163,21 +4263,20 @@ void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
4163
  if (err != ios_base::goodbit)
4164
  str.setstate(err);
4165
  }
4166
  ```
4167
 
4168
- The expression `in >> get_time(tmb, fmt)` shall have type
4169
  `basic_istream<charT, traits>&` and value `in`.
4170
 
4171
  ``` cpp
4172
  template<class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
4173
  ```
4174
 
4175
- *Requires:* The argument `tmb` shall be a valid pointer to an object of
4176
- type `struct tm`, and the argument `fmt` shall be a valid pointer to an
4177
- array of objects of type `charT` with `char_traits<charT>::length(fmt)`
4178
- elements.
4179
 
4180
  *Returns:* An object of unspecified type such that if `out` is an object
4181
  of type `basic_ostream<charT, traits>` then the expression
4182
  `out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
4183
  where the function `f` is defined as:
@@ -4195,11 +4294,11 @@ void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
4195
  if (end.failed())
4196
  str.setstate(ios_base::badbit);
4197
  }
4198
  ```
4199
 
4200
- The expression `out << put_time(tmb, fmt)` shall have type
4201
  `basic_ostream<charT, traits>&` and value `out`.
4202
 
4203
  ### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
4204
 
4205
  [*Note 1*: Quoted manipulators provide string insertion and extraction
@@ -4222,13 +4321,12 @@ template <class charT, class traits>
4222
  *Returns:* An object of unspecified type such that if `out` is an
4223
  instance of `basic_ostream` with member type `char_type` the same as
4224
  `charT` and with member type `traits_type`, which in the second and
4225
  third forms is the same as `traits`, then the expression
4226
  `out << quoted(s, delim, escape)` behaves as a formatted output
4227
- function ([[ostream.formatted.reqmts]]) of `out`. This forms a
4228
- character sequence `seq`, initially consisting of the following
4229
- elements:
4230
 
4231
  - `delim`.
4232
  - Each character in `s`. If the character to be output is equal to
4233
  `escape` or `delim`, as determined by `traits_type::eq`, first output
4234
  `escape`.
@@ -4236,11 +4334,11 @@ elements:
4236
 
4237
  Let `x` be the number of elements initially in `seq`. Then padding is
4238
  determined for `seq` as described in  [[ostream.formatted.reqmts]],
4239
  `seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
4240
  `n` is the larger of `out.width()` and `x`, and `out.width(0)` is
4241
- called. The expression `out << quoted(s, delim, escape)` shall have type
4242
  `basic_ostream<charT, traits>&` and value `out`.
4243
 
4244
  ``` cpp
4245
  template<class charT, class traits, class Allocator>
4246
  unspecified quoted(basic_string<charT, traits, Allocator>& s,
@@ -4251,12 +4349,13 @@ template <class charT, class traits, class Allocator>
4251
 
4252
  - If `in` is an instance of `basic_istream` with member types
4253
  `char_type` and `traits_type` the same as `charT` and `traits`,
4254
  respectively, then the expression `in >> quoted(s, delim, escape)`
4255
  behaves as if it extracts the following characters from `in` using
4256
- `operator>>(basic_istream<charT, traits>&, charT&)` ([[istream.extractors]])
4257
- which may throw `ios_base::failure` ([[ios::failure]]):
 
4258
  - If the first character extracted is equal to `delim`, as determined
4259
  by `traits_type::eq`, then:
4260
  - Turn off the `skipws` flag.
4261
  - `s.clear()`
4262
  - Until an unescaped `delim` character is reached or `!in`, extract
@@ -4270,14 +4369,13 @@ template <class charT, class traits, class Allocator>
4270
  `char_type` and `traits_type` the same as `charT` and `traits`,
4271
  respectively, then the expression `out << quoted(s, delim, escape)`
4272
  behaves as specified for the
4273
  `const basic_string<charT, traits, Allocator>&` overload of the
4274
  `quoted` function.
4275
-
4276
- The expression `in >> quoted(s, delim, escape)` shall have type
4277
- `basic_istream<charT, traits>&` and value `in`. The expression
4278
- `out << quoted(s, delim, escape)` shall have type
4279
  `basic_ostream<charT, traits>&` and value `out`.
4280
 
4281
  ## String-based streams <a id="string.streams">[[string.streams]]</a>
4282
 
4283
  ### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
@@ -4330,26 +4428,55 @@ namespace std {
4330
  using off_type = typename traits::off_type;
4331
  using traits_type = traits;
4332
  using allocator_type = Allocator;
4333
 
4334
  // [stringbuf.cons], constructors
 
 
4335
  explicit basic_stringbuf(
 
4336
  ios_base::openmode which = ios_base::in | ios_base::out);
 
 
 
4337
  explicit basic_stringbuf(
4338
- const basic_string<charT, traits, Allocator>& str,
4339
  ios_base::openmode which = ios_base::in | ios_base::out);
4340
- basic_stringbuf(const basic_stringbuf& rhs) = delete;
 
 
 
 
 
 
 
 
 
 
 
 
4341
  basic_stringbuf(basic_stringbuf&& rhs);
 
4342
 
4343
  // [stringbuf.assign], assign and swap
4344
- basic_stringbuf& operator=(const basic_stringbuf& rhs) = delete;
4345
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
4346
- void swap(basic_stringbuf& rhs);
 
 
 
 
 
 
 
 
 
4347
 
4348
- // [stringbuf.members], get and set
4349
- basic_string<charT, traits, Allocator> str() const;
4350
  void str(const basic_string<charT, traits, Allocator>& s);
 
 
 
4351
 
4352
  protected:
4353
  // [stringbuf.virtuals], overridden virtual functions
4354
  int_type underflow() override;
4355
  int_type pbackfail(int_type c = traits::eof()) override;
@@ -4363,66 +4490,120 @@ namespace std {
4363
  ios_base::openmode which
4364
  = ios_base::in | ios_base::out) override;
4365
 
4366
  private:
4367
  ios_base::openmode mode; // exposition only
 
 
4368
  };
4369
 
4370
  template<class charT, class traits, class Allocator>
4371
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
4372
- basic_stringbuf<charT, traits, Allocator>& y);
4373
  }
4374
  ```
4375
 
4376
  The class `basic_stringbuf` is derived from `basic_streambuf` to
4377
  associate possibly the input sequence and possibly the output sequence
4378
  with a sequence of arbitrary *characters*. The sequence can be
4379
  initialized from, or made available as, an object of class
4380
  `basic_string`.
4381
 
4382
- For the sake of exposition, the maintained data is presented here as:
 
4383
 
4384
  - `ios_base::openmode mode`, has `in` set if the input sequence can be
4385
  read, and `out` set if the output sequence can be written.
 
 
 
 
 
4386
 
4387
- #### `basic_stringbuf` constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
4388
 
4389
  ``` cpp
4390
- explicit basic_stringbuf(
4391
- ios_base::openmode which = ios_base::in | ios_base::out);
4392
  ```
4393
 
4394
- *Effects:* Constructs an object of class `basic_stringbuf`, initializing
4395
- the base class with `basic_streambuf()` ([[streambuf.cons]]), and
4396
- initializing `mode` with `which`.
 
 
4397
 
4398
- *Postconditions:* `str() == ""`.
4399
 
4400
  ``` cpp
4401
  explicit basic_stringbuf(
4402
  const basic_string<charT, traits, Allocator>& s,
4403
  ios_base::openmode which = ios_base::in | ios_base::out);
4404
  ```
4405
 
4406
- *Effects:* Constructs an object of class `basic_stringbuf`, initializing
4407
- the base class with `basic_streambuf()` ([[streambuf.cons]]), and
4408
- initializing `mode` with `which`. Then calls `str(s)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4409
 
4410
  ``` cpp
4411
  basic_stringbuf(basic_stringbuf&& rhs);
 
4412
  ```
4413
 
4414
- *Effects:* Move constructs from the rvalue `rhs`. It is
4415
- *implementation-defined* whether the sequence pointers in `*this`
4416
- (`eback()`, `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) obtain
4417
- the values which `rhs` had. Whether they do or not, `*this` and `rhs`
4418
- reference separate buffers (if any at all) after the construction. The
4419
- openmode, locale and any other state of `rhs` is also copied.
4420
 
4421
- *Postconditions:* Let `rhs_p` refer to the state of `rhs` just prior to
4422
- this construction and let `rhs_a` refer to the state of `rhs` just after
4423
- this construction.
4424
 
4425
  - `str() == rhs_p.str()`
4426
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
4427
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
4428
  - `pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()`
@@ -4431,12 +4612,14 @@ this construction.
4431
  - `if (gptr()) gptr() != rhs_a.gptr()`
4432
  - `if (egptr()) egptr() != rhs_a.egptr()`
4433
  - `if (pbase()) pbase() != rhs_a.pbase()`
4434
  - `if (pptr()) pptr() != rhs_a.pptr()`
4435
  - `if (epptr()) epptr() != rhs_a.epptr()`
 
 
4436
 
4437
- #### Assign and swap <a id="stringbuf.assign">[[stringbuf.assign]]</a>
4438
 
4439
  ``` cpp
4440
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
4441
  ```
4442
 
@@ -4445,62 +4628,165 @@ would have had if it had been move constructed from `rhs`
4445
  (see  [[stringbuf.cons]]).
4446
 
4447
  *Returns:* `*this`.
4448
 
4449
  ``` cpp
4450
- void swap(basic_stringbuf& rhs);
4451
  ```
4452
 
 
 
 
 
4453
  *Effects:* Exchanges the state of `*this` and `rhs`.
4454
 
 
 
 
 
4455
  ``` cpp
4456
  template<class charT, class traits, class Allocator>
4457
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
4458
- basic_stringbuf<charT, traits, Allocator>& y);
4459
  ```
4460
 
4461
- *Effects:* As if by `x.swap(y)`.
4462
 
4463
  #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
4464
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4465
  ``` cpp
4466
- basic_string<charT, traits, Allocator> str() const;
4467
- ```
4468
-
4469
- *Returns:* A `basic_string` object whose content is equal to the
4470
- `basic_stringbuf` underlying character sequence. If the
4471
- `basic_stringbuf` was created only in input mode, the resultant
4472
- `basic_string` contains the character sequence in the range \[`eback()`,
4473
- `egptr()`). If the `basic_stringbuf` was created with
4474
- `which & ios_base::out` being nonzero then the resultant `basic_string`
4475
- contains the character sequence in the range \[`pbase()`, `high_mark`),
4476
- where `high_mark` represents the position one past the highest
4477
- initialized character in the buffer. Characters can be initialized by
4478
- writing to the stream, by constructing the `basic_stringbuf` with a
4479
- `basic_string`, or by calling the `str(basic_string)` member function.
4480
- In the case of calling the `str(basic_string)` member function, all
4481
- characters initialized prior to the call are now considered
4482
- uninitialized (except for those characters re-initialized by the new
4483
- `basic_string`). Otherwise the `basic_stringbuf` has been created in
4484
- neither input nor output mode and a zero length `basic_string` is
4485
- returned.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4486
 
4487
  ``` cpp
4488
  void str(const basic_string<charT, traits, Allocator>& s);
4489
  ```
4490
 
4491
- *Effects:* Copies the content of `s` into the `basic_stringbuf`
4492
- underlying character sequence and initializes the input and output
4493
- sequences according to `mode`.
4494
-
4495
- *Postconditions:* If `mode & ios_base::out` is nonzero, `pbase()` points
4496
- to the first underlying character and `epptr()` `>= pbase() + s.size()`
4497
- holds; in addition, if `mode & ios_base::ate` is nonzero,
4498
- `pptr() == pbase() + s.size()` holds, otherwise `pptr() == pbase()` is
4499
- `true`. If `mode & ios_base::in` is nonzero, `eback()` points to the
4500
- first underlying character, and both `gptr() == eback()` and
4501
- `egptr() == eback() + s.size()` hold.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4502
 
4503
  #### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
4504
 
4505
  ``` cpp
4506
  int_type underflow() override;
@@ -4527,11 +4813,11 @@ sequence, if possible, in one of three ways:
4527
  `ios_base::out` is nonzero, assigns `c` to `*``gptr()`. Returns: `c`.
4528
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
4529
  input sequence has a putback position available, assigns `gptr() - 1`
4530
  to `gptr()`. Returns: `traits::not_eof(c)`.
4531
 
4532
- *Returns:* `traits::eof()` to indicate failure.
4533
 
4534
  *Remarks:* If the function can succeed in more than one of these ways,
4535
  it is unspecified which way is chosen.
4536
 
4537
  ``` cpp
@@ -4550,56 +4836,55 @@ sequence, if possible, in one of two ways:
4550
  `traits::eof()`.
4551
 
4552
  *Remarks:* The function can alter the number of write positions
4553
  available as a result of any call.
4554
 
4555
- *Returns:* `traits::eof()` to indicate failure.
4556
 
4557
- The function can make a write position available only if
4558
- `(mode & ios_base::out) != 0`. To make a write position available, the
4559
- function reallocates (or initially allocates) an array object with a
4560
- sufficient number of elements to hold the current array object (if any),
4561
- plus at least one additional write position. If
4562
- `(mode & ios_base::in) != 0`, the function alters the read end pointer
4563
- `egptr()` to point just past the new write position.
4564
 
4565
  ``` cpp
4566
  pos_type seekoff(off_type off, ios_base::seekdir way,
4567
  ios_base::openmode which
4568
  = ios_base::in | ios_base::out) override;
4569
  ```
4570
 
4571
  *Effects:* Alters the stream position within one of the controlled
4572
- sequences, if possible, as indicated in
4573
- Table  [[tab:iostreams.seekoff.positioning]].
4574
 
4575
- **Table: `seekoff` positioning** <a id="tab:iostreams.seekoff.positioning">[tab:iostreams.seekoff.positioning]</a>
4576
 
4577
  | Conditions | Result |
4578
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
4579
- | `(which & ios_base::in)`` == ios_base::in` | positions the input sequence |
4580
- | `(which & ios_base::out)`` == ios_base::out` | positions the output sequence |
4581
- | `(which & (ios_base::in |`<br> `ios_base::out)) ==`<br> `(ios_base::in) |`<br> `ios_base::out))`<br> and `way ==` either<br> `ios_base::beg` or<br> `ios_base::end` | positions both the input and the output sequences |
4582
  | Otherwise | the positioning operation fails. |
4583
 
4584
 
4585
- For a sequence to be positioned, if its next pointer (either `gptr()` or
4586
- `pptr()`) is a null pointer and the new offset `newoff` is nonzero, the
4587
- positioning operation fails. Otherwise, the function determines `newoff`
4588
- as indicated in Table  [[tab:iostreams.newoff.values]].
4589
 
4590
- **Table: `newoff` values** <a id="tab:iostreams.newoff.values">[tab:iostreams.newoff.values]</a>
4591
 
4592
  | Condition | `newoff` Value |
4593
  | ---------------------- | ----------------------------------------------------------------------- |
4594
  | `way == ios_base::beg` | 0 |
4595
  | `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
4596
  | `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
4597
 
4598
 
4599
  If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
4600
- character ([[stringbuf.members]]), the positioning operation fails.
4601
  Otherwise, the function assigns `xbeg + newoff + off` to the next
4602
  pointer `xnext`.
4603
 
4604
  *Returns:* `pos_type(newoff)`, constructed from the resultant offset
4605
  `newoff` (of type `off_type`), that stores the resultant stream
@@ -4641,28 +4926,52 @@ namespace std {
4641
  using off_type = typename traits::off_type;
4642
  using traits_type = traits;
4643
  using allocator_type = Allocator;
4644
 
4645
  // [istringstream.cons], constructors
 
 
4646
  explicit basic_istringstream(
 
4647
  ios_base::openmode which = ios_base::in);
 
4648
  explicit basic_istringstream(
4649
- const basic_string<charT, traits, Allocator>& str,
4650
  ios_base::openmode which = ios_base::in);
4651
- basic_istringstream(const basic_istringstream& rhs) = delete;
 
 
 
 
 
 
 
 
 
 
 
 
4652
  basic_istringstream(basic_istringstream&& rhs);
4653
 
4654
  // [istringstream.assign], assign and swap
4655
- basic_istringstream& operator=(const basic_istringstream& rhs) = delete;
4656
  basic_istringstream& operator=(basic_istringstream&& rhs);
4657
  void swap(basic_istringstream& rhs);
4658
 
4659
  // [istringstream.members], members
4660
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
 
 
 
 
 
4661
 
4662
- basic_string<charT, traits, Allocator> str() const;
4663
  void str(const basic_string<charT, traits, Allocator>& s);
 
 
 
 
4664
  private:
4665
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
4666
  };
4667
 
4668
  template<class charT, class traits, class Allocator>
@@ -4677,87 +4986,157 @@ uses a `basic_stringbuf<charT, traits, Allocator>` object to control the
4677
  associated storage. For the sake of exposition, the maintained data is
4678
  presented here as:
4679
 
4680
  - `sb`, the `stringbuf` object.
4681
 
4682
- #### `basic_istringstream` constructors <a id="istringstream.cons">[[istringstream.cons]]</a>
4683
 
4684
  ``` cpp
4685
- explicit basic_istringstream(ios_base::openmode which = ios_base::in);
4686
  ```
4687
 
4688
- *Effects:* Constructs an object of class
4689
- `basic_istringstream<charT, traits>`, initializing the base class with
4690
- `basic_istream(&sb)` and initializing `sb` with
4691
- `basic_stringbuf<charT, traits, Allocator>(which | ios_base::in))` ([[stringbuf.cons]]).
4692
 
4693
  ``` cpp
4694
  explicit basic_istringstream(
4695
- const basic_string<charT, traits, Allocator>& str,
4696
  ios_base::openmode which = ios_base::in);
4697
  ```
4698
 
4699
- *Effects:* Constructs an object of class
4700
- `basic_istringstream<charT, traits>`, initializing the base class with
4701
- `basic_istream(&sb)` and initializing `sb` with
4702
- `basic_stringbuf<charT, traits, Allocator>(str, which | ios_base::in))` ([[stringbuf.cons]]).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4703
 
4704
  ``` cpp
4705
  basic_istringstream(basic_istringstream&& rhs);
4706
  ```
4707
 
4708
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
4709
  by move constructing the base class, and the contained
4710
- `basic_stringbuf`. Next `basic_istream<charT, traits>::set_rdbuf(&sb)`
4711
- is called to install the contained `basic_stringbuf`.
 
4712
 
4713
- #### Assign and swap <a id="istringstream.assign">[[istringstream.assign]]</a>
4714
-
4715
- ``` cpp
4716
- basic_istringstream& operator=(basic_istringstream&& rhs);
4717
- ```
4718
-
4719
- *Effects:* Move assigns the base and members of `*this` from the base
4720
- and corresponding members of `rhs`.
4721
-
4722
- *Returns:* `*this`.
4723
 
4724
  ``` cpp
4725
  void swap(basic_istringstream& rhs);
4726
  ```
4727
 
4728
- *Effects:* Exchanges the state of `*this` and `rhs` by calling
4729
- `basic_istream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
 
 
 
4730
 
4731
  ``` cpp
4732
  template<class charT, class traits, class Allocator>
4733
  void swap(basic_istringstream<charT, traits, Allocator>& x,
4734
  basic_istringstream<charT, traits, Allocator>& y);
4735
  ```
4736
 
4737
- *Effects:* As if by `x.swap(y)`.
4738
 
4739
  #### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
4740
 
4741
  ``` cpp
4742
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4743
  ```
4744
 
4745
  *Returns:*
4746
- `const_cast<basic_stringbuf<charT, traits, Allocator>*>(&sb)`.
4747
 
4748
  ``` cpp
4749
- basic_string<charT, traits, Allocator> str() const;
4750
  ```
4751
 
4752
- *Returns:* `rdbuf()->str()`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4753
 
4754
  ``` cpp
4755
  void str(const basic_string<charT, traits, Allocator>& s);
4756
  ```
4757
 
4758
- *Effects:* Calls `rdbuf()->str(s)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
4759
 
4760
  ### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
4761
 
4762
  ``` cpp
4763
  namespace std {
@@ -4771,28 +5150,53 @@ namespace std {
4771
  using off_type = typename traits::off_type;
4772
  using traits_type = traits;
4773
  using allocator_type = Allocator;
4774
 
4775
  // [ostringstream.cons], constructors
 
 
4776
  explicit basic_ostringstream(
 
4777
  ios_base::openmode which = ios_base::out);
 
4778
  explicit basic_ostringstream(
4779
- const basic_string<charT, traits, Allocator>& str,
4780
  ios_base::openmode which = ios_base::out);
4781
- basic_ostringstream(const basic_ostringstream& rhs) = delete;
 
 
 
 
 
 
 
 
 
 
 
 
4782
  basic_ostringstream(basic_ostringstream&& rhs);
4783
 
4784
  // [ostringstream.assign], assign and swap
4785
- basic_ostringstream& operator=(const basic_ostringstream& rhs) = delete;
4786
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
4787
  void swap(basic_ostringstream& rhs);
4788
 
4789
  // [ostringstream.members], members
4790
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4791
 
4792
- basic_string<charT, traits, Allocator> str() const;
 
 
 
 
 
4793
  void str(const basic_string<charT, traits, Allocator>& s);
 
 
 
 
4794
  private:
4795
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
4796
  };
4797
 
4798
  template<class charT, class traits, class Allocator>
@@ -4806,88 +5210,157 @@ writing objects of class `basic_string<{}charT, traits, Allocator>`. It
4806
  uses a `basic_stringbuf` object to control the associated storage. For
4807
  the sake of exposition, the maintained data is presented here as:
4808
 
4809
  - `sb`, the `stringbuf` object.
4810
 
4811
- #### `basic_ostringstream` constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
 
 
 
 
 
 
 
 
 
4812
 
4813
  ``` cpp
4814
  explicit basic_ostringstream(
 
4815
  ios_base::openmode which = ios_base::out);
4816
  ```
4817
 
4818
- *Effects:* Constructs an object of class `basic_ostringstream`,
4819
- initializing the base class with `basic_ostream(&sb)` and initializing
4820
- `sb` with
4821
- `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out))` ([[stringbuf.cons]]).
 
 
 
 
 
 
 
4822
 
4823
  ``` cpp
4824
  explicit basic_ostringstream(
4825
- const basic_string<charT, traits, Allocator>& str,
4826
  ios_base::openmode which = ios_base::out);
4827
  ```
4828
 
4829
- *Effects:* Constructs an object of class
4830
- `basic_ostringstream<charT, traits>`, initializing the base class with
4831
- `basic_ostream(&sb)` and initializing `sb` with
4832
- `basic_stringbuf<charT, traits, Allocator>(str, which | ios_base::out))` ([[stringbuf.cons]]).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4833
 
4834
  ``` cpp
4835
  basic_ostringstream(basic_ostringstream&& rhs);
4836
  ```
4837
 
4838
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
4839
  by move constructing the base class, and the contained
4840
- `basic_stringbuf`. Next `basic_ostream<charT, traits>::set_rdbuf(&sb)`
4841
- is called to install the contained `basic_stringbuf`.
 
4842
 
4843
- #### Assign and swap <a id="ostringstream.assign">[[ostringstream.assign]]</a>
4844
-
4845
- ``` cpp
4846
- basic_ostringstream& operator=(basic_ostringstream&& rhs);
4847
- ```
4848
-
4849
- *Effects:* Move assigns the base and members of `*this` from the base
4850
- and corresponding members of `rhs`.
4851
-
4852
- *Returns:* `*this`.
4853
 
4854
  ``` cpp
4855
  void swap(basic_ostringstream& rhs);
4856
  ```
4857
 
4858
- *Effects:* Exchanges the state of `*this` and `rhs` by calling
4859
- `basic_ostream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
 
 
 
4860
 
4861
  ``` cpp
4862
  template<class charT, class traits, class Allocator>
4863
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
4864
  basic_ostringstream<charT, traits, Allocator>& y);
4865
  ```
4866
 
4867
- *Effects:* As if by `x.swap(y)`.
4868
 
4869
  #### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
4870
 
4871
  ``` cpp
4872
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4873
  ```
4874
 
4875
  *Returns:*
4876
- `const_cast<basic_stringbuf<charT, traits, Allocator>*>(&sb)`.
4877
 
4878
  ``` cpp
4879
- basic_string<charT, traits, Allocator> str() const;
4880
  ```
4881
 
4882
- *Returns:* `rdbuf()->str()`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4883
 
4884
  ``` cpp
4885
  void str(const basic_string<charT, traits, Allocator>& s);
4886
  ```
4887
 
4888
- *Effects:* Calls `rdbuf()->str(s)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
4889
 
4890
  ### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
4891
 
4892
  ``` cpp
4893
  namespace std {
@@ -4901,27 +5374,52 @@ namespace std {
4901
  using off_type = typename traits::off_type;
4902
  using traits_type = traits;
4903
  using allocator_type = Allocator;
4904
 
4905
  // [stringstream.cons], constructors
 
 
4906
  explicit basic_stringstream(
 
4907
  ios_base::openmode which = ios_base::out | ios_base::in);
 
4908
  explicit basic_stringstream(
4909
- const basic_string<charT, traits, Allocator>& str,
4910
  ios_base::openmode which = ios_base::out | ios_base::in);
4911
- basic_stringstream(const basic_stringstream& rhs) = delete;
 
 
 
 
 
 
 
 
 
 
 
 
4912
  basic_stringstream(basic_stringstream&& rhs);
4913
 
4914
  // [stringstream.assign], assign and swap
4915
- basic_stringstream& operator=(const basic_stringstream& rhs) = delete;
4916
  basic_stringstream& operator=(basic_stringstream&& rhs);
4917
  void swap(basic_stringstream& rhs);
4918
 
4919
  // [stringstream.members], members
4920
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4921
- basic_string<charT, traits, Allocator> str() const;
4922
- void str(const basic_string<charT, traits, Allocator>& str);
 
 
 
 
 
 
 
 
 
4923
 
4924
  private:
4925
  basic_stringbuf<charT, traits> sb; // exposition only
4926
  };
4927
 
@@ -4938,87 +5436,160 @@ and writing from objects of class
4938
  associated sequence. For the sake of exposition, the maintained data is
4939
  presented here as
4940
 
4941
  - `sb`, the `stringbuf` object.
4942
 
4943
- #### `basic_stringstream` constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
 
 
 
 
 
 
 
 
4944
 
4945
  ``` cpp
4946
  explicit basic_stringstream(
 
4947
  ios_base::openmode which = ios_base::out | ios_base::in);
4948
  ```
4949
 
4950
- *Effects:* Constructs an object of class
4951
- `basic_stringstream<charT, traits>`, initializing the base class with
4952
- `basic_iostream(&sb)` and initializing `sb` with
4953
- `basic_stringbuf<charT, traits, Allocator>(which)`.
 
 
 
 
 
 
 
 
4954
 
4955
  ``` cpp
4956
  explicit basic_stringstream(
4957
- const basic_string<charT, traits, Allocator>& str,
4958
  ios_base::openmode which = ios_base::out | ios_base::in);
4959
  ```
4960
 
4961
- *Effects:* Constructs an object of class
4962
- `basic_stringstream<charT, traits>`, initializing the base class with
4963
- `basic_iostream(&sb)` and initializing `sb` with
4964
- `basic_stringbuf<charT, traits, Allocator>(str, which)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4965
 
4966
  ``` cpp
4967
  basic_stringstream(basic_stringstream&& rhs);
4968
  ```
4969
 
4970
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
4971
  by move constructing the base class, and the contained
4972
- `basic_stringbuf`. Next `basic_istream<charT, traits>::set_rdbuf(&sb)`
4973
- is called to install the contained `basic_stringbuf`.
 
4974
 
4975
- #### Assign and swap <a id="stringstream.assign">[[stringstream.assign]]</a>
4976
-
4977
- ``` cpp
4978
- basic_stringstream& operator=(basic_stringstream&& rhs);
4979
- ```
4980
-
4981
- *Effects:* Move assigns the base and members of `*this` from the base
4982
- and corresponding members of `rhs`.
4983
-
4984
- *Returns:* `*this`.
4985
 
4986
  ``` cpp
4987
  void swap(basic_stringstream& rhs);
4988
  ```
4989
 
4990
- *Effects:* Exchanges the state of `*this` and `rhs` by calling
4991
- `basic_iostream<charT,traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
 
 
 
4992
 
4993
  ``` cpp
4994
  template<class charT, class traits, class Allocator>
4995
  void swap(basic_stringstream<charT, traits, Allocator>& x,
4996
  basic_stringstream<charT, traits, Allocator>& y);
4997
  ```
4998
 
4999
- *Effects:* As if by `x.swap(y)`.
5000
 
5001
  #### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
5002
 
5003
  ``` cpp
5004
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5005
  ```
5006
 
5007
- *Returns:* `const_cast<basic_stringbuf<charT, traits, Allocator>*>(&sb)`
 
5008
 
5009
  ``` cpp
5010
- basic_string<charT, traits, Allocator> str() const;
5011
  ```
5012
 
5013
- *Returns:* `rdbuf()->str()`.
5014
 
5015
  ``` cpp
5016
- void str(const basic_string<charT, traits, Allocator>& str);
 
5017
  ```
5018
 
5019
- *Effects:* Calls `rdbuf()->str(str)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5020
 
5021
  ## File-based streams <a id="file.streams">[[file.streams]]</a>
5022
 
5023
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
5024
 
@@ -5054,13 +5625,13 @@ files.
5054
  or sink of bytes. In an environment that uses a large character set, the
5055
  file typically holds multibyte character sequences and the
5056
  `basic_filebuf` object converts those multibyte sequences into wide
5057
  character sequences. — *end note*]
5058
 
5059
- In this subclause, member functions taking arguments of
5060
  `const filesystem::path::value_type*` are only be provided on systems
5061
- where `filesystem::path::value_type` ([[fs.class.path]]) is not `char`.
5062
 
5063
  [*Note 2*: These functions enable class `path` support for systems with
5064
  a wide native path character type, such as `wchar_t`. — *end note*]
5065
 
5066
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
@@ -5076,16 +5647,16 @@ namespace std {
5076
  using off_type = typename traits::off_type;
5077
  using traits_type = traits;
5078
 
5079
  // [filebuf.cons], constructors/destructor
5080
  basic_filebuf();
5081
- basic_filebuf(const basic_filebuf& rhs) = delete;
5082
  basic_filebuf(basic_filebuf&& rhs);
5083
  virtual ~basic_filebuf();
5084
 
5085
  // [filebuf.assign], assign and swap
5086
- basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
5087
  basic_filebuf& operator=(basic_filebuf&& rhs);
5088
  void swap(basic_filebuf& rhs);
5089
 
5090
  // [filebuf.members], members
5091
  bool is_open() const;
@@ -5143,45 +5714,44 @@ An instance of `basic_filebuf` behaves as described in  [[filebuf]]
5143
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
5144
  the behavior is undefined.
5145
 
5146
  In order to support file I/O and multibyte/wide character conversion,
5147
  conversions are performed using members of a facet, referred to as
5148
- `a_codecvt` in following sections, obtained as if by
5149
 
5150
  ``` cpp
5151
  const codecvt<charT, char, typename traits::state_type>& a_codecvt =
5152
  use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());
5153
  ```
5154
 
5155
- #### `basic_filebuf` constructors <a id="filebuf.cons">[[filebuf.cons]]</a>
5156
 
5157
  ``` cpp
5158
  basic_filebuf();
5159
  ```
5160
 
5161
- *Effects:* Constructs an object of class `basic_filebuf<charT, traits>`,
5162
- initializing the base class with
5163
- `basic_streambuf<charT, traits>()` ([[streambuf.cons]]).
5164
 
5165
- *Postconditions:* `is_open() == false`.
5166
 
5167
  ``` cpp
5168
  basic_filebuf(basic_filebuf&& rhs);
5169
  ```
5170
 
5171
- *Effects:* Move constructs from the rvalue `rhs`. It is
5172
- *implementation-defined* whether the sequence pointers in `*this`
5173
- (`eback()`, `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) obtain
5174
- the values which `rhs` had. Whether they do or not, `*this` and `rhs`
5175
- reference separate buffers (if any at all) after the construction.
5176
- Additionally `*this` references the file which `rhs` did before the
5177
- construction, and `rhs` references no file after the construction. The
5178
- openmode, locale and any other state of `rhs` is also copied.
5179
 
5180
- *Postconditions:* Let `rhs_p` refer to the state of `rhs` just prior to
5181
- this construction and let `rhs_a` refer to the state of `rhs` just after
5182
- this construction.
5183
 
5184
  - `is_open() == rhs_p.is_open()`
5185
  - `rhs_a.is_open() == false`
5186
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
5187
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
@@ -5196,16 +5766,16 @@ this construction.
5196
 
5197
  ``` cpp
5198
  virtual ~basic_filebuf();
5199
  ```
5200
 
5201
- *Effects:* Destroys an object of class `basic_filebuf<charT, traits>`.
5202
- Calls `close()`. If an exception occurs during the destruction of the
5203
- object, including the call to `close()`, the exception is caught but not
5204
- rethrown (see  [[res.on.exception.handling]]).
5205
 
5206
- #### Assign and swap <a id="filebuf.assign">[[filebuf.assign]]</a>
5207
 
5208
  ``` cpp
5209
  basic_filebuf& operator=(basic_filebuf&& rhs);
5210
  ```
5211
 
@@ -5225,11 +5795,11 @@ void swap(basic_filebuf& rhs);
5225
  template<class charT, class traits>
5226
  void swap(basic_filebuf<charT, traits>& x,
5227
  basic_filebuf<charT, traits>& y);
5228
  ```
5229
 
5230
- *Effects:* As if by `x.swap(y)`.
5231
 
5232
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
5233
 
5234
  ``` cpp
5235
  bool is_open() const;
@@ -5242,19 +5812,20 @@ non-null value) and there has been no intervening call to close.
5242
  basic_filebuf* open(const char* s, ios_base::openmode mode);
5243
  basic_filebuf* open(const filesystem::path::value_type* s,
5244
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
5245
  ```
5246
 
 
 
5247
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
5248
- initializes the `filebuf` as required. It then opens a file, if
5249
- possible, whose name is the NTBS`s` (as if by calling
5250
- `fopen(s, modstr)`). The NTBS`modstr` is determined from
5251
- `mode & ~ios_base::ate` as indicated in
5252
- Table  [[tab:iostreams.file.open.modes]]. If `mode` is not some
5253
- combination of flags shown in the table then the open fails.
5254
 
5255
- **Table: File open modes** <a id="tab:iostreams.file.open.modes">[tab:iostreams.file.open.modes]</a>
5256
 
5257
  | `binary` | `in` | `out` | `trunc` | `app` | | `stdio` equivalent |
5258
  | -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
5259
  | | | + | | | `"w"` |
5260
  | | | + | | + | `"a"` |
@@ -5273,13 +5844,14 @@ combination of flags shown in the table then the open fails.
5273
  | + | + | + | + | | `"w+b"` |
5274
  | + | + | + | | + | `"a+b"` |
5275
  | + | + | | | + | `"a+b"` |
5276
 
5277
 
5278
- If the open operation succeeds and `(mode & ios_base::ate) != 0`,
5279
  positions the file to the end (as if by calling
5280
- `fseek(file, 0, SEEK_END)`).[^40]
 
5281
 
5282
  If the repositioning operation fails, calls `close()` and returns a null
5283
  pointer to indicate failure.
5284
 
5285
  *Returns:* `this` if successful, a null pointer otherwise.
@@ -5308,20 +5880,20 @@ or throws an exception, the function closes the file (as if by calling
5308
  these calls throws an exception, the exception is caught and rethrown
5309
  after closing the file.
5310
 
5311
  *Returns:* `this` on success, a null pointer otherwise.
5312
 
5313
- *Postconditions:* `is_open() == false`.
5314
 
5315
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
5316
 
5317
  ``` cpp
5318
  streamsize showmanyc() override;
5319
  ```
5320
 
5321
- *Effects:* Behaves the same as
5322
- `basic_streambuf::showmanyc()` ([[streambuf.virtuals]]).
5323
 
5324
  *Remarks:* An implementation might well provide an overriding definition
5325
  for this function signature if it can determine that more characters can
5326
  be read from the input sequence.
5327
 
@@ -5378,11 +5950,11 @@ sequence, if possible, in one of three ways:
5378
  either the input sequence has a putback position available or the
5379
  function makes a putback position available, decrements the next
5380
  pointer for the input sequence, `gptr()`. Returns:
5381
  `traits::not_eof(c)`.
5382
 
5383
- *Returns:* `traits::eof()` to indicate failure.
5384
 
5385
  *Remarks:* If `is_open() == false`, the function always fails.
5386
 
5387
  The function does not put back a character directly to the input
5388
  sequence.
@@ -5452,13 +6024,13 @@ and write any unshift sequence. Next, seek to the new position: if
5452
  operation was overflow or the put buffer is non-empty. “Write any
5453
  unshift sequence” means, if `width` if less than zero then call
5454
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
5455
  resulting unshift sequence. The function determines one of three values
5456
  for the argument `whence`, of type `int`, as indicated in
5457
- Table  [[tab:iostreams.seekoff.effects]].
5458
 
5459
- **Table: `seekoff` effects** <a id="tab:iostreams.seekoff.effects">[tab:iostreams.seekoff.effects]</a>
5460
 
5461
  | `way` Value | `stdio` Equivalent |
5462
  | ---------------- | ------------------ |
5463
  | `basic_ios::beg` | `SEEK_SET` |
5464
  | `basic_ios::cur` | `SEEK_CUR` |
@@ -5507,13 +6079,13 @@ characters to the file, then flushes the file as if by calling
5507
 
5508
  ``` cpp
5509
  void imbue(const locale& loc) override;
5510
  ```
5511
 
5512
- *Requires:* If the file is not positioned at its beginning and the
5513
  encoding of the current locale as determined by `a_codecvt.encoding()`
5514
- is state-dependent ([[locale.codecvt.virtuals]]) then that facet is the
5515
  same as the corresponding facet of `loc`.
5516
 
5517
  *Effects:* Causes characters inserted or extracted after this call to be
5518
  converted according to `loc` until another call of `imbue`.
5519
 
@@ -5542,15 +6114,15 @@ namespace std {
5542
  ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
5543
  explicit basic_ifstream(const string& s,
5544
  ios_base::openmode mode = ios_base::in);
5545
  explicit basic_ifstream(const filesystem::path& s,
5546
  ios_base::openmode mode = ios_base::in);
5547
- basic_ifstream(const basic_ifstream& rhs) = delete;
5548
  basic_ifstream(basic_ifstream&& rhs);
5549
 
5550
  // [ifstream.assign], assign and swap
5551
- basic_ifstream& operator=(const basic_ifstream& rhs) = delete;
5552
  basic_ifstream& operator=(basic_ifstream&& rhs);
5553
  void swap(basic_ifstream& rhs);
5554
 
5555
  // [ifstream.members], members
5556
  basic_filebuf<charT, traits>* rdbuf() const;
@@ -5577,62 +6149,52 @@ files. It uses a `basic_filebuf<{}charT, traits>` object to control the
5577
  associated sequence. For the sake of exposition, the maintained data is
5578
  presented here as:
5579
 
5580
  - `sb`, the `filebuf` object.
5581
 
5582
- #### `basic_ifstream` constructors <a id="ifstream.cons">[[ifstream.cons]]</a>
5583
 
5584
  ``` cpp
5585
  basic_ifstream();
5586
  ```
5587
 
5588
- *Effects:* Constructs an object of class
5589
- `basic_ifstream<charT, traits>`, initializing the base class with
5590
- `basic_istream(&sb)` and initializing `sb` with
5591
- `basic_filebuf<charT, traits>())` ([[istream.cons]], [[filebuf.cons]]).
5592
 
5593
  ``` cpp
5594
  explicit basic_ifstream(const char* s,
5595
  ios_base::openmode mode = ios_base::in);
5596
  explicit basic_ifstream(const filesystem::path::value_type* s,
5597
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
5598
  ```
5599
 
5600
- *Effects:* Constructs an object of class `basic_ifstream`, initializing
5601
- the base class with `basic_istream(&sb)` and initializing `sb` with
5602
- `basic_filebuf<charT, traits>())` ([[istream.cons]], [[filebuf.cons]]),
5603
- then calls `rdbuf()->open(s, mode | ios_base::in)`. If that function
5604
- returns a null pointer, calls `setstate(failbit)`.
5605
 
5606
  ``` cpp
5607
  explicit basic_ifstream(const string& s,
5608
  ios_base::openmode mode = ios_base::in);
5609
  explicit basic_ifstream(const filesystem::path& s,
5610
  ios_base::openmode mode = ios_base::in);
5611
  ```
5612
 
5613
- *Effects:* The same as `basic_ifstream(s.c_str(), mode)`.
5614
 
5615
  ``` cpp
5616
  basic_ifstream(basic_ifstream&& rhs);
5617
  ```
5618
 
5619
- *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5620
- by move constructing the base class, and the contained `basic_filebuf`.
5621
- Next `basic_istream<charT, traits>::set_rdbuf(&sb)` is called to install
5622
- the contained `basic_filebuf`.
5623
 
5624
- #### Assign and swap <a id="ifstream.assign">[[ifstream.assign]]</a>
5625
-
5626
- ``` cpp
5627
- basic_ifstream& operator=(basic_ifstream&& rhs);
5628
- ```
5629
-
5630
- *Effects:* Move assigns the base and members of `*this` from the base
5631
- and corresponding members of `rhs`.
5632
-
5633
- *Returns:* `*this`.
5634
 
5635
  ``` cpp
5636
  void swap(basic_ifstream& rhs);
5637
  ```
5638
 
@@ -5643,19 +6205,19 @@ void swap(basic_ifstream& rhs);
5643
  template<class charT, class traits>
5644
  void swap(basic_ifstream<charT, traits>& x,
5645
  basic_ifstream<charT, traits>& y);
5646
  ```
5647
 
5648
- *Effects:* As if by `x.swap(y)`.
5649
 
5650
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
5651
 
5652
  ``` cpp
5653
  basic_filebuf<charT, traits>* rdbuf() const;
5654
  ```
5655
 
5656
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(&sb)`.
5657
 
5658
  ``` cpp
5659
  bool is_open() const;
5660
  ```
5661
 
@@ -5667,12 +6229,12 @@ void open(const filesystem::path::value_type* s,
5667
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
5668
  ```
5669
 
5670
  *Effects:* Calls `rdbuf()->open(s, mode | ios_base::in)`. If that
5671
  function does not return a null pointer calls `clear()`, otherwise calls
5672
- `setstate(failbit)` (which may throw `ios_base::failure`)
5673
- ([[iostate.flags]]).
5674
 
5675
  ``` cpp
5676
  void open(const string& s, ios_base::openmode mode = ios_base::in);
5677
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
5678
  ```
@@ -5683,11 +6245,11 @@ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
5683
  void close();
5684
  ```
5685
 
5686
  *Effects:* Calls `rdbuf()->close()` and, if that function returns a null
5687
  pointer, calls `setstate(failbit)` (which may throw
5688
- `ios_base::failure`) ([[iostate.flags]]).
5689
 
5690
  ### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
5691
 
5692
  ``` cpp
5693
  namespace std {
@@ -5702,21 +6264,21 @@ namespace std {
5702
 
5703
  // [ofstream.cons], constructors
5704
  basic_ofstream();
5705
  explicit basic_ofstream(const char* s,
5706
  ios_base::openmode mode = ios_base::out);
5707
- explicit basic_ofstream(const filesystem::path::value_type* s,
5708
- ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
5709
  explicit basic_ofstream(const string& s,
5710
  ios_base::openmode mode = ios_base::out);
5711
  explicit basic_ofstream(const filesystem::path& s,
5712
  ios_base::openmode mode = ios_base::out);
5713
- basic_ofstream(const basic_ofstream& rhs) = delete;
5714
  basic_ofstream(basic_ofstream&& rhs);
5715
 
5716
  // [ofstream.assign], assign and swap
5717
- basic_ofstream& operator=(const basic_ofstream& rhs) = delete;
5718
  basic_ofstream& operator=(basic_ofstream&& rhs);
5719
  void swap(basic_ofstream& rhs);
5720
 
5721
  // [ofstream.members], members
5722
  basic_filebuf<charT, traits>* rdbuf() const;
@@ -5743,63 +6305,52 @@ files. It uses a `basic_filebuf<{}charT, traits>` object to control the
5743
  associated sequence. For the sake of exposition, the maintained data is
5744
  presented here as:
5745
 
5746
  - `sb`, the `filebuf` object.
5747
 
5748
- #### `basic_ofstream` constructors <a id="ofstream.cons">[[ofstream.cons]]</a>
5749
 
5750
  ``` cpp
5751
  basic_ofstream();
5752
  ```
5753
 
5754
- *Effects:* Constructs an object of class
5755
- `basic_ofstream<charT, traits>`, initializing the base class with
5756
- `basic_ostream(&sb)` and initializing `sb` with
5757
- `basic_filebuf<charT, traits>())` ([[ostream.cons]], [[filebuf.cons]]).
5758
 
5759
  ``` cpp
5760
  explicit basic_ofstream(const char* s,
5761
  ios_base::openmode mode = ios_base::out);
5762
  explicit basic_ofstream(const filesystem::path::value_type* s,
5763
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
5764
  ```
5765
 
5766
- *Effects:* Constructs an object of class
5767
- `basic_ofstream<charT, traits>`, initializing the base class with
5768
- `basic_ostream(&sb)` and initializing `sb` with
5769
- `basic_filebuf<charT, traits>())` ([[ostream.cons]], [[filebuf.cons]]),
5770
- then calls `rdbuf()->open(s, mode | ios_base::out)`. If that function
5771
- returns a null pointer, calls `setstate(failbit)`.
5772
 
5773
  ``` cpp
5774
  explicit basic_ofstream(const string& s,
5775
  ios_base::openmode mode = ios_base::out);
5776
  explicit basic_ofstream(const filesystem::path& s,
5777
  ios_base::openmode mode = ios_base::out);
5778
  ```
5779
 
5780
- *Effects:* The same as `basic_ofstream(s.c_str(), mode)`.
5781
 
5782
  ``` cpp
5783
  basic_ofstream(basic_ofstream&& rhs);
5784
  ```
5785
 
5786
- *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5787
- by move constructing the base class, and the contained `basic_filebuf`.
5788
- Next `basic_ostream<charT, traits>::set_rdbuf(&sb)` is called to install
5789
- the contained `basic_filebuf`.
5790
 
5791
- #### Assign and swap <a id="ofstream.assign">[[ofstream.assign]]</a>
5792
-
5793
- ``` cpp
5794
- basic_ofstream& operator=(basic_ofstream&& rhs);
5795
- ```
5796
-
5797
- *Effects:* Move assigns the base and members of `*this` from the base
5798
- and corresponding members of `rhs`.
5799
-
5800
- *Returns:* `*this`.
5801
 
5802
  ``` cpp
5803
  void swap(basic_ofstream& rhs);
5804
  ```
5805
 
@@ -5810,19 +6361,19 @@ void swap(basic_ofstream& rhs);
5810
  template<class charT, class traits>
5811
  void swap(basic_ofstream<charT, traits>& x,
5812
  basic_ofstream<charT, traits>& y);
5813
  ```
5814
 
5815
- *Effects:* As if by `x.swap(y)`.
5816
 
5817
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
5818
 
5819
  ``` cpp
5820
  basic_filebuf<charT, traits>* rdbuf() const;
5821
  ```
5822
 
5823
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(&sb)`.
5824
 
5825
  ``` cpp
5826
  bool is_open() const;
5827
  ```
5828
 
@@ -5834,20 +6385,20 @@ void open(const filesystem::path::value_type* s,
5834
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
5835
  ```
5836
 
5837
  *Effects:* Calls `rdbuf()->open(s, mode | ios_base::out)`. If that
5838
  function does not return a null pointer calls `clear()`, otherwise calls
5839
- `setstate(failbit)` (which may throw `ios_base::failure`)
5840
- ([[iostate.flags]]).
5841
 
5842
  ``` cpp
5843
  void close();
5844
  ```
5845
 
5846
  *Effects:* Calls `rdbuf()->close()` and, if that function fails (returns
5847
  a null pointer), calls `setstate(failbit)` (which may throw
5848
- `ios_base::failure`) ([[iostate.flags]]).
5849
 
5850
  ``` cpp
5851
  void open(const string& s, ios_base::openmode mode = ios_base::out);
5852
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
5853
  ```
@@ -5871,34 +6422,34 @@ namespace std {
5871
  basic_fstream();
5872
  explicit basic_fstream(
5873
  const char* s,
5874
  ios_base::openmode mode = ios_base::in | ios_base::out);
5875
  explicit basic_fstream(
5876
- const std::filesystem::path::value_type* s,
5877
  ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
5878
  explicit basic_fstream(
5879
  const string& s,
5880
  ios_base::openmode mode = ios_base::in | ios_base::out);
5881
  explicit basic_fstream(
5882
  const filesystem::path& s,
5883
  ios_base::openmode mode = ios_base::in | ios_base::out);
5884
- basic_fstream(const basic_fstream& rhs) = delete;
5885
  basic_fstream(basic_fstream&& rhs);
5886
 
5887
  // [fstream.assign], assign and swap
5888
- basic_fstream& operator=(const basic_fstream& rhs) = delete;
5889
  basic_fstream& operator=(basic_fstream&& rhs);
5890
  void swap(basic_fstream& rhs);
5891
 
5892
  // [fstream.members], members
5893
  basic_filebuf<charT, traits>* rdbuf() const;
5894
  bool is_open() const;
5895
  void open(
5896
  const char* s,
5897
  ios_base::openmode mode = ios_base::in | ios_base::out);
5898
  void open(
5899
- const std::filesystem::path::value_type* s,
5900
  ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
5901
  void open(
5902
  const string& s,
5903
  ios_base::openmode mode = ios_base::in | ios_base::out);
5904
  void open(
@@ -5921,18 +6472,18 @@ writing from named files. It uses a `basic_filebuf<charT, traits>`
5921
  object to control the associated sequences. For the sake of exposition,
5922
  the maintained data is presented here as:
5923
 
5924
  - `sb`, the `basic_filebuf` object.
5925
 
5926
- #### `basic_fstream` constructors <a id="fstream.cons">[[fstream.cons]]</a>
5927
 
5928
  ``` cpp
5929
  basic_fstream();
5930
  ```
5931
 
5932
- *Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
5933
- initializing the base class with `basic_iostream(&sb)` and initializing
5934
  `sb` with `basic_filebuf<charT, traits>()`.
5935
 
5936
  ``` cpp
5937
  explicit basic_fstream(
5938
  const char* s,
@@ -5940,12 +6491,12 @@ explicit basic_fstream(
5940
  explicit basic_fstream(
5941
  const filesystem::path::value_type* s,
5942
  ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
5943
  ```
5944
 
5945
- *Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
5946
- initializing the base class with `basic_iostream(&sb)` and initializing
5947
  `sb` with `basic_filebuf<charT, traits>()`. Then calls
5948
  `rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
5949
  `setstate(failbit)`.
5950
 
5951
  ``` cpp
@@ -5955,31 +6506,22 @@ explicit basic_fstream(
5955
  explicit basic_fstream(
5956
  const filesystem::path& s,
5957
  ios_base::openmode mode = ios_base::in | ios_base::out);
5958
  ```
5959
 
5960
- *Effects:* The same as `basic_fstream(s.c_str(), mode)`.
5961
 
5962
  ``` cpp
5963
  basic_fstream(basic_fstream&& rhs);
5964
  ```
5965
 
5966
- *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5967
- by move constructing the base class, and the contained `basic_filebuf`.
5968
- Next `basic_istream<charT, traits>::set_rdbuf(&sb)` is called to install
5969
- the contained `basic_filebuf`.
5970
 
5971
- #### Assign and swap <a id="fstream.assign">[[fstream.assign]]</a>
5972
-
5973
- ``` cpp
5974
- basic_fstream& operator=(basic_fstream&& rhs);
5975
- ```
5976
-
5977
- *Effects:* Move assigns the base and members of `*this` from the base
5978
- and corresponding members of `rhs`.
5979
-
5980
- *Returns:* `*this`.
5981
 
5982
  ``` cpp
5983
  void swap(basic_fstream& rhs);
5984
  ```
5985
 
@@ -5990,19 +6532,19 @@ void swap(basic_fstream& rhs);
5990
  template<class charT, class traits>
5991
  void swap(basic_fstream<charT, traits>& x,
5992
  basic_fstream<charT, traits>& y);
5993
  ```
5994
 
5995
- *Effects:* As if by `x.swap(y)`.
5996
 
5997
  #### Member functions <a id="fstream.members">[[fstream.members]]</a>
5998
 
5999
  ``` cpp
6000
  basic_filebuf<charT, traits>* rdbuf() const;
6001
  ```
6002
 
6003
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(&sb)`.
6004
 
6005
  ``` cpp
6006
  bool is_open() const;
6007
  ```
6008
 
@@ -6018,11 +6560,11 @@ void open(
6018
  ```
6019
 
6020
  *Effects:* Calls `rdbuf()->open(s, mode)`. If that function does not
6021
  return a null pointer calls `clear()`, otherwise calls
6022
  `setstate(failbit)` (which may throw
6023
- `ios_base::failure`) ([[iostate.flags]]).
6024
 
6025
  ``` cpp
6026
  void open(
6027
  const string& s,
6028
  ios_base::openmode mode = ios_base::in | ios_base::out);
@@ -6037,41 +6579,489 @@ void open(
6037
  void close();
6038
  ```
6039
 
6040
  *Effects:* Calls `rdbuf()->close()` and, if that function returns a null
6041
  pointer, calls `setstate(failbit)` (which may throw
6042
- `ios_base::failure`) ([[iostate.flags]]).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6043
 
6044
  ## File systems <a id="filesystems">[[filesystems]]</a>
6045
 
6046
  ### General <a id="fs.general">[[fs.general]]</a>
6047
 
6048
- This subclause describes operations on file systems and their
6049
- components, such as paths, regular files, and directories.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6050
 
6051
  ### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
6052
 
6053
  Conformance is specified in terms of behavior. Ideal behavior is not
6054
  always implementable, so the conformance subclauses take that into
6055
  account.
6056
 
6057
  #### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
6058
 
6059
- Some behavior is specified by reference to POSIX ([[fs.norm.ref]]). How
6060
  such behavior is actually implemented is unspecified.
6061
 
6062
  [*Note 1*: This constitutes an “as if” rule allowing implementations to
6063
  call native operating system or other APIs. — *end note*]
6064
 
6065
- Implementations are encouraged to provide such behavior as it is defined
6066
- by POSIX. Implementations shall document any behavior that differs from
6067
- the behavior defined by POSIX. Implementations that do not support exact
6068
- POSIX behavior are encouraged to provide behavior as close to POSIX
6069
- behavior as is reasonable given the limitations of actual operating
6070
- systems and file systems. If an implementation cannot provide any
6071
- reasonable behavior, the implementation shall report an error as
6072
- specified in  [[fs.err.report]].
6073
 
6074
  [*Note 2*: This allows users to rely on an exception being thrown or an
6075
  error code being set when an implementation cannot provide any
6076
  reasonable behavior. — *end note*]
6077
 
@@ -6084,225 +7074,88 @@ other features of more capable file systems, so implementations are not
6084
  required to support those features on the FAT file system but instead
6085
  are required to report an error as described above. — *end example*]
6086
 
6087
  #### Operating system dependent behavior conformance <a id="fs.conform.os">[[fs.conform.os]]</a>
6088
 
6089
- Some behavior is specified as being operating system dependent (
6090
- [[fs.def.osdep]]). The operating system an implementation is dependent
6091
- upon is *implementation-defined*.
 
6092
 
6093
  It is permissible for an implementation to be dependent upon an
6094
  operating system emulator rather than the actual underlying operating
6095
  system.
6096
 
6097
  #### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
6098
 
6099
- Behavior is undefined if calls to functions provided by this subclause
6100
- introduce a file system race ([[fs.def.race]]).
 
 
 
6101
 
6102
  If the possibility of a file system race would make it unreliable for a
6103
  program to test for a precondition before calling a function described
6104
- herein, *Requires:* is not specified for the function.
6105
 
6106
  [*Note 1*: As a design practice, preconditions are not specified when
6107
  it is unreasonable for a program to detect them prior to calling the
6108
  function. — *end note*]
6109
 
6110
  ### Normative references <a id="fs.norm.ref">[[fs.norm.ref]]</a>
6111
 
6112
- This subclause mentions commercially available operating systems for
6113
- purposes of exposition.[^41]
6114
-
6115
- ### Terms and definitions <a id="fs.definitions">[[fs.definitions]]</a>
6116
-
6117
- A path that unambiguously identifies the location of a file without
6118
- reference to an additional starting location. The elements of a path
6119
- that determine if it is absolute are operating system dependent.
6120
-
6121
- A file within a file system that acts as a container of directory
6122
- entries that contain information about other files, possibly including
6123
- other directory files.
6124
-
6125
- An object within a file system that holds user or system data. Files can
6126
- be written to, or read from, or both. A file has certain attributes,
6127
- including type. File types include regular files and directories. Other
6128
- types of files, such as symbolic links ([[fs.def.symlink]]), may be
6129
- supported by the implementation.
6130
-
6131
- A collection of files and their attributes.
6132
-
6133
- The condition that occurs when multiple threads, processes, or computers
6134
- interleave access and modification of the same object within a file
6135
- system.
6136
-
6137
- The name of a file. Filenames *dot* and *dot-dot*, consisting solely of
6138
- one and two period characters respectively, have special meaning. The
6139
- following characteristics of filenames are operating system dependent:
6140
-
6141
- - The permitted characters. \[*Example 1*: Some operating systems
6142
- prohibit the ASCII control characters (0x00 – 0x1F) in
6143
- filenames. — *end example*]
6144
- - The maximum permitted length.
6145
- - Filenames that are not permitted.
6146
- - Filenames that have special meaning.
6147
- - Case awareness and sensitivity during path resolution.
6148
- - Special rules that may apply to file types other than regular files,
6149
- such as directories.
6150
-
6151
- A link ([[fs.def.link]]) to an existing file. Some file systems support
6152
- multiple hard links to a file. If the last hard link to a file is
6153
- removed, the file itself is removed.
6154
-
6155
- [*Note 1*: A hard link can be thought of as a shared-ownership smart
6156
- pointer to a file. — *end note*]
6157
-
6158
- An object that associates a filename with a file. Several links can
6159
- associate names with the same file.
6160
-
6161
- For narrow character strings, the operating system dependent current
6162
- encoding for pathnames ([[fs.def.pathname]]). For wide character
6163
- strings, the implementation-defined execution wide-character set
6164
- encoding ([[lex.charset]]).
6165
-
6166
- The operating system dependent pathname format accepted by the host
6167
- operating system.
6168
-
6169
- A path in normal form is said to be *normalized*. The process of
6170
- obtaining a normalized path from a path that is not in normal form is
6171
- called *normalization*.
6172
-
6173
- Normalization of a generic format pathname means:
6174
-
6175
- 1. If the path is empty, stop.
6176
- 2. Replace each slash character in the *root-name* with a
6177
- *preferred-separator*.
6178
- 3. Replace each *directory-separator* with a *preferred-separator*.
6179
- \[*Note 2*: The generic pathname grammar ([[fs.path.generic]])
6180
- defines *directory-separator* as one or more slashes and
6181
- *preferred-separator*s. — *end note*]
6182
- 4. Remove each *dot* filename and any immediately following
6183
- *directory-separator*.
6184
- 5. As long as any appear, remove a non-*dot-dot* filename immediately
6185
- followed by a *directory-separator* and a *dot-dot* filename, along
6186
- with any immediately following *directory-separator*.
6187
- 6. If there is a *root-directory*, remove all *dot-dot* filenames and
6188
- any *directory-separator*s immediately following them.
6189
- \[*Note 3*: These *dot-dot* filenames attempt to refer to
6190
- nonexistent parent directories. — *end note*]
6191
- 7. If the last filename is *dot-dot*, remove any trailing
6192
- *directory-separator*.
6193
- 8. If the path is empty, add a *dot*.
6194
-
6195
- Behavior that is dependent upon the behavior and characteristics of an
6196
- operating system. See  [[fs.conform.os]].
6197
-
6198
- the directory that both contains a directory entry for the given
6199
- directory and is represented by the filename *dot-dot* in the given
6200
- directory.
6201
-
6202
- a directory containing a directory entry for the file under discussion.
6203
-
6204
- A sequence of elements that identify the location of a file within a
6205
- filesystem. The elements are the *root-name*ₒₚₜ , *root-directory*ₒₚₜ ,
6206
- and an optional sequence of filenames. The maximum number of elements in
6207
- the sequence is operating system dependent.
6208
-
6209
- A character string that represents the name of a path. Pathnames are
6210
- formatted according to the generic pathname format grammar (
6211
- [[fs.path.generic]]) or an operating system dependent native pathname
6212
- format.
6213
-
6214
- Pathname resolution is the operating system dependent mechanism for
6215
- resolving a pathname to a particular file in a file hierarchy. There may
6216
- be multiple pathnames that resolve to the same file.
6217
-
6218
- [*Example 2*: POSIX specifies the mechanism in section 4.11, Pathname
6219
- resolution. — *end example*]
6220
-
6221
- A path that is not absolute, and as such, only unambiguously identifies
6222
- the location of a file when resolved ([[fs.def.pathres]]) relative to
6223
- an implied starting location. The elements of a path that determine if
6224
- it is relative are operating system dependent.
6225
-
6226
- [*Note 4*: Pathnames “.” and “..” are relative paths. — *end note*]
6227
-
6228
- A type of file with the property that when the file is encountered
6229
- during pathname resolution, a string stored by the file is used to
6230
- modify the pathname resolution.
6231
-
6232
- [*Note 5*: Symbolic links are often called symlinks. A symbolic link
6233
- can be thought of as a raw pointer to a file. If the file pointed to
6234
- does not exist, the symbolic link is said to be a “dangling” symbolic
6235
- link. — *end note*]
6236
 
6237
  ### Requirements <a id="fs.req">[[fs.req]]</a>
6238
 
6239
- Throughout this subclause, `char`, `wchar_t`, `char16_t`, and `char32_t`
6240
- are collectively called *encoded character types*.
 
6241
 
6242
  Functions with template parameters named `EcharT` shall not participate
6243
  in overload resolution unless `EcharT` is one of the encoded character
6244
  types.
6245
 
6246
- Template parameters named `InputIterator` shall meet the input iterator
6247
- requirements ([[input.iterators]]) and shall have a value type that is
6248
- one of the encoded character types.
6249
 
6250
  [*Note 1*: Use of an encoded character type implies an associated
6251
  character set and encoding. Since `signed char` and `unsigned char` have
6252
  no implied character set and encoding, they are not included as
6253
  permitted types. — *end note*]
6254
 
6255
- Template parameters named `Allocator` shall meet the Allocator
6256
- requirements ([[allocator.requirements]]).
6257
 
6258
  #### Namespaces and headers <a id="fs.req.namespace">[[fs.req.namespace]]</a>
6259
 
6260
- Unless otherwise specified, references to entities described in this
6261
- subclause are assumed to be qualified with `::std::filesystem::`.
 
6262
 
6263
  ### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
6264
 
6265
  ``` cpp
 
 
6266
  namespace std::filesystem {
6267
  // [fs.class.path], paths
6268
  class path;
6269
 
6270
  // [fs.path.nonmember], path non-member functions
6271
  void swap(path& lhs, path& rhs) noexcept;
6272
  size_t hash_value(const path& p) noexcept;
6273
 
6274
- bool operator==(const path& lhs, const path& rhs) noexcept;
6275
- bool operator!=(const path& lhs, const path& rhs) noexcept;
6276
- bool operator< (const path& lhs, const path& rhs) noexcept;
6277
- bool operator<=(const path& lhs, const path& rhs) noexcept;
6278
- bool operator> (const path& lhs, const path& rhs) noexcept;
6279
- bool operator>=(const path& lhs, const path& rhs) noexcept;
6280
-
6281
- path operator/ (const path& lhs, const path& rhs);
6282
-
6283
- // [fs.path.io], path inserter and extractor
6284
- template <class charT, class traits>
6285
- basic_ostream<charT, traits>&
6286
- operator<<(basic_ostream<charT, traits>& os, const path& p);
6287
- template <class charT, class traits>
6288
- basic_istream<charT, traits>&
6289
- operator>>(basic_istream<charT, traits>& is, path& p);
6290
-
6291
- // [fs.path.factory], path factory functions
6292
- template <class Source>
6293
- path u8path(const Source& source);
6294
- template <class InputIterator>
6295
- path u8path(InputIterator first, InputIterator last);
6296
-
6297
- // [fs.class.filesystem_error], filesystem errors
6298
  class filesystem_error;
6299
 
6300
- // [fs.class.directory_entry], directory entries
6301
  class directory_entry;
6302
 
6303
- // [fs.class.directory_iterator], directory iterators
6304
  class directory_iterator;
6305
 
6306
  // [fs.dir.itr.nonmembers], range access for directory iterators
6307
  directory_iterator begin(directory_iterator iter) noexcept;
6308
  directory_iterator end(const directory_iterator&) noexcept;
@@ -6312,53 +7165,55 @@ namespace std::filesystem {
6312
 
6313
  // [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
6314
  recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
6315
  recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
6316
 
6317
- // [fs.class.file_status], file status
6318
  class file_status;
6319
 
6320
  struct space_info {
6321
  uintmax_t capacity;
6322
  uintmax_t free;
6323
  uintmax_t available;
 
 
6324
  };
6325
 
6326
  // [fs.enum], enumerations
6327
  enum class file_type;
6328
  enum class perms;
6329
  enum class perm_options;
6330
  enum class copy_options;
6331
  enum class directory_options;
6332
 
6333
- using file_time_type = chrono::time_point<trivial-clock>;
6334
 
6335
  // [fs.op.funcs], filesystem operations
6336
- path absolute(const path& p, const path& base = current_path());
 
6337
 
6338
- path canonical(const path& p, const path& base = current_path());
6339
  path canonical(const path& p, error_code& ec);
6340
- path canonical(const path& p, const path& base, error_code& ec);
6341
 
6342
  void copy(const path& from, const path& to);
6343
- void copy(const path& from, const path& to, error_code& ec) noexcept;
6344
  void copy(const path& from, const path& to, copy_options options);
6345
  void copy(const path& from, const path& to, copy_options options,
6346
- error_code& ec) noexcept;
6347
 
6348
  bool copy_file(const path& from, const path& to);
6349
- bool copy_file(const path& from, const path& to, error_code& ec) noexcept;
6350
  bool copy_file(const path& from, const path& to, copy_options option);
6351
  bool copy_file(const path& from, const path& to, copy_options option,
6352
- error_code& ec) noexcept;
6353
 
6354
  void copy_symlink(const path& existing_symlink, const path& new_symlink);
6355
  void copy_symlink(const path& existing_symlink, const path& new_symlink,
6356
  error_code& ec) noexcept;
6357
 
6358
  bool create_directories(const path& p);
6359
- bool create_directories(const path& p, error_code& ec) noexcept;
6360
 
6361
  bool create_directory(const path& p);
6362
  bool create_directory(const path& p, error_code& ec) noexcept;
6363
 
6364
  bool create_directory(const path& p, const path& attributes);
@@ -6380,17 +7235,17 @@ namespace std::filesystem {
6380
  path current_path();
6381
  path current_path(error_code& ec);
6382
  void current_path(const path& p);
6383
  void current_path(const path& p, error_code& ec) noexcept;
6384
 
 
 
 
6385
  bool exists(file_status s) noexcept;
6386
  bool exists(const path& p);
6387
  bool exists(const path& p, error_code& ec) noexcept;
6388
 
6389
- bool equivalent(const path& p1, const path& p2);
6390
- bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
6391
-
6392
  uintmax_t file_size(const path& p);
6393
  uintmax_t file_size(const path& p, error_code& ec) noexcept;
6394
 
6395
  uintmax_t hard_link_count(const path& p);
6396
  uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
@@ -6406,11 +7261,11 @@ namespace std::filesystem {
6406
  bool is_directory(file_status s) noexcept;
6407
  bool is_directory(const path& p);
6408
  bool is_directory(const path& p, error_code& ec) noexcept;
6409
 
6410
  bool is_empty(const path& p);
6411
- bool is_empty(const path& p, error_code& ec) noexcept;
6412
 
6413
  bool is_fifo(file_status s) noexcept;
6414
  bool is_fifo(const path& p);
6415
  bool is_fifo(const path& p, error_code& ec) noexcept;
6416
 
@@ -6453,11 +7308,11 @@ namespace std::filesystem {
6453
 
6454
  bool remove(const path& p);
6455
  bool remove(const path& p, error_code& ec) noexcept;
6456
 
6457
  uintmax_t remove_all(const path& p);
6458
- uintmax_t remove_all(const path& p, error_code& ec) noexcept;
6459
 
6460
  void rename(const path& from, const path& to);
6461
  void rename(const path& from, const path& to, error_code& ec) noexcept;
6462
 
6463
  void resize_file(const path& p, uintmax_t size);
@@ -6480,15 +7335,13 @@ namespace std::filesystem {
6480
  path weakly_canonical(const path& p);
6481
  path weakly_canonical(const path& p, error_code& ec);
6482
  }
6483
  ```
6484
 
6485
- `trivial-clock` is an *implementation-defined* type that satisfies the
6486
- `TrivialClock` requirements ([[time.clock.req]]) and that is capable of
6487
- representing and measuring file time values. Implementations should
6488
- ensure that the resolution and range of `file_time_type` reflect the
6489
- operating system dependent resolution and range of file time values.
6490
 
6491
  ### Error reporting <a id="fs.err.report">[[fs.err.report]]</a>
6492
 
6493
  Filesystem library functions often provide two overloads, one that
6494
  throws an exception to report file system errors, and another that sets
@@ -6534,22 +7387,49 @@ follows, unless otherwise specified:
6534
  appropriate for the specific operating system dependent error.
6535
  Otherwise, `clear()` is called on the `error_code&` argument.
6536
 
6537
  ### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
6538
 
6539
- An object of class `path` represents a path ([[fs.def.path]]) and
6540
- contains a pathname ([[fs.def.pathname]]). Such an object is concerned
6541
- only with the lexical and syntactic aspects of a path. The path does not
6542
- necessarily exist in external storage, and the pathname is not
6543
- necessarily valid for the current operating system or for a particular
6544
- file system.
6545
 
6546
  [*Note 1*: Class `path` is used to support the differences between the
6547
  string types used by different operating systems to represent pathnames,
6548
  and to perform conversions between encodings when
6549
  necessary. — *end note*]
6550
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6551
  ``` cpp
6552
  namespace std::filesystem {
6553
  class path {
6554
  public:
6555
  using value_type = see below;
@@ -6580,11 +7460,11 @@ namespace std::filesystem {
6580
  path& operator=(string_type&& source);
6581
  path& assign(string_type&& source);
6582
  template<class Source>
6583
  path& operator=(const Source& source);
6584
  template<class Source>
6585
- path& assign(const Source& source)
6586
  template<class InputIterator>
6587
  path& assign(InputIterator first, InputIterator last);
6588
 
6589
  // [fs.path.append], appends
6590
  path& operator/=(const path& p);
@@ -6616,10 +7496,16 @@ namespace std::filesystem {
6616
  path& remove_filename();
6617
  path& replace_filename(const path& replacement);
6618
  path& replace_extension(const path& replacement = path());
6619
  void swap(path& rhs) noexcept;
6620
 
 
 
 
 
 
 
6621
  // [fs.path.native.obs], native format observers
6622
  const string_type& native() const noexcept;
6623
  const value_type* c_str() const noexcept;
6624
  operator string_type() const;
6625
 
@@ -6627,22 +7513,22 @@ namespace std::filesystem {
6627
  class Allocator = allocator<EcharT>>
6628
  basic_string<EcharT, traits, Allocator>
6629
  string(const Allocator& a = Allocator()) const;
6630
  std::string string() const;
6631
  std::wstring wstring() const;
6632
- std::string u8string() const;
6633
  std::u16string u16string() const;
6634
  std::u32string u32string() const;
6635
 
6636
  // [fs.path.generic.obs], generic format observers
6637
  template<class EcharT, class traits = char_traits<EcharT>,
6638
  class Allocator = allocator<EcharT>>
6639
  basic_string<EcharT, traits, Allocator>
6640
  generic_string(const Allocator& a = Allocator()) const;
6641
  std::string generic_string() const;
6642
  std::wstring generic_wstring() const;
6643
- std::string generic_u8string() const;
6644
  std::u16string generic_u16string() const;
6645
  std::u32string generic_u32string() const;
6646
 
6647
  // [fs.path.compare], compare
6648
  int compare(const path& p) const noexcept;
@@ -6659,11 +7545,11 @@ namespace std::filesystem {
6659
  path filename() const;
6660
  path stem() const;
6661
  path extension() const;
6662
 
6663
  // [fs.path.query], query
6664
- bool empty() const noexcept;
6665
  bool has_root_name() const;
6666
  bool has_root_directory() const;
6667
  bool has_root_path() const;
6668
  bool has_relative_path() const;
6669
  bool has_parent_path() const;
@@ -6682,21 +7568,29 @@ namespace std::filesystem {
6682
  class iterator;
6683
  using const_iterator = iterator;
6684
 
6685
  iterator begin() const;
6686
  iterator end() const;
 
 
 
 
 
 
 
 
6687
  };
6688
  }
6689
  ```
6690
 
6691
  `value_type` is a `typedef` for the operating system dependent encoded
6692
  character type used to represent pathnames.
6693
 
6694
  The value of the `preferred_separator` member is the operating system
6695
- dependent *preferred-separator* character ([[fs.path.generic]]).
6696
 
6697
- [*Example 1*: For POSIX-based operating systems, `value_type` is `char`
6698
  and `preferred_separator` is the slash character (`'/'`). For
6699
  Windows-based operating systems, `value_type` is `wchar_t` and
6700
  `preferred_separator` is the backslash character
6701
  (`L'\\'`). — *end example*]
6702
 
@@ -6744,31 +7638,42 @@ preferred-separator:
6744
  ``` bnf
6745
  fallback-separator:
6746
  /, if *preferred-separator* is not /
6747
  ```
6748
 
6749
- [*Note 1*: Operating systems often place restrictions on the characters
6750
- that may be used in a *filename*. For wide portability, users may wish
6751
- to limit *filename* characters to the POSIX Portable Filename Character
6752
- Set:
 
 
 
 
 
 
6753
  `A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
6754
  `a b c d e f g h i j k l m n o p q r s t u v w x y z`
6755
  `0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
 
 
 
 
 
 
6756
 
6757
  Except in a *root-name*, multiple successive *directory-separator*
6758
  characters are considered to be the same as one *directory-separator*
6759
  character.
6760
 
6761
- The filename *dot* ([[fs.def.filename]]) is treated as a reference to
6762
- the current directory. The filename *dot-dot* ([[fs.def.filename]]) is
6763
- treated as a reference to the parent directory. What the filename
6764
- *dot-dot* refers to relative to *root-directory* is
6765
  *implementation-defined*. Specific filenames may have special meanings
6766
  for a particular operating system.
6767
 
6768
- A *root-name* identifies the starting location for pathname resolution (
6769
- [[fs.def.pathres]]). If there are no operating system dependent
6770
  *root-name*s, at least one *implementation-defined* *root-name* is
6771
  required.
6772
 
6773
  [*Note 2*: Many operating systems define a name beginning with two
6774
  *directory-separator* characters as a *root-name* that identifies
@@ -6781,17 +7686,42 @@ longest sequence of characters is chosen.
6781
 
6782
  [*Note 3*: On a POSIX-like operating system, it is impossible to have a
6783
  *root-name* and a *relative-path* without an intervening
6784
  *root-directory* element. — *end note*]
6785
 
6786
- #### `path` conversions <a id="fs.path.cvt">[[fs.path.cvt]]</a>
6787
 
6788
- ##### `path` argument format conversions <a id="fs.path.fmt.cvt">[[fs.path.fmt.cvt]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6789
 
6790
  [*Note 1*:
6791
 
6792
- The format conversions described in this section are not applied on
6793
  POSIX-based operating systems because on these systems:
6794
 
6795
  - The generic format is acceptable as a native path.
6796
  - There is no need to distinguish between native format and generic
6797
  format in function arguments.
@@ -6800,15 +7730,15 @@ POSIX-based operating systems because on these systems:
6800
 
6801
  — *end note*]
6802
 
6803
  Several functions are defined to accept *detected-format* arguments,
6804
  which are character sequences. A detected-format argument represents a
6805
- path using either a pathname in the generic format (
6806
- [[fs.path.generic]]) or a pathname in the native format (
6807
- [[fs.def.native]]). Such an argument is taken to be in the generic
6808
- format if and only if it matches the generic format and is not
6809
- acceptable to the operating system as a native path.
6810
 
6811
  [*Note 2*: Some operating systems may have no unambiguous way to
6812
  distinguish between native format and generic format arguments. This is
6813
  by design as it simplifies use for operating systems that do not require
6814
  disambiguation. An implementation for an operating system where
@@ -6827,12 +7757,12 @@ native-to-generic and generic-to-native formats respectively. If
6827
  If the native format requires paths for regular files to be formatted
6828
  differently from paths for directories, the path shall be treated as a
6829
  directory path if its last element is a *directory-separator*, otherwise
6830
  it shall be treated as a path to a regular file.
6831
 
6832
- [*Note 4*: A path stores a native format pathname (
6833
- [[fs.path.native.obs]]) and acts as if it also stores a generic format
6834
  pathname, related as given below. The implementation may generate the
6835
  generic format pathname based on the native format pathname (and
6836
  possibly other information) when requested. — *end note*]
6837
 
6838
  When a path is constructed from or is assigned a single representation
@@ -6845,95 +7775,101 @@ the other representation. The value *q* converts to *p* (by *G* or *N*
6845
  as appropriate) if any such value does so; *q* is otherwise unspecified.
6846
 
6847
  [*Note 5*: If *q* is the result of converting any path at all, it is
6848
  the result of converting *p*. — *end note*]
6849
 
6850
- ##### `path` type and encoding conversions <a id="fs.path.type.cvt">[[fs.path.type.cvt]]</a>
 
 
 
 
 
 
6851
 
6852
  For member function arguments that take character sequences representing
6853
  paths and for member functions returning strings, value type and
6854
  encoding conversion is performed if the value type of the argument or
6855
  return value differs from `path::value_type`. For the argument or return
6856
  value, the method of conversion and the encoding to be converted to is
6857
  determined by its value type:
6858
 
6859
- - `char`: The encoding is the native narrow encoding (
6860
- [[fs.def.native.encode]]). The method of conversion, if any, is
6861
- operating system dependent. \[*Note 6*: For POSIX-based operating
6862
- systems `path::value_type` is `char` so no conversion from `char`
6863
- value type arguments or to `char` value type return values is
6864
- performed. For Windows-based operating systems, the native narrow
6865
- encoding is determined by calling a Windows API
6866
  function. — *end note*] \[*Note 7*: This results in behavior
6867
  identical to other C and C++ standard library functions that perform
6868
- file operations using narrow character strings to identify paths.
6869
  Changing this behavior would be surprising and error
6870
  prone. — *end note*]
6871
- - `wchar_t`: The encoding is the native wide encoding (
6872
- [[fs.def.native.encode]]). The method of conversion is unspecified.
6873
- \[*Note 8*: For Windows-based operating systems `path::value_type` is
6874
- `wchar_t` so no conversion from `wchar_t` value type arguments or to
6875
- `wchar_t` value type return values is performed. — *end note*]
 
 
6876
  - `char16_t`: The encoding is UTF-16. The method of conversion is
6877
  unspecified.
6878
  - `char32_t`: The encoding is UTF-32. The method of conversion is
6879
  unspecified.
6880
 
6881
  If the encoding being converted to has no representation for source
6882
  characters, the resulting converted characters, if any, are unspecified.
6883
  Implementations should not modify member function arguments if already
6884
  of type `path::value_type`.
6885
 
6886
- #### `path` requirements <a id="fs.path.req">[[fs.path.req]]</a>
6887
 
6888
- In addition to the requirements ([[fs.req]]), function template
6889
- parameters named `Source` shall be one of:
6890
 
6891
  - `basic_string<EcharT, traits, Allocator>`. A function argument
6892
  `const Source&` `source` shall have an effective range
6893
  \[`source.begin()`, `source.end()`).
6894
  - `basic_string_view<EcharT, traits>`. A function argument
6895
  `const Source&` `source` shall have an effective range
6896
  \[`source.begin()`, `source.end()`).
6897
- - A type meeting the input iterator requirements that iterates over a
6898
- NTCTS. The value type shall be an encoded character type. A function
6899
- argument `const Source&` `source` shall have an effective range
6900
- \[`source`, `end`) where `end` is the first iterator value with an
6901
- element value equal to `iterator_traits<Source>::value_type()`.
6902
  - A character array that after array-to-pointer decay results in a
6903
  pointer to the start of a NTCTS. The value type shall be an encoded
6904
  character type. A function argument `const Source&` `source` shall
6905
  have an effective range \[`source`, `end`) where `end` is the first
6906
  iterator value with an element value equal to
6907
  `iterator_traits<decay_t<Source>>::value_type()`.
6908
 
6909
  Functions taking template parameters named `Source` shall not
6910
- participate in overload resolution unless either
 
6911
 
6912
  - `Source` is a specialization of `basic_string` or `basic_string_view`,
6913
  or
6914
  - the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
6915
- valid and denotes a possibly `const` encoded character type (
6916
- [[temp.deduct]]).
6917
 
6918
- [*Note 1*: See path conversions ([[fs.path.cvt]]) for how the value
6919
- types above and their encodings convert to `path::value_type` and its
6920
  encoding. — *end note*]
6921
 
6922
  Arguments of type `Source` shall not be null pointers.
6923
 
6924
- #### `path` members <a id="fs.path.member">[[fs.path.member]]</a>
6925
 
6926
- ##### `path` constructors <a id="fs.path.construct">[[fs.path.construct]]</a>
6927
 
6928
  ``` cpp
6929
  path() noexcept;
6930
  ```
6931
 
6932
- *Effects:* Constructs an object of class `path`.
6933
-
6934
- *Postconditions:* `empty() == true`.
6935
 
6936
  ``` cpp
6937
  path(const path& p);
6938
  path(path&& p) noexcept;
6939
  ```
@@ -6946,49 +7882,48 @@ state.
6946
  ``` cpp
6947
  path(string_type&& source, format fmt = auto_format);
6948
  ```
6949
 
6950
  *Effects:* Constructs an object of class `path` for which the pathname
6951
- in the detected-format of `source` has the original value of
6952
- `source` ([[fs.path.fmt.cvt]]), converting format if
6953
- required ([[fs.path.fmt.cvt]]). `source` is left in a valid but
6954
- unspecified state.
6955
 
6956
  ``` cpp
6957
  template<class Source>
6958
  path(const Source& source, format fmt = auto_format);
6959
  template<class InputIterator>
6960
  path(InputIterator first, InputIterator last, format fmt = auto_format);
6961
  ```
6962
 
6963
- *Effects:* Let `s` be the effective range of `source` ([[fs.path.req]])
6964
- or the range \[`first`, `last`), with the encoding converted if
6965
- required ([[fs.path.cvt]]). Finds the detected-format of
6966
- `s` ([[fs.path.fmt.cvt]]) and constructs an object of class `path` for
6967
- which the pathname in that format is `s`.
6968
 
6969
  ``` cpp
6970
  template<class Source>
6971
  path(const Source& source, const locale& loc, format fmt = auto_format);
6972
  template<class InputIterator>
6973
  path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
6974
  ```
6975
 
6976
- *Requires:* The value type of `Source` and `InputIterator` is `char`.
6977
 
6978
  *Effects:* Let `s` be the effective range of `source` or the range
6979
  \[`first`, `last`), after converting the encoding as follows:
6980
 
6981
  - If `value_type` is `wchar_t`, converts to the native wide
6982
- encoding ([[fs.def.native.encode]]) using the
6983
  `codecvt<wchar_t, char, mbstate_t>` facet of `loc`.
6984
  - Otherwise a conversion is performed using the
6985
  `codecvt<wchar_t, char, mbstate_t>` facet of `loc`, and then a second
6986
- conversion to the current narrow encoding.
6987
 
6988
- Finds the detected-format of `s` ([[fs.path.fmt.cvt]]) and constructs
6989
- an object of class `path` for which the pathname in that format is `s`.
6990
 
6991
  [*Example 1*:
6992
 
6993
  A string is to be read from a database that is encoded in ISO/IEC
6994
  8859-1, and used to create a directory:
@@ -7002,27 +7937,27 @@ fs::create_directory(fs::path(latin1_string, latin1_locale));
7002
  ```
7003
 
7004
  For POSIX-based operating systems, the path is constructed by first
7005
  using `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string`
7006
  to a wide character string in the native wide
7007
- encoding ([[fs.def.native.encode]]). The resulting wide string is then
7008
- converted to a narrow character pathname string in the current native
7009
- narrow encoding. If the native wide encoding is UTF-16 or UTF-32, and
7010
- the current native narrow encoding is UTF-8, all of the characters in
7011
  the ISO/IEC 8859-1 character set will be converted to their Unicode
7012
- representation, but for other native narrow encodings some characters
7013
  may have no representation.
7014
 
7015
  For Windows-based operating systems, the path is constructed by using
7016
  `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string` to a
7017
  UTF-16 encoded wide character pathname string. All of the characters in
7018
  the ISO/IEC 8859-1 character set will be converted to their Unicode
7019
  representation.
7020
 
7021
  — *end example*]
7022
 
7023
- ##### `path` assignments <a id="fs.path.assign">[[fs.path.assign]]</a>
7024
 
7025
  ``` cpp
7026
  path& operator=(const path& p);
7027
  ```
7028
 
@@ -7062,18 +7997,18 @@ template <class Source>
7062
  path& assign(const Source& source);
7063
  template<class InputIterator>
7064
  path& assign(InputIterator first, InputIterator last);
7065
  ```
7066
 
7067
- *Effects:* Let `s` be the effective range of `source` ([[fs.path.req]])
7068
- or the range \[`first`, `last`), with the encoding converted if
7069
- required ([[fs.path.cvt]]). Finds the detected-format of
7070
- `s` ([[fs.path.fmt.cvt]]) and sets the pathname in that format to `s`.
7071
 
7072
  *Returns:* `*this`.
7073
 
7074
- ##### `path` appends <a id="fs.path.append">[[fs.path.append]]</a>
7075
 
7076
  The append operations use `operator/=` to denote their semantic effect
7077
  of appending *preferred-separator* when needed.
7078
 
7079
  ``` cpp
@@ -7096,26 +8031,28 @@ Otherwise, modifies `*this` as if by these steps:
7096
  pathname.
7097
 
7098
  [*Example 2*:
7099
 
7100
  Even if `//host` is interpreted as a *root-name*, both of the paths
7101
- `path("//host")/"foo"` and `path("//host/")/"foo"` equal `"//host/foo"`.
 
7102
 
7103
  Expression examples:
7104
 
7105
  ``` cpp
7106
  // On POSIX,
7107
- path("foo") / ""; // yields "foo/"
7108
- path("foo") / "/bar"; // yields "/bar"
7109
- // On Windows, backslashes replace slashes in the above yields
7110
 
7111
  // On Windows,
7112
- path("foo") / "c:/bar"; // yields "c:/bar"
7113
- path("foo") / "c:"; // yields "c:"
7114
- path("c:") / ""; // yields "c:"
7115
- path("c:foo") / "/bar"; // yields "c:/bar"
7116
- path("c:foo") / "c:bar"; // yields "c:foo/bar"
 
 
7117
  ```
7118
 
7119
  — *end example*]
7120
 
7121
  *Returns:* `*this`.
@@ -7134,22 +8071,19 @@ template <class InputIterator>
7134
  path& append(InputIterator first, InputIterator last);
7135
  ```
7136
 
7137
  *Effects:* Equivalent to: `return operator/=(path(first, last));`
7138
 
7139
- ##### `path` concatenation <a id="fs.path.concat">[[fs.path.concat]]</a>
7140
 
7141
  ``` cpp
7142
  path& operator+=(const path& x);
7143
  path& operator+=(const string_type& x);
7144
  path& operator+=(basic_string_view<value_type> x);
7145
  path& operator+=(const value_type* x);
7146
- path& operator+=(value_type x);
7147
  template<class Source>
7148
  path& operator+=(const Source& x);
7149
- template <class EcharT>
7150
- path& operator+=(EcharT x);
7151
  template<class Source>
7152
  path& concat(const Source& x);
7153
  ```
7154
 
7155
  *Effects:* Appends `path(x).native()` to the pathname in the native
@@ -7158,24 +8092,32 @@ format.
7158
  [*Note 2*: This directly manipulates the value of `native()` and may
7159
  not be portable between operating systems. — *end note*]
7160
 
7161
  *Returns:* `*this`.
7162
 
 
 
 
 
 
 
 
 
7163
  ``` cpp
7164
  template<class InputIterator>
7165
  path& concat(InputIterator first, InputIterator last);
7166
  ```
7167
 
7168
- *Effects:* Equivalent to `return *this += path(first, last)`.
7169
 
7170
- ##### `path` modifiers <a id="fs.path.modifiers">[[fs.path.modifiers]]</a>
7171
 
7172
  ``` cpp
7173
  void clear() noexcept;
7174
  ```
7175
 
7176
- *Postconditions:* `empty() == true`.
7177
 
7178
  ``` cpp
7179
  path& make_preferred();
7180
  ```
7181
 
@@ -7213,15 +8155,15 @@ output is:
7213
 
7214
  ``` cpp
7215
  path& remove_filename();
7216
  ```
7217
 
7218
- *Postconditions:* `!has_filename()`.
7219
-
7220
  *Effects:* Remove the generic format pathname of `filename()` from the
7221
  generic format pathname.
7222
 
 
 
7223
  *Returns:* `*this`.
7224
 
7225
  [*Example 4*:
7226
 
7227
  ``` cpp
@@ -7259,12 +8201,12 @@ path("/").replace_filename("bar"); // yields "/bar" on POSIX
7259
  path& replace_extension(const path& replacement = path());
7260
  ```
7261
 
7262
  *Effects:*
7263
 
7264
- - Any existing `extension()(` [[fs.path.decompose]]`)` is removed from
7265
- the pathname in the generic format, then
7266
  - If `replacement` is not empty and does not begin with a dot character,
7267
  a dot character is appended to the pathname in the generic format,
7268
  then
7269
  - `operator+=(replacement);`.
7270
 
@@ -7276,14 +8218,14 @@ void swap(path& rhs) noexcept;
7276
 
7277
  *Effects:* Swaps the contents (in all formats) of the two paths.
7278
 
7279
  *Complexity:* Constant time.
7280
 
7281
- ##### `path` native format observers <a id="fs.path.native.obs">[[fs.path.native.obs]]</a>
7282
 
7283
  The string returned by all native format observers is in the native
7284
- pathname format ([[fs.def.native]]).
7285
 
7286
  ``` cpp
7287
  const string_type& native() const noexcept;
7288
  ```
7289
 
@@ -7291,11 +8233,11 @@ const string_type& native() const noexcept;
7291
 
7292
  ``` cpp
7293
  const value_type* c_str() const noexcept;
7294
  ```
7295
 
7296
- *Returns:* Equivalent to `native().c_str()`.
7297
 
7298
  ``` cpp
7299
  operator string_type() const;
7300
  ```
7301
 
@@ -7319,26 +8261,25 @@ be performed by `a`. Conversion, if any, is specified by
7319
  [[fs.path.cvt]].
7320
 
7321
  ``` cpp
7322
  std::string string() const;
7323
  std::wstring wstring() const;
7324
- std::string u8string() const;
7325
  std::u16string u16string() const;
7326
  std::u32string u32string() const;
7327
  ```
7328
 
7329
- *Returns:* `pathstring`.
7330
 
7331
  *Remarks:* Conversion, if any, is performed as specified by
7332
- [[fs.path.cvt]]. The encoding of the string returned by `u8string()` is
7333
- always UTF-8.
7334
 
7335
- ##### `path` generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
7336
 
7337
  Generic format observer functions return strings formatted according to
7338
- the generic pathname format ([[fs.path.generic]]). A single slash
7339
- (`'/'`) character is used as the *directory-separator*.
7340
 
7341
  [*Example 1*:
7342
 
7343
  On an operating system that uses backslash as its *preferred-separator*,
7344
 
@@ -7364,53 +8305,51 @@ be performed by `a`. Conversion, if any, is specified by
7364
  [[fs.path.cvt]].
7365
 
7366
  ``` cpp
7367
  std::string generic_string() const;
7368
  std::wstring generic_wstring() const;
7369
- std::string generic_u8string() const;
7370
  std::u16string generic_u16string() const;
7371
  std::u32string generic_u32string() const;
7372
  ```
7373
 
7374
  *Returns:* The pathname in the generic format.
7375
 
7376
- *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]]. The
7377
- encoding of the string returned by `generic_u8string()` is always UTF-8.
7378
 
7379
- ##### `path` compare <a id="fs.path.compare">[[fs.path.compare]]</a>
7380
 
7381
  ``` cpp
7382
  int compare(const path& p) const noexcept;
7383
  ```
7384
 
7385
  *Returns:*
7386
 
7387
- - A value less than `0`, if `native()` for the elements of `*this` are
7388
- lexicographically less than `native()` for the elements of `p`;
7389
- otherwise,
7390
- - a value greater than `0`, if `native()` for the elements of `*this`
7391
- are lexicographically greater than `native()` for the elements of `p`;
7392
- otherwise,
7393
- - `0`.
7394
-
7395
- *Remarks:* The elements are determined as if by iteration over the
7396
- half-open range \[`begin()`, `end()`) for `*this` and `p`.
 
 
 
 
7397
 
7398
  ``` cpp
7399
- int compare(const string_type& s) const
7400
  int compare(basic_string_view<value_type> s) const;
 
7401
  ```
7402
 
7403
- *Returns:* `compare(path(s))`.
7404
 
7405
- ``` cpp
7406
- int compare(const value_type* s) const
7407
- ```
7408
-
7409
- *Returns:* `compare(path(s))`.
7410
-
7411
- ##### `path` decomposition <a id="fs.path.decompose">[[fs.path.decompose]]</a>
7412
 
7413
  ``` cpp
7414
  path root_name() const;
7415
  ```
7416
 
@@ -7433,20 +8372,21 @@ path root_path() const;
7433
  ``` cpp
7434
  path relative_path() const;
7435
  ```
7436
 
7437
  *Returns:* A `path` composed from the pathname in the generic format, if
7438
- `!empty()`, beginning with the first *filename* after *root-path*.
7439
- Otherwise, `path()`.
7440
 
7441
  ``` cpp
7442
  path parent_path() const;
7443
  ```
7444
 
7445
- *Returns:* `*this` if `!has_relative_path()`, otherwise a path whose
7446
- generic format pathname is the longest prefix of the generic format
7447
- pathname of `*this` that produces one fewer element in its iteration.
 
7448
 
7449
  ``` cpp
7450
  path filename() const;
7451
  ```
7452
 
@@ -7493,11 +8433,11 @@ for (; !p.extension().empty(); p = p.stem())
7493
 
7494
  ``` cpp
7495
  path extension() const;
7496
  ```
7497
 
7498
- *Returns:* a path whose pathname in the generic format is the suffix of
7499
  `filename()` not included in `stem()`.
7500
 
7501
  [*Example 8*:
7502
 
7503
  ``` cpp
@@ -7516,18 +8456,18 @@ extension. — *end note*]
7516
 
7517
  [*Note 5*: On non-POSIX operating systems, for a path `p`, it may not
7518
  be the case that `p.stem() + p.extension() == p.filename()`, even though
7519
  the generic format pathnames are the same. — *end note*]
7520
 
7521
- ##### `path` query <a id="fs.path.query">[[fs.path.query]]</a>
7522
 
7523
  ``` cpp
7524
- bool empty() const noexcept;
7525
  ```
7526
 
7527
- *Returns:* `true` if the pathname in the generic format is empty, else
7528
- `false`.
7529
 
7530
  ``` cpp
7531
  bool has_root_path() const;
7532
  ```
7533
 
@@ -7578,11 +8518,11 @@ bool has_extension() const;
7578
  ``` cpp
7579
  bool is_absolute() const;
7580
  ```
7581
 
7582
  *Returns:* `true` if the pathname in the native format contains an
7583
- absolute path ([[fs.def.absolute.path]]), else `false`.
7584
 
7585
  [*Example 9*: `path("/").is_absolute()` is `true` for POSIX-based
7586
  operating systems, and `false` for Windows-based operating
7587
  systems. — *end example*]
7588
 
@@ -7590,18 +8530,18 @@ systems. — *end example*]
7590
  bool is_relative() const;
7591
  ```
7592
 
7593
  *Returns:* `!is_absolute()`.
7594
 
7595
- ##### `path` generation <a id="fs.path.gen">[[fs.path.gen]]</a>
7596
 
7597
  ``` cpp
7598
  path lexically_normal() const;
7599
  ```
7600
 
7601
  *Returns:* A path whose pathname in the generic format is the normal
7602
- form ([[fs.def.normal.form]]) of the pathname in the generic format of
7603
  `*this`.
7604
 
7605
  [*Example 10*:
7606
 
7607
  ``` cpp
@@ -7618,29 +8558,40 @@ slashes, but that does not affect `path` equality.
7618
  ``` cpp
7619
  path lexically_relative(const path& base) const;
7620
  ```
7621
 
7622
  *Returns:* `*this` made relative to `base`. Does not
7623
- resolve ([[fs.def.pathres]]) symlinks. Does not first
7624
- normalize ([[fs.def.normal.form]]) `*this` or `base`.
7625
-
7626
- *Effects:* If `root_name() != base.root_name()` is `true` or
7627
- `is_absolute() != base.is_absolute()` is `true` or
7628
- `!has_root_directory() && base.has_root_directory()` is `true`, returns
7629
- `path()`. Determines the first mismatched element of `*this` and `base`
7630
- as if by:
 
 
 
 
 
 
 
 
 
7631
 
7632
  ``` cpp
7633
  auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
7634
  ```
7635
 
7636
  Then,
7637
 
7638
  - if `a == end()` and `b == base.end()`, returns `path(".")`; otherwise
7639
  - let `n` be the number of *filename* elements in \[`b`, `base.end()`)
7640
- that are not *dot* or *dot-dot* minus the number that are *dot-dot*.
7641
- If `n<0,` returns `path()`; otherwise
 
 
7642
  - returns an object of class `path` that is default-constructed,
7643
  followed by
7644
  - application of `operator/=(path(".."))` `n` times, and then
7645
  - application of `operator/=` for each element in \[`a`, `end()`).
7646
 
@@ -7659,41 +8610,41 @@ The above assertions will succeed. On Windows, the returned path’s
7659
  *directory-separator* characters will be backslashes rather than
7660
  slashes, but that does not affect `path` equality.
7661
 
7662
  — *end example*]
7663
 
7664
- [*Note 6*: If symlink following semantics are desired, use the
7665
  operational function `relative()`. — *end note*]
7666
 
7667
- [*Note 7*: If normalization ([[fs.def.normal.form]]) is needed to
7668
- ensure consistent matching of elements, apply `lexically_normal()` to
7669
- `*this`, `base`, or both. — *end note*]
7670
 
7671
  ``` cpp
7672
  path lexically_proximate(const path& base) const;
7673
  ```
7674
 
7675
  *Returns:* If the value of `lexically_relative(base)` is not an empty
7676
  path, return it. Otherwise return `*this`.
7677
 
7678
- [*Note 8*: If symlink following semantics are desired, use the
7679
  operational function `proximate()`. — *end note*]
7680
 
7681
- [*Note 9*: If normalization ([[fs.def.normal.form]]) is needed to
7682
- ensure consistent matching of elements, apply `lexically_normal()` to
7683
- `*this`, `base`, or both. — *end note*]
7684
 
7685
- #### `path` iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
7686
 
7687
  Path iterators iterate over the elements of the pathname in the generic
7688
- format ([[fs.path.generic]]).
7689
 
7690
- A `path::iterator` is a constant iterator satisfying all the
7691
- requirements of a bidirectional iterator ([[bidirectional.iterators]])
7692
- except that, for dereferenceable iterators `a` and `b` of type
7693
- `path::iterator` with `a == b`, there is no requirement that `*a` and
7694
- `*b` are bound to the same object. Its `value_type` is `path`.
7695
 
7696
  Calling any non-const member function of a `path` object invalidates all
7697
  iterators referring to elements of that object.
7698
 
7699
  For the elements of the pathname in the generic format, the forward
@@ -7720,171 +8671,94 @@ list above. If no elements are present, the end iterator.
7720
  iterator end() const;
7721
  ```
7722
 
7723
  *Returns:* The end iterator.
7724
 
7725
- #### `path` non-member functions <a id="fs.path.nonmember">[[fs.path.nonmember]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7726
 
7727
  ``` cpp
7728
  void swap(path& lhs, path& rhs) noexcept;
7729
  ```
7730
 
7731
- *Effects:* Equivalent to: `lhs.swap(rhs);`
7732
 
7733
  ``` cpp
7734
  size_t hash_value (const path& p) noexcept;
7735
  ```
7736
 
7737
  *Returns:* A hash value for the path `p`. If for two paths, `p1 == p2`
7738
  then `hash_value(p1) == hash_value(p2)`.
7739
 
7740
  ``` cpp
7741
- bool operator< (const path& lhs, const path& rhs) noexcept;
7742
  ```
7743
 
7744
- *Returns:* `lhs.compare(rhs) < 0`.
7745
-
7746
- ``` cpp
7747
- bool operator<=(const path& lhs, const path& rhs) noexcept;
7748
- ```
7749
-
7750
- *Returns:* `!(rhs < lhs)`.
7751
-
7752
- ``` cpp
7753
- bool operator> (const path& lhs, const path& rhs) noexcept;
7754
- ```
7755
-
7756
- *Returns:* `rhs < lhs`.
7757
-
7758
- ``` cpp
7759
- bool operator>=(const path& lhs, const path& rhs) noexcept;
7760
- ```
7761
-
7762
- *Returns:* `!(lhs < rhs)`.
7763
-
7764
- ``` cpp
7765
- bool operator==(const path& lhs, const path& rhs) noexcept;
7766
- ```
7767
-
7768
- *Returns:* `!(lhs < rhs) && !(rhs < lhs)`.
7769
 
7770
  [*Note 1*:
7771
 
7772
  Path equality and path equivalence have different semantics.
7773
 
7774
  - Equality is determined by the `path` non-member `operator==`, which
7775
- considers the two paths lexical representations only.
7776
  \[*Example 1*: `path("foo") == "bar"` is never
7777
  `true`. — *end example*]
7778
  - Equivalence is determined by the `equivalent()` non-member function,
7779
- which determines if two paths resolve ([[fs.def.pathres]]) to the
7780
- same file system entity. \[*Example 2*: `equivalent("foo", "bar")`
7781
- will be `true` when both paths resolve to the same
7782
- file. — *end example*]
7783
 
7784
  Programmers wishing to determine if two paths are “the same” must decide
7785
  if “the same” means “the same representation” or “resolve to the same
7786
  actual file”, and choose the appropriate function accordingly.
7787
 
7788
  — *end note*]
7789
 
7790
  ``` cpp
7791
- bool operator!=(const path& lhs, const path& rhs) noexcept;
7792
  ```
7793
 
7794
- *Returns:* `!(lhs == rhs)`.
7795
 
7796
  ``` cpp
7797
- path operator/ (const path& lhs, const path& rhs);
7798
  ```
7799
 
7800
  *Effects:* Equivalent to: `return path(lhs) /= rhs;`
7801
 
7802
- ##### `path` inserter and extractor <a id="fs.path.io">[[fs.path.io]]</a>
7803
-
7804
- ``` cpp
7805
- template <class charT, class traits>
7806
- basic_ostream<charT, traits>&
7807
- operator<<(basic_ostream<charT, traits>& os, const path& p);
7808
- ```
7809
-
7810
- *Effects:* Equivalent to: `os << quoted(p.string<charT, traits>());`
7811
-
7812
- [*Note 2*: The `quoted` function is described
7813
- in  [[quoted.manip]]. — *end note*]
7814
-
7815
- *Returns:* `os`.
7816
-
7817
- ``` cpp
7818
- template <class charT, class traits>
7819
- basic_istream<charT, traits>&
7820
- operator>>(basic_istream<charT, traits>& is, path& p);
7821
- ```
7822
-
7823
- *Effects:* Equivalent to:
7824
-
7825
- ``` cpp
7826
- basic_string<charT, traits> tmp;
7827
- is >> quoted(tmp);
7828
- p = tmp;
7829
- ```
7830
-
7831
- *Returns:* `is`.
7832
-
7833
- ##### `path` factory functions <a id="fs.path.factory">[[fs.path.factory]]</a>
7834
-
7835
- ``` cpp
7836
- template <class Source>
7837
- path u8path(const Source& source);
7838
- template <class InputIterator>
7839
- path u8path(InputIterator first, InputIterator last);
7840
- ```
7841
-
7842
- *Requires:* The `source` and \[`first`, `last`) sequences are UTF-8
7843
- encoded. The value type of `Source` and `InputIterator` is `char`.
7844
-
7845
- *Returns:*
7846
-
7847
- - If `value_type` is `char` and the current native narrow
7848
- encoding ([[fs.def.native.encode]]) is UTF-8, return `path(source)`
7849
- or `path(first, last)`; otherwise,
7850
- - if `value_type` is `wchar_t` and the native wide encoding is UTF-16,
7851
- or if `value_type` is `char16_t` or `char32_t`, convert `source` or
7852
- \[`first`, `last`) to a temporary, `tmp`, of type `string_type` and
7853
- return `path(tmp)`; otherwise,
7854
- - convert `source` or \[`first`, `last`) to a temporary, `tmp`, of type
7855
- `u32string` and return `path(tmp)`.
7856
-
7857
- *Remarks:* Argument format conversion ([[fs.path.fmt.cvt]]) applies to
7858
- the arguments for these functions. How Unicode encoding conversions are
7859
- performed is unspecified.
7860
-
7861
- [*Example 1*:
7862
-
7863
- A string is to be read from a database that is encoded in UTF-8, and
7864
- used to create a directory using the native encoding for filenames:
7865
-
7866
- ``` cpp
7867
- namespace fs = std::filesystem;
7868
- std::string utf8_string = read_utf8_data();
7869
- fs::create_directory(fs::u8path(utf8_string));
7870
- ```
7871
-
7872
- For POSIX-based operating systems with the native narrow encoding set to
7873
- UTF-8, no encoding or type conversion occurs.
7874
-
7875
- For POSIX-based operating systems with the native narrow encoding not
7876
- set to UTF-8, a conversion to UTF-32 occurs, followed by a conversion to
7877
- the current native narrow encoding. Some Unicode characters may have no
7878
- native character set representation.
7879
-
7880
- For Windows-based operating systems a conversion from UTF-8 to UTF-16
7881
- occurs.
7882
-
7883
- — *end example*]
7884
-
7885
- ### Class `filesystem_error` <a id="fs.class.filesystem_error">[[fs.class.filesystem_error]]</a>
7886
 
7887
  ``` cpp
7888
  namespace std::filesystem {
7889
  class filesystem_error : public system_error {
7890
  public:
@@ -7900,65 +8774,50 @@ namespace std::filesystem {
7900
  };
7901
  }
7902
  ```
7903
 
7904
  The class `filesystem_error` defines the type of objects thrown as
7905
- exceptions to report file system errors from functions described in this
7906
- subclause.
7907
 
7908
- #### `filesystem_error` members <a id="filesystem_error.members">[[filesystem_error.members]]</a>
7909
 
7910
  Constructors are provided that store zero, one, or two paths associated
7911
  with an error.
7912
 
7913
  ``` cpp
7914
  filesystem_error(const string& what_arg, error_code ec);
7915
  ```
7916
 
7917
- *Postconditions:* The postconditions of this function are indicated in
7918
- Table  [[tab:filesystem_error.1]].
7919
 
7920
- **Table: `filesystem_error(const string&, error_code)` effects** <a id="tab:filesystem_error.1">[tab:filesystem_error.1]</a>
7921
-
7922
- | Expression | Value |
7923
- | ----------------------- | ------------------ |
7924
- | `runtime_error::what()` | `what_arg.c_str()` |
7925
- | `code()` | `ec` |
7926
- | `path1().empty()` | `true` |
7927
- | `path2().empty()` | `true` |
7928
 
7929
  ``` cpp
7930
  filesystem_error(const string& what_arg, const path& p1, error_code ec);
7931
  ```
7932
 
7933
- *Postconditions:* The postconditions of this function are indicated in
7934
- Table  [[tab:filesystem_error.2]].
7935
 
7936
- **Table: `filesystem_error(const string&, const path&, error_code)` effects** <a id="tab:filesystem_error.2">[tab:filesystem_error.2]</a>
7937
-
7938
- | Expression | Value |
7939
- | ----------------------- | -------------------------------- |
7940
- | `runtime_error::what()` | `what_arg.c_str()` |
7941
- | `code()` | `ec` |
7942
- | `path1()` | Reference to stored copy of `p1` |
7943
- | `path2().empty()` | `true` |
7944
 
7945
  ``` cpp
7946
  filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
7947
  ```
7948
 
7949
- *Postconditions:* The postconditions of this function are indicated in
7950
- Table  [[tab:filesystem_error.3]].
7951
 
7952
- **Table: `filesystem_error(const string&, const path&, const path&, error_code)` effects** <a id="tab:filesystem_error.3">[tab:filesystem_error.3]</a>
7953
-
7954
- | Expression | Value |
7955
- | ----------------------- | -------------------------------- |
7956
- | `runtime_error::what()` | `what_arg.c_str()` |
7957
- | `code()` | `ec` |
7958
- | `path1()` | Reference to stored copy of `p1` |
7959
- | `path2()` | Reference to stored copy of `p2` |
7960
 
7961
  ``` cpp
7962
  const path& path1() const noexcept;
7963
  ```
7964
 
@@ -7974,45 +8833,46 @@ or, if none, an empty path.
7974
 
7975
  ``` cpp
7976
  const char* what() const noexcept override;
7977
  ```
7978
 
7979
- *Returns:* A string containing `runtime_error::what()`. The exact format
7980
- is unspecified. Implementations are encouraged but not required to
7981
- include `path1.native_string()` if not empty, `path2.native_string()` if
7982
- not empty, and `system_error::what()` strings in the returned string.
7983
 
7984
  ### Enumerations <a id="fs.enum">[[fs.enum]]</a>
7985
 
7986
  #### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
7987
 
7988
  This enum specifies constants used to identify the format of the
7989
- character sequence, with the meanings listed in Table 
7990
- [[tab:enum.path.format]].
7991
 
7992
  [*Note 1*: For POSIX-based systems, native and generic formats are
7993
  equivalent and the character sequence should always be interpreted in
7994
  the same way. — *end note*]
7995
 
7996
- #### Enum class `file_type` <a id="fs.enum.file_type">[[fs.enum.file_type]]</a>
7997
 
7998
  This enum class specifies constants used to identify file types, with
7999
- the meanings listed in Table  [[tab:fs.enum.file_type]].
 
8000
 
8001
  [*Note 1*: The file not being found is not considered an error while
8002
  determining the type of a file. — *end note*]
8003
 
8004
  #### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
8005
 
8006
- The `enum class` type `copy_options` is a bitmask type (
8007
- [[bitmask.types]]) that specifies bitmask constants used to control the
8008
- semantics of copy operations. The constants are specified in option
8009
- groups with the meanings listed in Table  [[tab:fs.enum.copy_options]].
8010
- Constant `none` is shown in each option group for purposes of
8011
  exposition; implementations shall provide only a single definition.
 
8012
 
8013
- **Table: Enum class `copy_options`** <a id="tab:fs.enum.copy_options">[tab:fs.enum.copy_options]</a>
8014
 
8015
  | Constant | Meaning |
8016
  | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
8017
  | `none` | (Default) Error; file already exists. |
8018
  | `skip_existing` | Do not overwrite existing file, do not report an error. |
@@ -8026,15 +8886,15 @@ exposition; implementations shall provide only a single definition.
8026
  | `create_hard_links` | Make hard links instead of copies of files. |
8027
 
8028
 
8029
  #### Enum class `perms` <a id="fs.enum.perms">[[fs.enum.perms]]</a>
8030
 
8031
- The `enum class` type `perms` is a bitmask type ([[bitmask.types]])
8032
- that specifies bitmask constants used to identify file permissions, with
8033
- the meanings listed in Table  [[tab:fs.enum.perms]].
8034
 
8035
- **Table: Enum class `perms`** <a id="tab:fs.enum.perms">[tab:fs.enum.perms]</a>
8036
 
8037
  | Name | Value (octal) | POSIX macro | Definition or notes |
8038
  | -------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
8039
  | `none` | `0` | | There are no permissions set for the file. |
8040
  | `owner_read` | `0400` | `S_IRUSR` | Read permission, owner |
@@ -8057,81 +8917,85 @@ the meanings listed in Table  [[tab:fs.enum.perms]].
8057
  | `unknown` | `0xFFFF` | | The permissions are not known, such as when a `file_status` object is created without specifying the permissions |
8058
 
8059
 
8060
  #### Enum class `perm_options` <a id="fs.enum.perm.opts">[[fs.enum.perm.opts]]</a>
8061
 
8062
- The `enum class` type `perm_options` is a bitmask type (
8063
- [[bitmask.types]]) that specifies bitmask constants used to control the
8064
- semantics of permissions operations, with the meanings listed in Table 
8065
- [[tab:enum.perm_options]]. The bitmask constants are bitmask elements.
8066
- In Table  [[tab:enum.perm_options]] `perm` denotes a value of type
8067
- `perms` passed to `permissions`.
8068
 
8069
- **Table: Enum class `perm_options`** <a id="tab:enum.perm_options">[tab:enum.perm_options]</a>
8070
 
8071
  | Name | Meaning |
8072
- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
8073
  | `replace` | `permissions` shall replace the file's permission bits with `perm` |
8074
- | `add` | `permissions` shall replace the file's permission bits with the bitwise OR of `perm` and the file's current permission bits. |
8075
- | `remove` | `permissions` shall replace the file's permission bits with the bitwise AND of the complement of `perm` and the file's current permission bits. |
8076
  | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
8077
 
8078
 
8079
  #### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
8080
 
8081
- The `enum class` type `directory_options` is a bitmask type (
8082
- [[bitmask.types]]) that specifies bitmask constants used to identify
8083
- directory traversal options, with the meanings listed in Table 
8084
- [[tab:fs.enum.directory_options]].
 
8085
 
8086
- **Table: Enum class `directory_options`** <a id="tab:fs.enum.directory_options">[tab:fs.enum.directory_options]</a>
8087
 
8088
  | Name | Meaning |
8089
  | -------------------------- | ------------------------------------------------------------------ |
8090
  | `none` | (Default) Skip directory symlinks, permission denied is an error. |
8091
  | `follow_directory_symlink` | Follow rather than skip directory symlinks. |
8092
  | `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
8093
 
8094
 
8095
- ### Class `file_status` <a id="fs.class.file_status">[[fs.class.file_status]]</a>
8096
 
8097
  ``` cpp
8098
  namespace std::filesystem {
8099
  class file_status {
8100
  public:
8101
- // [fs.file_status.cons], constructors and destructor
8102
  file_status() noexcept : file_status(file_type::none) {}
8103
  explicit file_status(file_type ft,
8104
  perms prms = perms::unknown) noexcept;
8105
  file_status(const file_status&) noexcept = default;
8106
  file_status(file_status&&) noexcept = default;
8107
  ~file_status();
8108
 
8109
- // assignments:
8110
  file_status& operator=(const file_status&) noexcept = default;
8111
  file_status& operator=(file_status&&) noexcept = default;
8112
 
8113
- // [fs.file_status.mods], modifiers
8114
  void type(file_type ft) noexcept;
8115
  void permissions(perms prms) noexcept;
8116
 
8117
- // [fs.file_status.obs], observers
8118
  file_type type() const noexcept;
8119
  perms permissions() const noexcept;
 
 
 
8120
  };
8121
  }
8122
  ```
8123
 
8124
- #### `file_status` constructors <a id="fs.file_status.cons">[[fs.file_status.cons]]</a>
8125
 
8126
  ``` cpp
8127
  explicit file_status(file_type ft, perms prms = perms::unknown) noexcept;
8128
  ```
8129
 
8130
- *Postconditions:* `type() == ft` and `permissions() == prms`.
8131
 
8132
- #### `file_status` observers <a id="fs.file_status.obs">[[fs.file_status.obs]]</a>
8133
 
8134
  ``` cpp
8135
  file_type type() const noexcept;
8136
  ```
8137
 
@@ -8145,53 +9009,53 @@ perms permissions() const noexcept;
8145
 
8146
  *Returns:* The value of `permissions()` specified by the postconditions
8147
  of the most recent call to a constructor, `operator=`, or
8148
  `permissions(perms)` function.
8149
 
8150
- #### `file_status` modifiers <a id="fs.file_status.mods">[[fs.file_status.mods]]</a>
8151
 
8152
  ``` cpp
8153
  void type(file_type ft) noexcept;
8154
  ```
8155
 
8156
- *Postconditions:* `type() == ft`.
8157
 
8158
  ``` cpp
8159
  void permissions(perms prms) noexcept;
8160
  ```
8161
 
8162
- *Postconditions:* `permissions() == prms`.
8163
 
8164
- ### Class `directory_entry` <a id="fs.class.directory_entry">[[fs.class.directory_entry]]</a>
8165
 
8166
  ``` cpp
8167
  namespace std::filesystem {
8168
  class directory_entry {
8169
  public:
8170
  // [fs.dir.entry.cons], constructors and destructor
8171
  directory_entry() noexcept = default;
8172
  directory_entry(const directory_entry&) = default;
8173
  directory_entry(directory_entry&&) noexcept = default;
8174
- explicit directory_entry(const path& p);
8175
- directory_entry(const path& p, error_code& ec);
8176
  ~directory_entry();
8177
 
8178
- // assignments:
8179
  directory_entry& operator=(const directory_entry&) = default;
8180
  directory_entry& operator=(directory_entry&&) noexcept = default;
8181
 
8182
  // [fs.dir.entry.mods], modifiers
8183
- void assign(const path& p);
8184
- void assign(const path& p, error_code& ec);
8185
- void replace_filename(const path& p);
8186
- void replace_filename(const path& p, error_code& ec);
8187
  void refresh();
8188
  void refresh(error_code& ec) noexcept;
8189
 
8190
  // [fs.dir.entry.obs], observers
8191
- const path& path() const noexcept;
8192
- operator const path&() const noexcept;
8193
  bool exists() const;
8194
  bool exists(error_code& ec) const noexcept;
8195
  bool is_block_file() const;
8196
  bool is_block_file(error_code& ec) const noexcept;
8197
  bool is_character_file() const;
@@ -8217,36 +9081,32 @@ namespace std::filesystem {
8217
  file_status status() const;
8218
  file_status status(error_code& ec) const noexcept;
8219
  file_status symlink_status() const;
8220
  file_status symlink_status(error_code& ec) const noexcept;
8221
 
8222
- bool operator< (const directory_entry& rhs) const noexcept;
8223
  bool operator==(const directory_entry& rhs) const noexcept;
8224
- bool operator!=(const directory_entry& rhs) const noexcept;
8225
- bool operator<=(const directory_entry& rhs) const noexcept;
8226
- bool operator> (const directory_entry& rhs) const noexcept;
8227
- bool operator>=(const directory_entry& rhs) const noexcept;
8228
 
8229
  private:
8230
- path pathobject; // exposition only
8231
  friend class directory_iterator; // exposition only
8232
  };
8233
  }
8234
  ```
8235
 
8236
  A `directory_entry` object stores a `path` object and may store
8237
  additional objects for file attributes such as hard link count, status,
8238
  symlink status, file size, and last write time.
8239
 
8240
- Implementations are encouraged to store such additional file attributes
8241
- during directory iteration if their values are available and storing the
8242
- values would allow the implementation to eliminate file system accesses
8243
- by `directory_entry` observer functions ([[fs.op.funcs]]). Such stored
8244
- file attribute values are said to be *cached*.
8245
 
8246
- [*Note 1*: For purposes of exposition, class `directory_iterator` (
8247
- [[fs.class.directory_iterator]]) is shown above as a friend of class
8248
  `directory_entry`. Friendship allows the `directory_iterator`
8249
  implementation to cache already available attribute values directly into
8250
  a `directory_entry` object without the cost of an unneeded call to
8251
  `refresh()`. — *end note*]
8252
 
@@ -8278,41 +9138,40 @@ so will not result in a potentially expensive call to the
8278
  `std::filesystem::last_write_time` function. The code is portable to any
8279
  implementation, regardless of whether or not it employs caching.
8280
 
8281
  — *end example*]
8282
 
8283
- #### `directory_entry` constructors <a id="fs.dir.entry.cons">[[fs.dir.entry.cons]]</a>
8284
 
8285
  ``` cpp
8286
- explicit directory_entry(const path& p);
8287
- directory_entry(const path& p, error_code& ec);
8288
  ```
8289
 
8290
- *Effects:* Constructs an object of type `directory_entry`, then
8291
- `refresh()` or `refresh(ec)`, respectively.
8292
 
8293
- *Postconditions:* `path() == p` if no error occurs, otherwise
8294
- `path() == std::filesystem::path()`.
8295
 
8296
  *Throws:* As specified in  [[fs.err.report]].
8297
 
8298
- #### `directory_entry` modifiers <a id="fs.dir.entry.mods">[[fs.dir.entry.mods]]</a>
8299
 
8300
  ``` cpp
8301
- void assign(const path& p);
8302
- void assign(const path& p, error_code& ec);
8303
  ```
8304
 
8305
  *Effects:* Equivalent to `pathobject = p`, then `refresh()` or
8306
  `refresh(ec)`, respectively. If an error occurs, the values of any
8307
  cached attributes are unspecified.
8308
 
8309
  *Throws:* As specified in  [[fs.err.report]].
8310
 
8311
  ``` cpp
8312
- void replace_filename(const path& p);
8313
- void replace_filename(const path& p, error_code& ec);
8314
  ```
8315
 
8316
  *Effects:* Equivalent to `pathobject.replace_filename(p)`, then
8317
  `refresh()` or `refresh(ec)`, respectively. If an error occurs, the
8318
  values of any cached attributes are unspecified.
@@ -8324,121 +9183,121 @@ void refresh();
8324
  void refresh(error_code& ec) noexcept;
8325
  ```
8326
 
8327
  *Effects:* Stores the current values of any cached attributes of the
8328
  file `p` resolves to. If an error occurs, an error is
8329
- reported ([[fs.err.report]]) and the values of any cached attributes
8330
- are unspecified.
8331
 
8332
  *Throws:* As specified in  [[fs.err.report]].
8333
 
8334
- [*Note 1*: Implementations of
8335
- `directory_iterator` ([[fs.class.directory_iterator]]) are prohibited
8336
- from directly or indirectly calling the `refresh` function since it must
8337
- access the external file system, and the objective of caching is to
8338
- avoid unnecessary file system accesses. — *end note*]
8339
 
8340
- #### `directory_entry` observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
8341
 
8342
  Unqualified function names in the *Returns:* elements of the
8343
  `directory_entry` observers described below refer to members of the
8344
  `std::filesystem` namespace.
8345
 
8346
  ``` cpp
8347
- const path& path() const noexcept;
8348
- operator const path&() const noexcept;
8349
  ```
8350
 
8351
  *Returns:* `pathobject`.
8352
 
8353
  ``` cpp
8354
  bool exists() const;
8355
  bool exists(error_code& ec) const noexcept;
8356
  ```
8357
 
8358
- *Returns:* `exists(this->status())` or `exists(this->status(), ec)`,
8359
  respectively.
8360
 
8361
  *Throws:* As specified in  [[fs.err.report]].
8362
 
8363
  ``` cpp
8364
  bool is_block_file() const;
8365
  bool is_block_file(error_code& ec) const noexcept;
8366
  ```
8367
 
8368
  *Returns:* `is_block_file(this->status())` or
8369
- `is_block_file(this->status(), ec)`, respectively.
8370
 
8371
  *Throws:* As specified in  [[fs.err.report]].
8372
 
8373
  ``` cpp
8374
  bool is_character_file() const;
8375
  bool is_character_file(error_code& ec) const noexcept;
8376
  ```
8377
 
8378
  *Returns:* `is_character_file(this->status())` or
8379
- `is_character_file(this->status(), ec)`, respectively.
8380
 
8381
  *Throws:* As specified in  [[fs.err.report]].
8382
 
8383
  ``` cpp
8384
  bool is_directory() const;
8385
  bool is_directory(error_code& ec) const noexcept;
8386
  ```
8387
 
8388
  *Returns:* `is_directory(this->status())` or
8389
- `is_directory(this->status(), ec)`, respectively.
8390
 
8391
  *Throws:* As specified in  [[fs.err.report]].
8392
 
8393
  ``` cpp
8394
  bool is_fifo() const;
8395
  bool is_fifo(error_code& ec) const noexcept;
8396
  ```
8397
 
8398
- *Returns:* `is_fifo(this->status())` or `is_fifo(this->status(), ec)`,
8399
  respectively.
8400
 
8401
  *Throws:* As specified in  [[fs.err.report]].
8402
 
8403
  ``` cpp
8404
  bool is_other() const;
8405
  bool is_other(error_code& ec) const noexcept;
8406
  ```
8407
 
8408
- *Returns:* `is_other(this->status())` or `is_other(this->status(), ec)`,
8409
  respectively.
8410
 
8411
  *Throws:* As specified in  [[fs.err.report]].
8412
 
8413
  ``` cpp
8414
  bool is_regular_file() const;
8415
  bool is_regular_file(error_code& ec) const noexcept;
8416
  ```
8417
 
8418
  *Returns:* `is_regular_file(this->status())` or
8419
- `is_regular_file(this->status(), ec)`, respectively.
8420
 
8421
  *Throws:* As specified in  [[fs.err.report]].
8422
 
8423
  ``` cpp
8424
  bool is_socket() const;
8425
  bool is_socket(error_code& ec) const noexcept;
8426
  ```
8427
 
8428
- *Returns:* `is_socket(this->status())` or
8429
- `is_socket(this->status(), ec)`, respectively.
8430
 
8431
  *Throws:* As specified in  [[fs.err.report]].
8432
 
8433
  ``` cpp
8434
  bool is_symlink() const;
8435
  bool is_symlink(error_code& ec) const noexcept;
8436
  ```
8437
 
8438
  *Returns:* `is_symlink(this->symlink_status())` or
8439
- `is_symlink(this->symlink_status(), ec)`, respectively.
8440
 
8441
  *Throws:* As specified in  [[fs.err.report]].
8442
 
8443
  ``` cpp
8444
  uintmax_t file_size() const;
@@ -8497,49 +9356,24 @@ bool operator==(const directory_entry& rhs) const noexcept;
8497
  ```
8498
 
8499
  *Returns:* `pathobject == rhs.pathobject`.
8500
 
8501
  ``` cpp
8502
- bool operator!=(const directory_entry& rhs) const noexcept;
8503
  ```
8504
 
8505
- *Returns:* `pathobject != rhs.pathobject`.
8506
 
8507
- ``` cpp
8508
- bool operator< (const directory_entry& rhs) const noexcept;
8509
- ```
8510
-
8511
- *Returns:* `pathobject < rhs.pathobject`.
8512
-
8513
- ``` cpp
8514
- bool operator<=(const directory_entry& rhs) const noexcept;
8515
- ```
8516
-
8517
- *Returns:* `pathobject <= rhs.pathobject`.
8518
-
8519
- ``` cpp
8520
- bool operator> (const directory_entry& rhs) const noexcept;
8521
- ```
8522
-
8523
- *Returns:* `pathobject > rhs.pathobject`.
8524
-
8525
- ``` cpp
8526
- bool operator>=(const directory_entry& rhs) const noexcept;
8527
- ```
8528
-
8529
- *Returns:* `pathobject >= rhs.pathobject`.
8530
-
8531
- ### Class `directory_iterator` <a id="fs.class.directory_iterator">[[fs.class.directory_iterator]]</a>
8532
 
8533
  An object of type `directory_iterator` provides an iterator for a
8534
  sequence of `directory_entry` elements representing the path and any
8535
- cached attribute values ([[fs.class.directory_entry]]) for each file in
8536
- a directory or in an *implementation-defined* directory-like file type.
8537
 
8538
  [*Note 1*: For iteration into sub-directories, see class
8539
- `recursive_directory_iterator` (
8540
- [[fs.class.rec.dir.itr]]). — *end note*]
8541
 
8542
  ``` cpp
8543
  namespace std::filesystem {
8544
  class directory_iterator {
8545
  public:
@@ -8551,32 +9385,32 @@ namespace std::filesystem {
8551
 
8552
  // [fs.dir.itr.members], member functions
8553
  directory_iterator() noexcept;
8554
  explicit directory_iterator(const path& p);
8555
  directory_iterator(const path& p, directory_options options);
8556
- directory_iterator(const path& p, error_code& ec) noexcept;
8557
  directory_iterator(const path& p, directory_options options,
8558
- error_code& ec) noexcept;
8559
  directory_iterator(const directory_iterator& rhs);
8560
  directory_iterator(directory_iterator&& rhs) noexcept;
8561
  ~directory_iterator();
8562
 
8563
  directory_iterator& operator=(const directory_iterator& rhs);
8564
  directory_iterator& operator=(directory_iterator&& rhs) noexcept;
8565
 
8566
  const directory_entry& operator*() const;
8567
  const directory_entry* operator->() const;
8568
  directory_iterator& operator++();
8569
- directory_iterator& increment(error_code& ec) noexcept;
8570
 
8571
  // other members as required by [input.iterators], input iterators
8572
  };
8573
  }
8574
  ```
8575
 
8576
- `directory_iterator` satisfies the requirements of an input iterator (
8577
- [[input.iterators]]).
8578
 
8579
  If an iterator of type `directory_iterator` reports an error or is
8580
  advanced past the last directory element, that iterator shall become
8581
  equal to the end iterator value. The `directory_iterator` default
8582
  constructor shall create an iterator equal to the end iterator value,
@@ -8592,24 +9426,24 @@ object obtained by dereferencing a `directory_iterator` is a reference
8592
  to a `path` object composed of the directory argument from which the
8593
  iterator was constructed with filename of the directory entry appended
8594
  as if by `operator/=`.
8595
 
8596
  Directory iteration shall not yield directory entries for the current
8597
- (*dot*) and parent (*dot-dot*) directories.
8598
 
8599
  The order of directory entries obtained by dereferencing successive
8600
  increments of a `directory_iterator` is unspecified.
8601
 
8602
  Constructors and non-const `directory_iterator` member functions store
8603
- the values of any cached attributes ([[fs.class.directory_entry]]) in
8604
- the `directory_entry` element returned by `operator*()`.
8605
  `directory_iterator` member functions shall not directly or indirectly
8606
  call any `directory_entry` `refresh` function.
8607
 
8608
  [*Note 2*: The exact mechanism for storing cached attribute values is
8609
  not exposed to users. For exposition, class `directory_iterator` is
8610
- shown in [[fs.class.directory_entry]] as a friend of class
8611
  `directory_entry`. — *end note*]
8612
 
8613
  [*Note 3*: Programs performing directory iteration may wish to test if
8614
  the path obtained by dereferencing a directory iterator actually exists.
8615
  It could be a symbolic link to a non-existent file. Programs recursively
@@ -8620,23 +9454,23 @@ may wish to avoid following symbolic links. — *end note*]
8620
  construction of a `directory_iterator` for the directory, it is
8621
  unspecified whether or not subsequently incrementing the iterator will
8622
  ever result in an iterator referencing the removed or added directory
8623
  entry. See POSIX `readdir_r`. — *end note*]
8624
 
8625
- #### `directory_iterator` members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
8626
 
8627
  ``` cpp
8628
  directory_iterator() noexcept;
8629
  ```
8630
 
8631
  *Effects:* Constructs the end iterator.
8632
 
8633
  ``` cpp
8634
  explicit directory_iterator(const path& p);
8635
  directory_iterator(const path& p, directory_options options);
8636
- directory_iterator(const path& p, error_code& ec) noexcept;
8637
- directory_iterator(const path& p, directory_options options, error_code& ec) noexcept;
8638
  ```
8639
 
8640
  *Effects:* For the directory that `p` resolves to, constructs an
8641
  iterator for the first element in a sequence of `directory_entry`
8642
  elements representing the files in the directory, if any; otherwise the
@@ -8659,39 +9493,37 @@ error.
8659
  ``` cpp
8660
  directory_iterator(const directory_iterator& rhs);
8661
  directory_iterator(directory_iterator&& rhs) noexcept;
8662
  ```
8663
 
8664
- *Effects:* Constructs an object of class `directory_iterator`.
8665
-
8666
- *Postconditions:* `*this` has the original value of `rhs`.
8667
 
8668
  ``` cpp
8669
  directory_iterator& operator=(const directory_iterator& rhs);
8670
  directory_iterator& operator=(directory_iterator&& rhs) noexcept;
8671
  ```
8672
 
8673
  *Effects:* If `*this` and `rhs` are the same object, the member has no
8674
  effect.
8675
 
8676
- *Postconditions:* `*this` has the original value of `rhs`.
8677
 
8678
  *Returns:* `*this`.
8679
 
8680
  ``` cpp
8681
  directory_iterator& operator++();
8682
- directory_iterator& increment(error_code& ec) noexcept;
8683
  ```
8684
 
8685
  *Effects:* As specified for the prefix increment operation of Input
8686
- iterators ([[input.iterators]]).
8687
 
8688
  *Returns:* `*this`.
8689
 
8690
  *Throws:* As specified in  [[fs.err.report]].
8691
 
8692
- #### `directory_iterator` non-member functions <a id="fs.dir.itr.nonmembers">[[fs.dir.itr.nonmembers]]</a>
8693
 
8694
  These functions enable range access for `directory_iterator`.
8695
 
8696
  ``` cpp
8697
  directory_iterator begin(directory_iterator iter) noexcept;
@@ -8725,12 +9557,12 @@ namespace std::filesystem {
8725
  // [fs.rec.dir.itr.members], constructors and destructor
8726
  recursive_directory_iterator() noexcept;
8727
  explicit recursive_directory_iterator(const path& p);
8728
  recursive_directory_iterator(const path& p, directory_options options);
8729
  recursive_directory_iterator(const path& p, directory_options options,
8730
- error_code& ec) noexcept;
8731
- recursive_directory_iterator(const path& p, error_code& ec) noexcept;
8732
  recursive_directory_iterator(const recursive_directory_iterator& rhs);
8733
  recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
8734
  ~recursive_directory_iterator();
8735
 
8736
  // [fs.rec.dir.itr.members], observers
@@ -8746,11 +9578,11 @@ namespace std::filesystem {
8746
  operator=(const recursive_directory_iterator& rhs);
8747
  recursive_directory_iterator&
8748
  operator=(recursive_directory_iterator&& rhs) noexcept;
8749
 
8750
  recursive_directory_iterator& operator++();
8751
- recursive_directory_iterator& increment(error_code& ec) noexcept;
8752
 
8753
  void pop();
8754
  void pop(error_code& ec);
8755
  void disable_recursion_pending();
8756
 
@@ -8767,38 +9599,38 @@ The behavior of a `recursive_directory_iterator` is the same as a
8767
  `directory_iterator` unless otherwise specified.
8768
 
8769
  [*Note 1*: If the directory structure being iterated over contains
8770
  cycles then the end iterator may be unreachable. — *end note*]
8771
 
8772
- #### `recursive_directory_iterator` members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
8773
 
8774
  ``` cpp
8775
  recursive_directory_iterator() noexcept;
8776
  ```
8777
 
8778
  *Effects:* Constructs the end iterator.
8779
 
8780
  ``` cpp
8781
  explicit recursive_directory_iterator(const path& p);
8782
  recursive_directory_iterator(const path& p, directory_options options);
8783
- recursive_directory_iterator(const path& p, directory_options options, error_code& ec) noexcept;
8784
- recursive_directory_iterator(const path& p, error_code& ec) noexcept;
8785
  ```
8786
 
8787
- *Effects:* Constructs a iterator representing the first entry in the
8788
- directory `p` resolves to, if any; otherwise, the end iterator. However,
8789
- if
8790
 
8791
  ``` cpp
8792
  (options & directory_options::skip_permission_denied) != directory_options::none
8793
  ```
8794
 
8795
  and construction encounters an error indicating that permission to
8796
  access `p` is denied, constructs the end iterator and does not report an
8797
  error.
8798
 
8799
- *Postconditions:* `options() == options` for the signatures with a
8800
  `directory_options` argument, otherwise
8801
  `options() == directory_options::none`.
8802
 
8803
  *Throws:* As specified in  [[fs.err.report]].
8804
 
@@ -8806,42 +9638,38 @@ error.
8806
  `recursive_directory_iterator(".")` rather than
8807
  `recursive_directory_iterator("")`. — *end note*]
8808
 
8809
  [*Note 2*: By default, `recursive_directory_iterator` does not follow
8810
  directory symlinks. To follow directory symlinks, specify `options` as
8811
- `directory_options::follow_directory_symlink` — *end note*]
8812
 
8813
  ``` cpp
8814
  recursive_directory_iterator(const recursive_directory_iterator& rhs);
8815
  ```
8816
 
8817
- *Effects:* Constructs an object of class `recursive_directory_iterator`.
8818
-
8819
- *Postconditions:*
8820
 
8821
  - `options() == rhs.options()`
8822
  - `depth() == rhs.depth()`
8823
  - `recursion_pending() == rhs.recursion_pending()`
8824
 
8825
  ``` cpp
8826
  recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
8827
  ```
8828
 
8829
- *Effects:* Constructs an object of class `recursive_directory_iterator`.
8830
-
8831
- *Postconditions:* `options()`, `depth()`, and `recursion_pending()` have
8832
- the values that `rhs.options()`, `rhs.depth()`, and
8833
  `rhs.recursion_pending()`, respectively, had before the function call.
8834
 
8835
  ``` cpp
8836
  recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
8837
  ```
8838
 
8839
  *Effects:* If `*this` and `rhs` are the same object, the member has no
8840
  effect.
8841
 
8842
- *Postconditions:*
8843
 
8844
  - `options() == rhs.options()`
8845
  - `depth() == rhs.depth()`
8846
  - `recursion_pending() == rhs.recursion_pending()`
8847
 
@@ -8852,12 +9680,12 @@ recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noex
8852
  ```
8853
 
8854
  *Effects:* If `*this` and `rhs` are the same object, the member has no
8855
  effect.
8856
 
8857
- *Postconditions:* `options()`, `depth()`, and `recursion_pending()` have
8858
- the values that `rhs.options()`, `rhs.depth()`, and
8859
  `rhs.recursion_pending()`, respectively, had before the function call.
8860
 
8861
  *Returns:* `*this`.
8862
 
8863
  ``` cpp
@@ -8890,15 +9718,15 @@ subsequent to the prior construction or increment operation, otherwise
8890
 
8891
  *Throws:* Nothing.
8892
 
8893
  ``` cpp
8894
  recursive_directory_iterator& operator++();
8895
- recursive_directory_iterator& increment(error_code& ec) noexcept;
8896
  ```
8897
 
8898
  *Effects:* As specified for the prefix increment operation of Input
8899
- iterators ([[input.iterators]]), except that:
8900
 
8901
  - If there are no more entries at the current depth, then if
8902
  `depth() != 0` iteration over the parent directory resumes; otherwise
8903
  `*this = recursive_directory_iterator()`.
8904
  - Otherwise if
@@ -8932,20 +9760,23 @@ void pop(error_code& ec);
8932
  directory currently being iterated over, and continue iteration over the
8933
  parent directory.
8934
 
8935
  *Throws:* As specified in  [[fs.err.report]].
8936
 
 
 
 
8937
  ``` cpp
8938
  void disable_recursion_pending();
8939
  ```
8940
 
8941
- *Postconditions:* `recursion_pending() == false`.
8942
 
8943
  [*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
8944
  recursion into a directory. — *end note*]
8945
 
8946
- #### `recursive_directory_iterator` non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
8947
 
8948
  These functions enable use of `recursive_directory_iterator` with
8949
  range-based for statements.
8950
 
8951
  ``` cpp
@@ -8964,11 +9795,11 @@ recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
8964
 
8965
  Filesystem operation functions query or modify files, including
8966
  directories, in external storage.
8967
 
8968
  [*Note 1*: Because hardware failures, network failures, file system
8969
- races ([[fs.def.race]]), and many other kinds of errors occur
8970
  frequently in file system operations, users should be aware that any
8971
  filesystem operation function, no matter how apparently innocuous, may
8972
  encounter an error; see  [[fs.err.report]]. — *end note*]
8973
 
8974
  #### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
@@ -8977,11 +9808,11 @@ encounter an error; see  [[fs.err.report]]. — *end note*]
8977
  path absolute(const path& p);
8978
  path absolute(const path& p, error_code& ec);
8979
  ```
8980
 
8981
  *Effects:* Composes an absolute path referencing the same file system
8982
- location as `p` according to the operating system ([[fs.conform.os]]).
8983
 
8984
  *Returns:* The composed path. The signature with argument `ec` returns
8985
  `path()` if an error occurs.
8986
 
8987
  [*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
@@ -8989,11 +9820,11 @@ unless an error occurs. — *end note*]
8989
 
8990
  *Throws:* As specified in  [[fs.err.report]].
8991
 
8992
  [*Note 2*: To resolve symlinks, or perform other sanitization which
8993
  might require queries to secondary storage, such as hard disks, consider
8994
- `canonical` ([[fs.op.canonical]]). — *end note*]
8995
 
8996
  [*Note 3*: Implementations are strongly encouraged to not query
8997
  secondary storage, and not consider `!exists(p)` an
8998
  error. — *end note*]
8999
 
@@ -9003,22 +9834,19 @@ simply `current_path()/p`. For Windows-based operating systems,
9003
  `GetFullPathNameW`. — *end example*]
9004
 
9005
  #### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
9006
 
9007
  ``` cpp
9008
- path canonical(const path& p, const path& base = current_path());
9009
  path canonical(const path& p, error_code& ec);
9010
- path canonical(const path& p, const path& base, error_code& ec);
9011
  ```
9012
 
9013
- *Effects:* Converts `p`, which must exist, to an absolute path that has
9014
- no symbolic link, *dot*, or *dot-dot* elements in its pathname in the
9015
- generic format.
9016
 
9017
  *Returns:* A path that refers to the same file system object as
9018
- `absolute(p, base)`. For the overload without a `base` argument, `base`
9019
- is `current_path()`. Signatures with argument `ec` return `path()` if an
9020
  error occurs.
9021
 
9022
  *Throws:* As specified in  [[fs.err.report]].
9023
 
9024
  *Remarks:* `!exists(p)` is an error.
@@ -9030,23 +9858,23 @@ void copy(const path& from, const path& to);
9030
  ```
9031
 
9032
  *Effects:* Equivalent to `copy(from, to, copy_options::none)`.
9033
 
9034
  ``` cpp
9035
- void copy(const path& from, const path& to, error_code& ec) noexcept;
9036
  ```
9037
 
9038
  *Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
9039
 
9040
  ``` cpp
9041
  void copy(const path& from, const path& to, copy_options options);
9042
  void copy(const path& from, const path& to, copy_options options,
9043
- error_code& ec) noexcept;
9044
  ```
9045
 
9046
- *Requires:* At most one element from each option group
9047
- ([[fs.enum.copy.opts]]) is set in `options`.
9048
 
9049
  *Effects:* Before the first use of `f` and `t`:
9050
 
9051
  - If
9052
  ``` cpp
@@ -9067,17 +9895,17 @@ void copy(const path& from, const path& to, copy_options options,
9067
  `auto t = status(to)`.
9068
 
9069
  Effects are then as follows:
9070
 
9071
  - If `f.type()` or `t.type()` is an implementation-defined file
9072
- type ([[fs.enum.file_type]]), then the effects are
9073
  *implementation-defined*.
9074
  - Otherwise, an error is reported as specified in  [[fs.err.report]] if:
9075
- - `!exists(f)`, or
9076
- - `equivalent(from, to)`, or
9077
- - `is_other(f) || is_other(t)`, or
9078
- - `is_directory(f) && is_regular_file(t)`.
9079
  - Otherwise, if `is_symlink(f)`, then:
9080
  - If `(options & copy_options::skip_symlinks) != copy_options::none`
9081
  then return.
9082
  - Otherwise if
9083
  ``` cpp
@@ -9097,24 +9925,36 @@ Effects are then as follows:
9097
  `(options & copy_options::create_hard_links) != copy_options::none`,
9098
  then create a hard link to the source file.
9099
  - Otherwise, if `is_directory(t)`, then
9100
  `copy_file(from, to/from.filename(), options)`.
9101
  - Otherwise, `copy_file(from, to, options)`.
 
 
 
 
 
 
 
 
9102
  - Otherwise, if
9103
  ``` cpp
9104
  is_directory(f) &&
9105
  ((options & copy_options::recursive) != copy_options::none ||
9106
  options == copy_options::none)
9107
  ```
9108
 
9109
  then:
9110
- - If `!exists(t)`, then `create_directory(to, from)`.
9111
  - Then, iterate over the files in `from`, as if by
9112
  ``` cpp
9113
  for (const directory_entry& x : directory_iterator(from))
9114
- copy(x.path(), to/x.path().filename(), options | copy_options::unspecified)
 
9115
  ```
 
 
 
9116
  - Otherwise, for the signature with argument `ec`, `ec.clear()`.
9117
  - Otherwise, no effects.
9118
 
9119
  *Throws:* As specified in  [[fs.err.report]].
9120
 
@@ -9163,62 +10003,61 @@ would result in:
9163
  file3
9164
  ```
9165
 
9166
  — *end example*]
9167
 
9168
- #### Copy file <a id="fs.op.copy_file">[[fs.op.copy_file]]</a>
9169
 
9170
  ``` cpp
9171
  bool copy_file(const path& from, const path& to);
9172
- bool copy_file(const path& from, const path& to, error_code& ec) noexcept;
9173
  ```
9174
 
9175
  *Returns:* `copy_file(from, to, copy_options::none)` or
9176
  `copy_file(from, to, copy_options::none, ec)`, respectively.
9177
 
9178
  *Throws:* As specified in  [[fs.err.report]].
9179
 
9180
  ``` cpp
9181
  bool copy_file(const path& from, const path& to, copy_options options);
9182
  bool copy_file(const path& from, const path& to, copy_options options,
9183
- error_code& ec) noexcept;
9184
  ```
9185
 
9186
- *Requires:* At most one element from each option group
9187
- ([[fs.enum.copy.opts]]) is set in `options`.
9188
 
9189
  *Effects:* As follows:
9190
 
9191
- - Report a file already exists error as specified in  [[fs.err.report]]
9192
- if:
9193
- - `!is_regular_file(from)`, or
9194
- - `exists(to)` and `!is_regular_file(to)`, or
9195
- - `exists(to)` and `equivalent(from, to)`, or
9196
- - `exists(to)` and
9197
  ``` cpp
9198
  (options & (copy_options::skip_existing |
9199
  copy_options::overwrite_existing |
9200
  copy_options::update_existing)) == copy_options::none
9201
  ```
9202
  - Otherwise, copy the contents and attributes of the file `from`
9203
  resolves to, to the file `to` resolves to, if:
9204
- - `!exists(to)`, or
9205
  - `(options & copy_options::overwrite_existing) != copy_options::none`,
9206
  or
9207
  - `(options & copy_options::update_existing) `` `` != copy_options::none`
9208
  and `from` is more recent than `to`, determined as if by use of the
9209
- `last_write_time` function ([[fs.op.last_write_time]]).
9210
  - Otherwise, no effects.
9211
 
9212
  *Returns:* `true` if the `from` file was copied, otherwise `false`. The
9213
  signature with argument `ec` returns `false` if an error occurs.
9214
 
9215
  *Throws:* As specified in  [[fs.err.report]].
9216
 
9217
  *Complexity:* At most one direct or indirect invocation of `status(to)`.
9218
 
9219
- #### Copy symlink <a id="fs.op.copy_symlink">[[fs.op.copy_symlink]]</a>
9220
 
9221
  ``` cpp
9222
  void copy_symlink(const path& existing_symlink, const path& new_symlink);
9223
  void copy_symlink(const path& existing_symlink, const path& new_symlink,
9224
  error_code& ec) noexcept;
@@ -9230,86 +10069,78 @@ void copy_symlink(const path& existing_symlink, const path& new_symlink,
9230
  respectively, where in each case *`function`* is `create_symlink` or
9231
  `create_directory_symlink` as appropriate.
9232
 
9233
  *Throws:* As specified in  [[fs.err.report]].
9234
 
9235
- #### Create directories <a id="fs.op.create_directories">[[fs.op.create_directories]]</a>
9236
 
9237
  ``` cpp
9238
  bool create_directories(const path& p);
9239
- bool create_directories(const path& p, error_code& ec) noexcept;
9240
  ```
9241
 
9242
- *Effects:* Establishes the postcondition by calling `create_directory()`
9243
- for any element of `p` that does not exist.
9244
-
9245
- *Postconditions:* `is_directory(p)`.
9246
-
9247
- *Returns:* `true` if a new directory was created, otherwise `false`. The
9248
- signature with argument `ec` returns `false` if an error occurs.
9249
-
9250
- *Throws:* As specified in  [[fs.err.report]].
9251
-
9252
- *Complexity:* 𝑂(n) where *n* is the number of elements of `p` that do
9253
  not exist.
9254
 
9255
- #### Create directory <a id="fs.op.create_directory">[[fs.op.create_directory]]</a>
 
 
 
 
 
 
 
9256
 
9257
  ``` cpp
9258
  bool create_directory(const path& p);
9259
  bool create_directory(const path& p, error_code& ec) noexcept;
9260
  ```
9261
 
9262
- *Effects:* Establishes the postcondition by attempting to create the
9263
- directory `p` resolves to, as if by POSIX `mkdir()` with a second
9264
- argument of `static_cast<int>(perms::all)`. Creation failure because `p`
9265
- resolves to an existing directory shall not be treated as an error.
9266
 
9267
- *Postconditions:* `is_directory(p)`.
9268
-
9269
- *Returns:* `true` if a new directory was created, otherwise `false`. The
9270
- signature with argument `ec` returns `false` if an error occurs.
9271
 
9272
  *Throws:* As specified in  [[fs.err.report]].
9273
 
9274
  ``` cpp
9275
  bool create_directory(const path& p, const path& existing_p);
9276
  bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
9277
  ```
9278
 
9279
- *Effects:* Establishes the postcondition by attempting to create the
9280
- directory `p` resolves to, with attributes copied from directory
9281
- `existing_p`. The set of attributes copied is operating system
9282
- dependent. Creation failure because `p` resolves to an existing
9283
- directory shall not be treated as an error.
9284
 
9285
  [*Note 1*: For POSIX-based operating systems, the attributes are those
9286
  copied by native API `stat(existing_p.c_str(), &attributes_stat)`
9287
  followed by `mkdir(p.c_str(), attributes_stat.st_mode)`. For
9288
  Windows-based operating systems, the attributes are those copied by
9289
  native API
9290
  `CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0)`. — *end note*]
9291
 
9292
- *Postconditions:* `is_directory(p)`.
9293
-
9294
- *Returns:* `true` if a new directory was created, otherwise `false`. The
9295
- signature with argument `ec` returns `false` if an error occurs.
9296
 
9297
  *Throws:* As specified in  [[fs.err.report]].
9298
 
9299
- #### Create directory symlink <a id="fs.op.create_dir_symlk">[[fs.op.create_dir_symlk]]</a>
9300
 
9301
  ``` cpp
9302
  void create_directory_symlink(const path& to, const path& new_symlink);
9303
  void create_directory_symlink(const path& to, const path& new_symlink,
9304
  error_code& ec) noexcept;
9305
  ```
9306
 
9307
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
9308
 
9309
- *Postconditions:* `new_symlink` resolves to a symbolic link file that
9310
- contains an unspecified representation of `to`.
9311
 
9312
  *Throws:* As specified in  [[fs.err.report]].
9313
 
9314
  [*Note 1*: Some operating systems require symlink creation to identify
9315
  that the link is to a directory. Portable code should use
@@ -9319,21 +10150,21 @@ that the link is to a directory. Portable code should use
9319
  [*Note 2*: Some operating systems do not support symbolic links at all
9320
  or support them only for regular files. Some file systems (such as the
9321
  FAT file system) do not support symbolic links regardless of the
9322
  operating system. — *end note*]
9323
 
9324
- #### Create hard link <a id="fs.op.create_hard_lk">[[fs.op.create_hard_lk]]</a>
9325
 
9326
  ``` cpp
9327
  void create_hard_link(const path& to, const path& new_hard_link);
9328
  void create_hard_link(const path& to, const path& new_hard_link,
9329
  error_code& ec) noexcept;
9330
  ```
9331
 
9332
  *Effects:* Establishes the postcondition, as if by POSIX `link()`.
9333
 
9334
- *Postconditions:*
9335
 
9336
  - `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
9337
  - The contents of the file or directory `to` resolves to are unchanged.
9338
 
9339
  *Throws:* As specified in  [[fs.err.report]].
@@ -9342,31 +10173,31 @@ void create_hard_link(const path& to, const path& new_hard_link,
9342
  support them only for regular files. Some file systems (such as the FAT
9343
  file system) do not support hard links regardless of the operating
9344
  system. Some file systems limit the number of links per
9345
  file. — *end note*]
9346
 
9347
- #### Create symlink <a id="fs.op.create_symlink">[[fs.op.create_symlink]]</a>
9348
 
9349
  ``` cpp
9350
  void create_symlink(const path& to, const path& new_symlink);
9351
  void create_symlink(const path& to, const path& new_symlink,
9352
  error_code& ec) noexcept;
9353
  ```
9354
 
9355
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
9356
 
9357
- *Postconditions:* `new_symlink` resolves to a symbolic link file that
9358
- contains an unspecified representation of `to`.
9359
 
9360
  *Throws:* As specified in  [[fs.err.report]].
9361
 
9362
  [*Note 1*: Some operating systems do not support symbolic links at all
9363
  or support them only for regular files. Some file systems (such as the
9364
  FAT file system) do not support symbolic links regardless of the
9365
  operating system. — *end note*]
9366
 
9367
- #### Current path <a id="fs.op.current_path">[[fs.op.current_path]]</a>
9368
 
9369
  ``` cpp
9370
  path current_path();
9371
  path current_path(error_code& ec);
9372
  ```
@@ -9384,22 +10215,21 @@ resolution for relative paths.
9384
  [*Note 1*: The `current_path()` name was chosen to emphasize that the
9385
  returned value is a path, not just a single directory
9386
  name. — *end note*]
9387
 
9388
  [*Note 2*: The current path as returned by many operating systems is a
9389
- dangerous global variable. It may be changed unexpectedly by a
9390
- third-party or system library functions, or by another
9391
- thread. — *end note*]
9392
 
9393
  ``` cpp
9394
  void current_path(const path& p);
9395
  void current_path(const path& p, error_code& ec) noexcept;
9396
  ```
9397
 
9398
  *Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
9399
 
9400
- *Postconditions:* `equivalent(p, current_path())`.
9401
 
9402
  *Throws:* As specified in  [[fs.err.report]].
9403
 
9404
  [*Note 3*: The current path for many operating systems is a dangerous
9405
  global state. It may be changed unexpectedly by a third-party or system
@@ -9410,26 +10240,22 @@ library functions, or by another thread. — *end note*]
9410
  ``` cpp
9411
  bool equivalent(const path& p1, const path& p2);
9412
  bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
9413
  ```
9414
 
9415
- Let `s1` and `s2` be `file_status`s, determined as if by `status(p1)`
9416
- and `status(p2)`, respectively.
9417
-
9418
- *Effects:* Determines `s1` and `s2`. If
9419
- `(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))` an
9420
- error is reported ([[fs.err.report]]).
9421
-
9422
- *Returns:* `true`, if `s1 == s2` and `p1` and `p2` resolve to the same
9423
- file system entity, else `false`. The signature with argument `ec`
9424
- returns `false` if an error occurs.
9425
 
9426
  Two paths are considered to resolve to the same file system entity if
9427
  two candidate entities reside on the same device at the same location.
9428
- This is determined as if by the values of the POSIX `stat` structure,
9429
- obtained as if by `stat()` for the two paths, having equal `st_dev`
9430
- values and equal `st_ino` values.
 
 
 
9431
 
9432
  *Throws:* As specified in  [[fs.err.report]].
9433
 
9434
  #### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
9435
 
@@ -9452,31 +10278,33 @@ Let `s` be a `file_status`, determined as if by `status(p)` or
9452
 
9453
  *Returns:* `exists(s)`.
9454
 
9455
  *Throws:* As specified in  [[fs.err.report]].
9456
 
9457
- #### File size <a id="fs.op.file_size">[[fs.op.file_size]]</a>
9458
 
9459
  ``` cpp
9460
  uintmax_t file_size(const path& p);
9461
  uintmax_t file_size(const path& p, error_code& ec) noexcept;
9462
  ```
9463
 
 
 
 
9464
  *Returns:*
9465
 
9466
- - If `!exists(p)` an error is reported ([[fs.err.report]]).
9467
- - Otherwise, if `is_regular_file(p)`, the size in bytes of the file `p`
9468
- resolves to, determined as if by the value of the POSIX `stat`
9469
- structure member `st_size` obtained as if by POSIX `stat()`.
9470
  - Otherwise, the result is *implementation-defined*.
9471
 
9472
  The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
9473
  an error occurs.
9474
 
9475
  *Throws:* As specified in  [[fs.err.report]].
9476
 
9477
- #### Hard link count <a id="fs.op.hard_lk_ct">[[fs.op.hard_lk_ct]]</a>
9478
 
9479
  ``` cpp
9480
  uintmax_t hard_link_count(const path& p);
9481
  uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
9482
  ```
@@ -9484,11 +10312,11 @@ uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
9484
  *Returns:* The number of hard links for `p`. The signature with argument
9485
  `ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
9486
 
9487
  *Throws:* As specified in  [[fs.err.report]].
9488
 
9489
- #### Is block file <a id="fs.op.is_block_file">[[fs.op.is_block_file]]</a>
9490
 
9491
  ``` cpp
9492
  bool is_block_file(file_status s) noexcept;
9493
  ```
9494
 
@@ -9503,11 +10331,11 @@ bool is_block_file(const path& p, error_code& ec) noexcept;
9503
  respectively. The signature with argument `ec` returns `false` if an
9504
  error occurs.
9505
 
9506
  *Throws:* As specified in  [[fs.err.report]].
9507
 
9508
- #### Is character file <a id="fs.op.is_char_file">[[fs.op.is_char_file]]</a>
9509
 
9510
  ``` cpp
9511
  bool is_character_file(file_status s) noexcept;
9512
  ```
9513
 
@@ -9522,11 +10350,11 @@ bool is_character_file(const path& p, error_code& ec) noexcept;
9522
  `is_character_file(status(p, ec))`, respectively.
9523
  The signature with argument `ec` returns `false` if an error occurs.
9524
 
9525
  *Throws:* As specified in  [[fs.err.report]].
9526
 
9527
- #### Is directory <a id="fs.op.is_directory">[[fs.op.is_directory]]</a>
9528
 
9529
  ``` cpp
9530
  bool is_directory(file_status s) noexcept;
9531
  ```
9532
 
@@ -9541,15 +10369,15 @@ bool is_directory(const path& p, error_code& ec) noexcept;
9541
  respectively. The signature with argument `ec` returns `false` if an
9542
  error occurs.
9543
 
9544
  *Throws:* As specified in  [[fs.err.report]].
9545
 
9546
- #### Is empty <a id="fs.op.is_empty">[[fs.op.is_empty]]</a>
9547
 
9548
  ``` cpp
9549
  bool is_empty(const path& p);
9550
- bool is_empty(const path& p, error_code& ec) noexcept;
9551
  ```
9552
 
9553
  *Effects:*
9554
 
9555
  - Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
@@ -9569,11 +10397,11 @@ bool is_empty(const path& p, error_code& ec) noexcept;
9569
  occurred.
9570
  - Otherwise, return `sz == 0`.
9571
 
9572
  *Throws:* As specified in  [[fs.err.report]].
9573
 
9574
- #### Is fifo <a id="fs.op.is_fifo">[[fs.op.is_fifo]]</a>
9575
 
9576
  ``` cpp
9577
  bool is_fifo(file_status s) noexcept;
9578
  ```
9579
 
@@ -9588,11 +10416,11 @@ bool is_fifo(const path& p, error_code& ec) noexcept;
9588
  respectively. The signature with argument `ec` returns `false` if an
9589
  error occurs.
9590
 
9591
  *Throws:* As specified in  [[fs.err.report]].
9592
 
9593
- #### Is other <a id="fs.op.is_other">[[fs.op.is_other]]</a>
9594
 
9595
  ``` cpp
9596
  bool is_other(file_status s) noexcept;
9597
  ```
9598
 
@@ -9608,11 +10436,11 @@ bool is_other(const path& p, error_code& ec) noexcept;
9608
  respectively. The signature with argument `ec` returns `false` if an
9609
  error occurs.
9610
 
9611
  *Throws:* As specified in  [[fs.err.report]].
9612
 
9613
- #### Is regular file <a id="fs.op.is_regular_file">[[fs.op.is_regular_file]]</a>
9614
 
9615
  ``` cpp
9616
  bool is_regular_file(file_status s) noexcept;
9617
  ```
9618
 
@@ -9623,11 +10451,11 @@ bool is_regular_file(const path& p);
9623
  ```
9624
 
9625
  *Returns:* `is_regular_file(status(p))`.
9626
 
9627
  *Throws:* `filesystem_error` if `status(p)` would throw
9628
- `filesystem_error.`
9629
 
9630
  ``` cpp
9631
  bool is_regular_file(const path& p, error_code& ec) noexcept;
9632
  ```
9633
 
@@ -9638,11 +10466,11 @@ bool is_regular_file(const path& p, error_code& ec) noexcept;
9638
  between cases, call the `status` function directly. — *end note*]
9639
 
9640
  *Returns:* `is_regular_file(status(p, ec))`. Returns `false` if an error
9641
  occurs.
9642
 
9643
- #### Is socket <a id="fs.op.is_socket">[[fs.op.is_socket]]</a>
9644
 
9645
  ``` cpp
9646
  bool is_socket(file_status s) noexcept;
9647
  ```
9648
 
@@ -9657,11 +10485,11 @@ bool is_socket(const path& p, error_code& ec) noexcept;
9657
  respectively. The signature with argument `ec` returns `false` if an
9658
  error occurs.
9659
 
9660
  *Throws:* As specified in  [[fs.err.report]].
9661
 
9662
- #### Is symlink <a id="fs.op.is_symlink">[[fs.op.is_symlink]]</a>
9663
 
9664
  ``` cpp
9665
  bool is_symlink(file_status s) noexcept;
9666
  ```
9667
 
@@ -9676,20 +10504,20 @@ bool is_symlink(const path& p, error_code& ec) noexcept;
9676
  `is_symlink(symlink_status(p, ec))`, respectively. The signature with
9677
  argument `ec` returns `false` if an error occurs.
9678
 
9679
  *Throws:* As specified in  [[fs.err.report]].
9680
 
9681
- #### Last write time <a id="fs.op.last_write_time">[[fs.op.last_write_time]]</a>
9682
 
9683
  ``` cpp
9684
  file_time_type last_write_time(const path& p);
9685
  file_time_type last_write_time(const path& p, error_code& ec) noexcept;
9686
  ```
9687
 
9688
  *Returns:* The time of last data modification of `p`, determined as if
9689
- by the value of the POSIX `stat` structure member `st_mtime` obtained as
9690
- if by POSIX `stat()`. The signature with argument `ec` returns
9691
  `file_time_type::min()` if an error occurs.
9692
 
9693
  *Throws:* As specified in  [[fs.err.report]].
9694
 
9695
  ``` cpp
@@ -9713,11 +10541,11 @@ granularity. — *end note*]
9713
  void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
9714
  void permissions(const path& p, perms prms, error_code& ec) noexcept;
9715
  void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
9716
  ```
9717
 
9718
- *Requires:* Exactly one of the `perm_options` constants `replace`,
9719
  `add`, or `remove` is present in `opts`.
9720
 
9721
  *Remarks:* The second signature behaves as if it had an additional
9722
  parameter `perm_options` `opts` with an argument of
9723
  `perm_options::replace`.
@@ -9761,11 +10589,11 @@ weakly_canonical(p, ec).lexically_proximate(weakly_canonical(base, ec));
9761
 
9762
  or `path()` at the first error occurrence, if any.
9763
 
9764
  *Throws:* As specified in  [[fs.err.report]].
9765
 
9766
- #### Read symlink <a id="fs.op.read_symlink">[[fs.op.read_symlink]]</a>
9767
 
9768
  ``` cpp
9769
  path read_symlink(const path& p);
9770
  path read_symlink(const path& p, error_code& ec);
9771
  ```
@@ -9821,31 +10649,31 @@ bool remove(const path& p, error_code& ec) noexcept;
9821
  as if by POSIX `remove()`.
9822
 
9823
  [*Note 1*: A symbolic link is itself removed, rather than the file it
9824
  resolves to. — *end note*]
9825
 
9826
- *Postconditions:* `!exists(symlink_status(p))`.
9827
 
9828
  *Returns:* `false` if `p` did not exist, otherwise `true`. The signature
9829
  with argument `ec` returns `false` if an error occurs.
9830
 
9831
  *Throws:* As specified in  [[fs.err.report]].
9832
 
9833
- #### Remove all <a id="fs.op.remove_all">[[fs.op.remove_all]]</a>
9834
 
9835
  ``` cpp
9836
  uintmax_t remove_all(const path& p);
9837
- uintmax_t remove_all(const path& p, error_code& ec) noexcept;
9838
  ```
9839
 
9840
  *Effects:* Recursively deletes the contents of `p` if it exists, then
9841
  deletes file `p` itself, as if by POSIX `remove()`.
9842
 
9843
  [*Note 1*: A symbolic link is itself removed, rather than the file it
9844
  resolves to. — *end note*]
9845
 
9846
- *Postconditions:* `!exists(symlink_status(p))`.
9847
 
9848
  *Returns:* The number of files removed. The signature with argument `ec`
9849
  returns `static_cast< uintmax_t>(-1)` if an error occurs.
9850
 
9851
  *Throws:* As specified in  [[fs.err.report]].
@@ -9874,23 +10702,22 @@ A symbolic link is itself renamed, rather than the file it resolves to.
9874
 
9875
  — *end note*]
9876
 
9877
  *Throws:* As specified in  [[fs.err.report]].
9878
 
9879
- #### Resize file <a id="fs.op.resize_file">[[fs.op.resize_file]]</a>
9880
 
9881
  ``` cpp
9882
  void resize_file(const path& p, uintmax_t new_size);
9883
  void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
9884
  ```
9885
 
9886
- *Postconditions:* `file_size(p) == new_size`.
 
9887
 
9888
  *Throws:* As specified in  [[fs.err.report]].
9889
 
9890
- *Remarks:* Achieves its postconditions as if by POSIX `truncate()`.
9891
-
9892
  #### Space <a id="fs.op.space">[[fs.op.space]]</a>
9893
 
9894
  ``` cpp
9895
  space_info space(const path& p);
9896
  space_info space(const path& p, error_code& ec) noexcept;
@@ -9989,27 +10816,27 @@ determined as if by converting the `st_mode` member of the obtained
9989
  - Otherwise, if the attributes indicate a fifo or pipe file, as if by
9990
  POSIX `S_ISFIFO`, returns `file_status(file_type::fifo, prms)`.
9991
  - Otherwise, if the attributes indicate a socket, as if by POSIX
9992
  `S_ISSOCK`, returns `file_status(file_type::socket, prms)`.
9993
  - Otherwise, if the attributes indicate an implementation-defined file
9994
- type ([[fs.enum.file_type]]), returns
9995
  `file_status(file_type::`*`A`*`, prms)`, where *A* is the constant
9996
  for the *implementation-defined* file type.
9997
  - Otherwise, returns `file_status(file_type::unknown, prms)`.
9998
 
9999
  *Remarks:* If a symbolic link is encountered during pathname resolution,
10000
  pathname resolution continues using the contents of the symbolic link.
10001
 
10002
- #### Status known <a id="fs.op.status_known">[[fs.op.status_known]]</a>
10003
 
10004
  ``` cpp
10005
  bool status_known(file_status s) noexcept;
10006
  ```
10007
 
10008
  *Returns:* `s.type() != file_type::none`.
10009
 
10010
- #### Symlink status <a id="fs.op.symlink_status">[[fs.op.symlink_status]]</a>
10011
 
10012
  ``` cpp
10013
  file_status symlink_status(const path& p);
10014
  file_status symlink_status(const path& p, error_code& ec) noexcept;
10015
  ```
@@ -10029,20 +10856,23 @@ indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
10029
 
10030
  *Remarks:* Pathname resolution terminates if `p` names a symbolic link.
10031
 
10032
  *Throws:* As specified in  [[fs.err.report]].
10033
 
10034
- #### Temporary directory path <a id="fs.op.temp_dir_path">[[fs.op.temp_dir_path]]</a>
10035
 
10036
  ``` cpp
10037
  path temp_directory_path();
10038
  path temp_directory_path(error_code& ec);
10039
  ```
10040
 
10041
- *Returns:* An unspecifed directory path suitable for temporary files. An
10042
- error shall be reported if `!exists(p) || !is_directory(p)`, where `p`
10043
- is the path to be returned. The signature with argument `ec` returns
 
 
 
10044
  `path()` if an error occurs.
10045
 
10046
  *Throws:* As specified in  [[fs.err.report]].
10047
 
10048
  [*Example 1*: For POSIX-based operating systems, an implementation
@@ -10050,36 +10880,33 @@ might return the path supplied by the first environment variable found
10050
  in the list TMPDIR, TMP, TEMP, TEMPDIR, or if none of these are found,
10051
  `"/tmp"`. For Windows-based operating systems, an implementation might
10052
  return the path reported by the Windows `GetTempPath` API
10053
  function. — *end example*]
10054
 
10055
- #### Weakly canonical <a id="fs.op.weakly_canonical">[[fs.op.weakly_canonical]]</a>
10056
 
10057
  ``` cpp
10058
  path weakly_canonical(const path& p);
10059
  path weakly_canonical(const path& p, error_code& ec);
10060
  ```
10061
 
10062
  *Returns:* `p` with symlinks resolved and the result
10063
- normalized ([[fs.def.normal.form]]).
10064
 
10065
  *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
10066
  determine existence, return a path composed by `operator/=` from the
10067
- result of calling `canonical()` without a `base` argument and with a
10068
- path argument composed of the leading elements of `p` that exist, if
10069
- any, followed by the elements of `p` that do not exist, if any. For the
10070
- first form, `canonical()` is called without an `error_code` argument.
10071
- For the second form, `canonical()` is called with `ec` as an
10072
- `error_code` argument, and `path()` is returned at the first error
10073
- occurrence, if any.
10074
 
10075
- *Postconditions:* The returned path is in normal
10076
- form ([[fs.def.normal.form]]).
10077
 
10078
- *Remarks:* Implementations are encouraged to avoid unnecessary
10079
- normalization such as when `canonical` has already been called on the
10080
- entirety of `p`.
10081
 
10082
  *Throws:* As specified in  [[fs.err.report]].
10083
 
10084
  ## C library files <a id="c.files">[[c.files]]</a>
10085
 
@@ -10109,11 +10936,11 @@ namespace std {
10109
  #define stdin see below
10110
  #define stdout see below
10111
 
10112
  namespace std {
10113
  int remove(const char* filename);
10114
- int rename(const char* old, const char* new);
10115
  FILE* tmpfile();
10116
  char* tmpnam(char* s);
10117
  int fclose(FILE* stream);
10118
  int fflush(FILE* stream);
10119
  FILE* fopen(const char* filename, const char* mode);
@@ -10160,14 +10987,14 @@ namespace std {
10160
 
10161
  The contents and meaning of the header `<cstdio>` are the same as the C
10162
  standard library header `<stdio.h>`.
10163
 
10164
  Calls to the function `tmpnam` with an argument that is a null pointer
10165
- value may introduce a data race ([[res.on.data.races]]) with other
10166
- calls to `tmpnam` with an argument that is a null pointer value.
10167
 
10168
- ISO C 7.21.
10169
 
10170
  ### Header `<cinttypes>` synopsis <a id="cinttypes.syn">[[cinttypes.syn]]</a>
10171
 
10172
  ``` cpp
10173
  #include <cstdint> // see [cstdint.syn]
@@ -10246,145 +11073,139 @@ namespace std {
10246
  The contents and meaning of the header `<cinttypes>` are the same as the
10247
  C standard library header `<inttypes.h>`, with the following changes:
10248
 
10249
  - The header `<cinttypes>` includes the header `<cstdint>` instead of
10250
  `<stdint.h>`, and
10251
- - if and only if the type `intmax_t` designates an extended integer
10252
- type ([[basic.fundamental]]), the following function signatures are
10253
- added:
10254
  ``` cpp
10255
  intmax_t abs(intmax_t);
10256
  imaxdiv_t div(intmax_t, intmax_t);
10257
  ```
10258
 
10259
  which shall have the same semantics as the function signatures
10260
  `intmax_t imaxabs(intmax_t)` and
10261
  `imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
10262
 
10263
- ISO C 7.8.
10264
 
10265
  <!-- Link reference definitions -->
10266
  [adjustfield.manip]: #adjustfield.manip
10267
- [allocator.requirements]: library.md#allocator.requirements
10268
  [basefield.manip]: #basefield.manip
10269
  [basic.fundamental]: basic.md#basic.fundamental
10270
  [basic.ios.cons]: #basic.ios.cons
 
10271
  [basic.ios.members]: #basic.ios.members
10272
  [basic.start.main]: basic.md#basic.start.main
10273
  [bidirectional.iterators]: iterators.md#bidirectional.iterators
10274
  [bitmask.types]: library.md#bitmask.types
10275
  [c.files]: #c.files
 
10276
  [cinttypes.syn]: #cinttypes.syn
 
 
 
 
 
 
 
10277
  [cstdio.syn]: #cstdio.syn
10278
  [defns.ntcts]: library.md#defns.ntcts
10279
  [enumerated.types]: library.md#enumerated.types
10280
  [error.reporting]: #error.reporting
10281
  [ext.manip]: #ext.manip
10282
- [fig:streampos]: #fig:streampos
10283
  [file.streams]: #file.streams
10284
  [filebuf]: #filebuf
10285
  [filebuf.assign]: #filebuf.assign
10286
  [filebuf.cons]: #filebuf.cons
10287
  [filebuf.members]: #filebuf.members
 
 
10288
  [filebuf.virtuals]: #filebuf.virtuals
10289
- [filesystem_error.members]: #filesystem_error.members
10290
  [filesystems]: #filesystems
10291
  [floatfield.manip]: #floatfield.manip
10292
  [fmtflags.manip]: #fmtflags.manip
10293
  [fmtflags.state]: #fmtflags.state
10294
  [fpos]: #fpos
10295
  [fpos.members]: #fpos.members
10296
  [fpos.operations]: #fpos.operations
10297
- [fs.class.directory_entry]: #fs.class.directory_entry
10298
- [fs.class.directory_iterator]: #fs.class.directory_iterator
10299
- [fs.class.file_status]: #fs.class.file_status
10300
- [fs.class.filesystem_error]: #fs.class.filesystem_error
10301
  [fs.class.path]: #fs.class.path
10302
  [fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
10303
  [fs.conform.9945]: #fs.conform.9945
10304
  [fs.conform.os]: #fs.conform.os
10305
  [fs.conformance]: #fs.conformance
10306
- [fs.def.absolute.path]: #fs.def.absolute.path
10307
- [fs.def.filename]: #fs.def.filename
10308
- [fs.def.link]: #fs.def.link
10309
- [fs.def.native]: #fs.def.native
10310
- [fs.def.native.encode]: #fs.def.native.encode
10311
- [fs.def.normal.form]: #fs.def.normal.form
10312
- [fs.def.osdep]: #fs.def.osdep
10313
- [fs.def.path]: #fs.def.path
10314
- [fs.def.pathname]: #fs.def.pathname
10315
- [fs.def.pathres]: #fs.def.pathres
10316
- [fs.def.race]: #fs.def.race
10317
- [fs.def.symlink]: #fs.def.symlink
10318
- [fs.definitions]: #fs.definitions
10319
  [fs.dir.entry.cons]: #fs.dir.entry.cons
10320
  [fs.dir.entry.mods]: #fs.dir.entry.mods
10321
  [fs.dir.entry.obs]: #fs.dir.entry.obs
10322
  [fs.dir.itr.members]: #fs.dir.itr.members
10323
  [fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
10324
  [fs.enum]: #fs.enum
10325
  [fs.enum.copy.opts]: #fs.enum.copy.opts
10326
  [fs.enum.dir.opts]: #fs.enum.dir.opts
10327
- [fs.enum.file_type]: #fs.enum.file_type
10328
  [fs.enum.path.format]: #fs.enum.path.format
10329
  [fs.enum.perm.opts]: #fs.enum.perm.opts
10330
  [fs.enum.perms]: #fs.enum.perms
10331
  [fs.err.report]: #fs.err.report
10332
- [fs.file_status.cons]: #fs.file_status.cons
10333
- [fs.file_status.mods]: #fs.file_status.mods
10334
- [fs.file_status.obs]: #fs.file_status.obs
 
10335
  [fs.filesystem.syn]: #fs.filesystem.syn
10336
  [fs.general]: #fs.general
10337
  [fs.norm.ref]: #fs.norm.ref
10338
  [fs.op.absolute]: #fs.op.absolute
10339
  [fs.op.canonical]: #fs.op.canonical
10340
  [fs.op.copy]: #fs.op.copy
10341
- [fs.op.copy_file]: #fs.op.copy_file
10342
- [fs.op.copy_symlink]: #fs.op.copy_symlink
10343
- [fs.op.create_dir_symlk]: #fs.op.create_dir_symlk
10344
- [fs.op.create_directories]: #fs.op.create_directories
10345
- [fs.op.create_directory]: #fs.op.create_directory
10346
- [fs.op.create_hard_lk]: #fs.op.create_hard_lk
10347
- [fs.op.create_symlink]: #fs.op.create_symlink
10348
- [fs.op.current_path]: #fs.op.current_path
10349
  [fs.op.equivalent]: #fs.op.equivalent
10350
  [fs.op.exists]: #fs.op.exists
10351
- [fs.op.file_size]: #fs.op.file_size
10352
  [fs.op.funcs]: #fs.op.funcs
10353
- [fs.op.hard_lk_ct]: #fs.op.hard_lk_ct
10354
- [fs.op.is_block_file]: #fs.op.is_block_file
10355
- [fs.op.is_char_file]: #fs.op.is_char_file
10356
- [fs.op.is_directory]: #fs.op.is_directory
10357
- [fs.op.is_empty]: #fs.op.is_empty
10358
- [fs.op.is_fifo]: #fs.op.is_fifo
10359
- [fs.op.is_other]: #fs.op.is_other
10360
- [fs.op.is_regular_file]: #fs.op.is_regular_file
10361
- [fs.op.is_socket]: #fs.op.is_socket
10362
- [fs.op.is_symlink]: #fs.op.is_symlink
10363
- [fs.op.last_write_time]: #fs.op.last_write_time
10364
  [fs.op.permissions]: #fs.op.permissions
10365
  [fs.op.proximate]: #fs.op.proximate
10366
- [fs.op.read_symlink]: #fs.op.read_symlink
10367
  [fs.op.relative]: #fs.op.relative
10368
  [fs.op.remove]: #fs.op.remove
10369
- [fs.op.remove_all]: #fs.op.remove_all
10370
  [fs.op.rename]: #fs.op.rename
10371
- [fs.op.resize_file]: #fs.op.resize_file
10372
  [fs.op.space]: #fs.op.space
10373
  [fs.op.status]: #fs.op.status
10374
- [fs.op.status_known]: #fs.op.status_known
10375
- [fs.op.symlink_status]: #fs.op.symlink_status
10376
- [fs.op.temp_dir_path]: #fs.op.temp_dir_path
10377
- [fs.op.weakly_canonical]: #fs.op.weakly_canonical
10378
  [fs.path.append]: #fs.path.append
10379
  [fs.path.assign]: #fs.path.assign
10380
  [fs.path.compare]: #fs.path.compare
10381
  [fs.path.concat]: #fs.path.concat
10382
  [fs.path.construct]: #fs.path.construct
10383
  [fs.path.cvt]: #fs.path.cvt
10384
  [fs.path.decompose]: #fs.path.decompose
10385
- [fs.path.factory]: #fs.path.factory
10386
  [fs.path.fmt.cvt]: #fs.path.fmt.cvt
10387
  [fs.path.gen]: #fs.path.gen
10388
  [fs.path.generic]: #fs.path.generic
10389
  [fs.path.generic.obs]: #fs.path.generic.obs
10390
  [fs.path.io]: #fs.path.io
@@ -10412,28 +11233,30 @@ ISO C 7.8.
10412
  [ifstream.members]: #ifstream.members
10413
  [input.iterators]: iterators.md#input.iterators
10414
  [input.output]: #input.output
10415
  [input.output.general]: #input.output.general
10416
  [input.streams]: #input.streams
10417
- [intro.multithread]: intro.md#intro.multithread
 
10418
  [iomanip.syn]: #iomanip.syn
10419
  [ios]: #ios
10420
  [ios.base]: #ios.base
10421
  [ios.base.callback]: #ios.base.callback
10422
  [ios.base.cons]: #ios.base.cons
10423
  [ios.base.locales]: #ios.base.locales
10424
  [ios.base.storage]: #ios.base.storage
 
 
 
 
 
10425
  [ios.members.static]: #ios.members.static
 
10426
  [ios.overview]: #ios.overview
 
10427
  [ios.syn]: #ios.syn
10428
  [ios.types]: #ios.types
10429
- [ios::Init]: #ios::Init
10430
- [ios::failure]: #ios::failure
10431
- [ios::fmtflags]: #ios::fmtflags
10432
- [ios::iostate]: #ios::iostate
10433
- [ios::openmode]: #ios::openmode
10434
- [ios::seekdir]: #ios::seekdir
10435
  [iosfwd.syn]: #iosfwd.syn
10436
  [iostate.flags]: #iostate.flags
10437
  [iostream.assign]: #iostream.assign
10438
  [iostream.cons]: #iostream.cons
10439
  [iostream.dest]: #iostream.dest
@@ -10446,32 +11269,34 @@ ISO C 7.8.
10446
  [iostream.syn]: #iostream.syn
10447
  [iostreamclass]: #iostreamclass
10448
  [iostreams.base]: #iostreams.base
10449
  [iostreams.limits.pos]: #iostreams.limits.pos
10450
  [iostreams.requirements]: #iostreams.requirements
 
10451
  [iostreams.threadsafety]: #iostreams.threadsafety
10452
  [istream]: #istream
10453
  [istream.assign]: #istream.assign
10454
  [istream.cons]: #istream.cons
10455
  [istream.extractors]: #istream.extractors
10456
  [istream.formatted]: #istream.formatted
10457
  [istream.formatted.arithmetic]: #istream.formatted.arithmetic
10458
  [istream.formatted.reqmts]: #istream.formatted.reqmts
10459
  [istream.manip]: #istream.manip
10460
  [istream.rvalue]: #istream.rvalue
 
10461
  [istream.syn]: #istream.syn
10462
  [istream.unformatted]: #istream.unformatted
10463
- [istream::sentry]: #istream::sentry
10464
  [istringstream]: #istringstream
10465
  [istringstream.assign]: #istringstream.assign
10466
  [istringstream.cons]: #istringstream.cons
10467
  [istringstream.members]: #istringstream.members
10468
  [lex.charset]: lex.md#lex.charset
10469
  [locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
10470
  [locale.num.get]: localization.md#locale.num.get
 
10471
  [narrow.stream.objects]: #narrow.stream.objects
10472
- [numeric.limits]: language.md#numeric.limits
10473
  [ofstream]: #ofstream
10474
  [ofstream.assign]: #ofstream.assign
10475
  [ofstream.cons]: #ofstream.cons
10476
  [ofstream.members]: #ofstream.members
10477
  [ostream]: #ostream
@@ -10483,13 +11308,13 @@ ISO C 7.8.
10483
  [ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
10484
  [ostream.inserters.character]: #ostream.inserters.character
10485
  [ostream.manip]: #ostream.manip
10486
  [ostream.rvalue]: #ostream.rvalue
10487
  [ostream.seeks]: #ostream.seeks
 
10488
  [ostream.syn]: #ostream.syn
10489
  [ostream.unformatted]: #ostream.unformatted
10490
- [ostream::sentry]: #ostream::sentry
10491
  [ostringstream]: #ostringstream
10492
  [ostringstream.assign]: #ostringstream.assign
10493
  [ostringstream.cons]: #ostringstream.cons
10494
  [ostringstream.members]: #ostringstream.members
10495
  [output.streams]: #output.streams
@@ -10525,60 +11350,49 @@ ISO C 7.8.
10525
  [string.streams]: #string.streams
10526
  [stringbuf]: #stringbuf
10527
  [stringbuf.assign]: #stringbuf.assign
10528
  [stringbuf.cons]: #stringbuf.cons
10529
  [stringbuf.members]: #stringbuf.members
 
 
10530
  [stringbuf.virtuals]: #stringbuf.virtuals
10531
  [strings]: strings.md#strings
10532
  [stringstream]: #stringstream
10533
  [stringstream.assign]: #stringstream.assign
10534
  [stringstream.cons]: #stringstream.cons
10535
  [stringstream.members]: #stringstream.members
10536
- [tab:enum.path.format]: #tab:enum.path.format
10537
- [tab:enum.perm_options]: #tab:enum.perm_options
10538
- [tab:filesystem_error.1]: #tab:filesystem_error.1
10539
- [tab:filesystem_error.2]: #tab:filesystem_error.2
10540
- [tab:filesystem_error.3]: #tab:filesystem_error.3
10541
- [tab:fs.enum.copy_options]: #tab:fs.enum.copy_options
10542
- [tab:fs.enum.directory_options]: #tab:fs.enum.directory_options
10543
- [tab:fs.enum.file_type]: #tab:fs.enum.file_type
10544
- [tab:fs.enum.perms]: #tab:fs.enum.perms
10545
- [tab:iostreams.basicios.init.effects]: #tab:iostreams.basicios.init.effects
10546
- [tab:iostreams.copyfmt.effects]: #tab:iostreams.copyfmt.effects
10547
- [tab:iostreams.file.open.modes]: #tab:iostreams.file.open.modes
10548
- [tab:iostreams.fmtflags.constants]: #tab:iostreams.fmtflags.constants
10549
- [tab:iostreams.fmtflags.effects]: #tab:iostreams.fmtflags.effects
10550
- [tab:iostreams.iostate.effects]: #tab:iostreams.iostate.effects
10551
- [tab:iostreams.lib.summary]: #tab:iostreams.lib.summary
10552
- [tab:iostreams.newoff.values]: #tab:iostreams.newoff.values
10553
- [tab:iostreams.openmode.effects]: #tab:iostreams.openmode.effects
10554
- [tab:iostreams.position.requirements]: #tab:iostreams.position.requirements
10555
- [tab:iostreams.seekdir.effects]: #tab:iostreams.seekdir.effects
10556
- [tab:iostreams.seekoff.effects]: #tab:iostreams.seekoff.effects
10557
- [tab:iostreams.seekoff.positioning]: #tab:iostreams.seekoff.positioning
10558
  [temp.deduct]: temp.md#temp.deduct
10559
- [time.clock.req]: utilities.md#time.clock.req
10560
  [wide.stream.objects]: #wide.stream.objects
10561
 
10562
  [^1]: It is the implementation’s responsibility to implement headers so
10563
  that including `<iosfwd>` and other headers does not violate the
10564
  rules about multiple occurrences of default arguments.
10565
 
10566
- [^2]: If it is possible for them to do so, implementations are
10567
- encouraged to initialize the objects earlier than required.
10568
 
10569
- [^3]: Constructors and destructors for static objects can access these
10570
- objects to read input from `stdin` or write output to `stdout` or
10571
- `stderr`.
10572
 
10573
  [^4]: Typically `long long`.
10574
 
10575
  [^5]: `streamsize` is used in most places where ISO C would use
10576
- `size_t`. Most of the uses of `streamsize` could use `size_t`,
10577
- except for the `strstreambuf` constructors, which require negative
10578
- values. It should probably be the signed type corresponding to
10579
- `size_t` (which is what Posix.2 calls `ssize_t`).
10580
 
10581
  [^6]: This implies that operations on a standard iostream object can be
10582
  mixed arbitrarily with operations on the corresponding stdio stream.
10583
  In practical terms, synchronization usually means that a standard
10584
  iostream object and a standard stdio object share a buffer.
@@ -10586,13 +11400,13 @@ ISO C 7.8.
10586
  [^7]: An implementation is free to implement both the integer array
10587
  pointed at by `iarray` and the pointer array pointed at by `parray`
10588
  as sparse data structures, possibly with a one-element cache for
10589
  each.
10590
 
10591
- [^8]: for example, because it cannot allocate space.
10592
 
10593
- [^9]: for example, because it cannot allocate space.
10594
 
10595
  [^10]: This suggests an infinite amount of copying, but the
10596
  implementation can keep track of the maximum element of the arrays
10597
  that is nonzero.
10598
 
@@ -10628,22 +11442,22 @@ ISO C 7.8.
10628
 
10629
  [^18]: This will be possible only in functions that are part of the
10630
  library. The semantics of the constructor used in user code is as
10631
  specified.
10632
 
10633
- [^19]: The sentry constructor and destructor can also perform additional
10634
- implementation-dependent operations.
10635
 
10636
- [^20]: This is done without causing an `ios::failure` to be thrown.
10637
 
10638
  [^21]: See, for example, the function signature
10639
- `ws(basic_istream&)` ([[istream.manip]]).
10640
 
10641
  [^22]: See, for example, the function signature
10642
- `dec(ios_base&)` ([[basefield.manip]]).
10643
 
10644
- [^23]: This is done without causing an `ios::failure` to be thrown.
10645
 
10646
  [^24]: Note that this function is not overloaded on types `signed char`
10647
  and `unsigned char`.
10648
 
10649
  [^25]: Note that this function is not overloaded on types `signed char`
@@ -10669,19 +11483,19 @@ ISO C 7.8.
10669
  function can determine that no synchronization is necessary.
10670
 
10671
  [^32]: The `sentry` constructor and destructor can also perform
10672
  additional implementation-dependent operations.
10673
 
10674
- [^33]: without causing an `ios::failure` to be thrown.
10675
 
10676
  [^34]: See, for example, the function signature
10677
- `endl(basic_ostream&)` ([[ostream.manip]]).
10678
 
10679
  [^35]: See, for example, the function signature
10680
- `dec(ios_base&)` ([[basefield.manip]]).
10681
 
10682
- [^36]: without causing an `ios::failure` to be thrown.
10683
 
10684
  [^37]: Note that this function is not overloaded on types `signed char`
10685
  and `unsigned char`.
10686
 
10687
  [^38]: Note that this function is not overloaded on types `signed char`
@@ -10696,11 +11510,11 @@ ISO C 7.8.
10696
  `basic_ostream<charT, traits>` object `cout` (the same as
10697
  `cout << noshowbase`).
10698
 
10699
  [^40]: The macro `SEEK_END` is defined, and the function signatures
10700
  `fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
10701
- declared, in `<cstdio>` ([[cstdio.syn]]).
10702
 
10703
  [^41]: POSIX® is a registered trademark of The IEEE. Windows® is a
10704
  registered trademark of Microsoft Corporation. This information is
10705
  given for the convenience of users of this document and does not
10706
  constitute an endorsement by ISO or IEC of these products.
 
7
 
8
  The following subclauses describe requirements for stream parameters,
9
  and components for forward declarations of iostreams, predefined
10
  iostreams objects, base iostreams classes, stream buffering, stream
11
  formatting and manipulators, string streams, and file streams, as
12
+ summarized in [[iostreams.summary]].
13
 
14
+ **Table: Input/output library summary** <a id="iostreams.summary">[iostreams.summary]</a>
15
 
16
  | Subclause | | Header |
17
+ | -------------------------- | --------------------------- | ------------------------------------- |
18
  | [[iostreams.requirements]] | Requirements | |
19
  | [[iostream.forward]] | Forward declarations | `<iosfwd>` |
20
  | [[iostream.objects]] | Standard iostream objects | `<iostream>` |
21
  | [[iostreams.base]] | Iostreams base classes | `<ios>` |
22
  | [[stream.buffers]] | Stream buffers | `<streambuf>` |
23
+ | [[iostream.format]] | Formatting and manipulators | `<iomanip>`, `<istream>`, `<ostream>` |
 
 
24
  | [[string.streams]] | String streams | `<sstream>` |
25
  | [[file.streams]] | File streams | `<fstream>` |
26
+ | [[syncstream]] | Synchronized output streams | `<syncstream>` |
27
  | [[filesystems]] | File systems | `<filesystem>` |
28
+ | [[c.files]] | C library files | `<cstdio>`, `<cinttypes>` |
 
29
 
30
 
31
+ [*Note 1*: Figure [[fig:iostreams.streampos]] illustrates
32
+ relationships among various types described in this clause. A line from
33
+ **A** to **B** indicates that **A** is an alias (e.g., a typedef) for
34
+ **B** or that **A** is defined in terms of **B**.
35
 
36
+ <a id="fig:iostreams.streampos"></a>
37
 
38
+ ![Stream position, offset, and size types \[fig:iostreams.streampos\]](images/figstreampos.svg)
39
+
40
+ — *end note*]
41
 
42
  ## Iostreams requirements <a id="iostreams.requirements">[[iostreams.requirements]]</a>
43
 
44
  ### Imbue limitations <a id="iostream.limits.imbue">[[iostream.limits.imbue]]</a>
45
 
46
+ No function described in [[input.output]] except for `ios_base::imbue`
47
+ and `basic_filebuf::pubimbue` causes any instance of `basic_ios::imbue`
48
+ or `basic_streambuf::imbue` to be called. If any user function called
49
+ from a function declared in [[input.output]] or as an overriding virtual
50
+ function of any class declared in [[input.output]] calls `imbue`, the
51
+ behavior is undefined.
52
 
53
  ### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
54
 
55
+ The classes of [[input.output]] with template arguments `charT` and
56
+ `traits` behave as described if `traits::pos_type` and
57
  `traits::off_type` are `streampos` and `streamoff` respectively. Except
58
  as noted explicitly below, their behavior when `traits::pos_type` and
59
  `traits::off_type` are other types is *implementation-defined*.
60
 
61
+ In the classes of [[input.output]], a template parameter with name
62
+ `charT` represents a member of the set of types containing `char`,
63
  `wchar_t`, and any other *implementation-defined* character types that
64
+ meet the requirements for a character on which any of the iostream
65
  components can be instantiated.
66
 
67
  ### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
68
 
69
+ Concurrent access to a stream object ([[string.streams]],
70
+ [[file.streams]]), stream buffer object [[stream.buffers]], or C Library
71
+ stream [[c.files]] by multiple threads may result in a data race
72
+ [[intro.multithread]] unless otherwise specified [[iostream.objects]].
 
73
 
74
+ [*Note 1*: Data races result in undefined behavior
75
+ [[intro.multithread]]. — *end note*]
76
 
77
  If one thread makes a library call *a* that writes a value to a stream
78
  and, as a result, another thread reads this value from the stream
79
  through a library call *b* such that this does not result in a data
80
  race, then *a*’s write synchronizes with *b*’s read.
 
83
 
84
  ### Header `<iosfwd>` synopsis <a id="iosfwd.syn">[[iosfwd.syn]]</a>
85
 
86
  ``` cpp
87
  namespace std {
88
+ template<class charT> struct char_traits;
89
+ template<> struct char_traits<char>;
90
+ template<> struct char_traits<char8_t>;
91
+ template<> struct char_traits<char16_t>;
92
+ template<> struct char_traits<char32_t>;
93
+ template<> struct char_traits<wchar_t>;
94
 
95
  template<class T> class allocator;
96
 
97
  template<class charT, class traits = char_traits<charT>>
98
  class basic_ios;
 
125
  template<class charT, class traits = char_traits<charT>>
126
  class basic_ofstream;
127
  template<class charT, class traits = char_traits<charT>>
128
  class basic_fstream;
129
 
130
+ template<class charT, class traits = char_traits<charT>,
131
+ class Allocator = allocator<charT>>
132
+ class basic_syncbuf;
133
+ template<class charT, class traits = char_traits<charT>,
134
+ class Allocator = allocator<charT>>
135
+ class basic_osyncstream;
136
+
137
  template<class charT, class traits = char_traits<charT>>
138
  class istreambuf_iterator;
139
  template<class charT, class traits = char_traits<charT>>
140
  class ostreambuf_iterator;
141
 
 
155
  using filebuf = basic_filebuf<char>;
156
  using ifstream = basic_ifstream<char>;
157
  using ofstream = basic_ofstream<char>;
158
  using fstream = basic_fstream<char>;
159
 
160
+ using syncbuf = basic_syncbuf<char>;
161
+ using osyncstream = basic_osyncstream<char>;
162
+
163
  using wstreambuf = basic_streambuf<wchar_t>;
164
  using wistream = basic_istream<wchar_t>;
165
  using wostream = basic_ostream<wchar_t>;
166
  using wiostream = basic_iostream<wchar_t>;
167
 
 
173
  using wfilebuf = basic_filebuf<wchar_t>;
174
  using wifstream = basic_ifstream<wchar_t>;
175
  using wofstream = basic_ofstream<wchar_t>;
176
  using wfstream = basic_fstream<wchar_t>;
177
 
178
+ using wsyncbuf = basic_syncbuf<wchar_t>;
179
+ using wosyncstream = basic_osyncstream<wchar_t>;
180
+
181
  template<class state> class fpos;
182
  using streampos = fpos<char_traits<char>::state_type>;
183
  using wstreampos = fpos<char_traits<wchar_t>::state_type>;
184
+ using u8streampos = fpos<char_traits<char8_t>::state_type>;
185
+ using u16streampos = fpos<char_traits<char16_t>::state_type>;
186
+ using u32streampos = fpos<char_traits<char32_t>::state_type>;
187
  }
188
  ```
189
 
190
  Default template arguments are described as appearing both in `<iosfwd>`
191
  and in the synopsis of other headers but it is well-formed to include
 
198
  `basic_ostream`, and class templates derived from them. `basic_iostream`
199
  is a class template derived from both `basic_istream<charT, traits>` and
200
  `basic_ostream<charT, traits>`.
201
 
202
  The class template specialization `basic_streambuf<charT, traits>`
203
+ serves as a base class for class templates `basic_stringbuf`,
204
+ `basic_filebuf`, and `basic_syncbuf`.
205
 
206
  The class template specialization `basic_istream<charT, traits>` serves
207
  as a base class for class templates `basic_istringstream` and
208
  `basic_ifstream`.
209
 
210
  The class template specialization `basic_ostream<charT, traits>` serves
211
+ as a base class for class templates `basic_ostringstream`,
212
+ `basic_ofstream`, and `basic_osyncstream`.
213
 
214
  The class template specialization `basic_iostream<charT, traits>` serves
215
  as a base class for class templates `basic_stringstream` and
216
  `basic_fstream`.
217
 
218
+ [*Note 1*: For each of the class templates above, the program is
219
+ ill-formed if `traits::char_type` is not the same type as `charT`
220
+ [[char.traits]]. — *end note*]
221
+
222
  Other *typedef-name*s define instances of class templates specialized
223
  for `char` or `wchar_t` types.
224
 
225
  Specializations of the class template `fpos` are used for specifying
226
  file position information.
227
 
228
+ [*Example 1*: The types `streampos` and `wstreampos` are used for
229
+ positioning streams specialized on `char` and `wchar_t`
230
+ respectively. — *end example*]
231
 
232
+ [*Note 2*: This synopsis suggests a circularity between `streampos` and
 
 
233
  `char_traits<char>`. An implementation can avoid this circularity by
234
+ substituting equivalent types. *end note*]
 
 
 
 
 
 
 
 
 
 
 
 
 
235
 
236
  ## Standard iostream objects <a id="iostream.objects">[[iostream.objects]]</a>
237
 
238
  ### Header `<iostream>` synopsis <a id="iostream.syn">[[iostream.syn]]</a>
239
 
 
257
  ```
258
 
259
  ### Overview <a id="iostream.objects.overview">[[iostream.objects.overview]]</a>
260
 
261
  In this Clause, the type name `FILE` refers to the type `FILE` declared
262
+ in `<cstdio>`.
263
 
264
  The header `<iostream>` declares objects that associate objects with the
265
+ standard C streams provided for by the functions declared in `<cstdio>`,
266
+ and includes all the headers necessary to use these objects.
 
267
 
268
  The objects are constructed and the associations are established at some
269
  time prior to or during the first time an object of class
270
  `ios_base::Init` is constructed, and in any case before the body of
271
+ `main` [[basic.start.main]] begins execution.[^2] The objects are not
272
  destroyed during program execution.[^3] The results of including
273
  `<iostream>` in a translation unit shall be as if `<iostream>` defined
274
  an instance of `ios_base::Init` with static storage duration.
275
 
276
  Mixing operations on corresponding wide- and narrow-character streams
277
  follows the same semantics as mixing such operations on `FILE`s, as
278
  specified in the C standard library.
279
 
280
+ Concurrent access to a synchronized [[ios.members.static]] standard
281
+ iostream object’s formatted and unformatted input [[istream]] and output
282
+ [[ostream]] functions or a standard C stream by multiple threads does
283
+ not result in a data race [[intro.multithread]].
284
 
285
  [*Note 1*: Users must still synchronize concurrent use of these objects
286
  and streams by multiple threads if they wish to avoid interleaved
287
  characters. — *end note*]
288
 
289
+ See also: ISO C 7.21.2
290
 
291
  ### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
292
 
293
  ``` cpp
294
  istream cin;
295
  ```
296
 
297
  The object `cin` controls input from a stream buffer associated with the
298
+ object `stdin`, declared in `<cstdio>`.
299
 
300
  After the object `cin` is initialized, `cin.tie()` returns `&cout`. Its
301
+ state is otherwise the same as required for `basic_ios<char>::init`
302
+ [[basic.ios.cons]].
303
 
304
  ``` cpp
305
  ostream cout;
306
  ```
307
 
308
  The object `cout` controls output to a stream buffer associated with the
309
+ object `stdout`, declared in `<cstdio>`.
310
 
311
  ``` cpp
312
  ostream cerr;
313
  ```
314
 
315
  The object `cerr` controls output to a stream buffer associated with the
316
+ object `stderr`, declared in `<cstdio>`.
317
 
318
  After the object `cerr` is initialized, `cerr.flags() & unitbuf` is
319
  nonzero and `cerr.tie()` returns `&cout`. Its state is otherwise the
320
+ same as required for `basic_ios<char>::init` [[basic.ios.cons]].
321
 
322
  ``` cpp
323
  ostream clog;
324
  ```
325
 
326
  The object `clog` controls output to a stream buffer associated with the
327
+ object `stderr`, declared in `<cstdio>`.
328
 
329
  ### Wide stream objects <a id="wide.stream.objects">[[wide.stream.objects]]</a>
330
 
331
  ``` cpp
332
  wistream wcin;
333
  ```
334
 
335
  The object `wcin` controls input from a stream buffer associated with
336
+ the object `stdin`, declared in `<cstdio>`.
337
 
338
  After the object `wcin` is initialized, `wcin.tie()` returns `&wcout`.
339
  Its state is otherwise the same as required for
340
+ `basic_ios<wchar_t>::init` [[basic.ios.cons]].
341
 
342
  ``` cpp
343
  wostream wcout;
344
  ```
345
 
346
  The object `wcout` controls output to a stream buffer associated with
347
+ the object `stdout`, declared in `<cstdio>`.
348
 
349
  ``` cpp
350
  wostream wcerr;
351
  ```
352
 
353
  The object `wcerr` controls output to a stream buffer associated with
354
+ the object `stderr`, declared in `<cstdio>`.
355
 
356
  After the object `wcerr` is initialized, `wcerr.flags() & unitbuf` is
357
  nonzero and `wcerr.tie()` returns `&wcout`. Its state is otherwise the
358
+ same as required for `basic_ios<wchar_t>::init` [[basic.ios.cons]].
359
 
360
  ``` cpp
361
  wostream wclog;
362
  ```
363
 
364
  The object `wclog` controls output to a stream buffer associated with
365
+ the object `stderr`, declared in `<cstdio>`.
366
 
367
  ## Iostreams base classes <a id="iostreams.base">[[iostreams.base]]</a>
368
 
369
  ### Header `<ios>` synopsis <a id="ios.syn">[[ios.syn]]</a>
370
 
 
454
  namespace std {
455
  class ios_base {
456
  public:
457
  class failure; // see below
458
 
459
+ // [ios.fmtflags], fmtflags
460
  using fmtflags = T1;
461
  static constexpr fmtflags boolalpha = unspecified;
462
  static constexpr fmtflags dec = unspecified;
463
  static constexpr fmtflags fixed = unspecified;
464
  static constexpr fmtflags hex = unspecified;
 
475
  static constexpr fmtflags uppercase = unspecified;
476
  static constexpr fmtflags adjustfield = see below;
477
  static constexpr fmtflags basefield = see below;
478
  static constexpr fmtflags floatfield = see below;
479
 
480
+ // [ios.iostate], iostate
481
  using iostate = T2;
482
  static constexpr iostate badbit = unspecified;
483
  static constexpr iostate eofbit = unspecified;
484
  static constexpr iostate failbit = unspecified;
485
  static constexpr iostate goodbit = see below;
486
 
487
+ // [ios.openmode], openmode
488
  using openmode = T3;
489
  static constexpr openmode app = unspecified;
490
  static constexpr openmode ate = unspecified;
491
  static constexpr openmode binary = unspecified;
492
  static constexpr openmode in = unspecified;
493
  static constexpr openmode out = unspecified;
494
  static constexpr openmode trunc = unspecified;
495
 
496
+ // [ios.seekdir], seekdir
497
  using seekdir = T4;
498
  static constexpr seekdir beg = unspecified;
499
  static constexpr seekdir cur = unspecified;
500
  static constexpr seekdir end = unspecified;
501
 
 
517
  locale imbue(const locale& loc);
518
  locale getloc() const;
519
 
520
  // [ios.base.storage], storage
521
  static int xalloc();
522
+ long& iword(int idx);
523
+ void*& pword(int idx);
524
 
525
+ // destructor
526
  virtual ~ios_base();
527
 
528
+ // [ios.base.callback], callbacks
529
  enum event { erase_event, imbue_event, copyfmt_event };
530
+ using event_callback = void (*)(event, ios_base&, int idx);
531
+ void register_callback(event_callback fn, int idx);
532
 
533
  ios_base(const ios_base&) = delete;
534
  ios_base& operator=(const ios_base&) = delete;
535
 
536
  static bool sync_with_stdio(bool sync = true);
 
578
 
579
  — *end note*]
580
 
581
  #### Types <a id="ios.types">[[ios.types]]</a>
582
 
583
+ ##### Class `ios_base::failure` <a id="ios.failure">[[ios.failure]]</a>
584
 
585
  ``` cpp
586
  namespace std {
587
  class ios_base::failure : public system_error {
588
  public:
 
594
 
595
  An implementation is permitted to define `ios_base::failure` as a
596
  synonym for a class with equivalent functionality to class
597
  `ios_base::failure` shown in this subclause.
598
 
599
+ [*Note 1*: When `ios_base::failure` is a synonym for another type, that
600
+ type is required to provide a nested type `failure` to emulate the
601
+ injected-class-name. — *end note*]
602
 
603
  The class `failure` defines the base class for the types of all objects
604
  thrown as exceptions, by functions in the iostreams library, to report
605
  errors detected during stream buffer operations.
606
 
 
617
 
618
  ``` cpp
619
  explicit failure(const string& msg, const error_code& ec = io_errc::stream);
620
  ```
621
 
622
+ *Effects:* Constructs the base class with `msg` and `ec`.
 
623
 
624
  ``` cpp
625
  explicit failure(const char* msg, const error_code& ec = io_errc::stream);
626
  ```
627
 
628
+ *Effects:* Constructs the base class with `msg` and `ec`.
 
629
 
630
+ ##### Type `ios_base::fmtflags` <a id="ios.fmtflags">[[ios.fmtflags]]</a>
631
 
632
  ``` cpp
633
  using fmtflags = T1;
634
  ```
635
 
636
+ The type `fmtflags` is a bitmask type [[bitmask.types]]. Setting its
637
+ elements has the effects indicated in [[ios.fmtflags]].
 
638
 
639
+ **Table: `fmtflags` effects** <a id="ios.fmtflags">[ios.fmtflags]</a>
640
 
641
  | Element | Effect(s) if set |
642
  | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
643
  | `boolalpha` | insert and extract `bool` type in alphabetic format |
644
  | `dec` | converts integer input or generates integer output in decimal base |
 
656
  | `unitbuf` | flushes output after each output operation |
657
  | `uppercase` | replaces certain lowercase letters with their uppercase equivalents in generated output |
658
 
659
 
660
  Type `fmtflags` also defines the constants indicated in
661
+ [[ios.fmtflags.const]].
662
 
663
+ **Table: `fmtflags` constants** <a id="ios.fmtflags.const">[ios.fmtflags.const]</a>
664
 
665
  | Constant | Allowable values |
666
  | ------------- | ------------------------- |
667
  | `adjustfield` | `left | right | internal` |
668
  | `basefield` | `dec | oct | hex` |
669
  | `floatfield` | `scientific | fixed` |
670
 
671
 
672
+ ##### Type `ios_base::iostate` <a id="ios.iostate">[[ios.iostate]]</a>
673
 
674
  ``` cpp
675
  using iostate = T2;
676
  ```
677
 
678
+ The type `iostate` is a bitmask type [[bitmask.types]] that contains the
679
+ elements indicated in [[ios.iostate]].
680
 
681
+ **Table: `iostate` effects** <a id="ios.iostate">[ios.iostate]</a>
682
 
683
  | Element | Effect(s) if set |
684
  | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
685
  | `badbit` | indicates a loss of integrity in an input or output sequence (such as an irrecoverable read error from a file); |
686
  | `eofbit` | indicates that an input operation reached the end of an input sequence; |
 
689
 
690
  Type `iostate` also defines the constant:
691
 
692
  - `goodbit`, the value zero.
693
 
694
+ ##### Type `ios_base::openmode` <a id="ios.openmode">[[ios.openmode]]</a>
695
 
696
  ``` cpp
697
  using openmode = T3;
698
  ```
699
 
700
+ The type `openmode` is a bitmask type [[bitmask.types]]. It contains the
701
+ elements indicated in [[ios.openmode]].
702
 
703
+ **Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
704
 
705
  | Element | Effect(s) if set |
706
  | -------- | ----------------------------------------------------------------- |
707
  | `app` | seek to end before each write |
708
  | `ate` | open and seek to end immediately after opening |
 
710
  | `in` | open for input |
711
  | `out` | open for output |
712
  | `trunc` | truncate an existing stream when opening |
713
 
714
 
715
+ ##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
716
 
717
  ``` cpp
718
  using seekdir = T4;
719
  ```
720
 
721
+ The type `seekdir` is an enumerated type [[enumerated.types]] that
722
+ contains the elements indicated in [[ios.seekdir]].
 
723
 
724
+ **Table: `seekdir` effects** <a id="ios.seekdir">[ios.seekdir]</a>
725
 
726
  | Element | Meaning |
727
  | ------- | --------------------------------------------------------------------------------------- |
728
  | `beg` | request a seek (for subsequent input or output) relative to the beginning of the stream |
729
  | `cur` | request a seek relative to the current position within the sequence |
730
  | `end` | request a seek relative to the current end of the sequence |
731
 
732
 
733
+ ##### Class `ios_base::Init` <a id="ios.init">[[ios.init]]</a>
734
 
735
  ``` cpp
736
  namespace std {
737
  class ios_base::Init {
738
  public:
739
  Init();
740
+ Init(const Init&) = default;
741
  ~Init();
742
+ Init& operator=(const Init&) = default;
743
  private:
744
  static int init_cnt; // exposition only
745
  };
746
  }
747
  ```
748
 
749
  The class `Init` describes an object whose construction ensures the
750
+ construction of the eight objects declared in `<iostream>`
751
+ [[iostream.objects]] that associate file stream buffers with the
752
+ standard C streams provided for by the functions declared in `<cstdio>`.
 
753
 
754
  For the sake of exposition, the maintained data is presented here as:
755
 
756
  - `static int init_cnt`, counts the number of constructor and destructor
757
  calls for class `Init`, initialized to zero.
758
 
759
  ``` cpp
760
  Init();
761
  ```
762
 
763
+ *Effects:* Constructs and initializes the objects `cin`, `cout`, `cerr`,
764
+ `clog`, `wcin`, `wcout`, `wcerr`, and `wclog` if they have not already
765
+ been constructed and initialized.
 
766
 
767
  ``` cpp
768
  ~Init();
769
  ```
770
 
771
+ *Effects:* If there are no other instances of the class still in
772
+ existence, calls `cout.flush()`, `cerr.flush()`, `clog.flush()`,
773
+ `wcout.flush()`, `wcerr.flush()`, `wclog.flush()`.
 
774
 
775
+ #### State functions <a id="fmtflags.state">[[fmtflags.state]]</a>
776
 
777
  ``` cpp
778
  fmtflags flags() const;
779
  ```
780
 
 
782
 
783
  ``` cpp
784
  fmtflags flags(fmtflags fmtfl);
785
  ```
786
 
787
+ *Ensures:* `fmtfl == flags()`.
788
 
789
  *Returns:* The previous value of `flags()`.
790
 
791
  ``` cpp
792
  fmtflags setf(fmtflags fmtfl);
 
818
 
819
  ``` cpp
820
  streamsize precision(streamsize prec);
821
  ```
822
 
823
+ *Ensures:* `prec == precision()`.
824
 
825
  *Returns:* The previous value of `precision()`.
826
 
827
  ``` cpp
828
  streamsize width() const;
 
833
 
834
  ``` cpp
835
  streamsize width(streamsize wide);
836
  ```
837
 
838
+ *Ensures:* `wide == width()`.
839
 
840
  *Returns:* The previous value of `width()`.
841
 
842
+ #### Functions <a id="ios.base.locales">[[ios.base.locales]]</a>
843
 
844
  ``` cpp
845
  locale imbue(const locale& loc);
846
  ```
847
 
848
+ *Effects:* Calls each registered callback pair `(fn, idx)`
849
+ [[ios.base.callback]] as `(*fn)(imbue_event, *this, idx)` at such a time
850
+ that a call to `ios_base::getloc()` from within `fn` returns the new
851
+ locale value `loc`.
852
+
853
+ *Ensures:* `loc == getloc()`.
854
 
855
  *Returns:* The previous value of `getloc()`.
856
 
 
 
857
  ``` cpp
858
  locale getloc() const;
859
  ```
860
 
861
+ *Returns:* If no locale has been imbued, a copy of the global C++
862
+ locale, `locale()`, in effect at the time of construction. Otherwise,
863
+ returns the imbued locale, to be used to perform locale-dependent input
864
+ and output operations.
865
 
866
+ #### Static members <a id="ios.members.static">[[ios.members.static]]</a>
867
 
868
  ``` cpp
869
+ static bool sync_with_stdio(bool sync = true);
870
  ```
871
 
872
  *Returns:* `true` if the previous state of the standard iostream
873
+ objects [[iostream.objects]] was synchronized and otherwise returns
874
  `false`. The first time it is called, the function returns `true`.
875
 
876
  *Effects:* If any input or output operation has occurred using the
877
  standard streams prior to the call, the effect is
878
  *implementation-defined*. Otherwise, called with a `false` argument, it
 
918
  str.rdbuf()->sputbackc(c);
919
  ```
920
 
921
  for any sequence of characters.[^6]
922
 
923
+ #### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
924
 
925
  ``` cpp
926
  static int xalloc();
927
  ```
928
 
929
  *Returns:* `index` `++`.
930
 
931
+ *Remarks:* Concurrent access to this function by multiple threads does
932
+ not result in a data race [[intro.multithread]].
933
 
934
  ``` cpp
935
  long& iword(int idx);
936
  ```
937
 
938
+ *Preconditions:* `idx` is a value obtained by a call to `xalloc`.
939
+
940
  *Effects:* If `iarray` is a null pointer, allocates an array of `long`
941
  of unspecified size and stores a pointer to its first element in
942
  `iarray`. The function then extends the array pointed at by `iarray` as
943
  necessary to include the element `iarray[idx]`. Each newly allocated
944
  element of the array is initialized to zero. The reference returned is
 
955
 
956
  ``` cpp
957
  void*& pword(int idx);
958
  ```
959
 
960
+ *Preconditions:* `idx` is a value obtained by a call to `xalloc`.
961
+
962
  *Effects:* If `parray` is a null pointer, allocates an array of pointers
963
  to `void` of unspecified size and stores a pointer to its first element
964
  in `parray`. The function then extends the array pointed at by `parray`
965
  as necessary to include the element `parray[idx]`. Each newly allocated
966
  element of the array is initialized to a null pointer. The reference
 
976
  initialized to 0.
977
 
978
  *Remarks:* After a subsequent call to `pword(int)` for the same object,
979
  the earlier return value may no longer be valid.
980
 
981
+ #### Callbacks <a id="ios.base.callback">[[ios.base.callback]]</a>
982
 
983
  ``` cpp
984
+ void register_callback(event_callback fn, int idx);
985
  ```
986
 
987
+ *Preconditions:* The function `fn` does not throw exceptions.
 
 
 
 
 
988
 
989
+ *Effects:* Registers the pair `(fn, idx)` such that during calls to
990
+ `imbue()` [[ios.base.locales]], `copyfmt()`, or `~ios_base()`
991
+ [[ios.base.cons]], the function `fn` is called with argument `idx`.
992
+ Functions registered are called when an event occurs, in opposite order
993
+ of registration. Functions registered while a callback function is
994
+ active are not called until the next event.
995
 
996
  *Remarks:* Identical pairs are not merged. A function registered twice
997
  will be called twice.
998
 
999
+ #### Constructors and destructor <a id="ios.base.cons">[[ios.base.cons]]</a>
1000
 
1001
  ``` cpp
1002
  ios_base();
1003
  ```
1004
 
 
1009
 
1010
  ``` cpp
1011
  ~ios_base();
1012
  ```
1013
 
1014
+ *Effects:* Calls each registered callback pair `(fn, idx)`
1015
+ [[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
1016
+ that any `ios_base` member function called from within `fn` has
1017
+ well-defined results.
1018
 
1019
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
1020
 
1021
  ``` cpp
1022
  namespace std {
 
1029
  stateT st; // exposition only
1030
  };
1031
  }
1032
  ```
1033
 
1034
+ #### Members <a id="fpos.members">[[fpos.members]]</a>
1035
 
1036
  ``` cpp
1037
  void state(stateT s);
1038
  ```
1039
 
 
1043
  stateT state() const;
1044
  ```
1045
 
1046
  *Returns:* Current value of `st`.
1047
 
1048
+ #### Requirements <a id="fpos.operations">[[fpos.operations]]</a>
1049
 
1050
+ An `fpos` type specifies file position information. It holds a state
1051
+ object whose type is equal to the template parameter `stateT`. Type
1052
+ `stateT` shall meet the *Cpp17DefaultConstructible* (
1053
+ [[cpp17.defaultconstructible]]), *Cpp17CopyConstructible* (
1054
+ [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
1055
+ [[cpp17.copyassignable]]), and *Cpp17Destructible* (
1056
+ [[cpp17.destructible]]) requirements. If
1057
+ `is_trivially_copy_constructible_v<stateT>` is `true`, then
1058
+ `fpos<stateT>` has a trivial copy constructor. If
1059
+ `is_trivially_copy_assignable<stateT>` is `true`, then `fpos<stateT>`
1060
+ has a trivial copy assignment operator. If
1061
+ `is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
1062
+ a trivial destructor. All specializations of `fpos` meet the
1063
+ *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
1064
+ *Cpp17CopyAssignable*, *Cpp17Destructible*, and
1065
+ *Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
1066
+ In addition, the expressions shown in [[fpos.operations]] are valid and
1067
+ have the indicated semantics. In that table,
1068
 
1069
  - `P` refers to an instance of `fpos`,
1070
+ - `p` and `q` refer to values of type `P` or `const P`,
1071
+ - `pl` and `ql` refer to modifiable lvalues of type `P`,
1072
+ - `O` refers to type `streamoff`, and
1073
+ - `o` refers to a value of type `streamoff` or `const streamoff`.
 
 
 
 
 
 
 
1074
 
1075
  Stream operations that return a value of type `traits::pos_type` return
1076
  `P(O(-1))` as an invalid value to signal an error. If this value is used
1077
  as an argument to any `istream`, `ostream`, or `streambuf` member that
1078
  accepts a value of type `traits::pos_type` then the behavior of that
 
1141
 
1142
  };
1143
  }
1144
  ```
1145
 
1146
+ #### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
1147
 
1148
  ``` cpp
1149
  explicit basic_ios(basic_streambuf<charT, traits>* sb);
1150
  ```
1151
 
1152
+ *Effects:* Assigns initial values to its member objects by calling
1153
+ `init(sb)`.
1154
 
1155
  ``` cpp
1156
  basic_ios();
1157
  ```
1158
 
1159
+ *Effects:* Leaves its member objects uninitialized. The object shall be
1160
+ initialized by calling `basic_ios::init` before its first use or before
1161
+ it is destroyed, whichever comes first; otherwise the behavior is
1162
+ undefined.
 
1163
 
1164
  ``` cpp
1165
  ~basic_ios();
1166
  ```
1167
 
 
1169
 
1170
  ``` cpp
1171
  void init(basic_streambuf<charT, traits>* sb);
1172
  ```
1173
 
1174
+ *Ensures:* The postconditions of this function are indicated in
1175
+ [[basic.ios.cons]].
1176
 
1177
+ **Table: `basic_ios::init()` effects** <a id="basic.ios.cons">[basic.ios.cons]</a>
1178
 
1179
  | Element | Value |
1180
  | -------------- | ------------------------------------------------------------ |
1181
  | `rdbuf()` | `sb` |
1182
  | `tie()` | `0` |
 
1202
 
1203
  ``` cpp
1204
  basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
1205
  ```
1206
 
1207
+ *Preconditions:* If `tiestr` is not null, `tiestr` is not reachable by
1208
  traversing the linked list of tied stream objects starting from
1209
  `tiestr->tie()`.
1210
 
1211
+ *Ensures:* `tiestr == tie()`.
1212
 
1213
  *Returns:* The previous value of `tie()`.
1214
 
1215
  ``` cpp
1216
  basic_streambuf<charT, traits>* rdbuf() const;
 
1220
 
1221
  ``` cpp
1222
  basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
1223
  ```
1224
 
 
 
1225
  *Effects:* Calls `clear()`.
1226
 
1227
+ *Ensures:* `sb == rdbuf()`.
1228
+
1229
  *Returns:* The previous value of `rdbuf()`.
1230
 
1231
  ``` cpp
1232
  locale imbue(const locale& loc);
1233
  ```
1234
 
1235
+ *Effects:* Calls `ios_base::imbue(loc)` [[ios.base.locales]] and if
1236
+ `rdbuf() != 0` then `rdbuf()->pubimbue(loc)` [[streambuf.locales]].
1237
 
1238
  *Returns:* The prior value of `ios_base::imbue()`.
1239
 
1240
  ``` cpp
1241
  char narrow(char_type c, char dfault) const;
 
1258
 
1259
  ``` cpp
1260
  char_type fill(char_type fillch);
1261
  ```
1262
 
1263
+ *Ensures:* `traits::eq(fillch, fill())`.
1264
 
1265
  *Returns:* The previous value of `fill()`.
1266
 
1267
  ``` cpp
1268
  basic_ios& copyfmt(const basic_ios& rhs);
1269
  ```
1270
 
1271
+ *Effects:* If `(this == addressof(rhs))` is `true` does nothing.
1272
+ Otherwise assigns to the member objects of `*this` the corresponding
1273
+ member objects of `rhs` as follows:
1274
 
1275
+ - calls each registered callback pair `(fn, idx)` as
1276
+ `(*fn)(erase_event, *this, idx)`;
1277
+ - then, assigns to the member objects of `*this` the corresponding
1278
+ member objects of `rhs`, except that
1279
  - `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
1280
+ - the contents of arrays pointed at by `pword` and `iword` are copied,
1281
+ not the pointers themselves;[^10] and
1282
  - if any newly stored pointer values in `*this` point at objects
1283
+ stored outside the object `rhs` and those objects are destroyed when
1284
+ `rhs` is destroyed, the newly stored pointer values are altered to
1285
+ point at newly constructed copies of the objects;
1286
+ - then, calls each callback pair that was copied from `rhs` as
1287
+ `(*fn)(copyfmt_event, *this, idx)`;
1288
+ - then, calls `exceptions(rhs.exceptions())`.
1289
 
1290
  [*Note 1*: The second pass through the callback pairs permits a copied
1291
  `pword` value to be zeroed, or to have its referent deep copied or
1292
  reference counted, or to have other special action taken. — *end note*]
1293
 
1294
+ *Ensures:* The postconditions of this function are indicated in
1295
+ [[basic.ios.copyfmt]].
1296
 
1297
+ **Table: `basic_ios::copyfmt()` effects** <a id="basic.ios.copyfmt">[basic.ios.copyfmt]</a>
1298
 
1299
  | Element | Value |
1300
  | -------------- | ------------------ |
1301
  | `rdbuf()` | unchanged |
1302
  | `tie()` | `rhs.tie()` |
 
1314
  ``` cpp
1315
  void move(basic_ios& rhs);
1316
  void move(basic_ios&& rhs);
1317
  ```
1318
 
1319
+ *Ensures:* `*this` has the state that `rhs` had before the function
1320
+ call, except that `rdbuf()` returns `nullptr`. `rhs` is in a valid but
1321
+ unspecified state, except that `rhs.rdbuf()` returns the same value as
1322
+ it returned before the function call, and `rhs.tie()` returns `nullptr`.
 
1323
 
1324
  ``` cpp
1325
  void swap(basic_ios& rhs) noexcept;
1326
  ```
1327
 
1328
+ *Effects:* The states of `*this` and `rhs` are exchanged, except that
1329
+ `rdbuf()` returns the same value as it returned before the function
1330
+ call, and `rhs.rdbuf()` returns the same value as it returned before the
1331
+ function call.
1332
 
1333
  ``` cpp
1334
  void set_rdbuf(basic_streambuf<charT, traits>* sb);
1335
  ```
1336
 
1337
+ *Preconditions:* `sb != nullptr` is `true`.
1338
 
1339
  *Effects:* Associates the `basic_streambuf` object pointed to by `sb`
1340
  with this stream without calling `clear()`.
1341
 
1342
+ *Ensures:* `rdbuf() == sb` is `true`.
1343
 
1344
  *Throws:* Nothing.
1345
 
1346
+ #### Flags functions <a id="iostate.flags">[[iostate.flags]]</a>
1347
 
1348
  ``` cpp
1349
  explicit operator bool() const;
1350
  ```
1351
 
 
1365
 
1366
  ``` cpp
1367
  void clear(iostate state = goodbit);
1368
  ```
1369
 
1370
+ *Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
1371
  `rdstate() == (state | ios_base::badbit)`.
1372
 
1373
  *Effects:* If
1374
  `((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
1375
+ Otherwise, the function throws an object of class `ios_base::failure`
1376
+ [[ios.failure]], constructed with *implementation-defined* argument
1377
+ values.
1378
 
1379
  ``` cpp
1380
  void setstate(iostate state);
1381
  ```
1382
 
1383
  *Effects:* Calls `clear(rdstate() | state)` (which may throw
1384
+ `ios_base::failure` [[ios.failure]]).
1385
 
1386
  ``` cpp
1387
  bool good() const;
1388
  ```
1389
 
 
1416
 
1417
  ``` cpp
1418
  void exceptions(iostate except);
1419
  ```
1420
 
1421
+ *Ensures:* `except == exceptions()`.
1422
 
1423
  *Effects:* Calls `clear(rdstate())`.
1424
 
1425
  ### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
1426
 
1427
  #### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
1428
 
1429
+ Each function specified in this subclause is a designated addressable
1430
+ function [[namespace.std]].
1431
+
1432
  ``` cpp
1433
  ios_base& boolalpha(ios_base& str);
1434
  ```
1435
 
1436
  *Effects:* Calls `str.setf(ios_base::boolalpha)`.
 
1541
 
1542
  *Returns:* `str`.
1543
 
1544
  #### `adjustfield` manipulators <a id="adjustfield.manip">[[adjustfield.manip]]</a>
1545
 
1546
+ Each function specified in this subclause is a designated addressable
1547
+ function [[namespace.std]].
1548
+
1549
  ``` cpp
1550
  ios_base& internal(ios_base& str);
1551
  ```
1552
 
1553
  *Effects:* Calls `str.setf(ios_base::internal, ios_base::adjustfield)`.
 
1570
 
1571
  *Returns:* `str`.
1572
 
1573
  #### `basefield` manipulators <a id="basefield.manip">[[basefield.manip]]</a>
1574
 
1575
+ Each function specified in this subclause is a designated addressable
1576
+ function [[namespace.std]].
1577
+
1578
  ``` cpp
1579
  ios_base& dec(ios_base& str);
1580
  ```
1581
 
1582
  *Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
 
1599
 
1600
  *Returns:* `str`.
1601
 
1602
  #### `floatfield` manipulators <a id="floatfield.manip">[[floatfield.manip]]</a>
1603
 
1604
+ Each function specified in this subclause is a designated addressable
1605
+ function [[namespace.std]].
1606
+
1607
  ``` cpp
1608
  ios_base& fixed(ios_base& str);
1609
  ```
1610
 
1611
  *Effects:* Calls `str.setf(ios_base::fixed, ios_base::floatfield)`.
 
1629
 
1630
  *Returns:* `str`.
1631
 
1632
  [*Note 1*: The more obvious use of `ios_base::hex` to specify
1633
  hexadecimal floating-point format would change the meaning of existing
1634
+ well-defined programs. C++03 gives no meaning to the combination of
1635
  `fixed` and `scientific`. — *end note*]
1636
 
1637
  ``` cpp
1638
  ios_base& defaultfloat(ios_base& str);
1639
  ```
1640
 
1641
  *Effects:* Calls `str.unsetf(ios_base::floatfield)`.
1642
 
1643
  *Returns:* `str`.
1644
 
1645
+ ### Error reporting <a id="error.reporting">[[error.reporting]]</a>
1646
 
1647
  ``` cpp
1648
  error_code make_error_code(io_errc e) noexcept;
1649
  ```
1650
 
 
1762
  pos_type pubseekpos(pos_type sp,
1763
  ios_base::openmode which
1764
  = ios_base::in | ios_base::out);
1765
  int pubsync();
1766
 
1767
+ // get and put areas
1768
  // [streambuf.pub.get], get area
1769
  streamsize in_avail();
1770
  int_type snextc();
1771
  int_type sbumpc();
1772
  int_type sgetc();
 
1836
  *character sequences*:
1837
 
1838
  - a character *input sequence*;
1839
  - a character *output sequence*.
1840
 
1841
+ #### Constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
1842
 
1843
  ``` cpp
1844
  basic_streambuf();
1845
  ```
1846
 
1847
+ *Effects:* Initializes:[^13]
 
1848
 
1849
+ - all pointer member objects to null pointers,
1850
  - the `getloc()` member to a copy the global locale, `locale()`, at the
1851
  time of construction.
1852
 
1853
  *Remarks:* Once the `getloc()` member is initialized, results of calling
1854
  locale member functions, and of members of facets so obtained, can
 
1856
 
1857
  ``` cpp
1858
  basic_streambuf(const basic_streambuf& rhs);
1859
  ```
1860
 
1861
+ *Ensures:*
 
 
1862
 
1863
  - `eback() == rhs.eback()`
1864
  - `gptr() == rhs.gptr()`
1865
  - `egptr() == rhs.egptr()`
1866
  - `pbase() == rhs.pbase()`
 
1872
  ~basic_streambuf();
1873
  ```
1874
 
1875
  *Effects:* None.
1876
 
1877
+ #### Public member functions <a id="streambuf.members">[[streambuf.members]]</a>
1878
 
1879
  ##### Locales <a id="streambuf.locales">[[streambuf.locales]]</a>
1880
 
1881
  ``` cpp
1882
  locale pubimbue(const locale& loc);
1883
  ```
1884
 
 
 
1885
  *Effects:* Calls `imbue(loc)`.
1886
 
1887
+ *Ensures:* `loc == getloc()`.
1888
+
1889
  *Returns:* Previous value of `getloc()`.
1890
 
1891
  ``` cpp
1892
  locale getloc() const;
1893
  ```
 
1933
  ``` cpp
1934
  streamsize in_avail();
1935
  ```
1936
 
1937
  *Returns:* If a read position is available, returns `egptr() - gptr()`.
1938
+ Otherwise returns `showmanyc()` [[streambuf.virt.get]].
1939
 
1940
  ``` cpp
1941
  int_type snextc();
1942
  ```
1943
 
 
1948
 
1949
  ``` cpp
1950
  int_type sbumpc();
1951
  ```
1952
 
1953
+ *Effects:* If the input sequence read position is not available, returns
1954
  `uflow()`. Otherwise, returns `traits::to_int_type(*gptr())` and
1955
  increments the next pointer for the input sequence.
1956
 
1957
  ``` cpp
1958
  int_type sgetc();
 
1971
 
1972
  ``` cpp
1973
  int_type sputbackc(char_type c);
1974
  ```
1975
 
1976
+ *Effects:* If the input sequence putback position is not available, or
1977
  if `traits::eq(c, gptr()[-1])` is `false`, returns
1978
  `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
1979
  pointer for the input sequence and returns
1980
  `traits::to_int_type(*gptr())`.
1981
 
1982
  ``` cpp
1983
  int_type sungetc();
1984
  ```
1985
 
1986
+ *Effects:* If the input sequence putback position is not available,
1987
  returns `pbackfail()`. Otherwise, decrements the next pointer for the
1988
  input sequence and returns `traits::to_int_type(*gptr())`.
1989
 
1990
  ##### Put area <a id="streambuf.pub.put">[[streambuf.pub.put]]</a>
1991
 
1992
  ``` cpp
1993
  int_type sputc(char_type c);
1994
  ```
1995
 
1996
+ *Effects:* If the output sequence write position is not available,
1997
  returns `overflow(traits::to_int_type(c))`. Otherwise, stores `c` at the
1998
  next pointer for the output sequence, increments the pointer, and
1999
  returns `traits::to_int_type(c)`.
2000
 
2001
  ``` cpp
2002
  streamsize sputn(const char_type* s, streamsize n);
2003
  ```
2004
 
2005
  *Returns:* `xsputn(s, n)`.
2006
 
2007
+ #### Protected member functions <a id="streambuf.protected">[[streambuf.protected]]</a>
2008
 
2009
  ##### Assignment <a id="streambuf.assign">[[streambuf.assign]]</a>
2010
 
2011
  ``` cpp
2012
  basic_streambuf& operator=(const basic_streambuf& rhs);
2013
  ```
2014
 
2015
+ *Ensures:*
 
 
2016
 
2017
  - `eback() == rhs.eback()`
2018
  - `gptr() == rhs.gptr()`
2019
  - `egptr() == rhs.egptr()`
2020
  - `pbase() == rhs.pbase()`
 
2058
 
2059
  ``` cpp
2060
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
2061
  ```
2062
 
2063
+ *Ensures:* `gbeg == eback()`, `gnext == gptr()`, and `gend == egptr()`
2064
+ are all `true`.
2065
 
2066
  ##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
2067
 
2068
  ``` cpp
2069
  char_type* pbase() const;
 
2091
 
2092
  ``` cpp
2093
  void setp(char_type* pbeg, char_type* pend);
2094
  ```
2095
 
2096
+ *Ensures:* `pbeg == pbase()`, `pbeg == pptr()`, and `pend == epptr()`
2097
+ are all `true`.
2098
 
2099
+ #### Virtual functions <a id="streambuf.virtuals">[[streambuf.virtuals]]</a>
2100
 
2101
  ##### Locales <a id="streambuf.virt.locales">[[streambuf.virt.locales]]</a>
2102
 
2103
  ``` cpp
2104
  void imbue(const locale&);
 
2159
  is, if `pbase()` is non-null the characters between `pbase()` and
2160
  `pptr()` are written to the controlled sequence. The pointers may then
2161
  be reset as appropriate.
2162
 
2163
  *Returns:* `-1` on failure. What constitutes failure is determined by
2164
+ each derived class [[filebuf.virtuals]].
2165
 
2166
  *Default behavior:* Returns zero.
2167
 
2168
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
2169
 
 
2200
  ``` cpp
2201
  int_type underflow();
2202
  ```
2203
 
2204
  *Remarks:* The public members of `basic_streambuf` call this virtual
2205
+ function only if `gptr()` is null or `gptr() >= egptr()`.
2206
 
2207
  *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
2208
  of the *pending sequence*, without moving the input sequence position
2209
  past it. If the pending sequence is null then the function returns
2210
  `traits::eof()` to indicate failure.
 
2242
 
2243
  ``` cpp
2244
  int_type uflow();
2245
  ```
2246
 
2247
+ *Preconditions:* The constraints are the same as for `underflow()`,
2248
+ except that the result character is transferred from the pending
2249
+ sequence to the backup sequence, and the pending sequence is not empty
2250
  before the transfer.
2251
 
2252
  *Default behavior:* Calls `underflow()`. If `underflow()` returns
2253
  `traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
2254
  of `traits::to_int_type(*gptr())` and increment the value of the next
 
2275
  is determined.
2276
  - If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
2277
  is prepended. Whether the input sequence is backed up or modified in
2278
  any other way is unspecified.
2279
 
2280
+ *Ensures:* On return, the constraints of `gptr()`, `eback()`, and
2281
  `pptr()` are the same as for `underflow()`.
2282
 
2283
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
2284
  because the input sequence could not be backed up, or if for some other
2285
  reason the pointers could not be set consistent with the constraints.
 
2311
 
2312
  *Effects:* Consumes some initial subsequence of the characters of the
2313
  *pending sequence*. The pending sequence is defined as the concatenation
2314
  of
2315
 
2316
+ - the empty sequence if `pbase()` is null, otherwise the
2317
  `pptr() - pbase()` characters beginning at `pbase()`, followed by
2318
  - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
2319
  `true`, otherwise the sequence consisting of `c`.
2320
 
2321
  *Remarks:* The member functions `sputc()` and `sputn()` call this
2322
  function in case that no room can be found in the put buffer enough to
2323
  accommodate the argument character sequence.
2324
 
2325
+ *Preconditions:* Every overriding definition of this virtual function
2326
+ obeys the following constraints:
2327
 
2328
+ - The effect of consuming a character on the associated output sequence
2329
+ is specified.[^16]
2330
+ - Let `r` be the number of characters in the pending sequence not
2331
+ consumed. If `r` is nonzero then `pbase()` and `pptr()` are set so
2332
+ that: `pptr() - pbase() == r` and the `r` characters starting at
2333
  `pbase()` are the associated output stream. In case `r` is zero (all
2334
  characters of the pending sequence have been consumed) then either
2335
+ `pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both set
2336
+ to the same non-null value.
2337
+ - The function may fail if either appending some character to the
2338
  associated output stream fails or if it is unable to establish
2339
  `pbase()` and `pptr()` according to the above rules.
2340
 
2341
  *Returns:* `traits::eof()` or throws an exception if the function fails.
2342
 
 
2386
  template<class charT, class traits>
2387
  basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
2388
  template<class charT, class traits>
2389
  basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
2390
 
2391
+ template<class charT, class traits>
2392
+ basic_ostream<charT, traits>& emit_on_flush(basic_ostream<charT, traits>& os);
2393
+ template<class charT, class traits>
2394
+ basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
2395
+ template<class charT, class traits>
2396
+ basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
2397
+
2398
  template<class charT, class traits, class T>
2399
  basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
2400
  }
2401
  ```
2402
 
 
2406
  namespace std {
2407
  // types T1, T2, ... are unspecified implementation types
2408
  T1 resetiosflags(ios_base::fmtflags mask);
2409
  T2 setiosflags (ios_base::fmtflags mask);
2410
  T3 setbase(int base);
2411
+ template<class charT> T4 setfill(charT c);
2412
  T5 setprecision(int n);
2413
  T6 setw(int n);
2414
  template<class moneyT> T7 get_money(moneyT& mon, bool intl = false);
2415
  template<class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
2416
  template<class charT> T9 get_time(struct tm* tmb, const charT* fmt);
 
2444
  ``` cpp
2445
  namespace std {
2446
  template<class charT, class traits = char_traits<charT>>
2447
  class basic_istream : virtual public basic_ios<charT, traits> {
2448
  public:
2449
+ // types (inherited from basic_ios[ios])
2450
  using char_type = charT;
2451
  using int_type = typename traits::int_type;
2452
  using pos_type = typename traits::pos_type;
2453
  using off_type = typename traits::off_type;
2454
  using traits_type = traits;
2455
 
2456
  // [istream.cons], constructor/destructor
2457
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2458
  virtual ~basic_istream();
2459
 
2460
+ // [istream.sentry], prefix/suffix
2461
  class sentry;
2462
 
2463
  // [istream.formatted], formatted input
2464
  basic_istream<charT, traits>&
2465
  operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
 
2509
  basic_istream<charT, traits>& seekg(pos_type);
2510
  basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
2511
 
2512
  protected:
2513
  // [istream.cons], copy/move constructor
2514
+ basic_istream(const basic_istream&) = delete;
2515
  basic_istream(basic_istream&& rhs);
2516
 
2517
  // [istream.assign], assign and swap
2518
+ basic_istream& operator=(const basic_istream&) = delete;
2519
  basic_istream& operator=(basic_istream&& rhs);
2520
  void swap(basic_istream& rhs);
2521
  };
2522
 
2523
  // [istream.extractors], character extraction templates
 
2526
  template<class traits>
2527
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char&);
2528
  template<class traits>
2529
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char&);
2530
 
2531
+ template<class charT, class traits, size_t N>
2532
+ basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT(&)[N]);
2533
+ template<class traits, size_t N>
2534
+ basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char(&)[N]);
2535
+ template<class traits, size_t N>
2536
+ basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char(&)[N]);
2537
  }
2538
  ```
2539
 
2540
  The class template `basic_istream` defines a number of member function
2541
  signatures that assist in reading and interpreting input from sequences
 
2548
  or `rdbuf()->sgetc()`. They may use other public members of `istream`.
2549
 
2550
  If `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`,
2551
  then the input function, except as explicitly noted otherwise, completes
2552
  its actions and does `setstate(eofbit)`, which may throw
2553
+ `ios_base::failure` [[iostate.flags]], before returning.
2554
 
2555
  If one of these called functions throws an exception, then unless
2556
+ explicitly noted otherwise, the input function sets `badbit` in the
2557
+ error state. If `badbit` is set in `exceptions()`, the input function
2558
+ rethrows the exception without completing its actions, otherwise it does
2559
+ not throw anything and proceeds as if the called function had returned a
2560
  failure indication.
2561
 
2562
+ ##### Constructors <a id="istream.cons">[[istream.cons]]</a>
2563
 
2564
  ``` cpp
2565
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2566
  ```
2567
 
2568
+ *Effects:* Initializes the base class subobject with
2569
+ `basic_ios::init(sb)` [[basic.ios.cons]].
 
2570
 
2571
+ *Ensures:* `gcount() == 0`.
2572
 
2573
  ``` cpp
2574
  basic_istream(basic_istream&& rhs);
2575
  ```
2576
 
2577
+ *Effects:* Default constructs the base class, copies the `gcount()` from
2578
+ `rhs`, calls `basic_ios<charT, traits>::move(rhs)` to initialize the
2579
+ base class, and sets the `gcount()` for `rhs` to 0.
 
2580
 
2581
  ``` cpp
2582
  virtual ~basic_istream();
2583
  ```
2584
 
 
 
2585
  *Remarks:* Does not perform any operations of `rdbuf()`.
2586
 
2587
+ ##### Assignment and swap <a id="istream.assign">[[istream.assign]]</a>
2588
 
2589
  ``` cpp
2590
  basic_istream& operator=(basic_istream&& rhs);
2591
  ```
2592
 
2593
+ *Effects:* Equivalent to: `swap(rhs)`.
2594
 
2595
  *Returns:* `*this`.
2596
 
2597
  ``` cpp
2598
  void swap(basic_istream& rhs);
2599
  ```
2600
 
2601
  *Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`. Exchanges the
2602
  values returned by `gcount()` and `rhs.gcount()`.
2603
 
2604
+ ##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
2605
 
2606
  ``` cpp
2607
  namespace std {
2608
  template<class charT, class traits = char_traits<charT>>
2609
  class basic_istream<charT, traits>::sentry {
 
2610
  bool ok_; // exposition only
2611
  public:
2612
  explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
2613
  ~sentry();
2614
  explicit operator bool() const { return ok_; }
 
2659
  ```
2660
 
2661
  If, after any preparation is completed, `is.good()` is `true`,
2662
  `ok_ != false` otherwise, `ok_ == false`. During preparation, the
2663
  constructor may call `setstate(failbit)` (which may throw
2664
+ `ios_base::failure` [[iostate.flags]]).[^19]
2665
 
2666
  ``` cpp
2667
  ~sentry();
2668
  ```
2669
 
 
2671
 
2672
  ``` cpp
2673
  explicit operator bool() const;
2674
  ```
2675
 
2676
+ *Returns:* `ok_`.
2677
 
2678
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2679
 
2680
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
2681
 
2682
  Each formatted input function begins execution by constructing an object
2683
  of class `sentry` with the `noskipws` (second) argument `false`. If the
2684
  `sentry` object returns `true`, when converted to a value of type
2685
  `bool`, the function endeavors to obtain the requested input. If an
2686
+ exception is thrown during input then `ios_base::badbit` is turned
2687
+ on[^20] in `*this`’s error state. If `(exceptions()&badbit) != 0` then
2688
+ the exception is rethrown. In any case, the formatted input function
2689
  destroys the `sentry` object. If no exception has been thrown, it
2690
  returns `*this`.
2691
 
2692
  ##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
2693
 
 
2704
  operator>>(bool& val);
2705
  operator>>(void*& val);
2706
  ```
2707
 
2708
  As in the case of the inserters, these extractors depend on the locale’s
2709
+ `num_get<>` [[locale.num.get]] object to perform parsing the input
2710
  stream data. These extractors behave as formatted input functions (as
2711
  described in  [[istream.formatted.reqmts]]). After a sentry object is
2712
  constructed, the conversion occurs as if performed by the following code
2713
  fragment:
2714
 
 
2808
  in  [[istream.formatted.reqmts]]).
2809
 
2810
  *Returns:* `*this`.
2811
 
2812
  ``` cpp
2813
+ template<class charT, class traits, size_t N>
2814
+ basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT (&s)[N]);
2815
+ template<class traits, size_t N>
2816
+ basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char (&s)[N]);
2817
+ template<class traits, size_t N>
2818
+ basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char (&s)[N]);
2819
  ```
2820
 
2821
  *Effects:* Behaves like a formatted input member (as described
2822
  in  [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
2823
+ constructed, `operator>>` extracts characters and stores them into `s`.
2824
+ If `width()` is greater than zero, `n` is `min(size_t(width()), N)`.
2825
+ Otherwise `n` is `N`. `n` is the maximum number of characters stored.
 
 
 
2826
 
2827
  Characters are extracted and stored until any of the following occurs:
2828
 
2829
  - `n-1` characters are stored;
2830
  - end of file occurs on the input sequence;
 
2834
  `operator>>` then stores a null byte (`charT()`) in the next position,
2835
  which may be the first position if no characters were extracted.
2836
  `operator>>` then calls `width(0)`.
2837
 
2838
  If the function extracted no characters, it calls `setstate(failbit)`,
2839
+ which may throw `ios_base::failure` [[iostate.flags]].
2840
 
2841
  *Returns:* `in`.
2842
 
2843
  ``` cpp
2844
  template<class charT, class traits>
 
2858
 
2859
  ``` cpp
2860
  basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
2861
  ```
2862
 
2863
+ *Effects:* Behaves as an unformatted input
2864
+ function [[istream.unformatted]]. If `sb` is null, calls
2865
+ `setstate(failbit)`, which may throw `ios_base::failure`
2866
+ [[iostate.flags]]. After a sentry object is constructed, extracts
2867
+ characters from `*this` and inserts them in the output sequence
2868
+ controlled by `sb`. Characters are extracted and inserted until any of
2869
+ the following occurs:
2870
 
2871
  - end-of-file occurs on the input sequence;
2872
  - inserting in the output sequence fails (in which case the character to
2873
  be inserted is not extracted);
2874
  - an exception occurs (in which case the exception is caught).
2875
 
2876
  If the function inserts no characters, it calls `setstate(failbit)`,
2877
+ which may throw `ios_base::failure` [[iostate.flags]]. If it inserted no
2878
+ characters because it caught an exception thrown while extracting
2879
+ characters from `*this` and `failbit` is set in `exceptions()`
2880
+ [[iostate.flags]], then the caught exception is rethrown.
 
2881
 
2882
  *Returns:* `*this`.
2883
 
2884
  #### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
2885
 
 
2892
  a value of type `bool`, the function returns without attempting to
2893
  obtain any input. In either case the number of extracted characters is
2894
  set to 0; unformatted input functions taking a character array of
2895
  nonzero size as an argument shall also store a null character (using
2896
  `charT()`) in the first location of the array. If an exception is thrown
2897
+ during input then `ios_base::badbit` is turned on[^23] in `*this`’s
2898
+ error state. (Exceptions thrown from `basic_ios<>::clear()` are not
2899
+ caught or rethrown.) If `(exceptions()&badbit) != 0` then the exception
2900
+ is rethrown. It also counts the number of characters extracted. If no
2901
  exception has been thrown it ends by storing the count in a member
2902
  object and returning the value specified. In any event the `sentry`
2903
  object is destroyed before leaving the unformatted input function.
2904
 
2905
  ``` cpp
 
2917
  ```
2918
 
2919
  *Effects:* Behaves as an unformatted input function (as described
2920
  above). After constructing a sentry object, extracts a character `c`, if
2921
  one is available. Otherwise, the function calls `setstate(failbit)`,
2922
+ which may throw `ios_base::failure` [[iostate.flags]].
2923
 
2924
  *Returns:* `c` if available, otherwise `traits::eof()`.
2925
 
2926
  ``` cpp
2927
  basic_istream<charT, traits>& get(char_type& c);
2928
  ```
2929
 
2930
  *Effects:* Behaves as an unformatted input function (as described
2931
  above). After constructing a sentry object, extracts a character, if one
2932
  is available, and assigns it to `c`.[^24] Otherwise, the function calls
2933
+ `setstate(failbit)` (which may throw `ios_base::failure`
2934
+ [[iostate.flags]]).
2935
 
2936
  *Returns:* `*this`.
2937
 
2938
  ``` cpp
2939
  basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
 
2950
  calls `setstate(eofbit)`);
2951
  - `traits::eq(c, delim)` for the next available input character `c` (in
2952
  which case `c` is not extracted).
2953
 
2954
  If the function stores no characters, it calls `setstate(failbit)`
2955
+ (which may throw `ios_base::failure` [[iostate.flags]]). In any case, if
2956
+ `n` is greater than zero it then stores a null character into the next
2957
+ successive location of the array.
2958
 
2959
  *Returns:* `*this`.
2960
 
2961
  ``` cpp
2962
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
 
2982
  which case `c` is not extracted);
2983
  - an exception occurs (in which case, the exception is caught but not
2984
  rethrown).
2985
 
2986
  If the function inserts no characters, it calls `setstate(failbit)`,
2987
+ which may throw `ios_base::failure` [[iostate.flags]].
2988
 
2989
  *Returns:* `*this`.
2990
 
2991
  ``` cpp
2992
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
 
3015
  the function calls `setstate(failbit)`).
3016
 
3017
  These conditions are tested in the order shown.[^28]
3018
 
3019
  If the function extracts no characters, it calls `setstate(failbit)`
3020
+ (which may throw `ios_base::failure` [[iostate.flags]]).[^29]
3021
 
3022
  In any case, if `n` is greater than zero, it then stores a null
3023
  character (using `charT()`) into the next successive location of the
3024
  array.
3025
 
 
3067
  *Effects:* Behaves as an unformatted input function (as described
3068
  above). After constructing a sentry object, extracts characters and
3069
  discards them. Characters are extracted until any of the following
3070
  occurs:
3071
 
3072
+ - `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
3073
  characters have been extracted so far
3074
  - end-of-file occurs on the input sequence (in which case the function
3075
+ calls `setstate(eofbit)`, which may throw `ios_base::failure`
3076
+ [[iostate.flags]]);
3077
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
3078
  available input character `c` (in which case `c` is extracted).
3079
 
3080
  *Remarks:* The last condition will never occur if
3081
  `traits::eq_int_type(delim, traits::eof())`.
 
3105
  extracted and stored until either of the following occurs:
3106
 
3107
  - `n` characters are stored;
3108
  - end-of-file occurs on the input sequence (in which case the function
3109
  calls `setstate(failbit | eofbit)`, which may throw
3110
+ `ios_base::failure` [[iostate.flags]]).
3111
 
3112
  *Returns:* `*this`.
3113
 
3114
  ``` cpp
3115
  streamsize readsome(char_type* s, streamsize n);
 
3119
  above). After constructing a sentry object, if `!good()` calls
3120
  `setstate(failbit)` which may throw an exception, and return. Otherwise
3121
  extracts characters and stores them into successive locations of an
3122
  array whose first element is designated by `s`. If
3123
  `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
3124
+ `ios_base::failure` [[iostate.flags]]), and extracts no characters;
3125
 
3126
  - If `rdbuf()->in_avail() == 0`, extracts no characters
3127
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
3128
 
3129
  *Returns:* The number of characters extracted.
 
3134
 
3135
  *Effects:* Behaves as an unformatted input function (as described
3136
  above), except that the function first clears `eofbit`. After
3137
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
3138
  which may throw an exception, and return. If `rdbuf()` is not null,
3139
+ calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
3140
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3141
+ `ios_base::failure` [[iostate.flags]]).
3142
 
3143
  [*Note 1*: This function extracts no characters, so the value returned
3144
  by the next call to `gcount()` is 0. — *end note*]
3145
 
3146
  *Returns:* `*this`.
 
3151
 
3152
  *Effects:* Behaves as an unformatted input function (as described
3153
  above), except that the function first clears `eofbit`. After
3154
  constructing a sentry object, if `!good()` calls `setstate(failbit)`
3155
  which may throw an exception, and return. If `rdbuf()` is not null,
3156
+ calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
3157
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3158
+ `ios_base::failure` [[iostate.flags]]).
3159
 
3160
  [*Note 2*: This function extracts no characters, so the value returned
3161
  by the next call to `gcount()` is 0. — *end note*]
3162
 
3163
  *Returns:* `*this`.
 
3170
  above), except that it does not count the number of characters extracted
3171
  and does not affect the value returned by subsequent calls to
3172
  `gcount()`. After constructing a sentry object, if `rdbuf()` is a null
3173
  pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
3174
  that function returns `-1` calls `setstate(badbit)` (which may throw
3175
+ `ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
3176
  returns zero.
3177
 
3178
  ``` cpp
3179
  pos_type tellg();
3180
  ```
 
3218
 
3219
  *Returns:* `*this`.
3220
 
3221
  #### Standard `basic_istream` manipulators <a id="istream.manip">[[istream.manip]]</a>
3222
 
3223
+ Each instantiation of the function template specified in this subclause
3224
+ is a designated addressable function [[namespace.std]].
3225
+
3226
  ``` cpp
3227
  template<class charT, class traits>
3228
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
3229
  ```
3230
 
3231
+ *Effects:* Behaves as an unformatted input
3232
+ function [[istream.unformatted]], except that it does not count the
3233
+ number of characters extracted and does not affect the value returned by
3234
+ subsequent calls to `is.gcount()`. After constructing a sentry object
3235
  extracts characters as long as the next available character `c` is
3236
  whitespace or until there are no more characters in the sequence.
3237
  Whitespace characters are distinguished with the same criterion as used
3238
+ by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
3239
  characters because there are no more available it sets `eofbit`, but not
3240
  `failbit`.
3241
 
3242
  *Returns:* `is`.
3243
 
3244
  #### Rvalue stream extraction <a id="istream.rvalue">[[istream.rvalue]]</a>
3245
 
3246
  ``` cpp
3247
+ template<class Istream, class T>
3248
+ Istream&& operator>>(Istream&& is, T&& x);
3249
  ```
3250
 
3251
+ *Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
3252
+ when treated as an unevaluated operand and `Istream` is publicly and
3253
+ unambiguously derived from `ios_base`.
3254
+
3255
  *Effects:* Equivalent to:
3256
 
3257
  ``` cpp
3258
  is >> std::forward<T>(x);
3259
+ return std::move(is);
3260
  ```
3261
 
 
 
 
3262
  #### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
3263
 
3264
  ``` cpp
3265
  namespace std {
3266
  template<class charT, class traits = char_traits<charT>>
 
3280
  // [iostream.dest], destructor
3281
  virtual ~basic_iostream();
3282
 
3283
  protected:
3284
  // [iostream.cons], constructor
3285
+ basic_iostream(const basic_iostream&) = delete;
3286
  basic_iostream(basic_iostream&& rhs);
3287
 
3288
  // [iostream.assign], assign and swap
3289
+ basic_iostream& operator=(const basic_iostream&) = delete;
3290
  basic_iostream& operator=(basic_iostream&& rhs);
3291
  void swap(basic_iostream& rhs);
3292
  };
3293
  }
3294
  ```
3295
 
3296
  The class template `basic_iostream` inherits a number of functions that
3297
  allow reading input and writing output to sequences controlled by a
3298
  stream buffer.
3299
 
3300
+ ##### Constructors <a id="iostream.cons">[[iostream.cons]]</a>
3301
 
3302
  ``` cpp
3303
  explicit basic_iostream(basic_streambuf<charT, traits>* sb);
3304
  ```
3305
 
3306
+ *Effects:* Initializes the base class subobjects with
3307
+ `basic_istream<charT, traits>(sb)` [[istream]] and
3308
+ `basic_ostream<charT, traits>(sb)` [[ostream]].
 
3309
 
3310
+ *Ensures:* `rdbuf() == sb` and `gcount() == 0`.
3311
 
3312
  ``` cpp
3313
  basic_iostream(basic_iostream&& rhs);
3314
  ```
3315
 
3316
  *Effects:* Move constructs from the rvalue `rhs` by constructing the
3317
  `basic_istream` base class with `move(rhs)`.
3318
 
3319
+ ##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
3320
 
3321
  ``` cpp
3322
  virtual ~basic_iostream();
3323
  ```
3324
 
 
 
3325
  *Remarks:* Does not perform any operations on `rdbuf()`.
3326
 
3327
+ ##### Assignment and swap <a id="iostream.assign">[[iostream.assign]]</a>
3328
 
3329
  ``` cpp
3330
  basic_iostream& operator=(basic_iostream&& rhs);
3331
  ```
3332
 
3333
+ *Effects:* Equivalent to: `swap(rhs)`.
3334
 
3335
  ``` cpp
3336
  void swap(basic_iostream& rhs);
3337
  ```
3338
 
 
3349
  ``` cpp
3350
  namespace std {
3351
  template<class charT, class traits = char_traits<charT>>
3352
  class basic_ostream : virtual public basic_ios<charT, traits> {
3353
  public:
3354
+ // types (inherited from basic_ios[ios])
3355
  using char_type = charT;
3356
  using int_type = typename traits::int_type;
3357
  using pos_type = typename traits::pos_type;
3358
  using off_type = typename traits::off_type;
3359
  using traits_type = traits;
3360
 
3361
  // [ostream.cons], constructor/destructor
3362
  explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
3363
  virtual ~basic_ostream();
3364
 
3365
+ // [ostream.sentry], prefix/suffix
3366
  class sentry;
3367
 
3368
  // [ostream.formatted], formatted output
3369
  basic_ostream<charT, traits>&
3370
  operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
 
3401
  basic_ostream<charT, traits>& seekp(pos_type);
3402
  basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
3403
 
3404
  protected:
3405
  // [ostream.cons], copy/move constructor
3406
+ basic_ostream(const basic_ostream&) = delete;
3407
  basic_ostream(basic_ostream&& rhs);
3408
 
3409
  // [ostream.assign], assign and swap
3410
+ basic_ostream& operator=(const basic_ostream&) = delete;
3411
  basic_ostream& operator=(basic_ostream&& rhs);
3412
  void swap(basic_ostream& rhs);
3413
  };
3414
 
3415
  // [ostream.inserters.character], character inserters
 
3423
  template<class traits>
3424
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, signed char);
3425
  template<class traits>
3426
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, unsigned char);
3427
 
3428
+ template<class traits>
3429
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, wchar_t) = delete;
3430
+ template<class traits>
3431
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char8_t) = delete;
3432
+ template<class traits>
3433
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char16_t) = delete;
3434
+ template<class traits>
3435
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char32_t) = delete;
3436
+ template<class traits>
3437
+ basic_ostream<wchar_t, traits>&
3438
+ operator<<(basic_ostream<wchar_t, traits>&, char8_t) = delete;
3439
+ template<class traits>
3440
+ basic_ostream<wchar_t, traits>&
3441
+ operator<<(basic_ostream<wchar_t, traits>&, char16_t) = delete;
3442
+ template<class traits>
3443
+ basic_ostream<wchar_t, traits>&
3444
+ operator<<(basic_ostream<wchar_t, traits>&, char32_t) = delete;
3445
+
3446
  template<class charT, class traits>
3447
  basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const charT*);
3448
  template<class charT, class traits>
3449
  basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const char*);
3450
  template<class traits>
 
3452
 
3453
  template<class traits>
3454
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const signed char*);
3455
  template<class traits>
3456
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const unsigned char*);
3457
+
3458
+ template<class traits>
3459
+ basic_ostream<char, traits>&
3460
+ operator<<(basic_ostream<char, traits>&, const wchar_t*) = delete;
3461
+ template<class traits>
3462
+ basic_ostream<char, traits>&
3463
+ operator<<(basic_ostream<char, traits>&, const char8_t*) = delete;
3464
+ template<class traits>
3465
+ basic_ostream<char, traits>&
3466
+ operator<<(basic_ostream<char, traits>&, const char16_t*) = delete;
3467
+ template<class traits>
3468
+ basic_ostream<char, traits>&
3469
+ operator<<(basic_ostream<char, traits>&, const char32_t*) = delete;
3470
+ template<class traits>
3471
+ basic_ostream<wchar_t, traits>&
3472
+ operator<<(basic_ostream<wchar_t, traits>&, const char8_t*) = delete;
3473
+ template<class traits>
3474
+ basic_ostream<wchar_t, traits>&
3475
+ operator<<(basic_ostream<wchar_t, traits>&, const char16_t*) = delete;
3476
+ template<class traits>
3477
+ basic_ostream<wchar_t, traits>&
3478
+ operator<<(basic_ostream<wchar_t, traits>&, const char32_t*) = delete;
3479
  }
3480
  ```
3481
 
3482
  The class template `basic_ostream` defines a number of member function
3483
  signatures that assist in formatting and writing output to output
 
3490
  `rdbuf()->sputc(int_type)`. They may use other public members of
3491
  `basic_ostream` except that they shall not invoke any virtual members of
3492
  `rdbuf()` except `overflow()`, `xsputn()`, and `sync()`.
3493
 
3494
  If one of these called functions throws an exception, then unless
3495
+ explicitly noted otherwise the output function sets `badbit` in the
3496
+ error state. If `badbit` is set in `exceptions()`, the output function
3497
+ rethrows the exception without completing its actions, otherwise it does
3498
+ not throw anything and proceeds as if the called function had returned a
3499
+ failure indication.
3500
 
3501
+ [*Note 1*: The deleted overloads of `operator<<` prevent formatting
3502
+ characters as integers and strings as pointers. — *end note*]
3503
+
3504
+ ##### Constructors <a id="ostream.cons">[[ostream.cons]]</a>
3505
 
3506
  ``` cpp
3507
  explicit basic_ostream(basic_streambuf<charT, traits>* sb);
3508
  ```
3509
 
3510
+ *Effects:* Initializes the base class subobject with
3511
+ `basic_ios<charT, traits>::init(sb)` [[basic.ios.cons]].
 
3512
 
3513
+ *Ensures:* `rdbuf() == sb`.
3514
 
3515
  ``` cpp
3516
  basic_ostream(basic_ostream&& rhs);
3517
  ```
3518
 
 
3522
 
3523
  ``` cpp
3524
  virtual ~basic_ostream();
3525
  ```
3526
 
 
 
3527
  *Remarks:* Does not perform any operations on `rdbuf()`.
3528
 
3529
+ ##### Assignment and swap <a id="ostream.assign">[[ostream.assign]]</a>
3530
 
3531
  ``` cpp
3532
  basic_ostream& operator=(basic_ostream&& rhs);
3533
  ```
3534
 
3535
+ *Effects:* Equivalent to: `swap(rhs)`.
3536
 
3537
  *Returns:* `*this`.
3538
 
3539
  ``` cpp
3540
  void swap(basic_ostream& rhs);
3541
  ```
3542
 
3543
  *Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`.
3544
 
3545
+ ##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
3546
 
3547
  ``` cpp
3548
  namespace std {
3549
  template<class charT, class traits = char_traits<charT>>
3550
  class basic_ostream<charT, traits>::sentry {
 
3571
  If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^31]
3572
 
3573
  If, after any preparation is completed, `os.good()` is `true`,
3574
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
3575
  constructor may call `setstate(failbit)` (which may throw
3576
+ `ios_base::failure` [[iostate.flags]]).[^32]
3577
 
3578
  ``` cpp
3579
  ~sentry();
3580
  ```
3581
 
 
3588
  explicit operator bool() const;
3589
  ```
3590
 
3591
  *Effects:* Returns `ok_`.
3592
 
3593
+ ##### Seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
3594
 
3595
  Each seek member function begins execution by constructing an object of
3596
  class `sentry`. It returns by destroying the `sentry` object.
3597
 
3598
  ``` cpp
 
3631
  Each formatted output function begins execution by constructing an
3632
  object of class `sentry`. If this object returns `true` when converted
3633
  to a value of type `bool`, the function endeavors to generate the
3634
  requested output. If the generation fails, then the formatted output
3635
  function does `setstate(ios_base::failbit)`, which might throw an
3636
+ exception. If an exception is thrown during output, then
3637
+ `ios_base::badbit` is turned on[^33] in `*this`’s error state. If
3638
  `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
3639
  not an exception is thrown, the `sentry` object is destroyed before
3640
  leaving the formatted output function. If no exception is thrown, the
3641
  result of the formatted output function is `*this`.
3642
 
 
3777
 
3778
  ``` cpp
3779
  basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
3780
  ```
3781
 
3782
+ *Effects:* Behaves as an unformatted output
3783
+ function [[ostream.unformatted]]. After the sentry object is
3784
+ constructed, if `sb` is null calls `setstate(badbit)` (which may throw
3785
  `ios_base::failure`).
3786
 
3787
  Gets characters from `sb` and inserts them in `*this`. Characters are
3788
  read from `sb` and inserted until any of the following occurs:
3789
 
 
3791
  - inserting in the output sequence fails (in which case the character to
3792
  be inserted is not extracted);
3793
  - an exception occurs while getting a character from `sb`.
3794
 
3795
  If the function inserts no characters, it calls `setstate(failbit)`
3796
+ (which may throw `ios_base::failure` [[iostate.flags]]). If an exception
3797
+ was thrown while extracting a character, the function sets `failbit` in
3798
+ the error state, and if `failbit` is set in `exceptions()` the caught
3799
+ exception is rethrown.
3800
 
3801
  *Returns:* `*this`.
3802
 
3803
  ``` cpp
3804
  basic_ostream<charT, traits>& operator<<(nullptr_t);
 
3808
 
3809
  ``` cpp
3810
  return *this << s;
3811
  ```
3812
 
3813
+ where `s` is an *implementation-defined* NTCTS [[defns.ntcts]].
3814
 
3815
  ##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
3816
 
3817
  ``` cpp
3818
  template<class charT, class traits>
 
3828
  template<class traits>
3829
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
3830
  ```
3831
 
3832
  *Effects:* Behaves as a formatted output
3833
+ function [[ostream.formatted.reqmts]] of `out`. Constructs a character
3834
+ sequence `seq`. If `c` has type `char` and the character type of the
3835
+ stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
3836
+ `seq` consists of `c`. Determines padding for `seq` as described
3837
+ in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
3838
+ `os.width(0)`.
3839
 
3840
  *Returns:* `out`.
3841
 
3842
  ``` cpp
3843
  template<class charT, class traits>
 
3851
  template<class traits>
3852
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
3853
  const unsigned char* s);
3854
  ```
3855
 
3856
+ *Preconditions:* `s` is not a null pointer.
3857
 
3858
  *Effects:* Behaves like a formatted inserter (as described
3859
  in  [[ostream.formatted.reqmts]]) of `out`. Creates a character sequence
3860
  `seq` of `n` characters starting at `s`, each widened using
3861
+ `out.widen()` [[basic.ios.members]], where `n` is the number that would
3862
+ be computed as if by:
3863
 
3864
  - `traits::length(s)` for the overload where the first argument is of
3865
  type `basic_ostream<charT, traits>&` and the second is of type
3866
  `const charT*`, and also for the overload where the first argument is
3867
  of type `basic_ostream<char, traits>&` and the second is of type
 
3882
 
3883
  Each unformatted output function begins execution by constructing an
3884
  object of class `sentry`. If this object returns `true`, while
3885
  converting to a value of type `bool`, the function endeavors to generate
3886
  the requested output. If an exception is thrown during output, then
3887
+ `ios_base::badbit` is turned on[^36] in `*this`’s error state. If
3888
  `(exceptions() & badbit) != 0` then the exception is rethrown. In any
3889
  case, the unformatted output function ends by destroying the sentry
3890
  object, then, if no exception was thrown, returning the value specified
3891
  for the unformatted output function.
3892
 
 
3896
 
3897
  *Effects:* Behaves as an unformatted output function (as described
3898
  above). After constructing a sentry object, inserts the character `c`,
3899
  if possible.[^37]
3900
 
3901
+ Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
3902
+ [[iostate.flags]]).
3903
 
3904
  *Returns:* `*this`.
3905
 
3906
  ``` cpp
3907
  basic_ostream& write(const char_type* s, streamsize n);
 
3913
  by `s`.[^38] Characters are inserted until either of the following
3914
  occurs:
3915
 
3916
  - `n` characters are inserted;
3917
  - inserting in the output sequence fails (in which case the function
3918
+ calls `setstate(badbit)`, which may throw `ios_base::failure`
3919
+ [[iostate.flags]]).
3920
 
3921
  *Returns:* `*this`.
3922
 
3923
  ``` cpp
3924
  basic_ostream& flush();
 
3926
 
3927
  *Effects:* Behaves as an unformatted output function (as described
3928
  above). If `rdbuf()` is not a null pointer, constructs a sentry object.
3929
  If this object returns `true` when converted to a value of type `bool`
3930
  the function calls `rdbuf()->pubsync()`. If that function returns -1
3931
+ calls `setstate(badbit)` (which may throw `ios_base::failure`
3932
+ [[iostate.flags]]). Otherwise, if the sentry object returns `false`,
3933
+ does nothing.
3934
 
3935
  *Returns:* `*this`.
3936
 
3937
+ #### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
3938
+
3939
+ Each instantiation of any of the function templates specified in this
3940
+ subclause is a designated addressable function [[namespace.std]].
3941
 
3942
  ``` cpp
3943
  template<class charT, class traits>
3944
  basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
3945
  ```
 
3965
 
3966
  *Effects:* Calls `os.flush()`.
3967
 
3968
  *Returns:* `os`.
3969
 
3970
+ ``` cpp
3971
+ template<class charT, class traits>
3972
+ basic_ostream<charT, traits>& emit_on_flush(basic_ostream<charT, traits>& os);
3973
+ ```
3974
+
3975
+ *Effects:* If `os.rdbuf()` is a
3976
+ `basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
3977
+ of exposition, calls `buf->set_emit_on_sync(true)`. Otherwise this
3978
+ manipulator has no effect.
3979
+
3980
+ [*Note 1*: To work around the issue that the `Allocator` template
3981
+ argument cannot be deduced, implementations can introduce an
3982
+ intermediate base class to `basic_syncbuf` that manages its
3983
+ `emit_on_sync` flag. — *end note*]
3984
+
3985
+ *Returns:* `os`.
3986
+
3987
+ ``` cpp
3988
+ template<class charT, class traits>
3989
+ basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
3990
+ ```
3991
+
3992
+ *Effects:* If `os.rdbuf()` is a
3993
+ `basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
3994
+ of exposition, calls `buf->set_emit_on_sync(false)`. Otherwise this
3995
+ manipulator has no effect.
3996
+
3997
+ *Returns:* `os`.
3998
+
3999
+ ``` cpp
4000
+ template<class charT, class traits>
4001
+ basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
4002
+ ```
4003
+
4004
+ *Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
4005
+ `basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
4006
+ of exposition, calls `buf->emit()`.
4007
+
4008
+ *Returns:* `os`.
4009
+
4010
  #### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
4011
 
4012
  ``` cpp
4013
+ template<class Ostream, class T>
4014
+ Ostream&& operator<<(Ostream&& os, const T& x);
4015
  ```
4016
 
4017
+ *Constraints:* The expression `os << x` is well-formed when treated as
4018
+ an unevaluated operand and `Ostream` is publicly and unambiguously
4019
+ derived from `ios_base`.
4020
+
4021
  *Effects:* As if by: `os << x;`
4022
 
4023
+ *Returns:* `std::move(os)`.
 
 
 
4024
 
4025
  ### Standard manipulators <a id="std.manip">[[std.manip]]</a>
4026
 
4027
  The header `<iomanip>` defines several functions that support extractors
4028
  and inserters that alter information maintained by class `ios_base` and
 
4044
  // reset specified flags
4045
  str.setf(ios_base::fmtflags(0), mask);
4046
  }
4047
  ```
4048
 
4049
+ The expression `out << resetiosflags(mask)` has type
4050
  `basic_ostream<charT, traits>&` and value `out`. The expression
4051
+ `in >> resetiosflags(mask)` has type `basic_istream<charT, traits>&` and
4052
+ value `in`.
4053
 
4054
  ``` cpp
4055
  unspecified setiosflags(ios_base::fmtflags mask);
4056
  ```
4057
 
 
4067
  // set specified flags
4068
  str.setf(mask);
4069
  }
4070
  ```
4071
 
4072
+ The expression `out << setiosflags(mask)` has type
4073
  `basic_ostream<charT, traits>&` and value `out`. The expression
4074
+ `in >> setiosflags(mask)` has type `basic_istream<charT, traits>&` and
4075
+ value `in`.
4076
 
4077
  ``` cpp
4078
  unspecified setbase(int base);
4079
  ```
4080
 
 
4093
  base == 16 ? ios_base::hex :
4094
  ios_base::fmtflags(0), ios_base::basefield);
4095
  }
4096
  ```
4097
 
4098
+ The expression `out << setbase(base)` has type
4099
  `basic_ostream<charT, traits>&` and value `out`. The expression
4100
+ `in >> setbase(base)` has type `basic_istream<charT, traits>&` and value
4101
+ `in`.
4102
 
4103
  ``` cpp
4104
  unspecified setfill(char_type c);
4105
  ```
4106
 
 
4115
  // set fill character
4116
  str.fill(c);
4117
  }
4118
  ```
4119
 
4120
+ The expression `out << setfill(c)` has type
4121
  `basic_ostream<charT, traits>&` and value `out`.
4122
 
4123
  ``` cpp
4124
  unspecified setprecision(int n);
4125
  ```
 
4136
  // set precision
4137
  str.precision(n);
4138
  }
4139
  ```
4140
 
4141
+ The expression `out << setprecision(n)` has type
4142
  `basic_ostream<charT, traits>&` and value `out`. The expression
4143
+ `in >> setprecision(n)` has type `basic_istream<charT, traits>&` and
4144
+ value `in`.
4145
 
4146
  ``` cpp
4147
  unspecified setw(int n);
4148
  ```
4149
 
 
4159
  // set width
4160
  str.width(n);
4161
  }
4162
  ```
4163
 
4164
+ The expression `out << setw(n)` has type `basic_ostream<charT, traits>&`
4165
+ and value `out`. The expression `in >> setw(n)` has type
4166
+ `basic_istream<charT, traits>&` and value `in`.
 
4167
 
4168
  ### Extended manipulators <a id="ext.manip">[[ext.manip]]</a>
4169
 
4170
  The header `<iomanip>` defines several functions that support extractors
4171
  and inserters that allow for the parsing and formatting of sequences and
 
4173
 
4174
  ``` cpp
4175
  template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
4176
  ```
4177
 
4178
+ *Mandates:* The type `moneyT` is either `long double` or a
4179
+ specialization of the `basic_string` template [[strings]].
4180
 
4181
  *Effects:* The expression `in >> get_money(mon, intl)` described below
4182
+ behaves as a formatted input function [[istream.formatted.reqmts]].
4183
 
4184
  *Returns:* An object of unspecified type such that if `in` is an object
4185
  of type `basic_istream<charT, traits>` then the expression
4186
  `in >> get_money(mon, intl)` behaves as if it called `f(in, mon, intl)`,
4187
  where the function `f` is defined as:
 
4200
  if (ios_base::goodbit != err)
4201
  str.setstate(err);
4202
  }
4203
  ```
4204
 
4205
+ The expression `in >> get_money(mon, intl)` has type
4206
  `basic_istream<charT, traits>&` and value `in`.
4207
 
4208
  ``` cpp
4209
  template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
4210
  ```
4211
 
4212
+ *Mandates:* The type `moneyT` is either `long double` or a
4213
+ specialization of the `basic_string` template [[strings]].
4214
 
4215
  *Returns:* An object of unspecified type such that if `out` is an object
4216
  of type `basic_ostream<charT, traits>` then the expression
4217
  `out << put_money(mon, intl)` behaves as a formatted output
4218
+ function [[ostream.formatted.reqmts]] that calls `f(out, mon, intl)`,
4219
  where the function `f` is defined as:
4220
 
4221
  ``` cpp
4222
  template<class charT, class traits, class moneyT>
4223
  void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
 
4226
 
4227
  const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
4228
  const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);
4229
 
4230
  if (end.failed())
4231
+ str.setstate(ios_base::badbit);
4232
  }
4233
  ```
4234
 
4235
+ The expression `out << put_money(mon, intl)` has type
4236
  `basic_ostream<charT, traits>&` and value `out`.
4237
 
4238
  ``` cpp
4239
  template<class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
4240
  ```
4241
 
4242
+ *Preconditions:* The argument `tmb` is a valid pointer to an object of
4243
+ type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
4244
+ is a valid range.
 
4245
 
4246
  *Returns:* An object of unspecified type such that if `in` is an object
4247
  of type `basic_istream<charT, traits>` then the expression
4248
  `in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
4249
  where the function `f` is defined as:
 
4263
  if (err != ios_base::goodbit)
4264
  str.setstate(err);
4265
  }
4266
  ```
4267
 
4268
+ The expression `in >> get_time(tmb, fmt)` has type
4269
  `basic_istream<charT, traits>&` and value `in`.
4270
 
4271
  ``` cpp
4272
  template<class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
4273
  ```
4274
 
4275
+ *Preconditions:* The argument `tmb` is a valid pointer to an object of
4276
+ type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
4277
+ is a valid range.
 
4278
 
4279
  *Returns:* An object of unspecified type such that if `out` is an object
4280
  of type `basic_ostream<charT, traits>` then the expression
4281
  `out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
4282
  where the function `f` is defined as:
 
4294
  if (end.failed())
4295
  str.setstate(ios_base::badbit);
4296
  }
4297
  ```
4298
 
4299
+ The expression `out << put_time(tmb, fmt)` has type
4300
  `basic_ostream<charT, traits>&` and value `out`.
4301
 
4302
  ### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
4303
 
4304
  [*Note 1*: Quoted manipulators provide string insertion and extraction
 
4321
  *Returns:* An object of unspecified type such that if `out` is an
4322
  instance of `basic_ostream` with member type `char_type` the same as
4323
  `charT` and with member type `traits_type`, which in the second and
4324
  third forms is the same as `traits`, then the expression
4325
  `out << quoted(s, delim, escape)` behaves as a formatted output
4326
+ function [[ostream.formatted.reqmts]] of `out`. This forms a character
4327
+ sequence `seq`, initially consisting of the following elements:
 
4328
 
4329
  - `delim`.
4330
  - Each character in `s`. If the character to be output is equal to
4331
  `escape` or `delim`, as determined by `traits_type::eq`, first output
4332
  `escape`.
 
4334
 
4335
  Let `x` be the number of elements initially in `seq`. Then padding is
4336
  determined for `seq` as described in  [[ostream.formatted.reqmts]],
4337
  `seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
4338
  `n` is the larger of `out.width()` and `x`, and `out.width(0)` is
4339
+ called. The expression `out << quoted(s, delim, escape)` has type
4340
  `basic_ostream<charT, traits>&` and value `out`.
4341
 
4342
  ``` cpp
4343
  template<class charT, class traits, class Allocator>
4344
  unspecified quoted(basic_string<charT, traits, Allocator>& s,
 
4349
 
4350
  - If `in` is an instance of `basic_istream` with member types
4351
  `char_type` and `traits_type` the same as `charT` and `traits`,
4352
  respectively, then the expression `in >> quoted(s, delim, escape)`
4353
  behaves as if it extracts the following characters from `in` using
4354
+ `operator>>(basic_istream<charT, traits>&, charT&)`
4355
+ [[istream.extractors]] which may throw `ios_base::failure`
4356
+ [[ios.failure]]:
4357
  - If the first character extracted is equal to `delim`, as determined
4358
  by `traits_type::eq`, then:
4359
  - Turn off the `skipws` flag.
4360
  - `s.clear()`
4361
  - Until an unescaped `delim` character is reached or `!in`, extract
 
4369
  `char_type` and `traits_type` the same as `charT` and `traits`,
4370
  respectively, then the expression `out << quoted(s, delim, escape)`
4371
  behaves as specified for the
4372
  `const basic_string<charT, traits, Allocator>&` overload of the
4373
  `quoted` function.
4374
+ - The expression `in >> quoted(s, delim, escape)` has type
4375
+ `basic_istream<charT, traits>&` and value `in`.
4376
+ - The expression `out << quoted(s, delim, escape)` has type
 
4377
  `basic_ostream<charT, traits>&` and value `out`.
4378
 
4379
  ## String-based streams <a id="string.streams">[[string.streams]]</a>
4380
 
4381
  ### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
 
4428
  using off_type = typename traits::off_type;
4429
  using traits_type = traits;
4430
  using allocator_type = Allocator;
4431
 
4432
  // [stringbuf.cons], constructors
4433
+ basic_stringbuf() : basic_stringbuf(ios_base::in | ios_base::out) {}
4434
+ explicit basic_stringbuf(ios_base::openmode which);
4435
  explicit basic_stringbuf(
4436
+ const basic_string<charT, traits, Allocator>& s,
4437
  ios_base::openmode which = ios_base::in | ios_base::out);
4438
+ explicit basic_stringbuf(const Allocator& a)
4439
+ : basic_stringbuf(ios_base::in | ios_base::out, a) {}
4440
+ basic_stringbuf(ios_base::openmode which, const Allocator& a);
4441
  explicit basic_stringbuf(
4442
+ basic_string<charT, traits, Allocator>&& s,
4443
  ios_base::openmode which = ios_base::in | ios_base::out);
4444
+ template<class SAlloc>
4445
+ basic_stringbuf(
4446
+ const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
4447
+ : basic_stringbuf(s, ios_base::in | ios_base::out, a) {}
4448
+ template<class SAlloc>
4449
+ basic_stringbuf(
4450
+ const basic_string<charT, traits, SAlloc>& s,
4451
+ ios_base::openmode which, const Allocator& a);
4452
+ template<class SAlloc>
4453
+ explicit basic_stringbuf(
4454
+ const basic_string<charT, traits, SAlloc>& s,
4455
+ ios_base::openmode which = ios_base::in | ios_base::out);
4456
+ basic_stringbuf(const basic_stringbuf&) = delete;
4457
  basic_stringbuf(basic_stringbuf&& rhs);
4458
+ basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
4459
 
4460
  // [stringbuf.assign], assign and swap
4461
+ basic_stringbuf& operator=(const basic_stringbuf&) = delete;
4462
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
4463
+ void swap(basic_stringbuf& rhs) noexcept(see below);
4464
+
4465
+ // [stringbuf.members], getters and setters
4466
+ allocator_type get_allocator() const noexcept;
4467
+
4468
+ basic_string<charT, traits, Allocator> str() const &;
4469
+ template<class SAlloc>
4470
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
4471
+ basic_string<charT, traits, Allocator> str() &&;
4472
+ basic_string_view<charT, traits> view() const noexcept;
4473
 
 
 
4474
  void str(const basic_string<charT, traits, Allocator>& s);
4475
+ template<class SAlloc>
4476
+ void str(const basic_string<charT, traits, SAlloc>& s);
4477
+ void str(basic_string<charT, traits, Allocator>&& s);
4478
 
4479
  protected:
4480
  // [stringbuf.virtuals], overridden virtual functions
4481
  int_type underflow() override;
4482
  int_type pbackfail(int_type c = traits::eof()) override;
 
4490
  ios_base::openmode which
4491
  = ios_base::in | ios_base::out) override;
4492
 
4493
  private:
4494
  ios_base::openmode mode; // exposition only
4495
+ basic_string<charT, traits, Allocator> buf; // exposition only
4496
+ void init_buf_ptrs(); // exposition only
4497
  };
4498
 
4499
  template<class charT, class traits, class Allocator>
4500
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
4501
+ basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
4502
  }
4503
  ```
4504
 
4505
  The class `basic_stringbuf` is derived from `basic_streambuf` to
4506
  associate possibly the input sequence and possibly the output sequence
4507
  with a sequence of arbitrary *characters*. The sequence can be
4508
  initialized from, or made available as, an object of class
4509
  `basic_string`.
4510
 
4511
+ For the sake of exposition, the maintained data and internal pointer
4512
+ initialization is presented here as:
4513
 
4514
  - `ios_base::openmode mode`, has `in` set if the input sequence can be
4515
  read, and `out` set if the output sequence can be written.
4516
+ - `basic_string<charT, traits, Allocator> buf` contains the underlying
4517
+ character sequence.
4518
+ - `init_buf_ptrs()` sets the base class’ get area [[streambuf.get.area]]
4519
+ and put area [[streambuf.put.area]] pointers after initializing,
4520
+ moving from, or assigning to `buf` accordingly.
4521
 
4522
+ #### Constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
4523
 
4524
  ``` cpp
4525
+ explicit basic_stringbuf(ios_base::openmode which);
 
4526
  ```
4527
 
4528
+ *Effects:* Initializes the base class with `basic_streambuf()`
4529
+ [[streambuf.cons]], and `mode` with `which`. It is
4530
+ *implementation-defined* whether the sequence pointers (`eback()`,
4531
+ `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) are initialized to
4532
+ null pointers.
4533
 
4534
+ *Ensures:* `str().empty()` is `true`.
4535
 
4536
  ``` cpp
4537
  explicit basic_stringbuf(
4538
  const basic_string<charT, traits, Allocator>& s,
4539
  ios_base::openmode which = ios_base::in | ios_base::out);
4540
  ```
4541
 
4542
+ *Effects:* Initializes the base class with `basic_streambuf()`
4543
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
4544
+ `init_buf_ptrs()`.
4545
+
4546
+ ``` cpp
4547
+ basic_stringbuf(ios_base::openmode which, const Allocator &a);
4548
+ ```
4549
+
4550
+ *Effects:* Initializes the base class with `basic_streambuf()`
4551
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `a`, then calls
4552
+ `init_buf_ptrs()`.
4553
+
4554
+ *Ensures:* `str().empty()` is `true`.
4555
+
4556
+ ``` cpp
4557
+ explicit basic_stringbuf(
4558
+ basic_string<charT, traits, Allocator>&& s,
4559
+ ios_base::openmode which = ios_base::in | ios_base::out);
4560
+ ```
4561
+
4562
+ *Effects:* Initializes the base class with `basic_streambuf()`
4563
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `std::move(s)`,
4564
+ then calls `init_buf_ptrs()`.
4565
+
4566
+ ``` cpp
4567
+ template<class SAlloc>
4568
+ basic_stringbuf(
4569
+ const basic_string<charT, traits, SAlloc>& s,
4570
+ ios_base::openmode which, const Allocator &a);
4571
+ ```
4572
+
4573
+ *Effects:* Initializes the base class with `basic_streambuf()`
4574
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `{s,a}`, then
4575
+ calls `init_buf_ptrs()`.
4576
+
4577
+ ``` cpp
4578
+ template<class SAlloc>
4579
+ explicit basic_stringbuf(
4580
+ const basic_string<charT, traits, SAlloc>& s,
4581
+ ios_base::openmode which = ios_base::in | ios_base::out);
4582
+ ```
4583
+
4584
+ *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
4585
+
4586
+ *Effects:* Initializes the base class with `basic_streambuf()`
4587
+ [[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
4588
+ `init_buf_ptrs()`.
4589
 
4590
  ``` cpp
4591
  basic_stringbuf(basic_stringbuf&& rhs);
4592
+ basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
4593
  ```
4594
 
4595
+ *Effects:* Copy constructs the base class from `rhs` and initializes
4596
+ `mode` with `rhs.mode`. In the first form `buf` is initialized from
4597
+ `std::move(rhs).str()`. In the second form `buf` is initialized from
4598
+ `{std::move(rhs).str(), a}`. It is *implementation-defined* whether the
4599
+ sequence pointers in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`,
4600
+ `pptr()`, `epptr()`) obtain the values which `rhs` had.
4601
 
4602
+ *Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
4603
+ construction and let `rhs_a` refer to the state of `rhs` just after this
4604
+ construction.
4605
 
4606
  - `str() == rhs_p.str()`
4607
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
4608
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
4609
  - `pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()`
 
4612
  - `if (gptr()) gptr() != rhs_a.gptr()`
4613
  - `if (egptr()) egptr() != rhs_a.egptr()`
4614
  - `if (pbase()) pbase() != rhs_a.pbase()`
4615
  - `if (pptr()) pptr() != rhs_a.pptr()`
4616
  - `if (epptr()) epptr() != rhs_a.epptr()`
4617
+ - `getloc() == rhs_p.getloc()`
4618
+ - `rhs` is empty but usable, as if `std::move(rhs).str()` was called.
4619
 
4620
+ #### Assignment and swap <a id="stringbuf.assign">[[stringbuf.assign]]</a>
4621
 
4622
  ``` cpp
4623
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
4624
  ```
4625
 
 
4628
  (see  [[stringbuf.cons]]).
4629
 
4630
  *Returns:* `*this`.
4631
 
4632
  ``` cpp
4633
+ void swap(basic_stringbuf& rhs) noexcept(see below);
4634
  ```
4635
 
4636
+ *Preconditions:*
4637
+ `allocator_traits<Allocator>::propagate_on_container_swap::value` is
4638
+ `true` or `get_allocator() == s.get_allocator()` is `true`.
4639
+
4640
  *Effects:* Exchanges the state of `*this` and `rhs`.
4641
 
4642
+ *Remarks:* The expression inside `noexcept` is equivalent to:
4643
+ `allocator_traits<Allocator>::propagate_on_container_swap::value ||`
4644
+ `allocator_traits<Allocator>::is_always_equal::value`.
4645
+
4646
  ``` cpp
4647
  template<class charT, class traits, class Allocator>
4648
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
4649
+ basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
4650
  ```
4651
 
4652
+ *Effects:* Equivalent to: `x.swap(y)`.
4653
 
4654
  #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
4655
 
4656
+ The member functions getting the underlying character sequence all refer
4657
+ to a `high_mark` value, where `high_mark` represents the position one
4658
+ past the highest initialized character in the buffer. Characters can be
4659
+ initialized by writing to the stream, by constructing the
4660
+ `basic_stringbuf` passing a `basic_string` argument, or by calling one
4661
+ of the `str` member functions passing a `basic_string` as an argument.
4662
+ In the latter case, all characters initialized prior to the call are now
4663
+ considered uninitialized (except for those characters re-initialized by
4664
+ the new `basic_string`).
4665
+
4666
+ ``` cpp
4667
+ void init_buf_ptrs(); // exposition only
4668
+ ```
4669
+
4670
+ *Effects:* Initializes the input and output sequences from `buf`
4671
+ according to `mode`.
4672
+
4673
+ *Ensures:*
4674
+
4675
+ - If `ios_base::out` is set in `mode`, `pbase()` points to `buf.front()`
4676
+ and `epptr() >= pbase() + buf.size()` is `true`;
4677
+ - in addition, if `ios_base::ate` is set in `mode`,
4678
+ `pptr() == pbase() + buf.size()` is `true`,
4679
+ - otherwise `pptr() == pbase()` is `true`.
4680
+ - If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
4681
+ and `(gptr() == eback() && egptr() == eback() + buf.size())` is
4682
+ `true`.
4683
+
4684
+ [*Note 1*: For efficiency reasons, stream buffer operations might
4685
+ violate invariants of `buf` while it is held encapsulated in the
4686
+ `basic_stringbuf`, e.g., by writing to characters in the range
4687
+ \[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
4688
+ operations retrieving a `basic_string` from `buf` ensure that the
4689
+ `basic_string` invariants hold on the returned value. — *end note*]
4690
+
4691
+ ``` cpp
4692
+ allocator_type get_allocator() const noexcept;
4693
+ ```
4694
+
4695
+ *Returns:* `buf.get_allocator()`.
4696
+
4697
+ ``` cpp
4698
+ basic_string<charT, traits, Allocator> str() const &;
4699
+ ```
4700
+
4701
+ *Effects:* Equivalent to:
4702
+
4703
+ ``` cpp
4704
+ return basic_string<charT, traits, Allocator>(view(), get_allocator());
4705
+ ```
4706
+
4707
  ``` cpp
4708
+ template<class SAlloc>
4709
+ basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
4710
+ ```
4711
+
4712
+ *Constraints:* `SAlloc` is a type that qualifies as an
4713
+ allocator [[container.requirements.general]].
4714
+
4715
+ *Effects:* Equivalent to:
4716
+
4717
+ ``` cpp
4718
+ return basic_string<charT, traits, SAlloc>(view(), sa);
4719
+ ```
4720
+
4721
+ ``` cpp
4722
+ basic_string<charT, traits, Allocator> str() &&;
4723
+ ```
4724
+
4725
+ *Returns:* A `basic_string<charT, traits, Allocator>` object move
4726
+ constructed from the `basic_stringbuf`’s underlying character sequence
4727
+ in `buf`. This can be achieved by first adjusting `buf` to have the same
4728
+ content as `view()`.
4729
+
4730
+ *Ensures:* The underlying character sequence `buf` is empty and
4731
+ `pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
4732
+ initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
4733
+
4734
+ ``` cpp
4735
+ basic_string_view<charT, traits> view() const noexcept;
4736
+ ```
4737
+
4738
+ Let `sv` be `basic_string_view<charT, traits>`.
4739
+
4740
+ *Returns:* A `sv` object referring to the `basic_stringbuf`’s underlying
4741
+ character sequence in `buf`:
4742
+
4743
+ - If `ios_base::out` is set in `mode`, then
4744
+ `sv(pbase(), high_mark-pbase())` is returned.
4745
+ - Otherwise, if `ios_base::in` is set in `mode`, then
4746
+ `sv(eback(), egptr()-eback())` is returned.
4747
+ - Otherwise, `sv()` is returned.
4748
+
4749
+ [*Note 2*: Using the returned `sv` object after destruction or
4750
+ invalidation of the character sequence underlying `*this` is undefined
4751
+ behavior, unless `sv.empty()` is `true`. — *end note*]
4752
 
4753
  ``` cpp
4754
  void str(const basic_string<charT, traits, Allocator>& s);
4755
  ```
4756
 
4757
+ *Effects:* Equivalent to:
4758
+
4759
+ ``` cpp
4760
+ buf = s;
4761
+ init_buf_ptrs();
4762
+ ```
4763
+
4764
+ ``` cpp
4765
+ template<class SAlloc>
4766
+ void str(const basic_string<charT, traits, SAlloc>& s);
4767
+ ```
4768
+
4769
+ *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
4770
+
4771
+ *Effects:* Equivalent to:
4772
+
4773
+ ``` cpp
4774
+ buf = s;
4775
+ init_buf_ptrs();
4776
+ ```
4777
+
4778
+ ``` cpp
4779
+ void str(basic_string<charT, traits, Allocator>&& s);
4780
+ ```
4781
+
4782
+ *Effects:* Equivalent to:
4783
+
4784
+ ``` cpp
4785
+ buf = std::move(s);
4786
+ init_buf_ptrs();
4787
+ ```
4788
 
4789
  #### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
4790
 
4791
  ``` cpp
4792
  int_type underflow() override;
 
4813
  `ios_base::out` is nonzero, assigns `c` to `*``gptr()`. Returns: `c`.
4814
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
4815
  input sequence has a putback position available, assigns `gptr() - 1`
4816
  to `gptr()`. Returns: `traits::not_eof(c)`.
4817
 
4818
+ *Returns:* As specified above, or `traits::eof()` to indicate failure.
4819
 
4820
  *Remarks:* If the function can succeed in more than one of these ways,
4821
  it is unspecified which way is chosen.
4822
 
4823
  ``` cpp
 
4836
  `traits::eof()`.
4837
 
4838
  *Remarks:* The function can alter the number of write positions
4839
  available as a result of any call.
4840
 
4841
+ *Returns:* As specified above, or `traits::eof()` to indicate failure.
4842
 
4843
+ The function can make a write position available only if `ios_base::out`
4844
+ is set in `mode`. To make a write position available, the function
4845
+ reallocates (or initially allocates) an array object with a sufficient
4846
+ number of elements to hold the current array object (if any), plus at
4847
+ least one additional write position. If `ios_base::in` is set in `mode`,
4848
+ the function alters the read end pointer `egptr()` to point just past
4849
+ the new write position.
4850
 
4851
  ``` cpp
4852
  pos_type seekoff(off_type off, ios_base::seekdir way,
4853
  ios_base::openmode which
4854
  = ios_base::in | ios_base::out) override;
4855
  ```
4856
 
4857
  *Effects:* Alters the stream position within one of the controlled
4858
+ sequences, if possible, as indicated in [[stringbuf.seekoff.pos]].
 
4859
 
4860
+ **Table: `seekoff` positioning** <a id="stringbuf.seekoff.pos">[stringbuf.seekoff.pos]</a>
4861
 
4862
  | Conditions | Result |
4863
+ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
4864
+ | `ios_base::in` is set in `which` | positions the input sequence |
4865
+ | `ios_base::out` is set in `which` | positions the output sequence |
4866
+ | both `ios_base::in` and `ios_base::out` are set in `which` and either<br> `way == ios_base::beg` or<br> `way == ios_base::end` | positions both the input and the output sequences |
4867
  | Otherwise | the positioning operation fails. |
4868
 
4869
 
4870
+ For a sequence to be positioned, the function determines `newoff` as
4871
+ indicated in [[stringbuf.seekoff.newoff]]. If the sequence’s next
4872
+ pointer (either `gptr()` or `pptr()`) is a null pointer and `newoff` is
4873
+ nonzero, the positioning operation fails.
4874
 
4875
+ **Table: `newoff` values** <a id="stringbuf.seekoff.newoff">[stringbuf.seekoff.newoff]</a>
4876
 
4877
  | Condition | `newoff` Value |
4878
  | ---------------------- | ----------------------------------------------------------------------- |
4879
  | `way == ios_base::beg` | 0 |
4880
  | `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
4881
  | `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
4882
 
4883
 
4884
  If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
4885
+ character [[stringbuf.members]], the positioning operation fails.
4886
  Otherwise, the function assigns `xbeg + newoff + off` to the next
4887
  pointer `xnext`.
4888
 
4889
  *Returns:* `pos_type(newoff)`, constructed from the resultant offset
4890
  `newoff` (of type `off_type`), that stores the resultant stream
 
4926
  using off_type = typename traits::off_type;
4927
  using traits_type = traits;
4928
  using allocator_type = Allocator;
4929
 
4930
  // [istringstream.cons], constructors
4931
+ basic_istringstream() : basic_istringstream(ios_base::in) {}
4932
+ explicit basic_istringstream(ios_base::openmode which);
4933
  explicit basic_istringstream(
4934
+ const basic_string<charT, traits, Allocator>& s,
4935
  ios_base::openmode which = ios_base::in);
4936
+ basic_istringstream(ios_base::openmode which, const Allocator& a);
4937
  explicit basic_istringstream(
4938
+ basic_string<charT, traits, Allocator>&& s,
4939
  ios_base::openmode which = ios_base::in);
4940
+ template<class SAlloc>
4941
+ basic_istringstream(
4942
+ const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
4943
+ : basic_istringstream(s, ios_base::in, a) {}
4944
+ template<class SAlloc>
4945
+ basic_istringstream(
4946
+ const basic_string<charT, traits, SAlloc>& s,
4947
+ ios_base::openmode which, const Allocator& a);
4948
+ template<class SAlloc>
4949
+ explicit basic_istringstream(
4950
+ const basic_string<charT, traits, SAlloc>& s,
4951
+ ios_base::openmode which = ios_base::in);
4952
+ basic_istringstream(const basic_istringstream&) = delete;
4953
  basic_istringstream(basic_istringstream&& rhs);
4954
 
4955
  // [istringstream.assign], assign and swap
4956
+ basic_istringstream& operator=(const basic_istringstream&) = delete;
4957
  basic_istringstream& operator=(basic_istringstream&& rhs);
4958
  void swap(basic_istringstream& rhs);
4959
 
4960
  // [istringstream.members], members
4961
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4962
+ basic_string<charT, traits, Allocator> str() const &;
4963
+ template<class SAlloc>
4964
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
4965
+ basic_string<charT, traits, Allocator> str() &&;
4966
+ basic_string_view<charT, traits> view() const noexcept;
4967
 
 
4968
  void str(const basic_string<charT, traits, Allocator>& s);
4969
+ template<class SAlloc>
4970
+ void str(const basic_string<charT, traits, SAlloc>& s);
4971
+ void str(basic_string<charT, traits, Allocator>&& s);
4972
+
4973
  private:
4974
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
4975
  };
4976
 
4977
  template<class charT, class traits, class Allocator>
 
4986
  associated storage. For the sake of exposition, the maintained data is
4987
  presented here as:
4988
 
4989
  - `sb`, the `stringbuf` object.
4990
 
4991
+ #### Constructors <a id="istringstream.cons">[[istringstream.cons]]</a>
4992
 
4993
  ``` cpp
4994
+ explicit basic_istringstream(ios_base::openmode which);
4995
  ```
4996
 
4997
+ *Effects:* Initializes the base class with
4998
+ `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
4999
+ `basic_stringbuf<charT, traits, Allocator>(which | ios_base::in)`
5000
+ [[stringbuf.cons]].
5001
 
5002
  ``` cpp
5003
  explicit basic_istringstream(
5004
+ const basic_string<charT, traits, Allocator>& s,
5005
  ios_base::openmode which = ios_base::in);
5006
  ```
5007
 
5008
+ *Effects:* Initializes the base class with
5009
+ `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5010
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`([[stringbuf.cons]]).
5011
+
5012
+ ``` cpp
5013
+ basic_istringstream(ios_base::openmode which, const Allocator& a);
5014
+ ```
5015
+
5016
+ *Effects:* Initializes the base class with
5017
+ `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5018
+ `basic_stringbuf<charT, traits, Allocator>(which | ios_base::in, a)`
5019
+ [[stringbuf.cons]].
5020
+
5021
+ ``` cpp
5022
+ explicit basic_istringstream(
5023
+ basic_string<charT, traits, Allocator>&& s,
5024
+ ios_base::openmode which = ios_base::in);
5025
+ ```
5026
+
5027
+ *Effects:* Initializes the base class with
5028
+ `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5029
+ `basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::in)`
5030
+ [[stringbuf.cons]].
5031
+
5032
+ ``` cpp
5033
+ template<class SAlloc>
5034
+ basic_istringstream(
5035
+ const basic_string<charT, traits, SAlloc>& s,
5036
+ ios_base::openmode which, const Allocator& a);
5037
+ ```
5038
+
5039
+ *Effects:* Initializes the base class with
5040
+ `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5041
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`([[stringbuf.cons]]).
5042
+
5043
+ ``` cpp
5044
+ template<class SAlloc>
5045
+ explicit basic_istringstream(
5046
+ const basic_string<charT, traits, SAlloc>& s,
5047
+ ios_base::openmode which = ios_base::in);
5048
+ ```
5049
+
5050
+ *Effects:* Initializes the base class with
5051
+ `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5052
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
5053
+ [[stringbuf.cons]].
5054
 
5055
  ``` cpp
5056
  basic_istringstream(basic_istringstream&& rhs);
5057
  ```
5058
 
5059
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5060
  by move constructing the base class, and the contained
5061
+ `basic_stringbuf`. Then calls
5062
+ `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5063
+ contained `basic_stringbuf`.
5064
 
5065
+ #### Assignment and swap <a id="istringstream.assign">[[istringstream.assign]]</a>
 
 
 
 
 
 
 
 
 
5066
 
5067
  ``` cpp
5068
  void swap(basic_istringstream& rhs);
5069
  ```
5070
 
5071
+ *Effects:* Equivalent to:
5072
+
5073
+ ``` cpp
5074
+ basic_istream<charT, traits>::swap(rhs);
5075
+ sb.swap(rhs.sb);
5076
+ ```
5077
 
5078
  ``` cpp
5079
  template<class charT, class traits, class Allocator>
5080
  void swap(basic_istringstream<charT, traits, Allocator>& x,
5081
  basic_istringstream<charT, traits, Allocator>& y);
5082
  ```
5083
 
5084
+ *Effects:* Equivalent to: `x.swap(y)`.
5085
 
5086
  #### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
5087
 
5088
  ``` cpp
5089
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5090
  ```
5091
 
5092
  *Returns:*
5093
+ `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
5094
 
5095
  ``` cpp
5096
+ basic_string<charT, traits, Allocator> str() const &;
5097
  ```
5098
 
5099
+ *Effects:* Equivalent to: `return rdbuf()->str();`
5100
+
5101
+ ``` cpp
5102
+ template<class SAlloc>
5103
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
5104
+ ```
5105
+
5106
+ *Effects:* Equivalent to: `return rdbuf()->str(sa);`
5107
+
5108
+ ``` cpp
5109
+ basic_string<charT,traits,Allocator> str() &&;
5110
+ ```
5111
+
5112
+ *Effects:* Equivalent to: `return std::move(*rdbuf()).str();`
5113
+
5114
+ ``` cpp
5115
+ basic_string_view<charT, traits> view() const noexcept;
5116
+ ```
5117
+
5118
+ *Effects:* Equivalent to: `return rdbuf()->view();`
5119
 
5120
  ``` cpp
5121
  void str(const basic_string<charT, traits, Allocator>& s);
5122
  ```
5123
 
5124
+ *Effects:* Equivalent to: `rdbuf()->str(s);`
5125
+
5126
+ ``` cpp
5127
+ template<class SAlloc>
5128
+ void str(const basic_string<charT, traits, SAlloc>& s);
5129
+ ```
5130
+
5131
+ *Effects:* Equivalent to: `rdbuf()->str(s);`
5132
+
5133
+ ``` cpp
5134
+ void str(basic_string<charT, traits, Allocator>&& s);
5135
+ ```
5136
+
5137
+ *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5138
 
5139
  ### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
5140
 
5141
  ``` cpp
5142
  namespace std {
 
5150
  using off_type = typename traits::off_type;
5151
  using traits_type = traits;
5152
  using allocator_type = Allocator;
5153
 
5154
  // [ostringstream.cons], constructors
5155
+ basic_ostringstream() : basic_ostringstream(ios_base::out) {}
5156
+ explicit basic_ostringstream(ios_base::openmode which);
5157
  explicit basic_ostringstream(
5158
+ const basic_string<charT, traits, Allocator>& s,
5159
  ios_base::openmode which = ios_base::out);
5160
+ basic_ostringstream(ios_base::openmode which, const Allocator& a);
5161
  explicit basic_ostringstream(
5162
+ basic_string<charT, traits, Allocator>&& s,
5163
  ios_base::openmode which = ios_base::out);
5164
+ template<class SAlloc>
5165
+ basic_ostringstream(
5166
+ const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
5167
+ : basic_ostringstream(s, ios_base::out, a) {}
5168
+ template<class SAlloc>
5169
+ basic_ostringstream(
5170
+ const basic_string<charT, traits, SAlloc>& s,
5171
+ ios_base::openmode which, const Allocator& a);
5172
+ template<class SAlloc>
5173
+ explicit basic_ostringstream(
5174
+ const basic_string<charT, traits, SAlloc>& s,
5175
+ ios_base::openmode which = ios_base::out);
5176
+ basic_ostringstream(const basic_ostringstream&) = delete;
5177
  basic_ostringstream(basic_ostringstream&& rhs);
5178
 
5179
  // [ostringstream.assign], assign and swap
5180
+ basic_ostringstream& operator=(const basic_ostringstream&) = delete;
5181
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
5182
  void swap(basic_ostringstream& rhs);
5183
 
5184
  // [ostringstream.members], members
5185
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5186
 
5187
+ basic_string<charT, traits, Allocator> str() const &;
5188
+ template<class SAlloc>
5189
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
5190
+ basic_string<charT, traits, Allocator> str() &&;
5191
+ basic_string_view<charT, traits> view() const noexcept;
5192
+
5193
  void str(const basic_string<charT, traits, Allocator>& s);
5194
+ template<class SAlloc>
5195
+ void str(const basic_string<charT, traits, SAlloc>& s);
5196
+ void str(basic_string<charT, traits, Allocator>&& s);
5197
+
5198
  private:
5199
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5200
  };
5201
 
5202
  template<class charT, class traits, class Allocator>
 
5210
  uses a `basic_stringbuf` object to control the associated storage. For
5211
  the sake of exposition, the maintained data is presented here as:
5212
 
5213
  - `sb`, the `stringbuf` object.
5214
 
5215
+ #### Constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
5216
+
5217
+ ``` cpp
5218
+ explicit basic_ostringstream(ios_base::openmode which);
5219
+ ```
5220
+
5221
+ *Effects:* Initializes the base class with
5222
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5223
+ `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out)`
5224
+ [[stringbuf.cons]].
5225
 
5226
  ``` cpp
5227
  explicit basic_ostringstream(
5228
+ const basic_string<charT, traits, Allocator>& s,
5229
  ios_base::openmode which = ios_base::out);
5230
  ```
5231
 
5232
+ *Effects:* Initializes the base class with
5233
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5234
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`([[stringbuf.cons]]).
5235
+
5236
+ ``` cpp
5237
+ basic_ostringstream(ios_base::openmode which, const Allocator& a);
5238
+ ```
5239
+
5240
+ *Effects:* Initializes the base class with
5241
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5242
+ `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`([[stringbuf.cons]]).
5243
 
5244
  ``` cpp
5245
  explicit basic_ostringstream(
5246
+ basic_string<charT, traits, Allocator>&& s,
5247
  ios_base::openmode which = ios_base::out);
5248
  ```
5249
 
5250
+ *Effects:* Initializes the base class with
5251
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5252
+ `basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::out)`
5253
+ [[stringbuf.cons]].
5254
+
5255
+ ``` cpp
5256
+ template<class SAlloc>
5257
+ basic_ostringstream(
5258
+ const basic_string<charT, traits, SAlloc>& s,
5259
+ ios_base::openmode which, const Allocator& a);
5260
+ ```
5261
+
5262
+ *Effects:* Initializes the base class with
5263
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5264
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`([[stringbuf.cons]]).
5265
+
5266
+ ``` cpp
5267
+ template<class SAlloc>
5268
+ explicit basic_ostringstream(
5269
+ const basic_string<charT, traits, SAlloc>& s,
5270
+ ios_base::openmode which = ios_base::out);
5271
+ ```
5272
+
5273
+ *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
5274
+
5275
+ *Effects:* Initializes the base class with
5276
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5277
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`([[stringbuf.cons]]).
5278
 
5279
  ``` cpp
5280
  basic_ostringstream(basic_ostringstream&& rhs);
5281
  ```
5282
 
5283
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5284
  by move constructing the base class, and the contained
5285
+ `basic_stringbuf`. Then calls
5286
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5287
+ contained `basic_stringbuf`.
5288
 
5289
+ #### Assignment and swap <a id="ostringstream.assign">[[ostringstream.assign]]</a>
 
 
 
 
 
 
 
 
 
5290
 
5291
  ``` cpp
5292
  void swap(basic_ostringstream& rhs);
5293
  ```
5294
 
5295
+ *Effects:* Equivalent to:
5296
+
5297
+ ``` cpp
5298
+ basic_ostream<charT, traits>::swap(rhs);
5299
+ sb.swap(rhs.sb);
5300
+ ```
5301
 
5302
  ``` cpp
5303
  template<class charT, class traits, class Allocator>
5304
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
5305
  basic_ostringstream<charT, traits, Allocator>& y);
5306
  ```
5307
 
5308
+ *Effects:* Equivalent to: `x.swap(y)`.
5309
 
5310
  #### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
5311
 
5312
  ``` cpp
5313
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5314
  ```
5315
 
5316
  *Returns:*
5317
+ `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
5318
 
5319
  ``` cpp
5320
+ basic_string<charT, traits, Allocator> str() const &;
5321
  ```
5322
 
5323
+ *Effects:* Equivalent to: `return rdbuf()->str();`
5324
+
5325
+ ``` cpp
5326
+ template<class SAlloc>
5327
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
5328
+ ```
5329
+
5330
+ *Effects:* Equivalent to: `return rdbuf()->str(sa);`
5331
+
5332
+ ``` cpp
5333
+ basic_string<charT,traits,Allocator> str() &&;
5334
+ ```
5335
+
5336
+ *Effects:* Equivalent to: `return std::move(*rdbuf()).str();`
5337
+
5338
+ ``` cpp
5339
+ basic_string_view<charT, traits> view() const noexcept;
5340
+ ```
5341
+
5342
+ *Effects:* Equivalent to: `return rdbuf()->view();`
5343
 
5344
  ``` cpp
5345
  void str(const basic_string<charT, traits, Allocator>& s);
5346
  ```
5347
 
5348
+ *Effects:* Equivalent to: `rdbuf()->str(s);`
5349
+
5350
+ ``` cpp
5351
+ template<class SAlloc>
5352
+ void str(const basic_string<charT, traits, SAlloc>& s);
5353
+ ```
5354
+
5355
+ *Effects:* Equivalent to: `rdbuf()->str(s);`
5356
+
5357
+ ``` cpp
5358
+ void str(basic_string<charT, traits, Allocator>&& s);
5359
+ ```
5360
+
5361
+ *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5362
 
5363
  ### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
5364
 
5365
  ``` cpp
5366
  namespace std {
 
5374
  using off_type = typename traits::off_type;
5375
  using traits_type = traits;
5376
  using allocator_type = Allocator;
5377
 
5378
  // [stringstream.cons], constructors
5379
+ basic_stringstream() : basic_stringstream(ios_base::out | ios_base::in) {}
5380
+ explicit basic_stringstream(ios_base::openmode which);
5381
  explicit basic_stringstream(
5382
+ const basic_string<charT, traits, Allocator>& s,
5383
  ios_base::openmode which = ios_base::out | ios_base::in);
5384
+ basic_stringstream(ios_base::openmode which, const Allocator& a);
5385
  explicit basic_stringstream(
5386
+ basic_string<charT, traits, Allocator>&& s,
5387
  ios_base::openmode which = ios_base::out | ios_base::in);
5388
+ template<class SAlloc>
5389
+ basic_stringstream(
5390
+ const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
5391
+ : basic_stringstream(s, ios_base::out | ios_base::in, a) {}
5392
+ template<class SAlloc>
5393
+ basic_stringstream(
5394
+ const basic_string<charT, traits, SAlloc>& s,
5395
+ ios_base::openmode which, const Allocator& a);
5396
+ template<class SAlloc>
5397
+ explicit basic_stringstream(
5398
+ const basic_string<charT, traits, SAlloc>& s,
5399
+ ios_base::openmode which = ios_base::out | ios_base::in);
5400
+ basic_stringstream(const basic_stringstream&) = delete;
5401
  basic_stringstream(basic_stringstream&& rhs);
5402
 
5403
  // [stringstream.assign], assign and swap
5404
+ basic_stringstream& operator=(const basic_stringstream&) = delete;
5405
  basic_stringstream& operator=(basic_stringstream&& rhs);
5406
  void swap(basic_stringstream& rhs);
5407
 
5408
  // [stringstream.members], members
5409
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5410
+
5411
+ basic_string<charT, traits, Allocator> str() const &;
5412
+ template<class SAlloc>
5413
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
5414
+ basic_string<charT, traits, Allocator> str() &&;
5415
+ basic_string_view<charT, traits> view() const noexcept;
5416
+
5417
+ void str(const basic_string<charT, traits, Allocator>& s);
5418
+ template<class SAlloc>
5419
+ void str(const basic_string<charT, traits, SAlloc>& s);
5420
+ void str(basic_string<charT, traits, Allocator>&& s);
5421
 
5422
  private:
5423
  basic_stringbuf<charT, traits> sb; // exposition only
5424
  };
5425
 
 
5436
  associated sequence. For the sake of exposition, the maintained data is
5437
  presented here as
5438
 
5439
  - `sb`, the `stringbuf` object.
5440
 
5441
+ #### Constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
5442
+
5443
+ ``` cpp
5444
+ explicit basic_stringstream(ios_base::openmode which);
5445
+ ```
5446
+
5447
+ *Effects:* Initializes the base class with
5448
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5449
+ `sb` with `basic_stringbuf<charT, traits, Allocator>(which)`.
5450
 
5451
  ``` cpp
5452
  explicit basic_stringstream(
5453
+ const basic_string<charT, traits, Allocator>& s,
5454
  ios_base::openmode which = ios_base::out | ios_base::in);
5455
  ```
5456
 
5457
+ *Effects:* Initializes the base class with
5458
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5459
+ `sb` with `basic_stringbuf<charT, traits, Allocator>(s, which)`.
5460
+
5461
+ ``` cpp
5462
+ basic_stringstream(ios_base::openmode which, const Allocator& a);
5463
+ ```
5464
+
5465
+ *Effects:* Initializes the base class with
5466
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5467
+ `sb` with `basic_stringbuf<charT, traits, Allocator>(which, a)`
5468
+ [[stringbuf.cons]].
5469
 
5470
  ``` cpp
5471
  explicit basic_stringstream(
5472
+ basic_string<charT, traits, Allocator>&& s,
5473
  ios_base::openmode which = ios_base::out | ios_base::in);
5474
  ```
5475
 
5476
+ *Effects:* Initializes the base class with
5477
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5478
+ `sb` with
5479
+ `basic_stringbuf<charT, traits, Allocator>(std::move(s), which)`
5480
+ [[stringbuf.cons]].
5481
+
5482
+ ``` cpp
5483
+ template<class SAlloc>
5484
+ basic_stringstream(
5485
+ const basic_string<charT, traits, SAlloc>& s,
5486
+ ios_base::openmode which, const Allocator& a);
5487
+ ```
5488
+
5489
+ *Effects:* Initializes the base class with
5490
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5491
+ `sb` with `basic_stringbuf<charT, traits, Allocator>(s, which, a)`
5492
+ [[stringbuf.cons]].
5493
+
5494
+ ``` cpp
5495
+ template<class SAlloc>
5496
+ explicit basic_stringstream(
5497
+ const basic_string<charT, traits, SAlloc>& s,
5498
+ ios_base::openmode which = ios_base::out | ios_base::in);
5499
+ ```
5500
+
5501
+ *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
5502
+
5503
+ *Effects:* Initializes the base class with
5504
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
5505
+ `sb` with `basic_stringbuf<charT, traits, Allocator>(s, which)`
5506
+ [[stringbuf.cons]].
5507
 
5508
  ``` cpp
5509
  basic_stringstream(basic_stringstream&& rhs);
5510
  ```
5511
 
5512
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
5513
  by move constructing the base class, and the contained
5514
+ `basic_stringbuf`. Then calls
5515
+ `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5516
+ contained `basic_stringbuf`.
5517
 
5518
+ #### Assignment and swap <a id="stringstream.assign">[[stringstream.assign]]</a>
 
 
 
 
 
 
 
 
 
5519
 
5520
  ``` cpp
5521
  void swap(basic_stringstream& rhs);
5522
  ```
5523
 
5524
+ *Effects:* Equivalent to:
5525
+
5526
+ ``` cpp
5527
+ basic_iostream<charT,traits>::swap(rhs);
5528
+ sb.swap(rhs.sb);
5529
+ ```
5530
 
5531
  ``` cpp
5532
  template<class charT, class traits, class Allocator>
5533
  void swap(basic_stringstream<charT, traits, Allocator>& x,
5534
  basic_stringstream<charT, traits, Allocator>& y);
5535
  ```
5536
 
5537
+ *Effects:* Equivalent to: `x.swap(y)`.
5538
 
5539
  #### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
5540
 
5541
  ``` cpp
5542
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5543
  ```
5544
 
5545
+ *Returns:*
5546
+ `const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
5547
 
5548
  ``` cpp
5549
+ basic_string<charT, traits, Allocator> str() const &;
5550
  ```
5551
 
5552
+ *Effects:* Equivalent to: `return rdbuf()->str();`
5553
 
5554
  ``` cpp
5555
+ template<class SAlloc>
5556
+ basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
5557
  ```
5558
 
5559
+ *Effects:* Equivalent to: `return rdbuf()->str(sa);`
5560
+
5561
+ ``` cpp
5562
+ basic_string<charT,traits,Allocator> str() &&;
5563
+ ```
5564
+
5565
+ *Effects:* Equivalent to: `return std::move(*rdbuf()).str();`
5566
+
5567
+ ``` cpp
5568
+ basic_string_view<charT, traits> view() const noexcept;
5569
+ ```
5570
+
5571
+ *Effects:* Equivalent to: `return rdbuf()->view();`
5572
+
5573
+ ``` cpp
5574
+ void str(const basic_string<charT, traits, Allocator>& s);
5575
+ ```
5576
+
5577
+ *Effects:* Equivalent to: `rdbuf()->str(s);`
5578
+
5579
+ ``` cpp
5580
+ template<class SAlloc>
5581
+ void str(const basic_string<charT, traits, SAlloc>& s);
5582
+ ```
5583
+
5584
+ *Effects:* Equivalent to: `rdbuf()->str(s);`
5585
+
5586
+ ``` cpp
5587
+ void str(basic_string<charT, traits, Allocator>&& s);
5588
+ ```
5589
+
5590
+ *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5591
 
5592
  ## File-based streams <a id="file.streams">[[file.streams]]</a>
5593
 
5594
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
5595
 
 
5625
  or sink of bytes. In an environment that uses a large character set, the
5626
  file typically holds multibyte character sequences and the
5627
  `basic_filebuf` object converts those multibyte sequences into wide
5628
  character sequences. — *end note*]
5629
 
5630
+ In subclause  [[file.streams]], member functions taking arguments of
5631
  `const filesystem::path::value_type*` are only be provided on systems
5632
+ where `filesystem::path::value_type` [[fs.class.path]] is not `char`.
5633
 
5634
  [*Note 2*: These functions enable class `path` support for systems with
5635
  a wide native path character type, such as `wchar_t`. — *end note*]
5636
 
5637
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
 
5647
  using off_type = typename traits::off_type;
5648
  using traits_type = traits;
5649
 
5650
  // [filebuf.cons], constructors/destructor
5651
  basic_filebuf();
5652
+ basic_filebuf(const basic_filebuf&) = delete;
5653
  basic_filebuf(basic_filebuf&& rhs);
5654
  virtual ~basic_filebuf();
5655
 
5656
  // [filebuf.assign], assign and swap
5657
+ basic_filebuf& operator=(const basic_filebuf&) = delete;
5658
  basic_filebuf& operator=(basic_filebuf&& rhs);
5659
  void swap(basic_filebuf& rhs);
5660
 
5661
  // [filebuf.members], members
5662
  bool is_open() const;
 
5714
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
5715
  the behavior is undefined.
5716
 
5717
  In order to support file I/O and multibyte/wide character conversion,
5718
  conversions are performed using members of a facet, referred to as
5719
+ `a_codecvt` in following subclauses, obtained as if by
5720
 
5721
  ``` cpp
5722
  const codecvt<charT, char, typename traits::state_type>& a_codecvt =
5723
  use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());
5724
  ```
5725
 
5726
+ #### Constructors <a id="filebuf.cons">[[filebuf.cons]]</a>
5727
 
5728
  ``` cpp
5729
  basic_filebuf();
5730
  ```
5731
 
5732
+ *Effects:* Initializes the base class with
5733
+ `basic_streambuf<charT, traits>()` [[streambuf.cons]].
 
5734
 
5735
+ *Ensures:* `is_open() == false`.
5736
 
5737
  ``` cpp
5738
  basic_filebuf(basic_filebuf&& rhs);
5739
  ```
5740
 
5741
+ *Effects:* It is *implementation-defined* whether the sequence pointers
5742
+ in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`, `pptr()`,
5743
+ `epptr()`) obtain the values which `rhs` had. Whether they do or not,
5744
+ `*this` and `rhs` reference separate buffers (if any at all) after the
5745
+ construction. Additionally `*this` references the file which `rhs` did
5746
+ before the construction, and `rhs` references no file after the
5747
+ construction. The openmode, locale and any other state of `rhs` is also
5748
+ copied.
5749
 
5750
+ *Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
5751
+ construction and let `rhs_a` refer to the state of `rhs` just after this
5752
+ construction.
5753
 
5754
  - `is_open() == rhs_p.is_open()`
5755
  - `rhs_a.is_open() == false`
5756
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
5757
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
 
5766
 
5767
  ``` cpp
5768
  virtual ~basic_filebuf();
5769
  ```
5770
 
5771
+ *Effects:* Calls `close()`. If an exception occurs during the
5772
+ destruction of the object, including the call to `close()`, the
5773
+ exception is caught but not rethrown
5774
+ (see  [[res.on.exception.handling]]).
5775
 
5776
+ #### Assignment and swap <a id="filebuf.assign">[[filebuf.assign]]</a>
5777
 
5778
  ``` cpp
5779
  basic_filebuf& operator=(basic_filebuf&& rhs);
5780
  ```
5781
 
 
5795
  template<class charT, class traits>
5796
  void swap(basic_filebuf<charT, traits>& x,
5797
  basic_filebuf<charT, traits>& y);
5798
  ```
5799
 
5800
+ *Effects:* Equivalent to: `x.swap(y)`.
5801
 
5802
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
5803
 
5804
  ``` cpp
5805
  bool is_open() const;
 
5812
  basic_filebuf* open(const char* s, ios_base::openmode mode);
5813
  basic_filebuf* open(const filesystem::path::value_type* s,
5814
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
5815
  ```
5816
 
5817
+ *Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
5818
+
5819
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
5820
+ initializes the `filebuf` as required. It then opens the file to which
5821
+ `s` resolves, if possible, as if by a call to `fopen` with the second
5822
+ argument determined from `mode & ~ios_base::ate` as indicated in
5823
+ [[filebuf.open.modes]]. If `mode` is not some combination of flags shown
5824
+ in the table then the open fails.
 
5825
 
5826
+ **Table: File open modes** <a id="filebuf.open.modes">[filebuf.open.modes]</a>
5827
 
5828
  | `binary` | `in` | `out` | `trunc` | `app` | | `stdio` equivalent |
5829
  | -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
5830
  | | | + | | | `"w"` |
5831
  | | | + | | + | `"a"` |
 
5844
  | + | + | + | + | | `"w+b"` |
5845
  | + | + | + | | + | `"a+b"` |
5846
  | + | + | | | + | `"a+b"` |
5847
 
5848
 
5849
+ If the open operation succeeds and `ios_base::ate` is set in `mode`,
5850
  positions the file to the end (as if by calling
5851
+ `fseek(file, 0, SEEK_END)`, where `file` is the pointer returned by
5852
+ calling `fopen`). [^40]
5853
 
5854
  If the repositioning operation fails, calls `close()` and returns a null
5855
  pointer to indicate failure.
5856
 
5857
  *Returns:* `this` if successful, a null pointer otherwise.
 
5880
  these calls throws an exception, the exception is caught and rethrown
5881
  after closing the file.
5882
 
5883
  *Returns:* `this` on success, a null pointer otherwise.
5884
 
5885
+ *Ensures:* `is_open() == false`.
5886
 
5887
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
5888
 
5889
  ``` cpp
5890
  streamsize showmanyc() override;
5891
  ```
5892
 
5893
+ *Effects:* Behaves the same as `basic_streambuf::showmanyc()`
5894
+ [[streambuf.virtuals]].
5895
 
5896
  *Remarks:* An implementation might well provide an overriding definition
5897
  for this function signature if it can determine that more characters can
5898
  be read from the input sequence.
5899
 
 
5950
  either the input sequence has a putback position available or the
5951
  function makes a putback position available, decrements the next
5952
  pointer for the input sequence, `gptr()`. Returns:
5953
  `traits::not_eof(c)`.
5954
 
5955
+ *Returns:* As specified above, or `traits::eof()` to indicate failure.
5956
 
5957
  *Remarks:* If `is_open() == false`, the function always fails.
5958
 
5959
  The function does not put back a character directly to the input
5960
  sequence.
 
6024
  operation was overflow or the put buffer is non-empty. “Write any
6025
  unshift sequence” means, if `width` if less than zero then call
6026
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
6027
  resulting unshift sequence. The function determines one of three values
6028
  for the argument `whence`, of type `int`, as indicated in
6029
+ [[filebuf.seekoff]].
6030
 
6031
+ **Table: `seekoff` effects** <a id="filebuf.seekoff">[filebuf.seekoff]</a>
6032
 
6033
  | `way` Value | `stdio` Equivalent |
6034
  | ---------------- | ------------------ |
6035
  | `basic_ios::beg` | `SEEK_SET` |
6036
  | `basic_ios::cur` | `SEEK_CUR` |
 
6079
 
6080
  ``` cpp
6081
  void imbue(const locale& loc) override;
6082
  ```
6083
 
6084
+ *Preconditions:* If the file is not positioned at its beginning and the
6085
  encoding of the current locale as determined by `a_codecvt.encoding()`
6086
+ is state-dependent [[locale.codecvt.virtuals]] then that facet is the
6087
  same as the corresponding facet of `loc`.
6088
 
6089
  *Effects:* Causes characters inserted or extracted after this call to be
6090
  converted according to `loc` until another call of `imbue`.
6091
 
 
6114
  ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
6115
  explicit basic_ifstream(const string& s,
6116
  ios_base::openmode mode = ios_base::in);
6117
  explicit basic_ifstream(const filesystem::path& s,
6118
  ios_base::openmode mode = ios_base::in);
6119
+ basic_ifstream(const basic_ifstream&) = delete;
6120
  basic_ifstream(basic_ifstream&& rhs);
6121
 
6122
  // [ifstream.assign], assign and swap
6123
+ basic_ifstream& operator=(const basic_ifstream&) = delete;
6124
  basic_ifstream& operator=(basic_ifstream&& rhs);
6125
  void swap(basic_ifstream& rhs);
6126
 
6127
  // [ifstream.members], members
6128
  basic_filebuf<charT, traits>* rdbuf() const;
 
6149
  associated sequence. For the sake of exposition, the maintained data is
6150
  presented here as:
6151
 
6152
  - `sb`, the `filebuf` object.
6153
 
6154
+ #### Constructors <a id="ifstream.cons">[[ifstream.cons]]</a>
6155
 
6156
  ``` cpp
6157
  basic_ifstream();
6158
  ```
6159
 
6160
+ *Effects:* Initializes the base class with
6161
+ `basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
6162
+ with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
 
6163
 
6164
  ``` cpp
6165
  explicit basic_ifstream(const char* s,
6166
  ios_base::openmode mode = ios_base::in);
6167
  explicit basic_ifstream(const filesystem::path::value_type* s,
6168
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
6169
  ```
6170
 
6171
+ *Effects:* Initializes the base class with
6172
+ `basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
6173
+ with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
6174
+ `rdbuf()->open(s, mode | ios_base::in)`. If that function returns a null
6175
+ pointer, calls `setstate(failbit)`.
6176
 
6177
  ``` cpp
6178
  explicit basic_ifstream(const string& s,
6179
  ios_base::openmode mode = ios_base::in);
6180
  explicit basic_ifstream(const filesystem::path& s,
6181
  ios_base::openmode mode = ios_base::in);
6182
  ```
6183
 
6184
+ *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
6185
 
6186
  ``` cpp
6187
  basic_ifstream(basic_ifstream&& rhs);
6188
  ```
6189
 
6190
+ *Effects:* Move constructs the base class, and the contained
6191
+ `basic_filebuf`. Then calls
6192
+ `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
6193
+ contained `basic_filebuf`.
6194
 
6195
+ #### Assignment and swap <a id="ifstream.assign">[[ifstream.assign]]</a>
 
 
 
 
 
 
 
 
 
6196
 
6197
  ``` cpp
6198
  void swap(basic_ifstream& rhs);
6199
  ```
6200
 
 
6205
  template<class charT, class traits>
6206
  void swap(basic_ifstream<charT, traits>& x,
6207
  basic_ifstream<charT, traits>& y);
6208
  ```
6209
 
6210
+ *Effects:* Equivalent to: `x.swap(y)`.
6211
 
6212
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
6213
 
6214
  ``` cpp
6215
  basic_filebuf<charT, traits>* rdbuf() const;
6216
  ```
6217
 
6218
+ *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
6219
 
6220
  ``` cpp
6221
  bool is_open() const;
6222
  ```
6223
 
 
6229
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
6230
  ```
6231
 
6232
  *Effects:* Calls `rdbuf()->open(s, mode | ios_base::in)`. If that
6233
  function does not return a null pointer calls `clear()`, otherwise calls
6234
+ `setstate(failbit)` (which may throw
6235
+ `ios_base::failure`) [[iostate.flags]].
6236
 
6237
  ``` cpp
6238
  void open(const string& s, ios_base::openmode mode = ios_base::in);
6239
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
6240
  ```
 
6245
  void close();
6246
  ```
6247
 
6248
  *Effects:* Calls `rdbuf()->close()` and, if that function returns a null
6249
  pointer, calls `setstate(failbit)` (which may throw
6250
+ `ios_base::failure`) [[iostate.flags]].
6251
 
6252
  ### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
6253
 
6254
  ``` cpp
6255
  namespace std {
 
6264
 
6265
  // [ofstream.cons], constructors
6266
  basic_ofstream();
6267
  explicit basic_ofstream(const char* s,
6268
  ios_base::openmode mode = ios_base::out);
6269
+ explicit basic_ofstream(const filesystem::path::value_type* s, // wide systems only; see [fstream.syn]
6270
+ ios_base::openmode mode = ios_base::out);
6271
  explicit basic_ofstream(const string& s,
6272
  ios_base::openmode mode = ios_base::out);
6273
  explicit basic_ofstream(const filesystem::path& s,
6274
  ios_base::openmode mode = ios_base::out);
6275
+ basic_ofstream(const basic_ofstream&) = delete;
6276
  basic_ofstream(basic_ofstream&& rhs);
6277
 
6278
  // [ofstream.assign], assign and swap
6279
+ basic_ofstream& operator=(const basic_ofstream&) = delete;
6280
  basic_ofstream& operator=(basic_ofstream&& rhs);
6281
  void swap(basic_ofstream& rhs);
6282
 
6283
  // [ofstream.members], members
6284
  basic_filebuf<charT, traits>* rdbuf() const;
 
6305
  associated sequence. For the sake of exposition, the maintained data is
6306
  presented here as:
6307
 
6308
  - `sb`, the `filebuf` object.
6309
 
6310
+ #### Constructors <a id="ofstream.cons">[[ofstream.cons]]</a>
6311
 
6312
  ``` cpp
6313
  basic_ofstream();
6314
  ```
6315
 
6316
+ *Effects:* Initializes the base class with
6317
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
6318
+ with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
 
6319
 
6320
  ``` cpp
6321
  explicit basic_ofstream(const char* s,
6322
  ios_base::openmode mode = ios_base::out);
6323
  explicit basic_ofstream(const filesystem::path::value_type* s,
6324
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
6325
  ```
6326
 
6327
+ *Effects:* Initializes the base class with
6328
+ `basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
6329
+ with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
6330
+ `rdbuf()->open(s, mode | ios_base::out)`. If that function returns a
6331
+ null pointer, calls `setstate(failbit)`.
 
6332
 
6333
  ``` cpp
6334
  explicit basic_ofstream(const string& s,
6335
  ios_base::openmode mode = ios_base::out);
6336
  explicit basic_ofstream(const filesystem::path& s,
6337
  ios_base::openmode mode = ios_base::out);
6338
  ```
6339
 
6340
+ *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
6341
 
6342
  ``` cpp
6343
  basic_ofstream(basic_ofstream&& rhs);
6344
  ```
6345
 
6346
+ *Effects:* Move constructs the base class, and the contained
6347
+ `basic_filebuf`. Then calls
6348
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
6349
+ contained `basic_filebuf`.
6350
 
6351
+ #### Assignment and swap <a id="ofstream.assign">[[ofstream.assign]]</a>
 
 
 
 
 
 
 
 
 
6352
 
6353
  ``` cpp
6354
  void swap(basic_ofstream& rhs);
6355
  ```
6356
 
 
6361
  template<class charT, class traits>
6362
  void swap(basic_ofstream<charT, traits>& x,
6363
  basic_ofstream<charT, traits>& y);
6364
  ```
6365
 
6366
+ *Effects:* Equivalent to: `x.swap(y)`.
6367
 
6368
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
6369
 
6370
  ``` cpp
6371
  basic_filebuf<charT, traits>* rdbuf() const;
6372
  ```
6373
 
6374
+ *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
6375
 
6376
  ``` cpp
6377
  bool is_open() const;
6378
  ```
6379
 
 
6385
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
6386
  ```
6387
 
6388
  *Effects:* Calls `rdbuf()->open(s, mode | ios_base::out)`. If that
6389
  function does not return a null pointer calls `clear()`, otherwise calls
6390
+ `setstate(failbit)` (which may throw
6391
+ `ios_base::failure`) [[iostate.flags]].
6392
 
6393
  ``` cpp
6394
  void close();
6395
  ```
6396
 
6397
  *Effects:* Calls `rdbuf()->close()` and, if that function fails (returns
6398
  a null pointer), calls `setstate(failbit)` (which may throw
6399
+ `ios_base::failure`) [[iostate.flags]].
6400
 
6401
  ``` cpp
6402
  void open(const string& s, ios_base::openmode mode = ios_base::out);
6403
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
6404
  ```
 
6422
  basic_fstream();
6423
  explicit basic_fstream(
6424
  const char* s,
6425
  ios_base::openmode mode = ios_base::in | ios_base::out);
6426
  explicit basic_fstream(
6427
+ const filesystem::path::value_type* s,
6428
  ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
6429
  explicit basic_fstream(
6430
  const string& s,
6431
  ios_base::openmode mode = ios_base::in | ios_base::out);
6432
  explicit basic_fstream(
6433
  const filesystem::path& s,
6434
  ios_base::openmode mode = ios_base::in | ios_base::out);
6435
+ basic_fstream(const basic_fstream&) = delete;
6436
  basic_fstream(basic_fstream&& rhs);
6437
 
6438
  // [fstream.assign], assign and swap
6439
+ basic_fstream& operator=(const basic_fstream&) = delete;
6440
  basic_fstream& operator=(basic_fstream&& rhs);
6441
  void swap(basic_fstream& rhs);
6442
 
6443
  // [fstream.members], members
6444
  basic_filebuf<charT, traits>* rdbuf() const;
6445
  bool is_open() const;
6446
  void open(
6447
  const char* s,
6448
  ios_base::openmode mode = ios_base::in | ios_base::out);
6449
  void open(
6450
+ const filesystem::path::value_type* s,
6451
  ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
6452
  void open(
6453
  const string& s,
6454
  ios_base::openmode mode = ios_base::in | ios_base::out);
6455
  void open(
 
6472
  object to control the associated sequences. For the sake of exposition,
6473
  the maintained data is presented here as:
6474
 
6475
  - `sb`, the `basic_filebuf` object.
6476
 
6477
+ #### Constructors <a id="fstream.cons">[[fstream.cons]]</a>
6478
 
6479
  ``` cpp
6480
  basic_fstream();
6481
  ```
6482
 
6483
+ *Effects:* Initializes the base class with
6484
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
6485
  `sb` with `basic_filebuf<charT, traits>()`.
6486
 
6487
  ``` cpp
6488
  explicit basic_fstream(
6489
  const char* s,
 
6491
  explicit basic_fstream(
6492
  const filesystem::path::value_type* s,
6493
  ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
6494
  ```
6495
 
6496
+ *Effects:* Initializes the base class with
6497
+ `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
6498
  `sb` with `basic_filebuf<charT, traits>()`. Then calls
6499
  `rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
6500
  `setstate(failbit)`.
6501
 
6502
  ``` cpp
 
6506
  explicit basic_fstream(
6507
  const filesystem::path& s,
6508
  ios_base::openmode mode = ios_base::in | ios_base::out);
6509
  ```
6510
 
6511
+ *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
6512
 
6513
  ``` cpp
6514
  basic_fstream(basic_fstream&& rhs);
6515
  ```
6516
 
6517
+ *Effects:* Move constructs the base class, and the contained
6518
+ `basic_filebuf`. Then calls
6519
+ `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
6520
+ contained `basic_filebuf`.
6521
 
6522
+ #### Assignment and swap <a id="fstream.assign">[[fstream.assign]]</a>
 
 
 
 
 
 
 
 
 
6523
 
6524
  ``` cpp
6525
  void swap(basic_fstream& rhs);
6526
  ```
6527
 
 
6532
  template<class charT, class traits>
6533
  void swap(basic_fstream<charT, traits>& x,
6534
  basic_fstream<charT, traits>& y);
6535
  ```
6536
 
6537
+ *Effects:* Equivalent to: `x.swap(y)`.
6538
 
6539
  #### Member functions <a id="fstream.members">[[fstream.members]]</a>
6540
 
6541
  ``` cpp
6542
  basic_filebuf<charT, traits>* rdbuf() const;
6543
  ```
6544
 
6545
+ *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
6546
 
6547
  ``` cpp
6548
  bool is_open() const;
6549
  ```
6550
 
 
6560
  ```
6561
 
6562
  *Effects:* Calls `rdbuf()->open(s, mode)`. If that function does not
6563
  return a null pointer calls `clear()`, otherwise calls
6564
  `setstate(failbit)` (which may throw
6565
+ `ios_base::failure`) [[iostate.flags]].
6566
 
6567
  ``` cpp
6568
  void open(
6569
  const string& s,
6570
  ios_base::openmode mode = ios_base::in | ios_base::out);
 
6579
  void close();
6580
  ```
6581
 
6582
  *Effects:* Calls `rdbuf()->close()` and, if that function returns a null
6583
  pointer, calls `setstate(failbit)` (which may throw
6584
+ `ios_base::failure`) [[iostate.flags]].
6585
+
6586
+ ## Synchronized output streams <a id="syncstream">[[syncstream]]</a>
6587
+
6588
+ ### Header `<syncstream>` synopsis <a id="syncstream.syn">[[syncstream.syn]]</a>
6589
+
6590
+ ``` cpp
6591
+ #include <ostream> // see [ostream.syn]
6592
+
6593
+ namespace std {
6594
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
6595
+ class basic_syncbuf;
6596
+
6597
+ using syncbuf = basic_syncbuf<char>;
6598
+ using wsyncbuf = basic_syncbuf<wchar_t>;
6599
+
6600
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
6601
+ class basic_osyncstream;
6602
+
6603
+ using osyncstream = basic_osyncstream<char>;
6604
+ using wosyncstream = basic_osyncstream<wchar_t>;
6605
+ }
6606
+ ```
6607
+
6608
+ The header `<syncstream>` provides a mechanism to synchronize execution
6609
+ agents writing to the same stream.
6610
+
6611
+ ### Class template `basic_syncbuf` <a id="syncstream.syncbuf">[[syncstream.syncbuf]]</a>
6612
+
6613
+ #### Overview <a id="syncstream.syncbuf.overview">[[syncstream.syncbuf.overview]]</a>
6614
+
6615
+ ``` cpp
6616
+ namespace std {
6617
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
6618
+ class basic_syncbuf : public basic_streambuf<charT, traits> {
6619
+ public:
6620
+ using char_type = charT;
6621
+ using int_type = typename traits::int_type;
6622
+ using pos_type = typename traits::pos_type;
6623
+ using off_type = typename traits::off_type;
6624
+ using traits_type = traits;
6625
+ using allocator_type = Allocator;
6626
+
6627
+ using streambuf_type = basic_streambuf<charT, traits>;
6628
+
6629
+ // [syncstream.syncbuf.cons], construction and destruction
6630
+ basic_syncbuf()
6631
+ : basic_syncbuf(nullptr) {}
6632
+ explicit basic_syncbuf(streambuf_type* obuf)
6633
+ : basic_syncbuf(obuf, Allocator()) {}
6634
+ basic_syncbuf(streambuf_type*, const Allocator&);
6635
+ basic_syncbuf(basic_syncbuf&&);
6636
+ ~basic_syncbuf();
6637
+
6638
+ // [syncstream.syncbuf.assign], assignment and swap
6639
+ basic_syncbuf& operator=(basic_syncbuf&&);
6640
+ void swap(basic_syncbuf&);
6641
+
6642
+ // [syncstream.syncbuf.members], member functions
6643
+ bool emit();
6644
+ streambuf_type* get_wrapped() const noexcept;
6645
+ allocator_type get_allocator() const noexcept;
6646
+ void set_emit_on_sync(bool) noexcept;
6647
+
6648
+ protected:
6649
+ // [syncstream.syncbuf.virtuals], overridden virtual functions
6650
+ int sync() override;
6651
+
6652
+ private:
6653
+ streambuf_type* wrapped; // exposition only
6654
+ bool emit_on_sync{}; // exposition only
6655
+ };
6656
+
6657
+ // [syncstream.syncbuf.special], specialized algorithms
6658
+ template<class charT, class traits, class Allocator>
6659
+ void swap(basic_syncbuf<charT, traits, Allocator>&,
6660
+ basic_syncbuf<charT, traits, Allocator>&);
6661
+ }
6662
+ ```
6663
+
6664
+ Class template `basic_syncbuf` stores character data written to it,
6665
+ known as the associated output, into internal buffers allocated using
6666
+ the object’s allocator. The associated output is transferred to the
6667
+ wrapped stream buffer object `*wrapped` when `emit()` is called or when
6668
+ the `basic_syncbuf` object is destroyed. Such transfers are atomic with
6669
+ respect to transfers by other `basic_syncbuf` objects with the same
6670
+ wrapped stream buffer object.
6671
+
6672
+ #### Construction and destruction <a id="syncstream.syncbuf.cons">[[syncstream.syncbuf.cons]]</a>
6673
+
6674
+ ``` cpp
6675
+ basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
6676
+ ```
6677
+
6678
+ *Effects:* Sets `wrapped` to `obuf`.
6679
+
6680
+ *Remarks:* A copy of `allocator` is used to allocate memory for internal
6681
+ buffers holding the associated output.
6682
+
6683
+ *Throws:* Nothing unless an exception is thrown by the construction of a
6684
+ mutex or by memory allocation.
6685
+
6686
+ *Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
6687
+ are `true`.
6688
+
6689
+ ``` cpp
6690
+ basic_syncbuf(basic_syncbuf&& other);
6691
+ ```
6692
+
6693
+ *Ensures:* The value returned by `this->get_wrapped()` is the value
6694
+ returned by `other.get_wrapped()` prior to calling this constructor.
6695
+ Output stored in `other` prior to calling this constructor will be
6696
+ stored in `*this` afterwards.
6697
+ `other.rdbuf()->pbase() == other.rdbuf()->pptr()` and
6698
+ `other.get_wrapped() == nullptr` are `true`.
6699
+
6700
+ *Remarks:* This constructor disassociates `other` from its wrapped
6701
+ stream buffer, ensuring destruction of `other` produces no output.
6702
+
6703
+ ``` cpp
6704
+ ~basic_syncbuf();
6705
+ ```
6706
+
6707
+ *Effects:* Calls `emit()`.
6708
+
6709
+ *Throws:* Nothing. If an exception is thrown from `emit()`, the
6710
+ destructor catches and ignores that exception.
6711
+
6712
+ #### Assignment and swap <a id="syncstream.syncbuf.assign">[[syncstream.syncbuf.assign]]</a>
6713
+
6714
+ ``` cpp
6715
+ basic_syncbuf& operator=(basic_syncbuf&& rhs) noexcept;
6716
+ ```
6717
+
6718
+ *Effects:* Calls `emit()` then move assigns from `rhs`. After the move
6719
+ assignment `*this` has the observable state it would have had if it had
6720
+ been move constructed from `rhs` [[syncstream.syncbuf.cons]].
6721
+
6722
+ *Returns:* `*this`.
6723
+
6724
+ *Ensures:*
6725
+
6726
+ - `rhs.get_wrapped() == nullptr` is `true`.
6727
+ - `this->get_allocator() == rhs.get_allocator()` is `true` when
6728
+ ``` cpp
6729
+ allocator_traits<Allocator>::propagate_on_container_move_assignment::value
6730
+ ```
6731
+
6732
+ is `true`; otherwise, the allocator is unchanged.
6733
+
6734
+ *Remarks:* This assignment operator disassociates `rhs` from its wrapped
6735
+ stream buffer, ensuring destruction of `rhs` produces no output.
6736
+
6737
+ ``` cpp
6738
+ void swap(basic_syncbuf& other) noexcept;
6739
+ ```
6740
+
6741
+ *Preconditions:* Either
6742
+ `allocator_traits<Allocator>::propagate_on_container_swap::value` is
6743
+ `true` or `this->get_allocator() == other.get_allocator()` is `true`.
6744
+
6745
+ *Effects:* Exchanges the state of `*this` and `other`.
6746
+
6747
+ #### Member functions <a id="syncstream.syncbuf.members">[[syncstream.syncbuf.members]]</a>
6748
+
6749
+ ``` cpp
6750
+ bool emit();
6751
+ ```
6752
+
6753
+ *Effects:* Atomically transfers the associated output of `*this` to the
6754
+ stream buffer `*wrapped`, so that it appears in the output stream as a
6755
+ contiguous sequence of characters. `wrapped->pubsync()` is called if and
6756
+ only if a call was made to `sync()` since the most recent call to
6757
+ `emit()`, if any.
6758
+
6759
+ *Returns:* `true` if all of the following conditions hold; otherwise
6760
+ `false`:
6761
+
6762
+ - `wrapped == nullptr` is `false`.
6763
+ - All of the characters in the associated output were successfully
6764
+ transferred.
6765
+ - The call to `wrapped->pubsync()` (if any) succeeded.
6766
+
6767
+ *Ensures:* On success, the associated output is empty.
6768
+
6769
+ *Synchronization:* All `emit()` calls transferring characters to the
6770
+ same stream buffer object appear to execute in a total order consistent
6771
+ with the “happens before” relation [[intro.races]], where each `emit()`
6772
+ call synchronizes with subsequent `emit()` calls in that total order.
6773
+
6774
+ *Remarks:* May call member functions of `wrapped` while holding a lock
6775
+ uniquely associated with `wrapped`.
6776
+
6777
+ ``` cpp
6778
+ streambuf_type* get_wrapped() const noexcept;
6779
+ ```
6780
+
6781
+ *Returns:* `wrapped`.
6782
+
6783
+ ``` cpp
6784
+ allocator_type get_allocator() const noexcept;
6785
+ ```
6786
+
6787
+ *Returns:* A copy of the allocator that was set in the constructor or
6788
+ assignment operator.
6789
+
6790
+ ``` cpp
6791
+ void set_emit_on_sync(bool b) noexcept;
6792
+ ```
6793
+
6794
+ *Effects:* `emit_on_sync = b`.
6795
+
6796
+ #### Overridden virtual functions <a id="syncstream.syncbuf.virtuals">[[syncstream.syncbuf.virtuals]]</a>
6797
+
6798
+ ``` cpp
6799
+ int sync() override;
6800
+ ```
6801
+
6802
+ *Effects:* Records that the wrapped stream buffer is to be flushed.
6803
+ Then, if `emit_on_sync` is `true`, calls `emit()`.
6804
+
6805
+ [*Note 1*: If `emit_on_sync` is `false`, the actual flush is delayed
6806
+ until a call to `emit()`. — *end note*]
6807
+
6808
+ *Returns:* If `emit()` was called and returned `false`, returns `-1`;
6809
+ otherwise `0`.
6810
+
6811
+ #### Specialized algorithms <a id="syncstream.syncbuf.special">[[syncstream.syncbuf.special]]</a>
6812
+
6813
+ ``` cpp
6814
+ template<class charT, class traits, class Allocator>
6815
+ void swap(basic_syncbuf<charT, traits, Allocator>& a,
6816
+ basic_syncbuf<charT, traits, Allocator>& b) noexcept;
6817
+ ```
6818
+
6819
+ *Effects:* Equivalent to `a.swap(b)`.
6820
+
6821
+ ### Class template `basic_osyncstream` <a id="syncstream.osyncstream">[[syncstream.osyncstream]]</a>
6822
+
6823
+ #### Overview <a id="syncstream.osyncstream.overview">[[syncstream.osyncstream.overview]]</a>
6824
+
6825
+ ``` cpp
6826
+ namespace std {
6827
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
6828
+ class basic_osyncstream : public basic_ostream<charT, traits> {
6829
+ public:
6830
+ using char_type = charT;
6831
+ using int_type = typename traits::int_type;
6832
+ using pos_type = typename traits::pos_type;
6833
+ using off_type = typename traits::off_type;
6834
+ using traits_type = traits;
6835
+
6836
+ using allocator_type = Allocator;
6837
+ using streambuf_type = basic_streambuf<charT, traits>;
6838
+ using syncbuf_type = basic_syncbuf<charT, traits, Allocator>;
6839
+
6840
+ // [syncstream.osyncstream.cons], construction and destruction
6841
+ basic_osyncstream(streambuf_type*, const Allocator&);
6842
+ explicit basic_osyncstream(streambuf_type* obuf)
6843
+ : basic_osyncstream(obuf, Allocator()) {}
6844
+ basic_osyncstream(basic_ostream<charT, traits>& os, const Allocator& allocator)
6845
+ : basic_osyncstream(os.rdbuf(), allocator) {}
6846
+ explicit basic_osyncstream(basic_ostream<charT, traits>& os)
6847
+ : basic_osyncstream(os, Allocator()) {}
6848
+ basic_osyncstream(basic_osyncstream&&) noexcept;
6849
+ ~basic_osyncstream();
6850
+
6851
+ // assignment
6852
+ basic_osyncstream& operator=(basic_osyncstream&&) noexcept;
6853
+
6854
+ // [syncstream.osyncstream.members], member functions
6855
+ void emit();
6856
+ streambuf_type* get_wrapped() const noexcept;
6857
+ syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); }
6858
+
6859
+ private:
6860
+ syncbuf_type sb; // exposition only
6861
+ };
6862
+ }
6863
+ ```
6864
+
6865
+ `Allocator` shall meet the *Cpp17Allocator* requirements (
6866
+ [[cpp17.allocator]]).
6867
+
6868
+ [*Example 1*:
6869
+
6870
+ A named variable can be used within a block statement for streaming.
6871
+
6872
+ ``` cpp
6873
+ {
6874
+ osyncstream bout(cout);
6875
+ bout << "Hello, ";
6876
+ bout << "World!";
6877
+ bout << endl; // flush is noted
6878
+ bout << "and more!\n";
6879
+ } // characters are transferred and cout is flushed
6880
+ ```
6881
+
6882
+ — *end example*]
6883
+
6884
+ [*Example 2*:
6885
+
6886
+ A temporary object can be used for streaming within a single statement.
6887
+
6888
+ ``` cpp
6889
+ osyncstream(cout) << "Hello, " << "World!" << '\n';
6890
+ ```
6891
+
6892
+ In this example, `cout` is not flushed.
6893
+
6894
+ — *end example*]
6895
+
6896
+ #### Construction and destruction <a id="syncstream.osyncstream.cons">[[syncstream.osyncstream.cons]]</a>
6897
+
6898
+ ``` cpp
6899
+ basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
6900
+ ```
6901
+
6902
+ *Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
6903
+ base class with `basic_ostream<charT, traits>(addressof(sb))`.
6904
+
6905
+ [*Note 1*: The member functions of the provided stream buffer might be
6906
+ called from `emit()` while a lock is held. Care should be taken to
6907
+ ensure that this does not result in deadlock. — *end note*]
6908
+
6909
+ *Ensures:* `get_wrapped() == buf` is `true`.
6910
+
6911
+ ``` cpp
6912
+ basic_osyncstream(basic_osyncstream&& other) noexcept;
6913
+ ```
6914
+
6915
+ *Effects:* Move constructs the base class and `sb` from the
6916
+ corresponding subobjects of `other`, and calls
6917
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
6918
+
6919
+ *Ensures:* The value returned by `get_wrapped()` is the value returned
6920
+ by `os.get_wrapped()` prior to calling this constructor.
6921
+ `nullptr == other.get_wrapped()` is `true`.
6922
+
6923
+ #### Member functions <a id="syncstream.osyncstream.members">[[syncstream.osyncstream.members]]</a>
6924
+
6925
+ ``` cpp
6926
+ void emit();
6927
+ ```
6928
+
6929
+ *Effects:* Calls `sb.emit()`. If that call returns `false`, calls
6930
+ `setstate(ios_base::badbit)`.
6931
+
6932
+ [*Example 1*:
6933
+
6934
+ A flush on a `basic_osyncstream` does not flush immediately:
6935
+
6936
+ ``` cpp
6937
+ {
6938
+ osyncstream bout(cout);
6939
+ bout << "Hello," << '\n'; // no flush
6940
+ bout.emit(); // characters transferred; cout not flushed
6941
+ bout << "World!" << endl; // flush noted; cout not flushed
6942
+ bout.emit(); // characters transferred; cout flushed
6943
+ bout << "Greetings." << '\n'; // no flush
6944
+ } // characters transferred; cout not flushed
6945
+ ```
6946
+
6947
+ — *end example*]
6948
+
6949
+ [*Example 2*:
6950
+
6951
+ The function `emit()` can be used to handle exceptions from operations
6952
+ on the underlying stream.
6953
+
6954
+ ``` cpp
6955
+ {
6956
+ osyncstream bout(cout);
6957
+ bout << "Hello, " << "World!" << '\n';
6958
+ try {
6959
+ bout.emit();
6960
+ } catch (...) {
6961
+ // handle exception
6962
+ }
6963
+ }
6964
+ ```
6965
+
6966
+ — *end example*]
6967
+
6968
+ ``` cpp
6969
+ streambuf_type* get_wrapped() const noexcept;
6970
+ ```
6971
+
6972
+ *Returns:* `sb.get_wrapped()`.
6973
+
6974
+ [*Example 3*:
6975
+
6976
+ Obtaining the wrapped stream buffer with `get_wrapped()` allows wrapping
6977
+ it again with an `osyncstream`. For example,
6978
+
6979
+ ``` cpp
6980
+ {
6981
+ osyncstream bout1(cout);
6982
+ bout1 << "Hello, ";
6983
+ {
6984
+ osyncstream(bout1.get_wrapped()) << "Goodbye, " << "Planet!" << '\n';
6985
+ }
6986
+ bout1 << "World!" << '\n';
6987
+ }
6988
+ ```
6989
+
6990
+ produces the *uninterleaved* output
6991
+
6992
+ ``` text
6993
+ Goodbye, Planet!
6994
+ Hello, World!
6995
+ ```
6996
+
6997
+ — *end example*]
6998
 
6999
  ## File systems <a id="filesystems">[[filesystems]]</a>
7000
 
7001
  ### General <a id="fs.general">[[fs.general]]</a>
7002
 
7003
+ Subclause  [[filesystems]] describes operations on file systems and
7004
+ their components, such as paths, regular files, and directories.
7005
+
7006
+ A *file system* is a collection of files and their attributes.
7007
+
7008
+ A *file* is an object within a file system that holds user or system
7009
+ data. Files can be written to, or read from, or both. A file has certain
7010
+ attributes, including type. File types include regular files and
7011
+ directories. Other types of files, such as symbolic links, may be
7012
+ supported by the implementation.
7013
+
7014
+ A *directory* is a file within a file system that acts as a container of
7015
+ directory entries that contain information about other files, possibly
7016
+ including other directory files. The *parent directory* of a directory
7017
+ is the directory that both contains a directory entry for the given
7018
+ directory and is represented by the dot-dot filename [[fs.path.generic]]
7019
+ in the given directory. The *parent directory* of other types of files
7020
+ is a directory containing a directory entry for the file under
7021
+ discussion.
7022
+
7023
+ A *link* is an object that associates a filename with a file. Several
7024
+ links can associate names with the same file. A *hard link* is a link to
7025
+ an existing file. Some file systems support multiple hard links to a
7026
+ file. If the last hard link to a file is removed, the file itself is
7027
+ removed.
7028
+
7029
+ [*Note 1*: A hard link can be thought of as a shared-ownership smart
7030
+ pointer to a file. — *end note*]
7031
+
7032
+ A *symbolic link* is a type of file with the property that when the file
7033
+ is encountered during pathname resolution [[fs.class.path]], a string
7034
+ stored by the file is used to modify the pathname resolution.
7035
+
7036
+ [*Note 2*: Symbolic links are often called symlinks. A symbolic link
7037
+ can be thought of as a raw pointer to a file. If the file pointed to
7038
+ does not exist, the symbolic link is said to be a “dangling” symbolic
7039
+ link. — *end note*]
7040
 
7041
  ### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
7042
 
7043
  Conformance is specified in terms of behavior. Ideal behavior is not
7044
  always implementable, so the conformance subclauses take that into
7045
  account.
7046
 
7047
  #### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
7048
 
7049
+ Some behavior is specified by reference to POSIX [[fs.norm.ref]]. How
7050
  such behavior is actually implemented is unspecified.
7051
 
7052
  [*Note 1*: This constitutes an “as if” rule allowing implementations to
7053
  call native operating system or other APIs. — *end note*]
7054
 
7055
+ Implementations should provide such behavior as it is defined by POSIX.
7056
+ Implementations shall document any behavior that differs from the
7057
+ behavior defined by POSIX. Implementations that do not support exact
7058
+ POSIX behavior should provide behavior as close to POSIX behavior as is
7059
+ reasonable given the limitations of actual operating systems and file
7060
+ systems. If an implementation cannot provide any reasonable behavior,
7061
+ the implementation shall report an error as specified in 
7062
+ [[fs.err.report]].
7063
 
7064
  [*Note 2*: This allows users to rely on an exception being thrown or an
7065
  error code being set when an implementation cannot provide any
7066
  reasonable behavior. — *end note*]
7067
 
 
7074
  required to support those features on the FAT file system but instead
7075
  are required to report an error as described above. — *end example*]
7076
 
7077
  #### Operating system dependent behavior conformance <a id="fs.conform.os">[[fs.conform.os]]</a>
7078
 
7079
+ Behavior that is specified as being *operating system dependent* is
7080
+ dependent upon the behavior and characteristics of an operating system.
7081
+ The operating system an implementation is dependent upon is
7082
+ *implementation-defined*.
7083
 
7084
  It is permissible for an implementation to be dependent upon an
7085
  operating system emulator rather than the actual underlying operating
7086
  system.
7087
 
7088
  #### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
7089
 
7090
+ A *file system race* is the condition that occurs when multiple threads,
7091
+ processes, or computers interleave access and modification of the same
7092
+ object within a file system. Behavior is undefined if calls to functions
7093
+ provided by subclause  [[fs.race.behavior]] introduce a file system
7094
+ race.
7095
 
7096
  If the possibility of a file system race would make it unreliable for a
7097
  program to test for a precondition before calling a function described
7098
+ herein, *Preconditions:* is not specified for the function.
7099
 
7100
  [*Note 1*: As a design practice, preconditions are not specified when
7101
  it is unreasonable for a program to detect them prior to calling the
7102
  function. — *end note*]
7103
 
7104
  ### Normative references <a id="fs.norm.ref">[[fs.norm.ref]]</a>
7105
 
7106
+ Subclause  [[filesystems]] mentions commercially available operating
7107
+ systems for purposes of exposition.[^41]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7108
 
7109
  ### Requirements <a id="fs.req">[[fs.req]]</a>
7110
 
7111
+ Throughout subclause  [[filesystems]], `char`, `wchar_t`, `char8_t`,
7112
+ `char16_t`, and `char32_t` are collectively called *encoded character
7113
+ types*.
7114
 
7115
  Functions with template parameters named `EcharT` shall not participate
7116
  in overload resolution unless `EcharT` is one of the encoded character
7117
  types.
7118
 
7119
+ Template parameters named `InputIterator` shall meet the
7120
+ *Cpp17InputIterator* requirements [[input.iterators]] and shall have a
7121
+ value type that is one of the encoded character types.
7122
 
7123
  [*Note 1*: Use of an encoded character type implies an associated
7124
  character set and encoding. Since `signed char` and `unsigned char` have
7125
  no implied character set and encoding, they are not included as
7126
  permitted types. — *end note*]
7127
 
7128
+ Template parameters named `Allocator` shall meet the *Cpp17Allocator*
7129
+ requirements ([[cpp17.allocator]]).
7130
 
7131
  #### Namespaces and headers <a id="fs.req.namespace">[[fs.req.namespace]]</a>
7132
 
7133
+ Unless otherwise specified, references to entities described in
7134
+ subclause  [[filesystems]] are assumed to be qualified with
7135
+ `::std::filesystem::`.
7136
 
7137
  ### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
7138
 
7139
  ``` cpp
7140
+ #include <compare> // see [compare.syn]
7141
+
7142
  namespace std::filesystem {
7143
  // [fs.class.path], paths
7144
  class path;
7145
 
7146
  // [fs.path.nonmember], path non-member functions
7147
  void swap(path& lhs, path& rhs) noexcept;
7148
  size_t hash_value(const path& p) noexcept;
7149
 
7150
+ // [fs.class.filesystem.error], filesystem errors
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7151
  class filesystem_error;
7152
 
7153
+ // [fs.class.directory.entry], directory entries
7154
  class directory_entry;
7155
 
7156
+ // [fs.class.directory.iterator], directory iterators
7157
  class directory_iterator;
7158
 
7159
  // [fs.dir.itr.nonmembers], range access for directory iterators
7160
  directory_iterator begin(directory_iterator iter) noexcept;
7161
  directory_iterator end(const directory_iterator&) noexcept;
 
7165
 
7166
  // [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
7167
  recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
7168
  recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
7169
 
7170
+ // [fs.class.file.status], file status
7171
  class file_status;
7172
 
7173
  struct space_info {
7174
  uintmax_t capacity;
7175
  uintmax_t free;
7176
  uintmax_t available;
7177
+
7178
+ friend bool operator==(const space_info&, const space_info&) = default;
7179
  };
7180
 
7181
  // [fs.enum], enumerations
7182
  enum class file_type;
7183
  enum class perms;
7184
  enum class perm_options;
7185
  enum class copy_options;
7186
  enum class directory_options;
7187
 
7188
+ using file_time_type = chrono::time_point<chrono::file_clock>;
7189
 
7190
  // [fs.op.funcs], filesystem operations
7191
+ path absolute(const path& p);
7192
+ path absolute(const path& p, error_code& ec);
7193
 
7194
+ path canonical(const path& p);
7195
  path canonical(const path& p, error_code& ec);
 
7196
 
7197
  void copy(const path& from, const path& to);
7198
+ void copy(const path& from, const path& to, error_code& ec);
7199
  void copy(const path& from, const path& to, copy_options options);
7200
  void copy(const path& from, const path& to, copy_options options,
7201
+ error_code& ec);
7202
 
7203
  bool copy_file(const path& from, const path& to);
7204
+ bool copy_file(const path& from, const path& to, error_code& ec);
7205
  bool copy_file(const path& from, const path& to, copy_options option);
7206
  bool copy_file(const path& from, const path& to, copy_options option,
7207
+ error_code& ec);
7208
 
7209
  void copy_symlink(const path& existing_symlink, const path& new_symlink);
7210
  void copy_symlink(const path& existing_symlink, const path& new_symlink,
7211
  error_code& ec) noexcept;
7212
 
7213
  bool create_directories(const path& p);
7214
+ bool create_directories(const path& p, error_code& ec);
7215
 
7216
  bool create_directory(const path& p);
7217
  bool create_directory(const path& p, error_code& ec) noexcept;
7218
 
7219
  bool create_directory(const path& p, const path& attributes);
 
7235
  path current_path();
7236
  path current_path(error_code& ec);
7237
  void current_path(const path& p);
7238
  void current_path(const path& p, error_code& ec) noexcept;
7239
 
7240
+ bool equivalent(const path& p1, const path& p2);
7241
+ bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
7242
+
7243
  bool exists(file_status s) noexcept;
7244
  bool exists(const path& p);
7245
  bool exists(const path& p, error_code& ec) noexcept;
7246
 
 
 
 
7247
  uintmax_t file_size(const path& p);
7248
  uintmax_t file_size(const path& p, error_code& ec) noexcept;
7249
 
7250
  uintmax_t hard_link_count(const path& p);
7251
  uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
 
7261
  bool is_directory(file_status s) noexcept;
7262
  bool is_directory(const path& p);
7263
  bool is_directory(const path& p, error_code& ec) noexcept;
7264
 
7265
  bool is_empty(const path& p);
7266
+ bool is_empty(const path& p, error_code& ec);
7267
 
7268
  bool is_fifo(file_status s) noexcept;
7269
  bool is_fifo(const path& p);
7270
  bool is_fifo(const path& p, error_code& ec) noexcept;
7271
 
 
7308
 
7309
  bool remove(const path& p);
7310
  bool remove(const path& p, error_code& ec) noexcept;
7311
 
7312
  uintmax_t remove_all(const path& p);
7313
+ uintmax_t remove_all(const path& p, error_code& ec);
7314
 
7315
  void rename(const path& from, const path& to);
7316
  void rename(const path& from, const path& to, error_code& ec) noexcept;
7317
 
7318
  void resize_file(const path& p, uintmax_t size);
 
7335
  path weakly_canonical(const path& p);
7336
  path weakly_canonical(const path& p, error_code& ec);
7337
  }
7338
  ```
7339
 
7340
+ Implementations should ensure that the resolution and range of
7341
+ `file_time_type` reflect the operating system dependent resolution and
7342
+ range of file time values.
 
 
7343
 
7344
  ### Error reporting <a id="fs.err.report">[[fs.err.report]]</a>
7345
 
7346
  Filesystem library functions often provide two overloads, one that
7347
  throws an exception to report file system errors, and another that sets
 
7387
  appropriate for the specific operating system dependent error.
7388
  Otherwise, `clear()` is called on the `error_code&` argument.
7389
 
7390
  ### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
7391
 
7392
+ An object of class `path` represents a path and contains a pathname.
7393
+ Such an object is concerned only with the lexical and syntactic aspects
7394
+ of a path. The path does not necessarily exist in external storage, and
7395
+ the pathname is not necessarily valid for the current operating system
7396
+ or for a particular file system.
 
7397
 
7398
  [*Note 1*: Class `path` is used to support the differences between the
7399
  string types used by different operating systems to represent pathnames,
7400
  and to perform conversions between encodings when
7401
  necessary. — *end note*]
7402
 
7403
+ A *path* is a sequence of elements that identify the location of a file
7404
+ within a filesystem. The elements are the *root-name*ₒₚₜ ,
7405
+ *root-directory*ₒₚₜ , and an optional sequence of *filename*s
7406
+ [[fs.path.generic]]. The maximum number of elements in the sequence is
7407
+ operating system dependent [[fs.conform.os]].
7408
+
7409
+ An *absolute path* is a path that unambiguously identifies the location
7410
+ of a file without reference to an additional starting location. The
7411
+ elements of a path that determine if it is absolute are operating system
7412
+ dependent. A *relative path* is a path that is not absolute, and as
7413
+ such, only unambiguously identifies the location of a file when resolved
7414
+ relative to an implied starting location. The elements of a path that
7415
+ determine if it is relative are operating system dependent.
7416
+
7417
+ [*Note 2*: Pathnames “.” and “..” are relative paths. — *end note*]
7418
+
7419
+ A *pathname* is a character string that represents the name of a path.
7420
+ Pathnames are formatted according to the generic pathname format grammar
7421
+ [[fs.path.generic]] or according to an operating system dependent
7422
+ *native pathname format* accepted by the host operating system.
7423
+
7424
+ *Pathname resolution* is the operating system dependent mechanism for
7425
+ resolving a pathname to a particular file in a file hierarchy. There may
7426
+ be multiple pathnames that resolve to the same file.
7427
+
7428
+ [*Example 1*: POSIX specifies the mechanism in section 4.11, Pathname
7429
+ resolution. — *end example*]
7430
+
7431
  ``` cpp
7432
  namespace std::filesystem {
7433
  class path {
7434
  public:
7435
  using value_type = see below;
 
7460
  path& operator=(string_type&& source);
7461
  path& assign(string_type&& source);
7462
  template<class Source>
7463
  path& operator=(const Source& source);
7464
  template<class Source>
7465
+ path& assign(const Source& source);
7466
  template<class InputIterator>
7467
  path& assign(InputIterator first, InputIterator last);
7468
 
7469
  // [fs.path.append], appends
7470
  path& operator/=(const path& p);
 
7496
  path& remove_filename();
7497
  path& replace_filename(const path& replacement);
7498
  path& replace_extension(const path& replacement = path());
7499
  void swap(path& rhs) noexcept;
7500
 
7501
+ // [fs.path.nonmember], non-member operators
7502
+ friend bool operator==(const path& lhs, const path& rhs) noexcept;
7503
+ friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
7504
+
7505
+ friend path operator/ (const path& lhs, const path& rhs);
7506
+
7507
  // [fs.path.native.obs], native format observers
7508
  const string_type& native() const noexcept;
7509
  const value_type* c_str() const noexcept;
7510
  operator string_type() const;
7511
 
 
7513
  class Allocator = allocator<EcharT>>
7514
  basic_string<EcharT, traits, Allocator>
7515
  string(const Allocator& a = Allocator()) const;
7516
  std::string string() const;
7517
  std::wstring wstring() const;
7518
+ std::u8string u8string() const;
7519
  std::u16string u16string() const;
7520
  std::u32string u32string() const;
7521
 
7522
  // [fs.path.generic.obs], generic format observers
7523
  template<class EcharT, class traits = char_traits<EcharT>,
7524
  class Allocator = allocator<EcharT>>
7525
  basic_string<EcharT, traits, Allocator>
7526
  generic_string(const Allocator& a = Allocator()) const;
7527
  std::string generic_string() const;
7528
  std::wstring generic_wstring() const;
7529
+ std::u8string generic_u8string() const;
7530
  std::u16string generic_u16string() const;
7531
  std::u32string generic_u32string() const;
7532
 
7533
  // [fs.path.compare], compare
7534
  int compare(const path& p) const noexcept;
 
7545
  path filename() const;
7546
  path stem() const;
7547
  path extension() const;
7548
 
7549
  // [fs.path.query], query
7550
+ [[nodiscard]] bool empty() const noexcept;
7551
  bool has_root_name() const;
7552
  bool has_root_directory() const;
7553
  bool has_root_path() const;
7554
  bool has_relative_path() const;
7555
  bool has_parent_path() const;
 
7568
  class iterator;
7569
  using const_iterator = iterator;
7570
 
7571
  iterator begin() const;
7572
  iterator end() const;
7573
+
7574
+ // [fs.path.io], path inserter and extractor
7575
+ template<class charT, class traits>
7576
+ friend basic_ostream<charT, traits>&
7577
+ operator<<(basic_ostream<charT, traits>& os, const path& p);
7578
+ template<class charT, class traits>
7579
+ friend basic_istream<charT, traits>&
7580
+ operator>>(basic_istream<charT, traits>& is, path& p);
7581
  };
7582
  }
7583
  ```
7584
 
7585
  `value_type` is a `typedef` for the operating system dependent encoded
7586
  character type used to represent pathnames.
7587
 
7588
  The value of the `preferred_separator` member is the operating system
7589
+ dependent *preferred-separator* character [[fs.path.generic]].
7590
 
7591
+ [*Example 2*: For POSIX-based operating systems, `value_type` is `char`
7592
  and `preferred_separator` is the slash character (`'/'`). For
7593
  Windows-based operating systems, `value_type` is `wchar_t` and
7594
  `preferred_separator` is the backslash character
7595
  (`L'\\'`). — *end example*]
7596
 
 
7638
  ``` bnf
7639
  fallback-separator:
7640
  /, if *preferred-separator* is not /
7641
  ```
7642
 
7643
+ A *filename* is the name of a file. The *dot* and *dot-dot* filenames,
7644
+ consisting solely of one and two period characters respectively, have
7645
+ special meaning. The following characteristics of filenames are
7646
+ operating system dependent:
7647
+
7648
+ - The permitted characters. \[*Example 1*: Some operating systems
7649
+ prohibit the ASCII control characters (0x00 – 0x1F) in
7650
+ filenames. — *end example*] \[*Note 1*: For wide portability, users
7651
+ may wish to limit *filename* characters to the POSIX Portable Filename
7652
+ Character Set:
7653
  `A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
7654
  `a b c d e f g h i j k l m n o p q r s t u v w x y z`
7655
  `0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
7656
+ - The maximum permitted length.
7657
+ - Filenames that are not permitted.
7658
+ - Filenames that have special meaning.
7659
+ - Case awareness and sensitivity during path resolution.
7660
+ - Special rules that may apply to file types other than regular files,
7661
+ such as directories.
7662
 
7663
  Except in a *root-name*, multiple successive *directory-separator*
7664
  characters are considered to be the same as one *directory-separator*
7665
  character.
7666
 
7667
+ The dot filename is treated as a reference to the current directory. The
7668
+ dot-dot filename is treated as a reference to the parent directory. What
7669
+ the dot-dot filename refers to relative to *root-directory* is
 
7670
  *implementation-defined*. Specific filenames may have special meanings
7671
  for a particular operating system.
7672
 
7673
+ A *root-name* identifies the starting location for pathname resolution
7674
+ [[fs.class.path]]. If there are no operating system dependent
7675
  *root-name*s, at least one *implementation-defined* *root-name* is
7676
  required.
7677
 
7678
  [*Note 2*: Many operating systems define a name beginning with two
7679
  *directory-separator* characters as a *root-name* that identifies
 
7686
 
7687
  [*Note 3*: On a POSIX-like operating system, it is impossible to have a
7688
  *root-name* and a *relative-path* without an intervening
7689
  *root-directory* element. — *end note*]
7690
 
7691
+ *Normalization* of a generic format pathname means:
7692
 
7693
+ 1. If the path is empty, stop.
7694
+ 2. Replace each slash character in the *root-name* with a
7695
+ *preferred-separator*.
7696
+ 3. Replace each *directory-separator* with a *preferred-separator*.
7697
+ \[*Note 4*: The generic pathname grammar [[fs.path.generic]] defines
7698
+ *directory-separator* as one or more slashes and
7699
+ *preferred-separator*s. — *end note*]
7700
+ 4. Remove each dot filename and any immediately following
7701
+ *directory-separator*.
7702
+ 5. As long as any appear, remove a non-dot-dot filename immediately
7703
+ followed by a *directory-separator* and a dot-dot filename, along
7704
+ with any immediately following *directory-separator*.
7705
+ 6. If there is a *root-directory*, remove all dot-dot filenames and any
7706
+ *directory-separator*s immediately following them. \[*Note 5*: These
7707
+ dot-dot filenames attempt to refer to nonexistent parent
7708
+ directories. — *end note*]
7709
+ 7. If the last filename is dot-dot, remove any trailing
7710
+ *directory-separator*.
7711
+ 8. If the path is empty, add a dot.
7712
+
7713
+ The result of normalization is a path in *normal form*, which is said to
7714
+ be *normalized*.
7715
+
7716
+ #### Conversions <a id="fs.path.cvt">[[fs.path.cvt]]</a>
7717
+
7718
+ ##### Argument format conversions <a id="fs.path.fmt.cvt">[[fs.path.fmt.cvt]]</a>
7719
 
7720
  [*Note 1*:
7721
 
7722
+ The format conversions described in this subclause are not applied on
7723
  POSIX-based operating systems because on these systems:
7724
 
7725
  - The generic format is acceptable as a native path.
7726
  - There is no need to distinguish between native format and generic
7727
  format in function arguments.
 
7730
 
7731
  — *end note*]
7732
 
7733
  Several functions are defined to accept *detected-format* arguments,
7734
  which are character sequences. A detected-format argument represents a
7735
+ path using either a pathname in the generic format [[fs.path.generic]]
7736
+ or a pathname in the native format [[fs.class.path]]. Such an argument
7737
+ is taken to be in the generic format if and only if it matches the
7738
+ generic format and is not acceptable to the operating system as a native
7739
+ path.
7740
 
7741
  [*Note 2*: Some operating systems may have no unambiguous way to
7742
  distinguish between native format and generic format arguments. This is
7743
  by design as it simplifies use for operating systems that do not require
7744
  disambiguation. An implementation for an operating system where
 
7757
  If the native format requires paths for regular files to be formatted
7758
  differently from paths for directories, the path shall be treated as a
7759
  directory path if its last element is a *directory-separator*, otherwise
7760
  it shall be treated as a path to a regular file.
7761
 
7762
+ [*Note 4*: A path stores a native format pathname
7763
+ [[fs.path.native.obs]] and acts as if it also stores a generic format
7764
  pathname, related as given below. The implementation may generate the
7765
  generic format pathname based on the native format pathname (and
7766
  possibly other information) when requested. — *end note*]
7767
 
7768
  When a path is constructed from or is assigned a single representation
 
7775
  as appropriate) if any such value does so; *q* is otherwise unspecified.
7776
 
7777
  [*Note 5*: If *q* is the result of converting any path at all, it is
7778
  the result of converting *p*. — *end note*]
7779
 
7780
+ ##### Type and encoding conversions <a id="fs.path.type.cvt">[[fs.path.type.cvt]]</a>
7781
+
7782
+ The *native encoding* of an ordinary character string is the operating
7783
+ system dependent current encoding for pathnames [[fs.class.path]]. The
7784
+ *native encoding* for wide character strings is the
7785
+ implementation-defined execution wide-character set encoding
7786
+ [[lex.charset]].
7787
 
7788
  For member function arguments that take character sequences representing
7789
  paths and for member functions returning strings, value type and
7790
  encoding conversion is performed if the value type of the argument or
7791
  return value differs from `path::value_type`. For the argument or return
7792
  value, the method of conversion and the encoding to be converted to is
7793
  determined by its value type:
7794
 
7795
+ - `char`: The encoding is the native ordinary encoding. The method of
7796
+ conversion, if any, is operating system dependent. \[*Note 6*: For
7797
+ POSIX-based operating systems `path::value_type` is `char` so no
7798
+ conversion from `char` value type arguments or to `char` value type
7799
+ return values is performed. For Windows-based operating systems, the
7800
+ native ordinary encoding is determined by calling a Windows API
 
7801
  function. — *end note*] \[*Note 7*: This results in behavior
7802
  identical to other C and C++ standard library functions that perform
7803
+ file operations using ordinary character strings to identify paths.
7804
  Changing this behavior would be surprising and error
7805
  prone. — *end note*]
7806
+ - `wchar_t`: The encoding is the native wide encoding. The method of
7807
+ conversion is unspecified. \[*Note 8*: For Windows-based operating
7808
+ systems `path::value_type` is `wchar_t` so no conversion from
7809
+ `wchar_t` value type arguments or to `wchar_t` value type return
7810
+ values is performed. — *end note*]
7811
+ - `char8_t`: The encoding is UTF-8. The method of conversion is
7812
+ unspecified.
7813
  - `char16_t`: The encoding is UTF-16. The method of conversion is
7814
  unspecified.
7815
  - `char32_t`: The encoding is UTF-32. The method of conversion is
7816
  unspecified.
7817
 
7818
  If the encoding being converted to has no representation for source
7819
  characters, the resulting converted characters, if any, are unspecified.
7820
  Implementations should not modify member function arguments if already
7821
  of type `path::value_type`.
7822
 
7823
+ #### Requirements <a id="fs.path.req">[[fs.path.req]]</a>
7824
 
7825
+ In addition to the requirements [[fs.req]], function template parameters
7826
+ named `Source` shall be one of:
7827
 
7828
  - `basic_string<EcharT, traits, Allocator>`. A function argument
7829
  `const Source&` `source` shall have an effective range
7830
  \[`source.begin()`, `source.end()`).
7831
  - `basic_string_view<EcharT, traits>`. A function argument
7832
  `const Source&` `source` shall have an effective range
7833
  \[`source.begin()`, `source.end()`).
7834
+ - A type meeting the *Cpp17InputIterator* requirements that iterates
7835
+ over a NTCTS. The value type shall be an encoded character type. A
7836
+ function argument `const Source&` `source` shall have an effective
7837
+ range \[`source`, `end`) where `end` is the first iterator value with
7838
+ an element value equal to `iterator_traits<Source>::value_type()`.
7839
  - A character array that after array-to-pointer decay results in a
7840
  pointer to the start of a NTCTS. The value type shall be an encoded
7841
  character type. A function argument `const Source&` `source` shall
7842
  have an effective range \[`source`, `end`) where `end` is the first
7843
  iterator value with an element value equal to
7844
  `iterator_traits<decay_t<Source>>::value_type()`.
7845
 
7846
  Functions taking template parameters named `Source` shall not
7847
+ participate in overload resolution unless `Source` denotes a type other
7848
+ than `path`, and either
7849
 
7850
  - `Source` is a specialization of `basic_string` or `basic_string_view`,
7851
  or
7852
  - the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
7853
+ valid and denotes a possibly `const` encoded character type
7854
+ [[temp.deduct]].
7855
 
7856
+ [*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
7857
+ above and their encodings convert to `path::value_type` and its
7858
  encoding. — *end note*]
7859
 
7860
  Arguments of type `Source` shall not be null pointers.
7861
 
7862
+ #### Members <a id="fs.path.member">[[fs.path.member]]</a>
7863
 
7864
+ ##### Constructors <a id="fs.path.construct">[[fs.path.construct]]</a>
7865
 
7866
  ``` cpp
7867
  path() noexcept;
7868
  ```
7869
 
7870
+ *Ensures:* `empty() == true`.
 
 
7871
 
7872
  ``` cpp
7873
  path(const path& p);
7874
  path(path&& p) noexcept;
7875
  ```
 
7882
  ``` cpp
7883
  path(string_type&& source, format fmt = auto_format);
7884
  ```
7885
 
7886
  *Effects:* Constructs an object of class `path` for which the pathname
7887
+ in the detected-format of `source` has the original value of `source`
7888
+ [[fs.path.fmt.cvt]], converting format if required [[fs.path.fmt.cvt]].
7889
+ `source` is left in a valid but unspecified state.
 
7890
 
7891
  ``` cpp
7892
  template<class Source>
7893
  path(const Source& source, format fmt = auto_format);
7894
  template<class InputIterator>
7895
  path(InputIterator first, InputIterator last, format fmt = auto_format);
7896
  ```
7897
 
7898
+ *Effects:* Let `s` be the effective range of `source` [[fs.path.req]] or
7899
+ the range \[`first`, `last`), with the encoding converted if
7900
+ required [[fs.path.cvt]]. Finds the detected-format of `s`
7901
+ [[fs.path.fmt.cvt]] and constructs an object of class `path` for which
7902
+ the pathname in that format is `s`.
7903
 
7904
  ``` cpp
7905
  template<class Source>
7906
  path(const Source& source, const locale& loc, format fmt = auto_format);
7907
  template<class InputIterator>
7908
  path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
7909
  ```
7910
 
7911
+ *Mandates:* The value type of `Source` and `InputIterator` is `char`.
7912
 
7913
  *Effects:* Let `s` be the effective range of `source` or the range
7914
  \[`first`, `last`), after converting the encoding as follows:
7915
 
7916
  - If `value_type` is `wchar_t`, converts to the native wide
7917
+ encoding [[fs.path.type.cvt]] using the
7918
  `codecvt<wchar_t, char, mbstate_t>` facet of `loc`.
7919
  - Otherwise a conversion is performed using the
7920
  `codecvt<wchar_t, char, mbstate_t>` facet of `loc`, and then a second
7921
+ conversion to the current ordinary encoding.
7922
 
7923
+ Finds the detected-format of `s` [[fs.path.fmt.cvt]] and constructs an
7924
+ object of class `path` for which the pathname in that format is `s`.
7925
 
7926
  [*Example 1*:
7927
 
7928
  A string is to be read from a database that is encoded in ISO/IEC
7929
  8859-1, and used to create a directory:
 
7937
  ```
7938
 
7939
  For POSIX-based operating systems, the path is constructed by first
7940
  using `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string`
7941
  to a wide character string in the native wide
7942
+ encoding [[fs.path.type.cvt]]. The resulting wide string is then
7943
+ converted to an ordinary character pathname string in the current native
7944
+ ordinary encoding. If the native wide encoding is UTF-16 or UTF-32, and
7945
+ the current native ordinary encoding is UTF-8, all of the characters in
7946
  the ISO/IEC 8859-1 character set will be converted to their Unicode
7947
+ representation, but for other native ordinary encodings some characters
7948
  may have no representation.
7949
 
7950
  For Windows-based operating systems, the path is constructed by using
7951
  `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string` to a
7952
  UTF-16 encoded wide character pathname string. All of the characters in
7953
  the ISO/IEC 8859-1 character set will be converted to their Unicode
7954
  representation.
7955
 
7956
  — *end example*]
7957
 
7958
+ ##### Assignments <a id="fs.path.assign">[[fs.path.assign]]</a>
7959
 
7960
  ``` cpp
7961
  path& operator=(const path& p);
7962
  ```
7963
 
 
7997
  path& assign(const Source& source);
7998
  template<class InputIterator>
7999
  path& assign(InputIterator first, InputIterator last);
8000
  ```
8001
 
8002
+ *Effects:* Let `s` be the effective range of `source` [[fs.path.req]] or
8003
+ the range \[`first`, `last`), with the encoding converted if
8004
+ required [[fs.path.cvt]]. Finds the detected-format of `s`
8005
+ [[fs.path.fmt.cvt]] and sets the pathname in that format to `s`.
8006
 
8007
  *Returns:* `*this`.
8008
 
8009
+ ##### Appends <a id="fs.path.append">[[fs.path.append]]</a>
8010
 
8011
  The append operations use `operator/=` to denote their semantic effect
8012
  of appending *preferred-separator* when needed.
8013
 
8014
  ``` cpp
 
8031
  pathname.
8032
 
8033
  [*Example 2*:
8034
 
8035
  Even if `//host` is interpreted as a *root-name*, both of the paths
8036
+ `path("//host")/"foo"` and `path("//host/")/"foo"` equal `"//host/foo"`
8037
+ (although the former might use backslash as the preferred separator).
8038
 
8039
  Expression examples:
8040
 
8041
  ``` cpp
8042
  // On POSIX,
8043
+ path("foo") /= path(""); // yields path("foo/")
8044
+ path("foo") /= path("/bar"); // yields path("/bar")
 
8045
 
8046
  // On Windows,
8047
+ path("foo") /= path(""); // yields path("foo\{")}
8048
+ path("foo") /= path("/bar"); // yields path("/bar")
8049
+ path("foo") /= path("c:/bar"); // yields path("c:/bar")
8050
+ path("foo") /= path("c:"); // yields path("c:")
8051
+ path("c:") /= path(""); // yields path("c:")
8052
+ path("c:foo") /= path("/bar"); // yields path("c:/bar")
8053
+ path("c:foo") /= path("c:bar"); // yields path("c:foo\{bar")}
8054
  ```
8055
 
8056
  — *end example*]
8057
 
8058
  *Returns:* `*this`.
 
8071
  path& append(InputIterator first, InputIterator last);
8072
  ```
8073
 
8074
  *Effects:* Equivalent to: `return operator/=(path(first, last));`
8075
 
8076
+ ##### Concatenation <a id="fs.path.concat">[[fs.path.concat]]</a>
8077
 
8078
  ``` cpp
8079
  path& operator+=(const path& x);
8080
  path& operator+=(const string_type& x);
8081
  path& operator+=(basic_string_view<value_type> x);
8082
  path& operator+=(const value_type* x);
 
8083
  template<class Source>
8084
  path& operator+=(const Source& x);
 
 
8085
  template<class Source>
8086
  path& concat(const Source& x);
8087
  ```
8088
 
8089
  *Effects:* Appends `path(x).native()` to the pathname in the native
 
8092
  [*Note 2*: This directly manipulates the value of `native()` and may
8093
  not be portable between operating systems. — *end note*]
8094
 
8095
  *Returns:* `*this`.
8096
 
8097
+ ``` cpp
8098
+ path& operator+=(value_type x);
8099
+ template<class EcharT>
8100
+ path& operator+=(EcharT x);
8101
+ ```
8102
+
8103
+ *Effects:* Equivalent to: `return *this += basic_string_view(&x, 1);`
8104
+
8105
  ``` cpp
8106
  template<class InputIterator>
8107
  path& concat(InputIterator first, InputIterator last);
8108
  ```
8109
 
8110
+ *Effects:* Equivalent to: `return *this += path(first, last);`
8111
 
8112
+ ##### Modifiers <a id="fs.path.modifiers">[[fs.path.modifiers]]</a>
8113
 
8114
  ``` cpp
8115
  void clear() noexcept;
8116
  ```
8117
 
8118
+ *Ensures:* `empty() == true`.
8119
 
8120
  ``` cpp
8121
  path& make_preferred();
8122
  ```
8123
 
 
8155
 
8156
  ``` cpp
8157
  path& remove_filename();
8158
  ```
8159
 
 
 
8160
  *Effects:* Remove the generic format pathname of `filename()` from the
8161
  generic format pathname.
8162
 
8163
+ *Ensures:* `!has_filename()`.
8164
+
8165
  *Returns:* `*this`.
8166
 
8167
  [*Example 4*:
8168
 
8169
  ``` cpp
 
8201
  path& replace_extension(const path& replacement = path());
8202
  ```
8203
 
8204
  *Effects:*
8205
 
8206
+ - Any existing `extension()` [[fs.path.decompose]] is removed from the
8207
+ pathname in the generic format, then
8208
  - If `replacement` is not empty and does not begin with a dot character,
8209
  a dot character is appended to the pathname in the generic format,
8210
  then
8211
  - `operator+=(replacement);`.
8212
 
 
8218
 
8219
  *Effects:* Swaps the contents (in all formats) of the two paths.
8220
 
8221
  *Complexity:* Constant time.
8222
 
8223
+ ##### Native format observers <a id="fs.path.native.obs">[[fs.path.native.obs]]</a>
8224
 
8225
  The string returned by all native format observers is in the native
8226
+ pathname format [[fs.class.path]].
8227
 
8228
  ``` cpp
8229
  const string_type& native() const noexcept;
8230
  ```
8231
 
 
8233
 
8234
  ``` cpp
8235
  const value_type* c_str() const noexcept;
8236
  ```
8237
 
8238
+ *Effects:* Equivalent to: `return native().c_str();`
8239
 
8240
  ``` cpp
8241
  operator string_type() const;
8242
  ```
8243
 
 
8261
  [[fs.path.cvt]].
8262
 
8263
  ``` cpp
8264
  std::string string() const;
8265
  std::wstring wstring() const;
8266
+ std::u8string u8string() const;
8267
  std::u16string u16string() const;
8268
  std::u32string u32string() const;
8269
  ```
8270
 
8271
+ *Returns:* `native()`.
8272
 
8273
  *Remarks:* Conversion, if any, is performed as specified by
8274
+ [[fs.path.cvt]].
 
8275
 
8276
+ ##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
8277
 
8278
  Generic format observer functions return strings formatted according to
8279
+ the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
8280
+ character is used as the *directory-separator*.
8281
 
8282
  [*Example 1*:
8283
 
8284
  On an operating system that uses backslash as its *preferred-separator*,
8285
 
 
8305
  [[fs.path.cvt]].
8306
 
8307
  ``` cpp
8308
  std::string generic_string() const;
8309
  std::wstring generic_wstring() const;
8310
+ std::u8string generic_u8string() const;
8311
  std::u16string generic_u16string() const;
8312
  std::u32string generic_u32string() const;
8313
  ```
8314
 
8315
  *Returns:* The pathname in the generic format.
8316
 
8317
+ *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]].
 
8318
 
8319
+ ##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
8320
 
8321
  ``` cpp
8322
  int compare(const path& p) const noexcept;
8323
  ```
8324
 
8325
  *Returns:*
8326
 
8327
+ - Let `rootNameComparison` be the result of
8328
+ `this->root_name().native().compare(p.root_name().native())`. If
8329
+ `rootNameComparison` is not `0`, `rootNameComparison`.
8330
+ - Otherwise, if `!this->has_root_directory()` and
8331
+ `p.has_root_directory()`, a value less than `0`.
8332
+ - Otherwise, if `this->has_root_directory()` and
8333
+ `!p.has_root_directory()`, a value greater than `0`.
8334
+ - Otherwise, if `native()` for the elements of `this->relative_path()`
8335
+ are lexicographically less than `native()` for the elements of
8336
+ `p.relative_path()`, a value less than `0`.
8337
+ - Otherwise, if `native()` for the elements of `this->relative_path()`
8338
+ are lexicographically greater than `native()` for the elements of
8339
+ `p.relative_path()`, a value greater than `0`.
8340
+ - Otherwise, `0`.
8341
 
8342
  ``` cpp
8343
+ int compare(const string_type& s) const;
8344
  int compare(basic_string_view<value_type> s) const;
8345
+ int compare(const value_type* s) const;
8346
  ```
8347
 
8348
+ *Effects:* Equivalent to: `return compare(path(s));`
8349
 
8350
+ ##### Decomposition <a id="fs.path.decompose">[[fs.path.decompose]]</a>
 
 
 
 
 
 
8351
 
8352
  ``` cpp
8353
  path root_name() const;
8354
  ```
8355
 
 
8372
  ``` cpp
8373
  path relative_path() const;
8374
  ```
8375
 
8376
  *Returns:* A `path` composed from the pathname in the generic format, if
8377
+ `empty()` is `false`, beginning with the first *filename* after
8378
+ `root_path()`. Otherwise, `path()`.
8379
 
8380
  ``` cpp
8381
  path parent_path() const;
8382
  ```
8383
 
8384
+ *Returns:* `*this` if `has_relative_path()` is `false`, otherwise a path
8385
+ whose generic format pathname is the longest prefix of the generic
8386
+ format pathname of `*this` that produces one fewer element in its
8387
+ iteration.
8388
 
8389
  ``` cpp
8390
  path filename() const;
8391
  ```
8392
 
 
8433
 
8434
  ``` cpp
8435
  path extension() const;
8436
  ```
8437
 
8438
+ *Returns:* A path whose pathname in the generic format is the suffix of
8439
  `filename()` not included in `stem()`.
8440
 
8441
  [*Example 8*:
8442
 
8443
  ``` cpp
 
8456
 
8457
  [*Note 5*: On non-POSIX operating systems, for a path `p`, it may not
8458
  be the case that `p.stem() + p.extension() == p.filename()`, even though
8459
  the generic format pathnames are the same. — *end note*]
8460
 
8461
+ ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
8462
 
8463
  ``` cpp
8464
+ [[nodiscard]] bool empty() const noexcept;
8465
  ```
8466
 
8467
+ *Returns:* `true` if the pathname in the generic format is empty,
8468
+ otherwise `false`.
8469
 
8470
  ``` cpp
8471
  bool has_root_path() const;
8472
  ```
8473
 
 
8518
  ``` cpp
8519
  bool is_absolute() const;
8520
  ```
8521
 
8522
  *Returns:* `true` if the pathname in the native format contains an
8523
+ absolute path [[fs.class.path]], otherwise `false`.
8524
 
8525
  [*Example 9*: `path("/").is_absolute()` is `true` for POSIX-based
8526
  operating systems, and `false` for Windows-based operating
8527
  systems. — *end example*]
8528
 
 
8530
  bool is_relative() const;
8531
  ```
8532
 
8533
  *Returns:* `!is_absolute()`.
8534
 
8535
+ ##### Generation <a id="fs.path.gen">[[fs.path.gen]]</a>
8536
 
8537
  ``` cpp
8538
  path lexically_normal() const;
8539
  ```
8540
 
8541
  *Returns:* A path whose pathname in the generic format is the normal
8542
+ form [[fs.path.generic]] of the pathname in the generic format of
8543
  `*this`.
8544
 
8545
  [*Example 10*:
8546
 
8547
  ``` cpp
 
8558
  ``` cpp
8559
  path lexically_relative(const path& base) const;
8560
  ```
8561
 
8562
  *Returns:* `*this` made relative to `base`. Does not
8563
+ resolve [[fs.class.path]] symlinks. Does not first
8564
+ normalize [[fs.path.generic]] `*this` or `base`.
8565
+
8566
+ *Effects:* If:
8567
+
8568
+ - `root_name() != base.root_name()` is `true`, or
8569
+ - `is_absolute() != base.is_absolute()` is `true`, or
8570
+ - `!has_root_directory() && base.has_root_directory()` is `true`, or
8571
+ - any *filename* in `relative_path()` or `base.relative_path()` can be
8572
+ interpreted as a *root-name*,
8573
+
8574
+ returns `path()`.
8575
+
8576
+ [*Note 6*: On a POSIX implementation, no *filename* in a
8577
+ *relative-path* is acceptable as a *root-name*. — *end note*]
8578
+
8579
+ Determines the first mismatched element of `*this` and `base` as if by:
8580
 
8581
  ``` cpp
8582
  auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
8583
  ```
8584
 
8585
  Then,
8586
 
8587
  - if `a == end()` and `b == base.end()`, returns `path(".")`; otherwise
8588
  - let `n` be the number of *filename* elements in \[`b`, `base.end()`)
8589
+ that are not dot or dot-dot or empty, minus the number that are
8590
+ dot-dot. If `n<0,` returns `path()`; otherwise
8591
+ - if `n == 0` and `(a == end() || a->empty())`, returns `path(".")`;
8592
+ otherwise
8593
  - returns an object of class `path` that is default-constructed,
8594
  followed by
8595
  - application of `operator/=(path(".."))` `n` times, and then
8596
  - application of `operator/=` for each element in \[`a`, `end()`).
8597
 
 
8610
  *directory-separator* characters will be backslashes rather than
8611
  slashes, but that does not affect `path` equality.
8612
 
8613
  — *end example*]
8614
 
8615
+ [*Note 7*: If symlink following semantics are desired, use the
8616
  operational function `relative()`. — *end note*]
8617
 
8618
+ [*Note 8*: If normalization [[fs.path.generic]] is needed to ensure
8619
+ consistent matching of elements, apply `lexically_normal()` to `*this`,
8620
+ `base`, or both. — *end note*]
8621
 
8622
  ``` cpp
8623
  path lexically_proximate(const path& base) const;
8624
  ```
8625
 
8626
  *Returns:* If the value of `lexically_relative(base)` is not an empty
8627
  path, return it. Otherwise return `*this`.
8628
 
8629
+ [*Note 9*: If symlink following semantics are desired, use the
8630
  operational function `proximate()`. — *end note*]
8631
 
8632
+ [*Note 10*: If normalization [[fs.path.generic]] is needed to ensure
8633
+ consistent matching of elements, apply `lexically_normal()` to `*this`,
8634
+ `base`, or both. — *end note*]
8635
 
8636
+ #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
8637
 
8638
  Path iterators iterate over the elements of the pathname in the generic
8639
+ format [[fs.path.generic]].
8640
 
8641
+ A `path::iterator` is a constant iterator meeting all the requirements
8642
+ of a bidirectional iterator [[bidirectional.iterators]] except that, for
8643
+ dereferenceable iterators `a` and `b` of type `path::iterator` with
8644
+ `a == b`, there is no requirement that `*a` and `*b` are bound to the
8645
+ same object. Its `value_type` is `path`.
8646
 
8647
  Calling any non-const member function of a `path` object invalidates all
8648
  iterators referring to elements of that object.
8649
 
8650
  For the elements of the pathname in the generic format, the forward
 
8671
  iterator end() const;
8672
  ```
8673
 
8674
  *Returns:* The end iterator.
8675
 
8676
+ #### Inserter and extractor <a id="fs.path.io">[[fs.path.io]]</a>
8677
+
8678
+ ``` cpp
8679
+ template<class charT, class traits>
8680
+ friend basic_ostream<charT, traits>&
8681
+ operator<<(basic_ostream<charT, traits>& os, const path& p);
8682
+ ```
8683
+
8684
+ *Effects:* Equivalent to `os << quoted(p.string<charT, traits>())`.
8685
+
8686
+ [*Note 1*: The `quoted` function is described
8687
+ in  [[quoted.manip]]. — *end note*]
8688
+
8689
+ *Returns:* `os`.
8690
+
8691
+ ``` cpp
8692
+ template<class charT, class traits>
8693
+ friend basic_istream<charT, traits>&
8694
+ operator>>(basic_istream<charT, traits>& is, path& p);
8695
+ ```
8696
+
8697
+ *Effects:* Equivalent to:
8698
+
8699
+ ``` cpp
8700
+ basic_string<charT, traits> tmp;
8701
+ is >> quoted(tmp);
8702
+ p = tmp;
8703
+ ```
8704
+
8705
+ *Returns:* `is`.
8706
+
8707
+ #### Non-member functions <a id="fs.path.nonmember">[[fs.path.nonmember]]</a>
8708
 
8709
  ``` cpp
8710
  void swap(path& lhs, path& rhs) noexcept;
8711
  ```
8712
 
8713
+ *Effects:* Equivalent to `lhs.swap(rhs)`.
8714
 
8715
  ``` cpp
8716
  size_t hash_value (const path& p) noexcept;
8717
  ```
8718
 
8719
  *Returns:* A hash value for the path `p`. If for two paths, `p1 == p2`
8720
  then `hash_value(p1) == hash_value(p2)`.
8721
 
8722
  ``` cpp
8723
+ friend bool operator==(const path& lhs, const path& rhs) noexcept;
8724
  ```
8725
 
8726
+ *Returns:* `lhs.compare(rhs) == 0`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8727
 
8728
  [*Note 1*:
8729
 
8730
  Path equality and path equivalence have different semantics.
8731
 
8732
  - Equality is determined by the `path` non-member `operator==`, which
8733
+ considers the two paths’ lexical representations only.
8734
  \[*Example 1*: `path("foo") == "bar"` is never
8735
  `true`. — *end example*]
8736
  - Equivalence is determined by the `equivalent()` non-member function,
8737
+ which determines if two paths resolve [[fs.class.path]] to the same
8738
+ file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
8739
+ `true` when both paths resolve to the same file. — *end example*]
 
8740
 
8741
  Programmers wishing to determine if two paths are “the same” must decide
8742
  if “the same” means “the same representation” or “resolve to the same
8743
  actual file”, and choose the appropriate function accordingly.
8744
 
8745
  — *end note*]
8746
 
8747
  ``` cpp
8748
+ friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
8749
  ```
8750
 
8751
+ *Returns:* `lhs.compare(rhs) <=> 0`.
8752
 
8753
  ``` cpp
8754
+ friend path operator/ (const path& lhs, const path& rhs);
8755
  ```
8756
 
8757
  *Effects:* Equivalent to: `return path(lhs) /= rhs;`
8758
 
8759
+ ### Class `filesystem_error` <a id="fs.class.filesystem.error">[[fs.class.filesystem.error]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8760
 
8761
  ``` cpp
8762
  namespace std::filesystem {
8763
  class filesystem_error : public system_error {
8764
  public:
 
8774
  };
8775
  }
8776
  ```
8777
 
8778
  The class `filesystem_error` defines the type of objects thrown as
8779
+ exceptions to report file system errors from functions described in
8780
+ subclause  [[filesystems]].
8781
 
8782
+ #### Members <a id="fs.filesystem.error.members">[[fs.filesystem.error.members]]</a>
8783
 
8784
  Constructors are provided that store zero, one, or two paths associated
8785
  with an error.
8786
 
8787
  ``` cpp
8788
  filesystem_error(const string& what_arg, error_code ec);
8789
  ```
8790
 
8791
+ *Ensures:*
 
8792
 
8793
+ - `code() == ec`,
8794
+ - `path1().empty() == true`,
8795
+ - `path2().empty() == true`, and
8796
+ - `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
 
 
 
 
8797
 
8798
  ``` cpp
8799
  filesystem_error(const string& what_arg, const path& p1, error_code ec);
8800
  ```
8801
 
8802
+ *Ensures:*
 
8803
 
8804
+ - `code() == ec`,
8805
+ - `path1()` returns a reference to the stored copy of `p1`,
8806
+ - `path2().empty() == true`, and
8807
+ - `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
 
 
 
 
8808
 
8809
  ``` cpp
8810
  filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
8811
  ```
8812
 
8813
+ *Ensures:*
 
8814
 
8815
+ - `code() == ec`,
8816
+ - `path1()` returns a reference to the stored copy of `p1`,
8817
+ - `path2()` returns a reference to the stored copy of `p2`, and
8818
+ - `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
 
 
 
 
8819
 
8820
  ``` cpp
8821
  const path& path1() const noexcept;
8822
  ```
8823
 
 
8833
 
8834
  ``` cpp
8835
  const char* what() const noexcept override;
8836
  ```
8837
 
8838
+ *Returns:* An NTBS that incorporates the `what_arg` argument supplied to
8839
+ the constructor. The exact format is unspecified. Implementations should
8840
+ include the `system_error::what()` string and the pathnames of `path1`
8841
+ and `path2` in the native format in the returned string.
8842
 
8843
  ### Enumerations <a id="fs.enum">[[fs.enum]]</a>
8844
 
8845
  #### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
8846
 
8847
  This enum specifies constants used to identify the format of the
8848
+ character sequence, with the meanings listed in [[fs.enum.path.format]].
 
8849
 
8850
  [*Note 1*: For POSIX-based systems, native and generic formats are
8851
  equivalent and the character sequence should always be interpreted in
8852
  the same way. — *end note*]
8853
 
8854
+ #### Enum class `file_type` <a id="fs.enum.file.type">[[fs.enum.file.type]]</a>
8855
 
8856
  This enum class specifies constants used to identify file types, with
8857
+ the meanings listed in [[fs.enum.file.type]]. The values of the
8858
+ constants are distinct.
8859
 
8860
  [*Note 1*: The file not being found is not considered an error while
8861
  determining the type of a file. — *end note*]
8862
 
8863
  #### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
8864
 
8865
+ The `enum class` type `copy_options` is a bitmask type [[bitmask.types]]
8866
+ that specifies bitmask constants used to control the semantics of copy
8867
+ operations. The constants are specified in option groups with the
8868
+ meanings listed in [[fs.enum.copy.opts]]. The constant `none` represents
8869
+ the empty bitmask, and is shown in each option group for purposes of
8870
  exposition; implementations shall provide only a single definition.
8871
+ Every other constant in the table represents a distinct bitmask element.
8872
 
8873
+ **Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
8874
 
8875
  | Constant | Meaning |
8876
  | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
8877
  | `none` | (Default) Error; file already exists. |
8878
  | `skip_existing` | Do not overwrite existing file, do not report an error. |
 
8886
  | `create_hard_links` | Make hard links instead of copies of files. |
8887
 
8888
 
8889
  #### Enum class `perms` <a id="fs.enum.perms">[[fs.enum.perms]]</a>
8890
 
8891
+ The `enum class` type `perms` is a bitmask type [[bitmask.types]] that
8892
+ specifies bitmask constants used to identify file permissions, with the
8893
+ meanings listed in [[fs.enum.perms]].
8894
 
8895
+ **Table: Enum class `perms`** <a id="fs.enum.perms">[fs.enum.perms]</a>
8896
 
8897
  | Name | Value (octal) | POSIX macro | Definition or notes |
8898
  | -------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
8899
  | `none` | `0` | | There are no permissions set for the file. |
8900
  | `owner_read` | `0400` | `S_IRUSR` | Read permission, owner |
 
8917
  | `unknown` | `0xFFFF` | | The permissions are not known, such as when a `file_status` object is created without specifying the permissions |
8918
 
8919
 
8920
  #### Enum class `perm_options` <a id="fs.enum.perm.opts">[[fs.enum.perm.opts]]</a>
8921
 
8922
+ The `enum class` type `perm_options` is a bitmask type [[bitmask.types]]
8923
+ that specifies bitmask constants used to control the semantics of
8924
+ permissions operations, with the meanings listed in
8925
+ [[fs.enum.perm.opts]]. The bitmask constants are bitmask elements. In
8926
+ [[fs.enum.perm.opts]] `perm` denotes a value of type `perms` passed to
8927
+ `permissions`.
8928
 
8929
+ **Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
8930
 
8931
  | Name | Meaning |
8932
+ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
8933
  | `replace` | `permissions` shall replace the file's permission bits with `perm` |
8934
+ | `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{OR} of `perm` and the file's current permission bits. |
8935
+ | `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. |
8936
  | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
8937
 
8938
 
8939
  #### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
8940
 
8941
+ The `enum class` type `directory_options` is a bitmask type
8942
+ [[bitmask.types]] that specifies bitmask constants used to identify
8943
+ directory traversal options, with the meanings listed in
8944
+ [[fs.enum.dir.opts]]. The constant `none` represents the empty bitmask;
8945
+ every other constant in the table represents a distinct bitmask element.
8946
 
8947
+ **Table: Enum class `directory_options`** <a id="fs.enum.dir.opts">[fs.enum.dir.opts]</a>
8948
 
8949
  | Name | Meaning |
8950
  | -------------------------- | ------------------------------------------------------------------ |
8951
  | `none` | (Default) Skip directory symlinks, permission denied is an error. |
8952
  | `follow_directory_symlink` | Follow rather than skip directory symlinks. |
8953
  | `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
8954
 
8955
 
8956
+ ### Class `file_status` <a id="fs.class.file.status">[[fs.class.file.status]]</a>
8957
 
8958
  ``` cpp
8959
  namespace std::filesystem {
8960
  class file_status {
8961
  public:
8962
+ // [fs.file.status.cons], constructors and destructor
8963
  file_status() noexcept : file_status(file_type::none) {}
8964
  explicit file_status(file_type ft,
8965
  perms prms = perms::unknown) noexcept;
8966
  file_status(const file_status&) noexcept = default;
8967
  file_status(file_status&&) noexcept = default;
8968
  ~file_status();
8969
 
8970
+ // assignments
8971
  file_status& operator=(const file_status&) noexcept = default;
8972
  file_status& operator=(file_status&&) noexcept = default;
8973
 
8974
+ // [fs.file.status.mods], modifiers
8975
  void type(file_type ft) noexcept;
8976
  void permissions(perms prms) noexcept;
8977
 
8978
+ // [fs.file.status.obs], observers
8979
  file_type type() const noexcept;
8980
  perms permissions() const noexcept;
8981
+
8982
+ friend bool operator==(const file_status& lhs, const file_status& rhs) noexcept
8983
+ { return lhs.type() == rhs.type() && lhs.permissions() == rhs.permissions(); }
8984
  };
8985
  }
8986
  ```
8987
 
8988
+ #### Constructors <a id="fs.file.status.cons">[[fs.file.status.cons]]</a>
8989
 
8990
  ``` cpp
8991
  explicit file_status(file_type ft, perms prms = perms::unknown) noexcept;
8992
  ```
8993
 
8994
+ *Ensures:* `type() == ft` and `permissions() == prms`.
8995
 
8996
+ #### Observers <a id="fs.file.status.obs">[[fs.file.status.obs]]</a>
8997
 
8998
  ``` cpp
8999
  file_type type() const noexcept;
9000
  ```
9001
 
 
9009
 
9010
  *Returns:* The value of `permissions()` specified by the postconditions
9011
  of the most recent call to a constructor, `operator=`, or
9012
  `permissions(perms)` function.
9013
 
9014
+ #### Modifiers <a id="fs.file.status.mods">[[fs.file.status.mods]]</a>
9015
 
9016
  ``` cpp
9017
  void type(file_type ft) noexcept;
9018
  ```
9019
 
9020
+ *Ensures:* `type() == ft`.
9021
 
9022
  ``` cpp
9023
  void permissions(perms prms) noexcept;
9024
  ```
9025
 
9026
+ *Ensures:* `permissions() == prms`.
9027
 
9028
+ ### Class `directory_entry` <a id="fs.class.directory.entry">[[fs.class.directory.entry]]</a>
9029
 
9030
  ``` cpp
9031
  namespace std::filesystem {
9032
  class directory_entry {
9033
  public:
9034
  // [fs.dir.entry.cons], constructors and destructor
9035
  directory_entry() noexcept = default;
9036
  directory_entry(const directory_entry&) = default;
9037
  directory_entry(directory_entry&&) noexcept = default;
9038
+ explicit directory_entry(const filesystem::path& p);
9039
+ directory_entry(const filesystem::path& p, error_code& ec);
9040
  ~directory_entry();
9041
 
9042
+ // assignments
9043
  directory_entry& operator=(const directory_entry&) = default;
9044
  directory_entry& operator=(directory_entry&&) noexcept = default;
9045
 
9046
  // [fs.dir.entry.mods], modifiers
9047
+ void assign(const filesystem::path& p);
9048
+ void assign(const filesystem::path& p, error_code& ec);
9049
+ void replace_filename(const filesystem::path& p);
9050
+ void replace_filename(const filesystem::path& p, error_code& ec);
9051
  void refresh();
9052
  void refresh(error_code& ec) noexcept;
9053
 
9054
  // [fs.dir.entry.obs], observers
9055
+ const filesystem::path& path() const noexcept;
9056
+ operator const filesystem::path&() const noexcept;
9057
  bool exists() const;
9058
  bool exists(error_code& ec) const noexcept;
9059
  bool is_block_file() const;
9060
  bool is_block_file(error_code& ec) const noexcept;
9061
  bool is_character_file() const;
 
9081
  file_status status() const;
9082
  file_status status(error_code& ec) const noexcept;
9083
  file_status symlink_status() const;
9084
  file_status symlink_status(error_code& ec) const noexcept;
9085
 
 
9086
  bool operator==(const directory_entry& rhs) const noexcept;
9087
+ strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
 
 
 
9088
 
9089
  private:
9090
+ filesystem::path pathobject; // exposition only
9091
  friend class directory_iterator; // exposition only
9092
  };
9093
  }
9094
  ```
9095
 
9096
  A `directory_entry` object stores a `path` object and may store
9097
  additional objects for file attributes such as hard link count, status,
9098
  symlink status, file size, and last write time.
9099
 
9100
+ Implementations should store such additional file attributes during
9101
+ directory iteration if their values are available and storing the values
9102
+ would allow the implementation to eliminate file system accesses by
9103
+ `directory_entry` observer functions [[fs.op.funcs]]. Such stored file
9104
+ attribute values are said to be *cached*.
9105
 
9106
+ [*Note 1*: For purposes of exposition, class `directory_iterator`
9107
+ [[fs.class.directory.iterator]] is shown above as a friend of class
9108
  `directory_entry`. Friendship allows the `directory_iterator`
9109
  implementation to cache already available attribute values directly into
9110
  a `directory_entry` object without the cost of an unneeded call to
9111
  `refresh()`. — *end note*]
9112
 
 
9138
  `std::filesystem::last_write_time` function. The code is portable to any
9139
  implementation, regardless of whether or not it employs caching.
9140
 
9141
  — *end example*]
9142
 
9143
+ #### Constructors <a id="fs.dir.entry.cons">[[fs.dir.entry.cons]]</a>
9144
 
9145
  ``` cpp
9146
+ explicit directory_entry(const filesystem::path& p);
9147
+ directory_entry(const filesystem::path& p, error_code& ec);
9148
  ```
9149
 
9150
+ *Effects:* Calls `refresh()` or `refresh(ec)`, respectively.
 
9151
 
9152
+ *Ensures:* `path() == p` if no error occurs, otherwise
9153
+ `path() == filesystem::path()`.
9154
 
9155
  *Throws:* As specified in  [[fs.err.report]].
9156
 
9157
+ #### Modifiers <a id="fs.dir.entry.mods">[[fs.dir.entry.mods]]</a>
9158
 
9159
  ``` cpp
9160
+ void assign(const filesystem::path& p);
9161
+ void assign(const filesystem::path& p, error_code& ec);
9162
  ```
9163
 
9164
  *Effects:* Equivalent to `pathobject = p`, then `refresh()` or
9165
  `refresh(ec)`, respectively. If an error occurs, the values of any
9166
  cached attributes are unspecified.
9167
 
9168
  *Throws:* As specified in  [[fs.err.report]].
9169
 
9170
  ``` cpp
9171
+ void replace_filename(const filesystem::path& p);
9172
+ void replace_filename(const filesystem::path& p, error_code& ec);
9173
  ```
9174
 
9175
  *Effects:* Equivalent to `pathobject.replace_filename(p)`, then
9176
  `refresh()` or `refresh(ec)`, respectively. If an error occurs, the
9177
  values of any cached attributes are unspecified.
 
9183
  void refresh(error_code& ec) noexcept;
9184
  ```
9185
 
9186
  *Effects:* Stores the current values of any cached attributes of the
9187
  file `p` resolves to. If an error occurs, an error is
9188
+ reported [[fs.err.report]] and the values of any cached attributes are
9189
+ unspecified.
9190
 
9191
  *Throws:* As specified in  [[fs.err.report]].
9192
 
9193
+ [*Note 1*: Implementations of `directory_iterator`
9194
+ [[fs.class.directory.iterator]] are prohibited from directly or
9195
+ indirectly calling the `refresh` function since it must access the
9196
+ external file system, and the objective of caching is to avoid
9197
+ unnecessary file system accesses. — *end note*]
9198
 
9199
+ #### Observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
9200
 
9201
  Unqualified function names in the *Returns:* elements of the
9202
  `directory_entry` observers described below refer to members of the
9203
  `std::filesystem` namespace.
9204
 
9205
  ``` cpp
9206
+ const filesystem::path& path() const noexcept;
9207
+ operator const filesystem::path&() const noexcept;
9208
  ```
9209
 
9210
  *Returns:* `pathobject`.
9211
 
9212
  ``` cpp
9213
  bool exists() const;
9214
  bool exists(error_code& ec) const noexcept;
9215
  ```
9216
 
9217
+ *Returns:* `exists(this->status())` or `exists(this->status(ec))`,
9218
  respectively.
9219
 
9220
  *Throws:* As specified in  [[fs.err.report]].
9221
 
9222
  ``` cpp
9223
  bool is_block_file() const;
9224
  bool is_block_file(error_code& ec) const noexcept;
9225
  ```
9226
 
9227
  *Returns:* `is_block_file(this->status())` or
9228
+ `is_block_file(this->status(ec))`, respectively.
9229
 
9230
  *Throws:* As specified in  [[fs.err.report]].
9231
 
9232
  ``` cpp
9233
  bool is_character_file() const;
9234
  bool is_character_file(error_code& ec) const noexcept;
9235
  ```
9236
 
9237
  *Returns:* `is_character_file(this->status())` or
9238
+ `is_character_file(this->status(ec))`, respectively.
9239
 
9240
  *Throws:* As specified in  [[fs.err.report]].
9241
 
9242
  ``` cpp
9243
  bool is_directory() const;
9244
  bool is_directory(error_code& ec) const noexcept;
9245
  ```
9246
 
9247
  *Returns:* `is_directory(this->status())` or
9248
+ `is_directory(this->status(ec))`, respectively.
9249
 
9250
  *Throws:* As specified in  [[fs.err.report]].
9251
 
9252
  ``` cpp
9253
  bool is_fifo() const;
9254
  bool is_fifo(error_code& ec) const noexcept;
9255
  ```
9256
 
9257
+ *Returns:* `is_fifo(this->status())` or `is_fifo(this->status(ec))`,
9258
  respectively.
9259
 
9260
  *Throws:* As specified in  [[fs.err.report]].
9261
 
9262
  ``` cpp
9263
  bool is_other() const;
9264
  bool is_other(error_code& ec) const noexcept;
9265
  ```
9266
 
9267
+ *Returns:* `is_other(this->status())` or `is_other(this->status(ec))`,
9268
  respectively.
9269
 
9270
  *Throws:* As specified in  [[fs.err.report]].
9271
 
9272
  ``` cpp
9273
  bool is_regular_file() const;
9274
  bool is_regular_file(error_code& ec) const noexcept;
9275
  ```
9276
 
9277
  *Returns:* `is_regular_file(this->status())` or
9278
+ `is_regular_file(this->status(ec))`, respectively.
9279
 
9280
  *Throws:* As specified in  [[fs.err.report]].
9281
 
9282
  ``` cpp
9283
  bool is_socket() const;
9284
  bool is_socket(error_code& ec) const noexcept;
9285
  ```
9286
 
9287
+ *Returns:* `is_socket(this->status())` or `is_socket(this->status(ec))`,
9288
+ respectively.
9289
 
9290
  *Throws:* As specified in  [[fs.err.report]].
9291
 
9292
  ``` cpp
9293
  bool is_symlink() const;
9294
  bool is_symlink(error_code& ec) const noexcept;
9295
  ```
9296
 
9297
  *Returns:* `is_symlink(this->symlink_status())` or
9298
+ `is_symlink(this->symlink_status(ec))`, respectively.
9299
 
9300
  *Throws:* As specified in  [[fs.err.report]].
9301
 
9302
  ``` cpp
9303
  uintmax_t file_size() const;
 
9356
  ```
9357
 
9358
  *Returns:* `pathobject == rhs.pathobject`.
9359
 
9360
  ``` cpp
9361
+ strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
9362
  ```
9363
 
9364
+ *Returns:* `pathobject <=> rhs.pathobject`.
9365
 
9366
+ ### Class `directory_iterator` <a id="fs.class.directory.iterator">[[fs.class.directory.iterator]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9367
 
9368
  An object of type `directory_iterator` provides an iterator for a
9369
  sequence of `directory_entry` elements representing the path and any
9370
+ cached attribute values [[fs.class.directory.entry]] for each file in a
9371
+ directory or in an *implementation-defined* directory-like file type.
9372
 
9373
  [*Note 1*: For iteration into sub-directories, see class
9374
+ `recursive_directory_iterator` [[fs.class.rec.dir.itr]]. — *end note*]
 
9375
 
9376
  ``` cpp
9377
  namespace std::filesystem {
9378
  class directory_iterator {
9379
  public:
 
9385
 
9386
  // [fs.dir.itr.members], member functions
9387
  directory_iterator() noexcept;
9388
  explicit directory_iterator(const path& p);
9389
  directory_iterator(const path& p, directory_options options);
9390
+ directory_iterator(const path& p, error_code& ec);
9391
  directory_iterator(const path& p, directory_options options,
9392
+ error_code& ec);
9393
  directory_iterator(const directory_iterator& rhs);
9394
  directory_iterator(directory_iterator&& rhs) noexcept;
9395
  ~directory_iterator();
9396
 
9397
  directory_iterator& operator=(const directory_iterator& rhs);
9398
  directory_iterator& operator=(directory_iterator&& rhs) noexcept;
9399
 
9400
  const directory_entry& operator*() const;
9401
  const directory_entry* operator->() const;
9402
  directory_iterator& operator++();
9403
+ directory_iterator& increment(error_code& ec);
9404
 
9405
  // other members as required by [input.iterators], input iterators
9406
  };
9407
  }
9408
  ```
9409
 
9410
+ `directory_iterator` meets the *Cpp17InputIterator* requirements
9411
+ [[input.iterators]].
9412
 
9413
  If an iterator of type `directory_iterator` reports an error or is
9414
  advanced past the last directory element, that iterator shall become
9415
  equal to the end iterator value. The `directory_iterator` default
9416
  constructor shall create an iterator equal to the end iterator value,
 
9426
  to a `path` object composed of the directory argument from which the
9427
  iterator was constructed with filename of the directory entry appended
9428
  as if by `operator/=`.
9429
 
9430
  Directory iteration shall not yield directory entries for the current
9431
+ (dot) and parent (dot-dot) directories.
9432
 
9433
  The order of directory entries obtained by dereferencing successive
9434
  increments of a `directory_iterator` is unspecified.
9435
 
9436
  Constructors and non-const `directory_iterator` member functions store
9437
+ the values of any cached attributes [[fs.class.directory.entry]] in the
9438
+ `directory_entry` element returned by `operator*()`.
9439
  `directory_iterator` member functions shall not directly or indirectly
9440
  call any `directory_entry` `refresh` function.
9441
 
9442
  [*Note 2*: The exact mechanism for storing cached attribute values is
9443
  not exposed to users. For exposition, class `directory_iterator` is
9444
+ shown in [[fs.class.directory.entry]] as a friend of class
9445
  `directory_entry`. — *end note*]
9446
 
9447
  [*Note 3*: Programs performing directory iteration may wish to test if
9448
  the path obtained by dereferencing a directory iterator actually exists.
9449
  It could be a symbolic link to a non-existent file. Programs recursively
 
9454
  construction of a `directory_iterator` for the directory, it is
9455
  unspecified whether or not subsequently incrementing the iterator will
9456
  ever result in an iterator referencing the removed or added directory
9457
  entry. See POSIX `readdir_r`. — *end note*]
9458
 
9459
+ #### Members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
9460
 
9461
  ``` cpp
9462
  directory_iterator() noexcept;
9463
  ```
9464
 
9465
  *Effects:* Constructs the end iterator.
9466
 
9467
  ``` cpp
9468
  explicit directory_iterator(const path& p);
9469
  directory_iterator(const path& p, directory_options options);
9470
+ directory_iterator(const path& p, error_code& ec);
9471
+ directory_iterator(const path& p, directory_options options, error_code& ec);
9472
  ```
9473
 
9474
  *Effects:* For the directory that `p` resolves to, constructs an
9475
  iterator for the first element in a sequence of `directory_entry`
9476
  elements representing the files in the directory, if any; otherwise the
 
9493
  ``` cpp
9494
  directory_iterator(const directory_iterator& rhs);
9495
  directory_iterator(directory_iterator&& rhs) noexcept;
9496
  ```
9497
 
9498
+ *Ensures:* `*this` has the original value of `rhs`.
 
 
9499
 
9500
  ``` cpp
9501
  directory_iterator& operator=(const directory_iterator& rhs);
9502
  directory_iterator& operator=(directory_iterator&& rhs) noexcept;
9503
  ```
9504
 
9505
  *Effects:* If `*this` and `rhs` are the same object, the member has no
9506
  effect.
9507
 
9508
+ *Ensures:* `*this` has the original value of `rhs`.
9509
 
9510
  *Returns:* `*this`.
9511
 
9512
  ``` cpp
9513
  directory_iterator& operator++();
9514
+ directory_iterator& increment(error_code& ec);
9515
  ```
9516
 
9517
  *Effects:* As specified for the prefix increment operation of Input
9518
+ iterators [[input.iterators]].
9519
 
9520
  *Returns:* `*this`.
9521
 
9522
  *Throws:* As specified in  [[fs.err.report]].
9523
 
9524
+ #### Non-member functions <a id="fs.dir.itr.nonmembers">[[fs.dir.itr.nonmembers]]</a>
9525
 
9526
  These functions enable range access for `directory_iterator`.
9527
 
9528
  ``` cpp
9529
  directory_iterator begin(directory_iterator iter) noexcept;
 
9557
  // [fs.rec.dir.itr.members], constructors and destructor
9558
  recursive_directory_iterator() noexcept;
9559
  explicit recursive_directory_iterator(const path& p);
9560
  recursive_directory_iterator(const path& p, directory_options options);
9561
  recursive_directory_iterator(const path& p, directory_options options,
9562
+ error_code& ec);
9563
+ recursive_directory_iterator(const path& p, error_code& ec);
9564
  recursive_directory_iterator(const recursive_directory_iterator& rhs);
9565
  recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
9566
  ~recursive_directory_iterator();
9567
 
9568
  // [fs.rec.dir.itr.members], observers
 
9578
  operator=(const recursive_directory_iterator& rhs);
9579
  recursive_directory_iterator&
9580
  operator=(recursive_directory_iterator&& rhs) noexcept;
9581
 
9582
  recursive_directory_iterator& operator++();
9583
+ recursive_directory_iterator& increment(error_code& ec);
9584
 
9585
  void pop();
9586
  void pop(error_code& ec);
9587
  void disable_recursion_pending();
9588
 
 
9599
  `directory_iterator` unless otherwise specified.
9600
 
9601
  [*Note 1*: If the directory structure being iterated over contains
9602
  cycles then the end iterator may be unreachable. — *end note*]
9603
 
9604
+ #### Members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
9605
 
9606
  ``` cpp
9607
  recursive_directory_iterator() noexcept;
9608
  ```
9609
 
9610
  *Effects:* Constructs the end iterator.
9611
 
9612
  ``` cpp
9613
  explicit recursive_directory_iterator(const path& p);
9614
  recursive_directory_iterator(const path& p, directory_options options);
9615
+ recursive_directory_iterator(const path& p, directory_options options, error_code& ec);
9616
+ recursive_directory_iterator(const path& p, error_code& ec);
9617
  ```
9618
 
9619
+ *Effects:* Constructs an iterator representing the first entry in the
9620
+ directory to which `p` resolves, if any; otherwise, the end iterator.
9621
+ However, if
9622
 
9623
  ``` cpp
9624
  (options & directory_options::skip_permission_denied) != directory_options::none
9625
  ```
9626
 
9627
  and construction encounters an error indicating that permission to
9628
  access `p` is denied, constructs the end iterator and does not report an
9629
  error.
9630
 
9631
+ *Ensures:* `options() == options` for the signatures with a
9632
  `directory_options` argument, otherwise
9633
  `options() == directory_options::none`.
9634
 
9635
  *Throws:* As specified in  [[fs.err.report]].
9636
 
 
9638
  `recursive_directory_iterator(".")` rather than
9639
  `recursive_directory_iterator("")`. — *end note*]
9640
 
9641
  [*Note 2*: By default, `recursive_directory_iterator` does not follow
9642
  directory symlinks. To follow directory symlinks, specify `options` as
9643
+ `directory_options::follow_directory_symlink`. — *end note*]
9644
 
9645
  ``` cpp
9646
  recursive_directory_iterator(const recursive_directory_iterator& rhs);
9647
  ```
9648
 
9649
+ *Ensures:*
 
 
9650
 
9651
  - `options() == rhs.options()`
9652
  - `depth() == rhs.depth()`
9653
  - `recursion_pending() == rhs.recursion_pending()`
9654
 
9655
  ``` cpp
9656
  recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
9657
  ```
9658
 
9659
+ *Ensures:* `options()`, `depth()`, and `recursion_pending()` have the
9660
+ values that `rhs.options()`, `rhs.depth()`, and
 
 
9661
  `rhs.recursion_pending()`, respectively, had before the function call.
9662
 
9663
  ``` cpp
9664
  recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
9665
  ```
9666
 
9667
  *Effects:* If `*this` and `rhs` are the same object, the member has no
9668
  effect.
9669
 
9670
+ *Ensures:*
9671
 
9672
  - `options() == rhs.options()`
9673
  - `depth() == rhs.depth()`
9674
  - `recursion_pending() == rhs.recursion_pending()`
9675
 
 
9680
  ```
9681
 
9682
  *Effects:* If `*this` and `rhs` are the same object, the member has no
9683
  effect.
9684
 
9685
+ *Ensures:* `options()`, `depth()`, and `recursion_pending()` have the
9686
+ values that `rhs.options()`, `rhs.depth()`, and
9687
  `rhs.recursion_pending()`, respectively, had before the function call.
9688
 
9689
  *Returns:* `*this`.
9690
 
9691
  ``` cpp
 
9718
 
9719
  *Throws:* Nothing.
9720
 
9721
  ``` cpp
9722
  recursive_directory_iterator& operator++();
9723
+ recursive_directory_iterator& increment(error_code& ec);
9724
  ```
9725
 
9726
  *Effects:* As specified for the prefix increment operation of Input
9727
+ iterators [[input.iterators]], except that:
9728
 
9729
  - If there are no more entries at the current depth, then if
9730
  `depth() != 0` iteration over the parent directory resumes; otherwise
9731
  `*this = recursive_directory_iterator()`.
9732
  - Otherwise if
 
9760
  directory currently being iterated over, and continue iteration over the
9761
  parent directory.
9762
 
9763
  *Throws:* As specified in  [[fs.err.report]].
9764
 
9765
+ *Remarks:* Any copies of the previous value of `*this` are no longer
9766
+ required to be dereferenceable nor to be in the domain of `==`.
9767
+
9768
  ``` cpp
9769
  void disable_recursion_pending();
9770
  ```
9771
 
9772
+ *Ensures:* `recursion_pending() == false`.
9773
 
9774
  [*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
9775
  recursion into a directory. — *end note*]
9776
 
9777
+ #### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
9778
 
9779
  These functions enable use of `recursive_directory_iterator` with
9780
  range-based for statements.
9781
 
9782
  ``` cpp
 
9795
 
9796
  Filesystem operation functions query or modify files, including
9797
  directories, in external storage.
9798
 
9799
  [*Note 1*: Because hardware failures, network failures, file system
9800
+ races [[fs.race.behavior]], and many other kinds of errors occur
9801
  frequently in file system operations, users should be aware that any
9802
  filesystem operation function, no matter how apparently innocuous, may
9803
  encounter an error; see  [[fs.err.report]]. — *end note*]
9804
 
9805
  #### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
 
9808
  path absolute(const path& p);
9809
  path absolute(const path& p, error_code& ec);
9810
  ```
9811
 
9812
  *Effects:* Composes an absolute path referencing the same file system
9813
+ location as `p` according to the operating system [[fs.conform.os]].
9814
 
9815
  *Returns:* The composed path. The signature with argument `ec` returns
9816
  `path()` if an error occurs.
9817
 
9818
  [*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
 
9820
 
9821
  *Throws:* As specified in  [[fs.err.report]].
9822
 
9823
  [*Note 2*: To resolve symlinks, or perform other sanitization which
9824
  might require queries to secondary storage, such as hard disks, consider
9825
+ `canonical` [[fs.op.canonical]]. — *end note*]
9826
 
9827
  [*Note 3*: Implementations are strongly encouraged to not query
9828
  secondary storage, and not consider `!exists(p)` an
9829
  error. — *end note*]
9830
 
 
9834
  `GetFullPathNameW`. — *end example*]
9835
 
9836
  #### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
9837
 
9838
  ``` cpp
9839
+ path canonical(const path& p);
9840
  path canonical(const path& p, error_code& ec);
 
9841
  ```
9842
 
9843
+ *Effects:* Converts `p` to an absolute path that has no symbolic link,
9844
+ dot, or dot-dot elements in its pathname in the generic format.
 
9845
 
9846
  *Returns:* A path that refers to the same file system object as
9847
+ `absolute(p)`. The signature with argument `ec` returns `path()` if an
 
9848
  error occurs.
9849
 
9850
  *Throws:* As specified in  [[fs.err.report]].
9851
 
9852
  *Remarks:* `!exists(p)` is an error.
 
9858
  ```
9859
 
9860
  *Effects:* Equivalent to `copy(from, to, copy_options::none)`.
9861
 
9862
  ``` cpp
9863
+ void copy(const path& from, const path& to, error_code& ec);
9864
  ```
9865
 
9866
  *Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
9867
 
9868
  ``` cpp
9869
  void copy(const path& from, const path& to, copy_options options);
9870
  void copy(const path& from, const path& to, copy_options options,
9871
+ error_code& ec);
9872
  ```
9873
 
9874
+ *Preconditions:* At most one element from each option
9875
+ group [[fs.enum.copy.opts]] is set in `options`.
9876
 
9877
  *Effects:* Before the first use of `f` and `t`:
9878
 
9879
  - If
9880
  ``` cpp
 
9895
  `auto t = status(to)`.
9896
 
9897
  Effects are then as follows:
9898
 
9899
  - If `f.type()` or `t.type()` is an implementation-defined file
9900
+ type [[fs.enum.file.type]], then the effects are
9901
  *implementation-defined*.
9902
  - Otherwise, an error is reported as specified in  [[fs.err.report]] if:
9903
+ - `exists(f)` is `false`, or
9904
+ - `equivalent(from, to)` is `true`, or
9905
+ - `is_other(f) || is_other(t)` is `true`, or
9906
+ - `is_directory(f) && is_regular_file(t)` is `true`.
9907
  - Otherwise, if `is_symlink(f)`, then:
9908
  - If `(options & copy_options::skip_symlinks) != copy_options::none`
9909
  then return.
9910
  - Otherwise if
9911
  ``` cpp
 
9925
  `(options & copy_options::create_hard_links) != copy_options::none`,
9926
  then create a hard link to the source file.
9927
  - Otherwise, if `is_directory(t)`, then
9928
  `copy_file(from, to/from.filename(), options)`.
9929
  - Otherwise, `copy_file(from, to, options)`.
9930
+ - Otherwise, if
9931
+ ``` cpp
9932
+ is_directory(f) &&
9933
+ (options & copy_options::create_symlinks) != copy_options::none
9934
+ ```
9935
+
9936
+ then report an error with an `error_code` argument equal to
9937
+ `make_error_code(errc::is_a_directory)`.
9938
  - Otherwise, if
9939
  ``` cpp
9940
  is_directory(f) &&
9941
  ((options & copy_options::recursive) != copy_options::none ||
9942
  options == copy_options::none)
9943
  ```
9944
 
9945
  then:
9946
+ - If `exists(t)` is `false`, then `create_directory(to, from)`.
9947
  - Then, iterate over the files in `from`, as if by
9948
  ``` cpp
9949
  for (const directory_entry& x : directory_iterator(from))
9950
+ copy(x.path(), to/x.path().filename(),
9951
+ options | copy_options::in-recursive-copy);
9952
  ```
9953
+
9954
+ where *`in-recursive-copy`* is a bitmask element of `copy_options`
9955
+ that is not one of the elements in  [[fs.enum.copy.opts]].
9956
  - Otherwise, for the signature with argument `ec`, `ec.clear()`.
9957
  - Otherwise, no effects.
9958
 
9959
  *Throws:* As specified in  [[fs.err.report]].
9960
 
 
10003
  file3
10004
  ```
10005
 
10006
  — *end example*]
10007
 
10008
+ #### Copy file <a id="fs.op.copy.file">[[fs.op.copy.file]]</a>
10009
 
10010
  ``` cpp
10011
  bool copy_file(const path& from, const path& to);
10012
+ bool copy_file(const path& from, const path& to, error_code& ec);
10013
  ```
10014
 
10015
  *Returns:* `copy_file(from, to, copy_options::none)` or
10016
  `copy_file(from, to, copy_options::none, ec)`, respectively.
10017
 
10018
  *Throws:* As specified in  [[fs.err.report]].
10019
 
10020
  ``` cpp
10021
  bool copy_file(const path& from, const path& to, copy_options options);
10022
  bool copy_file(const path& from, const path& to, copy_options options,
10023
+ error_code& ec);
10024
  ```
10025
 
10026
+ *Preconditions:* At most one element from each option
10027
+ group [[fs.enum.copy.opts]] is set in `options`.
10028
 
10029
  *Effects:* As follows:
10030
 
10031
+ - Report an error as specified in  [[fs.err.report]] if:
10032
+ - `is_regular_file(from)` is `false`, or
10033
+ - `exists(to)` is `true` and `is_regular_file(to)` is `false`, or
10034
+ - `exists(to)` is `true` and `equivalent(from, to)` is `true`, or
10035
+ - `exists(to)` is `true` and
 
10036
  ``` cpp
10037
  (options & (copy_options::skip_existing |
10038
  copy_options::overwrite_existing |
10039
  copy_options::update_existing)) == copy_options::none
10040
  ```
10041
  - Otherwise, copy the contents and attributes of the file `from`
10042
  resolves to, to the file `to` resolves to, if:
10043
+ - `exists(to)` is `false`, or
10044
  - `(options & copy_options::overwrite_existing) != copy_options::none`,
10045
  or
10046
  - `(options & copy_options::update_existing) `` `` != copy_options::none`
10047
  and `from` is more recent than `to`, determined as if by use of the
10048
+ `last_write_time` function [[fs.op.last.write.time]].
10049
  - Otherwise, no effects.
10050
 
10051
  *Returns:* `true` if the `from` file was copied, otherwise `false`. The
10052
  signature with argument `ec` returns `false` if an error occurs.
10053
 
10054
  *Throws:* As specified in  [[fs.err.report]].
10055
 
10056
  *Complexity:* At most one direct or indirect invocation of `status(to)`.
10057
 
10058
+ #### Copy symlink <a id="fs.op.copy.symlink">[[fs.op.copy.symlink]]</a>
10059
 
10060
  ``` cpp
10061
  void copy_symlink(const path& existing_symlink, const path& new_symlink);
10062
  void copy_symlink(const path& existing_symlink, const path& new_symlink,
10063
  error_code& ec) noexcept;
 
10069
  respectively, where in each case *`function`* is `create_symlink` or
10070
  `create_directory_symlink` as appropriate.
10071
 
10072
  *Throws:* As specified in  [[fs.err.report]].
10073
 
10074
+ #### Create directories <a id="fs.op.create.directories">[[fs.op.create.directories]]</a>
10075
 
10076
  ``` cpp
10077
  bool create_directories(const path& p);
10078
+ bool create_directories(const path& p, error_code& ec);
10079
  ```
10080
 
10081
+ *Effects:* Calls `create_directory()` for each element of `p` that does
 
 
 
 
 
 
 
 
 
 
10082
  not exist.
10083
 
10084
+ *Returns:* `true` if a new directory was created for the directory `p`
10085
+ resolves to, otherwise `false`.
10086
+
10087
+ *Throws:* As specified in  [[fs.err.report]].
10088
+
10089
+ *Complexity:* 𝑂(n) where *n* is the number of elements of `p`.
10090
+
10091
+ #### Create directory <a id="fs.op.create.directory">[[fs.op.create.directory]]</a>
10092
 
10093
  ``` cpp
10094
  bool create_directory(const path& p);
10095
  bool create_directory(const path& p, error_code& ec) noexcept;
10096
  ```
10097
 
10098
+ *Effects:* Creates the directory `p` resolves to, as if by POSIX `mkdir`
10099
+ with a second argument of `static_cast<int>(perms::all)`. If `mkdir`
10100
+ fails because `p` resolves to an existing directory, no error is
10101
+ reported. Otherwise on failure an error is reported.
10102
 
10103
+ *Returns:* `true` if a new directory was created, otherwise `false`.
 
 
 
10104
 
10105
  *Throws:* As specified in  [[fs.err.report]].
10106
 
10107
  ``` cpp
10108
  bool create_directory(const path& p, const path& existing_p);
10109
  bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
10110
  ```
10111
 
10112
+ *Effects:* Creates the directory `p` resolves to, with attributes copied
10113
+ from directory `existing_p`. The set of attributes copied is operating
10114
+ system dependent. If `mkdir` fails because `p` resolves to an existing
10115
+ directory, no error is reported. Otherwise on failure an error is
10116
+ reported.
10117
 
10118
  [*Note 1*: For POSIX-based operating systems, the attributes are those
10119
  copied by native API `stat(existing_p.c_str(), &attributes_stat)`
10120
  followed by `mkdir(p.c_str(), attributes_stat.st_mode)`. For
10121
  Windows-based operating systems, the attributes are those copied by
10122
  native API
10123
  `CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0)`. — *end note*]
10124
 
10125
+ *Returns:* `true` if a new directory was created with attributes copied
10126
+ from directory `existing_p`, otherwise `false`.
 
 
10127
 
10128
  *Throws:* As specified in  [[fs.err.report]].
10129
 
10130
+ #### Create directory symlink <a id="fs.op.create.dir.symlk">[[fs.op.create.dir.symlk]]</a>
10131
 
10132
  ``` cpp
10133
  void create_directory_symlink(const path& to, const path& new_symlink);
10134
  void create_directory_symlink(const path& to, const path& new_symlink,
10135
  error_code& ec) noexcept;
10136
  ```
10137
 
10138
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
10139
 
10140
+ *Ensures:* `new_symlink` resolves to a symbolic link file that contains
10141
+ an unspecified representation of `to`.
10142
 
10143
  *Throws:* As specified in  [[fs.err.report]].
10144
 
10145
  [*Note 1*: Some operating systems require symlink creation to identify
10146
  that the link is to a directory. Portable code should use
 
10150
  [*Note 2*: Some operating systems do not support symbolic links at all
10151
  or support them only for regular files. Some file systems (such as the
10152
  FAT file system) do not support symbolic links regardless of the
10153
  operating system. — *end note*]
10154
 
10155
+ #### Create hard link <a id="fs.op.create.hard.lk">[[fs.op.create.hard.lk]]</a>
10156
 
10157
  ``` cpp
10158
  void create_hard_link(const path& to, const path& new_hard_link);
10159
  void create_hard_link(const path& to, const path& new_hard_link,
10160
  error_code& ec) noexcept;
10161
  ```
10162
 
10163
  *Effects:* Establishes the postcondition, as if by POSIX `link()`.
10164
 
10165
+ *Ensures:*
10166
 
10167
  - `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
10168
  - The contents of the file or directory `to` resolves to are unchanged.
10169
 
10170
  *Throws:* As specified in  [[fs.err.report]].
 
10173
  support them only for regular files. Some file systems (such as the FAT
10174
  file system) do not support hard links regardless of the operating
10175
  system. Some file systems limit the number of links per
10176
  file. — *end note*]
10177
 
10178
+ #### Create symlink <a id="fs.op.create.symlink">[[fs.op.create.symlink]]</a>
10179
 
10180
  ``` cpp
10181
  void create_symlink(const path& to, const path& new_symlink);
10182
  void create_symlink(const path& to, const path& new_symlink,
10183
  error_code& ec) noexcept;
10184
  ```
10185
 
10186
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
10187
 
10188
+ *Ensures:* `new_symlink` resolves to a symbolic link file that contains
10189
+ an unspecified representation of `to`.
10190
 
10191
  *Throws:* As specified in  [[fs.err.report]].
10192
 
10193
  [*Note 1*: Some operating systems do not support symbolic links at all
10194
  or support them only for regular files. Some file systems (such as the
10195
  FAT file system) do not support symbolic links regardless of the
10196
  operating system. — *end note*]
10197
 
10198
+ #### Current path <a id="fs.op.current.path">[[fs.op.current.path]]</a>
10199
 
10200
  ``` cpp
10201
  path current_path();
10202
  path current_path(error_code& ec);
10203
  ```
 
10215
  [*Note 1*: The `current_path()` name was chosen to emphasize that the
10216
  returned value is a path, not just a single directory
10217
  name. — *end note*]
10218
 
10219
  [*Note 2*: The current path as returned by many operating systems is a
10220
+ dangerous global variable. It may be changed unexpectedly by third-party
10221
+ or system library functions, or by another thread. — *end note*]
 
10222
 
10223
  ``` cpp
10224
  void current_path(const path& p);
10225
  void current_path(const path& p, error_code& ec) noexcept;
10226
  ```
10227
 
10228
  *Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
10229
 
10230
+ *Ensures:* `equivalent(p, current_path())`.
10231
 
10232
  *Throws:* As specified in  [[fs.err.report]].
10233
 
10234
  [*Note 3*: The current path for many operating systems is a dangerous
10235
  global state. It may be changed unexpectedly by a third-party or system
 
10240
  ``` cpp
10241
  bool equivalent(const path& p1, const path& p2);
10242
  bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
10243
  ```
10244
 
10245
+ *Returns:* `true`, if `p1` and `p2` resolve to the same file system
10246
+ entity, otherwise `false`. The signature with argument `ec` returns
10247
+ `false` if an error occurs.
 
 
 
 
 
 
 
10248
 
10249
  Two paths are considered to resolve to the same file system entity if
10250
  two candidate entities reside on the same device at the same location.
10251
+
10252
+ [*Note 1*: On POSIX platforms, this is determined as if by the values
10253
+ of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
10254
+ having equal `st_dev` values and equal `st_ino` values. — *end note*]
10255
+
10256
+ *Remarks:* `!exists(p1) || !exists(p2)` is an error.
10257
 
10258
  *Throws:* As specified in  [[fs.err.report]].
10259
 
10260
  #### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
10261
 
 
10278
 
10279
  *Returns:* `exists(s)`.
10280
 
10281
  *Throws:* As specified in  [[fs.err.report]].
10282
 
10283
+ #### File size <a id="fs.op.file.size">[[fs.op.file.size]]</a>
10284
 
10285
  ``` cpp
10286
  uintmax_t file_size(const path& p);
10287
  uintmax_t file_size(const path& p, error_code& ec) noexcept;
10288
  ```
10289
 
10290
+ *Effects:* If `exists(p)` is `false`, an error is
10291
+ reported [[fs.err.report]].
10292
+
10293
  *Returns:*
10294
 
10295
+ - If `is_regular_file(p)`, the size in bytes of the file `p` resolves
10296
+ to, determined as if by the value of the POSIX `stat` class member
10297
+ `st_size` obtained as if by POSIX `stat()`.
 
10298
  - Otherwise, the result is *implementation-defined*.
10299
 
10300
  The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
10301
  an error occurs.
10302
 
10303
  *Throws:* As specified in  [[fs.err.report]].
10304
 
10305
+ #### Hard link count <a id="fs.op.hard.lk.ct">[[fs.op.hard.lk.ct]]</a>
10306
 
10307
  ``` cpp
10308
  uintmax_t hard_link_count(const path& p);
10309
  uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
10310
  ```
 
10312
  *Returns:* The number of hard links for `p`. The signature with argument
10313
  `ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
10314
 
10315
  *Throws:* As specified in  [[fs.err.report]].
10316
 
10317
+ #### Is block file <a id="fs.op.is.block.file">[[fs.op.is.block.file]]</a>
10318
 
10319
  ``` cpp
10320
  bool is_block_file(file_status s) noexcept;
10321
  ```
10322
 
 
10331
  respectively. The signature with argument `ec` returns `false` if an
10332
  error occurs.
10333
 
10334
  *Throws:* As specified in  [[fs.err.report]].
10335
 
10336
+ #### Is character file <a id="fs.op.is.char.file">[[fs.op.is.char.file]]</a>
10337
 
10338
  ``` cpp
10339
  bool is_character_file(file_status s) noexcept;
10340
  ```
10341
 
 
10350
  `is_character_file(status(p, ec))`, respectively.
10351
  The signature with argument `ec` returns `false` if an error occurs.
10352
 
10353
  *Throws:* As specified in  [[fs.err.report]].
10354
 
10355
+ #### Is directory <a id="fs.op.is.directory">[[fs.op.is.directory]]</a>
10356
 
10357
  ``` cpp
10358
  bool is_directory(file_status s) noexcept;
10359
  ```
10360
 
 
10369
  respectively. The signature with argument `ec` returns `false` if an
10370
  error occurs.
10371
 
10372
  *Throws:* As specified in  [[fs.err.report]].
10373
 
10374
+ #### Is empty <a id="fs.op.is.empty">[[fs.op.is.empty]]</a>
10375
 
10376
  ``` cpp
10377
  bool is_empty(const path& p);
10378
+ bool is_empty(const path& p, error_code& ec);
10379
  ```
10380
 
10381
  *Effects:*
10382
 
10383
  - Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
 
10397
  occurred.
10398
  - Otherwise, return `sz == 0`.
10399
 
10400
  *Throws:* As specified in  [[fs.err.report]].
10401
 
10402
+ #### Is fifo <a id="fs.op.is.fifo">[[fs.op.is.fifo]]</a>
10403
 
10404
  ``` cpp
10405
  bool is_fifo(file_status s) noexcept;
10406
  ```
10407
 
 
10416
  respectively. The signature with argument `ec` returns `false` if an
10417
  error occurs.
10418
 
10419
  *Throws:* As specified in  [[fs.err.report]].
10420
 
10421
+ #### Is other <a id="fs.op.is.other">[[fs.op.is.other]]</a>
10422
 
10423
  ``` cpp
10424
  bool is_other(file_status s) noexcept;
10425
  ```
10426
 
 
10436
  respectively. The signature with argument `ec` returns `false` if an
10437
  error occurs.
10438
 
10439
  *Throws:* As specified in  [[fs.err.report]].
10440
 
10441
+ #### Is regular file <a id="fs.op.is.regular.file">[[fs.op.is.regular.file]]</a>
10442
 
10443
  ``` cpp
10444
  bool is_regular_file(file_status s) noexcept;
10445
  ```
10446
 
 
10451
  ```
10452
 
10453
  *Returns:* `is_regular_file(status(p))`.
10454
 
10455
  *Throws:* `filesystem_error` if `status(p)` would throw
10456
+ `filesystem_error`.
10457
 
10458
  ``` cpp
10459
  bool is_regular_file(const path& p, error_code& ec) noexcept;
10460
  ```
10461
 
 
10466
  between cases, call the `status` function directly. — *end note*]
10467
 
10468
  *Returns:* `is_regular_file(status(p, ec))`. Returns `false` if an error
10469
  occurs.
10470
 
10471
+ #### Is socket <a id="fs.op.is.socket">[[fs.op.is.socket]]</a>
10472
 
10473
  ``` cpp
10474
  bool is_socket(file_status s) noexcept;
10475
  ```
10476
 
 
10485
  respectively. The signature with argument `ec` returns `false` if an
10486
  error occurs.
10487
 
10488
  *Throws:* As specified in  [[fs.err.report]].
10489
 
10490
+ #### Is symlink <a id="fs.op.is.symlink">[[fs.op.is.symlink]]</a>
10491
 
10492
  ``` cpp
10493
  bool is_symlink(file_status s) noexcept;
10494
  ```
10495
 
 
10504
  `is_symlink(symlink_status(p, ec))`, respectively. The signature with
10505
  argument `ec` returns `false` if an error occurs.
10506
 
10507
  *Throws:* As specified in  [[fs.err.report]].
10508
 
10509
+ #### Last write time <a id="fs.op.last.write.time">[[fs.op.last.write.time]]</a>
10510
 
10511
  ``` cpp
10512
  file_time_type last_write_time(const path& p);
10513
  file_time_type last_write_time(const path& p, error_code& ec) noexcept;
10514
  ```
10515
 
10516
  *Returns:* The time of last data modification of `p`, determined as if
10517
+ by the value of the POSIX `stat` class member `st_mtime` obtained as if
10518
+ by POSIX `stat()`. The signature with argument `ec` returns
10519
  `file_time_type::min()` if an error occurs.
10520
 
10521
  *Throws:* As specified in  [[fs.err.report]].
10522
 
10523
  ``` cpp
 
10541
  void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
10542
  void permissions(const path& p, perms prms, error_code& ec) noexcept;
10543
  void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
10544
  ```
10545
 
10546
+ *Preconditions:* Exactly one of the `perm_options` constants `replace`,
10547
  `add`, or `remove` is present in `opts`.
10548
 
10549
  *Remarks:* The second signature behaves as if it had an additional
10550
  parameter `perm_options` `opts` with an argument of
10551
  `perm_options::replace`.
 
10589
 
10590
  or `path()` at the first error occurrence, if any.
10591
 
10592
  *Throws:* As specified in  [[fs.err.report]].
10593
 
10594
+ #### Read symlink <a id="fs.op.read.symlink">[[fs.op.read.symlink]]</a>
10595
 
10596
  ``` cpp
10597
  path read_symlink(const path& p);
10598
  path read_symlink(const path& p, error_code& ec);
10599
  ```
 
10649
  as if by POSIX `remove()`.
10650
 
10651
  [*Note 1*: A symbolic link is itself removed, rather than the file it
10652
  resolves to. — *end note*]
10653
 
10654
+ *Ensures:* `exists(symlink_status(p))` is `false`.
10655
 
10656
  *Returns:* `false` if `p` did not exist, otherwise `true`. The signature
10657
  with argument `ec` returns `false` if an error occurs.
10658
 
10659
  *Throws:* As specified in  [[fs.err.report]].
10660
 
10661
+ #### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
10662
 
10663
  ``` cpp
10664
  uintmax_t remove_all(const path& p);
10665
+ uintmax_t remove_all(const path& p, error_code& ec);
10666
  ```
10667
 
10668
  *Effects:* Recursively deletes the contents of `p` if it exists, then
10669
  deletes file `p` itself, as if by POSIX `remove()`.
10670
 
10671
  [*Note 1*: A symbolic link is itself removed, rather than the file it
10672
  resolves to. — *end note*]
10673
 
10674
+ *Ensures:* `exists(symlink_status(p))` is `false`.
10675
 
10676
  *Returns:* The number of files removed. The signature with argument `ec`
10677
  returns `static_cast< uintmax_t>(-1)` if an error occurs.
10678
 
10679
  *Throws:* As specified in  [[fs.err.report]].
 
10702
 
10703
  — *end note*]
10704
 
10705
  *Throws:* As specified in  [[fs.err.report]].
10706
 
10707
+ #### Resize file <a id="fs.op.resize.file">[[fs.op.resize.file]]</a>
10708
 
10709
  ``` cpp
10710
  void resize_file(const path& p, uintmax_t new_size);
10711
  void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
10712
  ```
10713
 
10714
+ *Effects:* Causes the size that would be returned by `file_size(p)` to
10715
+ be equal to `new_size`, as if by POSIX `truncate()`.
10716
 
10717
  *Throws:* As specified in  [[fs.err.report]].
10718
 
 
 
10719
  #### Space <a id="fs.op.space">[[fs.op.space]]</a>
10720
 
10721
  ``` cpp
10722
  space_info space(const path& p);
10723
  space_info space(const path& p, error_code& ec) noexcept;
 
10816
  - Otherwise, if the attributes indicate a fifo or pipe file, as if by
10817
  POSIX `S_ISFIFO`, returns `file_status(file_type::fifo, prms)`.
10818
  - Otherwise, if the attributes indicate a socket, as if by POSIX
10819
  `S_ISSOCK`, returns `file_status(file_type::socket, prms)`.
10820
  - Otherwise, if the attributes indicate an implementation-defined file
10821
+ type [[fs.enum.file.type]], returns
10822
  `file_status(file_type::`*`A`*`, prms)`, where *A* is the constant
10823
  for the *implementation-defined* file type.
10824
  - Otherwise, returns `file_status(file_type::unknown, prms)`.
10825
 
10826
  *Remarks:* If a symbolic link is encountered during pathname resolution,
10827
  pathname resolution continues using the contents of the symbolic link.
10828
 
10829
+ #### Status known <a id="fs.op.status.known">[[fs.op.status.known]]</a>
10830
 
10831
  ``` cpp
10832
  bool status_known(file_status s) noexcept;
10833
  ```
10834
 
10835
  *Returns:* `s.type() != file_type::none`.
10836
 
10837
+ #### Symlink status <a id="fs.op.symlink.status">[[fs.op.symlink.status]]</a>
10838
 
10839
  ``` cpp
10840
  file_status symlink_status(const path& p);
10841
  file_status symlink_status(const path& p, error_code& ec) noexcept;
10842
  ```
 
10856
 
10857
  *Remarks:* Pathname resolution terminates if `p` names a symbolic link.
10858
 
10859
  *Throws:* As specified in  [[fs.err.report]].
10860
 
10861
+ #### Temporary directory path <a id="fs.op.temp.dir.path">[[fs.op.temp.dir.path]]</a>
10862
 
10863
  ``` cpp
10864
  path temp_directory_path();
10865
  path temp_directory_path(error_code& ec);
10866
  ```
10867
 
10868
+ Let `p` be an unspecified directory path suitable for temporary files.
10869
+
10870
+ *Effects:* If `exists(p)` is `false` or `is_directory(p)` is `false`, an
10871
+ error is reported [[fs.err.report]].
10872
+
10873
+ *Returns:* The path `p`. The signature with argument `ec` returns
10874
  `path()` if an error occurs.
10875
 
10876
  *Throws:* As specified in  [[fs.err.report]].
10877
 
10878
  [*Example 1*: For POSIX-based operating systems, an implementation
 
10880
  in the list TMPDIR, TMP, TEMP, TEMPDIR, or if none of these are found,
10881
  `"/tmp"`. For Windows-based operating systems, an implementation might
10882
  return the path reported by the Windows `GetTempPath` API
10883
  function. — *end example*]
10884
 
10885
+ #### Weakly canonical <a id="fs.op.weakly.canonical">[[fs.op.weakly.canonical]]</a>
10886
 
10887
  ``` cpp
10888
  path weakly_canonical(const path& p);
10889
  path weakly_canonical(const path& p, error_code& ec);
10890
  ```
10891
 
10892
  *Returns:* `p` with symlinks resolved and the result
10893
+ normalized [[fs.path.generic]].
10894
 
10895
  *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
10896
  determine existence, return a path composed by `operator/=` from the
10897
+ result of calling `canonical()` with a path argument composed of the
10898
+ leading elements of `p` that exist, if any, followed by the elements of
10899
+ `p` that do not exist, if any. For the first form, `canonical()` is
10900
+ called without an `error_code` argument. For the second form,
10901
+ `canonical()` is called with `ec` as an `error_code` argument, and
10902
+ `path()` is returned at the first error occurrence, if any.
 
10903
 
10904
+ *Ensures:* The returned path is in normal form [[fs.path.generic]].
 
10905
 
10906
+ *Remarks:* Implementations should avoid unnecessary normalization such
10907
+ as when `canonical` has already been called on the entirety of `p`.
 
10908
 
10909
  *Throws:* As specified in  [[fs.err.report]].
10910
 
10911
  ## C library files <a id="c.files">[[c.files]]</a>
10912
 
 
10936
  #define stdin see below
10937
  #define stdout see below
10938
 
10939
  namespace std {
10940
  int remove(const char* filename);
10941
+ int rename(const char* old_p, const char* new_p);
10942
  FILE* tmpfile();
10943
  char* tmpnam(char* s);
10944
  int fclose(FILE* stream);
10945
  int fflush(FILE* stream);
10946
  FILE* fopen(const char* filename, const char* mode);
 
10987
 
10988
  The contents and meaning of the header `<cstdio>` are the same as the C
10989
  standard library header `<stdio.h>`.
10990
 
10991
  Calls to the function `tmpnam` with an argument that is a null pointer
10992
+ value may introduce a data race [[res.on.data.races]] with other calls
10993
+ to `tmpnam` with an argument that is a null pointer value.
10994
 
10995
+ See also: ISO C 7.21
10996
 
10997
  ### Header `<cinttypes>` synopsis <a id="cinttypes.syn">[[cinttypes.syn]]</a>
10998
 
10999
  ``` cpp
11000
  #include <cstdint> // see [cstdint.syn]
 
11073
  The contents and meaning of the header `<cinttypes>` are the same as the
11074
  C standard library header `<inttypes.h>`, with the following changes:
11075
 
11076
  - The header `<cinttypes>` includes the header `<cstdint>` instead of
11077
  `<stdint.h>`, and
11078
+ - if and only if the type `intmax_t` designates an extended integer type
11079
+ [[basic.fundamental]], the following function signatures are added:
 
11080
  ``` cpp
11081
  intmax_t abs(intmax_t);
11082
  imaxdiv_t div(intmax_t, intmax_t);
11083
  ```
11084
 
11085
  which shall have the same semantics as the function signatures
11086
  `intmax_t imaxabs(intmax_t)` and
11087
  `imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
11088
 
11089
+ See also: ISO C 7.8
11090
 
11091
  <!-- Link reference definitions -->
11092
  [adjustfield.manip]: #adjustfield.manip
 
11093
  [basefield.manip]: #basefield.manip
11094
  [basic.fundamental]: basic.md#basic.fundamental
11095
  [basic.ios.cons]: #basic.ios.cons
11096
+ [basic.ios.copyfmt]: #basic.ios.copyfmt
11097
  [basic.ios.members]: #basic.ios.members
11098
  [basic.start.main]: basic.md#basic.start.main
11099
  [bidirectional.iterators]: iterators.md#bidirectional.iterators
11100
  [bitmask.types]: library.md#bitmask.types
11101
  [c.files]: #c.files
11102
+ [char.traits]: strings.md#char.traits
11103
  [cinttypes.syn]: #cinttypes.syn
11104
+ [container.requirements.general]: containers.md#container.requirements.general
11105
+ [cpp17.allocator]: #cpp17.allocator
11106
+ [cpp17.copyassignable]: #cpp17.copyassignable
11107
+ [cpp17.copyconstructible]: #cpp17.copyconstructible
11108
+ [cpp17.defaultconstructible]: #cpp17.defaultconstructible
11109
+ [cpp17.destructible]: #cpp17.destructible
11110
+ [cpp17.equalitycomparable]: #cpp17.equalitycomparable
11111
  [cstdio.syn]: #cstdio.syn
11112
  [defns.ntcts]: library.md#defns.ntcts
11113
  [enumerated.types]: library.md#enumerated.types
11114
  [error.reporting]: #error.reporting
11115
  [ext.manip]: #ext.manip
 
11116
  [file.streams]: #file.streams
11117
  [filebuf]: #filebuf
11118
  [filebuf.assign]: #filebuf.assign
11119
  [filebuf.cons]: #filebuf.cons
11120
  [filebuf.members]: #filebuf.members
11121
+ [filebuf.open.modes]: #filebuf.open.modes
11122
+ [filebuf.seekoff]: #filebuf.seekoff
11123
  [filebuf.virtuals]: #filebuf.virtuals
 
11124
  [filesystems]: #filesystems
11125
  [floatfield.manip]: #floatfield.manip
11126
  [fmtflags.manip]: #fmtflags.manip
11127
  [fmtflags.state]: #fmtflags.state
11128
  [fpos]: #fpos
11129
  [fpos.members]: #fpos.members
11130
  [fpos.operations]: #fpos.operations
11131
+ [fs.class.directory.entry]: #fs.class.directory.entry
11132
+ [fs.class.directory.iterator]: #fs.class.directory.iterator
11133
+ [fs.class.file.status]: #fs.class.file.status
11134
+ [fs.class.filesystem.error]: #fs.class.filesystem.error
11135
  [fs.class.path]: #fs.class.path
11136
  [fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
11137
  [fs.conform.9945]: #fs.conform.9945
11138
  [fs.conform.os]: #fs.conform.os
11139
  [fs.conformance]: #fs.conformance
 
 
 
 
 
 
 
 
 
 
 
 
 
11140
  [fs.dir.entry.cons]: #fs.dir.entry.cons
11141
  [fs.dir.entry.mods]: #fs.dir.entry.mods
11142
  [fs.dir.entry.obs]: #fs.dir.entry.obs
11143
  [fs.dir.itr.members]: #fs.dir.itr.members
11144
  [fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
11145
  [fs.enum]: #fs.enum
11146
  [fs.enum.copy.opts]: #fs.enum.copy.opts
11147
  [fs.enum.dir.opts]: #fs.enum.dir.opts
11148
+ [fs.enum.file.type]: #fs.enum.file.type
11149
  [fs.enum.path.format]: #fs.enum.path.format
11150
  [fs.enum.perm.opts]: #fs.enum.perm.opts
11151
  [fs.enum.perms]: #fs.enum.perms
11152
  [fs.err.report]: #fs.err.report
11153
+ [fs.file.status.cons]: #fs.file.status.cons
11154
+ [fs.file.status.mods]: #fs.file.status.mods
11155
+ [fs.file.status.obs]: #fs.file.status.obs
11156
+ [fs.filesystem.error.members]: #fs.filesystem.error.members
11157
  [fs.filesystem.syn]: #fs.filesystem.syn
11158
  [fs.general]: #fs.general
11159
  [fs.norm.ref]: #fs.norm.ref
11160
  [fs.op.absolute]: #fs.op.absolute
11161
  [fs.op.canonical]: #fs.op.canonical
11162
  [fs.op.copy]: #fs.op.copy
11163
+ [fs.op.copy.file]: #fs.op.copy.file
11164
+ [fs.op.copy.symlink]: #fs.op.copy.symlink
11165
+ [fs.op.create.dir.symlk]: #fs.op.create.dir.symlk
11166
+ [fs.op.create.directories]: #fs.op.create.directories
11167
+ [fs.op.create.directory]: #fs.op.create.directory
11168
+ [fs.op.create.hard.lk]: #fs.op.create.hard.lk
11169
+ [fs.op.create.symlink]: #fs.op.create.symlink
11170
+ [fs.op.current.path]: #fs.op.current.path
11171
  [fs.op.equivalent]: #fs.op.equivalent
11172
  [fs.op.exists]: #fs.op.exists
11173
+ [fs.op.file.size]: #fs.op.file.size
11174
  [fs.op.funcs]: #fs.op.funcs
11175
+ [fs.op.hard.lk.ct]: #fs.op.hard.lk.ct
11176
+ [fs.op.is.block.file]: #fs.op.is.block.file
11177
+ [fs.op.is.char.file]: #fs.op.is.char.file
11178
+ [fs.op.is.directory]: #fs.op.is.directory
11179
+ [fs.op.is.empty]: #fs.op.is.empty
11180
+ [fs.op.is.fifo]: #fs.op.is.fifo
11181
+ [fs.op.is.other]: #fs.op.is.other
11182
+ [fs.op.is.regular.file]: #fs.op.is.regular.file
11183
+ [fs.op.is.socket]: #fs.op.is.socket
11184
+ [fs.op.is.symlink]: #fs.op.is.symlink
11185
+ [fs.op.last.write.time]: #fs.op.last.write.time
11186
  [fs.op.permissions]: #fs.op.permissions
11187
  [fs.op.proximate]: #fs.op.proximate
11188
+ [fs.op.read.symlink]: #fs.op.read.symlink
11189
  [fs.op.relative]: #fs.op.relative
11190
  [fs.op.remove]: #fs.op.remove
11191
+ [fs.op.remove.all]: #fs.op.remove.all
11192
  [fs.op.rename]: #fs.op.rename
11193
+ [fs.op.resize.file]: #fs.op.resize.file
11194
  [fs.op.space]: #fs.op.space
11195
  [fs.op.status]: #fs.op.status
11196
+ [fs.op.status.known]: #fs.op.status.known
11197
+ [fs.op.symlink.status]: #fs.op.symlink.status
11198
+ [fs.op.temp.dir.path]: #fs.op.temp.dir.path
11199
+ [fs.op.weakly.canonical]: #fs.op.weakly.canonical
11200
  [fs.path.append]: #fs.path.append
11201
  [fs.path.assign]: #fs.path.assign
11202
  [fs.path.compare]: #fs.path.compare
11203
  [fs.path.concat]: #fs.path.concat
11204
  [fs.path.construct]: #fs.path.construct
11205
  [fs.path.cvt]: #fs.path.cvt
11206
  [fs.path.decompose]: #fs.path.decompose
 
11207
  [fs.path.fmt.cvt]: #fs.path.fmt.cvt
11208
  [fs.path.gen]: #fs.path.gen
11209
  [fs.path.generic]: #fs.path.generic
11210
  [fs.path.generic.obs]: #fs.path.generic.obs
11211
  [fs.path.io]: #fs.path.io
 
11233
  [ifstream.members]: #ifstream.members
11234
  [input.iterators]: iterators.md#input.iterators
11235
  [input.output]: #input.output
11236
  [input.output.general]: #input.output.general
11237
  [input.streams]: #input.streams
11238
+ [intro.multithread]: basic.md#intro.multithread
11239
+ [intro.races]: basic.md#intro.races
11240
  [iomanip.syn]: #iomanip.syn
11241
  [ios]: #ios
11242
  [ios.base]: #ios.base
11243
  [ios.base.callback]: #ios.base.callback
11244
  [ios.base.cons]: #ios.base.cons
11245
  [ios.base.locales]: #ios.base.locales
11246
  [ios.base.storage]: #ios.base.storage
11247
+ [ios.failure]: #ios.failure
11248
+ [ios.fmtflags]: #ios.fmtflags
11249
+ [ios.fmtflags.const]: #ios.fmtflags.const
11250
+ [ios.init]: #ios.init
11251
+ [ios.iostate]: #ios.iostate
11252
  [ios.members.static]: #ios.members.static
11253
+ [ios.openmode]: #ios.openmode
11254
  [ios.overview]: #ios.overview
11255
+ [ios.seekdir]: #ios.seekdir
11256
  [ios.syn]: #ios.syn
11257
  [ios.types]: #ios.types
 
 
 
 
 
 
11258
  [iosfwd.syn]: #iosfwd.syn
11259
  [iostate.flags]: #iostate.flags
11260
  [iostream.assign]: #iostream.assign
11261
  [iostream.cons]: #iostream.cons
11262
  [iostream.dest]: #iostream.dest
 
11269
  [iostream.syn]: #iostream.syn
11270
  [iostreamclass]: #iostreamclass
11271
  [iostreams.base]: #iostreams.base
11272
  [iostreams.limits.pos]: #iostreams.limits.pos
11273
  [iostreams.requirements]: #iostreams.requirements
11274
+ [iostreams.summary]: #iostreams.summary
11275
  [iostreams.threadsafety]: #iostreams.threadsafety
11276
  [istream]: #istream
11277
  [istream.assign]: #istream.assign
11278
  [istream.cons]: #istream.cons
11279
  [istream.extractors]: #istream.extractors
11280
  [istream.formatted]: #istream.formatted
11281
  [istream.formatted.arithmetic]: #istream.formatted.arithmetic
11282
  [istream.formatted.reqmts]: #istream.formatted.reqmts
11283
  [istream.manip]: #istream.manip
11284
  [istream.rvalue]: #istream.rvalue
11285
+ [istream.sentry]: #istream.sentry
11286
  [istream.syn]: #istream.syn
11287
  [istream.unformatted]: #istream.unformatted
 
11288
  [istringstream]: #istringstream
11289
  [istringstream.assign]: #istringstream.assign
11290
  [istringstream.cons]: #istringstream.cons
11291
  [istringstream.members]: #istringstream.members
11292
  [lex.charset]: lex.md#lex.charset
11293
  [locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
11294
  [locale.num.get]: localization.md#locale.num.get
11295
+ [namespace.std]: library.md#namespace.std
11296
  [narrow.stream.objects]: #narrow.stream.objects
11297
+ [numeric.limits]: support.md#numeric.limits
11298
  [ofstream]: #ofstream
11299
  [ofstream.assign]: #ofstream.assign
11300
  [ofstream.cons]: #ofstream.cons
11301
  [ofstream.members]: #ofstream.members
11302
  [ostream]: #ostream
 
11308
  [ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
11309
  [ostream.inserters.character]: #ostream.inserters.character
11310
  [ostream.manip]: #ostream.manip
11311
  [ostream.rvalue]: #ostream.rvalue
11312
  [ostream.seeks]: #ostream.seeks
11313
+ [ostream.sentry]: #ostream.sentry
11314
  [ostream.syn]: #ostream.syn
11315
  [ostream.unformatted]: #ostream.unformatted
 
11316
  [ostringstream]: #ostringstream
11317
  [ostringstream.assign]: #ostringstream.assign
11318
  [ostringstream.cons]: #ostringstream.cons
11319
  [ostringstream.members]: #ostringstream.members
11320
  [output.streams]: #output.streams
 
11350
  [string.streams]: #string.streams
11351
  [stringbuf]: #stringbuf
11352
  [stringbuf.assign]: #stringbuf.assign
11353
  [stringbuf.cons]: #stringbuf.cons
11354
  [stringbuf.members]: #stringbuf.members
11355
+ [stringbuf.seekoff.newoff]: #stringbuf.seekoff.newoff
11356
+ [stringbuf.seekoff.pos]: #stringbuf.seekoff.pos
11357
  [stringbuf.virtuals]: #stringbuf.virtuals
11358
  [strings]: strings.md#strings
11359
  [stringstream]: #stringstream
11360
  [stringstream.assign]: #stringstream.assign
11361
  [stringstream.cons]: #stringstream.cons
11362
  [stringstream.members]: #stringstream.members
11363
+ [syncstream]: #syncstream
11364
+ [syncstream.osyncstream]: #syncstream.osyncstream
11365
+ [syncstream.osyncstream.cons]: #syncstream.osyncstream.cons
11366
+ [syncstream.osyncstream.members]: #syncstream.osyncstream.members
11367
+ [syncstream.osyncstream.overview]: #syncstream.osyncstream.overview
11368
+ [syncstream.syn]: #syncstream.syn
11369
+ [syncstream.syncbuf]: #syncstream.syncbuf
11370
+ [syncstream.syncbuf.assign]: #syncstream.syncbuf.assign
11371
+ [syncstream.syncbuf.cons]: #syncstream.syncbuf.cons
11372
+ [syncstream.syncbuf.members]: #syncstream.syncbuf.members
11373
+ [syncstream.syncbuf.overview]: #syncstream.syncbuf.overview
11374
+ [syncstream.syncbuf.special]: #syncstream.syncbuf.special
11375
+ [syncstream.syncbuf.virtuals]: #syncstream.syncbuf.virtuals
 
 
 
 
 
 
 
 
 
11376
  [temp.deduct]: temp.md#temp.deduct
 
11377
  [wide.stream.objects]: #wide.stream.objects
11378
 
11379
  [^1]: It is the implementation’s responsibility to implement headers so
11380
  that including `<iosfwd>` and other headers does not violate the
11381
  rules about multiple occurrences of default arguments.
11382
 
11383
+ [^2]: If it is possible for them to do so, implementations should
11384
+ initialize the objects earlier than required.
11385
 
11386
+ [^3]: Constructors and destructors for objects with static storage
11387
+ duration can access these objects to read input from `stdin` or
11388
+ write output to `stdout` or `stderr`.
11389
 
11390
  [^4]: Typically `long long`.
11391
 
11392
  [^5]: `streamsize` is used in most places where ISO C would use
11393
+ `size_t`.
 
 
 
11394
 
11395
  [^6]: This implies that operations on a standard iostream object can be
11396
  mixed arbitrarily with operations on the corresponding stdio stream.
11397
  In practical terms, synchronization usually means that a standard
11398
  iostream object and a standard stdio object share a buffer.
 
11400
  [^7]: An implementation is free to implement both the integer array
11401
  pointed at by `iarray` and the pointer array pointed at by `parray`
11402
  as sparse data structures, possibly with a one-element cache for
11403
  each.
11404
 
11405
+ [^8]: For example, because it cannot allocate space.
11406
 
11407
+ [^9]: For example, because it cannot allocate space.
11408
 
11409
  [^10]: This suggests an infinite amount of copying, but the
11410
  implementation can keep track of the maximum element of the arrays
11411
  that is nonzero.
11412
 
 
11442
 
11443
  [^18]: This will be possible only in functions that are part of the
11444
  library. The semantics of the constructor used in user code is as
11445
  specified.
11446
 
11447
+ [^19]: The `sentry` constructor and destructor can also perform
11448
+ additional implementation-dependent operations.
11449
 
11450
+ [^20]: This is done without causing an `ios_base::failure` to be thrown.
11451
 
11452
  [^21]: See, for example, the function signature
11453
+ `ws(basic_istream&)`[[istream.manip]].
11454
 
11455
  [^22]: See, for example, the function signature
11456
+ `dec(ios_base&)`[[basefield.manip]].
11457
 
11458
+ [^23]: This is done without causing an `ios_base::failure` to be thrown.
11459
 
11460
  [^24]: Note that this function is not overloaded on types `signed char`
11461
  and `unsigned char`.
11462
 
11463
  [^25]: Note that this function is not overloaded on types `signed char`
 
11483
  function can determine that no synchronization is necessary.
11484
 
11485
  [^32]: The `sentry` constructor and destructor can also perform
11486
  additional implementation-dependent operations.
11487
 
11488
+ [^33]: without causing an `ios_base::failure` to be thrown.
11489
 
11490
  [^34]: See, for example, the function signature
11491
+ `endl(basic_ostream&)`[[ostream.manip]].
11492
 
11493
  [^35]: See, for example, the function signature
11494
+ `dec(ios_base&)`[[basefield.manip]].
11495
 
11496
+ [^36]: without causing an `ios_base::failure` to be thrown.
11497
 
11498
  [^37]: Note that this function is not overloaded on types `signed char`
11499
  and `unsigned char`.
11500
 
11501
  [^38]: Note that this function is not overloaded on types `signed char`
 
11510
  `basic_ostream<charT, traits>` object `cout` (the same as
11511
  `cout << noshowbase`).
11512
 
11513
  [^40]: The macro `SEEK_END` is defined, and the function signatures
11514
  `fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
11515
+ declared, in `<cstdio>`.
11516
 
11517
  [^41]: POSIX® is a registered trademark of The IEEE. Windows® is a
11518
  registered trademark of Microsoft Corporation. This information is
11519
  given for the convenience of users of this document and does not
11520
  constitute an endorsement by ISO or IEC of these products.