From Jason Turner

[input.output]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmphmnuuow9/{from.md → to.md} +5440 -964
tmp/tmphmnuuow9/{from.md → to.md} RENAMED
@@ -12,22 +12,23 @@ 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
- | | | `<cstdio>` |
 
29
  | | | `<cinttypes>` |
30
 
31
 
32
  Figure  [[fig:streampos]] illustrates relationships among various types
33
  described in this clause. A line from **A** to **B** indicates that
@@ -57,30 +58,34 @@ and `traits` behave as described if `traits::pos_type` and
57
  as noted explicitly below, their behavior when `traits::pos_type` and
58
  `traits::off_type` are other types is *implementation-defined*.
59
 
60
  In the classes of Clause  [[input.output]], a template parameter with
61
  name `charT` represents a member of the set of types containing `char`,
62
- `wchar_t`, and any other implementation-defined character types that
63
  satisfy the requirements for a character on which any of the iostream
64
  components can be instantiated.
65
 
66
  ### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
67
 
68
  Concurrent access to a stream object ([[string.streams]], 
69
  [[file.streams]]), stream buffer object ([[stream.buffers]]), or C
70
  Library stream ([[c.files]]) by multiple threads may result in a data
71
  race ([[intro.multithread]]) unless otherwise specified (
72
- [[iostream.objects]]). Data races result in undefined behavior (
73
- [[intro.multithread]]).
 
 
74
 
75
  If one thread makes a library call *a* that writes a value to a stream
76
  and, as a result, another thread reads this value from the stream
77
  through a library call *b* such that this does not result in a data
78
  race, then *a*’s write synchronizes with *b*’s read.
79
 
80
  ## Forward declarations <a id="iostream.forward">[[iostream.forward]]</a>
81
 
 
 
82
  ``` cpp
83
  namespace std {
84
  template<class charT> class char_traits;
85
  template<> class char_traits<char>;
86
  template<> class char_traits<char16_t>;
@@ -125,61 +130,63 @@ namespace std {
125
  template <class charT, class traits = char_traits<charT>>
126
  class istreambuf_iterator;
127
  template <class charT, class traits = char_traits<charT>>
128
  class ostreambuf_iterator;
129
 
130
- typedef basic_ios<char> ios;
131
- typedef basic_ios<wchar_t> wios;
132
 
133
- typedef basic_streambuf<char> streambuf;
134
- typedef basic_istream<char> istream;
135
- typedef basic_ostream<char> ostream;
136
- typedef basic_iostream<char> iostream;
137
 
138
- typedef basic_stringbuf<char> stringbuf;
139
- typedef basic_istringstream<char> istringstream;
140
- typedef basic_ostringstream<char> ostringstream;
141
- typedef basic_stringstream<char> stringstream;
142
 
143
- typedef basic_filebuf<char> filebuf;
144
- typedef basic_ifstream<char> ifstream;
145
- typedef basic_ofstream<char> ofstream;
146
- typedef basic_fstream<char> fstream;
147
 
148
- typedef basic_streambuf<wchar_t> wstreambuf;
149
- typedef basic_istream<wchar_t> wistream;
150
- typedef basic_ostream<wchar_t> wostream;
151
- typedef basic_iostream<wchar_t> wiostream;
152
 
153
- typedef basic_stringbuf<wchar_t> wstringbuf;
154
- typedef basic_istringstream<wchar_t> wistringstream;
155
- typedef basic_ostringstream<wchar_t> wostringstream;
156
- typedef basic_stringstream<wchar_t> wstringstream;
157
 
158
- typedef basic_filebuf<wchar_t> wfilebuf;
159
- typedef basic_ifstream<wchar_t> wifstream;
160
- typedef basic_ofstream<wchar_t> wofstream;
161
- typedef basic_fstream<wchar_t> wfstream;
162
 
163
  template <class state> class fpos;
164
- typedef fpos<char_traits<char>::state_type> streampos;
165
- typedef fpos<char_traits<wchar_t>::state_type> wstreampos;
166
  }
167
  ```
168
 
169
  Default template arguments are described as appearing both in `<iosfwd>`
170
  and in the synopsis of other headers but it is well-formed to include
171
  both `<iosfwd>` and one or more of the other headers.[^1]
172
 
 
 
173
  The class template specialization `basic_ios<charT, traits>` serves as a
174
  virtual base class for the class templates `basic_istream`,
175
  `basic_ostream`, and class templates derived from them. `basic_iostream`
176
  is a class template derived from both `basic_istream<charT, traits>` and
177
  `basic_ostream<charT, traits>`.
178
 
179
- The class template specialization `basic_streambuf<charT,traits>` serves
180
- as a base class for class templates `basic_stringbuf` and
181
  `basic_filebuf`.
182
 
183
  The class template specialization `basic_istream<charT, traits>` serves
184
  as a base class for class templates `basic_istringstream` and
185
  `basic_ifstream`.
@@ -190,44 +197,47 @@ as a base class for class templates `basic_ostringstream` and
190
 
191
  The class template specialization `basic_iostream<charT, traits>` serves
192
  as a base class for class templates `basic_stringstream` and
193
  `basic_fstream`.
194
 
195
- Other typedefs define instances of class templates specialized for
196
- `char` or `wchar_t` types.
197
 
198
  Specializations of the class template `fpos` are used for specifying
199
  file position information.
200
 
201
  The types `streampos` and `wstreampos` are used for positioning streams
202
  specialized on `char` and `wchar_t` respectively.
203
 
 
 
204
  This synopsis suggests a circularity between `streampos` and
205
  `char_traits<char>`. An implementation can avoid this circularity by
206
  substituting equivalent types. One way to do this might be
207
 
208
  ``` cpp
209
  template<class stateT> class fpos { ... }; // depends on nothing
210
- typedef ... _STATE; // implementation private declaration of stateT
211
 
212
- typedef fpos<_STATE> streampos;
213
 
214
  template<> struct char_traits<char> {
215
- typedef streampos
216
- pos_type;
217
  }
218
  ```
219
 
 
 
220
  ## Standard iostream objects <a id="iostream.objects">[[iostream.objects]]</a>
221
 
222
- ### Overview <a id="iostream.objects.overview">[[iostream.objects.overview]]</a>
223
 
224
  ``` cpp
225
- #include <ios>
226
- #include <streambuf>
227
- #include <istream>
228
- #include <ostream>
229
 
230
  namespace std {
231
  extern istream cin;
232
  extern ostream cout;
233
  extern ostream cerr;
@@ -238,129 +248,136 @@ namespace std {
238
  extern wostream wcerr;
239
  extern wostream wclog;
240
  }
241
  ```
242
 
 
 
 
 
 
243
  The header `<iostream>` declares objects that associate objects with the
244
  standard C streams provided for by the functions declared in
245
  `<cstdio>` ([[c.files]]), and includes all the headers necessary to use
246
  these objects.
247
 
248
  The objects are constructed and the associations are established at some
249
  time prior to or during the first time an object of class
250
  `ios_base::Init` is constructed, and in any case before the body of
251
- `main` begins execution.[^2] The objects are not destroyed during
252
- program execution.[^3] The results of including `<iostream>` in a
253
- translation unit shall be as if `<iostream>` defined an instance of
254
- `ios_base::Init` with static storage duration. Similarly, the entire
255
- program shall behave as if there were at least one instance of
256
- `ios_base::Init` with static storage duration.
257
 
258
  Mixing operations on corresponding wide- and narrow-character streams
259
  follows the same semantics as mixing such operations on `FILE`s, as
260
- specified in Amendment 1 of the ISO C standard.
261
 
262
  Concurrent access to a synchronized ([[ios.members.static]]) standard
263
  iostream object’s formatted and unformatted input ([[istream]]) and
264
  output ([[ostream]]) functions or a standard C stream by multiple
265
- threads shall not result in a data race ([[intro.multithread]]). Users
266
- must still synchronize concurrent use of these objects and streams by
267
- multiple threads if they wish to avoid interleaved characters.
 
 
 
 
268
 
269
  ### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
270
 
271
  ``` cpp
272
  istream cin;
273
  ```
274
 
275
  The object `cin` controls input from a stream buffer associated with the
276
- object `stdin`, declared in `<cstdio>`.
277
 
278
  After the object `cin` is initialized, `cin.tie()` returns `&cout`. Its
279
  state is otherwise the same as required for
280
  `basic_ios<char>::init` ([[basic.ios.cons]]).
281
 
282
  ``` cpp
283
  ostream cout;
284
  ```
285
 
286
  The object `cout` controls output to a stream buffer associated with the
287
- object `stdout`, declared in `<cstdio>` ([[c.files]]).
288
 
289
  ``` cpp
290
  ostream cerr;
291
  ```
292
 
293
  The object `cerr` controls output to a stream buffer associated with the
294
- object `stderr`, declared in `<cstdio>` ([[c.files]]).
295
 
296
  After the object `cerr` is initialized, `cerr.flags() & unitbuf` is
297
  nonzero and `cerr.tie()` returns `&cout`. Its state is otherwise the
298
  same as required for `basic_ios<char>::init` ([[basic.ios.cons]]).
299
 
300
  ``` cpp
301
  ostream clog;
302
  ```
303
 
304
  The object `clog` controls output to a stream buffer associated with the
305
- object `stderr`, declared in `<cstdio>` ([[c.files]]).
306
 
307
  ### Wide stream objects <a id="wide.stream.objects">[[wide.stream.objects]]</a>
308
 
309
  ``` cpp
310
  wistream wcin;
311
  ```
312
 
313
  The object `wcin` controls input from a stream buffer associated with
314
- the object `stdin`, declared in `<cstdio>`.
315
 
316
  After the object `wcin` is initialized, `wcin.tie()` returns `&wcout`.
317
  Its state is otherwise the same as required for
318
  `basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
319
 
320
  ``` cpp
321
  wostream wcout;
322
  ```
323
 
324
  The object `wcout` controls output to a stream buffer associated with
325
- the object `stdout`, declared in `<cstdio>` ([[c.files]]).
326
 
327
  ``` cpp
328
  wostream wcerr;
329
  ```
330
 
331
  The object `wcerr` controls output to a stream buffer associated with
332
- the object `stderr`, declared in `<cstdio>` ([[c.files]]).
333
 
334
  After the object `wcerr` is initialized, `wcerr.flags() & unitbuf` is
335
  nonzero and `wcerr.tie()` returns `&wcout`. Its state is otherwise the
336
  same as required for `basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
337
 
338
  ``` cpp
339
  wostream wclog;
340
  ```
341
 
342
  The object `wclog` controls output to a stream buffer associated with
343
- the object `stderr`, declared in `<cstdio>` ([[c.files]]).
344
 
345
  ## Iostreams base classes <a id="iostreams.base">[[iostreams.base]]</a>
346
 
347
- ### Overview <a id="iostreams.base.overview">[[iostreams.base.overview]]</a>
348
 
349
  ``` cpp
350
- #include <iosfwd>
351
 
352
  namespace std {
353
- typedef implementation-defined streamoff;
354
- typedef implementation-defined streamsize;
355
  template <class stateT> class fpos;
356
 
357
  class ios_base;
358
  template <class charT, class traits = char_traits<charT>>
359
  class basic_ios;
360
 
361
- // [std.ios.manip], manipulators:
362
  ios_base& boolalpha (ios_base& str);
363
  ios_base& noboolalpha(ios_base& str);
364
 
365
  ios_base& showbase (ios_base& str);
366
  ios_base& noshowbase (ios_base& str);
@@ -378,27 +395,27 @@ namespace std {
378
  ios_base& nouppercase(ios_base& str);
379
 
380
  ios_base& unitbuf (ios_base& str);
381
  ios_base& nounitbuf (ios_base& str);
382
 
383
- // [adjustfield.manip] adjustfield:
384
  ios_base& internal (ios_base& str);
385
  ios_base& left (ios_base& str);
386
  ios_base& right (ios_base& str);
387
 
388
- // [basefield.manip] basefield:
389
  ios_base& dec (ios_base& str);
390
  ios_base& hex (ios_base& str);
391
  ios_base& oct (ios_base& str);
392
 
393
- // [floatfield.manip] floatfield:
394
  ios_base& fixed (ios_base& str);
395
  ios_base& scientific (ios_base& str);
396
  ios_base& hexfloat (ios_base& str);
397
  ios_base& defaultfloat(ios_base& str);
398
 
399
- // [error.reporting] error reporting:
400
  enum class io_errc {
401
  stream = 1
402
  };
403
 
404
  template <> struct is_error_code_enum<io_errc> : public true_type { };
@@ -409,19 +426,19 @@ namespace std {
409
  ```
410
 
411
  ### Types <a id="stream.types">[[stream.types]]</a>
412
 
413
  ``` cpp
414
- typedef implementation-defined streamoff;
415
  ```
416
 
417
  The type `streamoff` is a synonym for one of the signed basic integral
418
  types of sufficient size to represent the maximum possible file size for
419
  the operating system.[^4]
420
 
421
  ``` cpp
422
- typedef implementation-defined streamsize;
423
  ```
424
 
425
  The type `streamsize` is a synonym for one of the signed basic integral
426
  types. It is used to represent the number of characters transferred in
427
  an I/O operation, or the size of I/O buffers.[^5]
@@ -430,14 +447,14 @@ an I/O operation, or the size of I/O buffers.[^5]
430
 
431
  ``` cpp
432
  namespace std {
433
  class ios_base {
434
  public:
435
- class failure;
436
 
437
- // [ios::fmtflags] fmtflags
438
- typedef T1 fmtflags;
439
  static constexpr fmtflags boolalpha = unspecified;
440
  static constexpr fmtflags dec = unspecified;
441
  static constexpr fmtflags fixed = unspecified;
442
  static constexpr fmtflags hex = unspecified;
443
  static constexpr fmtflags internal = unspecified;
@@ -453,35 +470,35 @@ namespace std {
453
  static constexpr fmtflags uppercase = unspecified;
454
  static constexpr fmtflags adjustfield = see below;
455
  static constexpr fmtflags basefield = see below;
456
  static constexpr fmtflags floatfield = see below;
457
 
458
- // [ios::iostate] iostate
459
- typedef T2 iostate;
460
  static constexpr iostate badbit = unspecified;
461
  static constexpr iostate eofbit = unspecified;
462
  static constexpr iostate failbit = unspecified;
463
  static constexpr iostate goodbit = see below;
464
 
465
- // [ios::openmode] openmode
466
- typedef T3 openmode;
467
  static constexpr openmode app = unspecified;
468
  static constexpr openmode ate = unspecified;
469
  static constexpr openmode binary = unspecified;
470
  static constexpr openmode in = unspecified;
471
  static constexpr openmode out = unspecified;
472
  static constexpr openmode trunc = unspecified;
473
 
474
- // [ios::seekdir] seekdir
475
- typedef T4 seekdir;
476
  static constexpr seekdir beg = unspecified;
477
  static constexpr seekdir cur = unspecified;
478
  static constexpr seekdir end = unspecified;
479
 
480
  class Init;
481
 
482
- // [fmtflags.state] fmtflags state:
483
  fmtflags flags() const;
484
  fmtflags flags(fmtflags fmtfl);
485
  fmtflags setf(fmtflags fmtfl);
486
  fmtflags setf(fmtflags fmtfl, fmtflags mask);
487
  void unsetf(fmtflags mask);
@@ -489,25 +506,25 @@ namespace std {
489
  streamsize precision() const;
490
  streamsize precision(streamsize prec);
491
  streamsize width() const;
492
  streamsize width(streamsize wide);
493
 
494
- // [ios.base.locales] locales:
495
  locale imbue(const locale& loc);
496
  locale getloc() const;
497
 
498
- // [ios.base.storage] storage:
499
  static int xalloc();
500
  long& iword(int index);
501
  void*& pword(int index);
502
 
503
- // destructor
504
  virtual ~ios_base();
505
 
506
- // [ios.base.callback] callbacks;
507
  enum event { erase_event, imbue_event, copyfmt_event };
508
- typedef void (*event_callback)(event, ios_base&, int index);
509
  void register_callback(event_callback fn, int index);
510
 
511
  ios_base(const ios_base&) = delete;
512
  ios_base& operator=(const ios_base&) = delete;
513
 
@@ -526,11 +543,12 @@ namespace std {
526
 
527
  `ios_base`
528
 
529
  defines several member types:
530
 
531
- - a class `failure` derived from `system_error`;
 
532
  - a class `Init`;
533
  - three bitmask types, `fmtflags`, `iostate`, and `openmode`;
534
  - an enumerated type, `seekdir`.
535
 
536
  It maintains several kinds of data:
@@ -539,20 +557,24 @@ It maintains several kinds of data:
539
  - control information that influences how to interpret (format) input
540
  sequences and how to generate (format) output sequences;
541
  - additional information that is stored by the program for its private
542
  use.
543
 
 
 
544
  For the sake of exposition, the maintained data is presented here as:
545
 
546
  - `static int index`, specifies the next available unique index for the
547
  integer or pointer arrays maintained for the private use of the
548
  program, initialized to an unspecified value;
549
  - `long* iarray`, points to the first element of an arbitrary-length
550
  `long` array maintained for the private use of the program;
551
  - `void** parray`, points to the first element of an arbitrary-length
552
  pointer array maintained for the private use of the program.
553
 
 
 
554
  #### Types <a id="ios.types">[[ios.types]]</a>
555
 
556
  ##### Class `ios_base::failure` <a id="ios::failure">[[ios::failure]]</a>
557
 
558
  ``` cpp
@@ -563,22 +585,32 @@ namespace std {
563
  explicit failure(const char* msg, const error_code& ec = io_errc::stream);
564
  };
565
  }
566
  ```
567
 
 
 
 
 
 
 
 
 
568
  The class `failure` defines the base class for the types of all objects
569
  thrown as exceptions, by functions in the iostreams library, to report
570
  errors detected during stream buffer operations.
571
 
572
  When throwing `ios_base::failure` exceptions, implementations should
573
  provide values of `ec` that identify the specific reason for the
574
- failure. Errors arising from the operating system would typically be
 
 
575
  reported as `system_category()` errors with an error value of the error
576
  number reported by the operating system. Errors arising from within the
577
  stream library would typically be reported as
578
  `error_code(io_errc::stream,
579
- iostream_category())`.
580
 
581
  ``` cpp
582
  explicit failure(const string& msg, const error_code& ec = io_errc::stream);
583
  ```
584
 
@@ -593,11 +625,11 @@ explicit failure(const char* msg, const error_code& ec = io_errc::stream);
593
  base class with `msg` and `ec`.
594
 
595
  ##### Type `ios_base::fmtflags` <a id="ios::fmtflags">[[ios::fmtflags]]</a>
596
 
597
  ``` cpp
598
- typedef T1 fmtflags;
599
  ```
600
 
601
  The type `fmtflags` is a bitmask type ([[bitmask.types]]). Setting its
602
  elements has the effects indicated in
603
  Table  [[tab:iostreams.fmtflags.effects]].
@@ -636,11 +668,11 @@ Table  [[tab:iostreams.fmtflags.constants]].
636
 
637
 
638
  ##### Type `ios_base::iostate` <a id="ios::iostate">[[ios::iostate]]</a>
639
 
640
  ``` cpp
641
- typedef T2 iostate;
642
  ```
643
 
644
  The type `iostate` is a bitmask type ([[bitmask.types]]) that contains
645
  the elements indicated in Table  [[tab:iostreams.iostate.effects]].
646
 
@@ -658,11 +690,11 @@ Type `iostate` also defines the constant:
658
  - `goodbit`, the value zero.
659
 
660
  ##### Type `ios_base::openmode` <a id="ios::openmode">[[ios::openmode]]</a>
661
 
662
  ``` cpp
663
- typedef T3 openmode;
664
  ```
665
 
666
  The type `openmode` is a bitmask type ([[bitmask.types]]). It contains
667
  the elements indicated in Table  [[tab:iostreams.openmode.effects]].
668
 
@@ -679,11 +711,11 @@ the elements indicated in Table  [[tab:iostreams.openmode.effects]].
679
 
680
 
681
  ##### Type `ios_base::seekdir` <a id="ios::seekdir">[[ios::seekdir]]</a>
682
 
683
  ``` cpp
684
- typedef T4 seekdir;
685
  ```
686
 
687
  The type `seekdir` is an enumerated type ([[enumerated.types]]) that
688
  contains the elements indicated in
689
  Table  [[tab:iostreams.seekdir.effects]].
@@ -713,11 +745,11 @@ namespace std {
713
 
714
  The class `Init` describes an object whose construction ensures the
715
  construction of the eight objects declared in `<iostream>` (
716
  [[iostream.objects]]) that associate file stream buffers with the
717
  standard C streams provided for by the functions declared in
718
- `<cstdio>` ([[c.files]]).
719
 
720
  For the sake of exposition, the maintained data is presented here as:
721
 
722
  - `static int init_cnt`, counts the number of constructor and destructor
723
  calls for class `Init`, initialized to zero.
@@ -750,11 +782,11 @@ fmtflags flags() const;
750
 
751
  ``` cpp
752
  fmtflags flags(fmtflags fmtfl);
753
  ```
754
 
755
- `fmtfl == flags()`.
756
 
757
  *Returns:* The previous value of `flags()`.
758
 
759
  ``` cpp
760
  fmtflags setf(fmtflags fmtfl);
@@ -786,11 +818,11 @@ streamsize precision() const;
786
 
787
  ``` cpp
788
  streamsize precision(streamsize prec);
789
  ```
790
 
791
- `prec == precision()`.
792
 
793
  *Returns:* The previous value of `precision()`.
794
 
795
  ``` cpp
796
  streamsize width() const;
@@ -801,11 +833,11 @@ certain output conversions.
801
 
802
  ``` cpp
803
  streamsize width(streamsize wide);
804
  ```
805
 
806
- `wide == width()`.
807
 
808
  *Returns:* The previous value of `width()`.
809
 
810
  #### `ios_base` functions <a id="ios.base.locales">[[ios.base.locales]]</a>
811
 
@@ -819,11 +851,11 @@ locale imbue(const locale& loc);
819
  `ios_base::getloc()` from within `fn` returns the new locale value
820
  `loc`.
821
 
822
  *Returns:* The previous value of `getloc()`.
823
 
824
- `loc == getloc()`.
825
 
826
  ``` cpp
827
  locale getloc() const;
828
  ```
829
 
@@ -842,11 +874,11 @@ bool sync_with_stdio(bool sync = true);
842
  objects ([[iostream.objects]]) was synchronized and otherwise returns
843
  `false`. The first time it is called, the function returns `true`.
844
 
845
  *Effects:* If any input or output operation has occurred using the
846
  standard streams prior to the call, the effect is
847
- *implementation-defined*. Otherwise, called with a false argument, it
848
  allows the standard streams to operate independently of the standard C
849
  streams.
850
 
851
  When a standard iostream object `str` is *synchronized* with a standard
852
  stdio stream `f`, the effect of inserting a character `c` by
@@ -910,11 +942,11 @@ of unspecified size and stores a pointer to its first element in
910
  necessary to include the element `iarray[idx]`. Each newly allocated
911
  element of the array is initialized to zero. The reference returned is
912
  invalid after any other operations on the object.[^7] However, the value
913
  of the storage referred to is retained, so that until the next call to
914
  `copyfmt`, calling `iword` with the same index yields another reference
915
- to the same value. If the function fails[^8] and `*this` is a base
916
  subobject of a `basic_ios<>` object or subobject, the effect is
917
  equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
918
  object (which may throw `failure`).
919
 
920
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
@@ -931,12 +963,12 @@ as necessary to include the element `parray[idx]`. Each newly allocated
931
  element of the array is initialized to a null pointer. The reference
932
  returned is invalid after any other operations on the object. However,
933
  the value of the storage referred to is retained, so that until the next
934
  call to `copyfmt`, calling `pword` with the same index yields another
935
  reference to the same value. If the function fails[^9] and `*this` is a
936
- base subobject of a `basic_ios<>` object or subobject, the effect is
937
- equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
938
  object (which may throw `failure`).
939
 
940
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
941
  initialized to 0.
942
 
@@ -985,11 +1017,11 @@ member function called from within `fn` has well defined results.
985
 
986
  ``` cpp
987
  namespace std {
988
  template <class stateT> class fpos {
989
  public:
990
- // [fpos.members] Members
991
  stateT state() const;
992
  void state(stateT);
993
  private;
994
  stateT st; // exposition only
995
  };
@@ -1000,11 +1032,11 @@ namespace std {
1000
 
1001
  ``` cpp
1002
  void state(stateT s);
1003
  ```
1004
 
1005
- *Effects:* Assign `s` to `st`.
1006
 
1007
  ``` cpp
1008
  stateT state() const;
1009
  ```
1010
 
@@ -1020,14 +1052,15 @@ are permitted. In that table,
1020
  - `O` refers to type `streamoff`,
1021
  - `o` refers to a value of type `streamoff`,
1022
  - `sz` refers to a value of type `streamsize` and
1023
  - `i` refers to a value of type `int`.
1024
 
1025
- Every implementation is required to supply overloaded operators on
1026
- `fpos` objects to satisfy the requirements of  [[fpos.operations]]. It
1027
- is unspecified whether these operators are members of `fpos`, global
1028
- operators, or provided in some other way.
 
1029
 
1030
  Stream operations that return a value of type `traits::pos_type` return
1031
  `P(O(-1))` as an invalid value to signal an error. If this value is used
1032
  as an argument to any `istream`, `ostream`, or `streambuf` member that
1033
  accepts a value of type `traits::pos_type` then the behavior of that
@@ -1040,18 +1073,17 @@ function is undefined.
1040
  ``` cpp
1041
  namespace std {
1042
  template <class charT, class traits = char_traits<charT>>
1043
  class basic_ios : public ios_base {
1044
  public:
 
 
 
 
 
1045
 
1046
- // types:
1047
- typedef charT char_type;
1048
- typedef typename traits::int_type int_type;
1049
- typedef typename traits::pos_type pos_type;
1050
- typedef typename traits::off_type off_type;
1051
- typedef traits traits_type;
1052
-
1053
  explicit operator bool() const;
1054
  bool operator!() const;
1055
  iostate rdstate() const;
1056
  void clear(iostate state = goodbit);
1057
  void setstate(iostate state);
@@ -1061,15 +1093,15 @@ namespace std {
1061
  bool bad() const;
1062
 
1063
  iostate exceptions() const;
1064
  void exceptions(iostate except);
1065
 
1066
- // [basic.ios.cons] Constructor/destructor:
1067
  explicit basic_ios(basic_streambuf<charT, traits>* sb);
1068
  virtual ~basic_ios();
1069
 
1070
- // [basic.ios.members] Members:
1071
  basic_ostream<charT, traits>* tie() const;
1072
  basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
1073
 
1074
  basic_streambuf<charT, traits>* rdbuf() const;
1075
  basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
@@ -1140,11 +1172,11 @@ Table  [[tab:iostreams.basicios.init.effects]].
1140
  | `rdstate()` | `goodbit` if `sb` is not a null pointer, otherwise `badbit`. |
1141
  | `exceptions()` | `goodbit` |
1142
  | `flags()` | `skipws | dec` |
1143
  | `width()` | `0` |
1144
  | `precision()` | `6` |
1145
- | `fill()` | `widen(' ');` |
1146
  | `getloc()` | a copy of the value returned by `locale()` |
1147
  | `iarray` | a null pointer |
1148
  | `parray` | a null pointer |
1149
 
1150
 
@@ -1163,11 +1195,11 @@ basic_ostream<charT,traits>* tie(basic_ostream<charT,traits>* tiestr);
1163
 
1164
  *Requires:* If `tiestr` is not null, `tiestr` must not be reachable by
1165
  traversing the linked list of tied stream objects starting from
1166
  `tiestr->tie()`.
1167
 
1168
- `tiestr == tie()`.
1169
 
1170
  *Returns:* The previous value of `tie()`.
1171
 
1172
  ``` cpp
1173
  basic_streambuf<charT, traits>* rdbuf() const;
@@ -1177,11 +1209,11 @@ basic_streambuf<charT,traits>* rdbuf() const;
1177
 
1178
  ``` cpp
1179
  basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
1180
  ```
1181
 
1182
- `sb == rdbuf()`.
1183
 
1184
  *Effects:* Calls `clear()`.
1185
 
1186
  *Returns:* The previous value of `rdbuf()`.
1187
 
@@ -1215,11 +1247,11 @@ specified field width.
1215
 
1216
  ``` cpp
1217
  char_type fill(char_type fillch);
1218
  ```
1219
 
1220
- `traits::eq(fillch, fill())`
1221
 
1222
  *Returns:* The previous value of `fill()`.
1223
 
1224
  ``` cpp
1225
  basic_ios& copyfmt(const basic_ios& rhs);
@@ -1240,15 +1272,15 @@ follows:
1240
  stored outside the object `rhs` and those objects are destroyed
1241
  when `rhs` is destroyed, the newly stored pointer values are
1242
  altered to point at newly constructed copies of the objects;
1243
  3. calls each callback pair that was copied from `rhs` as
1244
  `(*fn)(copyfmt_event, *this, index)`;
1245
- 4. calls `exceptions(rhs.except())`.
1246
 
1247
- *Note:* The second pass through the callback pairs permits a copied
1248
  `pword` value to be zeroed, or to have its referent deep copied or
1249
- reference counted, or to have other special action taken.
1250
 
1251
  *Postconditions:* The postconditions of this function are indicated in
1252
  Table  [[tab:iostreams.copyfmt.effects]].
1253
 
1254
  **Table: `basic_ios::copyfmt()` effects** <a id="tab:iostreams.copyfmt.effects">[tab:iostreams.copyfmt.effects]</a>
@@ -1323,16 +1355,16 @@ iostate rdstate() const;
1323
 
1324
  ``` cpp
1325
  void clear(iostate state = goodbit);
1326
  ```
1327
 
1328
- If `rdbuf()!=0` then `state == rdstate()`; otherwise
1329
  `rdstate() == (state | ios_base::badbit)`.
1330
 
1331
  *Effects:* If
1332
  `((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
1333
- Otherwise, the function throws an object `fail` of class
1334
  `basic_ios::failure` ([[ios::failure]]), constructed with
1335
  *implementation-defined* argument values.
1336
 
1337
  ``` cpp
1338
  void setstate(iostate state);
@@ -1374,11 +1406,11 @@ exceptions to be thrown.
1374
 
1375
  ``` cpp
1376
  void exceptions(iostate except);
1377
  ```
1378
 
1379
- `except == exceptions()`.
1380
 
1381
  *Effects:* Calls `clear(rdstate())`.
1382
 
1383
  ### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
1384
 
@@ -1573,14 +1605,14 @@ ios_base& hexfloat(ios_base& str);
1573
  *Effects:* Calls
1574
  `str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
1575
 
1576
  *Returns:* `str`.
1577
 
1578
- The more obvious use of `ios_base::hex` to specify hexadecimal
1579
- floating-point format would change the meaning of existing well defined
1580
- programs. C++2003 gives no meaning to the combination of `fixed` and
1581
- `scientific`.
1582
 
1583
  ``` cpp
1584
  ios_base& defaultfloat(ios_base& str);
1585
  ```
1586
 
@@ -1614,18 +1646,18 @@ functions shall behave as specified for the class `error_category`. The
1614
  object’s `name` virtual function shall return a pointer to the string
1615
  `"iostream"`.
1616
 
1617
  ## Stream buffers <a id="stream.buffers">[[stream.buffers]]</a>
1618
 
1619
- ### Overview <a id="stream.buffers.overview">[[stream.buffers.overview]]</a>
1620
 
1621
  ``` cpp
1622
  namespace std {
1623
  template <class charT, class traits = char_traits<charT>>
1624
  class basic_streambuf;
1625
- typedef basic_streambuf<char> streambuf;
1626
- typedef basic_streambuf<wchar_t> wstreambuf;
1627
  }
1628
  ```
1629
 
1630
  The header `<streambuf>` defines types that control input from and
1631
  output to *character* sequences.
@@ -1679,123 +1711,121 @@ above:
1679
  - If `xnext` is not a null pointer and `xnext < xend` for an input
1680
  sequence, then a *read position* is available. In this case, `*xnext`
1681
  shall have a defined value and is the next element to read (to get, or
1682
  to obtain a character value, from the sequence).
1683
 
1684
- ### Class template `basic_streambuf<charT,traits>` <a id="streambuf">[[streambuf]]</a>
1685
 
1686
  ``` cpp
1687
  namespace std {
1688
  template <class charT, class traits = char_traits<charT>>
1689
  class basic_streambuf {
1690
  public:
1691
-
1692
- // types:
1693
- typedef charT char_type;
1694
- typedef typename traits::int_type int_type;
1695
- typedef typename traits::pos_type pos_type;
1696
- typedef typename traits::off_type off_type;
1697
- typedef traits traits_type;
1698
 
1699
  virtual ~basic_streambuf();
1700
 
1701
- // [streambuf.locales] locales:
1702
  locale pubimbue(const locale& loc);
1703
  locale getloc() const;
1704
 
1705
- // [streambuf.buffer] buffer and positioning:
1706
- basic_streambuf<char_type,traits>*
1707
- pubsetbuf(char_type* s, streamsize n);
1708
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
1709
- ios_base::openmode which =
1710
- ios_base::in | ios_base::out);
1711
  pos_type pubseekpos(pos_type sp,
1712
- ios_base::openmode which =
1713
- ios_base::in | ios_base::out);
1714
  int pubsync();
1715
 
1716
- // Get and put areas:
1717
- // [streambuf.pub.get] Get area:
1718
  streamsize in_avail();
1719
  int_type snextc();
1720
  int_type sbumpc();
1721
  int_type sgetc();
1722
  streamsize sgetn(char_type* s, streamsize n);
1723
 
1724
- // [streambuf.pub.pback] Putback:
1725
  int_type sputbackc(char_type c);
1726
  int_type sungetc();
1727
 
1728
- // [streambuf.pub.put] Put area:
1729
  int_type sputc(char_type c);
1730
  streamsize sputn(const char_type* s, streamsize n);
1731
 
1732
  protected:
1733
  basic_streambuf();
1734
  basic_streambuf(const basic_streambuf& rhs);
1735
  basic_streambuf& operator=(const basic_streambuf& rhs);
1736
 
1737
  void swap(basic_streambuf& rhs);
1738
 
1739
- // [streambuf.get.area] Get area:
1740
  char_type* eback() const;
1741
  char_type* gptr() const;
1742
  char_type* egptr() const;
1743
  void gbump(int n);
1744
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
1745
 
1746
- // [streambuf.put.area] Put area:
1747
  char_type* pbase() const;
1748
  char_type* pptr() const;
1749
  char_type* epptr() const;
1750
  void pbump(int n);
1751
  void setp(char_type* pbeg, char_type* pend);
1752
 
1753
- // [streambuf.virtuals] virtual functions:
1754
- // [streambuf.virt.locales] Locales:
1755
  virtual void imbue(const locale& loc);
1756
 
1757
- // [streambuf.virt.buffer] Buffer management and positioning:
1758
- virtual basic_streambuf<char_type,traits>*
1759
- setbuf(char_type* s, streamsize n);
1760
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
1761
- ios_base::openmode which = ios_base::in | ios_base::out);
 
1762
  virtual pos_type seekpos(pos_type sp,
1763
- ios_base::openmode which = ios_base::in | ios_base::out);
 
1764
  virtual int sync();
1765
 
1766
- // [streambuf.virt.get] Get area:
1767
  virtual streamsize showmanyc();
1768
  virtual streamsize xsgetn(char_type* s, streamsize n);
1769
  virtual int_type underflow();
1770
  virtual int_type uflow();
1771
 
1772
- // [streambuf.virt.pback] Putback:
1773
  virtual int_type pbackfail(int_type c = traits::eof());
1774
 
1775
- // [streambuf.virt.put] Put area:
1776
  virtual streamsize xsputn(const char_type* s, streamsize n);
1777
  virtual int_type overflow(int_type c = traits::eof());
1778
  };
1779
  }
1780
  ```
1781
 
1782
- The class template `basic_streambuf<charT,traits>` serves as an abstract
1783
- base class for deriving various *stream buffers* whose objects each
1784
- control two *character sequences*:
1785
 
1786
  - a character *input sequence*;
1787
  - a character *output sequence*.
1788
 
1789
  #### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
1790
 
1791
  ``` cpp
1792
  basic_streambuf();
1793
  ```
1794
 
1795
- *Effects:* Constructs an object of class `basic_streambuf<charT,traits>`
1796
- and initializes:[^13]
1797
 
1798
  - all its pointer member objects to null pointers,
1799
  - the `getloc()` member to a copy the global locale, `locale()`, at the
1800
  time of construction.
1801
 
@@ -1831,11 +1861,11 @@ basic_streambuf(const basic_streambuf& rhs);
1831
 
1832
  ``` cpp
1833
  locale pubimbue(const locale& loc);
1834
  ```
1835
 
1836
- `loc == getloc()`.
1837
 
1838
  *Effects:* Calls `imbue(loc)`.
1839
 
1840
  *Returns:* Previous value of `getloc()`.
1841
 
@@ -1850,25 +1880,27 @@ been called but before `pubimbue` has returned (i.e., from within the
1850
  call of `imbue()`) then it returns the previous value.
1851
 
1852
  ##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
1853
 
1854
  ``` cpp
1855
- basic_streambuf<char_type,traits>* pubsetbuf(char_type* s, streamsize n);
1856
  ```
1857
 
1858
  *Returns:* `setbuf(s, n)`.
1859
 
1860
  ``` cpp
1861
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
1862
- ios_base::openmode which = ios_base::in | ios_base::out);
 
1863
  ```
1864
 
1865
  *Returns:* `seekoff(off, way, which)`.
1866
 
1867
  ``` cpp
1868
  pos_type pubseekpos(pos_type sp,
1869
- ios_base::openmode which = ios_base::in | ios_base::out);
 
1870
  ```
1871
 
1872
  *Returns:* `seekpos(sp, which)`.
1873
 
1874
  ``` cpp
@@ -1921,11 +1953,11 @@ streamsize sgetn(char_type* s, streamsize n);
1921
  ``` cpp
1922
  int_type sputbackc(char_type c);
1923
  ```
1924
 
1925
  *Returns:* If the input sequence putback position is not available, or
1926
- if `traits::eq(c,gptr()[-1])` is false, returns
1927
  `pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
1928
  pointer for the input sequence and returns
1929
  `traits::to_int_type(*gptr())`.
1930
 
1931
  ``` cpp
@@ -2109,12 +2141,12 @@ int sync();
2109
  *Effects:* Synchronizes the controlled sequences with the arrays. That
2110
  is, if `pbase()` is non-null the characters between `pbase()` and
2111
  `pptr()` are written to the controlled sequence. The pointers may then
2112
  be reset as appropriate.
2113
 
2114
- *Returns:* -1 on failure. What constitutes failure is determined by each
2115
- derived class ([[filebuf.virtuals]]).
2116
 
2117
  *Default behavior:* Returns zero.
2118
 
2119
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
2120
 
@@ -2158,22 +2190,38 @@ function only if `gptr()` is null or `gptr() >= egptr()`
2158
  *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
2159
  of the *pending sequence*, without moving the input sequence position
2160
  past it. If the pending sequence is null then the function returns
2161
  `traits::eof()` to indicate failure.
2162
 
2163
- The *pending sequence* of characters is defined as the concatenation of:
2164
 
2165
- The *result character* is
 
 
 
2166
 
2167
- The *backup sequence* is defined as the concatenation of:
 
 
2168
 
2169
- *Effects:* The function sets up the `gptr()` and `egptr()` satisfying
2170
- one of:
 
 
 
 
 
2171
 
2172
  If `eback()` and `gptr()` are non-null then the function is not
2173
  constrained as to their contents, but the “usual backup condition” is
2174
- that either:
 
 
 
 
 
 
2175
 
2176
  *Default behavior:* Returns `traits::eof()`.
2177
 
2178
  ``` cpp
2179
  int_type uflow();
@@ -2206,16 +2254,16 @@ The *pending sequence* is defined as for `underflow()`, with the
2206
  modifications that
2207
 
2208
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
2209
  input sequence is backed up one character before the pending sequence
2210
  is determined.
2211
- - If `traits::eq_int_type(c,traits::eof())` returns `false`, then `c` is
2212
- prepended. Whether the input sequence is backed up or modified in any
2213
- other way is unspecified.
2214
 
2215
- On return, the constraints of `gptr()`, `eback()`, and `pptr()` are the
2216
- same as for `underflow()`.
2217
 
2218
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
2219
  because the input sequence could not be backed up, or if for some other
2220
  reason the pointers could not be set consistent with the constraints.
2221
  `pbackfail()` is called only when put back has really failed.
@@ -2232,13 +2280,13 @@ streamsize xsputn(const char_type* s, streamsize n);
2232
 
2233
  *Effects:* Writes up to `n` characters to the output sequence as if by
2234
  repeated calls to `sputc(c)`. The characters written are obtained from
2235
  successive elements of the array whose first element is designated by
2236
  `s`. Writing stops when either `n` characters have been written or a
2237
- call to `sputc(c)` would return `traits::eof()`. Is is unspecified
2238
  whether the function calls `overflow()` when `pptr() == epptr()` becomes
2239
- true or whether it achieves the same effects by other means.
2240
 
2241
  *Returns:* The number of characters written.
2242
 
2243
  ``` cpp
2244
  int_type overflow(int_type c = traits::eof());
@@ -2246,71 +2294,92 @@ int_type overflow(int_type c = traits::eof());
2246
 
2247
  *Effects:* Consumes some initial subsequence of the characters of the
2248
  *pending sequence*. The pending sequence is defined as the concatenation
2249
  of
2250
 
 
 
 
 
 
2251
  *Remarks:* The member functions `sputc()` and `sputn()` call this
2252
  function in case that no room can be found in the put buffer enough to
2253
  accommodate the argument character sequence.
2254
 
2255
  *Requires:* Every overriding definition of this virtual function shall
2256
  obey the following constraints:
2257
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2258
  *Returns:* `traits::eof()` or throws an exception if the function fails.
2259
 
2260
  Otherwise, returns some value other than `traits::eof()` to indicate
2261
- success.[^16]
2262
 
2263
  *Default behavior:* Returns `traits::eof()`.
2264
 
2265
  ## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
2266
 
2267
- ### Overview <a id="iostream.format.overview">[[iostream.format.overview]]</a>
2268
-
2269
- \synopsis{Header \texttt{\<istream\>} synopsis}
2270
 
2271
  ``` cpp
2272
  namespace std {
2273
  template <class charT, class traits = char_traits<charT>>
2274
  class basic_istream;
2275
- typedef basic_istream<char> istream;
2276
- typedef basic_istream<wchar_t> wistream;
 
2277
 
2278
  template <class charT, class traits = char_traits<charT>>
2279
  class basic_iostream;
2280
- typedef basic_iostream<char> iostream;
2281
- typedef basic_iostream<wchar_t> wiostream;
 
2282
 
2283
  template <class charT, class traits>
2284
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
2285
 
2286
  template <class charT, class traits, class T>
2287
- basic_istream<charT, traits>&
2288
- operator>>(basic_istream<charT, traits>&& is, T& x);
2289
  }
2290
  ```
2291
 
 
 
2292
  ``` cpp
2293
  namespace std {
2294
  template <class charT, class traits = char_traits<charT>>
2295
  class basic_ostream;
2296
- typedef basic_ostream<char> ostream;
2297
- typedef basic_ostream<wchar_t> wostream;
 
2298
 
2299
  template <class charT, class traits>
2300
  basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
2301
  template <class charT, class traits>
2302
  basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
2303
  template <class charT, class traits>
2304
  basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
2305
 
2306
  template <class charT, class traits, class T>
2307
- basic_ostream<charT, traits>&
2308
- operator<<(basic_ostream<charT, traits>&& os, const T& x);
2309
  }
2310
  ```
2311
 
 
 
2312
  ``` cpp
2313
  namespace std {
2314
  // types T1, T2, ... are unspecified implementation types
2315
  T1 resetiosflags(ios_base::fmtflags mask);
2316
  T2 setiosflags (ios_base::fmtflags mask);
@@ -2326,15 +2395,19 @@ namespace std {
2326
  template <class charT>
2327
  T11 quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
2328
 
2329
  template <class charT, class traits, class Allocator>
2330
  T12 quoted(const basic_string<charT, traits, Allocator>& s,
2331
- charT delim=charT('"'), charT escape=charT('\\'));
2332
 
2333
  template <class charT, class traits, class Allocator>
2334
  T13 quoted(basic_string<charT, traits, Allocator>& s,
2335
- charT delim=charT('"'), charT escape=charT('\\'));
 
 
 
 
2336
  }
2337
  ```
2338
 
2339
  ### Input streams <a id="input.streams">[[input.streams]]</a>
2340
 
@@ -2348,30 +2421,30 @@ extracts from stream rvalues.
2348
  namespace std {
2349
  template <class charT, class traits = char_traits<charT>>
2350
  class basic_istream : virtual public basic_ios<charT, traits> {
2351
  public:
2352
  // types (inherited from basic_ios ([ios])):
2353
- typedef charT char_type;
2354
- typedef typename traits::int_type int_type;
2355
- typedef typename traits::pos_type pos_type;
2356
- typedef typename traits::off_type off_type;
2357
- typedef traits traits_type;
2358
 
2359
- // [istream.cons] Constructor/destructor:
2360
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2361
  virtual ~basic_istream();
2362
 
2363
- // [istream::sentry] Prefix/suffix:
2364
  class sentry;
2365
 
2366
- // [istream.formatted] Formatted input:
2367
- basic_istream<charT,traits>& operator>>(
2368
- basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&));
2369
- basic_istream<charT,traits>& operator>>(
2370
- basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
2371
- basic_istream<charT,traits>& operator>>(
2372
- ios_base& (*pf)(ios_base&));
2373
 
2374
  basic_istream<charT, traits>& operator>>(bool& n);
2375
  basic_istream<charT, traits>& operator>>(short& n);
2376
  basic_istream<charT, traits>& operator>>(unsigned short& n);
2377
  basic_istream<charT, traits>& operator>>(int& n);
@@ -2383,30 +2456,25 @@ namespace std {
2383
  basic_istream<charT, traits>& operator>>(float& f);
2384
  basic_istream<charT, traits>& operator>>(double& f);
2385
  basic_istream<charT, traits>& operator>>(long double& f);
2386
 
2387
  basic_istream<charT, traits>& operator>>(void*& p);
2388
- basic_istream<charT,traits>& operator>>(
2389
- basic_streambuf<char_type,traits>* sb);
2390
 
2391
- // [istream.unformatted] Unformatted input:
2392
  streamsize gcount() const;
2393
  int_type get();
2394
  basic_istream<charT, traits>& get(char_type& c);
2395
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
2396
- basic_istream<charT,traits>& get(char_type* s, streamsize n,
2397
- char_type delim);
2398
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
2399
- basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb,
2400
- char_type delim);
2401
 
2402
  basic_istream<charT, traits>& getline(char_type* s, streamsize n);
2403
- basic_istream<charT,traits>& getline(char_type* s, streamsize n,
2404
- char_type delim);
2405
 
2406
- basic_istream<charT,traits>& ignore(
2407
- streamsize n = 1, int_type delim = traits::eof());
2408
  int_type peek();
2409
  basic_istream<charT, traits>& read (char_type* s, streamsize n);
2410
  streamsize readsome(char_type* s, streamsize n);
2411
 
2412
  basic_istream<charT, traits>& putback(char_type c);
@@ -2416,45 +2484,40 @@ namespace std {
2416
  pos_type tellg();
2417
  basic_istream<charT, traits>& seekg(pos_type);
2418
  basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
2419
 
2420
  protected:
 
2421
  basic_istream(const basic_istream& rhs) = delete;
2422
  basic_istream(basic_istream&& rhs);
2423
 
2424
- // [istream.assign] Assign/swap:
2425
  basic_istream& operator=(const basic_istream& rhs) = delete;
2426
  basic_istream& operator=(basic_istream&& rhs);
2427
  void swap(basic_istream& rhs);
2428
  };
2429
 
2430
- // [istream::extractors] character extraction templates:
2431
  template<class charT, class traits>
2432
- basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&,
2433
- charT&);
2434
  template<class traits>
2435
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
2436
- unsigned char&);
2437
  template<class traits>
2438
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
2439
- signed char&);
2440
 
2441
  template<class charT, class traits>
2442
- basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&,
2443
- charT*);
2444
  template<class traits>
2445
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
2446
- unsigned char*);
2447
  template<class traits>
2448
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
2449
- signed char*);
2450
  }
2451
  ```
2452
 
2453
- The class `basic_istream` defines a number of member function signatures
2454
- that assist in reading and interpreting input from sequences controlled
2455
- by a stream buffer.
2456
 
2457
  Two groups of member function signatures share common properties: the
2458
  *formatted input functions* (or *extractors*) and the *unformatted input
2459
  functions.* Both groups of input functions are described as if they
2460
  obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
@@ -2476,15 +2539,15 @@ failure indication.
2476
 
2477
  ``` cpp
2478
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2479
  ```
2480
 
2481
- *Effects:* Constructs an object of class `basic_istream`, assigning
2482
- initial values to the base class by calling
2483
  `basic_ios::init(sb)` ([[basic.ios.cons]]).
2484
 
2485
- `gcount() == 0`
2486
 
2487
  ``` cpp
2488
  basic_istream(basic_istream&& rhs);
2489
  ```
2490
 
@@ -2505,11 +2568,11 @@ virtual ~basic_istream();
2505
 
2506
  ``` cpp
2507
  basic_istream& operator=(basic_istream&& rhs);
2508
  ```
2509
 
2510
- *Effects:* `swap(rhs);`.
2511
 
2512
  *Returns:* `*this`.
2513
 
2514
  ``` cpp
2515
  void swap(basic_istream& rhs);
@@ -2522,11 +2585,11 @@ values returned by `gcount()` and `rhs.gcount()`.
2522
 
2523
  ``` cpp
2524
  namespace std {
2525
  template <class charT, class traits = char_traits<charT>>
2526
  class basic_istream<charT, traits>::sentry {
2527
- typedef traits traits_type;
2528
  bool ok_; // exposition only
2529
  public:
2530
  explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
2531
  ~sentry();
2532
  explicit operator bool() const { return ok_; }
@@ -2549,19 +2612,23 @@ Otherwise, prepares for formatted or unformatted input. First, if
2549
  to synchronize the output sequence with any associated external C
2550
  stream. Except that this call can be suppressed if the put area of
2551
  `is.tie()` is empty. Further an implementation is allowed to defer the
2552
  call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
2553
  such call occurs before the `sentry` object is destroyed, the call to
2554
- `flush` may be eliminated entirely.[^17] If `noskipws` is zero and
2555
  `is.flags() & ios_base::skipws` is nonzero, the function extracts and
2556
  discards each character as long as the next available input character
2557
  `c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
2558
  `is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
2559
  `setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
2560
 
2561
  *Remarks:* The constructor
2562
- `explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false)`
 
 
 
 
2563
  uses the currently imbued locale in `is`, to determine whether the next
2564
  input character is whitespace or not.
2565
 
2566
  To decide if the character `c` is a whitespace character, the
2567
  constructor performs as if it executes the following code fragment:
@@ -2573,11 +2640,11 @@ if (ctype.is(ctype.space,c)!=0)
2573
  ```
2574
 
2575
  If, after any preparation is completed, `is.good()` is `true`,
2576
  `ok_ != false` otherwise, `ok_ == false`. During preparation, the
2577
  constructor may call `setstate(failbit)` (which may throw
2578
- `ios_base::failure` ([[iostate.flags]]))[^18]
2579
 
2580
  ``` cpp
2581
  ~sentry();
2582
  ```
2583
 
@@ -2595,11 +2662,11 @@ explicit operator bool() const;
2595
 
2596
  Each formatted input function begins execution by constructing an object
2597
  of class `sentry` with the `noskipws` (second) argument `false`. If the
2598
  `sentry` object returns `true`, when converted to a value of type
2599
  `bool`, the function endeavors to obtain the requested input. If an
2600
- exception is thrown during input then `ios::badbit` is turned on[^19] in
2601
  `*this`’s error state. If `(exceptions()&badbit) != 0` then the
2602
  exception is rethrown. In any case, the formatted input function
2603
  destroys the `sentry` object. If no exception has been thrown, it
2604
  returns `*this`.
2605
 
@@ -2625,32 +2692,36 @@ stream data. These extractors behave as formatted input functions (as
2625
  described in  [[istream.formatted.reqmts]]). After a sentry object is
2626
  constructed, the conversion occurs as if performed by the following code
2627
  fragment:
2628
 
2629
  ``` cpp
2630
- typedef num_get< charT,istreambuf_iterator<charT,traits> > numget;
2631
  iostate err = iostate::goodbit;
2632
  use_facet<numget>(loc).get(*this, 0, *this, err, val);
2633
  setstate(err);
2634
  ```
2635
 
2636
  In the above fragment, `loc` stands for the private member of the
2637
- `basic_ios` class. The first argument provides an object of the
 
 
2638
  `istreambuf_iterator` class which is an iterator pointed to an input
2639
- stream. It bypasses istreams and uses streambufs directly. Class
2640
- `locale` relies on this type as its interface to `istream`, so that it
2641
- does not need to depend directly on `istream`.
 
 
2642
 
2643
  ``` cpp
2644
  operator>>(short& val);
2645
  ```
2646
 
2647
  The conversion occurs as if performed by the following code fragment
2648
  (using the same notation as for the preceding code fragment):
2649
 
2650
  ``` cpp
2651
- typedef num_get<charT,istreambuf_iterator<charT,traits> > numget;
2652
  iostate err = ios_base::goodbit;
2653
  long lval;
2654
  use_facet<numget>(loc).get(*this, 0, *this, err, lval);
2655
  if (lval < numeric_limits<short>::min()) {
2656
  err |= ios_base::failbit;
@@ -2669,11 +2740,11 @@ operator>>(int& val);
2669
 
2670
  The conversion occurs as if performed by the following code fragment
2671
  (using the same notation as for the preceding code fragment):
2672
 
2673
  ``` cpp
2674
- typedef num_get<charT,istreambuf_iterator<charT,traits> > numget;
2675
  iostate err = ios_base::goodbit;
2676
  long lval;
2677
  use_facet<numget>(loc).get(*this, 0, *this, err, lval);
2678
  if (lval < numeric_limits<int>::min()) {
2679
  err |= ios_base::failbit;
@@ -2684,54 +2755,50 @@ if (lval < numeric_limits<int>::min()) {
2684
  } else
2685
  val = static_cast<int>(lval);
2686
  setstate(err);
2687
  ```
2688
 
2689
- ##### `basic_istream::operator>>` <a id="istream::extractors">[[istream::extractors]]</a>
2690
 
2691
  ``` cpp
2692
- basic_istream<charT,traits>& operator>>
2693
- (basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&));
2694
  ```
2695
 
2696
  *Effects:* None. This extractor does not behave as a formatted input
2697
- function (as described in  [[istream.formatted.reqmts]].)
2698
 
2699
- *Returns:* `pf(*this)`.[^20]
2700
 
2701
  ``` cpp
2702
- basic_istream<charT,traits>& operator>>
2703
- (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
2704
  ```
2705
 
2706
  *Effects:* Calls `pf(*this)`. This extractor does not behave as a
2707
  formatted input function (as described
2708
  in  [[istream.formatted.reqmts]]).
2709
 
2710
  *Returns:* `*this`.
2711
 
2712
  ``` cpp
2713
- basic_istream<charT,traits>& operator>>
2714
- (ios_base& (*pf)(ios_base&));
2715
  ```
2716
 
2717
- *Effects:* Calls `pf(*this)`.[^21] This extractor does not behave as a
2718
  formatted input function (as described
2719
  in  [[istream.formatted.reqmts]]).
2720
 
2721
  *Returns:* `*this`.
2722
 
2723
  ``` cpp
2724
  template<class charT, class traits>
2725
- basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>& in,
2726
- charT* s);
2727
  template<class traits>
2728
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
2729
- unsigned char* s);
2730
  template<class traits>
2731
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
2732
- signed char* s);
2733
  ```
2734
 
2735
  *Effects:* Behaves like a formatted input member (as described
2736
  in  [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
2737
  constructed, `operator>>` extracts characters and stores them into
@@ -2743,12 +2810,12 @@ stored.
2743
 
2744
  Characters are extracted and stored until any of the following occurs:
2745
 
2746
  - `n-1` characters are stored;
2747
  - end of file occurs on the input sequence;
2748
- - `ct.is(ct.space,c)` is `true` for the next available input character
2749
- `c`, where `ct` is `use_facet<ctype<charT> >(in.getloc())`.
2750
 
2751
  `operator>>` then stores a null byte (`charT()`) in the next position,
2752
  which may be the first position if no characters were extracted.
2753
  `operator>>` then calls `width(0)`.
2754
 
@@ -2757,38 +2824,33 @@ which may throw `ios_base::failure` ([[iostate.flags]]).
2757
 
2758
  *Returns:* `in`.
2759
 
2760
  ``` cpp
2761
  template<class charT, class traits>
2762
- basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>& in,
2763
- charT& c);
2764
  template<class traits>
2765
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
2766
- unsigned char& c);
2767
  template<class traits>
2768
- basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
2769
- signed char& c);
2770
  ```
2771
 
2772
  *Effects:* Behaves like a formatted input member (as described
2773
  in  [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
2774
  constructed a character is extracted from `in`, if one is available, and
2775
  stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
2776
 
2777
  *Returns:* `in`.
2778
 
2779
  ``` cpp
2780
- basic_istream<charT,traits>& operator>>
2781
- (basic_streambuf<charT,traits>* sb);
2782
  ```
2783
 
2784
- *Effects:* Behaves as an unformatted input function (as described
2785
- in  [[istream.unformatted]], paragraph 1). If `sb` is null, calls
2786
- `setstate(failbit)`, which may throw
2787
- `ios_base::failure` ([[iostate.flags]]). After a sentry object is
2788
- constructed, extracts characters from `*this` and inserts them in the
2789
- output sequence controlled by `sb`. Characters are extracted and
2790
  inserted until any of the following occurs:
2791
 
2792
  - end-of-file occurs on the input sequence;
2793
  - inserting in the output sequence fails (in which case the character to
2794
  be inserted is not extracted);
@@ -2808,18 +2870,18 @@ rethrown.
2808
  Each unformatted input function begins execution by constructing an
2809
  object of class `sentry` with the default argument `noskipws` (second)
2810
  argument `true`. If the `sentry` object returns `true`, when converted
2811
  to a value of type `bool`, the function endeavors to obtain the
2812
  requested input. Otherwise, if the sentry constructor exits by throwing
2813
- an exception or if the sentry object returns false, when converted to a
2814
- value of type `bool`, the function returns without attempting to obtain
2815
- any input. In either case the number of extracted characters is set to
2816
- 0; unformatted input functions taking a character array of non-zero size
2817
- as an argument shall also store a null character (using `charT()`) in
2818
- the first location of the array. If an exception is thrown during input
2819
- then `ios::badbit` is turned on[^22] in `*this`’s error state.
2820
- (Exceptions thrown from `basic_ios<>::clear()` are not caught or
2821
  rethrown.) If `(exceptions()&badbit) != 0` then the exception is
2822
  rethrown. It also counts the number of characters extracted. If no
2823
  exception has been thrown it ends by storing the count in a member
2824
  object and returning the value specified. In any event the `sentry`
2825
  object is destroyed before leaving the unformatted input function.
@@ -2827,49 +2889,47 @@ object is destroyed before leaving the unformatted input function.
2827
  ``` cpp
2828
  streamsize gcount() const;
2829
  ```
2830
 
2831
  *Effects:* None. This member function does not behave as an unformatted
2832
- input function (as described in  [[istream.unformatted]], paragraph 1).
2833
 
2834
  *Returns:* The number of characters extracted by the last unformatted
2835
  input member function called for the object.
2836
 
2837
  ``` cpp
2838
  int_type get();
2839
  ```
2840
 
2841
  *Effects:* Behaves as an unformatted input function (as described
2842
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
2843
- object, extracts a character `c`, if one is available. Otherwise, the
2844
- function calls `setstate(failbit)`, which may throw
2845
- `ios_base::failure` ([[iostate.flags]]),
2846
 
2847
  *Returns:* `c` if available, otherwise `traits::eof()`.
2848
 
2849
  ``` cpp
2850
  basic_istream<charT, traits>& get(char_type& c);
2851
  ```
2852
 
2853
  *Effects:* Behaves as an unformatted input function (as described
2854
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
2855
- object, extracts a character, if one is available, and assigns it to
2856
- `c`.[^23] Otherwise, the function calls `setstate(failbit)` (which may
2857
- throw `ios_base::failure` ([[iostate.flags]])).
2858
 
2859
  *Returns:* `*this`.
2860
 
2861
  ``` cpp
2862
- basic_istream<charT,traits>& get(char_type* s, streamsize n,
2863
- char_type delim );
2864
  ```
2865
 
2866
  *Effects:* Behaves as an unformatted input function (as described
2867
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
2868
- object, extracts characters and stores them into successive locations of
2869
- an array whose first element is designated by `s`.[^24] Characters are
2870
- extracted and stored until any of the following occurs:
2871
 
2872
  - `n` is less than one or `n - 1` characters are stored;
2873
  - end-of-file occurs on the input sequence (in which case the function
2874
  calls `setstate(eofbit)`);
2875
  - `traits::eq(c, delim)` for the next available input character `c` (in
@@ -2884,24 +2944,22 @@ next successive location of the array.
2884
 
2885
  ``` cpp
2886
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
2887
  ```
2888
 
2889
- *Effects:* Calls `get(s,n,widen(’\n’))`
2890
 
2891
  *Returns:* Value returned by the call.
2892
 
2893
  ``` cpp
2894
- basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb,
2895
- char_type delim );
2896
  ```
2897
 
2898
  *Effects:* Behaves as an unformatted input function (as described
2899
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
2900
- object, extracts characters and inserts them in the output sequence
2901
- controlled by `sb`. Characters are extracted and inserted until any of
2902
- the following occurs:
2903
 
2904
  - end-of-file occurs on the input sequence;
2905
  - inserting in the output sequence fails (in which case the character to
2906
  be inserted is not extracted);
2907
  - `traits::eq(c, delim)` for the next available input character `c` (in
@@ -2916,44 +2974,45 @@ which may throw `ios_base::failure` ([[iostate.flags]]).
2916
 
2917
  ``` cpp
2918
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
2919
  ```
2920
 
2921
- *Effects:* Calls `get(sb, widen(’\n’))`
2922
 
2923
  *Returns:* Value returned by the call.
2924
 
2925
  ``` cpp
2926
- basic_istream<charT,traits>& getline(char_type* s, streamsize n,
2927
- char_type delim);
2928
  ```
2929
 
2930
  *Effects:* Behaves as an unformatted input function (as described
2931
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
2932
- object, extracts characters and stores them into successive locations of
2933
- an array whose first element is designated by `s`.[^25] Characters are
2934
- extracted and stored until one of the following occurs:
2935
 
2936
  1. end-of-file occurs on the input sequence (in which case the function
2937
  calls `setstate(eofbit)`);
2938
  2. `traits::eq(c, delim)` for the next available input character `c`
2939
  (in which case the input character is extracted but not
2940
- stored);[^26]
2941
  3. `n` is less than one or `n - 1` characters are stored (in which case
2942
  the function calls `setstate(failbit)`).
2943
 
2944
- These conditions are tested in the order shown.[^27]
2945
 
2946
  If the function extracts no characters, it calls `setstate(failbit)`
2947
- (which may throw `ios_base::failure` ([[iostate.flags]])).[^28]
2948
 
2949
  In any case, if `n` is greater than zero, it then stores a null
2950
  character (using `charT()`) into the next successive location of the
2951
  array.
2952
 
2953
  *Returns:* `*this`.
2954
 
 
 
2955
  ``` cpp
2956
  #include <iostream>
2957
 
2958
  int main() {
2959
  using namespace std;
@@ -2975,27 +3034,28 @@ int main() {
2975
  cout << " (" << count << " chars): " << buffer << endl;
2976
  }
2977
  }
2978
  ```
2979
 
 
 
2980
  ``` cpp
2981
  basic_istream<charT, traits>& getline(char_type* s, streamsize n);
2982
  ```
2983
 
2984
  *Returns:* `getline(s, n, widen(’\n’))`
2985
 
2986
  ``` cpp
2987
- basic_istream<charT,traits>&
2988
- ignore(streamsize n = 1, int_type delim = traits::eof());
2989
  ```
2990
 
2991
  *Effects:* Behaves as an unformatted input function (as described
2992
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
2993
- object, extracts characters and discards them. Characters are extracted
2994
- until any of the following occurs:
2995
 
2996
- - `n != numeric_limits<streamsize>::max()` ([[limits]]) and `n`
2997
  characters have been extracted so far
2998
  - end-of-file occurs on the input sequence (in which case the function
2999
  calls `setstate(eofbit)`, which may throw
3000
  `ios_base::failure` ([[iostate.flags]]));
3001
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
@@ -3009,27 +3069,26 @@ until any of the following occurs:
3009
  ``` cpp
3010
  int_type peek();
3011
  ```
3012
 
3013
  *Effects:* Behaves as an unformatted input function (as described
3014
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
3015
- object, reads but does not extract the current input character.
3016
 
3017
  *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
3018
  `rdbuf()->sgetc()`.
3019
 
3020
  ``` cpp
3021
  basic_istream<charT, traits>& read(char_type* s, streamsize n);
3022
  ```
3023
 
3024
  *Effects:* Behaves as an unformatted input function (as described
3025
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
3026
- object, if `!good()` calls `setstate(failbit)` which may throw an
3027
- exception, and return. Otherwise extracts characters and stores them
3028
- into successive locations of an array whose first element is designated
3029
- by `s`.[^29] Characters are extracted and stored until either of the
3030
- following occurs:
3031
 
3032
  - `n` characters are stored;
3033
  - end-of-file occurs on the input sequence (in which case the function
3034
  calls `setstate(failbit | eofbit)`, which may throw
3035
  `ios_base::failure` ([[iostate.flags]])).
@@ -3039,17 +3098,16 @@ following occurs:
3039
  ``` cpp
3040
  streamsize readsome(char_type* s, streamsize n);
3041
  ```
3042
 
3043
  *Effects:* Behaves as an unformatted input function (as described
3044
- in  [[istream.unformatted]], paragraph 1). After constructing a sentry
3045
- object, if `!good()` calls `setstate(failbit)` which may throw an
3046
- exception, and return. Otherwise extracts characters and stores them
3047
- into successive locations of an array whose first element is designated
3048
- by `s`. If `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which
3049
- may throw `ios_base::failure` ([[iostate.flags]])), and extracts no
3050
- characters;
3051
 
3052
  - If `rdbuf()->in_avail() == 0`, extracts no characters
3053
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
3054
 
3055
  *Returns:* The number of characters extracted.
@@ -3057,86 +3115,87 @@ characters;
3057
  ``` cpp
3058
  basic_istream<charT, traits>& putback(char_type c);
3059
  ```
3060
 
3061
  *Effects:* Behaves as an unformatted input function (as described
3062
- in  [[istream.unformatted]], paragraph 1), except that the function
3063
- first clears `eofbit`. After constructing a sentry object, if `!good()`
3064
- calls `setstate(failbit)` which may throw an exception, and return. If
3065
- `rdbuf()` is not null, calls `rdbuf->sputbackc()`. If `rdbuf()` is null,
3066
- or if `sputbackc()` returns `traits::eof()`, calls `setstate(badbit)`
3067
- (which may throw `ios_base::failure` ([[iostate.flags]])). This
3068
- function extracts no characters, so the value returned by the next call
3069
- to `gcount()` is 0.
 
3070
 
3071
  *Returns:* `*this`.
3072
 
3073
  ``` cpp
3074
  basic_istream<charT, traits>& unget();
3075
  ```
3076
 
3077
  *Effects:* Behaves as an unformatted input function (as described
3078
- in  [[istream.unformatted]], paragraph 1), except that the function
3079
- first clears `eofbit`. After constructing a sentry object, if `!good()`
3080
- calls `setstate(failbit)` which may throw an exception, and return. If
3081
- `rdbuf()` is not null, calls `rdbuf()->sungetc()`. If `rdbuf()` is null,
3082
- or if `sungetc()` returns `traits::eof()`, calls `setstate(badbit)`
3083
- (which may throw `ios_base::failure` ([[iostate.flags]])). This
3084
- function extracts no characters, so the value returned by the next call
3085
- to `gcount()` is 0.
 
3086
 
3087
  *Returns:* `*this`.
3088
 
3089
  ``` cpp
3090
  int sync();
3091
  ```
3092
 
3093
  *Effects:* Behaves as an unformatted input function (as described
3094
- in  [[istream.unformatted]], paragraph 1), except that it does not count
3095
- the number of characters extracted and does not affect the value
3096
- returned by subsequent calls to `gcount()`. After constructing a sentry
3097
- object, if `rdbuf()` is a null pointer, returns -1 . Otherwise, calls
3098
- `rdbuf()->pubsync()` and, if that function returns -1 calls
3099
- `setstate(badbit)` (which may throw
3100
  `ios_base::failure` ([[iostate.flags]]), and returns `-1`. Otherwise,
3101
  returns zero.
3102
 
3103
  ``` cpp
3104
  pos_type tellg();
3105
  ```
3106
 
3107
  *Effects:* Behaves as an unformatted input function (as described
3108
- in  [[istream.unformatted]], paragraph 1), except that it does not count
3109
- the number of characters extracted and does not affect the value
3110
- returned by subsequent calls to `gcount()`.
3111
 
3112
  *Returns:* After constructing a sentry object, if `fail() != false`,
3113
  returns `pos_type(-1)` to indicate failure. Otherwise, returns
3114
  `rdbuf()->pubseekoff(0, cur, in)`.
3115
 
3116
  ``` cpp
3117
  basic_istream<charT, traits>& seekg(pos_type pos);
3118
  ```
3119
 
3120
  *Effects:* Behaves as an unformatted input function (as described
3121
- in  [[istream.unformatted]], paragraph 1), except that the function
3122
- first clears `eofbit`, it does not count the number of characters
3123
- extracted, and it does not affect the value returned by subsequent calls
3124
- to `gcount()`. After constructing a sentry object, if `fail() != true`,
3125
- executes `rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure,
3126
- the function calls `setstate(failbit)` (which may throw
3127
  `ios_base::failure`).
3128
 
3129
  *Returns:* `*this`.
3130
 
3131
  ``` cpp
3132
  basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
3133
  ```
3134
 
3135
  *Effects:* Behaves as an unformatted input function (as described
3136
- in  [[istream.unformatted]], paragraph 1), except that it does not count
3137
- the number of characters extracted and does not affect the value
3138
  returned by subsequent calls to `gcount()`. After constructing a sentry
3139
  object, if `fail() != true`, executes
3140
  `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
3141
  function calls `setstate(failbit)` (which may throw
3142
  `ios_base::failure`).
@@ -3144,77 +3203,94 @@ function calls `setstate(failbit)` (which may throw
3144
  *Returns:* `*this`.
3145
 
3146
  #### Standard `basic_istream` manipulators <a id="istream.manip">[[istream.manip]]</a>
3147
 
3148
  ``` cpp
3149
- namespace std {
3150
  template <class charT, class traits>
3151
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
3152
- }
3153
  ```
3154
 
3155
- *Effects:* Behaves as an unformatted input function (as described
3156
- in  [[istream.unformatted]], paragraph 1), except that it does not count
3157
- the number of characters extracted and does not affect the value
3158
- returned by subsequent calls to is.gcount(). After constructing a sentry
3159
- object extracts characters as long as the next available character `c`
3160
- is whitespace or until there are no more characters in the sequence.
3161
  Whitespace characters are distinguished with the same criterion as used
3162
  by `sentry::sentry` ([[istream::sentry]]). If `ws` stops extracting
3163
  characters because there are no more available it sets `eofbit`, but not
3164
  `failbit`.
3165
 
3166
  *Returns:* `is`.
3167
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3168
  #### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
3169
 
3170
  ``` cpp
3171
  namespace std {
3172
  template <class charT, class traits = char_traits<charT>>
3173
- class basic_iostream :
3174
- public basic_istream<charT,traits>,
3175
  public basic_ostream<charT, traits> {
3176
  public:
3177
- // types:
3178
- typedef charT char_type;
3179
- typedef typename traits::int_type int_type;
3180
- typedef typename traits::pos_type pos_type;
3181
- typedef typename traits::off_type off_type;
3182
- typedef traits traits_type;
3183
 
3184
- // constructor/destructor
3185
  explicit basic_iostream(basic_streambuf<charT, traits>* sb);
 
 
3186
  virtual ~basic_iostream();
3187
 
3188
  protected:
 
3189
  basic_iostream(const basic_iostream& rhs) = delete;
3190
  basic_iostream(basic_iostream&& rhs);
3191
 
3192
- // assign/swap
3193
  basic_iostream& operator=(const basic_iostream& rhs) = delete;
3194
  basic_iostream& operator=(basic_iostream&& rhs);
3195
  void swap(basic_iostream& rhs);
3196
  };
3197
  }
3198
  ```
3199
 
3200
- The class `basic_iostream` inherits a number of functions that allow
3201
- reading input and writing output to sequences controlled by a stream
3202
- buffer.
3203
 
3204
  ##### `basic_iostream` constructors <a id="iostream.cons">[[iostream.cons]]</a>
3205
 
3206
  ``` cpp
3207
  explicit basic_iostream(basic_streambuf<charT, traits>* sb);
3208
  ```
3209
 
3210
- *Effects:* Constructs an object of class `basic_iostream`, assigning
3211
- initial values to the base classes by calling
3212
  `basic_istream<charT, traits>(sb)` ([[istream]]) and
3213
- `basic_ostream<charT,traits>(sb)` ([[ostream]])
3214
 
3215
- `rdbuf()==sb` and `gcount()==0`.
3216
 
3217
  ``` cpp
3218
  basic_iostream(basic_iostream&& rhs);
3219
  ```
3220
 
@@ -3235,30 +3311,18 @@ virtual ~basic_iostream();
3235
 
3236
  ``` cpp
3237
  basic_iostream& operator=(basic_iostream&& rhs);
3238
  ```
3239
 
3240
- *Effects:* `swap(rhs)`.
3241
 
3242
  ``` cpp
3243
  void swap(basic_iostream& rhs);
3244
  ```
3245
 
3246
  *Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
3247
 
3248
- #### Rvalue stream extraction <a id="istream.rvalue">[[istream.rvalue]]</a>
3249
-
3250
- ``` cpp
3251
- template <class charT, class traits, class T>
3252
- basic_istream<charT, traits>&
3253
- operator>>(basic_istream<charT, traits>&& is, T& x);
3254
- ```
3255
-
3256
- *Effects:* `is >>x`
3257
-
3258
- *Returns:* `is`
3259
-
3260
  ### Output streams <a id="output.streams">[[output.streams]]</a>
3261
 
3262
  The header `<ostream>` defines a type and several function signatures
3263
  that control output to a stream buffer along with a function template
3264
  that inserts into stream rvalues.
@@ -3269,30 +3333,30 @@ that inserts into stream rvalues.
3269
  namespace std {
3270
  template <class charT, class traits = char_traits<charT>>
3271
  class basic_ostream : virtual public basic_ios<charT, traits> {
3272
  public:
3273
  // types (inherited from basic_ios ([ios])):
3274
- typedef charT char_type;
3275
- typedef typename traits::int_type int_type;
3276
- typedef typename traits::pos_type pos_type;
3277
- typedef typename traits::off_type off_type;
3278
- typedef traits traits_type;
3279
 
3280
- // [ostream.cons] Constructor/destructor:
3281
  explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
3282
  virtual ~basic_ostream();
3283
 
3284
- // [ostream::sentry] Prefix/suffix:
3285
  class sentry;
3286
 
3287
- // [ostream.formatted] Formatted output:
3288
- basic_ostream<charT,traits>& operator<<(
3289
- basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&));
3290
- basic_ostream<charT,traits>& operator<<(
3291
- basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
3292
- basic_ostream<charT,traits>& operator<<(
3293
- ios_base& (*pf)(ios_base&));
3294
 
3295
  basic_ostream<charT, traits>& operator<<(bool n);
3296
  basic_ostream<charT, traits>& operator<<(short n);
3297
  basic_ostream<charT, traits>& operator<<(unsigned short n);
3298
  basic_ostream<charT, traits>& operator<<(int n);
@@ -3304,75 +3368,65 @@ namespace std {
3304
  basic_ostream<charT, traits>& operator<<(float f);
3305
  basic_ostream<charT, traits>& operator<<(double f);
3306
  basic_ostream<charT, traits>& operator<<(long double f);
3307
 
3308
  basic_ostream<charT, traits>& operator<<(const void* p);
3309
- basic_ostream<charT,traits>& operator<<(
3310
- basic_streambuf<char_type,traits>* sb);
3311
 
3312
- // [ostream.unformatted] Unformatted output:
3313
  basic_ostream<charT, traits>& put(char_type c);
3314
  basic_ostream<charT, traits>& write(const char_type* s, streamsize n);
3315
 
3316
  basic_ostream<charT, traits>& flush();
3317
 
3318
- // [ostream.seeks] seeks:
3319
  pos_type tellp();
3320
  basic_ostream<charT, traits>& seekp(pos_type);
3321
  basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
 
3322
  protected:
 
3323
  basic_ostream(const basic_ostream& rhs) = delete;
3324
  basic_ostream(basic_ostream&& rhs);
3325
 
3326
- // [ostream.assign] Assign/swap
3327
  basic_ostream& operator=(const basic_ostream& rhs) = delete;
3328
  basic_ostream& operator=(basic_ostream&& rhs);
3329
  void swap(basic_ostream& rhs);
3330
  };
3331
 
3332
- // [ostream.inserters.character] character inserters
3333
  template<class charT, class traits>
3334
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
3335
- charT);
3336
  template<class charT, class traits>
3337
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
3338
- char);
3339
  template<class traits>
3340
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
3341
- char);
3342
 
3343
- // signed and unsigned
3344
  template<class traits>
3345
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
3346
- signed char);
3347
  template<class traits>
3348
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
3349
- unsigned char);
3350
 
3351
  template<class charT, class traits>
3352
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
3353
- const charT*);
3354
  template<class charT, class traits>
3355
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
3356
- const char*);
3357
  template<class traits>
3358
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
3359
- const char*);
3360
 
3361
- // signed and unsigned
3362
  template<class traits>
3363
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
3364
- const signed char*);
3365
  template<class traits>
3366
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
3367
- const unsigned char*);
3368
  }
3369
  ```
3370
 
3371
- The class `basic_ostream` defines a number of member function signatures
3372
- that assist in formatting and writing output to output sequences
3373
- controlled by a stream buffer.
3374
 
3375
  Two groups of member function signatures share common properties: the
3376
  *formatted output functions* (or *inserters*) and the *unformatted
3377
  output functions.* Both groups of output functions generate (or
3378
  *insert*) output *characters* by actions equivalent to calling
@@ -3384,45 +3438,55 @@ If one of these called functions throws an exception, then unless
3384
  explicitly noted otherwise the output function sets `badbit` in error
3385
  state. If `badbit` is on in `exceptions()`, the output function rethrows
3386
  the exception without completing its actions, otherwise it does not
3387
  throw anything and treat as an error.
3388
 
3389
- #### `basic_ostream` constructors <a id="ostream.cons">[[ostream.cons]]</a>
3390
 
3391
  ``` cpp
3392
  explicit basic_ostream(basic_streambuf<charT, traits>* sb);
3393
  ```
3394
 
3395
- ``` cpp
3396
- virtual ~basic_ostream();
3397
- ```
 
 
3398
 
3399
  ``` cpp
3400
  basic_ostream(basic_ostream&& rhs);
3401
  ```
3402
 
3403
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
3404
  by default constructing the base class and calling
3405
  `basic_ios<charT, traits>::move(rhs)` to initialize the base class.
3406
 
3407
- #### Class `basic_ostream` assign and swap <a id="ostream.assign">[[ostream.assign]]</a>
 
 
 
 
 
 
 
 
3408
 
3409
  ``` cpp
3410
  basic_ostream& operator=(basic_ostream&& rhs);
3411
  ```
3412
 
3413
- *Effects:* `swap(rhs)`.
3414
 
3415
  *Returns:* `*this`.
3416
 
3417
  ``` cpp
3418
  void swap(basic_ostream& rhs);
3419
  ```
3420
 
3421
  *Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`.
3422
 
3423
- #### Class `basic_ostream::sentry` <a id="ostream::sentry">[[ostream::sentry]]</a>
3424
 
3425
  ``` cpp
3426
  namespace std {
3427
  template <class charT, class traits = char_traits<charT>>
3428
  class basic_ostream<charT, traits>::sentry {
@@ -3444,45 +3508,55 @@ exception safe prefix and suffix operations.
3444
  ``` cpp
3445
  explicit sentry(basic_ostream<charT, traits>& os);
3446
  ```
3447
 
3448
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
3449
- If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^30]
3450
 
3451
  If, after any preparation is completed, `os.good()` is `true`,
3452
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
3453
  constructor may call `setstate(failbit)` (which may throw
3454
- `ios_base::failure` ([[iostate.flags]]))[^31]
3455
 
3456
  ``` cpp
3457
  ~sentry();
3458
  ```
3459
 
3460
  If
3461
- `((os.flags() & ios_base::unitbuf) && !uncaught_exception() && os.good())`
3462
  is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1,
3463
  sets `badbit` in `os.rdstate()` without propagating an exception.
3464
 
3465
  ``` cpp
3466
  explicit operator bool() const;
3467
  ```
3468
 
3469
  *Effects:* Returns `ok_`.
3470
 
3471
- #### `basic_ostream` seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
3472
 
3473
  Each seek member function begins execution by constructing an object of
3474
  class `sentry`. It returns by destroying the `sentry` object.
3475
 
3476
  ``` cpp
3477
  pos_type tellp();
3478
  ```
3479
 
 
 
 
3480
  ``` cpp
3481
  basic_ostream<charT, traits>& seekp(pos_type pos);
3482
  ```
3483
 
 
 
 
 
 
 
 
3484
  ``` cpp
3485
  basic_ostream<charT, traits>& seekp(off_type off, ios_base::seekdir dir);
3486
  ```
3487
 
3488
  *Effects:* If `fail() != true`, executes
@@ -3500,11 +3574,11 @@ Each formatted output function begins execution by constructing an
3500
  object of class `sentry`. If this object returns `true` when converted
3501
  to a value of type `bool`, the function endeavors to generate the
3502
  requested output. If the generation fails, then the formatted output
3503
  function does `setstate(ios_base::failbit)`, which might throw an
3504
  exception. If an exception is thrown during output, then `ios::badbit`
3505
- is turned on[^32] in `*this`’s error state. If
3506
  `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
3507
  not an exception is thrown, the `sentry` object is destroyed before
3508
  leaving the formatted output function. If no exception is thrown, the
3509
  result of the formatted output function is `*this`.
3510
 
@@ -3601,59 +3675,57 @@ bool failed = use_facet<
3601
  The first argument provides an object of the `ostreambuf_iterator<>`
3602
  class which is an iterator for class `basic_ostream<>`. It bypasses
3603
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
3604
  these types as its interface to iostreams, since for flexibility it has
3605
  been abstracted away from direct dependence on `ostream`. The second
3606
- parameter is a reference to the base subobject of type `ios_base`. It
3607
- provides formatting specifications such as field width, and a locale
3608
  from which to obtain other facets. If `failed` is `true` then does
3609
  `setstate(badbit)`, which may throw an exception, and returns.
3610
 
3611
  *Returns:* `*this`.
3612
 
3613
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
3614
 
3615
  ``` cpp
3616
- basic_ostream<charT,traits>& operator<<
3617
- (basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&));
3618
  ```
3619
 
3620
  *Effects:* None. Does not behave as a formatted output function (as
3621
  described in  [[ostream.formatted.reqmts]]).
3622
 
3623
- *Returns:* `pf(*this)`.[^33]
3624
 
3625
  ``` cpp
3626
- basic_ostream<charT,traits>& operator<<
3627
- (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
3628
  ```
3629
 
3630
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3631
  formatted output function (as described
3632
  in  [[ostream.formatted.reqmts]]).
3633
 
3634
- *Returns:* `*this`.[^34]
3635
 
3636
  ``` cpp
3637
- basic_ostream<charT,traits>& operator<<
3638
- (ios_base& (*pf)(ios_base&));
3639
  ```
3640
 
3641
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3642
  formatted output function (as described
3643
  in  [[ostream.formatted.reqmts]]).
3644
 
3645
  *Returns:* `*this`.
3646
 
3647
  ``` cpp
3648
- basic_ostream<charT,traits>& operator<<
3649
- (basic_streambuf<charT,traits>* sb);
3650
  ```
3651
 
3652
- *Effects:* Behaves as an unformatted output function (as described
3653
- in  [[ostream.unformatted]], paragraph 1). After the sentry object is
3654
- constructed, if `sb` is null calls `setstate(badbit)` (which may throw
3655
  `ios_base::failure`).
3656
 
3657
  Gets characters from `sb` and inserts them in `*this`. Characters are
3658
  read from `sb` and inserted until any of the following occurs:
3659
 
@@ -3668,55 +3740,58 @@ exception was thrown while extracting a character, the function sets
3668
  `failbit` in error state, and if `failbit` is on in `exceptions()` the
3669
  caught exception is rethrown.
3670
 
3671
  *Returns:* `*this`.
3672
 
 
 
 
 
 
 
 
 
 
 
 
 
3673
  ##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
3674
 
3675
  ``` cpp
3676
  template<class charT, class traits>
3677
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
3678
- charT c);
3679
  template<class charT, class traits>
3680
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
3681
- char c);
3682
  // specialization
3683
  template<class traits>
3684
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
3685
- char c);
3686
  // signed and unsigned
3687
  template<class traits>
3688
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
3689
- signed char c);
3690
  template<class traits>
3691
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
3692
- unsigned char c);
3693
  ```
3694
 
3695
- *Effects:* Behaves as a formatted output function
3696
- (  [[ostream.formatted.reqmts]]) of `out`. Constructs a character
3697
- sequence `seq`. If `c` has type `char` and the character type of the
3698
- stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
3699
- `seq` consists of `c`. Determines padding for `seq` as described
3700
- in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
3701
- `os.width(0)`.
3702
 
3703
  *Returns:* `out`.
3704
 
3705
  ``` cpp
3706
  template<class charT, class traits>
3707
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
3708
- const charT* s);
3709
  template<class charT, class traits>
3710
- basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
3711
- const char* s);
3712
  template<class traits>
3713
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
3714
- const char* s);
3715
  template<class traits>
3716
- basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
3717
- const signed char* s);
3718
  template<class traits>
3719
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
3720
  const unsigned char* s);
3721
  ```
3722
 
@@ -3731,11 +3806,11 @@ would be computed as if by:
3731
  - `traits::length(s)` for the overload where the first argument is of
3732
  type `basic_ostream<charT, traits>&` and the second is of type
3733
  `const charT*`, and also for the overload where the first argument is
3734
  of type `basic_ostream<char, traits>&` and the second is of type
3735
  `const char*`,
3736
- - `std::char_traits<char>::length(s)` for the overload where the first
3737
  argument is of type `basic_ostream<charT, traits>&` and the second is
3738
  of type `const char*`,
3739
  - `traits::length(reinterpret_cast<const char*>(s))` for the other two
3740
  overloads.
3741
 
@@ -3749,23 +3824,23 @@ in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
3749
 
3750
  Each unformatted output function begins execution by constructing an
3751
  object of class `sentry`. If this object returns `true`, while
3752
  converting to a value of type `bool`, the function endeavors to generate
3753
  the requested output. If an exception is thrown during output, then
3754
- `ios::badbit` is turned on[^35] in `*this`’s error state. If
3755
  `(exceptions() & badbit) != 0` then the exception is rethrown. In any
3756
  case, the unformatted output function ends by destroying the sentry
3757
  object, then, if no exception was thrown, returning the value specified
3758
  for the unformatted output function.
3759
 
3760
  ``` cpp
3761
  basic_ostream<charT, traits>& put(char_type c);
3762
  ```
3763
 
3764
  *Effects:* Behaves as an unformatted output function (as described
3765
- in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
3766
- object, inserts the character `c`, if possible.[^36]
3767
 
3768
  Otherwise, calls `setstate(badbit)` (which may throw
3769
  `ios_base::failure` ([[iostate.flags]])).
3770
 
3771
  *Returns:* `*this`.
@@ -3773,14 +3848,14 @@ Otherwise, calls `setstate(badbit)` (which may throw
3773
  ``` cpp
3774
  basic_ostream& write(const char_type* s, streamsize n);
3775
  ```
3776
 
3777
  *Effects:* Behaves as an unformatted output function (as described
3778
- in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
3779
- object, obtains characters to insert from successive locations of an
3780
- array whose first element is designated by `s`.[^37] Characters are
3781
- inserted until either of the following occurs:
3782
 
3783
  - `n` characters are inserted;
3784
  - inserting in the output sequence fails (in which case the function
3785
  calls `setstate(badbit)`, which may throw
3786
  `ios_base::failure` ([[iostate.flags]])).
@@ -3790,67 +3865,62 @@ inserted until either of the following occurs:
3790
  ``` cpp
3791
  basic_ostream& flush();
3792
  ```
3793
 
3794
  *Effects:* Behaves as an unformatted output function (as described
3795
- in  [[ostream.formatted.reqmts]], paragraph 1). If `rdbuf()` is not a
3796
- null pointer, constructs a sentry object. If this object returns `true`
3797
- when converted to a value of type `bool` the function calls
3798
- `rdbuf()->pubsync()`. If that function returns -1 calls
3799
- `setstate(badbit)` (which may throw
3800
  `ios_base::failure` ([[iostate.flags]])). Otherwise, if the sentry
3801
  object returns `false`, does nothing.
3802
 
3803
  *Returns:* `*this`.
3804
 
3805
  #### Standard `basic_ostream` manipulators <a id="ostream.manip">[[ostream.manip]]</a>
3806
 
3807
  ``` cpp
3808
- namespace std {
3809
  template <class charT, class traits>
3810
  basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
3811
- }
3812
  ```
3813
 
3814
  *Effects:* Calls `os.put(os.widen(’\n’))`, then `os.flush()`.
3815
 
3816
  *Returns:* `os`.
3817
 
3818
  ``` cpp
3819
- namespace std {
3820
  template <class charT, class traits>
3821
  basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
3822
- }
3823
  ```
3824
 
3825
  *Effects:* Inserts a null character into the output sequence: calls
3826
  `os.put(charT())`.
3827
 
3828
  *Returns:* `os`.
3829
 
3830
  ``` cpp
3831
- namespace std {
3832
  template <class charT, class traits>
3833
  basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
3834
- }
3835
  ```
3836
 
3837
  *Effects:* Calls `os.flush()`.
3838
 
3839
  *Returns:* `os`.
3840
 
3841
  #### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
3842
 
3843
  ``` cpp
3844
  template <class charT, class traits, class T>
3845
- basic_ostream<charT, traits>&
3846
- operator<<(basic_ostream<charT, traits>&& os, const T& x);
3847
  ```
3848
 
3849
- *Effects:* `os << x`
3850
 
3851
- *Returns:* `os`
 
 
 
3852
 
3853
  ### Standard manipulators <a id="std.manip">[[std.manip]]</a>
3854
 
3855
  The header `<iomanip>` defines several functions that support extractors
3856
  and inserters that alter information maintained by class `ios_base` and
@@ -3860,59 +3930,59 @@ its derived classes.
3860
  unspecified resetiosflags(ios_base::fmtflags mask);
3861
  ```
3862
 
3863
  *Returns:* An object of unspecified type such that if `out` is an object
3864
  of type `basic_ostream<charT, traits>` then the expression
3865
- `out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
3866
  if `in` is an object of type `basic_istream<charT, traits>` then the
3867
- expression `in >> resetiosflags(mask)` behaves as if it called
3868
- `f(in, mask)`, where the function `f` is defined as:[^38]
3869
 
3870
  ``` cpp
3871
  void f(ios_base& str, ios_base::fmtflags mask) {
3872
  // reset specified flags
3873
  str.setf(ios_base::fmtflags(0), mask);
3874
  }
3875
  ```
3876
 
3877
- The expression `out << resetiosflags(mask)` shall have type
3878
  `basic_ostream<charT, traits>&` and value `out`. The expression
3879
- `in >> resetiosflags(mask)` shall have type
3880
  `basic_istream<charT, traits>&` and value `in`.
3881
 
3882
  ``` cpp
3883
  unspecified setiosflags(ios_base::fmtflags mask);
3884
  ```
3885
 
3886
  *Returns:* An object of unspecified type such that if `out` is an object
3887
  of type `basic_ostream<charT, traits>` then the expression
3888
- `out << setiosflags(mask)` behaves as if it called `f(out, mask)`, or if
3889
  `in` is an object of type `basic_istream<charT, traits>` then the
3890
- expression `in >> setiosflags(mask)` behaves as if it called
3891
  `f(in, mask)`, where the function `f` is defined as:
3892
 
3893
  ``` cpp
3894
  void f(ios_base& str, ios_base::fmtflags mask) {
3895
  // set specified flags
3896
  str.setf(mask);
3897
  }
3898
  ```
3899
 
3900
- The expression `out << setiosflags(mask)` shall have type
3901
  `basic_ostream<charT, traits>&` and value `out`. The expression
3902
- `in >> setiosflags(mask)` shall have type `basic_istream<charT,`
3903
  `traits>&` and value `in`.
3904
 
3905
  ``` cpp
3906
  unspecified setbase(int base);
3907
  ```
3908
 
3909
  *Returns:* An object of unspecified type such that if `out` is an object
3910
  of type `basic_ostream<charT, traits>` then the expression
3911
- `out << setbase(base)` behaves as if it called `f(out, base)`, or if
3912
  `in` is an object of type `basic_istream<charT, traits>` then the
3913
- expression `in >> setbase(base)` behaves as if it called `f(in, base)`,
3914
  where the function `f` is defined as:
3915
 
3916
  ``` cpp
3917
  void f(ios_base& str, int base) {
3918
  // set basefield
@@ -3921,79 +3991,79 @@ void f(ios_base& str, int base) {
3921
  base == 16 ? ios_base::hex :
3922
  ios_base::fmtflags(0), ios_base::basefield);
3923
  }
3924
  ```
3925
 
3926
- The expression `out << setbase(base)` shall have type
3927
  `basic_ostream<charT, traits>&` and value `out`. The expression
3928
- `in >> setbase(base)` shall have type `basic_istream<charT, traits>&`
3929
  and value `in`.
3930
 
3931
  ``` cpp
3932
  unspecified setfill(char_type c);
3933
  ```
3934
 
3935
  *Returns:* An object of unspecified type such that if `out` is an object
3936
  of type `basic_ostream<charT, traits>` and `c` has type `charT` then the
3937
- expression `out << setfill(c)` behaves as if it called `f(out, c)`,
3938
  where the function `f` is defined as:
3939
 
3940
  ``` cpp
3941
  template<class charT, class traits>
3942
  void f(basic_ios<charT, traits>& str, charT c) {
3943
  // set fill character
3944
  str.fill(c);
3945
  }
3946
  ```
3947
 
3948
- The expression `out << setfill(c)` shall have type
3949
  `basic_ostream<charT, traits>&` and value `out`.
3950
 
3951
  ``` cpp
3952
  unspecified setprecision(int n);
3953
  ```
3954
 
3955
  *Returns:* An object of unspecified type such that if `out` is an object
3956
  of type `basic_ostream<charT, traits>` then the expression
3957
- `out << setprecision(n)` behaves as if it called `f(out, n)`, or if `in`
3958
  is an object of type `basic_istream<charT, traits>` then the expression
3959
- `in >> setprecision(n)` behaves as if it called `f(in, n)`, where the
3960
  function `f` is defined as:
3961
 
3962
  ``` cpp
3963
  void f(ios_base& str, int n) {
3964
  // set precision
3965
  str.precision(n);
3966
  }
3967
  ```
3968
 
3969
- The expression `out << setprecision(n)` shall have type
3970
  `basic_ostream<charT, traits>&` and value `out`. The expression
3971
- `in >> setprecision(n)` shall have type `basic_istream<charT, traits>&`
3972
  and value `in`.
3973
 
3974
  ``` cpp
3975
  unspecified setw(int n);
3976
  ```
3977
 
3978
  *Returns:* An object of unspecified type such that if `out` is an
3979
  instance of `basic_ostream<charT, traits>` then the expression
3980
- `out << setw(n)` behaves as if it called `f(out, n)`, or if `in` is an
3981
  object of type `basic_istream<charT, traits>` then the expression
3982
- `in >> setw(n)` behaves as if it called `f(in, n)`, where the function
3983
  `f` is defined as:
3984
 
3985
  ``` cpp
3986
  void f(ios_base& str, int n) {
3987
  // set width
3988
  str.width(n);
3989
  }
3990
  ```
3991
 
3992
- The expression `out << setw(n)` shall have type
3993
  `basic_ostream<charT, traits>&` and value `out`. The expression
3994
- `in >> setw(n)` shall have type `basic_istream<charT, traits>&` and
3995
  value `in`.
3996
 
3997
  ### Extended manipulators <a id="ext.manip">[[ext.manip]]</a>
3998
 
3999
  The header `<iomanip>` defines several functions that support extractors
@@ -4010,18 +4080,18 @@ specialization of the `basic_string` template (Clause  [[strings]]).
4010
  *Effects:* The expression `in >> get_money(mon, intl)` described below
4011
  behaves as a formatted input function ([[istream.formatted.reqmts]]).
4012
 
4013
  *Returns:* An object of unspecified type such that if `in` is an object
4014
  of type `basic_istream<charT, traits>` then the expression
4015
- `in >> get_money(mon, intl)` behaves as if it called `f(in, mon, intl)`,
4016
  where the function `f` is defined as:
4017
 
4018
  ``` cpp
4019
  template <class charT, class traits, class moneyT>
4020
  void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
4021
- typedef istreambuf_iterator<charT, traits> Iter;
4022
- typedef money_get<charT, Iter> MoneyGet;
4023
 
4024
  ios_base::iostate err = ios_base::goodbit;
4025
  const MoneyGet& mg = use_facet<MoneyGet>(str.getloc());
4026
 
4027
  mg.get(Iter(str.rdbuf()), Iter(), intl, str, err, mon);
@@ -4029,11 +4099,11 @@ void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
4029
  if (ios_base::goodbit != err)
4030
  str.setstate(err);
4031
  }
4032
  ```
4033
 
4034
- The expression `in >> get_money(mon, intl)` shall have type
4035
  `basic_istream<charT, traits>&` and value `in`.
4036
 
4037
  ``` cpp
4038
  template <class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
4039
  ```
@@ -4041,62 +4111,63 @@ template <class moneyT> unspecified put_money(const moneyT& mon, bool intl = fal
4041
  *Requires:* The type `moneyT` shall be either `long double` or a
4042
  specialization of the `basic_string` template (Clause  [[strings]]).
4043
 
4044
  *Returns:* An object of unspecified type such that if `out` is an object
4045
  of type `basic_ostream<charT, traits>` then the expression
4046
- `out << put_money(mon, intl)` behaves as a formatted input function that
4047
- calls `f(out, mon, intl)`, where the function `f` is defined as:
 
4048
 
4049
  ``` cpp
4050
  template <class charT, class traits, class moneyT>
4051
  void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
4052
- typedef ostreambuf_iterator<charT, traits> Iter;
4053
- typedef money_put<charT, Iter> MoneyPut;
4054
 
4055
  const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
4056
  const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);
4057
 
4058
  if (end.failed())
4059
  str.setstate(ios::badbit);
4060
  }
4061
  ```
4062
 
4063
- The expression `out << put_money(mon, intl)` shall have type
4064
  `basic_ostream<charT, traits>&` and value `out`.
4065
 
4066
  ``` cpp
4067
  template <class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
4068
  ```
4069
 
4070
  *Requires:* The argument `tmb` shall be a valid pointer to an object of
4071
- type `struct tm`, and the argument `fmt` shall be a valid pointer to an
4072
  array of objects of type `charT` with `char_traits<charT>::length(fmt)`
4073
  elements.
4074
 
4075
  *Returns:* An object of unspecified type such that if `in` is an object
4076
  of type `basic_istream<charT, traits>` then the expression
4077
- `in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
4078
  where the function `f` is defined as:
4079
 
4080
  ``` cpp
4081
  template <class charT, class traits>
4082
  void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
4083
- typedef istreambuf_iterator<charT, traits> Iter;
4084
- typedef time_get<charT, Iter> TimeGet;
4085
 
4086
  ios_base::iostate err = ios_base::goodbit;
4087
  const TimeGet& tg = use_facet<TimeGet>(str.getloc());
4088
 
4089
  tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
4090
  fmt, fmt + traits::length(fmt));
4091
 
4092
  if (err != ios_base::goodbit)
4093
- str.setstate(err):
4094
  }
4095
  ```
4096
 
4097
- The expression `in >> get_time(tmb, fmt)` shall have type
4098
  `basic_istream<charT, traits>&` and value `in`.
4099
 
4100
  ``` cpp
4101
  template <class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
4102
  ```
@@ -4106,51 +4177,55 @@ type `struct tm`, and the argument `fmt` shall be a valid pointer to an
4106
  array of objects of type `charT` with `char_traits<charT>::length(fmt)`
4107
  elements.
4108
 
4109
  *Returns:* An object of unspecified type such that if `out` is an object
4110
  of type `basic_ostream<charT, traits>` then the expression
4111
- `out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
4112
  where the function `f` is defined as:
4113
 
4114
  ``` cpp
4115
  template <class charT, class traits>
4116
  void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
4117
- typedef ostreambuf_iterator<charT, traits> Iter;
4118
- typedef time_put<charT, Iter> TimePut;
4119
 
4120
  const TimePut& tp = use_facet<TimePut>(str.getloc());
4121
  const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
4122
  fmt, fmt + traits::length(fmt));
4123
 
4124
  if (end.failed())
4125
  str.setstate(ios_base::badbit);
4126
  }
4127
  ```
4128
 
4129
- The expression `out << put_time(tmb, fmt)` shall have type
4130
  `basic_ostream<charT, traits>&` and value `out`.
4131
 
4132
  ### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
4133
 
4134
- Quoted manipulators provide string insertion and extraction of quoted
4135
- strings (for example, XML and CSV formats). Quoted manipulators are
4136
- useful in ensuring that the content of a string with embedded spaces
4137
- remains unchanged if inserted and then extracted via stream I/O.
 
4138
 
4139
  ``` cpp
4140
  template <class charT>
4141
  unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
4142
  template <class charT, class traits, class Allocator>
4143
  unspecified quoted(const basic_string<charT, traits, Allocator>& s,
4144
- charT delim=charT('"'), charT escape=charT('\\'));
 
 
 
4145
  ```
4146
 
4147
  *Returns:* An object of unspecified type such that if `out` is an
4148
  instance of `basic_ostream` with member type `char_type` the same as
4149
- `charT` and with member type `traits_type`, which in the second form is
4150
- the same as `traits`, then the expression
4151
- `out << quoted(s, delim, escape)` behaves as a formatted output
4152
  function ([[ostream.formatted.reqmts]]) of `out`. This forms a
4153
  character sequence `seq`, initially consisting of the following
4154
  elements:
4155
 
4156
  - `delim`.
@@ -4161,135 +4236,134 @@ elements:
4161
 
4162
  Let `x` be the number of elements initially in `seq`. Then padding is
4163
  determined for `seq` as described in  [[ostream.formatted.reqmts]],
4164
  `seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
4165
  `n` is the larger of `out.width()` and `x`, and `out.width(0)` is
4166
- called. The expression `out << quoted(s, delim, escape)` shall have type
4167
  `basic_ostream<charT, traits>&` and value `out`.
4168
 
4169
  ``` cpp
4170
  template <class charT, class traits, class Allocator>
4171
  unspecified quoted(basic_string<charT, traits, Allocator>& s,
4172
- charT delim=charT('"'), charT escape=charT('\\'));
4173
  ```
4174
 
4175
  *Returns:* An object of unspecified type such that:
4176
 
4177
  - If `in` is an instance of `basic_istream` with member types
4178
  `char_type` and `traits_type` the same as `charT` and `traits`,
4179
- respectively, then the expression `in >> quoted(s, delim, escape)`
4180
  behaves as if it extracts the following characters from `in` using
4181
- `basic_istream::operator>>` ([[istream::extractors]]) which may throw
4182
- `ios_base::failure` ([[ios::failure]]):
4183
  - If the first character extracted is equal to `delim`, as determined
4184
  by `traits_type::eq`, then:
4185
  - Turn off the `skipws` flag.
4186
  - `s.clear()`
4187
  - Until an unescaped `delim` character is reached or `!in`, extract
4188
  characters from `in` and append them to `s`, except that if an
4189
  `escape` is reached, ignore it and append the next character to
4190
  `s`.
4191
  - Discard the final `delim` character.
4192
  - Restore the `skipws` flag to its original value.
4193
- - Otherwise, `in >> s`.
4194
  - If `out` is an instance of `basic_ostream` with member types
4195
  `char_type` and `traits_type` the same as `charT` and `traits`,
4196
- respectively, then the expression `out << quoted(s, delim, escape)`
4197
  behaves as specified for the
4198
  `const basic_string<charT, traits, Allocator>&` overload of the
4199
  `quoted` function.
4200
 
4201
- The expression `in >> quoted(s, delim, escape)` shall have type
4202
  `basic_istream<charT, traits>&` and value `in`. The expression
4203
- `out << quoted(s, delim, escape)` shall have type
4204
  `basic_ostream<charT, traits>&` and value `out`.
4205
 
4206
  ## String-based streams <a id="string.streams">[[string.streams]]</a>
4207
 
4208
- ### Overview <a id="string.streams.overview">[[string.streams.overview]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4209
 
4210
  The header `<sstream>` defines four class templates and eight types that
4211
  associate stream buffers with objects of class `basic_string`, as
4212
  described in  [[string.classes]].
4213
 
4214
- ``` cpp
4215
- namespace std {
4216
- template <class charT, class traits = char_traits<charT>,
4217
- class Allocator = allocator<charT> >
4218
- class basic_stringbuf;
4219
-
4220
- typedef basic_stringbuf<char> stringbuf;
4221
- typedef basic_stringbuf<wchar_t> wstringbuf;
4222
-
4223
- template <class charT, class traits = char_traits<charT>,
4224
- class Allocator = allocator<charT> >
4225
- class basic_istringstream;
4226
-
4227
- typedef basic_istringstream<char> istringstream;
4228
- typedef basic_istringstream<wchar_t> wistringstream;
4229
-
4230
- template <class charT, class traits = char_traits<charT>,
4231
- class Allocator = allocator<charT> >
4232
- class basic_ostringstream;
4233
- typedef basic_ostringstream<char> ostringstream;
4234
- typedef basic_ostringstream<wchar_t> wostringstream;
4235
-
4236
- template <class charT, class traits = char_traits<charT>,
4237
- class Allocator = allocator<charT> >
4238
- class basic_stringstream;
4239
- typedef basic_stringstream<char> stringstream;
4240
- typedef basic_stringstream<wchar_t> wstringstream;
4241
- }
4242
- ```
4243
-
4244
  ### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
4245
 
4246
  ``` cpp
4247
  namespace std {
4248
  template <class charT, class traits = char_traits<charT>,
4249
  class Allocator = allocator<charT>>
4250
  class basic_stringbuf : public basic_streambuf<charT, traits> {
4251
  public:
4252
- typedef charT char_type;
4253
- typedef typename traits::int_type int_type;
4254
- typedef typename traits::pos_type pos_type;
4255
- typedef typename traits::off_type off_type;
4256
- typedef traits traits_type;
4257
- typedef Allocator allocator_type;
4258
 
4259
- // [stringbuf.cons] Constructors:
4260
- explicit basic_stringbuf(ios_base::openmode which
4261
- = ios_base::in | ios_base::out);
4262
- explicit basic_stringbuf
4263
- (const basic_string<charT,traits,Allocator>& str,
4264
  ios_base::openmode which = ios_base::in | ios_base::out);
4265
  basic_stringbuf(const basic_stringbuf& rhs) = delete;
4266
  basic_stringbuf(basic_stringbuf&& rhs);
4267
 
4268
- // [stringbuf.assign] Assign and swap:
4269
  basic_stringbuf& operator=(const basic_stringbuf& rhs) = delete;
4270
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
4271
  void swap(basic_stringbuf& rhs);
4272
 
4273
- // [stringbuf.members] Get and set:
4274
  basic_string<charT, traits, Allocator> str() const;
4275
  void str(const basic_string<charT, traits, Allocator>& s);
4276
 
4277
  protected:
4278
- // [stringbuf.virtuals] Overridden virtual functions:
4279
- virtual int_type underflow();
4280
- virtual int_type pbackfail(int_type c = traits::eof());
4281
- virtual int_type overflow (int_type c = traits::eof());
4282
- virtual basic_streambuf<charT,traits>* setbuf(charT*, streamsize);
4283
 
4284
-
4285
- virtual pos_type seekoff(off_type off, ios_base::seekdir way,
4286
  ios_base::openmode which
4287
- = ios_base::in | ios_base::out);
4288
- virtual pos_type seekpos(pos_type sp,
4289
  ios_base::openmode which
4290
- = ios_base::in | ios_base::out);
4291
 
4292
  private:
4293
  ios_base::openmode mode; // exposition only
4294
  };
4295
 
@@ -4311,22 +4385,23 @@ For the sake of exposition, the maintained data is presented here as:
4311
  read, and `out` set if the output sequence can be written.
4312
 
4313
  #### `basic_stringbuf` constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
4314
 
4315
  ``` cpp
4316
- explicit basic_stringbuf(ios_base::openmode which =
4317
- ios_base::in | ios_base::out);
4318
  ```
4319
 
4320
  *Effects:* Constructs an object of class `basic_stringbuf`, initializing
4321
  the base class with `basic_streambuf()` ([[streambuf.cons]]), and
4322
  initializing `mode` with `which`.
4323
 
4324
- `str() == ""`.
4325
 
4326
  ``` cpp
4327
- explicit basic_stringbuf(const basic_string<charT,traits,Allocator>& s,
 
4328
  ios_base::openmode which = ios_base::in | ios_base::out);
4329
  ```
4330
 
4331
  *Effects:* Constructs an object of class `basic_stringbuf`, initializing
4332
  the base class with `basic_streambuf()` ([[streambuf.cons]]), and
@@ -4381,11 +4456,11 @@ void swap(basic_stringbuf& rhs);
4381
  template <class charT, class traits, class Allocator>
4382
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
4383
  basic_stringbuf<charT, traits, Allocator>& y);
4384
  ```
4385
 
4386
- *Effects:* `x.swap(y)`.
4387
 
4388
  #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
4389
 
4390
  ``` cpp
4391
  basic_string<charT, traits, Allocator> str() const;
@@ -4394,11 +4469,11 @@ basic_string<charT,traits,Allocator> str() const;
4394
  *Returns:* A `basic_string` object whose content is equal to the
4395
  `basic_stringbuf` underlying character sequence. If the
4396
  `basic_stringbuf` was created only in input mode, the resultant
4397
  `basic_string` contains the character sequence in the range \[`eback()`,
4398
  `egptr()`). If the `basic_stringbuf` was created with
4399
- `which & ios_base::out` being true then the resultant `basic_string`
4400
  contains the character sequence in the range \[`pbase()`, `high_mark`),
4401
  where `high_mark` represents the position one past the highest
4402
  initialized character in the buffer. Characters can be initialized by
4403
  writing to the stream, by constructing the `basic_stringbuf` with a
4404
  `basic_string`, or by calling the `str(basic_string)` member function.
@@ -4415,31 +4490,31 @@ void str(const basic_string<charT,traits,Allocator>& s);
4415
 
4416
  *Effects:* Copies the content of `s` into the `basic_stringbuf`
4417
  underlying character sequence and initializes the input and output
4418
  sequences according to `mode`.
4419
 
4420
- *Postconditions:* If `mode & ios_base::out` is true, `pbase()` points to
4421
- the first underlying character and `epptr()` `>= pbase() + s.size()`
4422
- holds; in addition, if `mode & ios_base::ate` is true,
4423
  `pptr() == pbase() + s.size()` holds, otherwise `pptr() == pbase()` is
4424
- true. If `mode & ios_base::in` is true, `eback()` points to the first
4425
- underlying character, and both `gptr() == eback()` and
4426
  `egptr() == eback() + s.size()` hold.
4427
 
4428
  #### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
4429
 
4430
  ``` cpp
4431
- int_type underflow();
4432
  ```
4433
 
4434
  *Returns:* If the input sequence has a read position available, returns
4435
  `traits::to_int_type(*gptr())`. Otherwise, returns `traits::eof()`. Any
4436
  character in the underlying buffer which has been initialized is
4437
  considered to be part of the input sequence.
4438
 
4439
  ``` cpp
4440
- int_type pbackfail(int_type c = traits::eof());
4441
  ```
4442
 
4443
  *Effects:* Puts back the character designated by `c` to the input
4444
  sequence, if possible, in one of three ways:
4445
 
@@ -4458,11 +4533,11 @@ sequence, if possible, in one of three ways:
4458
 
4459
  *Remarks:* If the function can succeed in more than one of these ways,
4460
  it is unspecified which way is chosen.
4461
 
4462
  ``` cpp
4463
- int_type overflow(int_type c = traits::eof());
4464
  ```
4465
 
4466
  *Effects:* Appends the character designated by `c` to the output
4467
  sequence, if possible, in one of two ways:
4468
 
@@ -4488,11 +4563,11 @@ plus at least one additional write position. If
4488
  `egptr()` to point just past the new write position.
4489
 
4490
  ``` cpp
4491
  pos_type seekoff(off_type off, ios_base::seekdir way,
4492
  ios_base::openmode which
4493
- = ios_base::in | ios_base::out);
4494
  ```
4495
 
4496
  *Effects:* Alters the stream position within one of the controlled
4497
  sequences, if possible, as indicated in
4498
  Table  [[tab:iostreams.seekoff.positioning]].
@@ -4520,23 +4595,24 @@ as indicated in Table  [[tab:iostreams.newoff.values]].
4520
  | `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
4521
  | `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
4522
 
4523
 
4524
  If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
4525
- character (as defined in  [[stringbuf.members]] paragraph 1), the
4526
- positioning operation fails. Otherwise, the function assigns
4527
- `xbeg + newoff + off` to the next pointer `xnext`.
4528
 
4529
  *Returns:* `pos_type(newoff)`, constructed from the resultant offset
4530
  `newoff` (of type `off_type`), that stores the resultant stream
4531
  position, if possible. If the positioning operation fails, or if the
4532
  constructed object cannot represent the resultant stream position, the
4533
  return value is `pos_type(off_type(-1))`.
4534
 
4535
  ``` cpp
4536
- pos_type seekpos(pos_type sp, ios_base::openmode which
4537
- = ios_base::in | ios_base::out);
 
4538
  ```
4539
 
4540
  *Effects:* Equivalent to `seekoff(off_type(sp), ios_base::beg, which)`.
4541
 
4542
  *Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
@@ -4557,31 +4633,32 @@ effect.
4557
  namespace std {
4558
  template <class charT, class traits = char_traits<charT>,
4559
  class Allocator = allocator<charT>>
4560
  class basic_istringstream : public basic_istream<charT, traits> {
4561
  public:
4562
- typedef charT char_type;
4563
- typedef typename traits::int_type int_type;
4564
- typedef typename traits::pos_type pos_type;
4565
- typedef typename traits::off_type off_type;
4566
- typedef traits traits_type;
4567
- typedef Allocator allocator_type;
4568
 
4569
- // [istringstream.cons] Constructors:
4570
- explicit basic_istringstream(ios_base::openmode which = ios_base::in);
 
4571
  explicit basic_istringstream(
4572
  const basic_string<charT, traits, Allocator>& str,
4573
  ios_base::openmode which = ios_base::in);
4574
  basic_istringstream(const basic_istringstream& rhs) = delete;
4575
  basic_istringstream(basic_istringstream&& rhs);
4576
 
4577
- // [istringstream.assign] Assign and swap:
4578
  basic_istringstream& operator=(const basic_istringstream& rhs) = delete;
4579
  basic_istringstream& operator=(basic_istringstream&& rhs);
4580
  void swap(basic_istringstream& rhs);
4581
 
4582
- // [istringstream.members] Members:
4583
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4584
 
4585
  basic_string<charT, traits, Allocator> str() const;
4586
  void str(const basic_string<charT, traits, Allocator>& s);
4587
  private:
@@ -4628,12 +4705,12 @@ explicit basic_istringstream(
4628
  basic_istringstream(basic_istringstream&& rhs);
4629
  ```
4630
 
4631
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
4632
  by move constructing the base class, and the contained
4633
- `basic_stringbuf`. Next `basic_istream<charT,traits>::set_rdbuf(&sb)` is
4634
- called to install the contained `basic_stringbuf`.
4635
 
4636
  #### Assign and swap <a id="istringstream.assign">[[istringstream.assign]]</a>
4637
 
4638
  ``` cpp
4639
  basic_istringstream& operator=(basic_istringstream&& rhs);
@@ -4655,19 +4732,20 @@ void swap(basic_istringstream& rhs);
4655
  template <class charT, class traits, class Allocator>
4656
  void swap(basic_istringstream<charT, traits, Allocator>& x,
4657
  basic_istringstream<charT, traits, Allocator>& y);
4658
  ```
4659
 
4660
- *Effects:* `x.swap(y)`.
4661
 
4662
  #### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
4663
 
4664
  ``` cpp
4665
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4666
  ```
4667
 
4668
- *Returns:* `const_cast<basic_stringbuf<charT,traits,Allocator>*>(&sb)`.
 
4669
 
4670
  ``` cpp
4671
  basic_string<charT, traits, Allocator> str() const;
4672
  ```
4673
 
@@ -4685,33 +4763,32 @@ void str(const basic_string<charT,traits,Allocator>& s);
4685
  namespace std {
4686
  template <class charT, class traits = char_traits<charT>,
4687
  class Allocator = allocator<charT>>
4688
  class basic_ostringstream : public basic_ostream<charT, traits> {
4689
  public:
 
 
 
 
 
 
4690
 
4691
- // types:
4692
- typedef charT char_type;
4693
- typedef typename traits::int_type int_type;
4694
- typedef typename traits::pos_type pos_type;
4695
- typedef typename traits::off_type off_type;
4696
- typedef traits traits_type;
4697
- typedef Allocator allocator_type;
4698
-
4699
- // [ostringstream.cons] Constructors/destructor:
4700
- explicit basic_ostringstream(ios_base::openmode which = ios_base::out);
4701
  explicit basic_ostringstream(
4702
  const basic_string<charT, traits, Allocator>& str,
4703
  ios_base::openmode which = ios_base::out);
4704
  basic_ostringstream(const basic_ostringstream& rhs) = delete;
4705
  basic_ostringstream(basic_ostringstream&& rhs);
4706
 
4707
- // [ostringstream.assign] Assign/swap:
4708
  basic_ostringstream& operator=(const basic_ostringstream& rhs) = delete;
4709
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
4710
  void swap(basic_ostringstream& rhs);
4711
 
4712
- // [ostringstream.members] Members:
4713
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4714
 
4715
  basic_string<charT, traits, Allocator> str() const;
4716
  void str(const basic_string<charT, traits, Allocator>& s);
4717
  private:
@@ -4732,11 +4809,12 @@ the sake of exposition, the maintained data is presented here as:
4732
  - `sb`, the `stringbuf` object.
4733
 
4734
  #### `basic_ostringstream` constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
4735
 
4736
  ``` cpp
4737
- explicit basic_ostringstream(ios_base::openmode which = ios_base::out);
 
4738
  ```
4739
 
4740
  *Effects:* Constructs an object of class `basic_ostringstream`,
4741
  initializing the base class with `basic_ostream(&sb)` and initializing
4742
  `sb` with
@@ -4757,12 +4835,12 @@ explicit basic_ostringstream(
4757
  basic_ostringstream(basic_ostringstream&& rhs);
4758
  ```
4759
 
4760
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
4761
  by move constructing the base class, and the contained
4762
- `basic_stringbuf`. Next `basic_ostream<charT,traits>::set_rdbuf(&sb)` is
4763
- called to install the contained `basic_stringbuf`.
4764
 
4765
  #### Assign and swap <a id="ostringstream.assign">[[ostringstream.assign]]</a>
4766
 
4767
  ``` cpp
4768
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
@@ -4784,19 +4862,20 @@ void swap(basic_ostringstream& rhs);
4784
  template <class charT, class traits, class Allocator>
4785
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
4786
  basic_ostringstream<charT, traits, Allocator>& y);
4787
  ```
4788
 
4789
- *Effects:* `x.swap(y)`.
4790
 
4791
  #### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
4792
 
4793
  ``` cpp
4794
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4795
  ```
4796
 
4797
- *Returns:* `const_cast<basic_stringbuf<charT,traits,Allocator>*>(&sb)`.
 
4798
 
4799
  ``` cpp
4800
  basic_string<charT, traits, Allocator> str() const;
4801
  ```
4802
 
@@ -4812,37 +4891,34 @@ void str(const basic_string<charT,traits,Allocator>& s);
4812
 
4813
  ``` cpp
4814
  namespace std {
4815
  template <class charT, class traits = char_traits<charT>,
4816
  class Allocator = allocator<charT>>
4817
- class basic_stringstream
4818
- : public basic_iostream<charT,traits> {
4819
  public:
 
 
 
 
 
 
4820
 
4821
- // types:
4822
- typedef charT char_type;
4823
- typedef typename traits::int_type int_type;
4824
- typedef typename traits::pos_type pos_type;
4825
- typedef typename traits::off_type off_type;
4826
- typedef traits traits_type;
4827
- typedef Allocator allocator_type;
4828
-
4829
- // constructors/destructor
4830
  explicit basic_stringstream(
4831
  ios_base::openmode which = ios_base::out | ios_base::in);
4832
  explicit basic_stringstream(
4833
  const basic_string<charT, traits, Allocator>& str,
4834
  ios_base::openmode which = ios_base::out | ios_base::in);
4835
  basic_stringstream(const basic_stringstream& rhs) = delete;
4836
  basic_stringstream(basic_stringstream&& rhs);
4837
 
4838
- // [stringstream.assign] Assign/swap:
4839
  basic_stringstream& operator=(const basic_stringstream& rhs) = delete;
4840
  basic_stringstream& operator=(basic_stringstream&& rhs);
4841
  void swap(basic_stringstream& rhs);
4842
 
4843
- // Members:
4844
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4845
  basic_string<charT, traits, Allocator> str() const;
4846
  void str(const basic_string<charT, traits, Allocator>& str);
4847
 
4848
  private:
@@ -4862,11 +4938,11 @@ and writing from objects of class
4862
  associated sequence. For the sake of exposition, the maintained data is
4863
  presented here as
4864
 
4865
  - `sb`, the `stringbuf` object.
4866
 
4867
- #### basic_stringstream constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
4868
 
4869
  ``` cpp
4870
  explicit basic_stringstream(
4871
  ios_base::openmode which = ios_base::out | ios_base::in);
4872
  ```
@@ -4891,12 +4967,12 @@ explicit basic_stringstream(
4891
  basic_stringstream(basic_stringstream&& rhs);
4892
  ```
4893
 
4894
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
4895
  by move constructing the base class, and the contained
4896
- `basic_stringbuf`. Next `basic_istream<charT,traits>::set_rdbuf(&sb)` is
4897
- called to install the contained `basic_stringbuf`.
4898
 
4899
  #### Assign and swap <a id="stringstream.assign">[[stringstream.assign]]</a>
4900
 
4901
  ``` cpp
4902
  basic_stringstream& operator=(basic_stringstream&& rhs);
@@ -4918,11 +4994,11 @@ void swap(basic_stringstream& rhs);
4918
  template <class charT, class traits, class Allocator>
4919
  void swap(basic_stringstream<charT, traits, Allocator>& x,
4920
  basic_stringstream<charT, traits, Allocator>& y);
4921
  ```
4922
 
4923
- *Effects:* `x.swap(y)`.
4924
 
4925
  #### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
4926
 
4927
  ``` cpp
4928
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
@@ -4942,96 +5018,106 @@ void str(const basic_string<charT,traits,Allocator>& str);
4942
 
4943
  *Effects:* Calls `rdbuf()->str(str)`.
4944
 
4945
  ## File-based streams <a id="file.streams">[[file.streams]]</a>
4946
 
4947
- ### File streams <a id="fstreams">[[fstreams]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4948
 
4949
  The header `<fstream>` defines four class templates and eight types that
4950
  associate stream buffers with files and assist reading and writing
4951
  files.
4952
 
4953
- ``` cpp
4954
- namespace std {
4955
- template <class charT, class traits = char_traits<charT> >
4956
- class basic_filebuf;
4957
- typedef basic_filebuf<char> filebuf;
4958
- typedef basic_filebuf<wchar_t> wfilebuf;
4959
 
4960
- template <class charT, class traits = char_traits<charT> >
4961
- class basic_ifstream;
4962
- typedef basic_ifstream<char> ifstream;
4963
- typedef basic_ifstream<wchar_t> wifstream;
4964
 
4965
- template <class charT, class traits = char_traits<charT> >
4966
- class basic_ofstream;
4967
- typedef basic_ofstream<char> ofstream;
4968
- typedef basic_ofstream<wchar_t> wofstream;
4969
 
4970
- template <class charT, class traits = char_traits<charT> >
4971
- class basic_fstream;
4972
- typedef basic_fstream<char> fstream;
4973
- typedef basic_fstream<wchar_t> wfstream;
4974
- }
4975
- ```
4976
-
4977
- In this subclause, the type name `FILE` refers to the type `FILE`
4978
- declared in `<cstdio>` ([[c.files]]).
4979
-
4980
- The class template `basic_filebuf` treats a file as a source or sink of
4981
- bytes. In an environment that uses a large character set, the file
4982
- typically holds multibyte character sequences and the `basic_filebuf`
4983
- object converts those multibyte sequences into wide character sequences.
4984
-
4985
- #### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
4986
 
4987
  ``` cpp
4988
  namespace std {
4989
  template <class charT, class traits = char_traits<charT>>
4990
  class basic_filebuf : public basic_streambuf<charT, traits> {
4991
  public:
4992
- typedef charT char_type;
4993
- typedef typename traits::int_type int_type;
4994
- typedef typename traits::pos_type pos_type;
4995
- typedef typename traits::off_type off_type;
4996
- typedef traits traits_type;
4997
 
4998
- // [filebuf.cons] Constructors/destructor:
4999
  basic_filebuf();
5000
  basic_filebuf(const basic_filebuf& rhs) = delete;
5001
  basic_filebuf(basic_filebuf&& rhs);
5002
  virtual ~basic_filebuf();
5003
 
5004
- // [filebuf.assign] Assign/swap:
5005
  basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
5006
  basic_filebuf& operator=(basic_filebuf&& rhs);
5007
  void swap(basic_filebuf& rhs);
5008
 
5009
- // [filebuf.members] Members:
5010
  bool is_open() const;
5011
- basic_filebuf<charT,traits>* open(const char* s,
 
 
 
5012
  ios_base::openmode mode);
5013
- basic_filebuf<charT,traits>* open(const string& s,
5014
  ios_base::openmode mode);
5015
- basic_filebuf<charT,traits>* close();
5016
 
5017
  protected:
5018
- // [filebuf.virtuals] Overridden virtual functions:
5019
- virtual streamsize showmanyc();
5020
- virtual int_type underflow();
5021
- virtual int_type uflow();
5022
- virtual int_type pbackfail(int_type c = traits::eof());
5023
- virtual int_type overflow (int_type c = traits::eof());
5024
 
5025
- virtual basic_streambuf<charT,traits>*
5026
- setbuf(char_type* s, streamsize n);
5027
- virtual pos_type seekoff(off_type off, ios_base::seekdir way,
5028
- ios_base::openmode which = ios_base::in | ios_base::out);
5029
- virtual pos_type seekpos(pos_type sp,
5030
- ios_base::openmode which = ios_base::in | ios_base::out);
5031
- virtual int sync();
5032
- virtual void imbue(const locale& loc);
 
 
5033
  };
5034
 
5035
  template <class charT, class traits>
5036
  void swap(basic_filebuf<charT, traits>& x,
5037
  basic_filebuf<charT, traits>& y);
@@ -5041,23 +5127,23 @@ namespace std {
5041
  The class `basic_filebuf<charT, traits>` associates both the input
5042
  sequence and the output sequence with a file.
5043
 
5044
  The restrictions on reading and writing a sequence controlled by an
5045
  object of class `basic_filebuf<charT, traits>` are the same as for
5046
- reading and writing with the Standard C library `FILE`s.
5047
 
5048
  In particular:
5049
 
5050
  - If the file is not open for reading the input sequence cannot be read.
5051
  - If the file is not open for writing the output sequence cannot be
5052
  written.
5053
  - A joint file position is maintained for both the input sequence and
5054
  the output sequence.
5055
 
5056
  An instance of `basic_filebuf` behaves as described in  [[filebuf]]
5057
- provided `traits::pos_type` is `fpos<traits::state_type>`. Otherwise the
5058
- behavior is undefined.
5059
 
5060
  In order to support file I/O and multibyte/wide character conversion,
5061
  conversions are performed using members of a facet, referred to as
5062
  `a_codecvt` in following sections, obtained as if by
5063
 
@@ -5074,11 +5160,11 @@ basic_filebuf();
5074
 
5075
  *Effects:* Constructs an object of class `basic_filebuf<charT, traits>`,
5076
  initializing the base class with
5077
  `basic_streambuf<charT, traits>()` ([[streambuf.cons]]).
5078
 
5079
- `is_open() == false`.
5080
 
5081
  ``` cpp
5082
  basic_filebuf(basic_filebuf&& rhs);
5083
  ```
5084
 
@@ -5121,13 +5207,13 @@ rethrown (see  [[res.on.exception.handling]]).
5121
 
5122
  ``` cpp
5123
  basic_filebuf& operator=(basic_filebuf&& rhs);
5124
  ```
5125
 
5126
- *Effects:* Calls `this->close()` then move assigns from `rhs`. After the
5127
- move assignment `*this` has the observable state it would have had if it
5128
- had been move constructed from `rhs` (see  [[filebuf.cons]]).
5129
 
5130
  *Returns:* `*this`.
5131
 
5132
  ``` cpp
5133
  void swap(basic_filebuf& rhs);
@@ -5139,11 +5225,11 @@ void swap(basic_filebuf& rhs);
5139
  template <class charT, class traits>
5140
  void swap(basic_filebuf<charT, traits>& x,
5141
  basic_filebuf<charT, traits>& y);
5142
  ```
5143
 
5144
- *Effects:* `x.swap(y)`.
5145
 
5146
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
5147
 
5148
  ``` cpp
5149
  bool is_open() const;
@@ -5151,18 +5237,19 @@ bool is_open() const;
5151
 
5152
  *Returns:* `true` if a previous call to `open` succeeded (returned a
5153
  non-null value) and there has been no intervening call to close.
5154
 
5155
  ``` cpp
5156
- basic_filebuf<charT,traits>* open(const char* s,
5157
- ios_base::openmode mode);
 
5158
  ```
5159
 
5160
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
5161
  initializes the `filebuf` as required. It then opens a file, if
5162
  possible, whose name is the NTBS`s` (as if by calling
5163
- `std::fopen(s,modstr)`). The NTBS`modstr` is determined from
5164
  `mode & ~ios_base::ate` as indicated in
5165
  Table  [[tab:iostreams.file.open.modes]]. If `mode` is not some
5166
  combination of flags shown in the table then the open fails.
5167
 
5168
  **Table: File open modes** <a id="tab:iostreams.file.open.modes">[tab:iostreams.file.open.modes]</a>
@@ -5188,67 +5275,67 @@ combination of flags shown in the table then the open fails.
5188
  | + | + | | | + | `"a+b"` |
5189
 
5190
 
5191
  If the open operation succeeds and `(mode & ios_base::ate) != 0`,
5192
  positions the file to the end (as if by calling
5193
- `std::fseek(file,0,SEEK_END)`).[^39]
5194
 
5195
  If the repositioning operation fails, calls `close()` and returns a null
5196
  pointer to indicate failure.
5197
 
5198
  *Returns:* `this` if successful, a null pointer otherwise.
5199
 
5200
  ``` cpp
5201
- basic_filebuf<charT,traits>* open(const string& s,
5202
- ios_base::openmode mode);
5203
  ```
5204
 
5205
  *Returns:* `open(s.c_str(), mode);`
5206
 
5207
  ``` cpp
5208
- basic_filebuf<charT,traits>* close();
5209
  ```
5210
 
5211
  *Effects:* If `is_open() == false`, returns a null pointer. If a put
5212
  area exists, calls `overflow(traits::eof())` to flush characters. If the
5213
  last virtual member function called on `*this` (between `underflow`,
5214
  `overflow`, `seekoff`, and `seekpos`) was `overflow` then calls
5215
  `a_codecvt.unshift` (possibly several times) to determine a termination
5216
  sequence, inserts those characters and calls `overflow(traits::eof())`
5217
  again. Finally, regardless of whether any of the preceding calls fails
5218
  or throws an exception, the function closes the file (as if by calling
5219
- `std::fclose(file)`).[^40] If any of the calls made by the function,
5220
- including `std::fclose`, fails, `close` fails by returning a null
5221
- pointer. If one of these calls throws an exception, the exception is
5222
- caught and rethrown after closing the file.
5223
 
5224
  *Returns:* `this` on success, a null pointer otherwise.
5225
 
5226
- `is_open() == false`.
5227
 
5228
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
5229
 
5230
  ``` cpp
5231
- streamsize showmanyc();
5232
  ```
5233
 
5234
  *Effects:* Behaves the same as
5235
  `basic_streambuf::showmanyc()` ([[streambuf.virtuals]]).
5236
 
5237
  *Remarks:* An implementation might well provide an overriding definition
5238
  for this function signature if it can determine that more characters can
5239
  be read from the input sequence.
5240
 
5241
  ``` cpp
5242
- int_type underflow();
5243
  ```
5244
 
5245
  *Effects:* Behaves according to the description of
5246
  `basic_streambuf<charT, traits>::underflow()`, with the specialization
5247
  that a sequence of characters is read from the input sequence as if by
5248
  reading from the associated file into an internal buffer (`extern_buf`)
5249
- and then as if by doing
5250
 
5251
  ``` cpp
5252
  char extern_buf[XSIZE];
5253
  char* extern_end;
5254
  charT intern_buf[ISIZE];
@@ -5262,20 +5349,20 @@ This shall be done in such a way that the class can recover the position
5262
  (`fpos_t`) corresponding to each character between `intern_buf` and
5263
  `intern_end`. If the value of `r` indicates that `a_codecvt.in()` ran
5264
  out of space in `intern_buf`, retry with a larger `intern_buf`.
5265
 
5266
  ``` cpp
5267
- int_type uflow();
5268
  ```
5269
 
5270
  *Effects:* Behaves according to the description of
5271
- `basic_streambuf<charT,traits>::uflow()`, with the specialization that a
5272
- sequence of characters is read from the input with the same method as
5273
  used by `underflow`.
5274
 
5275
  ``` cpp
5276
- int_type pbackfail(int_type c = traits::eof());
5277
  ```
5278
 
5279
  *Effects:* Puts back the character designated by `c` to the input
5280
  sequence, if possible, in one of three ways:
5281
 
@@ -5303,11 +5390,11 @@ sequence.
5303
  If the function can succeed in more than one of these ways, it is
5304
  unspecified which way is chosen. The function can alter the number of
5305
  putback positions available as a result of any call.
5306
 
5307
  ``` cpp
5308
- int_type overflow(int_type c = traits::eof());
5309
  ```
5310
 
5311
  *Effects:* Behaves according to the description of
5312
  `basic_streambuf<charT, traits>::overflow(c)`, except that the behavior
5313
  of “consuming characters” is performed by first converting as if by:
@@ -5336,31 +5423,32 @@ and then
5336
 
5337
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
5338
  to indicate failure. If `is_open() == false`, the function always fails.
5339
 
5340
  ``` cpp
5341
- basic_streambuf* setbuf(char_type* s, streamsize n);
5342
  ```
5343
 
5344
  *Effects:* If `setbuf(0, 0)` is called on a stream before any I/O has
5345
  occurred on that stream, the stream becomes unbuffered. Otherwise the
5346
  results are *implementation-defined*. “Unbuffered” means that `pbase()`
5347
  and `pptr()` always return null and output to the file should appear as
5348
  soon as possible.
5349
 
5350
  ``` cpp
5351
  pos_type seekoff(off_type off, ios_base::seekdir way,
5352
- ios_base::openmode which = ios_base::in | ios_base::out);
 
5353
  ```
5354
 
5355
  *Effects:* Let `width` denote `a_codecvt.encoding()`. If
5356
  `is_open() == false`, or `off != 0 && width <= 0`, then the positioning
5357
  operation fails. Otherwise, if `way != basic_ios::cur` or `off != 0`,
5358
  and if the last operation was output, then update the output sequence
5359
  and write any unshift sequence. Next, seek to the new position: if
5360
- `width > 0`, call `std::fseek(file, width * off, whence)`, otherwise
5361
- call `std::fseek(file, 0, whence)`.
5362
 
5363
  *Remarks:* “The last operation was output” means either the last virtual
5364
  operation was overflow or the put buffer is non-empty. “Write any
5365
  unshift sequence” means, if `width` if less than zero then call
5366
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
@@ -5382,90 +5470,99 @@ resultant stream position, if possible. If the positioning operation
5382
  fails, or if the object cannot represent the resultant stream position,
5383
  returns `pos_type(off_type(-1))`.
5384
 
5385
  ``` cpp
5386
  pos_type seekpos(pos_type sp,
5387
- ios_base::openmode which = ios_base::in | ios_base::out);
 
5388
  ```
5389
 
5390
  Alters the file position, if possible, to correspond to the position
5391
  stored in `sp` (as described below). Altering the file position performs
5392
  as follows:
5393
 
5394
  1. if `(om & ios_base::out) != 0`, then update the output sequence and
5395
  write any unshift sequence;
5396
- 2. set the file position to `sp`;
5397
  3. if `(om & ios_base::in) != 0`, then update the input sequence;
5398
 
5399
  where `om` is the open mode passed to the last call to `open()`. The
5400
- operation fails if `is_open()` returns false.
5401
 
5402
  If `sp` is an invalid stream position, or if the function positions
5403
  neither sequence, the positioning operation fails. If `sp` has not been
5404
  obtained by a previous successful call to one of the positioning
5405
  functions (`seekoff` or `seekpos`) on the same file the effects are
5406
  undefined.
5407
 
5408
  *Returns:* `sp` on success. Otherwise returns `pos_type(off_type(-1))`.
5409
 
5410
  ``` cpp
5411
- int sync();
5412
  ```
5413
 
5414
  *Effects:* If a put area exists, calls `filebuf::overflow` to write the
5415
- characters to the file. If a get area exists, the effect is
 
5416
  *implementation-defined*.
5417
 
5418
  ``` cpp
5419
- void imbue(const locale& loc);
5420
  ```
5421
 
5422
- If the file is not positioned at its beginning and the encoding of the
5423
- current locale as determined by `a_codecvt.encoding()` is
5424
- state-dependent ([[locale.codecvt.virtuals]]) then that facet is the
5425
  same as the corresponding facet of `loc`.
5426
 
5427
  *Effects:* Causes characters inserted or extracted after this call to be
5428
  converted according to `loc` until another call of `imbue`.
5429
 
5430
- This may require reconversion of previously converted characters. This
5431
- in turn may require the implementation to be able to reconstruct the
5432
- original contents of the file.
5433
 
5434
- #### Class template `basic_ifstream` <a id="ifstream">[[ifstream]]</a>
5435
 
5436
  ``` cpp
5437
  namespace std {
5438
  template <class charT, class traits = char_traits<charT>>
5439
  class basic_ifstream : public basic_istream<charT, traits> {
5440
  public:
5441
- typedef charT char_type;
5442
- typedef typename traits::int_type int_type;
5443
- typedef typename traits::pos_type pos_type;
5444
- typedef typename traits::off_type off_type;
5445
- typedef traits traits_type;
5446
 
5447
- // [ifstream.cons] Constructors:
5448
  basic_ifstream();
5449
  explicit basic_ifstream(const char* s,
5450
  ios_base::openmode mode = ios_base::in);
 
 
5451
  explicit basic_ifstream(const string& s,
5452
  ios_base::openmode mode = ios_base::in);
 
 
5453
  basic_ifstream(const basic_ifstream& rhs) = delete;
5454
  basic_ifstream(basic_ifstream&& rhs);
5455
 
5456
- // [ifstream.assign] Assign/swap:
5457
  basic_ifstream& operator=(const basic_ifstream& rhs) = delete;
5458
  basic_ifstream& operator=(basic_ifstream&& rhs);
5459
  void swap(basic_ifstream& rhs);
5460
 
5461
- // [ifstream.members] Members:
5462
  basic_filebuf<charT, traits>* rdbuf() const;
5463
 
5464
  bool is_open() const;
5465
  void open(const char* s, ios_base::openmode mode = ios_base::in);
 
 
5466
  void open(const string& s, ios_base::openmode mode = ios_base::in);
 
5467
  void close();
5468
  private:
5469
  basic_filebuf<charT, traits> sb; // exposition only
5470
  };
5471
 
@@ -5486,18 +5583,20 @@ presented here as:
5486
 
5487
  ``` cpp
5488
  basic_ifstream();
5489
  ```
5490
 
5491
- *Effects:* Constructs an object of class `basic_ifstream<charT,traits>`,
5492
- initializing the base class with `basic_istream(&sb)` and initializing
5493
- `sb` with `basic_filebuf<charT,traits>())` ([[istream.cons]],
5494
- [[filebuf.cons]]).
5495
 
5496
  ``` cpp
5497
  explicit basic_ifstream(const char* s,
5498
  ios_base::openmode mode = ios_base::in);
 
 
5499
  ```
5500
 
5501
  *Effects:* Constructs an object of class `basic_ifstream`, initializing
5502
  the base class with `basic_istream(&sb)` and initializing `sb` with
5503
  `basic_filebuf<charT, traits>())` ([[istream.cons]], [[filebuf.cons]]),
@@ -5505,13 +5604,15 @@ then calls `rdbuf()->open(s, mode | ios_base::in)`. If that function
5505
  returns a null pointer, calls `setstate(failbit)`.
5506
 
5507
  ``` cpp
5508
  explicit basic_ifstream(const string& s,
5509
  ios_base::openmode mode = ios_base::in);
 
 
5510
  ```
5511
 
5512
- *Effects:* the same as `basic_ifstream(s.c_str(), mode)`.
5513
 
5514
  ``` cpp
5515
  basic_ifstream(basic_ifstream&& rhs);
5516
  ```
5517
 
@@ -5542,11 +5643,11 @@ void swap(basic_ifstream& rhs);
5542
  template <class charT, class traits>
5543
  void swap(basic_ifstream<charT, traits>& x,
5544
  basic_ifstream<charT, traits>& y);
5545
  ```
5546
 
5547
- *Effects:* `x.swap(y)`.
5548
 
5549
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
5550
 
5551
  ``` cpp
5552
  basic_filebuf<charT, traits>* rdbuf() const;
@@ -5560,64 +5661,74 @@ bool is_open() const;
5560
 
5561
  *Returns:* `rdbuf()->is_open()`.
5562
 
5563
  ``` cpp
5564
  void open(const char* s, ios_base::openmode mode = ios_base::in);
 
 
5565
  ```
5566
 
5567
  *Effects:* Calls `rdbuf()->open(s, mode | ios_base::in)`. If that
5568
  function does not return a null pointer calls `clear()`, otherwise calls
5569
- `setstate(failbit)` (which may throw `ios_base::failure`
5570
- ([[iostate.flags]])).
5571
 
5572
  ``` cpp
5573
  void open(const string& s, ios_base::openmode mode = ios_base::in);
 
5574
  ```
5575
 
5576
- *Effects:* calls `open(s.c_str(), mode)`.
5577
 
5578
  ``` cpp
5579
  void close();
5580
  ```
5581
 
5582
  *Effects:* Calls `rdbuf()->close()` and, if that function returns a null
5583
  pointer, calls `setstate(failbit)` (which may throw
5584
- `ios_base::failure` ([[iostate.flags]])).
5585
 
5586
- #### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
5587
 
5588
  ``` cpp
5589
  namespace std {
5590
  template <class charT, class traits = char_traits<charT>>
5591
  class basic_ofstream : public basic_ostream<charT, traits> {
5592
  public:
5593
- typedef charT char_type;
5594
- typedef typename traits::int_type int_type;
5595
- typedef typename traits::pos_type pos_type;
5596
- typedef typename traits::off_type off_type;
5597
- typedef traits traits_type;
5598
 
5599
- // [ofstream.cons] Constructors:
5600
  basic_ofstream();
5601
  explicit basic_ofstream(const char* s,
5602
  ios_base::openmode mode = ios_base::out);
 
 
5603
  explicit basic_ofstream(const string& s,
5604
  ios_base::openmode mode = ios_base::out);
 
 
5605
  basic_ofstream(const basic_ofstream& rhs) = delete;
5606
  basic_ofstream(basic_ofstream&& rhs);
5607
 
5608
- // [ofstream.assign] Assign/swap:
5609
  basic_ofstream& operator=(const basic_ofstream& rhs) = delete;
5610
  basic_ofstream& operator=(basic_ofstream&& rhs);
5611
  void swap(basic_ofstream& rhs);
5612
 
5613
- // [ofstream.members] Members:
5614
  basic_filebuf<charT, traits>* rdbuf() const;
5615
 
5616
  bool is_open() const;
5617
  void open(const char* s, ios_base::openmode mode = ios_base::out);
 
 
5618
  void open(const string& s, ios_base::openmode mode = ios_base::out);
 
5619
  void close();
5620
  private:
5621
  basic_filebuf<charT, traits> sb; // exposition only
5622
  };
5623
 
@@ -5638,32 +5749,37 @@ presented here as:
5638
 
5639
  ``` cpp
5640
  basic_ofstream();
5641
  ```
5642
 
5643
- *Effects:* Constructs an object of class `basic_ofstream<charT,traits>`,
5644
- initializing the base class with `basic_ostream(&sb)` and initializing
5645
- `sb` with `basic_filebuf<charT,traits>())` ([[ostream.cons]],
5646
- [[filebuf.cons]]).
5647
 
5648
  ``` cpp
5649
  explicit basic_ofstream(const char* s,
5650
  ios_base::openmode mode = ios_base::out);
 
 
5651
  ```
5652
 
5653
- *Effects:* Constructs an object of class `basic_ofstream<charT,traits>`,
5654
- initializing the base class with `basic_ostream(&sb)` and initializing
5655
- `sb` with `basic_filebuf<charT,traits>())` ([[ostream.cons]],
5656
- [[filebuf.cons]]), then calls `rdbuf()->open(s, mode|ios_base::out)`. If
5657
- that function returns a null pointer, calls `setstate(failbit)`.
 
5658
 
5659
  ``` cpp
5660
  explicit basic_ofstream(const string& s,
5661
  ios_base::openmode mode = ios_base::out);
 
 
5662
  ```
5663
 
5664
- *Effects:* the same as `basic_ofstream(s.c_str(), mode);`
5665
 
5666
  ``` cpp
5667
  basic_ofstream(basic_ofstream&& rhs);
5668
  ```
5669
 
@@ -5694,11 +5810,11 @@ void swap(basic_ofstream& rhs);
5694
  template <class charT, class traits>
5695
  void swap(basic_ofstream<charT, traits>& x,
5696
  basic_ofstream<charT, traits>& y);
5697
  ```
5698
 
5699
- *Effects:* `x.swap(y)`.
5700
 
5701
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
5702
 
5703
  ``` cpp
5704
  basic_filebuf<charT, traits>* rdbuf() const;
@@ -5712,66 +5828,83 @@ bool is_open() const;
5712
 
5713
  *Returns:* `rdbuf()->is_open()`.
5714
 
5715
  ``` cpp
5716
  void open(const char* s, ios_base::openmode mode = ios_base::out);
 
 
5717
  ```
5718
 
5719
  *Effects:* Calls `rdbuf()->open(s, mode | ios_base::out)`. If that
5720
  function does not return a null pointer calls `clear()`, otherwise calls
5721
- `setstate(failbit)` (which may throw `ios_base::failure`
5722
- ([[iostate.flags]])).
5723
 
5724
  ``` cpp
5725
  void close();
5726
  ```
5727
 
5728
  *Effects:* Calls `rdbuf()->close()` and, if that function fails (returns
5729
  a null pointer), calls `setstate(failbit)` (which may throw
5730
- `ios_base::failure` ([[iostate.flags]])).
5731
 
5732
  ``` cpp
5733
  void open(const string& s, ios_base::openmode mode = ios_base::out);
 
5734
  ```
5735
 
5736
- *Effects:* calls `open(s.c_str(), mode);`
5737
 
5738
- #### Class template `basic_fstream` <a id="fstream">[[fstream]]</a>
5739
 
5740
  ``` cpp
5741
  namespace std {
5742
  template <class charT, class traits = char_traits<charT>>
5743
- class basic_fstream
5744
- : public basic_iostream<charT,traits> {
5745
-
5746
  public:
5747
- typedef charT char_type;
5748
- typedef typename traits::int_type int_type;
5749
- typedef typename traits::pos_type pos_type;
5750
- typedef typename traits::off_type off_type;
5751
- typedef traits traits_type;
5752
 
5753
- // constructors/destructor
5754
  basic_fstream();
5755
- explicit basic_fstream(const char* s,
 
5756
  ios_base::openmode mode = ios_base::in | ios_base::out);
5757
- explicit basic_fstream(const string& s,
 
 
 
 
 
 
 
5758
  ios_base::openmode mode = ios_base::in | ios_base::out);
5759
  basic_fstream(const basic_fstream& rhs) = delete;
5760
  basic_fstream(basic_fstream&& rhs);
5761
 
5762
- // [fstream.assign] Assign/swap:
5763
  basic_fstream& operator=(const basic_fstream& rhs) = delete;
5764
  basic_fstream& operator=(basic_fstream&& rhs);
5765
  void swap(basic_fstream& rhs);
5766
 
5767
- // Members:
5768
  basic_filebuf<charT, traits>* rdbuf() const;
5769
  bool is_open() const;
5770
- void open(const char* s,
 
5771
  ios_base::openmode mode = ios_base::in | ios_base::out);
5772
- void open(const string& s,
 
 
 
 
 
 
 
5773
  ios_base::openmode mode = ios_base::in | ios_base::out);
5774
  void close();
5775
 
5776
  private:
5777
  basic_filebuf<charT, traits> sb; // exposition only
@@ -5782,13 +5915,13 @@ namespace std {
5782
  basic_fstream<charT, traits>& y);
5783
  }
5784
  ```
5785
 
5786
  The class template `basic_fstream<charT, traits>` supports reading and
5787
- writing from named files. It uses a `basic_filebuf<charT,traits>` object
5788
- to control the associated sequences. For the sake of exposition, the
5789
- maintained data is presented here as:
5790
 
5791
  - `sb`, the `basic_filebuf` object.
5792
 
5793
  #### `basic_fstream` constructors <a id="fstream.cons">[[fstream.cons]]</a>
5794
 
@@ -5799,26 +5932,34 @@ basic_fstream();
5799
  *Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
5800
  initializing the base class with `basic_iostream(&sb)` and initializing
5801
  `sb` with `basic_filebuf<charT, traits>()`.
5802
 
5803
  ``` cpp
5804
- explicit basic_fstream(const char* s,
 
5805
  ios_base::openmode mode = ios_base::in | ios_base::out);
 
 
 
5806
  ```
5807
 
5808
  *Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
5809
  initializing the base class with `basic_iostream(&sb)` and initializing
5810
  `sb` with `basic_filebuf<charT, traits>()`. Then calls
5811
  `rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
5812
  `setstate(failbit)`.
5813
 
5814
  ``` cpp
5815
- explicit basic_fstream(const string& s,
 
 
 
 
5816
  ios_base::openmode mode = ios_base::in | ios_base::out);
5817
  ```
5818
 
5819
- *Effects:* the same as `basic_fstream(s.c_str(), mode);`
5820
 
5821
  ``` cpp
5822
  basic_fstream(basic_fstream&& rhs);
5823
  ```
5824
 
@@ -5849,11 +5990,11 @@ void swap(basic_fstream& rhs);
5849
  template <class charT, class traits>
5850
  void swap(basic_fstream<charT, traits>& x,
5851
  basic_fstream<charT, traits>& y);
5852
  ```
5853
 
5854
- *Effects:* `x.swap(y)`.
5855
 
5856
  #### Member functions <a id="fstream.members">[[fstream.members]]</a>
5857
 
5858
  ``` cpp
5859
  basic_filebuf<charT, traits>* rdbuf() const;
@@ -5866,54 +6007,4248 @@ bool is_open() const;
5866
  ```
5867
 
5868
  *Returns:* `rdbuf()->is_open()`.
5869
 
5870
  ``` cpp
5871
- void open(const char* s,
 
5872
  ios_base::openmode mode = ios_base::in | ios_base::out);
 
 
 
5873
  ```
5874
 
5875
  *Effects:* Calls `rdbuf()->open(s, mode)`. If that function does not
5876
  return a null pointer calls `clear()`, otherwise calls
5877
- `setstate(failbit)`, (which may throw
5878
  `ios_base::failure`) ([[iostate.flags]]).
5879
 
5880
  ``` cpp
5881
- void open(const string& s,
 
 
 
 
5882
  ios_base::openmode mode = ios_base::in | ios_base::out);
5883
  ```
5884
 
5885
- *Effects:* calls `open(s.c_str(), mode);`
5886
 
5887
  ``` cpp
5888
  void close();
5889
  ```
5890
 
5891
- *Effects:* Calls `rdbuf()->close()` and, if that function returns
5892
- returns a null pointer, calls `setstate(failbit)` ([[iostate.flags]])
5893
- (which may throw `ios_base::failure`).
5894
 
5895
- ### C library files <a id="c.files">[[c.files]]</a>
5896
 
5897
- Table  [[tab:iostreams.hdr.cstdio]] describes header `<cstdio>`. C++does
5898
- not define the function `gets`.
5899
 
5900
- Calls to the function `tmpnam` with an argument of `NULL` may introduce
5901
- a data race ([[res.on.data.races]]) with other calls to `tmpnam` with
5902
- an argument of `NULL`.
5903
 
5904
- ISO C 7.9, Amendment 1 4.6.2.
5905
 
5906
- Table  [[tab:iostreams.hdr.cinttypes]] describes header `<cinttypes>`.
5907
- The macros defined by `<cinttypes>` are provided unconditionally. In
5908
- particular, the symbol `__STDC_FORMAT_MACROS`, mentioned in footnote 182
5909
- of the C standard, plays no role in C++.
5910
 
5911
- The contents of header `<cinttypes>` are the same as the Standard C
5912
- Library header `<inttypes.h>`, with the following changes:
5913
 
5914
- - the header `<cinttypes>` includes the header `<cstdint>` instead of
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5915
  `<stdint.h>`, and
5916
  - if and only if the type `intmax_t` designates an extended integer
5917
  type ([[basic.fundamental]]), the following function signatures are
5918
  added:
5919
  ``` cpp
@@ -5923,97 +10258,220 @@ Library header `<inttypes.h>`, with the following changes:
5923
 
5924
  which shall have the same semantics as the function signatures
5925
  `intmax_t imaxabs(intmax_t)` and
5926
  `imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
5927
 
 
 
5928
  <!-- Link reference definitions -->
5929
  [adjustfield.manip]: #adjustfield.manip
 
5930
  [basefield.manip]: #basefield.manip
5931
  [basic.fundamental]: basic.md#basic.fundamental
5932
  [basic.ios.cons]: #basic.ios.cons
5933
  [basic.ios.members]: #basic.ios.members
 
 
5934
  [bitmask.types]: library.md#bitmask.types
5935
  [c.files]: #c.files
 
 
 
5936
  [enumerated.types]: library.md#enumerated.types
5937
  [error.reporting]: #error.reporting
5938
  [ext.manip]: #ext.manip
5939
  [fig:streampos]: #fig:streampos
5940
  [file.streams]: #file.streams
5941
  [filebuf]: #filebuf
5942
  [filebuf.assign]: #filebuf.assign
5943
  [filebuf.cons]: #filebuf.cons
5944
  [filebuf.members]: #filebuf.members
5945
  [filebuf.virtuals]: #filebuf.virtuals
 
 
5946
  [floatfield.manip]: #floatfield.manip
5947
  [fmtflags.manip]: #fmtflags.manip
5948
  [fmtflags.state]: #fmtflags.state
5949
  [fpos]: #fpos
5950
  [fpos.members]: #fpos.members
5951
  [fpos.operations]: #fpos.operations
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5952
  [fstream]: #fstream
5953
  [fstream.assign]: #fstream.assign
5954
  [fstream.cons]: #fstream.cons
5955
  [fstream.members]: #fstream.members
5956
- [fstreams]: #fstreams
5957
  [ifstream]: #ifstream
5958
  [ifstream.assign]: #ifstream.assign
5959
  [ifstream.cons]: #ifstream.cons
5960
  [ifstream.members]: #ifstream.members
 
5961
  [input.output]: #input.output
5962
  [input.output.general]: #input.output.general
5963
  [input.streams]: #input.streams
5964
  [intro.multithread]: intro.md#intro.multithread
 
5965
  [ios]: #ios
5966
  [ios.base]: #ios.base
5967
  [ios.base.callback]: #ios.base.callback
5968
  [ios.base.cons]: #ios.base.cons
5969
  [ios.base.locales]: #ios.base.locales
5970
  [ios.base.storage]: #ios.base.storage
5971
  [ios.members.static]: #ios.members.static
5972
  [ios.overview]: #ios.overview
 
5973
  [ios.types]: #ios.types
5974
  [ios::Init]: #ios::Init
5975
  [ios::failure]: #ios::failure
5976
  [ios::fmtflags]: #ios::fmtflags
5977
  [ios::iostate]: #ios::iostate
5978
  [ios::openmode]: #ios::openmode
5979
  [ios::seekdir]: #ios::seekdir
 
5980
  [iostate.flags]: #iostate.flags
5981
  [iostream.assign]: #iostream.assign
5982
  [iostream.cons]: #iostream.cons
5983
  [iostream.dest]: #iostream.dest
5984
  [iostream.format]: #iostream.format
5985
- [iostream.format.overview]: #iostream.format.overview
5986
  [iostream.forward]: #iostream.forward
 
5987
  [iostream.limits.imbue]: #iostream.limits.imbue
5988
  [iostream.objects]: #iostream.objects
5989
  [iostream.objects.overview]: #iostream.objects.overview
 
5990
  [iostreamclass]: #iostreamclass
5991
  [iostreams.base]: #iostreams.base
5992
- [iostreams.base.overview]: #iostreams.base.overview
5993
  [iostreams.limits.pos]: #iostreams.limits.pos
5994
  [iostreams.requirements]: #iostreams.requirements
5995
  [iostreams.threadsafety]: #iostreams.threadsafety
5996
  [istream]: #istream
5997
  [istream.assign]: #istream.assign
5998
  [istream.cons]: #istream.cons
 
5999
  [istream.formatted]: #istream.formatted
6000
  [istream.formatted.arithmetic]: #istream.formatted.arithmetic
6001
  [istream.formatted.reqmts]: #istream.formatted.reqmts
6002
  [istream.manip]: #istream.manip
6003
  [istream.rvalue]: #istream.rvalue
 
6004
  [istream.unformatted]: #istream.unformatted
6005
- [istream::extractors]: #istream::extractors
6006
  [istream::sentry]: #istream::sentry
6007
  [istringstream]: #istringstream
6008
  [istringstream.assign]: #istringstream.assign
6009
  [istringstream.cons]: #istringstream.cons
6010
  [istringstream.members]: #istringstream.members
6011
- [limits]: language.md#limits
6012
  [locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
6013
  [locale.num.get]: localization.md#locale.num.get
6014
  [narrow.stream.objects]: #narrow.stream.objects
 
6015
  [ofstream]: #ofstream
6016
  [ofstream.assign]: #ofstream.assign
6017
  [ofstream.cons]: #ofstream.cons
6018
  [ofstream.members]: #ofstream.members
6019
  [ostream]: #ostream
@@ -6025,24 +10483,25 @@ Library header `<inttypes.h>`, with the following changes:
6025
  [ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
6026
  [ostream.inserters.character]: #ostream.inserters.character
6027
  [ostream.manip]: #ostream.manip
6028
  [ostream.rvalue]: #ostream.rvalue
6029
  [ostream.seeks]: #ostream.seeks
 
6030
  [ostream.unformatted]: #ostream.unformatted
6031
  [ostream::sentry]: #ostream::sentry
6032
  [ostringstream]: #ostringstream
6033
  [ostringstream.assign]: #ostringstream.assign
6034
  [ostringstream.cons]: #ostringstream.cons
6035
  [ostringstream.members]: #ostringstream.members
6036
  [output.streams]: #output.streams
6037
  [quoted.manip]: #quoted.manip
6038
  [res.on.data.races]: library.md#res.on.data.races
6039
  [res.on.exception.handling]: library.md#res.on.exception.handling
 
6040
  [std.ios.manip]: #std.ios.manip
6041
  [std.manip]: #std.manip
6042
  [stream.buffers]: #stream.buffers
6043
- [stream.buffers.overview]: #stream.buffers.overview
6044
  [stream.types]: #stream.types
6045
  [streambuf]: #streambuf
6046
  [streambuf.assign]: #streambuf.assign
6047
  [streambuf.buffer]: #streambuf.buffer
6048
  [streambuf.cons]: #streambuf.cons
@@ -6053,44 +10512,53 @@ Library header `<inttypes.h>`, with the following changes:
6053
  [streambuf.pub.get]: #streambuf.pub.get
6054
  [streambuf.pub.pback]: #streambuf.pub.pback
6055
  [streambuf.pub.put]: #streambuf.pub.put
6056
  [streambuf.put.area]: #streambuf.put.area
6057
  [streambuf.reqts]: #streambuf.reqts
 
6058
  [streambuf.virt.buffer]: #streambuf.virt.buffer
6059
  [streambuf.virt.get]: #streambuf.virt.get
6060
  [streambuf.virt.locales]: #streambuf.virt.locales
6061
  [streambuf.virt.pback]: #streambuf.virt.pback
6062
  [streambuf.virt.put]: #streambuf.virt.put
6063
  [streambuf.virtuals]: #streambuf.virtuals
6064
  [string.classes]: strings.md#string.classes
6065
  [string.streams]: #string.streams
6066
- [string.streams.overview]: #string.streams.overview
6067
  [stringbuf]: #stringbuf
6068
  [stringbuf.assign]: #stringbuf.assign
6069
  [stringbuf.cons]: #stringbuf.cons
6070
  [stringbuf.members]: #stringbuf.members
6071
  [stringbuf.virtuals]: #stringbuf.virtuals
6072
  [strings]: strings.md#strings
6073
  [stringstream]: #stringstream
6074
  [stringstream.assign]: #stringstream.assign
6075
  [stringstream.cons]: #stringstream.cons
6076
  [stringstream.members]: #stringstream.members
 
 
 
 
 
 
 
 
 
6077
  [tab:iostreams.basicios.init.effects]: #tab:iostreams.basicios.init.effects
6078
  [tab:iostreams.copyfmt.effects]: #tab:iostreams.copyfmt.effects
6079
  [tab:iostreams.file.open.modes]: #tab:iostreams.file.open.modes
6080
  [tab:iostreams.fmtflags.constants]: #tab:iostreams.fmtflags.constants
6081
  [tab:iostreams.fmtflags.effects]: #tab:iostreams.fmtflags.effects
6082
- [tab:iostreams.hdr.cinttypes]: #tab:iostreams.hdr.cinttypes
6083
- [tab:iostreams.hdr.cstdio]: #tab:iostreams.hdr.cstdio
6084
  [tab:iostreams.iostate.effects]: #tab:iostreams.iostate.effects
6085
  [tab:iostreams.lib.summary]: #tab:iostreams.lib.summary
6086
  [tab:iostreams.newoff.values]: #tab:iostreams.newoff.values
6087
  [tab:iostreams.openmode.effects]: #tab:iostreams.openmode.effects
6088
  [tab:iostreams.position.requirements]: #tab:iostreams.position.requirements
6089
  [tab:iostreams.seekdir.effects]: #tab:iostreams.seekdir.effects
6090
  [tab:iostreams.seekoff.effects]: #tab:iostreams.seekoff.effects
6091
  [tab:iostreams.seekoff.positioning]: #tab:iostreams.seekoff.positioning
 
 
6092
  [wide.stream.objects]: #wide.stream.objects
6093
 
6094
  [^1]: It is the implementation’s responsibility to implement headers so
6095
  that including `<iosfwd>` and other headers does not violate the
6096
  rules about multiple occurrences of default arguments.
@@ -6124,11 +10592,11 @@ Library header `<inttypes.h>`, with the following changes:
6124
 
6125
  [^9]: for example, because it cannot allocate space.
6126
 
6127
  [^10]: This suggests an infinite amount of copying, but the
6128
  implementation can keep track of the maximum element of the arrays
6129
- that is non-zero.
6130
 
6131
  [^11]: Checking `badbit` also for `fail()` is historical practice.
6132
 
6133
  [^12]: The function signature `dec(ios_base&)` can be called by the
6134
  function signature
@@ -6140,91 +10608,99 @@ Library header `<inttypes.h>`, with the following changes:
6140
  to assure that only objects for classes derived from this class may
6141
  be constructed.
6142
 
6143
  [^14]: `underflow` or `uflow` might fail by throwing an exception
6144
  prematurely. The intention is not only that the calls will not
6145
- return `eof()` but that they will return “immediately.
6146
 
6147
  [^15]: Classes derived from `basic_streambuf` can provide more efficient
6148
  ways to implement `xsgetn()` and `xsputn()` by overriding these
6149
  definitions from the base class.
6150
 
6151
- [^16]: Typically, `overflow` returns `c` to indicate success, except
6152
- when `traits::eq_int_type(c,traits::eof())` returns `true`, in which
6153
- case it returns `traits::not_eof(c)`.
 
 
6154
 
6155
- [^17]: This will be possible only in functions that are part of the
 
 
 
 
6156
  library. The semantics of the constructor used in user code is as
6157
  specified.
6158
 
6159
- [^18]: The sentry constructor and destructor can also perform additional
6160
  implementation-dependent operations.
6161
 
6162
- [^19]: This is done without causing an `ios::failure` to be thrown.
6163
-
6164
- [^20]: See, for example, the function signature
6165
- `ws(basic_istream&)` ([[istream.manip]]).
6166
 
6167
  [^21]: See, for example, the function signature
 
 
 
6168
  `dec(ios_base&)` ([[basefield.manip]]).
6169
 
6170
- [^22]: This is done without causing an `ios::failure` to be thrown.
6171
-
6172
- [^23]: Note that this function is not overloaded on types `signed char`
6173
- and `unsigned char`.
6174
 
6175
  [^24]: Note that this function is not overloaded on types `signed char`
6176
  and `unsigned char`.
6177
 
6178
  [^25]: Note that this function is not overloaded on types `signed char`
6179
  and `unsigned char`.
6180
 
6181
- [^26]: Since the final input character is “extracted,” it is counted in
 
 
 
6182
  the `gcount()`, even though it is not stored.
6183
 
6184
- [^27]: This allows an input line which exactly fills the buffer, without
6185
  setting `failbit`. This is different behavior than the historical
6186
  AT&T implementation.
6187
 
6188
- [^28]: This implies an empty input line will not cause `failbit` to be
6189
  set.
6190
 
6191
- [^29]: Note that this function is not overloaded on types `signed char`
6192
  and `unsigned char`.
6193
 
6194
- [^30]: The call `os.tie()->flush()` does not necessarily occur if the
6195
  function can determine that no synchronization is necessary.
6196
 
6197
- [^31]: The `sentry` constructor and destructor can also perform
6198
  additional implementation-dependent operations.
6199
 
6200
- [^32]: without causing an `ios::failure` to be thrown.
6201
-
6202
- [^33]: See, for example, the function signature
6203
- `endl(basic_ostream&)` ([[ostream.manip]]).
6204
 
6205
  [^34]: See, for example, the function signature
 
 
 
6206
  `dec(ios_base&)` ([[basefield.manip]]).
6207
 
6208
- [^35]: without causing an `ios::failure` to be thrown.
6209
-
6210
- [^36]: Note that this function is not overloaded on types `signed char`
6211
- and `unsigned char`.
6212
 
6213
  [^37]: Note that this function is not overloaded on types `signed char`
6214
  and `unsigned char`.
6215
 
6216
- [^38]: The expression `cin >>resetiosflags(ios_base::skipws)` clears
 
 
 
6217
  `ios_base::skipws` in the format flags stored in the
6218
  `basic_istream<charT, traits>` object `cin` (the same as
6219
  `cin >> noskipws`), and the expression
6220
  `cout << resetiosflags(ios_base::showbase)` clears
6221
  `ios_base::showbase` in the format flags stored in the
6222
  `basic_ostream<charT, traits>` object `cout` (the same as
6223
  `cout << noshowbase`).
6224
 
6225
- [^39]: The macro `SEEK_END` is defined, and the function signatures
6226
  `fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
6227
- declared, in `<cstdio>` ([[c.files]]).
6228
 
6229
- [^40]: The function signature `fclose(FILE*)` is declared in `<cstdio>`
6230
- ([[c.files]]).
 
 
 
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
 
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.
82
 
83
  ## Forward declarations <a id="iostream.forward">[[iostream.forward]]</a>
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>;
 
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
 
135
+ using ios = basic_ios<char>;
136
+ using wios = basic_ios<wchar_t>;
137
 
138
+ using streambuf = basic_streambuf<char>;
139
+ using istream = basic_istream<char>;
140
+ using ostream = basic_ostream<char>;
141
+ using iostream = basic_iostream<char>;
142
 
143
+ using stringbuf = basic_stringbuf<char>;
144
+ using istringstream = basic_istringstream<char>;
145
+ using ostringstream = basic_ostringstream<char>;
146
+ using stringstream = basic_stringstream<char>;
147
 
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
 
158
+ using wstringbuf = basic_stringbuf<wchar_t>;
159
+ using wistringstream = basic_istringstream<wchar_t>;
160
+ using wostringstream = basic_ostringstream<wchar_t>;
161
+ using wstringstream = basic_stringstream<wchar_t>;
162
 
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
176
  both `<iosfwd>` and one or more of the other headers.[^1]
177
 
178
+ ### Overview <a id="iostream.forward.overview">[[iostream.forward.overview]]</a>
179
+
180
  The class template specialization `basic_ios<charT, traits>` serves as a
181
  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`.
 
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
 
234
  ``` cpp
235
+ #include <ios> // see [ios.syn]
236
+ #include <streambuf> // see [streambuf.syn]
237
+ #include <istream> // see [istream.syn]
238
+ #include <ostream> // see [ostream.syn]
239
 
240
  namespace std {
241
  extern istream cin;
242
  extern ostream cout;
243
  extern ostream cerr;
 
248
  extern wostream wcerr;
249
  extern wostream wclog;
250
  }
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
 
366
  ``` cpp
367
+ #include <iosfwd> // see [iosfwd.syn]
368
 
369
  namespace std {
370
+ using streamoff = implementation-defined;
371
+ using streamsize = implementation-defined;
372
  template <class stateT> class fpos;
373
 
374
  class ios_base;
375
  template <class charT, class traits = char_traits<charT>>
376
  class basic_ios;
377
 
378
+ // [std.ios.manip], manipulators
379
  ios_base& boolalpha (ios_base& str);
380
  ios_base& noboolalpha(ios_base& str);
381
 
382
  ios_base& showbase (ios_base& str);
383
  ios_base& noshowbase (ios_base& str);
 
395
  ios_base& nouppercase(ios_base& str);
396
 
397
  ios_base& unitbuf (ios_base& str);
398
  ios_base& nounitbuf (ios_base& str);
399
 
400
+ // [adjustfield.manip], adjustfield
401
  ios_base& internal (ios_base& str);
402
  ios_base& left (ios_base& str);
403
  ios_base& right (ios_base& str);
404
 
405
+ // [basefield.manip], basefield
406
  ios_base& dec (ios_base& str);
407
  ios_base& hex (ios_base& str);
408
  ios_base& oct (ios_base& str);
409
 
410
+ // [floatfield.manip], floatfield
411
  ios_base& fixed (ios_base& str);
412
  ios_base& scientific (ios_base& str);
413
  ios_base& hexfloat (ios_base& str);
414
  ios_base& defaultfloat(ios_base& str);
415
 
416
+ // [error.reporting], error reporting
417
  enum class io_errc {
418
  stream = 1
419
  };
420
 
421
  template <> struct is_error_code_enum<io_errc> : public true_type { };
 
426
  ```
427
 
428
  ### Types <a id="stream.types">[[stream.types]]</a>
429
 
430
  ``` cpp
431
+ using streamoff = implementation-defined;
432
  ```
433
 
434
  The type `streamoff` is a synonym for one of the signed basic integral
435
  types of sufficient size to represent the maximum possible file size for
436
  the operating system.[^4]
437
 
438
  ``` cpp
439
+ using streamsize = implementation-defined;
440
  ```
441
 
442
  The type `streamsize` is a synonym for one of the signed basic integral
443
  types. It is used to represent the number of characters transferred in
444
  an I/O operation, or the size of I/O buffers.[^5]
 
447
 
448
  ``` cpp
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;
460
  static constexpr fmtflags internal = unspecified;
 
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
 
497
  class Init;
498
 
499
+ // [fmtflags.state], fmtflags state
500
  fmtflags flags() const;
501
  fmtflags flags(fmtflags fmtfl);
502
  fmtflags setf(fmtflags fmtfl);
503
  fmtflags setf(fmtflags fmtfl, fmtflags mask);
504
  void unsetf(fmtflags mask);
 
506
  streamsize precision() const;
507
  streamsize precision(streamsize prec);
508
  streamsize width() const;
509
  streamsize width(streamsize wide);
510
 
511
+ // [ios.base.locales], locales
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
 
 
543
 
544
  `ios_base`
545
 
546
  defines several member types:
547
 
548
+ - a type `failure`, defined as either a class derived from
549
+ `system_error` or a synonym for a class derived from `system_error`;
550
  - a class `Init`;
551
  - three bitmask types, `fmtflags`, `iostate`, and `openmode`;
552
  - an enumerated type, `seekdir`.
553
 
554
  It maintains several kinds of data:
 
557
  - control information that influences how to interpret (format) input
558
  sequences and how to generate (format) output sequences;
559
  - additional information that is stored by the program for its private
560
  use.
561
 
562
+ [*Note 1*:
563
+
564
  For the sake of exposition, the maintained data is presented here as:
565
 
566
  - `static int index`, specifies the next available unique index for the
567
  integer or pointer arrays maintained for the private use of the
568
  program, initialized to an unspecified value;
569
  - `long* iarray`, points to the first element of an arbitrary-length
570
  `long` array maintained for the private use of the program;
571
  - `void** parray`, points to the first element of an arbitrary-length
572
  pointer array maintained for the private use of the program.
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
 
585
  explicit failure(const char* msg, const error_code& ec = io_errc::stream);
586
  };
587
  }
588
  ```
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
 
602
  When throwing `ios_base::failure` exceptions, implementations should
603
  provide values of `ec` that identify the specific reason for the
604
+ failure.
605
+
606
+ [*Note 2*: Errors arising from the operating system would typically be
607
  reported as `system_category()` errors with an error value of the error
608
  number reported by the operating system. Errors arising from within the
609
  stream library would typically be reported as
610
  `error_code(io_errc::stream,
611
+ iostream_category())`. — *end note*]
612
 
613
  ``` cpp
614
  explicit failure(const string& msg, const error_code& ec = io_errc::stream);
615
  ```
616
 
 
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]].
 
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
 
 
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
 
 
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]].
 
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.
 
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
 
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
 
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
 
 
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
 
 
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
880
  allows the standard streams to operate independently of the standard C
881
  streams.
882
 
883
  When a standard iostream object `str` is *synchronized* with a standard
884
  stdio stream `f`, the effect of inserting a character `c` by
 
942
  necessary to include the element `iarray[idx]`. Each newly allocated
943
  element of the array is initialized to zero. The reference returned is
944
  invalid after any other operations on the object.[^7] However, the value
945
  of the storage referred to is retained, so that until the next call to
946
  `copyfmt`, calling `iword` with the same index yields another reference
947
+ to the same value. If the function fails[^8] and `*this` is a base class
948
  subobject of a `basic_ios<>` object or subobject, the effect is
949
  equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
950
  object (which may throw `failure`).
951
 
952
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
 
963
  element of the array is initialized to a null pointer. The reference
964
  returned is invalid after any other operations on the object. However,
965
  the value of the storage referred to is retained, so that until the next
966
  call to `copyfmt`, calling `pword` with the same index yields another
967
  reference to the same value. If the function fails[^9] and `*this` is a
968
+ base class subobject of a `basic_ios<>` object or subobject, the effect
969
+ is equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
970
  object (which may throw `failure`).
971
 
972
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
973
  initialized to 0.
974
 
 
1017
 
1018
  ``` cpp
1019
  namespace std {
1020
  template <class stateT> class fpos {
1021
  public:
1022
+ // [fpos.members], members
1023
  stateT state() const;
1024
  void state(stateT);
1025
  private;
1026
  stateT st; // exposition only
1027
  };
 
1032
 
1033
  ``` cpp
1034
  void state(stateT s);
1035
  ```
1036
 
1037
+ *Effects:* Assigns `s` to `st`.
1038
 
1039
  ``` cpp
1040
  stateT state() const;
1041
  ```
1042
 
 
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
 
1073
  ``` cpp
1074
  namespace std {
1075
  template <class charT, class traits = char_traits<charT>>
1076
  class basic_ios : public ios_base {
1077
  public:
1078
+ using char_type = charT;
1079
+ using int_type = typename traits::int_type;
1080
+ using pos_type = typename traits::pos_type;
1081
+ using off_type = typename traits::off_type;
1082
+ using traits_type = traits;
1083
 
1084
+ // [iostate.flags], flags functions
 
 
 
 
 
 
1085
  explicit operator bool() const;
1086
  bool operator!() const;
1087
  iostate rdstate() const;
1088
  void clear(iostate state = goodbit);
1089
  void setstate(iostate state);
 
1093
  bool bad() const;
1094
 
1095
  iostate exceptions() const;
1096
  void exceptions(iostate except);
1097
 
1098
+ // [basic.ios.cons], constructor/destructor
1099
  explicit basic_ios(basic_streambuf<charT, traits>* sb);
1100
  virtual ~basic_ios();
1101
 
1102
+ // [basic.ios.members], members
1103
  basic_ostream<charT, traits>* tie() const;
1104
  basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
1105
 
1106
  basic_streambuf<charT, traits>* rdbuf() const;
1107
  basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
 
1172
  | `rdstate()` | `goodbit` if `sb` is not a null pointer, otherwise `badbit`. |
1173
  | `exceptions()` | `goodbit` |
1174
  | `flags()` | `skipws | dec` |
1175
  | `width()` | `0` |
1176
  | `precision()` | `6` |
1177
+ | `fill()` | `widen(' ')` |
1178
  | `getloc()` | a copy of the value returned by `locale()` |
1179
  | `iarray` | a null pointer |
1180
  | `parray` | a null pointer |
1181
 
1182
 
 
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
 
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
 
 
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);
 
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>
 
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);
 
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
 
 
1605
  *Effects:* Calls
1606
  `str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
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
 
 
1646
  object’s `name` virtual function shall return a pointer to the string
1647
  `"iostream"`.
1648
 
1649
  ## Stream buffers <a id="stream.buffers">[[stream.buffers]]</a>
1650
 
1651
+ ### Header `<streambuf>` synopsis <a id="streambuf.syn">[[streambuf.syn]]</a>
1652
 
1653
  ``` cpp
1654
  namespace std {
1655
  template <class charT, class traits = char_traits<charT>>
1656
  class basic_streambuf;
1657
+ using streambuf = basic_streambuf<char>;
1658
+ using wstreambuf = basic_streambuf<wchar_t>;
1659
  }
1660
  ```
1661
 
1662
  The header `<streambuf>` defines types that control input from and
1663
  output to *character* sequences.
 
1711
  - If `xnext` is not a null pointer and `xnext < xend` for an input
1712
  sequence, then a *read position* is available. In this case, `*xnext`
1713
  shall have a defined value and is the next element to read (to get, or
1714
  to obtain a character value, from the sequence).
1715
 
1716
+ ### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
1717
 
1718
  ``` cpp
1719
  namespace std {
1720
  template <class charT, class traits = char_traits<charT>>
1721
  class basic_streambuf {
1722
  public:
1723
+ using char_type = charT;
1724
+ using int_type = typename traits::int_type;
1725
+ using pos_type = typename traits::pos_type;
1726
+ using off_type = typename traits::off_type;
1727
+ using traits_type = traits;
 
 
1728
 
1729
  virtual ~basic_streambuf();
1730
 
1731
+ // [streambuf.locales], locales
1732
  locale pubimbue(const locale& loc);
1733
  locale getloc() const;
1734
 
1735
+ // [streambuf.buffer], buffer and positioning
1736
+ basic_streambuf* pubsetbuf(char_type* s, streamsize n);
 
1737
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
1738
+ ios_base::openmode which
1739
+ = ios_base::in | ios_base::out);
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();
1751
  streamsize sgetn(char_type* s, streamsize n);
1752
 
1753
+ // [streambuf.pub.pback], putback
1754
  int_type sputbackc(char_type c);
1755
  int_type sungetc();
1756
 
1757
+ // [streambuf.pub.put], put area
1758
  int_type sputc(char_type c);
1759
  streamsize sputn(const char_type* s, streamsize n);
1760
 
1761
  protected:
1762
  basic_streambuf();
1763
  basic_streambuf(const basic_streambuf& rhs);
1764
  basic_streambuf& operator=(const basic_streambuf& rhs);
1765
 
1766
  void swap(basic_streambuf& rhs);
1767
 
1768
+ // [streambuf.get.area], get area access
1769
  char_type* eback() const;
1770
  char_type* gptr() const;
1771
  char_type* egptr() const;
1772
  void gbump(int n);
1773
  void setg(char_type* gbeg, char_type* gnext, char_type* gend);
1774
 
1775
+ // [streambuf.put.area], put area access
1776
  char_type* pbase() const;
1777
  char_type* pptr() const;
1778
  char_type* epptr() const;
1779
  void pbump(int n);
1780
  void setp(char_type* pbeg, char_type* pend);
1781
 
1782
+ // [streambuf.virtuals], virtual functions
1783
+ // [streambuf.virt.locales], locales
1784
  virtual void imbue(const locale& loc);
1785
 
1786
+ // [streambuf.virt.buffer], buffer management and positioning
1787
+ virtual basic_streambuf* setbuf(char_type* s, streamsize n);
 
1788
  virtual pos_type seekoff(off_type off, ios_base::seekdir way,
1789
+ ios_base::openmode which
1790
+ = ios_base::in | ios_base::out);
1791
  virtual pos_type seekpos(pos_type sp,
1792
+ ios_base::openmode which
1793
+ = ios_base::in | ios_base::out);
1794
  virtual int sync();
1795
 
1796
+ // [streambuf.virt.get], get area
1797
  virtual streamsize showmanyc();
1798
  virtual streamsize xsgetn(char_type* s, streamsize n);
1799
  virtual int_type underflow();
1800
  virtual int_type uflow();
1801
 
1802
+ // [streambuf.virt.pback], putback
1803
  virtual int_type pbackfail(int_type c = traits::eof());
1804
 
1805
+ // [streambuf.virt.put], put area
1806
  virtual streamsize xsputn(const char_type* s, streamsize n);
1807
  virtual int_type overflow(int_type c = traits::eof());
1808
  };
1809
  }
1810
  ```
1811
 
1812
+ The class template `basic_streambuf` serves as an abstract base class
1813
+ 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
 
 
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
 
 
1880
  call of `imbue()`) then it returns the previous value.
1881
 
1882
  ##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
1883
 
1884
  ``` cpp
1885
+ basic_streambuf* pubsetbuf(char_type* s, streamsize n);
1886
  ```
1887
 
1888
  *Returns:* `setbuf(s, n)`.
1889
 
1890
  ``` cpp
1891
  pos_type pubseekoff(off_type off, ios_base::seekdir way,
1892
+ ios_base::openmode which
1893
+ = ios_base::in | ios_base::out);
1894
  ```
1895
 
1896
  *Returns:* `seekoff(off, way, which)`.
1897
 
1898
  ``` cpp
1899
  pos_type pubseekpos(pos_type sp,
1900
+ ios_base::openmode which
1901
+ = ios_base::in | ios_base::out);
1902
  ```
1903
 
1904
  *Returns:* `seekpos(sp, which)`.
1905
 
1906
  ``` cpp
 
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
 
2141
  *Effects:* Synchronizes the controlled sequences with the arrays. That
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
 
 
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.
2194
 
2195
+ The *pending sequence* of characters is defined as the concatenation of
2196
 
2197
+ - the empty sequence if `gptr()` is null, otherwise the characters in
2198
+ \[`gptr()`, `egptr()`), followed by
2199
+ - some (possibly empty) sequence of characters read from the input
2200
+ sequence.
2201
 
2202
+ The *result character* is the first character of the pending sequence if
2203
+ it is non-empty, otherwise the next character that would be read from
2204
+ the input sequence.
2205
 
2206
+ The *backup sequence* is the empty sequence if `eback()` is null,
2207
+ otherwise the characters in \[`eback()`, `gptr()`).
2208
+
2209
+ *Effects:* The function sets up the `gptr()` and `egptr()` such that if
2210
+ the pending sequence is non-empty, then `egptr()` is non-null and the
2211
+ characters in \[`gptr()`, `egptr()`) are the characters in the pending
2212
+ sequence, otherwise either `gptr()` is null or `gptr() == egptr()`.
2213
 
2214
  If `eback()` and `gptr()` are non-null then the function is not
2215
  constrained as to their contents, but the “usual backup condition” is
2216
+ that either
2217
+
2218
+ - the backup sequence contains at least `gptr() - eback()` characters,
2219
+ in which case the characters in \[`eback()`, `gptr()`) agree with the
2220
+ last `gptr() - eback()` characters of the backup sequence, or
2221
+ - the characters in \[`gptr() - n`, `gptr()`) agree with the backup
2222
+ sequence (where `n` is the length of the backup sequence).
2223
 
2224
  *Default behavior:* Returns `traits::eof()`.
2225
 
2226
  ``` cpp
2227
  int_type uflow();
 
2254
  modifications that
2255
 
2256
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
2257
  input sequence is backed up one character before the pending sequence
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.
2269
  `pbackfail()` is called only when put back has really failed.
 
2280
 
2281
  *Effects:* Writes up to `n` characters to the output sequence as if by
2282
  repeated calls to `sputc(c)`. The characters written are obtained from
2283
  successive elements of the array whose first element is designated by
2284
  `s`. Writing stops when either `n` characters have been written or a
2285
+ call to `sputc(c)` would return `traits::eof()`. It is unspecified
2286
  whether the function calls `overflow()` when `pptr() == epptr()` becomes
2287
+ `true` or whether it achieves the same effects by other means.
2288
 
2289
  *Returns:* The number of characters written.
2290
 
2291
  ``` cpp
2292
  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
 
2326
  Otherwise, returns some value other than `traits::eof()` to indicate
2327
+ success.[^17]
2328
 
2329
  *Default behavior:* Returns `traits::eof()`.
2330
 
2331
  ## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
2332
 
2333
+ ### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
 
 
2334
 
2335
  ``` cpp
2336
  namespace std {
2337
  template <class charT, class traits = char_traits<charT>>
2338
  class basic_istream;
2339
+
2340
+ using istream = basic_istream<char>;
2341
+ using wistream = basic_istream<wchar_t>;
2342
 
2343
  template <class charT, class traits = char_traits<charT>>
2344
  class basic_iostream;
2345
+
2346
+ using iostream = basic_iostream<char>;
2347
+ using wiostream = basic_iostream<wchar_t>;
2348
 
2349
  template <class charT, class traits>
2350
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
2351
 
2352
  template <class charT, class traits, class T>
2353
+ basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);
 
2354
  }
2355
  ```
2356
 
2357
+ ### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
2358
+
2359
  ``` cpp
2360
  namespace std {
2361
  template <class charT, class traits = char_traits<charT>>
2362
  class basic_ostream;
2363
+
2364
+ using ostream = basic_ostream<char>;
2365
+ using wostream = basic_ostream<wchar_t>;
2366
 
2367
  template <class charT, class traits>
2368
  basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
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
 
2379
+ ### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
2380
+
2381
  ``` cpp
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);
 
2395
  template <class charT>
2396
  T11 quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
2397
 
2398
  template <class charT, class traits, class Allocator>
2399
  T12 quoted(const basic_string<charT, traits, Allocator>& s,
2400
+ \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2401
 
2402
  template <class charT, class traits, class Allocator>
2403
  T13 quoted(basic_string<charT, traits, Allocator>& s,
2404
+ \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2405
+
2406
+ template <class charT, class traits>
2407
+ T14 quoted(basic_string_view<charT, traits> s,
2408
+ \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2409
  }
2410
  ```
2411
 
2412
  ### Input streams <a id="input.streams">[[input.streams]]</a>
2413
 
 
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>&));
2442
+ basic_istream<charT, traits>&
2443
+ operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
2444
+ basic_istream<charT, traits>&
2445
+ operator>>(ios_base& (*pf)(ios_base&));
2446
 
2447
  basic_istream<charT, traits>& operator>>(bool& n);
2448
  basic_istream<charT, traits>& operator>>(short& n);
2449
  basic_istream<charT, traits>& operator>>(unsigned short& n);
2450
  basic_istream<charT, traits>& operator>>(int& n);
 
2456
  basic_istream<charT, traits>& operator>>(float& f);
2457
  basic_istream<charT, traits>& operator>>(double& f);
2458
  basic_istream<charT, traits>& operator>>(long double& f);
2459
 
2460
  basic_istream<charT, traits>& operator>>(void*& p);
2461
+ basic_istream<charT, traits>& operator>>(basic_streambuf<char_type, traits>* sb);
 
2462
 
2463
+ // [istream.unformatted], unformatted input
2464
  streamsize gcount() const;
2465
  int_type get();
2466
  basic_istream<charT, traits>& get(char_type& c);
2467
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
2468
+ basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
 
2469
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
2470
+ basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
 
2471
 
2472
  basic_istream<charT, traits>& getline(char_type* s, streamsize n);
2473
+ basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
 
2474
 
2475
+ basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
 
2476
  int_type peek();
2477
  basic_istream<charT, traits>& read (char_type* s, streamsize n);
2478
  streamsize readsome(char_type* s, streamsize n);
2479
 
2480
  basic_istream<charT, traits>& putback(char_type c);
 
2484
  pos_type tellg();
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
2500
  template<class charT, class traits>
2501
+ basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT&);
 
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
2518
+ controlled by a stream buffer.
2519
 
2520
  Two groups of member function signatures share common properties: the
2521
  *formatted input functions* (or *extractors*) and the *unformatted input
2522
  functions.* Both groups of input functions are described as if they
2523
  obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
 
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
 
 
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);
 
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_; }
 
2612
  to synchronize the output sequence with any associated external C
2613
  stream. Except that this call can be suppressed if the put area of
2614
  `is.tie()` is empty. Further an implementation is allowed to defer the
2615
  call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
2616
  such call occurs before the `sentry` object is destroyed, the call to
2617
+ `flush` may be eliminated entirely.[^18] If `noskipws` is zero and
2618
  `is.flags() & ios_base::skipws` is nonzero, the function extracts and
2619
  discards each character as long as the next available input character
2620
  `c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
2621
  `is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
2622
  `setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
2623
 
2624
  *Remarks:* The constructor
2625
+
2626
+ ``` cpp
2627
+ explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false)
2628
+ ```
2629
+
2630
  uses the currently imbued locale in `is`, to determine whether the next
2631
  input character is whitespace or not.
2632
 
2633
  To decide if the character `c` is a whitespace character, the
2634
  constructor performs as if it executes the following code fragment:
 
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
 
 
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
 
 
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
 
2696
  ``` cpp
2697
+ using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2698
  iostate err = iostate::goodbit;
2699
  use_facet<numget>(loc).get(*this, 0, *this, err, val);
2700
  setstate(err);
2701
  ```
2702
 
2703
  In the above fragment, `loc` stands for the private member of the
2704
+ `basic_ios` class.
2705
+
2706
+ [*Note 1*: The first argument provides an object of the
2707
  `istreambuf_iterator` class which is an iterator pointed to an input
2708
+ stream. It bypasses istreams and uses streambufs
2709
+ directly. *end note*]
2710
+
2711
+ Class `locale` relies on this type as its interface to `istream`, so
2712
+ that it does not need to depend directly on `istream`.
2713
 
2714
  ``` cpp
2715
  operator>>(short& val);
2716
  ```
2717
 
2718
  The conversion occurs as if performed by the following code fragment
2719
  (using the same notation as for the preceding code fragment):
2720
 
2721
  ``` cpp
2722
+ using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2723
  iostate err = ios_base::goodbit;
2724
  long lval;
2725
  use_facet<numget>(loc).get(*this, 0, *this, err, lval);
2726
  if (lval < numeric_limits<short>::min()) {
2727
  err |= ios_base::failbit;
 
2740
 
2741
  The conversion occurs as if performed by the following code fragment
2742
  (using the same notation as for the preceding code fragment):
2743
 
2744
  ``` cpp
2745
+ using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2746
  iostate err = ios_base::goodbit;
2747
  long lval;
2748
  use_facet<numget>(loc).get(*this, 0, *this, err, lval);
2749
  if (lval < numeric_limits<int>::min()) {
2750
  err |= ios_base::failbit;
 
2755
  } else
2756
  val = static_cast<int>(lval);
2757
  setstate(err);
2758
  ```
2759
 
2760
+ ##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
2761
 
2762
  ``` cpp
2763
+ basic_istream<charT, traits>&
2764
+ operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
2765
  ```
2766
 
2767
  *Effects:* None. This extractor does not behave as a formatted input
2768
+ function (as described in  [[istream.formatted.reqmts]]).
2769
 
2770
+ *Returns:* `pf(*this)`.[^21]
2771
 
2772
  ``` cpp
2773
+ basic_istream<charT, traits>&
2774
+ operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
2775
  ```
2776
 
2777
  *Effects:* Calls `pf(*this)`. This extractor does not behave as a
2778
  formatted input function (as described
2779
  in  [[istream.formatted.reqmts]]).
2780
 
2781
  *Returns:* `*this`.
2782
 
2783
  ``` cpp
2784
+ basic_istream<charT, traits>& operator>>(ios_base& (*pf)(ios_base&));
 
2785
  ```
2786
 
2787
+ *Effects:* Calls `pf(*this)`.[^22] This extractor does not behave as a
2788
  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
 
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;
2815
+ - letting `ct` be `use_facet<ctype<charT>>(in.getloc())`,
2816
+ `ct.is(ct.space, c)` is `true`.
2817
 
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
 
 
2824
 
2825
  *Returns:* `in`.
2826
 
2827
  ``` cpp
2828
  template<class charT, class traits>
2829
+ basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT& c);
 
2830
  template<class traits>
2831
+ basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char& c);
 
2832
  template<class traits>
2833
+ basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
 
2834
  ```
2835
 
2836
  *Effects:* Behaves like a formatted input member (as described
2837
  in  [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
2838
  constructed a character is extracted from `in`, if one is available, and
2839
  stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
2840
 
2841
  *Returns:* `in`.
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);
 
2870
  Each unformatted input function begins execution by constructing an
2871
  object of class `sentry` with the default argument `noskipws` (second)
2872
  argument `true`. If the `sentry` object returns `true`, when converted
2873
  to a value of type `bool`, the function endeavors to obtain the
2874
  requested input. Otherwise, if the sentry constructor exits by throwing
2875
+ 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.
 
2889
  ``` cpp
2890
  streamsize gcount() const;
2891
  ```
2892
 
2893
  *Effects:* None. This member function does not behave as an unformatted
2894
+ input function (as described above).
2895
 
2896
  *Returns:* The number of characters extracted by the last unformatted
2897
  input member function called for the object.
2898
 
2899
  ``` cpp
2900
  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);
 
2924
  ```
2925
 
2926
  *Effects:* Behaves as an unformatted input function (as described
2927
+ above). After constructing a sentry object, extracts characters and
2928
+ stores them into successive locations of an array whose first element is
2929
+ designated by `s`.[^25] Characters are extracted and stored until any of
2930
+ the following occurs:
2931
 
2932
  - `n` is less than one or `n - 1` characters are stored;
2933
  - end-of-file occurs on the input sequence (in which case the function
2934
  calls `setstate(eofbit)`);
2935
  - `traits::eq(c, delim)` for the next available input character `c` (in
 
2944
 
2945
  ``` cpp
2946
  basic_istream<charT, traits>& get(char_type* s, streamsize n);
2947
  ```
2948
 
2949
+ *Effects:* Calls `get(s, n, widen(’\n’))`.
2950
 
2951
  *Returns:* Value returned by the call.
2952
 
2953
  ``` cpp
2954
+ basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
 
2955
  ```
2956
 
2957
  *Effects:* Behaves as an unformatted input function (as described
2958
+ above). After constructing a sentry object, extracts characters and
2959
+ inserts them in the output sequence controlled by `sb`. Characters are
2960
+ extracted and inserted until any of the following occurs:
 
2961
 
2962
  - end-of-file occurs on the input sequence;
2963
  - inserting in the output sequence fails (in which case the character to
2964
  be inserted is not extracted);
2965
  - `traits::eq(c, delim)` for the next available input character `c` (in
 
2974
 
2975
  ``` cpp
2976
  basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
2977
  ```
2978
 
2979
+ *Effects:* Calls `get(sb, widen(’\n’))`.
2980
 
2981
  *Returns:* Value returned by the call.
2982
 
2983
  ``` cpp
2984
+ basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
 
2985
  ```
2986
 
2987
  *Effects:* Behaves as an unformatted input function (as described
2988
+ above). After constructing a sentry object, extracts characters and
2989
+ stores them into successive locations of an array whose first element is
2990
+ designated by `s`.[^26] Characters are extracted and stored until one of
2991
+ the following occurs:
2992
 
2993
  1. end-of-file occurs on the input sequence (in which case the function
2994
  calls `setstate(eofbit)`);
2995
  2. `traits::eq(c, delim)` for the next available input character `c`
2996
  (in which case the input character is extracted but not
2997
+ stored);[^27]
2998
  3. `n` is less than one or `n - 1` characters are stored (in which case
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
 
3010
  *Returns:* `*this`.
3011
 
3012
+ [*Example 1*:
3013
+
3014
  ``` cpp
3015
  #include <iostream>
3016
 
3017
  int main() {
3018
  using namespace std;
 
3034
  cout << " (" << count << " chars): " << buffer << endl;
3035
  }
3036
  }
3037
  ```
3038
 
3039
+ — *end example*]
3040
+
3041
  ``` cpp
3042
  basic_istream<charT, traits>& getline(char_type* s, streamsize n);
3043
  ```
3044
 
3045
  *Returns:* `getline(s, n, widen(’\n’))`
3046
 
3047
  ``` cpp
3048
+ basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
 
3049
  ```
3050
 
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
 
3069
  ``` cpp
3070
  int_type peek();
3071
  ```
3072
 
3073
  *Effects:* Behaves as an unformatted input function (as described
3074
+ above). After constructing a sentry object, reads but does not extract
3075
+ the current input character.
3076
 
3077
  *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
3078
  `rdbuf()->sgetc()`.
3079
 
3080
  ``` cpp
3081
  basic_istream<charT, traits>& read(char_type* s, streamsize n);
3082
  ```
3083
 
3084
  *Effects:* Behaves as an unformatted input function (as described
3085
+ above). After constructing a sentry object, if `!good()` calls
3086
+ `setstate(failbit)` which may throw an exception, and return. Otherwise
3087
+ extracts characters and stores them into successive locations of an
3088
+ 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]])).
 
3098
  ``` cpp
3099
  streamsize readsome(char_type* s, streamsize n);
3100
  ```
3101
 
3102
  *Effects:* Behaves as an unformatted input function (as described
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.
 
3115
  ``` cpp
3116
  basic_istream<charT, traits>& putback(char_type c);
3117
  ```
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`.
3131
 
3132
  ``` cpp
3133
  basic_istream<charT, traits>& unget();
3134
  ```
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`.
3148
 
3149
  ``` cpp
3150
  int sync();
3151
  ```
3152
 
3153
  *Effects:* Behaves as an unformatted input function (as described
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
  ```
3165
 
3166
  *Effects:* Behaves as an unformatted input function (as described
3167
+ above), except that it does not count the number of characters extracted
3168
+ and does not affect the value returned by subsequent calls to
3169
+ `gcount()`.
3170
 
3171
  *Returns:* After constructing a sentry object, if `fail() != false`,
3172
  returns `pos_type(-1)` to indicate failure. Otherwise, returns
3173
  `rdbuf()->pubseekoff(0, cur, in)`.
3174
 
3175
  ``` cpp
3176
  basic_istream<charT, traits>& seekg(pos_type pos);
3177
  ```
3178
 
3179
  *Effects:* Behaves as an unformatted input function (as described
3180
+ above), except that the function first clears `eofbit`, it does not
3181
+ count the number of characters extracted, and it does not affect the
3182
+ value returned by subsequent calls to `gcount()`. After constructing a
3183
+ sentry object, if `fail() != true`, executes
3184
+ `rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
3185
+ function calls `setstate(failbit)` (which may throw
3186
  `ios_base::failure`).
3187
 
3188
  *Returns:* `*this`.
3189
 
3190
  ``` cpp
3191
  basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
3192
  ```
3193
 
3194
  *Effects:* Behaves as an unformatted input function (as described
3195
+ above), except that the function first clears `eofbit`, does not count
3196
+ the number of characters extracted, and does not affect the value
3197
  returned by subsequent calls to `gcount()`. After constructing a sentry
3198
  object, if `fail() != true`, executes
3199
  `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
3200
  function calls `setstate(failbit)` (which may throw
3201
  `ios_base::failure`).
 
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>>
3247
+ class basic_iostream
3248
+ : public basic_istream<charT, traits>,
3249
  public basic_ostream<charT, traits> {
3250
  public:
3251
+ using char_type = charT;
3252
+ using int_type = typename traits::int_type;
3253
+ using pos_type = typename traits::pos_type;
3254
+ using off_type = typename traits::off_type;
3255
+ using traits_type = traits;
 
3256
 
3257
+ // [iostream.cons], constructor
3258
  explicit basic_iostream(basic_streambuf<charT, traits>* sb);
3259
+
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
 
 
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
 
3322
  *Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
3323
 
 
 
 
 
 
 
 
 
 
 
 
 
3324
  ### Output streams <a id="output.streams">[[output.streams]]</a>
3325
 
3326
  The header `<ostream>` defines a type and several function signatures
3327
  that control output to a stream buffer along with a function template
3328
  that inserts into stream rvalues.
 
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>&));
3354
+ basic_ostream<charT, traits>&
3355
+ operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
3356
+ basic_ostream<charT, traits>&
3357
+ operator<<(ios_base& (*pf)(ios_base&));
3358
 
3359
  basic_ostream<charT, traits>& operator<<(bool n);
3360
  basic_ostream<charT, traits>& operator<<(short n);
3361
  basic_ostream<charT, traits>& operator<<(unsigned short n);
3362
  basic_ostream<charT, traits>& operator<<(int n);
 
3368
  basic_ostream<charT, traits>& operator<<(float f);
3369
  basic_ostream<charT, traits>& operator<<(double f);
3370
  basic_ostream<charT, traits>& operator<<(long double f);
3371
 
3372
  basic_ostream<charT, traits>& operator<<(const void* p);
3373
+ basic_ostream<charT, traits>& operator<<(nullptr_t);
3374
+ basic_ostream<charT, traits>& operator<<(basic_streambuf<char_type, traits>* sb);
3375
 
3376
+ // [ostream.unformatted], unformatted output
3377
  basic_ostream<charT, traits>& put(char_type c);
3378
  basic_ostream<charT, traits>& write(const char_type* s, streamsize n);
3379
 
3380
  basic_ostream<charT, traits>& flush();
3381
 
3382
+ // [ostream.seeks], seeks
3383
  pos_type tellp();
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
3399
  template<class charT, class traits>
3400
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, charT);
 
3401
  template<class charT, class traits>
3402
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, char);
 
3403
  template<class traits>
3404
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char);
 
3405
 
 
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>
3416
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const char*);
 
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
3427
+ sequences controlled by a stream buffer.
3428
 
3429
  Two groups of member function signatures share common properties: the
3430
  *formatted output functions* (or *inserters*) and the *unformatted
3431
  output functions.* Both groups of output functions generate (or
3432
  *insert*) output *characters* by actions equivalent to calling
 
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
 
3459
  *Effects:* Move constructs from the rvalue `rhs`. This is accomplished
3460
  by default constructing the base class and calling
3461
  `basic_ios<charT, traits>::move(rhs)` to initialize the base class.
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 {
 
3508
  ``` cpp
3509
  explicit sentry(basic_ostream<charT, traits>& os);
3510
  ```
3511
 
3512
  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
 
3524
  If
3525
+ `(os.flags() & ios_base::unitbuf) && !uncaught_exceptions() && os.good()`
3526
  is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1,
3527
  sets `badbit` in `os.rdstate()` without propagating an exception.
3528
 
3529
  ``` cpp
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
3541
  pos_type tellp();
3542
  ```
3543
 
3544
+ *Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
3545
+ failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
3546
+
3547
  ``` cpp
3548
  basic_ostream<charT, traits>& seekp(pos_type pos);
3549
  ```
3550
 
3551
+ *Effects:* If `fail() != true`, executes
3552
+ `rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
3553
+ function calls `setstate(failbit)` (which may throw
3554
+ `ios_base::failure`).
3555
+
3556
+ *Returns:* `*this`.
3557
+
3558
  ``` cpp
3559
  basic_ostream<charT, traits>& seekp(off_type off, ios_base::seekdir dir);
3560
  ```
3561
 
3562
  *Effects:* If `fail() != true`, executes
 
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
 
 
3675
  The first argument provides an object of the `ostreambuf_iterator<>`
3676
  class which is an iterator for class `basic_ostream<>`. It bypasses
3677
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
3678
  these types as its interface to iostreams, since for flexibility it has
3679
  been abstracted away from direct dependence on `ostream`. The second
3680
+ parameter is a reference to the base class subobject of type `ios_base`.
3681
+ It provides formatting specifications such as field width, and a locale
3682
  from which to obtain other facets. If `failed` is `true` then does
3683
  `setstate(badbit)`, which may throw an exception, and returns.
3684
 
3685
  *Returns:* `*this`.
3686
 
3687
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
3688
 
3689
  ``` cpp
3690
+ basic_ostream<charT, traits>&
3691
+ operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
3692
  ```
3693
 
3694
  *Effects:* None. Does not behave as a formatted output function (as
3695
  described in  [[ostream.formatted.reqmts]]).
3696
 
3697
+ *Returns:* `pf(*this)`.[^34]
3698
 
3699
  ``` cpp
3700
+ basic_ostream<charT, traits>&
3701
+ operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
3702
  ```
3703
 
3704
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3705
  formatted output function (as described
3706
  in  [[ostream.formatted.reqmts]]).
3707
 
3708
+ *Returns:* `*this`.[^35]
3709
 
3710
  ``` cpp
3711
+ basic_ostream<charT, traits>& operator<<(ios_base& (*pf)(ios_base&));
 
3712
  ```
3713
 
3714
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3715
  formatted output function (as described
3716
  in  [[ostream.formatted.reqmts]]).
3717
 
3718
  *Returns:* `*this`.
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
 
 
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);
3747
+ ```
3748
+
3749
+ *Effects:* Equivalent to:
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>
3761
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, charT c);
 
3762
  template<class charT, class traits>
3763
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, char c);
 
3764
  // specialization
3765
  template<class traits>
3766
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, char c);
 
3767
  // signed and unsigned
3768
  template<class traits>
3769
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, signed char c);
 
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>
3786
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, const charT* s);
 
3787
  template<class charT, class traits>
3788
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, const char* s);
 
3789
  template<class traits>
3790
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, const char* s);
 
3791
  template<class traits>
3792
+ basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, const signed char* s);
 
3793
  template<class traits>
3794
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
3795
  const unsigned char* s);
3796
  ```
3797
 
 
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
3810
  `const char*`,
3811
+ - `char_traits<char>::length(s)` for the overload where the first
3812
  argument is of type `basic_ostream<charT, traits>&` and the second is
3813
  of type `const char*`,
3814
  - `traits::length(reinterpret_cast<const char*>(s))` for the other two
3815
  overloads.
3816
 
 
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
 
3835
  ``` cpp
3836
  basic_ostream<charT, traits>& put(char_type c);
3837
  ```
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`.
 
3848
  ``` cpp
3849
  basic_ostream& write(const char_type* s, streamsize n);
3850
  ```
3851
 
3852
  *Effects:* Behaves as an unformatted output function (as described
3853
+ above). After constructing a sentry object, obtains characters to insert
3854
+ 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]])).
 
3865
  ``` cpp
3866
  basic_ostream& flush();
3867
  ```
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
  ```
3885
 
3886
  *Effects:* Calls `os.put(os.widen(’\n’))`, then `os.flush()`.
3887
 
3888
  *Returns:* `os`.
3889
 
3890
  ``` cpp
 
3891
  template <class charT, class traits>
3892
  basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
 
3893
  ```
3894
 
3895
  *Effects:* Inserts a null character into the output sequence: calls
3896
  `os.put(charT())`.
3897
 
3898
  *Returns:* `os`.
3899
 
3900
  ``` cpp
 
3901
  template <class charT, class traits>
3902
  basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
 
3903
  ```
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
 
3930
  unspecified resetiosflags(ios_base::fmtflags mask);
3931
  ```
3932
 
3933
  *Returns:* An object of unspecified type such that if `out` is an object
3934
  of type `basic_ostream<charT, traits>` then the expression
3935
+ `out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
3936
  if `in` is an object of type `basic_istream<charT, traits>` then the
3937
+ expression `in >> resetiosflags(mask)` behaves as if it called
3938
+ `f(in, mask)`, where the function `f` is defined as:[^39]
3939
 
3940
  ``` cpp
3941
  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
 
3956
  *Returns:* An object of unspecified type such that if `out` is an object
3957
  of type `basic_ostream<charT, traits>` then the expression
3958
+ `out << setiosflags(mask)` behaves as if it called `f(out, mask)`, or if
3959
  `in` is an object of type `basic_istream<charT, traits>` then the
3960
+ expression `in >> setiosflags(mask)` behaves as if it called
3961
  `f(in, mask)`, where the function `f` is defined as:
3962
 
3963
  ``` cpp
3964
  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
 
3979
  *Returns:* An object of unspecified type such that if `out` is an object
3980
  of type `basic_ostream<charT, traits>` then the expression
3981
+ `out << setbase(base)` behaves as if it called `f(out, base)`, or if
3982
  `in` is an object of type `basic_istream<charT, traits>` then the
3983
+ expression `in >> setbase(base)` behaves as if it called `f(in, base)`,
3984
  where the function `f` is defined as:
3985
 
3986
  ``` cpp
3987
  void f(ios_base& str, int base) {
3988
  // set basefield
 
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
 
4005
  *Returns:* An object of unspecified type such that if `out` is an object
4006
  of type `basic_ostream<charT, traits>` and `c` has type `charT` then the
4007
+ expression `out << setfill(c)` behaves as if it called `f(out, c)`,
4008
  where the function `f` is defined as:
4009
 
4010
  ``` cpp
4011
  template<class charT, class traits>
4012
  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
  ```
4024
 
4025
  *Returns:* An object of unspecified type such that if `out` is an object
4026
  of type `basic_ostream<charT, traits>` then the expression
4027
+ `out << setprecision(n)` behaves as if it called `f(out, n)`, or if `in`
4028
  is an object of type `basic_istream<charT, traits>` then the expression
4029
+ `in >> setprecision(n)` behaves as if it called `f(in, n)`, where the
4030
  function `f` is defined as:
4031
 
4032
  ``` cpp
4033
  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
 
4048
  *Returns:* An object of unspecified type such that if `out` is an
4049
  instance of `basic_ostream<charT, traits>` then the expression
4050
+ `out << setw(n)` behaves as if it called `f(out, n)`, or if `in` is an
4051
  object of type `basic_istream<charT, traits>` then the expression
4052
+ `in >> setw(n)` behaves as if it called `f(in, n)`, where the function
4053
  `f` is defined as:
4054
 
4055
  ``` cpp
4056
  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
 
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:
4087
 
4088
  ``` cpp
4089
  template <class charT, class traits, class moneyT>
4090
  void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
4091
+ using Iter = istreambuf_iterator<charT, traits>;
4092
+ using MoneyGet = money_get<charT, Iter>;
4093
 
4094
  ios_base::iostate err = ios_base::goodbit;
4095
  const MoneyGet& mg = use_facet<MoneyGet>(str.getloc());
4096
 
4097
  mg.get(Iter(str.rdbuf()), Iter(), intl, str, err, mon);
 
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
  ```
 
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) {
4123
+ using Iter = ostreambuf_iterator<charT, traits>;
4124
+ using MoneyPut = money_put<charT, Iter>;
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:
4150
 
4151
  ``` cpp
4152
  template <class charT, class traits>
4153
  void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
4154
+ using Iter = istreambuf_iterator<charT, traits>;
4155
+ using TimeGet = time_get<charT, Iter>;
4156
 
4157
  ios_base::iostate err = ios_base::goodbit;
4158
  const TimeGet& tg = use_facet<TimeGet>(str.getloc());
4159
 
4160
  tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
4161
  fmt, fmt + traits::length(fmt));
4162
 
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
  ```
 
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:
4184
 
4185
  ``` cpp
4186
  template <class charT, class traits>
4187
  void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
4188
+ using Iter = ostreambuf_iterator<charT, traits>;
4189
+ using TimePut = time_put<charT, Iter>;
4190
 
4191
  const TimePut& tp = use_facet<TimePut>(str.getloc());
4192
  const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
4193
  fmt, fmt + traits::length(fmt));
4194
 
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
4206
+ of quoted strings (for example, XML and CSV formats). Quoted
4207
+ manipulators are useful in ensuring that the content of a string with
4208
+ embedded spaces remains unchanged if inserted and then extracted via
4209
+ stream I/O. — *end note*]
4210
 
4211
  ``` cpp
4212
  template <class charT>
4213
  unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
4214
  template <class charT, class traits, class Allocator>
4215
  unspecified quoted(const basic_string<charT, traits, Allocator>& s,
4216
+ \itcorr charT delim = charT('"'), charT escape = charT('\\'));
4217
+ template <class charT, class traits>
4218
+ unspecified quoted(basic_string_view<charT, traits> s,
4219
+ \itcorr charT delim = charT('"'), charT escape = charT('\\'));
4220
  ```
4221
 
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`.
 
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,
4247
+ \itcorr charT delim = charT('"'), charT escape = charT('\\'));
4248
  ```
4249
 
4250
  *Returns:* An object of unspecified type such that:
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
4263
  characters from `in` and append them to `s`, except that if an
4264
  `escape` is reached, ignore it and append the next character to
4265
  `s`.
4266
  - Discard the final `delim` character.
4267
  - Restore the `skipws` flag to its original value.
4268
+ - Otherwise, `in >> s`.
4269
  - If `out` is an instance of `basic_ostream` with member types
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>
4284
+
4285
+ ``` cpp
4286
+ namespace std {
4287
+ template <class charT, class traits = char_traits<charT>,
4288
+ class Allocator = allocator<charT>>
4289
+ class basic_stringbuf;
4290
+
4291
+ using stringbuf = basic_stringbuf<char>;
4292
+ using wstringbuf = basic_stringbuf<wchar_t>;
4293
+
4294
+ template <class charT, class traits = char_traits<charT>,
4295
+ class Allocator = allocator<charT>>
4296
+ class basic_istringstream;
4297
+
4298
+ using istringstream = basic_istringstream<char>;
4299
+ using wistringstream = basic_istringstream<wchar_t>;
4300
+
4301
+ template <class charT, class traits = char_traits<charT>,
4302
+ class Allocator = allocator<charT>>
4303
+ class basic_ostringstream;
4304
+ using ostringstream = basic_ostringstream<char>;
4305
+ using wostringstream = basic_ostringstream<wchar_t>;
4306
+
4307
+ template <class charT, class traits = char_traits<charT>,
4308
+ class Allocator = allocator<charT>>
4309
+ class basic_stringstream;
4310
+ using stringstream = basic_stringstream<char>;
4311
+ using wstringstream = basic_stringstream<wchar_t>;
4312
+ }
4313
+ ```
4314
 
4315
  The header `<sstream>` defines four class templates and eight types that
4316
  associate stream buffers with objects of class `basic_string`, as
4317
  described in  [[string.classes]].
4318
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4319
  ### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
4320
 
4321
  ``` cpp
4322
  namespace std {
4323
  template <class charT, class traits = char_traits<charT>,
4324
  class Allocator = allocator<charT>>
4325
  class basic_stringbuf : public basic_streambuf<charT, traits> {
4326
  public:
4327
+ using char_type = charT;
4328
+ using int_type = typename traits::int_type;
4329
+ using pos_type = typename traits::pos_type;
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;
4356
+ int_type overflow (int_type c = traits::eof()) override;
4357
+ basic_streambuf<charT, traits>* setbuf(charT*, streamsize) override;
4358
 
4359
+ pos_type seekoff(off_type off, ios_base::seekdir way,
 
4360
  ios_base::openmode which
4361
+ = ios_base::in | ios_base::out) override;
4362
+ pos_type seekpos(pos_type sp,
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
 
 
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
 
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;
 
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.
 
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;
4507
  ```
4508
 
4509
  *Returns:* If the input sequence has a read position available, returns
4510
  `traits::to_int_type(*gptr())`. Otherwise, returns `traits::eof()`. Any
4511
  character in the underlying buffer which has been initialized is
4512
  considered to be part of the input sequence.
4513
 
4514
  ``` cpp
4515
+ int_type pbackfail(int_type c = traits::eof()) override;
4516
  ```
4517
 
4518
  *Effects:* Puts back the character designated by `c` to the input
4519
  sequence, if possible, in one of three ways:
4520
 
 
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
4538
+ int_type overflow(int_type c = traits::eof()) override;
4539
  ```
4540
 
4541
  *Effects:* Appends the character designated by `c` to the output
4542
  sequence, if possible, in one of two ways:
4543
 
 
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]].
 
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
4606
  position, if possible. If the positioning operation fails, or if the
4607
  constructed object cannot represent the resultant stream position, the
4608
  return value is `pos_type(off_type(-1))`.
4609
 
4610
  ``` cpp
4611
+ pos_type seekpos(pos_type sp,
4612
+ ios_base::openmode which
4613
+ = ios_base::in | ios_base::out) override;
4614
  ```
4615
 
4616
  *Effects:* Equivalent to `seekoff(off_type(sp), ios_base::beg, which)`.
4617
 
4618
  *Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
 
4633
  namespace std {
4634
  template <class charT, class traits = char_traits<charT>,
4635
  class Allocator = allocator<charT>>
4636
  class basic_istringstream : public basic_istream<charT, traits> {
4637
  public:
4638
+ using char_type = charT;
4639
+ using int_type = typename traits::int_type;
4640
+ using pos_type = typename traits::pos_type;
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:
 
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);
 
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
 
 
4763
  namespace std {
4764
  template <class charT, class traits = char_traits<charT>,
4765
  class Allocator = allocator<charT>>
4766
  class basic_ostringstream : public basic_ostream<charT, traits> {
4767
  public:
4768
+ using char_type = charT;
4769
+ using int_type = typename traits::int_type;
4770
+ using pos_type = typename traits::pos_type;
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:
 
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
 
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);
 
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
 
 
4891
 
4892
  ``` cpp
4893
  namespace std {
4894
  template <class charT, class traits = char_traits<charT>,
4895
  class Allocator = allocator<charT>>
4896
+ class basic_stringstream : public basic_iostream<charT, traits> {
 
4897
  public:
4898
+ using char_type = charT;
4899
+ using int_type = typename traits::int_type;
4900
+ using pos_type = typename traits::pos_type;
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:
 
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
  ```
 
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);
 
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;
 
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
+
5025
+ ``` cpp
5026
+ namespace std {
5027
+ template <class charT, class traits = char_traits<charT>>
5028
+ class basic_filebuf;
5029
+ using filebuf = basic_filebuf<char>;
5030
+ using wfilebuf = basic_filebuf<wchar_t>;
5031
+
5032
+ template <class charT, class traits = char_traits<charT>>
5033
+ class basic_ifstream;
5034
+ using ifstream = basic_ifstream<char>;
5035
+ using wifstream = basic_ifstream<wchar_t>;
5036
+
5037
+ template <class charT, class traits = char_traits<charT>>
5038
+ class basic_ofstream;
5039
+ using ofstream = basic_ofstream<char>;
5040
+ using wofstream = basic_ofstream<wchar_t>;
5041
+
5042
+ template <class charT, class traits = char_traits<charT>>
5043
+ class basic_fstream;
5044
+ using fstream = basic_fstream<char>;
5045
+ using wfstream = basic_fstream<wchar_t>;
5046
+ }
5047
+ ```
5048
 
5049
  The header `<fstream>` defines four class templates and eight types that
5050
  associate stream buffers with files and assist reading and writing
5051
  files.
5052
 
5053
+ [*Note 1*: The class template `basic_filebuf` treats a file as a source
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>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5067
 
5068
  ``` cpp
5069
  namespace std {
5070
  template <class charT, class traits = char_traits<charT>>
5071
  class basic_filebuf : public basic_streambuf<charT, traits> {
5072
  public:
5073
+ using char_type = charT;
5074
+ using int_type = typename traits::int_type;
5075
+ using pos_type = typename traits::pos_type;
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;
5092
+ basic_filebuf* open(const char* s, ios_base::openmode mode);
5093
+ basic_filebuf* open(const filesystem::path::value_type* s,
5094
+ ios_base::openmode mode); // wide systems only; see [fstream.syn]
5095
+ basic_filebuf* open(const string& s,
5096
  ios_base::openmode mode);
5097
+ basic_filebuf* open(const filesystem::path& s,
5098
  ios_base::openmode mode);
5099
+ basic_filebuf* close();
5100
 
5101
  protected:
5102
+ // [filebuf.virtuals], overridden virtual functions
5103
+ streamsize showmanyc() override;
5104
+ int_type underflow() override;
5105
+ int_type uflow() override;
5106
+ int_type pbackfail(int_type c = traits::eof()) override;
5107
+ int_type overflow (int_type c = traits::eof()) override;
5108
 
5109
+ basic_streambuf<charT, traits>* setbuf(char_type* s,
5110
+ streamsize n) override;
5111
+ pos_type seekoff(off_type off, ios_base::seekdir way,
5112
+ ios_base::openmode which
5113
+ = ios_base::in | ios_base::out) override;
5114
+ pos_type seekpos(pos_type sp,
5115
+ ios_base::openmode which
5116
+ = ios_base::in | ios_base::out) override;
5117
+ int sync() override;
5118
+ void imbue(const locale& loc) override;
5119
  };
5120
 
5121
  template <class charT, class traits>
5122
  void swap(basic_filebuf<charT, traits>& x,
5123
  basic_filebuf<charT, traits>& y);
 
5127
  The class `basic_filebuf<charT, traits>` associates both the input
5128
  sequence and the output sequence with a file.
5129
 
5130
  The restrictions on reading and writing a sequence controlled by an
5131
  object of class `basic_filebuf<charT, traits>` are the same as for
5132
+ reading and writing with the C standard library `FILE`s.
5133
 
5134
  In particular:
5135
 
5136
  - If the file is not open for reading the input sequence cannot be read.
5137
  - If the file is not open for writing the output sequence cannot be
5138
  written.
5139
  - A joint file position is maintained for both the input sequence and
5140
  the output sequence.
5141
 
5142
  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
 
 
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
 
 
5207
 
5208
  ``` cpp
5209
  basic_filebuf& operator=(basic_filebuf&& rhs);
5210
  ```
5211
 
5212
+ *Effects:* Calls `close()` then move assigns from `rhs`. After the move
5213
+ assignment `*this` has the observable state it would have had if it had
5214
+ been move constructed from `rhs` (see  [[filebuf.cons]]).
5215
 
5216
  *Returns:* `*this`.
5217
 
5218
  ``` cpp
5219
  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;
 
5237
 
5238
  *Returns:* `true` if a previous call to `open` succeeded (returned a
5239
  non-null value) and there has been no intervening call to close.
5240
 
5241
  ``` cpp
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>
 
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.
5286
 
5287
  ``` cpp
5288
+ basic_filebuf* open(const string& s, ios_base::openmode mode);
5289
+ basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
5290
  ```
5291
 
5292
  *Returns:* `open(s.c_str(), mode);`
5293
 
5294
  ``` cpp
5295
+ basic_filebuf* close();
5296
  ```
5297
 
5298
  *Effects:* If `is_open() == false`, returns a null pointer. If a put
5299
  area exists, calls `overflow(traits::eof())` to flush characters. If the
5300
  last virtual member function called on `*this` (between `underflow`,
5301
  `overflow`, `seekoff`, and `seekpos`) was `overflow` then calls
5302
  `a_codecvt.unshift` (possibly several times) to determine a termination
5303
  sequence, inserts those characters and calls `overflow(traits::eof())`
5304
  again. Finally, regardless of whether any of the preceding calls fails
5305
  or throws an exception, the function closes the file (as if by calling
5306
+ `fclose(file)`). If any of the calls made by the function, including
5307
+ `fclose`, fails, `close` fails by returning a null pointer. If one of
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
 
5328
  ``` cpp
5329
+ int_type underflow() override;
5330
  ```
5331
 
5332
  *Effects:* Behaves according to the description of
5333
  `basic_streambuf<charT, traits>::underflow()`, with the specialization
5334
  that a sequence of characters is read from the input sequence as if by
5335
  reading from the associated file into an internal buffer (`extern_buf`)
5336
+ and then as if by doing:
5337
 
5338
  ``` cpp
5339
  char extern_buf[XSIZE];
5340
  char* extern_end;
5341
  charT intern_buf[ISIZE];
 
5349
  (`fpos_t`) corresponding to each character between `intern_buf` and
5350
  `intern_end`. If the value of `r` indicates that `a_codecvt.in()` ran
5351
  out of space in `intern_buf`, retry with a larger `intern_buf`.
5352
 
5353
  ``` cpp
5354
+ int_type uflow() override;
5355
  ```
5356
 
5357
  *Effects:* Behaves according to the description of
5358
+ `basic_streambuf<charT, traits>::uflow()`, with the specialization that
5359
+ a sequence of characters is read from the input with the same method as
5360
  used by `underflow`.
5361
 
5362
  ``` cpp
5363
+ int_type pbackfail(int_type c = traits::eof()) override;
5364
  ```
5365
 
5366
  *Effects:* Puts back the character designated by `c` to the input
5367
  sequence, if possible, in one of three ways:
5368
 
 
5390
  If the function can succeed in more than one of these ways, it is
5391
  unspecified which way is chosen. The function can alter the number of
5392
  putback positions available as a result of any call.
5393
 
5394
  ``` cpp
5395
+ int_type overflow(int_type c = traits::eof()) override;
5396
  ```
5397
 
5398
  *Effects:* Behaves according to the description of
5399
  `basic_streambuf<charT, traits>::overflow(c)`, except that the behavior
5400
  of “consuming characters” is performed by first converting as if by:
 
5423
 
5424
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
5425
  to indicate failure. If `is_open() == false`, the function always fails.
5426
 
5427
  ``` cpp
5428
+ basic_streambuf* setbuf(char_type* s, streamsize n) override;
5429
  ```
5430
 
5431
  *Effects:* If `setbuf(0, 0)` is called on a stream before any I/O has
5432
  occurred on that stream, the stream becomes unbuffered. Otherwise the
5433
  results are *implementation-defined*. “Unbuffered” means that `pbase()`
5434
  and `pptr()` always return null and output to the file should appear as
5435
  soon as possible.
5436
 
5437
  ``` cpp
5438
  pos_type seekoff(off_type off, ios_base::seekdir way,
5439
+ ios_base::openmode which
5440
+ = ios_base::in | ios_base::out) override;
5441
  ```
5442
 
5443
  *Effects:* Let `width` denote `a_codecvt.encoding()`. If
5444
  `is_open() == false`, or `off != 0 && width <= 0`, then the positioning
5445
  operation fails. Otherwise, if `way != basic_ios::cur` or `off != 0`,
5446
  and if the last operation was output, then update the output sequence
5447
  and write any unshift sequence. Next, seek to the new position: if
5448
+ `width > 0`, call `fseek(file, width * off, whence)`, otherwise call
5449
+ `fseek(file, 0, whence)`.
5450
 
5451
  *Remarks:* “The last operation was output” means either the last virtual
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
 
5470
  fails, or if the object cannot represent the resultant stream position,
5471
  returns `pos_type(off_type(-1))`.
5472
 
5473
  ``` cpp
5474
  pos_type seekpos(pos_type sp,
5475
+ ios_base::openmode which
5476
+ = ios_base::in | ios_base::out) override;
5477
  ```
5478
 
5479
  Alters the file position, if possible, to correspond to the position
5480
  stored in `sp` (as described below). Altering the file position performs
5481
  as follows:
5482
 
5483
  1. if `(om & ios_base::out) != 0`, then update the output sequence and
5484
  write any unshift sequence;
5485
+ 2. set the file position to `sp` as if by a call to `fsetpos`;
5486
  3. if `(om & ios_base::in) != 0`, then update the input sequence;
5487
 
5488
  where `om` is the open mode passed to the last call to `open()`. The
5489
+ operation fails if `is_open()` returns `false`.
5490
 
5491
  If `sp` is an invalid stream position, or if the function positions
5492
  neither sequence, the positioning operation fails. If `sp` has not been
5493
  obtained by a previous successful call to one of the positioning
5494
  functions (`seekoff` or `seekpos`) on the same file the effects are
5495
  undefined.
5496
 
5497
  *Returns:* `sp` on success. Otherwise returns `pos_type(off_type(-1))`.
5498
 
5499
  ``` cpp
5500
+ int sync() override;
5501
  ```
5502
 
5503
  *Effects:* If a put area exists, calls `filebuf::overflow` to write the
5504
+ characters to the file, then flushes the file as if by calling
5505
+ `fflush(file)`. If a get area exists, the effect is
5506
  *implementation-defined*.
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
 
5520
+ *Remarks:* This may require reconversion of previously converted
5521
+ characters. This in turn may require the implementation to be able to
5522
+ reconstruct the original contents of the file.
5523
 
5524
+ ### Class template `basic_ifstream` <a id="ifstream">[[ifstream]]</a>
5525
 
5526
  ``` cpp
5527
  namespace std {
5528
  template <class charT, class traits = char_traits<charT>>
5529
  class basic_ifstream : public basic_istream<charT, traits> {
5530
  public:
5531
+ using char_type = charT;
5532
+ using int_type = typename traits::int_type;
5533
+ using pos_type = typename traits::pos_type;
5534
+ using off_type = typename traits::off_type;
5535
+ using traits_type = traits;
5536
 
5537
+ // [ifstream.cons], constructors
5538
  basic_ifstream();
5539
  explicit basic_ifstream(const char* s,
5540
  ios_base::openmode mode = ios_base::in);
5541
+ explicit basic_ifstream(const filesystem::path::value_type* s,
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;
5557
 
5558
  bool is_open() const;
5559
  void open(const char* s, ios_base::openmode mode = ios_base::in);
5560
+ void open(const filesystem::path::value_type* s,
5561
+ ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
5562
  void open(const string& s, ios_base::openmode mode = ios_base::in);
5563
+ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
5564
  void close();
5565
  private:
5566
  basic_filebuf<charT, traits> sb; // exposition only
5567
  };
5568
 
 
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]]),
 
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
 
 
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;
 
5661
 
5662
  *Returns:* `rdbuf()->is_open()`.
5663
 
5664
  ``` cpp
5665
  void open(const char* s, ios_base::openmode mode = ios_base::in);
5666
+ 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
  ```
5679
 
5680
+ *Effects:* Calls `open(s.c_str(), mode)`.
5681
 
5682
  ``` cpp
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 {
5694
  template <class charT, class traits = char_traits<charT>>
5695
  class basic_ofstream : public basic_ostream<charT, traits> {
5696
  public:
5697
+ using char_type = charT;
5698
+ using int_type = typename traits::int_type;
5699
+ using pos_type = typename traits::pos_type;
5700
+ using off_type = typename traits::off_type;
5701
+ using traits_type = traits;
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;
5723
 
5724
  bool is_open() const;
5725
  void open(const char* s, ios_base::openmode mode = ios_base::out);
5726
+ void open(const filesystem::path::value_type* s,
5727
+ ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
5728
  void open(const string& s, ios_base::openmode mode = ios_base::out);
5729
+ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
5730
  void close();
5731
  private:
5732
  basic_filebuf<charT, traits> sb; // exposition only
5733
  };
5734
 
 
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
 
 
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;
 
5828
 
5829
  *Returns:* `rdbuf()->is_open()`.
5830
 
5831
  ``` cpp
5832
  void open(const char* s, ios_base::openmode mode = ios_base::out);
5833
+ 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
  ```
5854
 
5855
+ *Effects:* Calls `open(s.c_str(), mode)`.
5856
 
5857
+ ### Class template `basic_fstream` <a id="fstream">[[fstream]]</a>
5858
 
5859
  ``` cpp
5860
  namespace std {
5861
  template <class charT, class traits = char_traits<charT>>
5862
+ class basic_fstream : public basic_iostream<charT, traits> {
 
 
5863
  public:
5864
+ using char_type = charT;
5865
+ using int_type = typename traits::int_type;
5866
+ using pos_type = typename traits::pos_type;
5867
+ using off_type = typename traits::off_type;
5868
+ using traits_type = traits;
5869
 
5870
+ // [fstream.cons], constructors
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(
5905
+ const filesystem::path& s,
5906
  ios_base::openmode mode = ios_base::in | ios_base::out);
5907
  void close();
5908
 
5909
  private:
5910
  basic_filebuf<charT, traits> sb; // exposition only
 
5915
  basic_fstream<charT, traits>& y);
5916
  }
5917
  ```
5918
 
5919
  The class template `basic_fstream<charT, traits>` supports reading and
5920
+ 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
 
 
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,
5939
  ios_base::openmode mode = ios_base::in | ios_base::out);
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
5952
+ explicit basic_fstream(
5953
+ const string& s,
5954
+ ios_base::openmode mode = ios_base::in | ios_base::out);
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
 
 
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;
 
6007
  ```
6008
 
6009
  *Returns:* `rdbuf()->is_open()`.
6010
 
6011
  ``` cpp
6012
+ void open(
6013
+ const char* s,
6014
  ios_base::openmode mode = ios_base::in | ios_base::out);
6015
+ void open(
6016
+ const filesystem::path::value_type* s,
6017
+ ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
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);
6029
+ void open(
6030
+ const filesystem::path& s,
6031
  ios_base::openmode mode = ios_base::in | ios_base::out);
6032
  ```
6033
 
6034
+ *Effects:* Calls `open(s.c_str(), mode)`.
6035
 
6036
  ``` cpp
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
+
6078
+ Implementations are not required to provide behavior that is not
6079
+ supported by a particular file system.
6080
+
6081
+ [*Example 1*: The FAT file system used by some memory cards, camera
6082
+ memory, and floppy disks does not support hard links, symlinks, and many
6083
+ 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;
6309
+
6310
+ // [fs.class.rec.dir.itr], recursive directory iterators
6311
+ class recursive_directory_iterator;
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);
6365
+ bool create_directory(const path& p, const path& attributes,
6366
+ error_code& ec) noexcept;
6367
+
6368
+ void create_directory_symlink(const path& to, const path& new_symlink);
6369
+ void create_directory_symlink(const path& to, const path& new_symlink,
6370
+ error_code& ec) noexcept;
6371
+
6372
+ void create_hard_link(const path& to, const path& new_hard_link);
6373
+ void create_hard_link(const path& to, const path& new_hard_link,
6374
+ error_code& ec) noexcept;
6375
+
6376
+ void create_symlink(const path& to, const path& new_symlink);
6377
+ void create_symlink(const path& to, const path& new_symlink,
6378
+ error_code& ec) noexcept;
6379
+
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;
6397
+
6398
+ bool is_block_file(file_status s) noexcept;
6399
+ bool is_block_file(const path& p);
6400
+ bool is_block_file(const path& p, error_code& ec) noexcept;
6401
+
6402
+ bool is_character_file(file_status s) noexcept;
6403
+ bool is_character_file(const path& p);
6404
+ bool is_character_file(const path& p, error_code& ec) noexcept;
6405
+
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
+
6417
+ bool is_other(file_status s) noexcept;
6418
+ bool is_other(const path& p);
6419
+ bool is_other(const path& p, error_code& ec) noexcept;
6420
+
6421
+ bool is_regular_file(file_status s) noexcept;
6422
+ bool is_regular_file(const path& p);
6423
+ bool is_regular_file(const path& p, error_code& ec) noexcept;
6424
+
6425
+ bool is_socket(file_status s) noexcept;
6426
+ bool is_socket(const path& p);
6427
+ bool is_socket(const path& p, error_code& ec) noexcept;
6428
+
6429
+ bool is_symlink(file_status s) noexcept;
6430
+ bool is_symlink(const path& p);
6431
+ bool is_symlink(const path& p, error_code& ec) noexcept;
6432
+
6433
+ file_time_type last_write_time(const path& p);
6434
+ file_time_type last_write_time(const path& p, error_code& ec) noexcept;
6435
+ void last_write_time(const path& p, file_time_type new_time);
6436
+ void last_write_time(const path& p, file_time_type new_time,
6437
+ error_code& ec) noexcept;
6438
+
6439
+ void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
6440
+ void permissions(const path& p, perms prms, error_code& ec) noexcept;
6441
+ void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
6442
+
6443
+ path proximate(const path& p, error_code& ec);
6444
+ path proximate(const path& p, const path& base = current_path());
6445
+ path proximate(const path& p, const path& base, error_code& ec);
6446
+
6447
+ path read_symlink(const path& p);
6448
+ path read_symlink(const path& p, error_code& ec);
6449
+
6450
+ path relative(const path& p, error_code& ec);
6451
+ path relative(const path& p, const path& base = current_path());
6452
+ path relative(const path& p, const path& base, error_code& ec);
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);
6464
+ void resize_file(const path& p, uintmax_t size, error_code& ec) noexcept;
6465
+
6466
+ space_info space(const path& p);
6467
+ space_info space(const path& p, error_code& ec) noexcept;
6468
+
6469
+ file_status status(const path& p);
6470
+ file_status status(const path& p, error_code& ec) noexcept;
6471
+
6472
+ bool status_known(file_status s) noexcept;
6473
+
6474
+ file_status symlink_status(const path& p);
6475
+ file_status symlink_status(const path& p, error_code& ec) noexcept;
6476
+
6477
+ path temp_directory_path();
6478
+ path temp_directory_path(error_code& ec);
6479
+
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
6495
+ an `error_code`.
6496
+
6497
+ [*Note 1*:
6498
+
6499
+ This supports two common use cases:
6500
+
6501
+ - Uses where file system errors are truly exceptional and indicate a
6502
+ serious failure. Throwing an exception is an appropriate response.
6503
+ - Uses where file system errors are routine and do not necessarily
6504
+ represent failure. Returning an error code is the most appropriate
6505
+ response. This allows application specific error handling, including
6506
+ simply ignoring the error.
6507
+
6508
+ — *end note*]
6509
+
6510
+ Functions not having an argument of type `error_code&` handle errors as
6511
+ follows, unless otherwise specified:
6512
+
6513
+ - When a call by the implementation to an operating system or other
6514
+ underlying API results in an error that prevents the function from
6515
+ meeting its specifications, an exception of type `filesystem_error`
6516
+ shall be thrown. For functions with a single path argument, that
6517
+ argument shall be passed to the `filesystem_error` constructor with a
6518
+ single path argument. For functions with two path arguments, the first
6519
+ of these arguments shall be passed to the `filesystem_error`
6520
+ constructor as the `path1` argument, and the second shall be passed as
6521
+ the `path2` argument. The `filesystem_error` constructor’s
6522
+ `error_code` argument is set as appropriate for the specific operating
6523
+ system dependent error.
6524
+ - Failure to allocate storage is reported by throwing an exception as
6525
+ described in  [[res.on.exception.handling]].
6526
+ - Destructors throw nothing.
6527
+
6528
+ Functions having an argument of type `error_code&` handle errors as
6529
+ follows, unless otherwise specified:
6530
+
6531
+ - If a call by the implementation to an operating system or other
6532
+ underlying API results in an error that prevents the function from
6533
+ meeting its specifications, the `error_code&` argument is set as
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;
6556
+ using string_type = basic_string<value_type>;
6557
+ static constexpr value_type preferred_separator = see below;
6558
+
6559
+ // [fs.enum.path.format], enumeration format
6560
+ enum format;
6561
+
6562
+ // [fs.path.construct], constructors and destructor
6563
+ path() noexcept;
6564
+ path(const path& p);
6565
+ path(path&& p) noexcept;
6566
+ path(string_type&& source, format fmt = auto_format);
6567
+ template <class Source>
6568
+ path(const Source& source, format fmt = auto_format);
6569
+ template <class InputIterator>
6570
+ path(InputIterator first, InputIterator last, format fmt = auto_format);
6571
+ template <class Source>
6572
+ path(const Source& source, const locale& loc, format fmt = auto_format);
6573
+ template <class InputIterator>
6574
+ path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
6575
+ ~path();
6576
+
6577
+ // [fs.path.assign], assignments
6578
+ path& operator=(const path& p);
6579
+ path& operator=(path&& p) noexcept;
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);
6591
+ template <class Source>
6592
+ path& operator/=(const Source& source);
6593
+ template <class Source>
6594
+ path& append(const Source& source);
6595
+ template <class InputIterator>
6596
+ path& append(InputIterator first, InputIterator last);
6597
+
6598
+ // [fs.path.concat], concatenation
6599
+ path& operator+=(const path& x);
6600
+ path& operator+=(const string_type& x);
6601
+ path& operator+=(basic_string_view<value_type> x);
6602
+ path& operator+=(const value_type* x);
6603
+ path& operator+=(value_type x);
6604
+ template <class Source>
6605
+ path& operator+=(const Source& x);
6606
+ template <class EcharT>
6607
+ path& operator+=(EcharT x);
6608
+ template <class Source>
6609
+ path& concat(const Source& x);
6610
+ template <class InputIterator>
6611
+ path& concat(InputIterator first, InputIterator last);
6612
+
6613
+ // [fs.path.modifiers], modifiers
6614
+ void clear() noexcept;
6615
+ path& make_preferred();
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
+
6626
+ template <class EcharT, class traits = char_traits<EcharT>,
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;
6649
+ int compare(const string_type& s) const;
6650
+ int compare(basic_string_view<value_type> s) const;
6651
+ int compare(const value_type* s) const;
6652
+
6653
+ // [fs.path.decompose], decomposition
6654
+ path root_name() const;
6655
+ path root_directory() const;
6656
+ path root_path() const;
6657
+ path relative_path() const;
6658
+ path parent_path() const;
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;
6670
+ bool has_filename() const;
6671
+ bool has_stem() const;
6672
+ bool has_extension() const;
6673
+ bool is_absolute() const;
6674
+ bool is_relative() const;
6675
+
6676
+ // [fs.path.gen], generation
6677
+ path lexically_normal() const;
6678
+ path lexically_relative(const path& base) const;
6679
+ path lexically_proximate(const path& base) const;
6680
+
6681
+ // [fs.path.itr], iterators
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
+
6703
+ #### Generic pathname format <a id="fs.path.generic">[[fs.path.generic]]</a>
6704
+
6705
+ ``` bnf
6706
+ pathname:
6707
+ root-nameₒₚₜ root-directoryₒₚₜ relative-path
6708
+ ```
6709
+
6710
+ ``` bnf
6711
+ root-name:
6712
+ operating system dependent sequences of characters
6713
+ implementation-defined sequences of characters
6714
+ ```
6715
+
6716
+ ``` bnf
6717
+ root-directory:
6718
+ directory-separator
6719
+ ```
6720
+
6721
+ ``` bnf
6722
+ relative-path:
6723
+ filename
6724
+ filename directory-separator relative-path
6725
+ an empty path
6726
+ ```
6727
+
6728
+ ``` bnf
6729
+ filename:
6730
+ non-empty sequence of characters other than *directory-separator* characters
6731
+ ```
6732
+
6733
+ ``` bnf
6734
+ directory-separator:
6735
+ preferred-separator directory-separatorₒₚₜ
6736
+ fallback-separator directory-separatorₒₚₜ
6737
+ ```
6738
+
6739
+ ``` bnf
6740
+ preferred-separator:
6741
+ operating system dependent directory separator character
6742
+ ```
6743
+
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
6775
+ network or other resource locations. Some operating systems define a
6776
+ single letter followed by a colon as a drive specifier – a *root-name*
6777
+ identifying a specific device such as a disk drive. — *end note*]
6778
+
6779
+ If a *root-name* is otherwise ambiguous, the possibility with the
6780
+ 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.
6798
+ - Paths for regular files and paths for directories share the same
6799
+ syntax.
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
6815
+ disambiguation is required is permitted to distinguish between the
6816
+ formats. — *end note*]
6817
+
6818
+ Pathnames are converted as needed between the generic and native formats
6819
+ in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
6820
+ mathematical sense be the implementation’s functions that convert
6821
+ native-to-generic and generic-to-native formats respectively. If
6822
+ *g=G(n)* for some *n*, then *G(N(g))=g*; if *n=N(g)* for some *g*, then
6823
+ *N(G(n))=n*.
6824
+
6825
+ [*Note 3*: Neither *G* nor *N* need be invertible. — *end note*]
6826
+
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
6839
+ separate from any path, the other representation is selected by the
6840
+ appropriate conversion function (*G* or *N*).
6841
+
6842
+ When the (new) value *p* of one representation of a path is derived from
6843
+ the representation of that or another path, a value *q* is chosen for
6844
+ 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
+ ```
6940
+
6941
+ *Effects:* Constructs an object of class `path` having the same pathname
6942
+ in the native and generic formats, respectively, as the original value
6943
+ of `p`. In the second form, `p` is left in a valid but unspecified
6944
+ state.
6945
+
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:
6995
+
6996
+ ``` cpp
6997
+ namespace fs = std::filesystem;
6998
+ std::string latin1_string = read_latin1_data();
6999
+ codecvt_8859_1<wchar_t> latin1_facet;
7000
+ std::locale latin1_locale(std::locale(), latin1_facet);
7001
+ 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
+
7029
+ *Effects:* If `*this` and `p` are the same object, has no effect.
7030
+ Otherwise, sets both respective pathnames of `*this` to the respective
7031
+ pathnames of `p`.
7032
+
7033
+ *Returns:* `*this`.
7034
+
7035
+ ``` cpp
7036
+ path& operator=(path&& p) noexcept;
7037
+ ```
7038
+
7039
+ *Effects:* If `*this` and `p` are the same object, has no effect.
7040
+ Otherwise, sets both respective pathnames of `*this` to the respective
7041
+ pathnames of `p`. `p` is left in a valid but unspecified state.
7042
+
7043
+ [*Note 1*: A valid implementation is `swap(p)`. — *end note*]
7044
+
7045
+ *Returns:* `*this`.
7046
+
7047
+ ``` cpp
7048
+ path& operator=(string_type&& source);
7049
+ path& assign(string_type&& source);
7050
+ ```
7051
+
7052
+ *Effects:* Sets the pathname in the detected-format of `source` to the
7053
+ original value of `source`. `source` is left in a valid but unspecified
7054
+ state.
7055
+
7056
+ *Returns:* `*this`.
7057
+
7058
+ ``` cpp
7059
+ template <class Source>
7060
+ path& operator=(const Source& source);
7061
+ 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
7080
+ path& operator/=(const path& p);
7081
+ ```
7082
+
7083
+ *Effects:* If
7084
+ `p.is_absolute() || (p.has_root_name() && p.root_name() != root_name())`,
7085
+ then `operator=(p)`.
7086
+
7087
+ Otherwise, modifies `*this` as if by these steps:
7088
+
7089
+ - If `p.has_root_directory()`, then removes any root directory and
7090
+ relative path from the generic format pathname. Otherwise, if
7091
+ `!has_root_directory() && is_absolute()` is `true` or if
7092
+ `has_filename()` is `true`, then appends `path::preferred_separator`
7093
+ to the generic format pathname.
7094
+ - Then appends the native format pathname of `p`, omitting any
7095
+ *root-name* from its generic format pathname, to the native format
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`.
7122
+
7123
+ ``` cpp
7124
+ template <class Source>
7125
+ path& operator/=(const Source& source);
7126
+ template <class Source>
7127
+ path& append(const Source& source);
7128
+ ```
7129
+
7130
+ *Effects:* Equivalent to: `return operator/=(path(source));`
7131
+
7132
+ ``` cpp
7133
+ 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
7156
+ format.
7157
+
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
+
7182
+ *Effects:* Each *directory-separator* of the pathname in the generic
7183
+ format is converted to *preferred-separator*.
7184
+
7185
+ *Returns:* `*this`.
7186
+
7187
+ [*Example 3*:
7188
+
7189
+ ``` cpp
7190
+ path p("foo/bar");
7191
+ std::cout << p << '\n';
7192
+ p.make_preferred();
7193
+ std::cout << p << '\n';
7194
+ ```
7195
+
7196
+ On an operating system where *preferred-separator* is a slash, the
7197
+ output is:
7198
+
7199
+ ``` cpp
7200
+ "foo/bar"
7201
+ "foo/bar"
7202
+ ```
7203
+
7204
+ On an operating system where *preferred-separator* is a backslash, the
7205
+ output is:
7206
+
7207
+ ``` cpp
7208
+ "foo/bar"
7209
+ "foo\bar"
7210
+ ```
7211
+
7212
+ — *end example*]
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
7228
+ path("foo/bar").remove_filename(); // yields "foo/"
7229
+ path("foo/").remove_filename(); // yields "foo/"
7230
+ path("/foo").remove_filename(); // yields "/"
7231
+ path("/").remove_filename(); // yields "/"
7232
+ ```
7233
+
7234
+ — *end example*]
7235
+
7236
+ ``` cpp
7237
+ path& replace_filename(const path& replacement);
7238
+ ```
7239
+
7240
+ *Effects:* Equivalent to:
7241
+
7242
+ ``` cpp
7243
+ remove_filename();
7244
+ operator/=(replacement);
7245
+ ```
7246
+
7247
+ *Returns:* `*this`.
7248
+
7249
+ [*Example 5*:
7250
+
7251
+ ``` cpp
7252
+ path("/foo").replace_filename("bar"); // yields "/bar" on POSIX
7253
+ path("/").replace_filename("bar"); // yields "/bar" on POSIX
7254
+ ```
7255
+
7256
+ — *end example*]
7257
+
7258
+ ``` cpp
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
+
7271
+ *Returns:* `*this`.
7272
+
7273
+ ``` cpp
7274
+ void swap(path& rhs) noexcept;
7275
+ ```
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
+
7290
+ *Returns:* The pathname in the native format.
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
+
7302
+ *Returns:* `native()`.
7303
+
7304
+ [*Note 3*: Conversion to `string_type` is provided so that an object of
7305
+ class `path` can be given as an argument to existing standard library
7306
+ file stream constructors and open functions. — *end note*]
7307
+
7308
+ ``` cpp
7309
+ template <class EcharT, class traits = char_traits<EcharT>,
7310
+ class Allocator = allocator<EcharT>>
7311
+ basic_string<EcharT, traits, Allocator>
7312
+ string(const Allocator& a = Allocator()) const;
7313
+ ```
7314
+
7315
+ *Returns:* `native()`.
7316
+
7317
+ *Remarks:* All memory allocation, including for the return value, shall
7318
+ 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
+
7345
+ ``` cpp
7346
+ path("foo\\bar").generic_string()
7347
+ ```
7348
+
7349
+ returns `"foo/bar"`.
7350
+
7351
+ — *end example*]
7352
+
7353
+ ``` cpp
7354
+ template <class EcharT, class traits = char_traits<EcharT>,
7355
+ class Allocator = allocator<EcharT>>
7356
+ basic_string<EcharT, traits, Allocator>
7357
+ generic_string(const Allocator& a = Allocator()) const;
7358
+ ```
7359
+
7360
+ *Returns:* The pathname in the generic format.
7361
+
7362
+ *Remarks:* All memory allocation, including for the return value, shall
7363
+ 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
+
7417
+ *Returns:* *root-name*, if the pathname in the generic format includes
7418
+ *root-name*, otherwise `path()`.
7419
+
7420
+ ``` cpp
7421
+ path root_directory() const;
7422
+ ```
7423
+
7424
+ *Returns:* *root-directory*, if the pathname in the generic format
7425
+ includes *root-directory*, otherwise `path()`.
7426
+
7427
+ ``` cpp
7428
+ path root_path() const;
7429
+ ```
7430
+
7431
+ *Returns:* `root_name() / root_directory()`.
7432
+
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
+
7453
+ *Returns:* `relative_path().empty() ? path() : *–end()`.
7454
+
7455
+ [*Example 6*:
7456
+
7457
+ ``` cpp
7458
+ path("/foo/bar.txt").filename(); // yields "bar.txt"
7459
+ path("/foo/bar").filename(); // yields "bar"
7460
+ path("/foo/bar/").filename(); // yields ""
7461
+ path("/").filename(); // yields ""
7462
+ path("//host").filename(); // yields ""
7463
+ path(".").filename(); // yields "."
7464
+ path("..").filename(); // yields ".."
7465
+ ```
7466
+
7467
+ — *end example*]
7468
+
7469
+ ``` cpp
7470
+ path stem() const;
7471
+ ```
7472
+
7473
+ *Returns:* Let `f` be the generic format pathname of `filename()`.
7474
+ Returns a path whose pathname in the generic format is
7475
+
7476
+ - `f`, if it contains no periods other than a leading period or consists
7477
+ solely of one or two periods;
7478
+ - otherwise, the prefix of `f` ending before its last period.
7479
+
7480
+ [*Example 7*:
7481
+
7482
+ ``` cpp
7483
+ std::cout << path("/foo/bar.txt").stem(); // outputs "bar"
7484
+ path p = "foo.bar.baz.tar";
7485
+ for (; !p.extension().empty(); p = p.stem())
7486
+ std::cout << p.extension() << '\n';
7487
+ // outputs: .tar
7488
+ // .baz
7489
+ // .bar
7490
+ ```
7491
+
7492
+ — *end example*]
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
7504
+ path("/foo/bar.txt").extension(); // yields ".txt" and stem() is "bar"
7505
+ path("/foo/bar").extension(); // yields "" and stem() is "bar"
7506
+ path("/foo/.profile").extension(); // yields "" and stem() is ".profile"
7507
+ path(".bar").extension(); // yields "" and stem() is ".bar"
7508
+ path("..bar").extension(); // yields ".bar" and stem() is "."
7509
+ ```
7510
+
7511
+ — *end example*]
7512
+
7513
+ [*Note 4*: The period is included in the return value so that it is
7514
+ possible to distinguish between no extension and an empty
7515
+ 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
+
7534
+ *Returns:* `!root_path().empty()`.
7535
+
7536
+ ``` cpp
7537
+ bool has_root_name() const;
7538
+ ```
7539
+
7540
+ *Returns:* `!root_name().empty()`.
7541
+
7542
+ ``` cpp
7543
+ bool has_root_directory() const;
7544
+ ```
7545
+
7546
+ *Returns:* `!root_directory().empty()`.
7547
+
7548
+ ``` cpp
7549
+ bool has_relative_path() const;
7550
+ ```
7551
+
7552
+ *Returns:* `!relative_path().empty()`.
7553
+
7554
+ ``` cpp
7555
+ bool has_parent_path() const;
7556
+ ```
7557
+
7558
+ *Returns:* `!parent_path().empty()`.
7559
+
7560
+ ``` cpp
7561
+ bool has_filename() const;
7562
+ ```
7563
+
7564
+ *Returns:* `!filename().empty()`.
7565
+
7566
+ ``` cpp
7567
+ bool has_stem() const;
7568
+ ```
7569
+
7570
+ *Returns:* `!stem().empty()`.
7571
+
7572
+ ``` cpp
7573
+ bool has_extension() const;
7574
+ ```
7575
+
7576
+ *Returns:* `!extension().empty()`.
7577
+
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
+
7589
+ ``` cpp
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
7608
+ assert(path("foo/./bar/..").lexically_normal() == "foo/");
7609
+ assert(path("foo/.///bar/../").lexically_normal() == "foo/");
7610
+ ```
7611
+
7612
+ The above assertions will succeed. On Windows, the returned path’s
7613
+ *directory-separator* characters will be backslashes rather than
7614
+ slashes, but that does not affect `path` equality.
7615
+
7616
+ — *end example*]
7617
+
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
+
7647
+ [*Example 11*:
7648
+
7649
+ ``` cpp
7650
+ assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
7651
+ assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
7652
+ assert(path("a/b/c").lexically_relative("a") == "b/c");
7653
+ assert(path("a/b/c").lexically_relative("a/b/c/x/y") == "../..");
7654
+ assert(path("a/b/c").lexically_relative("a/b/c") == ".");
7655
+ assert(path("a/b").lexically_relative("c/d") == "../../a/b");
7656
+ ```
7657
+
7658
+ 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
7700
+ traversal order is as follows:
7701
+
7702
+ - The *root-name* element, if present.
7703
+ - The *root-directory* element, if present. \[*Note 1*: The generic
7704
+ format is required to ensure lexicographical comparison works
7705
+ correctly. — *end note*]
7706
+ - Each successive *filename* element, if present.
7707
+ - An empty element, if a trailing non-root *directory-separator* is
7708
+ present.
7709
+
7710
+ The backward traversal order is the reverse of forward traversal.
7711
+
7712
+ ``` cpp
7713
+ iterator begin() const;
7714
+ ```
7715
+
7716
+ *Returns:* An iterator for the first present element in the traversal
7717
+ list above. If no elements are present, the end iterator.
7718
+
7719
+ ``` cpp
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 path’s 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:
7891
+ filesystem_error(const string& what_arg, error_code ec);
7892
+ filesystem_error(const string& what_arg,
7893
+ const path& p1, error_code ec);
7894
+ filesystem_error(const string& what_arg,
7895
+ const path& p1, const path& p2, error_code ec);
7896
+
7897
+ const path& path1() const noexcept;
7898
+ const path& path2() const noexcept;
7899
+ const char* what() const noexcept override;
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
+
7965
+ *Returns:* A reference to the copy of `p1` stored by the constructor,
7966
+ or, if none, an empty path.
7967
+
7968
+ ``` cpp
7969
+ const path& path2() const noexcept;
7970
+ ```
7971
+
7972
+ *Returns:* A reference to the copy of `p2` stored by the constructor,
7973
+ 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. |
8019
+ | `overwrite_existing` | Overwrite the existing file. |
8020
+ | `update_existing` | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for sub-directories} |
8021
+ | `recursive` | Recursively copy sub-directories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links} |
8022
+ | `copy_symlinks` | Copy symbolic links as symbolic links rather than copying the files that they point to. |
8023
+ | `skip_symlinks` | Ignore symbolic links. \ohdrx{2}{Option group controlling `copy` function effects for choosing the form of copying} |
8024
+ | `directories_only` | Copy directory structure only, do not copy non-directory files. |
8025
+ | `create_symlinks` | Make symbolic links instead of copies of files. The source path shall be an absolute path unless the destination path is in the current directory. |
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 |
8041
+ | `owner_write` | `0200` | `S_IWUSR` | Write permission, owner |
8042
+ | `owner_exec` | `0100` | `S_IXUSR` | Execute/search permission, owner |
8043
+ | `owner_all` | `0700` | `S_IRWXU` | Read, write, execute/search by owner;<br> `owner_read | owner_write | owner_exec` |
8044
+ | `group_read` | `040` | `S_IRGRP` | Read permission, group |
8045
+ | `group_write` | `020` | `S_IWGRP` | Write permission, group |
8046
+ | `group_exec` | `010` | `S_IXGRP` | Execute/search permission, group |
8047
+ | `group_all` | `070` | `S_IRWXG` | Read, write, execute/search by group;<br> `group_read | group_write | group_exec` |
8048
+ | `others_read` | `04` | `S_IROTH` | Read permission, others |
8049
+ | `others_write` | `02` | `S_IWOTH` | Write permission, others |
8050
+ | `others_exec` | `01` | `S_IXOTH` | Execute/search permission, others |
8051
+ | `others_all` | `07` | `S_IRWXO` | Read, write, execute/search by others;<br> `others_read | others_write | others_exec` |
8052
+ | `all` | `0777` | | `owner_all | group_all | others_all` |
8053
+ | `set_uid` | `04000` | `S_ISUID` | Set-user-ID on execution |
8054
+ | `set_gid` | `02000` | `S_ISGID` | Set-group-ID on execution |
8055
+ | `sticky_bit` | `01000` | `S_ISVTX` | Operating system dependent. |
8056
+ | `mask` | `07777` | | `all | set_uid | set_gid | sticky_bit` |
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
+
8138
+ *Returns:* The value of `type()` specified by the postconditions of the
8139
+ most recent call to a constructor, `operator=`, or `type(file_type)`
8140
+ function.
8141
+
8142
+ ``` cpp
8143
+ perms permissions() const noexcept;
8144
+ ```
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;
8198
+ bool is_character_file(error_code& ec) const noexcept;
8199
+ bool is_directory() const;
8200
+ bool is_directory(error_code& ec) const noexcept;
8201
+ bool is_fifo() const;
8202
+ bool is_fifo(error_code& ec) const noexcept;
8203
+ bool is_other() const;
8204
+ bool is_other(error_code& ec) const noexcept;
8205
+ bool is_regular_file() const;
8206
+ bool is_regular_file(error_code& ec) const noexcept;
8207
+ bool is_socket() const;
8208
+ bool is_socket(error_code& ec) const noexcept;
8209
+ bool is_symlink() const;
8210
+ bool is_symlink(error_code& ec) const noexcept;
8211
+ uintmax_t file_size() const;
8212
+ uintmax_t file_size(error_code& ec) const noexcept;
8213
+ uintmax_t hard_link_count() const;
8214
+ uintmax_t hard_link_count(error_code& ec) const noexcept;
8215
+ file_time_type last_write_time() const;
8216
+ file_time_type last_write_time(error_code& ec) const noexcept;
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
+
8253
+ [*Example 1*:
8254
+
8255
+ ``` cpp
8256
+ using namespace std::filesystem;
8257
+
8258
+ // use possibly cached last write time to minimize disk accesses
8259
+ for (auto&& x : directory_iterator("."))
8260
+ {
8261
+ std::cout << x.path() << " " << x.last_write_time() << std::endl;
8262
+ }
8263
+
8264
+ // call refresh() to refresh a stale cache
8265
+ for (auto&& x : directory_iterator("."))
8266
+ {
8267
+ lengthy_function(x.path()); // cache becomes stale
8268
+ x.refresh();
8269
+ std::cout << x.path() << " " << x.last_write_time() << std::endl;
8270
+ }
8271
+ ```
8272
+
8273
+ On implementations that do not cache the last write time, both loops
8274
+ will result in a potentially expensive call to the
8275
+ `std::filesystem::last_write_time` function. On implementations that do
8276
+ cache the last write time, the first loop will use the cached value and
8277
+ 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.
8319
+
8320
+ *Throws:* As specified in  [[fs.err.report]].
8321
+
8322
+ ``` cpp
8323
+ 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;
8445
+ uintmax_t file_size(error_code& ec) const noexcept;
8446
+ ```
8447
+
8448
+ *Returns:* If cached, the file size attribute value. Otherwise,
8449
+ `file_size(path())` or `file_size(path(), ec)`, respectively.
8450
+
8451
+ *Throws:* As specified in  [[fs.err.report]].
8452
+
8453
+ ``` cpp
8454
+ uintmax_t hard_link_count() const;
8455
+ uintmax_t hard_link_count(error_code& ec) const noexcept;
8456
+ ```
8457
+
8458
+ *Returns:* If cached, the hard link count attribute value. Otherwise,
8459
+ `hard_link_count(path())` or `hard_link_count(path(), ec)`,
8460
+ respectively.
8461
+
8462
+ *Throws:* As specified in  [[fs.err.report]].
8463
+
8464
+ ``` cpp
8465
+ file_time_type last_write_time() const;
8466
+ file_time_type last_write_time(error_code& ec) const noexcept;
8467
+ ```
8468
+
8469
+ *Returns:* If cached, the last write time attribute value. Otherwise,
8470
+ `last_write_time(path())` or `last_write_time(path(), ec)`,
8471
+ respectively.
8472
+
8473
+ *Throws:* As specified in  [[fs.err.report]].
8474
+
8475
+ ``` cpp
8476
+ file_status status() const;
8477
+ file_status status(error_code& ec) const noexcept;
8478
+ ```
8479
+
8480
+ *Returns:* If cached, the status attribute value. Otherwise,
8481
+ `status(path())` or `status(path(), ec)`, respectively.
8482
+
8483
+ *Throws:* As specified in  [[fs.err.report]].
8484
+
8485
+ ``` cpp
8486
+ file_status symlink_status() const;
8487
+ file_status symlink_status(error_code& ec) const noexcept;
8488
+ ```
8489
+
8490
+ *Returns:* If cached, the symlink status attribute value. Otherwise,
8491
+ `symlink_status(path())` or `symlink_status(path(), ec)`, respectively.
8492
+
8493
+ *Throws:* As specified in  [[fs.err.report]].
8494
+
8495
+ ``` cpp
8496
+ 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:
8546
+ using iterator_category = input_iterator_tag;
8547
+ using value_type = directory_entry;
8548
+ using difference_type = ptrdiff_t;
8549
+ using pointer = const directory_entry*;
8550
+ using reference = const directory_entry&;
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,
8583
+ and this shall be the only valid iterator for the end condition.
8584
+
8585
+ The end iterator is not dereferenceable.
8586
+
8587
+ Two end iterators are always equal. An end iterator shall not be equal
8588
+ to a non-end iterator.
8589
+
8590
+ The result of calling the `path()` member of the `directory_entry`
8591
+ 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
8616
+ walking directory trees for purposes of removing and renaming entries
8617
+ may wish to avoid following symbolic links. — *end note*]
8618
+
8619
+ [*Note 4*: If a file is removed from or added to a directory after the
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
8643
+ end iterator. However, if
8644
+
8645
+ ``` cpp
8646
+ (options & directory_options::skip_permission_denied) != directory_options::none
8647
+ ```
8648
+
8649
+ and construction encounters an error indicating that permission to
8650
+ access `p` is denied, constructs the end iterator and does not report an
8651
+ error.
8652
+
8653
+ *Throws:* As specified in  [[fs.err.report]].
8654
+
8655
+ [*Note 1*: To iterate over the current directory, use
8656
+ `directory_iterator(".")` rather than
8657
+ `directory_iterator("")`. — *end note*]
8658
+
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;
8698
+ ```
8699
+
8700
+ *Returns:* `iter`.
8701
+
8702
+ ``` cpp
8703
+ directory_iterator end(const directory_iterator&) noexcept;
8704
+ ```
8705
+
8706
+ *Returns:* `directory_iterator()`.
8707
+
8708
+ ### Class `recursive_directory_iterator` <a id="fs.class.rec.dir.itr">[[fs.class.rec.dir.itr]]</a>
8709
+
8710
+ An object of type `recursive_directory_iterator` provides an iterator
8711
+ for a sequence of `directory_entry` elements representing the files in a
8712
+ directory or in an *implementation-defined* directory-like file type,
8713
+ and its sub-directories.
8714
+
8715
+ ``` cpp
8716
+ namespace std::filesystem {
8717
+ class recursive_directory_iterator {
8718
+ public:
8719
+ using iterator_category = input_iterator_tag;
8720
+ using value_type = directory_entry;
8721
+ using difference_type = ptrdiff_t;
8722
+ using pointer = const directory_entry*;
8723
+ using reference = const directory_entry&;
8724
+
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
8737
+ directory_options options() const;
8738
+ int depth() const;
8739
+ bool recursion_pending() const;
8740
+
8741
+ const directory_entry& operator*() const;
8742
+ const directory_entry* operator->() const;
8743
+
8744
+ // [fs.rec.dir.itr.members], modifiers
8745
+ recursive_directory_iterator&
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
+
8757
+ // other members as required by [input.iterators], input iterators
8758
+ };
8759
+ }
8760
+ ```
8761
+
8762
+ Calling `options`, `depth`, `recursion_pending`, `pop` or
8763
+ `disable_recursion_pending` on an iterator that is not dereferenceable
8764
+ results in undefined behavior.
8765
+
8766
+ 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
+
8805
+ [*Note 1*: To iterate over the current directory, use
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
+
8848
+ *Returns:* `*this`.
8849
+
8850
+ ``` cpp
8851
+ recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;
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
8864
+ directory_options options() const;
8865
+ ```
8866
+
8867
+ *Returns:* The value of the argument passed to the constructor for the
8868
+ `options` parameter, if present, otherwise `directory_options::none`.
8869
+
8870
+ *Throws:* Nothing.
8871
+
8872
+ ``` cpp
8873
+ int depth() const;
8874
+ ```
8875
+
8876
+ *Returns:* The current depth of the directory tree being traversed.
8877
+
8878
+ [*Note 3*: The initial directory is depth `0`, its immediate
8879
+ subdirectories are depth `1`, and so forth. — *end note*]
8880
+
8881
+ *Throws:* Nothing.
8882
+
8883
+ ``` cpp
8884
+ bool recursion_pending() const;
8885
+ ```
8886
+
8887
+ *Returns:* `true` if `disable_recursion_pending()` has not been called
8888
+ subsequent to the prior construction or increment operation, otherwise
8889
+ `false`.
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
8905
+ ``` cpp
8906
+ recursion_pending() && is_directory((*this)->status()) &&
8907
+ (!is_symlink((*this)->symlink_status()) ||
8908
+ (options() & directory_options::follow_directory_symlink) != directory_options::none)
8909
+ ```
8910
+
8911
+ then either directory `(*this)->path()` is recursively iterated into
8912
+ or, if
8913
+ ``` cpp
8914
+ (options() & directory_options::skip_permission_denied) != directory_options::none
8915
+ ```
8916
+
8917
+ and an error occurs indicating that permission to access directory
8918
+ `(*this)->path()` is denied, then directory `(*this)->path()` is
8919
+ treated as an empty directory and no error is reported.
8920
+
8921
+ *Returns:* `*this`.
8922
+
8923
+ *Throws:* As specified in  [[fs.err.report]].
8924
+
8925
+ ``` cpp
8926
+ void pop();
8927
+ void pop(error_code& ec);
8928
+ ```
8929
+
8930
+ *Effects:* If `depth() == 0`, set `*this` to
8931
+ `recursive_directory_iterator()`. Otherwise, cease iteration of the
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
8952
+ recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
8953
+ ```
8954
+
8955
+ *Returns:* `iter`.
8956
+
8957
+ ``` cpp
8958
+ recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
8959
+ ```
8960
+
8961
+ *Returns:* `recursive_directory_iterator()`.
8962
+
8963
+ ### Filesystem operation functions <a id="fs.op.funcs">[[fs.op.funcs]]</a>
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>
8975
+
8976
+ ``` cpp
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`
8988
+ 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
+
9000
+ [*Example 1*: For POSIX-based operating systems, `absolute(p)` is
9001
+ simply `current_path()/p`. For Windows-based operating systems,
9002
+ `absolute` might have the same semantics as
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.
9025
+
9026
+ #### Copy <a id="fs.op.copy">[[fs.op.copy]]</a>
9027
+
9028
+ ``` cpp
9029
+ 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
9053
+ (options & copy_options::create_symlinks) != copy_options::none ||
9054
+ (options & copy_options::skip_symlinks) != copy_options::none
9055
+ ```
9056
+
9057
+ then `auto f = symlink_status(from)` and if needed
9058
+ `auto t = symlink_status(to)`.
9059
+ - Otherwise, if
9060
+ ``` cpp
9061
+ (options & copy_options::copy_symlinks) != copy_options::none
9062
+ ```
9063
+
9064
+ then `auto f = symlink_status(from)` and if needed
9065
+ `auto t = status(to)`.
9066
+ - Otherwise, `auto f = status(from)` and if needed
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
9084
+ !exists(t) && (options & copy_options::copy_symlinks) != copy_options::none
9085
+ ```
9086
+
9087
+ then `copy_symlink(from, to)`.
9088
+ - Otherwise report an error as specified in  [[fs.err.report]].
9089
+ - Otherwise, if `is_regular_file(f)`, then:
9090
+ - If
9091
+ `(options & copy_options::directories_only) != copy_options::none`,
9092
+ then return.
9093
+ - Otherwise, if
9094
+ `(options & copy_options::create_symlinks) `` != copy_options::none`,
9095
+ then create a symbolic link to the source file.
9096
+ - Otherwise, if
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
+
9121
+ *Remarks:* For the signature with argument `ec`, any library functions
9122
+ called by the implementation shall have an `error_code` argument if
9123
+ applicable.
9124
+
9125
+ [*Example 1*:
9126
+
9127
+ Given this directory structure:
9128
+
9129
+ ``` cpp
9130
+ /dir1
9131
+ file1
9132
+ file2
9133
+ dir2
9134
+ file3
9135
+ ```
9136
+
9137
+ Calling `copy("/dir1", "/dir3")` would result in:
9138
+
9139
+ ``` cpp
9140
+ /dir1
9141
+ file1
9142
+ file2
9143
+ dir2
9144
+ file3
9145
+ /dir3
9146
+ file1
9147
+ file2
9148
+ ```
9149
+
9150
+ Alternatively, calling `copy("/dir1", "/dir3", copy_options::recursive)`
9151
+ would result in:
9152
+
9153
+ ``` cpp
9154
+ /dir1
9155
+ file1
9156
+ file2
9157
+ dir2
9158
+ file3
9159
+ /dir3
9160
+ file1
9161
+ file2
9162
+ dir2
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;
9225
+ ```
9226
+
9227
+ *Effects:* Equivalent to
9228
+ *`function`*`(read_symlink(existing_symlink), new_symlink)` or
9229
+ *`function`*`(read_symlink(existing_symlink, ec), new_symlink, ec)`,
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
9316
+ `create_directory_symlink()` to create directory symlinks rather than
9317
+ `create_symlink()` — *end note*]
9318
+
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]].
9340
+
9341
+ [*Note 1*: Some operating systems do not support hard links at all or
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
+ ```
9373
+
9374
+ *Returns:* The absolute path of the current working directory, whose
9375
+ pathname in the native format is obtained as if by POSIX `getcwd()`. The
9376
+ signature with argument `ec` returns `path()` if an error occurs.
9377
+
9378
+ *Throws:* As specified in  [[fs.err.report]].
9379
+
9380
+ *Remarks:* The current working directory is the directory, associated
9381
+ with the process, that is used as the starting location in pathname
9382
+ resolution for relative paths.
9383
+
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
9406
+ library functions, or by another thread. — *end note*]
9407
+
9408
+ #### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
9409
+
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
+
9436
+ ``` cpp
9437
+ bool exists(file_status s) noexcept;
9438
+ ```
9439
+
9440
+ *Returns:* `status_known(s) && s.type() != file_type::not_found`.
9441
+
9442
+ ``` cpp
9443
+ bool exists(const path& p);
9444
+ bool exists(const path& p, error_code& ec) noexcept;
9445
+ ```
9446
+
9447
+ Let `s` be a `file_status`, determined as if by `status(p)` or
9448
+ `status(p, ec)`, respectively.
9449
+
9450
+ *Effects:* The signature with argument `ec` calls `ec.clear()` if
9451
+ `status_known(s)`.
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
+ ```
9483
+
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
+
9495
+ *Returns:* `s.type() == file_type::block`.
9496
+
9497
+ ``` cpp
9498
+ bool is_block_file(const path& p);
9499
+ bool is_block_file(const path& p, error_code& ec) noexcept;
9500
+ ```
9501
+
9502
+ *Returns:* `is_block_file(status(p))` or `is_block_file(status(p, ec))`,
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
+
9514
+ *Returns:* `s.type() == file_type::character`.
9515
+
9516
+ ``` cpp
9517
+ bool is_character_file(const path& p);
9518
+ bool is_character_file(const path& p, error_code& ec) noexcept;
9519
+ ```
9520
+
9521
+ *Returns:* `is_character_file(status(p))` or
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
+
9533
+ *Returns:* `s.type() == file_type::directory`.
9534
+
9535
+ ``` cpp
9536
+ bool is_directory(const path& p);
9537
+ bool is_directory(const path& p, error_code& ec) noexcept;
9538
+ ```
9539
+
9540
+ *Returns:* `is_directory(status(p))` or `is_directory(status(p, ec))`,
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)`,
9556
+ respectively.
9557
+ - For the signature with argument `ec`, return `false` if an error
9558
+ occurred.
9559
+ - Otherwise, if `is_directory(s)`:
9560
+ - Create a variable `itr`, as if by `directory_iterator itr(p)` or
9561
+ `directory_iterator itr(p, ec)`, respectively.
9562
+ - For the signature with argument `ec`, return `false` if an error
9563
+ occurred.
9564
+ - Otherwise, return `itr == directory_iterator()`.
9565
+ - Otherwise:
9566
+ - Determine `uintmax_t sz`, as if by `file_size(p)` or
9567
+ `file_size(p, ec)`, respectively.
9568
+ - For the signature with argument `ec`, return `false` if an error
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
+
9580
+ *Returns:* `s.type() == file_type::fifo`.
9581
+
9582
+ ``` cpp
9583
+ bool is_fifo(const path& p);
9584
+ bool is_fifo(const path& p, error_code& ec) noexcept;
9585
+ ```
9586
+
9587
+ *Returns:* `is_fifo(status(p))` or `is_fifo(status(p, ec))`,
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
+
9599
+ *Returns:*
9600
+ `exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)`.
9601
+
9602
+ ``` cpp
9603
+ bool is_other(const path& p);
9604
+ bool is_other(const path& p, error_code& ec) noexcept;
9605
+ ```
9606
+
9607
+ *Returns:* `is_other(status(p))` or `is_other(status(p, ec))`,
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
+
9619
+ *Returns:* `s.type() == file_type::regular`.
9620
+
9621
+ ``` cpp
9622
+ 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
+
9634
+ *Effects:* Sets `ec` as if by `status(p, ec)`.
9635
+
9636
+ [*Note 1*: `file_type::none`, `file_type::not_found` and
9637
+ `file_type::unknown` cases set `ec` to error values. To distinguish
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
+
9649
+ *Returns:* `s.type() == file_type::socket`.
9650
+
9651
+ ``` cpp
9652
+ bool is_socket(const path& p);
9653
+ bool is_socket(const path& p, error_code& ec) noexcept;
9654
+ ```
9655
+
9656
+ *Returns:* `is_socket(status(p))` or `is_socket(status(p, ec))`,
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
+
9668
+ *Returns:* `s.type() == file_type::symlink`.
9669
+
9670
+ ``` cpp
9671
+ bool is_symlink(const path& p);
9672
+ bool is_symlink(const path& p, error_code& ec) noexcept;
9673
+ ```
9674
+
9675
+ *Returns:* `is_symlink(symlink_status(p))` or
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
9696
+ void last_write_time(const path& p, file_time_type new_time);
9697
+ void last_write_time(const path& p, file_time_type new_time,
9698
+ error_code& ec) noexcept;
9699
+ ```
9700
+
9701
+ *Effects:* Sets the time of last data modification of the file resolved
9702
+ to by `p` to `new_time`, as if by POSIX `futimens()`.
9703
+
9704
+ *Throws:* As specified in  [[fs.err.report]].
9705
+
9706
+ [*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
9707
+ specified since it might not hold for file systems with coarse time
9708
+ granularity. — *end note*]
9709
+
9710
+ #### Permissions <a id="fs.op.permissions">[[fs.op.permissions]]</a>
9711
+
9712
+ ``` cpp
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`.
9724
+
9725
+ *Effects:* Applies the action specified by `opts` to the file `p`
9726
+ resolves to, or to file `p` itself if `p` is a symbolic link and
9727
+ `perm_options::nofollow` is set in `opts`. The action is applied as if
9728
+ by POSIX `fchmodat()`.
9729
+
9730
+ [*Note 1*: Conceptually permissions are viewed as bits, but the actual
9731
+ implementation may use some other mechanism. — *end note*]
9732
+
9733
+ *Throws:* As specified in  [[fs.err.report]].
9734
+
9735
+ #### Proximate <a id="fs.op.proximate">[[fs.op.proximate]]</a>
9736
+
9737
+ ``` cpp
9738
+ path proximate(const path& p, error_code& ec);
9739
+ ```
9740
+
9741
+ *Returns:* `proximate(p, current_path(), ec)`.
9742
+
9743
+ *Throws:* As specified in  [[fs.err.report]].
9744
+
9745
+ ``` cpp
9746
+ path proximate(const path& p, const path& base = current_path());
9747
+ path proximate(const path& p, const path& base, error_code& ec);
9748
+ ```
9749
+
9750
+ *Returns:* For the first form:
9751
+
9752
+ ``` cpp
9753
+ weakly_canonical(p).lexically_proximate(weakly_canonical(base));
9754
+ ```
9755
+
9756
+ For the second form:
9757
+
9758
+ ``` cpp
9759
+ weakly_canonical(p, ec).lexically_proximate(weakly_canonical(base, ec));
9760
+ ```
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
+ ```
9772
+
9773
+ *Returns:* If `p` resolves to a symbolic link, a `path` object
9774
+ containing the contents of that symbolic link. The signature with
9775
+ argument `ec` returns `path()` if an error occurs.
9776
+
9777
+ *Throws:* As specified in  [[fs.err.report]].
9778
+
9779
+ [*Note 1*: It is an error if `p` does not resolve to a symbolic
9780
+ link. — *end note*]
9781
+
9782
+ #### Relative <a id="fs.op.relative">[[fs.op.relative]]</a>
9783
+
9784
+ ``` cpp
9785
+ path relative(const path& p, error_code& ec);
9786
+ ```
9787
+
9788
+ *Returns:* `relative(p, current_path(), ec)`.
9789
+
9790
+ *Throws:* As specified in  [[fs.err.report]].
9791
+
9792
+ ``` cpp
9793
+ path relative(const path& p, const path& base = current_path());
9794
+ path relative(const path& p, const path& base, error_code& ec);
9795
+ ```
9796
+
9797
+ *Returns:* For the first form:
9798
+
9799
+ ``` cpp
9800
+ weakly_canonical(p).lexically_relative(weakly_canonical(base));
9801
+ ```
9802
+
9803
+ For the second form:
9804
+
9805
+ ``` cpp
9806
+ weakly_canonical(p, ec).lexically_relative(weakly_canonical(base, ec));
9807
+ ```
9808
+
9809
+ or `path()` at the first error occurrence, if any.
9810
+
9811
+ *Throws:* As specified in  [[fs.err.report]].
9812
+
9813
+ #### Remove <a id="fs.op.remove">[[fs.op.remove]]</a>
9814
+
9815
+ ``` cpp
9816
+ bool remove(const path& p);
9817
+ bool remove(const path& p, error_code& ec) noexcept;
9818
+ ```
9819
+
9820
+ *Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
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]].
9852
+
9853
+ #### Rename <a id="fs.op.rename">[[fs.op.rename]]</a>
9854
+
9855
+ ``` cpp
9856
+ void rename(const path& old_p, const path& new_p);
9857
+ void rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
9858
+ ```
9859
+
9860
+ *Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
9861
+
9862
+ [*Note 1*:
9863
+
9864
+ - If `old_p` and `new_p` resolve to the same existing file, no action is
9865
+ taken.
9866
+ - Otherwise, the rename may include the following effects:
9867
+ - if `new_p` resolves to an existing non-directory file, `new_p` is
9868
+ removed; otherwise,
9869
+ - if `new_p` resolves to an existing directory, `new_p` is removed if
9870
+ empty on POSIX compliant operating systems but may be an error on
9871
+ other operating systems.
9872
+
9873
+ 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;
9897
+ ```
9898
+
9899
+ *Returns:* An object of type `space_info`. The value of the `space_info`
9900
+ object is determined as if by using POSIX `statvfs` to obtain a POSIX
9901
+ `struct statvfs`, and then multiplying its `f_blocks`, `f_bfree`, and
9902
+ `f_bavail` members by its `f_frsize` member, and assigning the results
9903
+ to the `capacity`, `free`, and `available` members respectively. Any
9904
+ members for which the value cannot be determined shall be set to
9905
+ `static_cast<uintmax_t>(-1)`. For the signature with argument `ec`, all
9906
+ members are set to `static_cast<uintmax_t>(-1)` if an error occurs.
9907
+
9908
+ *Throws:* As specified in  [[fs.err.report]].
9909
+
9910
+ *Remarks:* The value of member `space_info::available` is operating
9911
+ system dependent.
9912
+
9913
+ [*Note 1*: `available` may be less than `free`. — *end note*]
9914
+
9915
+ #### Status <a id="fs.op.status">[[fs.op.status]]</a>
9916
+
9917
+ ``` cpp
9918
+ file_status status(const path& p);
9919
+ ```
9920
+
9921
+ *Effects:* As if:
9922
+
9923
+ ``` cpp
9924
+ error_code ec;
9925
+ file_status result = status(p, ec);
9926
+ if (result.type() == file_type::none)
9927
+ throw filesystem_error(implementation-supplied-message, p, ec);
9928
+ return result;
9929
+ ```
9930
+
9931
+ *Returns:* See above.
9932
+
9933
+ *Throws:* `filesystem_error`.
9934
+
9935
+ [*Note 1*: `result` values of `file_status(file_type::not_found)` and
9936
+ `file_status(file_type::unknown)` are not considered failures and do not
9937
+ cause an exception to be thrown. — *end note*]
9938
+
9939
+ ``` cpp
9940
+ file_status status(const path& p, error_code& ec) noexcept;
9941
+ ```
9942
+
9943
+ *Effects:* If possible, determines the attributes of the file `p`
9944
+ resolves to, as if by using POSIX `stat()` to obtain a POSIX
9945
+ `struct stat`. If, during attribute determination, the underlying file
9946
+ system API reports an error, sets `ec` to indicate the specific error
9947
+ reported. Otherwise, `ec.clear()`.
9948
+
9949
+ [*Note 2*: This allows users to inspect the specifics of underlying API
9950
+ errors even when the value returned by `status()` is not
9951
+ `file_status(file_type::none)`. — *end note*]
9952
+
9953
+ Let `prms` denote the result of `(m & perms::mask)`, where `m` is
9954
+ determined as if by converting the `st_mode` member of the obtained
9955
+ `struct stat` to the type `perms`.
9956
+
9957
+ *Returns:*
9958
+
9959
+ - If `ec != error_code()`:
9960
+ - If the specific error indicates that `p` cannot be resolved because
9961
+ some element of the path does not exist, returns
9962
+ `file_status(file_type::not_found)`.
9963
+ - Otherwise, if the specific error indicates that `p` can be resolved
9964
+ but the attributes cannot be determined, returns
9965
+ `file_status(file_type::unknown)`.
9966
+ - Otherwise, returns `file_status(file_type::none)`.
9967
+
9968
+ \[*Note 1*: These semantics distinguish between `p` being known not to
9969
+ exist, `p` existing but not being able to determine its attributes,
9970
+ and there being an error that prevents even knowing if `p` exists.
9971
+ These distinctions are important to some use cases. — *end note*]
9972
+ - Otherwise,
9973
+ - If the attributes indicate a regular file, as if by POSIX `S_ISREG`,
9974
+ returns `file_status(file_type::regular, prms)`.
9975
+ \[*Note 2*: `file_type::regular` implies appropriate `<fstream>`
9976
+ operations would succeed, assuming no hardware, permission, access,
9977
+ or file system race errors. Lack of `file_type::regular` does not
9978
+ necessarily imply `<fstream>` operations would fail on a
9979
+ directory. — *end note*]
9980
+ - Otherwise, if the attributes indicate a directory, as if by POSIX
9981
+ `S_ISDIR`, returns `file_status(file_type::directory, prms)`.
9982
+ \[*Note 3*: `file_type::directory` implies that calling
9983
+ `directory_iterator(p)` would succeed. — *end note*]
9984
+ - Otherwise, if the attributes indicate a block special file, as if by
9985
+ POSIX `S_ISBLK`, returns `file_status(file_type::block, prms)`.
9986
+ - Otherwise, if the attributes indicate a character special file, as
9987
+ if by POSIX `S_ISCHR`, returns
9988
+ `file_status(file_type::character, prms)`.
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
+ ```
10016
+
10017
+ *Effects:* Same as `status()`, above, except that the attributes of `p`
10018
+ are determined as if by using POSIX `lstat()` to obtain a POSIX
10019
+ `struct stat`.
10020
+
10021
+ Let `prms` denote the result of `(m & perms::mask)`, where `m` is
10022
+ determined as if by converting the `st_mode` member of the obtained
10023
+ `struct stat` to the type `perms`.
10024
+
10025
+ *Returns:* Same as `status()`, above, except that if the attributes
10026
+ indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
10027
+ `file_status(file_type::symlink, prms)`. The signature with argument
10028
+ `ec` returns `file_status(file_type::none)` if an error occurs.
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
10049
+ 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
+
10086
+ ### Header `<cstdio>` synopsis <a id="cstdio.syn">[[cstdio.syn]]</a>
10087
+
10088
+ ``` cpp
10089
+ namespace std {
10090
+ using size_t = see [support.types.layout];
10091
+ using FILE = see below;
10092
+ using fpos_t = see below;
10093
+ }
10094
+
10095
+ #define NULL see [support.types.nullptr]
10096
+ #define _IOFBF see below
10097
+ #define _IOLBF see below
10098
+ #define _IONBF see below
10099
+ #define BUFSIZ see below
10100
+ #define EOF see below
10101
+ #define FOPEN_MAX see below
10102
+ #define FILENAME_MAX see below
10103
+ #define L_tmpnam see below
10104
+ #define SEEK_CUR see below
10105
+ #define SEEK_END see below
10106
+ #define SEEK_SET see below
10107
+ #define TMP_MAX see below
10108
+ #define stderr see below
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);
10120
+ FILE* freopen(const char* filename, const char* mode, FILE* stream);
10121
+ void setbuf(FILE* stream, char* buf);
10122
+ int setvbuf(FILE* stream, char* buf, int mode, size_t size);
10123
+ int fprintf(FILE* stream, const char* format, ...);
10124
+ int fscanf(FILE* stream, const char* format, ...);
10125
+ int printf(const char* format, ...);
10126
+ int scanf(const char* format, ...);
10127
+ int snprintf(char* s, size_t n, const char* format, ...);
10128
+ int sprintf(char* s, const char* format, ...);
10129
+ int sscanf(const char* s, const char* format, ...);
10130
+ int vfprintf(FILE* stream, const char* format, va_list arg);
10131
+ int vfscanf(FILE* stream, const char* format, va_list arg);
10132
+ int vprintf(const char* format, va_list arg);
10133
+ int vscanf(const char* format, va_list arg);
10134
+ int vsnprintf(char* s, size_t n, const char* format, va_list arg);
10135
+ int vsprintf(char* s, const char* format, va_list arg);
10136
+ int vsscanf(const char* s, const char* format, va_list arg);
10137
+ int fgetc(FILE* stream);
10138
+ char* fgets(char* s, int n, FILE* stream);
10139
+ int fputc(int c, FILE* stream);
10140
+ int fputs(const char* s, FILE* stream);
10141
+ int getc(FILE* stream);
10142
+ int getchar();
10143
+ int putc(int c, FILE* stream);
10144
+ int putchar(int c);
10145
+ int puts(const char* s);
10146
+ int ungetc(int c, FILE* stream);
10147
+ size_t fread(void* ptr, size_t size, size_t nmemb, FILE* stream);
10148
+ size_t fwrite(const void* ptr, size_t size, size_t nmemb, FILE* stream);
10149
+ int fgetpos(FILE* stream, fpos_t* pos);
10150
+ int fseek(FILE* stream, long int offset, int whence);
10151
+ int fsetpos(FILE* stream, const fpos_t* pos);
10152
+ long int ftell(FILE* stream);
10153
+ void rewind(FILE* stream);
10154
+ void clearerr(FILE* stream);
10155
+ int feof(FILE* stream);
10156
+ int ferror(FILE* stream);
10157
+ void perror(const char* s);
10158
+ }
10159
+ ```
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]
10174
+
10175
+ namespace std {
10176
+ using imaxdiv_t = see below;
10177
+
10178
+ intmax_t imaxabs(intmax_t j);
10179
+ imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
10180
+ intmax_t strtoimax(const char* nptr, char** endptr, int base);
10181
+ uintmax_t strtoumax(const char* nptr, char** endptr, int base);
10182
+ intmax_t wcstoimax(const wchar_t* nptr, wchar_t** endptr, int base);
10183
+ uintmax_t wcstoumax(const wchar_t* nptr, wchar_t** endptr, int base);
10184
+
10185
+ intmax_t abs(intmax_t); // optional, see below
10186
+ imaxdiv_t div(intmax_t, intmax_t); // optional, see below
10187
+ }
10188
+
10189
+ #define PRIdN see below
10190
+ #define PRIiN see below
10191
+ #define PRIoN see below
10192
+ #define PRIuN see below
10193
+ #define PRIxN see below
10194
+ #define PRIXN see below
10195
+ #define SCNdN see below
10196
+ #define SCNiN see below
10197
+ #define SCNoN see below
10198
+ #define SCNuN see below
10199
+ #define SCNxN see below
10200
+ #define PRIdLEASTN see below
10201
+ #define PRIiLEASTN see below
10202
+ #define PRIoLEASTN see below
10203
+ #define PRIuLEASTN see below
10204
+ #define PRIxLEASTN see below
10205
+ #define PRIXLEASTN see below
10206
+ #define SCNdLEASTN see below
10207
+ #define SCNiLEASTN see below
10208
+ #define SCNoLEASTN see below
10209
+ #define SCNuLEASTN see below
10210
+ #define SCNxLEASTN see below
10211
+ #define PRIdFASTN see below
10212
+ #define PRIiFASTN see below
10213
+ #define PRIoFASTN see below
10214
+ #define PRIuFASTN see below
10215
+ #define PRIxFASTN see below
10216
+ #define PRIXFASTN see below
10217
+ #define SCNdFASTN see below
10218
+ #define SCNiFASTN see below
10219
+ #define SCNoFASTN see below
10220
+ #define SCNuFASTN see below
10221
+ #define SCNxFASTN see below
10222
+ #define PRIdMAX see below
10223
+ #define PRIiMAX see below
10224
+ #define PRIoMAX see below
10225
+ #define PRIuMAX see below
10226
+ #define PRIxMAX see below
10227
+ #define PRIXMAX see below
10228
+ #define SCNdMAX see below
10229
+ #define SCNiMAX see below
10230
+ #define SCNoMAX see below
10231
+ #define SCNuMAX see below
10232
+ #define SCNxMAX see below
10233
+ #define PRIdPTR see below
10234
+ #define PRIiPTR see below
10235
+ #define PRIoPTR see below
10236
+ #define PRIuPTR see below
10237
+ #define PRIxPTR see below
10238
+ #define PRIXPTR see below
10239
+ #define SCNdPTR see below
10240
+ #define SCNiPTR see below
10241
+ #define SCNoPTR see below
10242
+ #define SCNuPTR see below
10243
+ #define SCNxPTR see below
10244
+ ```
10245
+
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
 
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
10391
+ [fs.path.itr]: #fs.path.itr
10392
+ [fs.path.member]: #fs.path.member
10393
+ [fs.path.modifiers]: #fs.path.modifiers
10394
+ [fs.path.native.obs]: #fs.path.native.obs
10395
+ [fs.path.nonmember]: #fs.path.nonmember
10396
+ [fs.path.query]: #fs.path.query
10397
+ [fs.path.req]: #fs.path.req
10398
+ [fs.path.type.cvt]: #fs.path.type.cvt
10399
+ [fs.race.behavior]: #fs.race.behavior
10400
+ [fs.rec.dir.itr.members]: #fs.rec.dir.itr.members
10401
+ [fs.rec.dir.itr.nonmembers]: #fs.rec.dir.itr.nonmembers
10402
+ [fs.req]: #fs.req
10403
+ [fs.req.namespace]: #fs.req.namespace
10404
  [fstream]: #fstream
10405
  [fstream.assign]: #fstream.assign
10406
  [fstream.cons]: #fstream.cons
10407
  [fstream.members]: #fstream.members
10408
+ [fstream.syn]: #fstream.syn
10409
  [ifstream]: #ifstream
10410
  [ifstream.assign]: #ifstream.assign
10411
  [ifstream.cons]: #ifstream.cons
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
10440
  [iostream.format]: #iostream.format
 
10441
  [iostream.forward]: #iostream.forward
10442
+ [iostream.forward.overview]: #iostream.forward.overview
10443
  [iostream.limits.imbue]: #iostream.limits.imbue
10444
  [iostream.objects]: #iostream.objects
10445
  [iostream.objects.overview]: #iostream.objects.overview
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
  [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
10496
  [quoted.manip]: #quoted.manip
10497
  [res.on.data.races]: library.md#res.on.data.races
10498
  [res.on.exception.handling]: library.md#res.on.exception.handling
10499
+ [sstream.syn]: #sstream.syn
10500
  [std.ios.manip]: #std.ios.manip
10501
  [std.manip]: #std.manip
10502
  [stream.buffers]: #stream.buffers
 
10503
  [stream.types]: #stream.types
10504
  [streambuf]: #streambuf
10505
  [streambuf.assign]: #streambuf.assign
10506
  [streambuf.buffer]: #streambuf.buffer
10507
  [streambuf.cons]: #streambuf.cons
 
10512
  [streambuf.pub.get]: #streambuf.pub.get
10513
  [streambuf.pub.pback]: #streambuf.pub.pback
10514
  [streambuf.pub.put]: #streambuf.pub.put
10515
  [streambuf.put.area]: #streambuf.put.area
10516
  [streambuf.reqts]: #streambuf.reqts
10517
+ [streambuf.syn]: #streambuf.syn
10518
  [streambuf.virt.buffer]: #streambuf.virt.buffer
10519
  [streambuf.virt.get]: #streambuf.virt.get
10520
  [streambuf.virt.locales]: #streambuf.virt.locales
10521
  [streambuf.virt.pback]: #streambuf.virt.pback
10522
  [streambuf.virt.put]: #streambuf.virt.put
10523
  [streambuf.virtuals]: #streambuf.virtuals
10524
  [string.classes]: strings.md#string.classes
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.
 
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
 
10599
  [^11]: Checking `badbit` also for `fail()` is historical practice.
10600
 
10601
  [^12]: The function signature `dec(ios_base&)` can be called by the
10602
  function signature
 
10608
  to assure that only objects for classes derived from this class may
10609
  be constructed.
10610
 
10611
  [^14]: `underflow` or `uflow` might fail by throwing an exception
10612
  prematurely. The intention is not only that the calls will not
10613
+ return `eof()` but that they will return “immediately”.
10614
 
10615
  [^15]: Classes derived from `basic_streambuf` can provide more efficient
10616
  ways to implement `xsgetn()` and `xsputn()` by overriding these
10617
  definitions from the base class.
10618
 
10619
+ [^16]: That is, for each class derived from an instance of
10620
+ `basic_streambuf` in this Clause ([[stringbuf]],
10621
+ [[filebuf]]), a specification of how consuming a character
10622
+ effects the associated output sequence is given. There is no
10623
+ requirement on a program-defined class.
10624
 
10625
+ [^17]: Typically, `overflow` returns `c` to indicate success, except
10626
+ when `traits::eq_int_type(c, traits::eof())` returns `true`, in
10627
+ which case it returns `traits::not_eof(c)`.
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`
10650
  and `unsigned char`.
10651
 
10652
+ [^26]: Note that this function is not overloaded on types `signed char`
10653
+ and `unsigned char`.
10654
+
10655
+ [^27]: Since the final input character is “extracted”, it is counted in
10656
  the `gcount()`, even though it is not stored.
10657
 
10658
+ [^28]: This allows an input line which exactly fills the buffer, without
10659
  setting `failbit`. This is different behavior than the historical
10660
  AT&T implementation.
10661
 
10662
+ [^29]: This implies an empty input line will not cause `failbit` to be
10663
  set.
10664
 
10665
+ [^30]: Note that this function is not overloaded on types `signed char`
10666
  and `unsigned char`.
10667
 
10668
+ [^31]: The call `os.tie()->flush()` does not necessarily occur if the
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`
10688
+ and `unsigned char`.
10689
+
10690
+ [^39]: The expression `cin >> resetiosflags(ios_base::skipws)` clears
10691
  `ios_base::skipws` in the format flags stored in the
10692
  `basic_istream<charT, traits>` object `cin` (the same as
10693
  `cin >> noskipws`), and the expression
10694
  `cout << resetiosflags(ios_base::showbase)` clears
10695
  `ios_base::showbase` in the format flags stored in the
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.