From Jason Turner

[input.output]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp0skc848x/{from.md → to.md} +2056 -871
tmp/tmp0skc848x/{from.md → to.md} RENAMED
@@ -12,35 +12,25 @@ formatting and manipulators, string streams, and file streams, as
12
  summarized in [[iostreams.summary]].
13
 
14
  **Table: Input/output library summary** <a id="iostreams.summary">[iostreams.summary]</a>
15
 
16
  | Subclause | | Header |
17
- | -------------------------- | --------------------------- | ------------------------------------- |
18
  | [[iostreams.requirements]] | Requirements | |
19
  | [[iostream.forward]] | Forward declarations | `<iosfwd>` |
20
  | [[iostream.objects]] | Standard iostream objects | `<iostream>` |
21
  | [[iostreams.base]] | Iostreams base classes | `<ios>` |
22
  | [[stream.buffers]] | Stream buffers | `<streambuf>` |
23
- | [[iostream.format]] | Formatting and manipulators | `<iomanip>`, `<istream>`, `<ostream>` |
24
  | [[string.streams]] | String streams | `<sstream>` |
 
25
  | [[file.streams]] | File streams | `<fstream>` |
26
  | [[syncstream]] | Synchronized output streams | `<syncstream>` |
27
  | [[filesystems]] | File systems | `<filesystem>` |
28
  | [[c.files]] | C library files | `<cstdio>`, `<cinttypes>` |
29
 
30
 
31
- [*Note 1*: Figure [[fig:iostreams.streampos]] illustrates
32
- relationships among various types described in this clause. A line from
33
- **A** to **B** indicates that **A** is an alias (e.g., a typedef) for
34
- **B** or that **A** is defined in terms of **B**.
35
-
36
- <a id="fig:iostreams.streampos"></a>
37
-
38
- ![Stream position, offset, and size types \[fig:iostreams.streampos\]](images/figstreampos.svg)
39
-
40
- — *end note*]
41
-
42
  ## Iostreams requirements <a id="iostreams.requirements">[[iostreams.requirements]]</a>
43
 
44
  ### Imbue limitations <a id="iostream.limits.imbue">[[iostream.limits.imbue]]</a>
45
 
46
  No function described in [[input.output]] except for `ios_base::imbue`
@@ -48,30 +38,54 @@ and `basic_filebuf::pubimbue` causes any instance of `basic_ios::imbue`
48
  or `basic_streambuf::imbue` to be called. If any user function called
49
  from a function declared in [[input.output]] or as an overriding virtual
50
  function of any class declared in [[input.output]] calls `imbue`, the
51
  behavior is undefined.
52
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
53
  ### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
54
 
55
  The classes of [[input.output]] with template arguments `charT` and
56
  `traits` behave as described if `traits::pos_type` and
57
  `traits::off_type` are `streampos` and `streamoff` respectively. Except
58
  as noted explicitly below, their behavior when `traits::pos_type` and
59
  `traits::off_type` are other types is *implementation-defined*.
60
 
 
 
 
 
 
61
  In the classes of [[input.output]], a template parameter with name
62
  `charT` represents a member of the set of types containing `char`,
63
  `wchar_t`, and any other *implementation-defined* character types that
64
  meet the requirements for a character on which any of the iostream
65
  components can be instantiated.
66
 
67
  ### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
68
 
69
- Concurrent access to a stream object ([[string.streams]],
70
- [[file.streams]]), stream buffer object [[stream.buffers]], or C Library
71
- stream [[c.files]] by multiple threads may result in a data race
72
- [[intro.multithread]] unless otherwise specified [[iostream.objects]].
 
73
 
74
  [*Note 1*: Data races result in undefined behavior
75
  [[intro.multithread]]. — *end note*]
76
 
77
  If one thread makes a library call *a* that writes a value to a stream
@@ -116,10 +130,19 @@ namespace std {
116
  class basic_ostringstream;
117
  template<class charT, class traits = char_traits<charT>,
118
  class Allocator = allocator<charT>>
119
  class basic_stringstream;
120
 
 
 
 
 
 
 
 
 
 
121
  template<class charT, class traits = char_traits<charT>>
122
  class basic_filebuf;
123
  template<class charT, class traits = char_traits<charT>>
124
  class basic_ifstream;
125
  template<class charT, class traits = char_traits<charT>>
@@ -150,10 +173,15 @@ namespace std {
150
  using stringbuf = basic_stringbuf<char>;
151
  using istringstream = basic_istringstream<char>;
152
  using ostringstream = basic_ostringstream<char>;
153
  using stringstream = basic_stringstream<char>;
154
 
 
 
 
 
 
155
  using filebuf = basic_filebuf<char>;
156
  using ifstream = basic_ifstream<char>;
157
  using ofstream = basic_ofstream<char>;
158
  using fstream = basic_fstream<char>;
159
 
@@ -168,10 +196,15 @@ namespace std {
168
  using wstringbuf = basic_stringbuf<wchar_t>;
169
  using wistringstream = basic_istringstream<wchar_t>;
170
  using wostringstream = basic_ostringstream<wchar_t>;
171
  using wstringstream = basic_stringstream<wchar_t>;
172
 
 
 
 
 
 
173
  using wfilebuf = basic_filebuf<wchar_t>;
174
  using wifstream = basic_ifstream<wchar_t>;
175
  using wofstream = basic_ofstream<wchar_t>;
176
  using wfstream = basic_fstream<wchar_t>;
177
 
@@ -187,11 +220,11 @@ namespace std {
187
  }
188
  ```
189
 
190
  Default template arguments are described as appearing both in `<iosfwd>`
191
  and in the synopsis of other headers but it is well-formed to include
192
- both `<iosfwd>` and one or more of the other headers.[^1]
193
 
194
  ### Overview <a id="iostream.forward.overview">[[iostream.forward.overview]]</a>
195
 
196
  The class template specialization `basic_ios<charT, traits>` serves as a
197
  virtual base class for the class templates `basic_istream`,
@@ -266,27 +299,40 @@ standard C streams provided for by the functions declared in `<cstdio>`,
266
  and includes all the headers necessary to use these objects.
267
 
268
  The objects are constructed and the associations are established at some
269
  time prior to or during the first time an object of class
270
  `ios_base::Init` is constructed, and in any case before the body of
271
- `main` [[basic.start.main]] begins execution.[^2] The objects are not
272
- destroyed during program execution.[^3] The results of including
273
- `<iostream>` in a translation unit shall be as if `<iostream>` defined
274
- an instance of `ios_base::Init` with static storage duration.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
275
 
276
  Mixing operations on corresponding wide- and narrow-character streams
277
  follows the same semantics as mixing such operations on `FILE`s, as
278
  specified in the C standard library.
279
 
280
  Concurrent access to a synchronized [[ios.members.static]] standard
281
  iostream object’s formatted and unformatted input [[istream]] and output
282
  [[ostream]] functions or a standard C stream by multiple threads does
283
  not result in a data race [[intro.multithread]].
284
 
285
- [*Note 1*: Users must still synchronize concurrent use of these objects
286
- and streams by multiple threads if they wish to avoid interleaved
287
- characters. — *end note*]
288
 
289
  See also: ISO C 7.21.2
290
 
291
  ### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
292
 
@@ -428,30 +474,14 @@ namespace std {
428
  error_condition make_error_condition(io_errc e) noexcept;
429
  const error_category& iostream_category() noexcept;
430
  }
431
  ```
432
 
433
- ### Types <a id="stream.types">[[stream.types]]</a>
434
-
435
- ``` cpp
436
- using streamoff = implementation-defined;
437
- ```
438
-
439
- The type `streamoff` is a synonym for one of the signed basic integral
440
- types of sufficient size to represent the maximum possible file size for
441
- the operating system.[^4]
442
-
443
- ``` cpp
444
- using streamsize = implementation-defined;
445
- ```
446
-
447
- The type `streamsize` is a synonym for one of the signed basic integral
448
- types. It is used to represent the number of characters transferred in
449
- an I/O operation, or the size of I/O buffers.[^5]
450
-
451
  ### Class `ios_base` <a id="ios.base">[[ios.base]]</a>
452
 
 
 
453
  ``` cpp
454
  namespace std {
455
  class ios_base {
456
  public:
457
  class failure; // see below
@@ -488,10 +518,11 @@ namespace std {
488
  using openmode = T3;
489
  static constexpr openmode app = unspecified;
490
  static constexpr openmode ate = unspecified;
491
  static constexpr openmode binary = unspecified;
492
  static constexpr openmode in = unspecified;
 
493
  static constexpr openmode out = unspecified;
494
  static constexpr openmode trunc = unspecified;
495
 
496
  // [ios.seekdir], seekdir
497
  using seekdir = T4;
@@ -701,15 +732,16 @@ The type `openmode` is a bitmask type [[bitmask.types]]. It contains the
701
  elements indicated in [[ios.openmode]].
702
 
703
  **Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
704
 
705
  | Element | Effect(s) if set |
706
- | -------- | ----------------------------------------------------------------- |
707
  | `app` | seek to end before each write |
708
  | `ate` | open and seek to end immediately after opening |
709
  | `binary` | perform input and output in binary mode (as opposed to text mode) |
710
  | `in` | open for input |
 
711
  | `out` | open for output |
712
  | `trunc` | truncate an existing stream when opening |
713
 
714
 
715
  ##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
@@ -738,10 +770,11 @@ namespace std {
738
  public:
739
  Init();
740
  Init(const Init&) = default;
741
  ~Init();
742
  Init& operator=(const Init&) = default;
 
743
  private:
744
  static int init_cnt; // exposition only
745
  };
746
  }
747
  ```
@@ -867,22 +900,22 @@ and output operations.
867
 
868
  ``` cpp
869
  static bool sync_with_stdio(bool sync = true);
870
  ```
871
 
872
- *Returns:* `true` if the previous state of the standard iostream
873
- objects [[iostream.objects]] was synchronized and otherwise returns
874
- `false`. The first time it is called, the function returns `true`.
875
-
876
  *Effects:* If any input or output operation has occurred using the
877
  standard streams prior to the call, the effect is
878
  *implementation-defined*. Otherwise, called with a `false` argument, it
879
  allows the standard streams to operate independently of the standard C
880
  streams.
881
 
882
- When a standard iostream object `str` is *synchronized* with a standard
883
- stdio stream `f`, the effect of inserting a character `c` by
 
 
 
 
884
 
885
  ``` cpp
886
  fputc(f, c);
887
  ```
888
 
@@ -916,11 +949,11 @@ is the same as the effect of
916
 
917
  ``` cpp
918
  str.rdbuf()->sputbackc(c);
919
  ```
920
 
921
- for any sequence of characters.[^6]
922
 
923
  #### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
924
 
925
  ``` cpp
926
  static int xalloc();
@@ -940,17 +973,20 @@ long& iword(int idx);
940
  *Effects:* If `iarray` is a null pointer, allocates an array of `long`
941
  of unspecified size and stores a pointer to its first element in
942
  `iarray`. The function then extends the array pointed at by `iarray` as
943
  necessary to include the element `iarray[idx]`. Each newly allocated
944
  element of the array is initialized to zero. The reference returned is
945
- invalid after any other operations on the object.[^7] However, the value
946
- of the storage referred to is retained, so that until the next call to
947
- `copyfmt`, calling `iword` with the same index yields another reference
948
- to the same value. If the function fails[^8] and `*this` is a base class
949
- subobject of a `basic_ios<>` object or subobject, the effect is
950
- equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
951
- object (which may throw `failure`).
 
 
 
952
 
953
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
954
  initialized to 0.
955
 
956
  ``` cpp
@@ -962,17 +998,19 @@ void*& pword(int idx);
962
  *Effects:* If `parray` is a null pointer, allocates an array of pointers
963
  to `void` of unspecified size and stores a pointer to its first element
964
  in `parray`. The function then extends the array pointed at by `parray`
965
  as necessary to include the element `parray[idx]`. Each newly allocated
966
  element of the array is initialized to a null pointer. The reference
967
- returned is invalid after any other operations on the object. However,
968
  the value of the storage referred to is retained, so that until the next
969
  call to `copyfmt`, calling `pword` with the same index yields another
970
- reference to the same value. If the function fails[^9] and `*this` is a
971
- base class subobject of a `basic_ios<>` object or subobject, the effect
972
- is equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
973
- object (which may throw `failure`).
 
 
974
 
975
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
976
  initialized to 0.
977
 
978
  *Remarks:* After a subsequent call to `pword(int)` for the same object,
@@ -1012,22 +1050,23 @@ destroyed, whichever comes first; otherwise the behavior is undefined.
1012
  ```
1013
 
1014
  *Effects:* Calls each registered callback pair `(fn, idx)`
1015
  [[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
1016
  that any `ios_base` member function called from within `fn` has
1017
- well-defined results.
1018
 
1019
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
1020
 
1021
  ``` cpp
1022
  namespace std {
1023
  template<class stateT> class fpos {
1024
  public:
1025
  // [fpos.members], members
1026
  stateT state() const;
1027
  void state(stateT);
1028
- private;
 
1029
  stateT st; // exposition only
1030
  };
1031
  }
1032
  ```
1033
 
@@ -1054,25 +1093,25 @@ object whose type is equal to the template parameter `stateT`. Type
1054
  [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
1055
  [[cpp17.copyassignable]]), and *Cpp17Destructible* (
1056
  [[cpp17.destructible]]) requirements. If
1057
  `is_trivially_copy_constructible_v<stateT>` is `true`, then
1058
  `fpos<stateT>` has a trivial copy constructor. If
1059
- `is_trivially_copy_assignable<stateT>` is `true`, then `fpos<stateT>`
1060
  has a trivial copy assignment operator. If
1061
  `is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
1062
  a trivial destructor. All specializations of `fpos` meet the
1063
  *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
1064
  *Cpp17CopyAssignable*, *Cpp17Destructible*, and
1065
  *Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
1066
  In addition, the expressions shown in [[fpos.operations]] are valid and
1067
  have the indicated semantics. In that table,
1068
 
1069
- - `P` refers to an instance of `fpos`,
1070
  - `p` and `q` refer to values of type `P` or `const P`,
1071
  - `pl` and `ql` refer to modifiable lvalues of type `P`,
1072
  - `O` refers to type `streamoff`, and
1073
- - `o` refers to a value of type `streamoff` or `const streamoff`.
1074
 
1075
  Stream operations that return a value of type `traits::pos_type` return
1076
  `P(O(-1))` as an invalid value to signal an error. If this value is used
1077
  as an argument to any `istream`, `ostream`, or `streambuf` member that
1078
  accepts a value of type `traits::pos_type` then the behavior of that
@@ -1136,11 +1175,10 @@ namespace std {
1136
  void init(basic_streambuf<charT, traits>* sb);
1137
  void move(basic_ios& rhs);
1138
  void move(basic_ios&& rhs);
1139
  void swap(basic_ios& rhs) noexcept;
1140
  void set_rdbuf(basic_streambuf<charT, traits>* sb);
1141
-
1142
  };
1143
  }
1144
  ```
1145
 
1146
  #### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
@@ -1276,11 +1314,11 @@ member objects of `rhs` as follows:
1276
  `(*fn)(erase_event, *this, idx)`;
1277
  - then, assigns to the member objects of `*this` the corresponding
1278
  member objects of `rhs`, except that
1279
  - `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
1280
  - the contents of arrays pointed at by `pword` and `iword` are copied,
1281
- not the pointers themselves;[^10] and
1282
  - if any newly stored pointer values in `*this` point at objects
1283
  stored outside the object `rhs` and those objects are destroyed when
1284
  `rhs` is destroyed, the newly stored pointer values are altered to
1285
  point at newly constructed copies of the objects;
1286
  - then, calls each callback pair that was copied from `rhs` as
@@ -1365,19 +1403,19 @@ iostate rdstate() const;
1365
 
1366
  ``` cpp
1367
  void clear(iostate state = goodbit);
1368
  ```
1369
 
1370
- *Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
1371
- `rdstate() == (state | ios_base::badbit)`.
1372
-
1373
  *Effects:* If
1374
  `((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
1375
  Otherwise, the function throws an object of class `ios_base::failure`
1376
  [[ios.failure]], constructed with *implementation-defined* argument
1377
  values.
1378
 
 
 
 
1379
  ``` cpp
1380
  void setstate(iostate state);
1381
  ```
1382
 
1383
  *Effects:* Calls `clear(rdstate() | state)` (which may throw
@@ -1397,11 +1435,11 @@ bool eof() const;
1397
 
1398
  ``` cpp
1399
  bool fail() const;
1400
  ```
1401
 
1402
- *Returns:* `true` if `failbit` or `badbit` is set in `rdstate()`.[^11]
1403
 
1404
  ``` cpp
1405
  bool bad() const;
1406
  ```
1407
 
@@ -1416,14 +1454,14 @@ exceptions to be thrown.
1416
 
1417
  ``` cpp
1418
  void exceptions(iostate except);
1419
  ```
1420
 
1421
- *Ensures:* `except == exceptions()`.
1422
-
1423
  *Effects:* Calls `clear(rdstate())`.
1424
 
 
 
1425
  ### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
1426
 
1427
  #### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
1428
 
1429
  Each function specified in this subclause is a designated addressable
@@ -1579,11 +1617,11 @@ function [[namespace.std]].
1579
  ios_base& dec(ios_base& str);
1580
  ```
1581
 
1582
  *Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
1583
 
1584
- *Returns:* `str`[^12].
1585
 
1586
  ``` cpp
1587
  ios_base& hex(ios_base& str);
1588
  ```
1589
 
@@ -1627,14 +1665,13 @@ ios_base& hexfloat(ios_base& str);
1627
  *Effects:* Calls
1628
  `str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
1629
 
1630
  *Returns:* `str`.
1631
 
1632
- [*Note 1*: The more obvious use of `ios_base::hex` to specify
1633
- hexadecimal floating-point format would change the meaning of existing
1634
- well-defined programs. C++03 gives no meaning to the combination of
1635
- `fixed` and `scientific`. — *end note*]
1636
 
1637
  ``` cpp
1638
  ios_base& defaultfloat(ios_base& str);
1639
  ```
1640
 
@@ -1735,10 +1772,12 @@ above:
1735
  shall have a defined value and is the next element to read (to get, or
1736
  to obtain a character value, from the sequence).
1737
 
1738
  ### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
1739
 
 
 
1740
  ``` cpp
1741
  namespace std {
1742
  template<class charT, class traits = char_traits<charT>>
1743
  class basic_streambuf {
1744
  public:
@@ -1842,15 +1881,15 @@ for deriving various *stream buffers* whose objects each control two
1842
 
1843
  ``` cpp
1844
  basic_streambuf();
1845
  ```
1846
 
1847
- *Effects:* Initializes:[^13]
1848
 
1849
  - all pointer member objects to null pointers,
1850
- - the `getloc()` member to a copy the global locale, `locale()`, at the
1851
- time of construction.
1852
 
1853
  *Remarks:* Once the `getloc()` member is initialized, results of calling
1854
  locale member functions, and of members of facets so obtained, can
1855
  safely be cached until the next time the member `imbue` is called.
1856
 
@@ -2119,11 +2158,11 @@ functions and to members of facets so obtained.
2119
  basic_streambuf* setbuf(char_type* s, streamsize n);
2120
  ```
2121
 
2122
  *Effects:* Influences stream buffering in a way that is defined
2123
  separately for each class derived from `basic_streambuf` in this
2124
- Clause ([[stringbuf.virtuals]], [[filebuf.virtuals]]).
2125
 
2126
  *Default behavior:* Does nothing. Returns `this`.
2127
 
2128
  ``` cpp
2129
  pos_type seekoff(off_type off, ios_base::seekdir way,
@@ -2131,12 +2170,12 @@ pos_type seekoff(off_type off, ios_base::seekdir way,
2131
  = ios_base::in | ios_base::out);
2132
  ```
2133
 
2134
  *Effects:* Alters the stream positions within one or more of the
2135
  controlled sequences in a way that is defined separately for each class
2136
- derived from `basic_streambuf` in this Clause ([[stringbuf.virtuals]],
2137
- [[filebuf.virtuals]]).
2138
 
2139
  *Default behavior:* Returns `pos_type(off_type(-1))`.
2140
 
2141
  ``` cpp
2142
  pos_type seekpos(pos_type sp,
@@ -2144,12 +2183,12 @@ pos_type seekpos(pos_type sp,
2144
  = ios_base::in | ios_base::out);
2145
  ```
2146
 
2147
  *Effects:* Alters the stream positions within one or more of the
2148
  controlled sequences in a way that is defined separately for each class
2149
- derived from `basic_streambuf` in this Clause ([[stringbuf]],
2150
- [[filebuf]]).
2151
 
2152
  *Default behavior:* Returns `pos_type(off_type(-1))`.
2153
 
2154
  ``` cpp
2155
  int sync();
@@ -2166,14 +2205,15 @@ each derived class [[filebuf.virtuals]].
2166
  *Default behavior:* Returns zero.
2167
 
2168
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
2169
 
2170
  ``` cpp
2171
- streamsize showmanyc();\footnote{The morphemes of showmanyc\
2172
- are ``es-how-many-see'', not ``show-manic''.}
2173
  ```
2174
 
 
 
2175
  *Returns:* An estimate of the number of characters available in the
2176
  sequence, or -1. If it returns a positive value, then successive calls
2177
  to `underflow()` will not return `traits::eof()` until at least that
2178
  number of characters have been extracted from the stream. If
2179
  `showmanyc()` returns -1, then calls to `underflow()` or `uflow()` will
@@ -2199,18 +2239,10 @@ to `sbumpc()` would return `traits::eof()`.
2199
 
2200
  ``` cpp
2201
  int_type underflow();
2202
  ```
2203
 
2204
- *Remarks:* The public members of `basic_streambuf` call this virtual
2205
- function only if `gptr()` is null or `gptr() >= egptr()`.
2206
-
2207
- *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
2208
- of the *pending sequence*, without moving the input sequence position
2209
- past it. If the pending sequence is null then the function returns
2210
- `traits::eof()` to indicate failure.
2211
-
2212
  The *pending sequence* of characters is defined as the concatenation of
2213
 
2214
  - the empty sequence if `gptr()` is null, otherwise the characters in
2215
  \[`gptr()`, `egptr()`), followed by
2216
  - some (possibly empty) sequence of characters read from the input
@@ -2236,12 +2268,20 @@ that either
2236
  in which case the characters in \[`eback()`, `gptr()`) agree with the
2237
  last `gptr() - eback()` characters of the backup sequence, or
2238
  - the characters in \[`gptr() - n`, `gptr()`) agree with the backup
2239
  sequence (where `n` is the length of the backup sequence).
2240
 
 
 
 
 
 
2241
  *Default behavior:* Returns `traits::eof()`.
2242
 
 
 
 
2243
  ``` cpp
2244
  int_type uflow();
2245
  ```
2246
 
2247
  *Preconditions:* The constraints are the same as for `underflow()`,
@@ -2249,26 +2289,21 @@ except that the result character is transferred from the pending
2249
  sequence to the backup sequence, and the pending sequence is not empty
2250
  before the transfer.
2251
 
2252
  *Default behavior:* Calls `underflow()`. If `underflow()` returns
2253
  `traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
2254
- of `traits::to_int_type(*gptr())` and increment the value of the next
2255
  pointer for the input sequence.
2256
 
2257
  *Returns:* `traits::eof()` to indicate failure.
2258
 
2259
  ##### Putback <a id="streambuf.virt.pback">[[streambuf.virt.pback]]</a>
2260
 
2261
  ``` cpp
2262
  int_type pbackfail(int_type c = traits::eof());
2263
  ```
2264
 
2265
- *Remarks:* The public functions of `basic_streambuf` call this virtual
2266
- function only when `gptr()` is null, `gptr() == eback()`, or
2267
- `traits::eq(traits::to_char_type(c), gptr()[-1])` returns `false`. Other
2268
- calls shall also satisfy that constraint.
2269
-
2270
  The *pending sequence* is defined as for `underflow()`, with the
2271
  modifications that
2272
 
2273
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
2274
  input sequence is backed up one character before the pending sequence
@@ -2280,17 +2315,22 @@ modifications that
2280
  *Ensures:* On return, the constraints of `gptr()`, `eback()`, and
2281
  `pptr()` are the same as for `underflow()`.
2282
 
2283
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
2284
  because the input sequence could not be backed up, or if for some other
2285
- reason the pointers could not be set consistent with the constraints.
2286
  `pbackfail()` is called only when put back has really failed.
2287
 
2288
  Returns some value other than `traits::eof()` to indicate success.
2289
 
2290
  *Default behavior:* Returns `traits::eof()`.
2291
 
 
 
 
 
 
2292
  ##### Put area <a id="streambuf.virt.put">[[streambuf.virt.put]]</a>
2293
 
2294
  ``` cpp
2295
  streamsize xsputn(const char_type* s, streamsize n);
2296
  ```
@@ -2316,14 +2356,10 @@ of
2316
  - the empty sequence if `pbase()` is null, otherwise the
2317
  `pptr() - pbase()` characters beginning at `pbase()`, followed by
2318
  - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
2319
  `true`, otherwise the sequence consisting of `c`.
2320
 
2321
- *Remarks:* The member functions `sputc()` and `sputn()` call this
2322
- function in case that no room can be found in the put buffer enough to
2323
- accommodate the argument character sequence.
2324
-
2325
  *Preconditions:* Every overriding definition of this virtual function
2326
  obeys the following constraints:
2327
 
2328
  - The effect of consuming a character on the associated output sequence
2329
  is specified.[^16]
@@ -2343,10 +2379,14 @@ obeys the following constraints:
2343
  Otherwise, returns some value other than `traits::eof()` to indicate
2344
  success.[^17]
2345
 
2346
  *Default behavior:* Returns `traits::eof()`.
2347
 
 
 
 
 
2348
  ## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
2349
 
2350
  ### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
2351
 
2352
  ``` cpp
@@ -2364,12 +2404,12 @@ namespace std {
2364
  using wiostream = basic_iostream<wchar_t>;
2365
 
2366
  template<class charT, class traits>
2367
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
2368
 
2369
- template<class charT, class traits, class T>
2370
- basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);
2371
  }
2372
  ```
2373
 
2374
  ### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
2375
 
@@ -2393,56 +2433,96 @@ namespace std {
2393
  template<class charT, class traits>
2394
  basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
2395
  template<class charT, class traits>
2396
  basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
2397
 
2398
- template<class charT, class traits, class T>
2399
- basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
 
 
 
 
 
 
 
 
 
2400
  }
2401
  ```
2402
 
2403
  ### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
2404
 
2405
  ``` cpp
2406
  namespace std {
2407
- // types T1, T2, ... are unspecified implementation types
2408
- T1 resetiosflags(ios_base::fmtflags mask);
2409
- T2 setiosflags (ios_base::fmtflags mask);
2410
- T3 setbase(int base);
2411
- template<class charT> T4 setfill(charT c);
2412
- T5 setprecision(int n);
2413
- T6 setw(int n);
2414
- template<class moneyT> T7 get_money(moneyT& mon, bool intl = false);
2415
- template<class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
2416
- template<class charT> T9 get_time(struct tm* tmb, const charT* fmt);
2417
- template<class charT> T10 put_time(const struct tm* tmb, const charT* fmt);
2418
 
2419
  template<class charT>
2420
- T11 quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
2421
 
2422
  template<class charT, class traits, class Allocator>
2423
- T12 quoted(const basic_string<charT, traits, Allocator>& s,
2424
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2425
 
2426
  template<class charT, class traits, class Allocator>
2427
- T13 quoted(basic_string<charT, traits, Allocator>& s,
2428
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2429
 
2430
  template<class charT, class traits>
2431
- T14 quoted(basic_string_view<charT, traits> s,
2432
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2433
  }
2434
  ```
2435
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2436
  ### Input streams <a id="input.streams">[[input.streams]]</a>
2437
 
2438
- The header `<istream>` defines two types and a function signature that
2439
- control input from a stream buffer along with a function template that
2440
- extracts from stream rvalues.
 
 
2441
 
2442
  #### Class template `basic_istream` <a id="istream">[[istream]]</a>
2443
 
 
 
 
 
 
 
 
2444
  ``` cpp
2445
  namespace std {
2446
  template<class charT, class traits = char_traits<charT>>
2447
  class basic_istream : virtual public basic_ios<charT, traits> {
2448
  public:
@@ -2459,64 +2539,62 @@ namespace std {
2459
 
2460
  // [istream.sentry], prefix/suffix
2461
  class sentry;
2462
 
2463
  // [istream.formatted], formatted input
2464
- basic_istream<charT, traits>&
2465
- operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
2466
- basic_istream<charT, traits>&
2467
- operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
2468
- basic_istream<charT, traits>&
2469
- operator>>(ios_base& (*pf)(ios_base&));
2470
 
2471
- basic_istream<charT, traits>& operator>>(bool& n);
2472
- basic_istream<charT, traits>& operator>>(short& n);
2473
- basic_istream<charT, traits>& operator>>(unsigned short& n);
2474
- basic_istream<charT, traits>& operator>>(int& n);
2475
- basic_istream<charT, traits>& operator>>(unsigned int& n);
2476
- basic_istream<charT, traits>& operator>>(long& n);
2477
- basic_istream<charT, traits>& operator>>(unsigned long& n);
2478
- basic_istream<charT, traits>& operator>>(long long& n);
2479
- basic_istream<charT, traits>& operator>>(unsigned long long& n);
2480
- basic_istream<charT, traits>& operator>>(float& f);
2481
- basic_istream<charT, traits>& operator>>(double& f);
2482
- basic_istream<charT, traits>& operator>>(long double& f);
 
2483
 
2484
- basic_istream<charT, traits>& operator>>(void*& p);
2485
- basic_istream<charT, traits>& operator>>(basic_streambuf<char_type, traits>* sb);
2486
 
2487
  // [istream.unformatted], unformatted input
2488
  streamsize gcount() const;
2489
  int_type get();
2490
- basic_istream<charT, traits>& get(char_type& c);
2491
- basic_istream<charT, traits>& get(char_type* s, streamsize n);
2492
- basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
2493
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
2494
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
2495
 
2496
- basic_istream<charT, traits>& getline(char_type* s, streamsize n);
2497
- basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
2498
 
2499
- basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
2500
  int_type peek();
2501
- basic_istream<charT, traits>& read (char_type* s, streamsize n);
2502
  streamsize readsome(char_type* s, streamsize n);
2503
 
2504
- basic_istream<charT, traits>& putback(char_type c);
2505
- basic_istream<charT, traits>& unget();
2506
  int sync();
2507
 
2508
  pos_type tellg();
2509
- basic_istream<charT, traits>& seekg(pos_type);
2510
- basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
2511
 
2512
  protected:
2513
  // [istream.cons], copy/move constructor
2514
  basic_istream(const basic_istream&) = delete;
2515
  basic_istream(basic_istream&& rhs);
2516
 
2517
- // [istream.assign], assign and swap
2518
  basic_istream& operator=(const basic_istream&) = delete;
2519
  basic_istream& operator=(basic_istream&& rhs);
2520
  void swap(basic_istream& rhs);
2521
  };
2522
 
@@ -2545,22 +2623,10 @@ Two groups of member function signatures share common properties: the
2545
  *formatted input functions* (or *extractors*) and the *unformatted input
2546
  functions.* Both groups of input functions are described as if they
2547
  obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
2548
  or `rdbuf()->sgetc()`. They may use other public members of `istream`.
2549
 
2550
- If `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`,
2551
- then the input function, except as explicitly noted otherwise, completes
2552
- its actions and does `setstate(eofbit)`, which may throw
2553
- `ios_base::failure` [[iostate.flags]], before returning.
2554
-
2555
- If one of these called functions throws an exception, then unless
2556
- explicitly noted otherwise, the input function sets `badbit` in the
2557
- error state. If `badbit` is set in `exceptions()`, the input function
2558
- rethrows the exception without completing its actions, otherwise it does
2559
- not throw anything and proceeds as if the called function had returned a
2560
- failure indication.
2561
-
2562
  ##### Constructors <a id="istream.cons">[[istream.cons]]</a>
2563
 
2564
  ``` cpp
2565
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2566
  ```
@@ -2603,15 +2669,16 @@ values returned by `gcount()` and `rhs.gcount()`.
2603
 
2604
  ##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
2605
 
2606
  ``` cpp
2607
  namespace std {
2608
- template<class charT, class traits = char_traits<charT>>
2609
  class basic_istream<charT, traits>::sentry {
2610
  bool ok_; // exposition only
 
2611
  public:
2612
- explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
2613
  ~sentry();
2614
  explicit operator bool() const { return ok_; }
2615
  sentry(const sentry&) = delete;
2616
  sentry& operator=(const sentry&) = delete;
2617
  };
@@ -2620,32 +2687,34 @@ namespace std {
2620
 
2621
  The class `sentry` defines a class that is responsible for doing
2622
  exception safe prefix and suffix operations.
2623
 
2624
  ``` cpp
2625
- explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
2626
  ```
2627
 
2628
  *Effects:* If `is.good()` is `false`, calls `is.setstate(failbit)`.
2629
  Otherwise, prepares for formatted or unformatted input. First, if
2630
  `is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
2631
  to synchronize the output sequence with any associated external C
2632
  stream. Except that this call can be suppressed if the put area of
2633
  `is.tie()` is empty. Further an implementation is allowed to defer the
2634
  call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
2635
  such call occurs before the `sentry` object is destroyed, the call to
2636
- `flush` may be eliminated entirely.[^18] If `noskipws` is zero and
2637
- `is.flags() & ios_base::skipws` is nonzero, the function extracts and
2638
- discards each character as long as the next available input character
2639
- `c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
2640
- `is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
2641
- `setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
 
 
2642
 
2643
  *Remarks:* The constructor
2644
 
2645
  ``` cpp
2646
- explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false)
2647
  ```
2648
 
2649
  uses the currently imbued locale in `is`, to determine whether the next
2650
  input character is whitespace or not.
2651
 
@@ -2678,47 +2747,56 @@ explicit operator bool() const;
2678
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2679
 
2680
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
2681
 
2682
  Each formatted input function begins execution by constructing an object
2683
- of class `sentry` with the `noskipws` (second) argument `false`. If the
 
 
2684
  `sentry` object returns `true`, when converted to a value of type
2685
- `bool`, the function endeavors to obtain the requested input. If an
2686
- exception is thrown during input then `ios_base::badbit` is turned
2687
- on[^20] in `*this`’s error state. If `(exceptions()&badbit) != 0` then
2688
- the exception is rethrown. In any case, the formatted input function
2689
- destroys the `sentry` object. If no exception has been thrown, it
2690
- returns `*this`.
 
 
 
 
 
 
 
 
2691
 
2692
  ##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
2693
 
2694
  ``` cpp
2695
- operator>>(unsigned short& val);
2696
- operator>>(unsigned int& val);
2697
- operator>>(long& val);
2698
- operator>>(unsigned long& val);
2699
- operator>>(long long& val);
2700
- operator>>(unsigned long long& val);
2701
- operator>>(float& val);
2702
- operator>>(double& val);
2703
- operator>>(long double& val);
2704
- operator>>(bool& val);
2705
- operator>>(void*& val);
2706
  ```
2707
 
2708
  As in the case of the inserters, these extractors depend on the locale’s
2709
  `num_get<>` [[locale.num.get]] object to perform parsing the input
2710
  stream data. These extractors behave as formatted input functions (as
2711
- described in  [[istream.formatted.reqmts]]). After a sentry object is
2712
  constructed, the conversion occurs as if performed by the following code
2713
- fragment:
 
2714
 
2715
  ``` cpp
2716
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2717
- iostate err = iostate::goodbit;
2718
- use_facet<numget>(loc).get(*this, 0, *this, err, val);
2719
- setstate(err);
2720
  ```
2721
 
2722
  In the above fragment, `loc` stands for the private member of the
2723
  `basic_ios` class.
2724
 
@@ -2729,85 +2807,123 @@ directly. — *end note*]
2729
 
2730
  Class `locale` relies on this type as its interface to `istream`, so
2731
  that it does not need to depend directly on `istream`.
2732
 
2733
  ``` cpp
2734
- operator>>(short& val);
2735
  ```
2736
 
2737
  The conversion occurs as if performed by the following code fragment
2738
  (using the same notation as for the preceding code fragment):
2739
 
2740
  ``` cpp
2741
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2742
- iostate err = ios_base::goodbit;
2743
  long lval;
2744
- use_facet<numget>(loc).get(*this, 0, *this, err, lval);
2745
  if (lval < numeric_limits<short>::min()) {
2746
- err |= ios_base::failbit;
2747
  val = numeric_limits<short>::min();
2748
  } else if (numeric_limits<short>::max() < lval) {
2749
- err |= ios_base::failbit;
2750
  val = numeric_limits<short>::max();
2751
  } else
2752
  val = static_cast<short>(lval);
2753
- setstate(err);
2754
  ```
2755
 
2756
  ``` cpp
2757
- operator>>(int& val);
2758
  ```
2759
 
2760
  The conversion occurs as if performed by the following code fragment
2761
  (using the same notation as for the preceding code fragment):
2762
 
2763
  ``` cpp
2764
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2765
- iostate err = ios_base::goodbit;
2766
  long lval;
2767
- use_facet<numget>(loc).get(*this, 0, *this, err, lval);
2768
  if (lval < numeric_limits<int>::min()) {
2769
- err |= ios_base::failbit;
2770
  val = numeric_limits<int>::min();
2771
  } else if (numeric_limits<int>::max() < lval) {
2772
- err |= ios_base::failbit;
2773
  val = numeric_limits<int>::max();
2774
  } else
2775
  val = static_cast<int>(lval);
2776
- setstate(err);
2777
  ```
2778
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2779
  ##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
2780
 
2781
  ``` cpp
2782
- basic_istream<charT, traits>&
2783
- operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
2784
  ```
2785
 
2786
  *Effects:* None. This extractor does not behave as a formatted input
2787
  function (as described in  [[istream.formatted.reqmts]]).
2788
 
2789
- *Returns:* `pf(*this)`.[^21]
2790
 
2791
  ``` cpp
2792
- basic_istream<charT, traits>&
2793
- operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
2794
  ```
2795
 
2796
  *Effects:* Calls `pf(*this)`. This extractor does not behave as a
2797
  formatted input function (as described
2798
  in  [[istream.formatted.reqmts]]).
2799
 
2800
  *Returns:* `*this`.
2801
 
2802
  ``` cpp
2803
- basic_istream<charT, traits>& operator>>(ios_base& (*pf)(ios_base&));
2804
  ```
2805
 
2806
- *Effects:* Calls `pf(*this)`.[^22] This extractor does not behave as a
2807
- formatted input function (as described
2808
- in  [[istream.formatted.reqmts]]).
 
2809
 
2810
  *Returns:* `*this`.
2811
 
2812
  ``` cpp
2813
  template<class charT, class traits, size_t N>
@@ -2833,12 +2949,12 @@ Characters are extracted and stored until any of the following occurs:
2833
 
2834
  `operator>>` then stores a null byte (`charT()`) in the next position,
2835
  which may be the first position if no characters were extracted.
2836
  `operator>>` then calls `width(0)`.
2837
 
2838
- If the function extracted no characters, it calls `setstate(failbit)`,
2839
- which may throw `ios_base::failure` [[iostate.flags]].
2840
 
2841
  *Returns:* `in`.
2842
 
2843
  ``` cpp
2844
  template<class charT, class traits>
@@ -2848,132 +2964,138 @@ template<class traits>
2848
  template<class traits>
2849
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
2850
  ```
2851
 
2852
  *Effects:* Behaves like a formatted input member (as described
2853
- in  [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
2854
- constructed a character is extracted from `in`, if one is available, and
2855
- stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
 
2856
 
2857
  *Returns:* `in`.
2858
 
2859
  ``` cpp
2860
- basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
2861
  ```
2862
 
2863
  *Effects:* Behaves as an unformatted input
2864
  function [[istream.unformatted]]. If `sb` is null, calls
2865
  `setstate(failbit)`, which may throw `ios_base::failure`
2866
- [[iostate.flags]]. After a sentry object is constructed, extracts
2867
  characters from `*this` and inserts them in the output sequence
2868
  controlled by `sb`. Characters are extracted and inserted until any of
2869
  the following occurs:
2870
 
2871
  - end-of-file occurs on the input sequence;
2872
  - inserting in the output sequence fails (in which case the character to
2873
  be inserted is not extracted);
2874
  - an exception occurs (in which case the exception is caught).
2875
 
2876
- If the function inserts no characters, it calls `setstate(failbit)`,
2877
- which may throw `ios_base::failure` [[iostate.flags]]. If it inserted no
2878
- characters because it caught an exception thrown while extracting
2879
- characters from `*this` and `failbit` is set in `exceptions()`
2880
- [[iostate.flags]], then the caught exception is rethrown.
2881
 
2882
  *Returns:* `*this`.
2883
 
2884
  #### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
2885
 
2886
  Each unformatted input function begins execution by constructing an
2887
- object of class `sentry` with the default argument `noskipws` (second)
2888
- argument `true`. If the `sentry` object returns `true`, when converted
2889
- to a value of type `bool`, the function endeavors to obtain the
2890
- requested input. Otherwise, if the sentry constructor exits by throwing
2891
- an exception or if the sentry object returns `false`, when converted to
2892
- a value of type `bool`, the function returns without attempting to
2893
- obtain any input. In either case the number of extracted characters is
2894
- set to 0; unformatted input functions taking a character array of
2895
- nonzero size as an argument shall also store a null character (using
2896
- `charT()`) in the first location of the array. If an exception is thrown
2897
- during input then `ios_base::badbit` is turned on[^23] in `*this`’s
2898
- error state. (Exceptions thrown from `basic_ios<>::clear()` are not
2899
- caught or rethrown.) If `(exceptions()&badbit) != 0` then the exception
2900
- is rethrown. It also counts the number of characters extracted. If no
2901
- exception has been thrown it ends by storing the count in a member
2902
- object and returning the value specified. In any event the `sentry`
2903
- object is destroyed before leaving the unformatted input function.
 
 
 
 
 
 
2904
 
2905
  ``` cpp
2906
  streamsize gcount() const;
2907
  ```
2908
 
2909
  *Effects:* None. This member function does not behave as an unformatted
2910
  input function (as described above).
2911
 
2912
  *Returns:* The number of characters extracted by the last unformatted
2913
- input member function called for the object.
 
2914
 
2915
  ``` cpp
2916
  int_type get();
2917
  ```
2918
 
2919
  *Effects:* Behaves as an unformatted input function (as described
2920
- above). After constructing a sentry object, extracts a character `c`, if
2921
- one is available. Otherwise, the function calls `setstate(failbit)`,
2922
- which may throw `ios_base::failure` [[iostate.flags]].
2923
 
2924
  *Returns:* `c` if available, otherwise `traits::eof()`.
2925
 
2926
  ``` cpp
2927
- basic_istream<charT, traits>& get(char_type& c);
2928
  ```
2929
 
2930
  *Effects:* Behaves as an unformatted input function (as described
2931
- above). After constructing a sentry object, extracts a character, if one
2932
- is available, and assigns it to `c`.[^24] Otherwise, the function calls
2933
- `setstate(failbit)` (which may throw `ios_base::failure`
2934
- [[iostate.flags]]).
 
2935
 
2936
  *Returns:* `*this`.
2937
 
2938
  ``` cpp
2939
- basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
2940
  ```
2941
 
2942
  *Effects:* Behaves as an unformatted input function (as described
2943
- above). After constructing a sentry object, extracts characters and
2944
  stores them into successive locations of an array whose first element is
2945
- designated by `s`.[^25] Characters are extracted and stored until any of
2946
- the following occurs:
 
2947
 
2948
  - `n` is less than one or `n - 1` characters are stored;
2949
- - end-of-file occurs on the input sequence (in which case the function
2950
- calls `setstate(eofbit)`);
2951
  - `traits::eq(c, delim)` for the next available input character `c` (in
2952
  which case `c` is not extracted).
2953
 
2954
- If the function stores no characters, it calls `setstate(failbit)`
2955
- (which may throw `ios_base::failure` [[iostate.flags]]). In any case, if
2956
- `n` is greater than zero it then stores a null character into the next
2957
- successive location of the array.
2958
 
2959
  *Returns:* `*this`.
2960
 
2961
  ``` cpp
2962
- basic_istream<charT, traits>& get(char_type* s, streamsize n);
2963
  ```
2964
 
2965
  *Effects:* Calls `get(s, n, widen(’\n’))`.
2966
 
2967
  *Returns:* Value returned by the call.
2968
 
2969
  ``` cpp
2970
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
2971
  ```
2972
 
2973
  *Effects:* Behaves as an unformatted input function (as described
2974
- above). After constructing a sentry object, extracts characters and
2975
  inserts them in the output sequence controlled by `sb`. Characters are
2976
  extracted and inserted until any of the following occurs:
2977
 
2978
  - end-of-file occurs on the input sequence;
2979
  - inserting in the output sequence fails (in which case the character to
@@ -2981,45 +3103,45 @@ extracted and inserted until any of the following occurs:
2981
  - `traits::eq(c, delim)` for the next available input character `c` (in
2982
  which case `c` is not extracted);
2983
  - an exception occurs (in which case, the exception is caught but not
2984
  rethrown).
2985
 
2986
- If the function inserts no characters, it calls `setstate(failbit)`,
2987
- which may throw `ios_base::failure` [[iostate.flags]].
2988
 
2989
  *Returns:* `*this`.
2990
 
2991
  ``` cpp
2992
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
2993
  ```
2994
 
2995
  *Effects:* Calls `get(sb, widen(’\n’))`.
2996
 
2997
  *Returns:* Value returned by the call.
2998
 
2999
  ``` cpp
3000
- basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
3001
  ```
3002
 
3003
  *Effects:* Behaves as an unformatted input function (as described
3004
- above). After constructing a sentry object, extracts characters and
3005
  stores them into successive locations of an array whose first element is
3006
- designated by `s`.[^26] Characters are extracted and stored until one of
3007
- the following occurs:
3008
 
3009
- 1. end-of-file occurs on the input sequence (in which case the function
3010
- calls `setstate(eofbit)`);
 
3011
  2. `traits::eq(c, delim)` for the next available input character `c`
3012
  (in which case the input character is extracted but not
3013
- stored);[^27]
3014
  3. `n` is less than one or `n - 1` characters are stored (in which case
3015
  the function calls `setstate(failbit)`).
3016
 
3017
- These conditions are tested in the order shown.[^28]
3018
 
3019
- If the function extracts no characters, it calls `setstate(failbit)`
3020
- (which may throw `ios_base::failure` [[iostate.flags]]).[^29]
3021
 
3022
  In any case, if `n` is greater than zero, it then stores a null
3023
  character (using `charT()`) into the next successive location of the
3024
  array.
3025
 
@@ -3053,21 +3175,21 @@ int main() {
3053
  ```
3054
 
3055
  — *end example*]
3056
 
3057
  ``` cpp
3058
- basic_istream<charT, traits>& getline(char_type* s, streamsize n);
3059
  ```
3060
 
3061
  *Returns:* `getline(s, n, widen(’\n’))`
3062
 
3063
  ``` cpp
3064
- basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
3065
  ```
3066
 
3067
  *Effects:* Behaves as an unformatted input function (as described
3068
- above). After constructing a sentry object, extracts characters and
3069
  discards them. Characters are extracted until any of the following
3070
  occurs:
3071
 
3072
  - `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
3073
  characters have been extracted so far
@@ -3075,36 +3197,38 @@ occurs:
3075
  calls `setstate(eofbit)`, which may throw `ios_base::failure`
3076
  [[iostate.flags]]);
3077
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
3078
  available input character `c` (in which case `c` is extracted).
3079
 
3080
- *Remarks:* The last condition will never occur if
3081
- `traits::eq_int_type(delim, traits::eof())`.
3082
 
3083
  *Returns:* `*this`.
3084
 
3085
  ``` cpp
3086
  int_type peek();
3087
  ```
3088
 
3089
  *Effects:* Behaves as an unformatted input function (as described
3090
- above). After constructing a sentry object, reads but does not extract
3091
  the current input character.
3092
 
3093
  *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
3094
  `rdbuf()->sgetc()`.
3095
 
3096
  ``` cpp
3097
- basic_istream<charT, traits>& read(char_type* s, streamsize n);
3098
  ```
3099
 
3100
  *Effects:* Behaves as an unformatted input function (as described
3101
- above). After constructing a sentry object, if `!good()` calls
3102
  `setstate(failbit)` which may throw an exception, and return. Otherwise
3103
  extracts characters and stores them into successive locations of an
3104
- array whose first element is designated by `s`.[^30] Characters are
3105
- extracted and stored until either of the following occurs:
 
 
3106
 
3107
  - `n` characters are stored;
3108
  - end-of-file occurs on the input sequence (in which case the function
3109
  calls `setstate(failbit | eofbit)`, which may throw
3110
  `ios_base::failure` [[iostate.flags]]).
@@ -3114,11 +3238,11 @@ extracted and stored until either of the following occurs:
3114
  ``` cpp
3115
  streamsize readsome(char_type* s, streamsize n);
3116
  ```
3117
 
3118
  *Effects:* Behaves as an unformatted input function (as described
3119
- above). After constructing a sentry object, if `!good()` calls
3120
  `setstate(failbit)` which may throw an exception, and return. Otherwise
3121
  extracts characters and stores them into successive locations of an
3122
  array whose first element is designated by `s`. If
3123
  `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
3124
  `ios_base::failure` [[iostate.flags]]), and extracts no characters;
@@ -3127,51 +3251,51 @@ array whose first element is designated by `s`. If
3127
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
3128
 
3129
  *Returns:* The number of characters extracted.
3130
 
3131
  ``` cpp
3132
- basic_istream<charT, traits>& putback(char_type c);
3133
  ```
3134
 
3135
  *Effects:* Behaves as an unformatted input function (as described
3136
  above), except that the function first clears `eofbit`. After
3137
- constructing a sentry object, if `!good()` calls `setstate(failbit)`
3138
  which may throw an exception, and return. If `rdbuf()` is not null,
3139
  calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
3140
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3141
  `ios_base::failure` [[iostate.flags]]).
3142
 
3143
- [*Note 1*: This function extracts no characters, so the value returned
3144
- by the next call to `gcount()` is 0. — *end note*]
3145
-
3146
- *Returns:* `*this`.
3147
-
3148
- ``` cpp
3149
- basic_istream<charT, traits>& unget();
3150
- ```
3151
-
3152
- *Effects:* Behaves as an unformatted input function (as described
3153
- above), except that the function first clears `eofbit`. After
3154
- constructing a sentry object, if `!good()` calls `setstate(failbit)`
3155
- which may throw an exception, and return. If `rdbuf()` is not null,
3156
- calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
3157
- returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3158
- `ios_base::failure` [[iostate.flags]]).
3159
-
3160
  [*Note 2*: This function extracts no characters, so the value returned
3161
  by the next call to `gcount()` is 0. — *end note*]
3162
 
3163
  *Returns:* `*this`.
3164
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3165
  ``` cpp
3166
  int sync();
3167
  ```
3168
 
3169
  *Effects:* Behaves as an unformatted input function (as described
3170
  above), except that it does not count the number of characters extracted
3171
  and does not affect the value returned by subsequent calls to
3172
- `gcount()`. After constructing a sentry object, if `rdbuf()` is a null
3173
  pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
3174
  that function returns `-1` calls `setstate(badbit)` (which may throw
3175
  `ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
3176
  returns zero.
3177
 
@@ -3182,38 +3306,38 @@ pos_type tellg();
3182
  *Effects:* Behaves as an unformatted input function (as described
3183
  above), except that it does not count the number of characters extracted
3184
  and does not affect the value returned by subsequent calls to
3185
  `gcount()`.
3186
 
3187
- *Returns:* After constructing a sentry object, if `fail() != false`,
3188
  returns `pos_type(-1)` to indicate failure. Otherwise, returns
3189
  `rdbuf()->pubseekoff(0, cur, in)`.
3190
 
3191
  ``` cpp
3192
- basic_istream<charT, traits>& seekg(pos_type pos);
3193
  ```
3194
 
3195
  *Effects:* Behaves as an unformatted input function (as described
3196
  above), except that the function first clears `eofbit`, it does not
3197
  count the number of characters extracted, and it does not affect the
3198
  value returned by subsequent calls to `gcount()`. After constructing a
3199
- sentry object, if `fail() != true`, executes
3200
  `rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
3201
  function calls `setstate(failbit)` (which may throw
3202
  `ios_base::failure`).
3203
 
3204
  *Returns:* `*this`.
3205
 
3206
  ``` cpp
3207
- basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
3208
  ```
3209
 
3210
  *Effects:* Behaves as an unformatted input function (as described
3211
  above), except that the function first clears `eofbit`, does not count
3212
  the number of characters extracted, and does not affect the value
3213
- returned by subsequent calls to `gcount()`. After constructing a sentry
3214
- object, if `fail() != true`, executes
3215
  `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
3216
  function calls `setstate(failbit)` (which may throw
3217
  `ios_base::failure`).
3218
 
3219
  *Returns:* `*this`.
@@ -3229,11 +3353,11 @@ template<class charT, class traits>
3229
  ```
3230
 
3231
  *Effects:* Behaves as an unformatted input
3232
  function [[istream.unformatted]], except that it does not count the
3233
  number of characters extracted and does not affect the value returned by
3234
- subsequent calls to `is.gcount()`. After constructing a sentry object
3235
  extracts characters as long as the next available character `c` is
3236
  whitespace or until there are no more characters in the sequence.
3237
  Whitespace characters are distinguished with the same criterion as used
3238
  by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
3239
  characters because there are no more available it sets `eofbit`, but not
@@ -3247,22 +3371,24 @@ characters because there are no more available it sets `eofbit`, but not
3247
  template<class Istream, class T>
3248
  Istream&& operator>>(Istream&& is, T&& x);
3249
  ```
3250
 
3251
  *Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
3252
- when treated as an unevaluated operand and `Istream` is publicly and
3253
- unambiguously derived from `ios_base`.
3254
 
3255
  *Effects:* Equivalent to:
3256
 
3257
  ``` cpp
3258
  is >> std::forward<T>(x);
3259
  return std::move(is);
3260
  ```
3261
 
3262
  #### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
3263
 
 
 
3264
  ``` cpp
3265
  namespace std {
3266
  template<class charT, class traits = char_traits<charT>>
3267
  class basic_iostream
3268
  : public basic_istream<charT, traits>,
@@ -3283,11 +3409,11 @@ namespace std {
3283
  protected:
3284
  // [iostream.cons], constructor
3285
  basic_iostream(const basic_iostream&) = delete;
3286
  basic_iostream(basic_iostream&& rhs);
3287
 
3288
- // [iostream.assign], assign and swap
3289
  basic_iostream& operator=(const basic_iostream&) = delete;
3290
  basic_iostream& operator=(basic_iostream&& rhs);
3291
  void swap(basic_iostream& rhs);
3292
  };
3293
  }
@@ -3312,11 +3438,11 @@ explicit basic_iostream(basic_streambuf<charT, traits>* sb);
3312
  ``` cpp
3313
  basic_iostream(basic_iostream&& rhs);
3314
  ```
3315
 
3316
  *Effects:* Move constructs from the rvalue `rhs` by constructing the
3317
- `basic_istream` base class with `move(rhs)`.
3318
 
3319
  ##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
3320
 
3321
  ``` cpp
3322
  virtual ~basic_iostream();
@@ -3338,16 +3464,24 @@ void swap(basic_iostream& rhs);
3338
 
3339
  *Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
3340
 
3341
  ### Output streams <a id="output.streams">[[output.streams]]</a>
3342
 
3343
- The header `<ostream>` defines a type and several function signatures
3344
- that control output to a stream buffer along with a function template
3345
- that inserts into stream rvalues.
 
 
3346
 
3347
  #### Class template `basic_ostream` <a id="ostream">[[ostream]]</a>
3348
 
 
 
 
 
 
 
3349
  ``` cpp
3350
  namespace std {
3351
  template<class charT, class traits = char_traits<charT>>
3352
  class basic_ostream : virtual public basic_ios<charT, traits> {
3353
  public:
@@ -3364,51 +3498,50 @@ namespace std {
3364
 
3365
  // [ostream.sentry], prefix/suffix
3366
  class sentry;
3367
 
3368
  // [ostream.formatted], formatted output
3369
- basic_ostream<charT, traits>&
3370
- operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
3371
- basic_ostream<charT, traits>&
3372
- operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
3373
- basic_ostream<charT, traits>&
3374
- operator<<(ios_base& (*pf)(ios_base&));
3375
 
3376
- basic_ostream<charT, traits>& operator<<(bool n);
3377
- basic_ostream<charT, traits>& operator<<(short n);
3378
- basic_ostream<charT, traits>& operator<<(unsigned short n);
3379
- basic_ostream<charT, traits>& operator<<(int n);
3380
- basic_ostream<charT, traits>& operator<<(unsigned int n);
3381
- basic_ostream<charT, traits>& operator<<(long n);
3382
- basic_ostream<charT, traits>& operator<<(unsigned long n);
3383
- basic_ostream<charT, traits>& operator<<(long long n);
3384
- basic_ostream<charT, traits>& operator<<(unsigned long long n);
3385
- basic_ostream<charT, traits>& operator<<(float f);
3386
- basic_ostream<charT, traits>& operator<<(double f);
3387
- basic_ostream<charT, traits>& operator<<(long double f);
 
3388
 
3389
- basic_ostream<charT, traits>& operator<<(const void* p);
3390
- basic_ostream<charT, traits>& operator<<(nullptr_t);
3391
- basic_ostream<charT, traits>& operator<<(basic_streambuf<char_type, traits>* sb);
 
3392
 
3393
  // [ostream.unformatted], unformatted output
3394
- basic_ostream<charT, traits>& put(char_type c);
3395
- basic_ostream<charT, traits>& write(const char_type* s, streamsize n);
3396
 
3397
- basic_ostream<charT, traits>& flush();
3398
 
3399
  // [ostream.seeks], seeks
3400
  pos_type tellp();
3401
- basic_ostream<charT, traits>& seekp(pos_type);
3402
- basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
3403
 
3404
  protected:
3405
  // [ostream.cons], copy/move constructor
3406
  basic_ostream(const basic_ostream&) = delete;
3407
  basic_ostream(basic_ostream&& rhs);
3408
 
3409
- // [ostream.assign], assign and swap
3410
  basic_ostream& operator=(const basic_ostream&) = delete;
3411
  basic_ostream& operator=(basic_ostream&& rhs);
3412
  void swap(basic_ostream& rhs);
3413
  };
3414
 
@@ -3544,15 +3677,16 @@ void swap(basic_ostream& rhs);
3544
 
3545
  ##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
3546
 
3547
  ``` cpp
3548
  namespace std {
3549
- template<class charT, class traits = char_traits<charT>>
3550
  class basic_ostream<charT, traits>::sentry {
3551
  bool ok_; // exposition only
 
3552
  public:
3553
- explicit sentry(basic_ostream<charT, traits>& os);
3554
  ~sentry();
3555
  explicit operator bool() const { return ok_; }
3556
 
3557
  sentry(const sentry&) = delete;
3558
  sentry& operator=(const sentry&) = delete;
@@ -3562,20 +3696,20 @@ namespace std {
3562
 
3563
  The class `sentry` defines a class that is responsible for doing
3564
  exception safe prefix and suffix operations.
3565
 
3566
  ``` cpp
3567
- explicit sentry(basic_ostream<charT, traits>& os);
3568
  ```
3569
 
3570
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
3571
- If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^31]
3572
 
3573
  If, after any preparation is completed, `os.good()` is `true`,
3574
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
3575
  constructor may call `setstate(failbit)` (which may throw
3576
- `ios_base::failure` [[iostate.flags]]).[^32]
3577
 
3578
  ``` cpp
3579
  ~sentry();
3580
  ```
3581
 
@@ -3601,22 +3735,22 @@ pos_type tellp();
3601
 
3602
  *Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
3603
  failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
3604
 
3605
  ``` cpp
3606
- basic_ostream<charT, traits>& seekp(pos_type pos);
3607
  ```
3608
 
3609
  *Effects:* If `fail() != true`, executes
3610
  `rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
3611
  function calls `setstate(failbit)` (which may throw
3612
  `ios_base::failure`).
3613
 
3614
  *Returns:* `*this`.
3615
 
3616
  ``` cpp
3617
- basic_ostream<charT, traits>& seekp(off_type off, ios_base::seekdir dir);
3618
  ```
3619
 
3620
  *Effects:* If `fail() != true`, executes
3621
  `rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
3622
  function calls `setstate(failbit)` (which may throw
@@ -3627,20 +3761,22 @@ function calls `setstate(failbit)` (which may throw
3627
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
3628
 
3629
  ##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
3630
 
3631
  Each formatted output function begins execution by constructing an
3632
- object of class `sentry`. If this object returns `true` when converted
3633
  to a value of type `bool`, the function endeavors to generate the
3634
  requested output. If the generation fails, then the formatted output
3635
- function does `setstate(ios_base::failbit)`, which might throw an
3636
  exception. If an exception is thrown during output, then
3637
- `ios_base::badbit` is turned on[^33] in `*this`’s error state. If
3638
- `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
3639
- not an exception is thrown, the `sentry` object is destroyed before
3640
- leaving the formatted output function. If no exception is thrown, the
3641
- result of the formatted output function is `*this`.
 
 
3642
 
3643
  The descriptions of the individual formatted output functions describe
3644
  how they perform output and do not mention the `sentry` object.
3645
 
3646
  If a formatted output function of a stream `os` determines padding, it
@@ -3653,23 +3789,23 @@ the fill characters are placed after the character sequence; otherwise,
3653
  they are placed before the character sequence.
3654
 
3655
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
3656
 
3657
  ``` cpp
3658
- operator<<(bool val);
3659
- operator<<(short val);
3660
- operator<<(unsigned short val);
3661
- operator<<(int val);
3662
- operator<<(unsigned int val);
3663
- operator<<(long val);
3664
- operator<<(unsigned long val);
3665
- operator<<(long long val);
3666
- operator<<(unsigned long long val);
3667
- operator<<(float val);
3668
- operator<<(double val);
3669
- operator<<(long double val);
3670
- operator<<(const void* val);
3671
  ```
3672
 
3673
  *Effects:* The classes `num_get<>` and `num_put<>` handle
3674
  locale-dependent numeric formatting and parsing. These inserter
3675
  functions use the imbued `locale` value to perform numeric formatting.
@@ -3740,49 +3876,90 @@ It provides formatting specifications such as field width, and a locale
3740
  from which to obtain other facets. If `failed` is `true` then does
3741
  `setstate(badbit)`, which may throw an exception, and returns.
3742
 
3743
  *Returns:* `*this`.
3744
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3745
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
3746
 
3747
  ``` cpp
3748
- basic_ostream<charT, traits>&
3749
- operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
3750
  ```
3751
 
3752
  *Effects:* None. Does not behave as a formatted output function (as
3753
  described in  [[ostream.formatted.reqmts]]).
3754
 
3755
- *Returns:* `pf(*this)`.[^34]
3756
 
3757
  ``` cpp
3758
- basic_ostream<charT, traits>&
3759
- operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
3760
  ```
3761
 
3762
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3763
  formatted output function (as described
3764
  in  [[ostream.formatted.reqmts]]).
3765
 
3766
- *Returns:* `*this`.[^35]
3767
 
3768
  ``` cpp
3769
- basic_ostream<charT, traits>& operator<<(ios_base& (*pf)(ios_base&));
3770
  ```
3771
 
3772
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3773
  formatted output function (as described
3774
  in  [[ostream.formatted.reqmts]]).
3775
 
3776
  *Returns:* `*this`.
3777
 
3778
  ``` cpp
3779
- basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
3780
  ```
3781
 
3782
  *Effects:* Behaves as an unformatted output
3783
- function [[ostream.unformatted]]. After the sentry object is
3784
  constructed, if `sb` is null calls `setstate(badbit)` (which may throw
3785
  `ios_base::failure`).
3786
 
3787
  Gets characters from `sb` and inserts them in `*this`. Characters are
3788
  read from `sb` and inserted until any of the following occurs:
@@ -3799,11 +3976,11 @@ the error state, and if `failbit` is set in `exceptions()` the caught
3799
  exception is rethrown.
3800
 
3801
  *Returns:* `*this`.
3802
 
3803
  ``` cpp
3804
- basic_ostream<charT, traits>& operator<<(nullptr_t);
3805
  ```
3806
 
3807
  *Effects:* Equivalent to:
3808
 
3809
  ``` cpp
@@ -3876,29 +4053,98 @@ Determines padding for `seq` as described
3876
  in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
3877
  `width(0)`.
3878
 
3879
  *Returns:* `out`.
3880
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3881
  #### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
3882
 
3883
  Each unformatted output function begins execution by constructing an
3884
- object of class `sentry`. If this object returns `true`, while
3885
  converting to a value of type `bool`, the function endeavors to generate
3886
  the requested output. If an exception is thrown during output, then
3887
- `ios_base::badbit` is turned on[^36] in `*this`’s error state. If
3888
- `(exceptions() & badbit) != 0` then the exception is rethrown. In any
3889
- case, the unformatted output function ends by destroying the sentry
3890
- object, then, if no exception was thrown, returning the value specified
3891
- for the unformatted output function.
 
3892
 
3893
  ``` cpp
3894
- basic_ostream<charT, traits>& put(char_type c);
3895
  ```
3896
 
3897
  *Effects:* Behaves as an unformatted output function (as described
3898
- above). After constructing a sentry object, inserts the character `c`,
3899
- if possible.[^37]
3900
 
3901
  Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
3902
  [[iostate.flags]]).
3903
 
3904
  *Returns:* `*this`.
@@ -3906,14 +4152,15 @@ Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
3906
  ``` cpp
3907
  basic_ostream& write(const char_type* s, streamsize n);
3908
  ```
3909
 
3910
  *Effects:* Behaves as an unformatted output function (as described
3911
- above). After constructing a sentry object, obtains characters to insert
3912
- from successive locations of an array whose first element is designated
3913
- by `s`.[^38] Characters are inserted until either of the following
3914
- occurs:
 
3915
 
3916
  - `n` characters are inserted;
3917
  - inserting in the output sequence fails (in which case the function
3918
  calls `setstate(badbit)`, which may throw `ios_base::failure`
3919
  [[iostate.flags]]).
@@ -3923,15 +4170,15 @@ occurs:
3923
  ``` cpp
3924
  basic_ostream& flush();
3925
  ```
3926
 
3927
  *Effects:* Behaves as an unformatted output function (as described
3928
- above). If `rdbuf()` is not a null pointer, constructs a sentry object.
3929
- If this object returns `true` when converted to a value of type `bool`
3930
- the function calls `rdbuf()->pubsync()`. If that function returns -1
3931
- calls `setstate(badbit)` (which may throw `ios_base::failure`
3932
- [[iostate.flags]]). Otherwise, if the sentry object returns `false`,
3933
  does nothing.
3934
 
3935
  *Returns:* `*this`.
3936
 
3937
  #### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
@@ -4001,11 +4248,14 @@ template<class charT, class traits>
4001
  basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
4002
  ```
4003
 
4004
  *Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
4005
  `basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
4006
- of exposition, calls `buf->emit()`.
 
 
 
4007
 
4008
  *Returns:* `os`.
4009
 
4010
  #### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
4011
 
@@ -4035,11 +4285,11 @@ unspecified resetiosflags(ios_base::fmtflags mask);
4035
  *Returns:* An object of unspecified type such that if `out` is an object
4036
  of type `basic_ostream<charT, traits>` then the expression
4037
  `out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
4038
  if `in` is an object of type `basic_istream<charT, traits>` then the
4039
  expression `in >> resetiosflags(mask)` behaves as if it called
4040
- `f(in, mask)`, where the function `f` is defined as:[^39]
4041
 
4042
  ``` cpp
4043
  void f(ios_base& str, ios_base::fmtflags mask) {
4044
  // reset specified flags
4045
  str.setf(ios_base::fmtflags(0), mask);
@@ -4234,25 +4484,25 @@ void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
4234
 
4235
  The expression `out << put_money(mon, intl)` has type
4236
  `basic_ostream<charT, traits>&` and value `out`.
4237
 
4238
  ``` cpp
4239
- template<class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
4240
  ```
4241
 
4242
  *Preconditions:* The argument `tmb` is a valid pointer to an object of
4243
- type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
4244
- is a valid range.
4245
 
4246
  *Returns:* An object of unspecified type such that if `in` is an object
4247
  of type `basic_istream<charT, traits>` then the expression
4248
  `in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
4249
  where the function `f` is defined as:
4250
 
4251
  ``` cpp
4252
  template<class charT, class traits>
4253
- void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
4254
  using Iter = istreambuf_iterator<charT, traits>;
4255
  using TimeGet = time_get<charT, Iter>;
4256
 
4257
  ios_base::iostate err = ios_base::goodbit;
4258
  const TimeGet& tg = use_facet<TimeGet>(str.getloc());
@@ -4267,25 +4517,25 @@ void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
4267
 
4268
  The expression `in >> get_time(tmb, fmt)` has type
4269
  `basic_istream<charT, traits>&` and value `in`.
4270
 
4271
  ``` cpp
4272
- template<class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
4273
  ```
4274
 
4275
  *Preconditions:* The argument `tmb` is a valid pointer to an object of
4276
- type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
4277
- is a valid range.
4278
 
4279
  *Returns:* An object of unspecified type such that if `out` is an object
4280
  of type `basic_ostream<charT, traits>` then the expression
4281
  `out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
4282
  where the function `f` is defined as:
4283
 
4284
  ``` cpp
4285
  template<class charT, class traits>
4286
- void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
4287
  using Iter = ostreambuf_iterator<charT, traits>;
4288
  using TimePut = time_put<charT, Iter>;
4289
 
4290
  const TimePut& tp = use_facet<TimePut>(str.getloc());
4291
  const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
@@ -4374,39 +4624,178 @@ template<class charT, class traits, class Allocator>
4374
  - The expression `in >> quoted(s, delim, escape)` has type
4375
  `basic_istream<charT, traits>&` and value `in`.
4376
  - The expression `out << quoted(s, delim, escape)` has type
4377
  `basic_ostream<charT, traits>&` and value `out`.
4378
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4379
  ## String-based streams <a id="string.streams">[[string.streams]]</a>
4380
 
4381
  ### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
4382
 
4383
  ``` cpp
4384
  namespace std {
4385
  template<class charT, class traits = char_traits<charT>,
4386
  class Allocator = allocator<charT>>
4387
  class basic_stringbuf;
4388
 
 
 
 
 
4389
  using stringbuf = basic_stringbuf<char>;
4390
  using wstringbuf = basic_stringbuf<wchar_t>;
4391
 
4392
  template<class charT, class traits = char_traits<charT>,
4393
  class Allocator = allocator<charT>>
4394
  class basic_istringstream;
4395
 
 
 
 
 
4396
  using istringstream = basic_istringstream<char>;
4397
  using wistringstream = basic_istringstream<wchar_t>;
4398
 
4399
  template<class charT, class traits = char_traits<charT>,
4400
  class Allocator = allocator<charT>>
4401
  class basic_ostringstream;
 
 
 
 
 
4402
  using ostringstream = basic_ostringstream<char>;
4403
  using wostringstream = basic_ostringstream<wchar_t>;
4404
 
4405
  template<class charT, class traits = char_traits<charT>,
4406
  class Allocator = allocator<charT>>
4407
  class basic_stringstream;
 
 
 
 
 
4408
  using stringstream = basic_stringstream<char>;
4409
  using wstringstream = basic_stringstream<wchar_t>;
4410
  }
4411
  ```
4412
 
@@ -4414,10 +4803,12 @@ The header `<sstream>` defines four class templates and eight types that
4414
  associate stream buffers with objects of class `basic_string`, as
4415
  described in  [[string.classes]].
4416
 
4417
  ### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
4418
 
 
 
4419
  ``` cpp
4420
  namespace std {
4421
  template<class charT, class traits = char_traits<charT>,
4422
  class Allocator = allocator<charT>>
4423
  class basic_stringbuf : public basic_streambuf<charT, traits> {
@@ -4455,11 +4846,11 @@ namespace std {
4455
  ios_base::openmode which = ios_base::in | ios_base::out);
4456
  basic_stringbuf(const basic_stringbuf&) = delete;
4457
  basic_stringbuf(basic_stringbuf&& rhs);
4458
  basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
4459
 
4460
- // [stringbuf.assign], assign and swap
4461
  basic_stringbuf& operator=(const basic_stringbuf&) = delete;
4462
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
4463
  void swap(basic_stringbuf& rhs) noexcept(see below);
4464
 
4465
  // [stringbuf.members], getters and setters
@@ -4493,14 +4884,10 @@ namespace std {
4493
  private:
4494
  ios_base::openmode mode; // exposition only
4495
  basic_string<charT, traits, Allocator> buf; // exposition only
4496
  void init_buf_ptrs(); // exposition only
4497
  };
4498
-
4499
- template<class charT, class traits, class Allocator>
4500
- void swap(basic_stringbuf<charT, traits, Allocator>& x,
4501
- basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
4502
  }
4503
  ```
4504
 
4505
  The class `basic_stringbuf` is derived from `basic_streambuf` to
4506
  associate possibly the input sequence and possibly the output sequence
@@ -4633,15 +5020,15 @@ would have had if it had been move constructed from `rhs`
4633
  void swap(basic_stringbuf& rhs) noexcept(see below);
4634
  ```
4635
 
4636
  *Preconditions:*
4637
  `allocator_traits<Allocator>::propagate_on_container_swap::value` is
4638
- `true` or `get_allocator() == s.get_allocator()` is `true`.
4639
 
4640
  *Effects:* Exchanges the state of `*this` and `rhs`.
4641
 
4642
- *Remarks:* The expression inside `noexcept` is equivalent to:
4643
  `allocator_traits<Allocator>::propagate_on_container_swap::value ||`
4644
  `allocator_traits<Allocator>::is_always_equal::value`.
4645
 
4646
  ``` cpp
4647
  template<class charT, class traits, class Allocator>
@@ -4679,12 +5066,12 @@ according to `mode`.
4679
  - otherwise `pptr() == pbase()` is `true`.
4680
  - If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
4681
  and `(gptr() == eback() && egptr() == eback() + buf.size())` is
4682
  `true`.
4683
 
4684
- [*Note 1*: For efficiency reasons, stream buffer operations might
4685
- violate invariants of `buf` while it is held encapsulated in the
4686
  `basic_stringbuf`, e.g., by writing to characters in the range
4687
  \[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
4688
  operations retrieving a `basic_string` from `buf` ensure that the
4689
  `basic_string` invariants hold on the returned value. — *end note*]
4690
 
@@ -4720,19 +5107,19 @@ return basic_string<charT, traits, SAlloc>(view(), sa);
4720
 
4721
  ``` cpp
4722
  basic_string<charT, traits, Allocator> str() &&;
4723
  ```
4724
 
 
 
 
 
4725
  *Returns:* A `basic_string<charT, traits, Allocator>` object move
4726
  constructed from the `basic_stringbuf`’s underlying character sequence
4727
  in `buf`. This can be achieved by first adjusting `buf` to have the same
4728
  content as `view()`.
4729
 
4730
- *Ensures:* The underlying character sequence `buf` is empty and
4731
- `pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
4732
- initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
4733
-
4734
  ``` cpp
4735
  basic_string_view<charT, traits> view() const noexcept;
4736
  ```
4737
 
4738
  Let `sv` be `basic_string_view<charT, traits>`.
@@ -4808,11 +5195,11 @@ sequence, if possible, in one of three ways:
4808
  input sequence has a putback position available, and if
4809
  `traits::eq(to_char_type(c), gptr()[-1])` returns `true`, assigns
4810
  `gptr() - 1` to `gptr()`. Returns: `c`.
4811
  - If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
4812
  input sequence has a putback position available, and if `mode` `&`
4813
- `ios_base::out` is nonzero, assigns `c` to `*``gptr()`. Returns: `c`.
4814
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
4815
  input sequence has a putback position available, assigns `gptr() - 1`
4816
  to `gptr()`. Returns: `traits::not_eof(c)`.
4817
 
4818
  *Returns:* As specified above, or `traits::eof()` to indicate failure.
@@ -4833,15 +5220,15 @@ sequence, if possible, in one of two ways:
4833
  function calls `sputc(c)`. Signals success by returning `c`.
4834
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, there is no
4835
  character to append. Signals success by returning a value other than
4836
  `traits::eof()`.
4837
 
 
 
4838
  *Remarks:* The function can alter the number of write positions
4839
  available as a result of any call.
4840
 
4841
- *Returns:* As specified above, or `traits::eof()` to indicate failure.
4842
-
4843
  The function can make a write position available only if `ios_base::out`
4844
  is set in `mode`. To make a write position available, the function
4845
  reallocates (or initially allocates) an array object with a sufficient
4846
  number of elements to hold the current array object (if any), plus at
4847
  least one additional write position. If `ios_base::in` is set in `mode`,
@@ -4902,20 +5289,22 @@ pos_type seekpos(pos_type sp,
4902
 
4903
  *Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
4904
  indicate failure.
4905
 
4906
  ``` cpp
4907
- basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n);
4908
  ```
4909
 
4910
  *Effects:* *implementation-defined*, except that `setbuf(0, 0)` has no
4911
  effect.
4912
 
4913
  *Returns:* `this`.
4914
 
4915
  ### Class template `basic_istringstream` <a id="istringstream">[[istringstream]]</a>
4916
 
 
 
4917
  ``` cpp
4918
  namespace std {
4919
  template<class charT, class traits = char_traits<charT>,
4920
  class Allocator = allocator<charT>>
4921
  class basic_istringstream : public basic_istream<charT, traits> {
@@ -4950,13 +5339,14 @@ namespace std {
4950
  const basic_string<charT, traits, SAlloc>& s,
4951
  ios_base::openmode which = ios_base::in);
4952
  basic_istringstream(const basic_istringstream&) = delete;
4953
  basic_istringstream(basic_istringstream&& rhs);
4954
 
4955
- // [istringstream.assign], assign and swap
4956
  basic_istringstream& operator=(const basic_istringstream&) = delete;
4957
  basic_istringstream& operator=(basic_istringstream&& rhs);
 
 
4958
  void swap(basic_istringstream& rhs);
4959
 
4960
  // [istringstream.members], members
4961
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
4962
  basic_string<charT, traits, Allocator> str() const &;
@@ -4971,14 +5361,10 @@ namespace std {
4971
  void str(basic_string<charT, traits, Allocator>&& s);
4972
 
4973
  private:
4974
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
4975
  };
4976
-
4977
- template<class charT, class traits, class Allocator>
4978
- void swap(basic_istringstream<charT, traits, Allocator>& x,
4979
- basic_istringstream<charT, traits, Allocator>& y);
4980
  }
4981
  ```
4982
 
4983
  The class `basic_istringstream<charT, traits, Allocator>` supports
4984
  reading objects of class `basic_string<{}charT, traits, Allocator>`. It
@@ -5005,11 +5391,12 @@ explicit basic_istringstream(
5005
  ios_base::openmode which = ios_base::in);
5006
  ```
5007
 
5008
  *Effects:* Initializes the base class with
5009
  `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5010
- `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`([[stringbuf.cons]]).
 
5011
 
5012
  ``` cpp
5013
  basic_istringstream(ios_base::openmode which, const Allocator& a);
5014
  ```
5015
 
@@ -5036,11 +5423,12 @@ template<class SAlloc>
5036
  ios_base::openmode which, const Allocator& a);
5037
  ```
5038
 
5039
  *Effects:* Initializes the base class with
5040
  `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5041
- `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`([[stringbuf.cons]]).
 
5042
 
5043
  ``` cpp
5044
  template<class SAlloc>
5045
  explicit basic_istringstream(
5046
  const basic_string<charT, traits, SAlloc>& s,
@@ -5060,11 +5448,11 @@ basic_istringstream(basic_istringstream&& rhs);
5060
  by move constructing the base class, and the contained
5061
  `basic_stringbuf`. Then calls
5062
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5063
  contained `basic_stringbuf`.
5064
 
5065
- #### Assignment and swap <a id="istringstream.assign">[[istringstream.assign]]</a>
5066
 
5067
  ``` cpp
5068
  void swap(basic_istringstream& rhs);
5069
  ```
5070
 
@@ -5136,10 +5524,12 @@ void str(basic_string<charT, traits, Allocator>&& s);
5136
 
5137
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5138
 
5139
  ### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
5140
 
 
 
5141
  ``` cpp
5142
  namespace std {
5143
  template<class charT, class traits = char_traits<charT>,
5144
  class Allocator = allocator<charT>>
5145
  class basic_ostringstream : public basic_ostream<charT, traits> {
@@ -5174,13 +5564,14 @@ namespace std {
5174
  const basic_string<charT, traits, SAlloc>& s,
5175
  ios_base::openmode which = ios_base::out);
5176
  basic_ostringstream(const basic_ostringstream&) = delete;
5177
  basic_ostringstream(basic_ostringstream&& rhs);
5178
 
5179
- // [ostringstream.assign], assign and swap
5180
  basic_ostringstream& operator=(const basic_ostringstream&) = delete;
5181
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
 
 
5182
  void swap(basic_ostringstream& rhs);
5183
 
5184
  // [ostringstream.members], members
5185
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5186
 
@@ -5196,14 +5587,10 @@ namespace std {
5196
  void str(basic_string<charT, traits, Allocator>&& s);
5197
 
5198
  private:
5199
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5200
  };
5201
-
5202
- template<class charT, class traits, class Allocator>
5203
- void swap(basic_ostringstream<charT, traits, Allocator>& x,
5204
- basic_ostringstream<charT, traits, Allocator>& y);
5205
  }
5206
  ```
5207
 
5208
  The class `basic_ostringstream<charT, traits, Allocator>` supports
5209
  writing objects of class `basic_string<{}charT, traits, Allocator>`. It
@@ -5229,19 +5616,21 @@ explicit basic_ostringstream(
5229
  ios_base::openmode which = ios_base::out);
5230
  ```
5231
 
5232
  *Effects:* Initializes the base class with
5233
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5234
- `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`([[stringbuf.cons]]).
 
5235
 
5236
  ``` cpp
5237
  basic_ostringstream(ios_base::openmode which, const Allocator& a);
5238
  ```
5239
 
5240
  *Effects:* Initializes the base class with
5241
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5242
- `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`([[stringbuf.cons]]).
 
5243
 
5244
  ``` cpp
5245
  explicit basic_ostringstream(
5246
  basic_string<charT, traits, Allocator>&& s,
5247
  ios_base::openmode which = ios_base::out);
@@ -5259,11 +5648,12 @@ template<class SAlloc>
5259
  ios_base::openmode which, const Allocator& a);
5260
  ```
5261
 
5262
  *Effects:* Initializes the base class with
5263
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5264
- `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`([[stringbuf.cons]]).
 
5265
 
5266
  ``` cpp
5267
  template<class SAlloc>
5268
  explicit basic_ostringstream(
5269
  const basic_string<charT, traits, SAlloc>& s,
@@ -5272,11 +5662,12 @@ template<class SAlloc>
5272
 
5273
  *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
5274
 
5275
  *Effects:* Initializes the base class with
5276
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5277
- `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`([[stringbuf.cons]]).
 
5278
 
5279
  ``` cpp
5280
  basic_ostringstream(basic_ostringstream&& rhs);
5281
  ```
5282
 
@@ -5284,11 +5675,11 @@ basic_ostringstream(basic_ostringstream&& rhs);
5284
  by move constructing the base class, and the contained
5285
  `basic_stringbuf`. Then calls
5286
  `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5287
  contained `basic_stringbuf`.
5288
 
5289
- #### Assignment and swap <a id="ostringstream.assign">[[ostringstream.assign]]</a>
5290
 
5291
  ``` cpp
5292
  void swap(basic_ostringstream& rhs);
5293
  ```
5294
 
@@ -5360,10 +5751,12 @@ void str(basic_string<charT, traits, Allocator>&& s);
5360
 
5361
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5362
 
5363
  ### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
5364
 
 
 
5365
  ``` cpp
5366
  namespace std {
5367
  template<class charT, class traits = char_traits<charT>,
5368
  class Allocator = allocator<charT>>
5369
  class basic_stringstream : public basic_iostream<charT, traits> {
@@ -5398,13 +5791,14 @@ namespace std {
5398
  const basic_string<charT, traits, SAlloc>& s,
5399
  ios_base::openmode which = ios_base::out | ios_base::in);
5400
  basic_stringstream(const basic_stringstream&) = delete;
5401
  basic_stringstream(basic_stringstream&& rhs);
5402
 
5403
- // [stringstream.assign], assign and swap
5404
  basic_stringstream& operator=(const basic_stringstream&) = delete;
5405
  basic_stringstream& operator=(basic_stringstream&& rhs);
 
 
5406
  void swap(basic_stringstream& rhs);
5407
 
5408
  // [stringstream.members], members
5409
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5410
 
@@ -5420,14 +5814,10 @@ namespace std {
5420
  void str(basic_string<charT, traits, Allocator>&& s);
5421
 
5422
  private:
5423
  basic_stringbuf<charT, traits> sb; // exposition only
5424
  };
5425
-
5426
- template<class charT, class traits, class Allocator>
5427
- void swap(basic_stringstream<charT, traits, Allocator>& x,
5428
- basic_stringstream<charT, traits, Allocator>& y);
5429
  }
5430
  ```
5431
 
5432
  The class template `basic_stringstream<charT, traits>` supports reading
5433
  and writing from objects of class
@@ -5513,11 +5903,11 @@ basic_stringstream(basic_stringstream&& rhs);
5513
  by move constructing the base class, and the contained
5514
  `basic_stringbuf`. Then calls
5515
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5516
  contained `basic_stringbuf`.
5517
 
5518
- #### Assignment and swap <a id="stringstream.assign">[[stringstream.assign]]</a>
5519
 
5520
  ``` cpp
5521
  void swap(basic_stringstream& rhs);
5522
  ```
5523
 
@@ -5587,33 +5977,686 @@ template<class SAlloc>
5587
  void str(basic_string<charT, traits, Allocator>&& s);
5588
  ```
5589
 
5590
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5591
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5592
  ## File-based streams <a id="file.streams">[[file.streams]]</a>
5593
 
5594
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
5595
 
5596
  ``` cpp
5597
  namespace std {
5598
  template<class charT, class traits = char_traits<charT>>
5599
  class basic_filebuf;
 
 
 
 
5600
  using filebuf = basic_filebuf<char>;
5601
  using wfilebuf = basic_filebuf<wchar_t>;
5602
 
5603
  template<class charT, class traits = char_traits<charT>>
5604
  class basic_ifstream;
 
 
 
 
5605
  using ifstream = basic_ifstream<char>;
5606
  using wifstream = basic_ifstream<wchar_t>;
5607
 
5608
  template<class charT, class traits = char_traits<charT>>
5609
  class basic_ofstream;
 
 
 
 
5610
  using ofstream = basic_ofstream<char>;
5611
  using wofstream = basic_ofstream<wchar_t>;
5612
 
5613
  template<class charT, class traits = char_traits<charT>>
5614
  class basic_fstream;
 
 
 
 
5615
  using fstream = basic_fstream<char>;
5616
  using wfstream = basic_fstream<wchar_t>;
5617
  }
5618
  ```
5619
 
@@ -5626,18 +6669,20 @@ or sink of bytes. In an environment that uses a large character set, the
5626
  file typically holds multibyte character sequences and the
5627
  `basic_filebuf` object converts those multibyte sequences into wide
5628
  character sequences. — *end note*]
5629
 
5630
  In subclause  [[file.streams]], member functions taking arguments of
5631
- `const filesystem::path::value_type*` are only be provided on systems
5632
- where `filesystem::path::value_type` [[fs.class.path]] is not `char`.
5633
 
5634
  [*Note 2*: These functions enable class `path` support for systems with
5635
  a wide native path character type, such as `wchar_t`. — *end note*]
5636
 
5637
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
5638
 
 
 
5639
  ``` cpp
5640
  namespace std {
5641
  template<class charT, class traits = char_traits<charT>>
5642
  class basic_filebuf : public basic_streambuf<charT, traits> {
5643
  public:
@@ -5651,11 +6696,11 @@ namespace std {
5651
  basic_filebuf();
5652
  basic_filebuf(const basic_filebuf&) = delete;
5653
  basic_filebuf(basic_filebuf&& rhs);
5654
  virtual ~basic_filebuf();
5655
 
5656
- // [filebuf.assign], assign and swap
5657
  basic_filebuf& operator=(const basic_filebuf&) = delete;
5658
  basic_filebuf& operator=(basic_filebuf&& rhs);
5659
  void swap(basic_filebuf& rhs);
5660
 
5661
  // [filebuf.members], members
@@ -5686,14 +6731,10 @@ namespace std {
5686
  ios_base::openmode which
5687
  = ios_base::in | ios_base::out) override;
5688
  int sync() override;
5689
  void imbue(const locale& loc) override;
5690
  };
5691
-
5692
- template<class charT, class traits>
5693
- void swap(basic_filebuf<charT, traits>& x,
5694
- basic_filebuf<charT, traits>& y);
5695
  }
5696
  ```
5697
 
5698
  The class `basic_filebuf<charT, traits>` associates both the input
5699
  sequence and the output sequence with a file.
@@ -5791,12 +6832,11 @@ void swap(basic_filebuf& rhs);
5791
 
5792
  *Effects:* Exchanges the state of `*this` and `rhs`.
5793
 
5794
  ``` cpp
5795
  template<class charT, class traits>
5796
- void swap(basic_filebuf<charT, traits>& x,
5797
- basic_filebuf<charT, traits>& y);
5798
  ```
5799
 
5800
  *Effects:* Equivalent to: `x.swap(y)`.
5801
 
5802
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
@@ -5823,35 +6863,42 @@ argument determined from `mode & ~ios_base::ate` as indicated in
5823
  [[filebuf.open.modes]]. If `mode` is not some combination of flags shown
5824
  in the table then the open fails.
5825
 
5826
  **Table: File open modes** <a id="filebuf.open.modes">[filebuf.open.modes]</a>
5827
 
5828
- | `binary` | `in` | `out` | `trunc` | `app` | | `stdio` equivalent |
5829
- | -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
5830
- | | | + | | | `"w"` |
5831
- | | | + | | + | `"a"` |
5832
- | | | | | + | `"a"` |
5833
- | | | + | + | | `"w"` |
5834
- | | + | | | | `"r"` |
5835
- | | + | + | | | `"r+"` |
5836
- | | + | + | + | | `"w+"` |
5837
- | | + | + | | + | `"a+"` |
5838
- | | + | | | + | `"a+"` + | | + | | | `"wb"` |
5839
- | + | | + | | + | `"ab"` |
5840
- | + | | | | + | `"ab"` |
5841
- | + | | + | + | | `"wb"` |
5842
- | + | + | | | | `"rb"` |
5843
- | + | + | + | | | `"r+b"` |
5844
- | + | + | + | + | | `"w+b"` |
5845
- | + | + | + | | + | `"a+b"` |
5846
- | + | + | | | + | `"a+b"` |
 
 
 
 
 
 
 
5847
 
5848
 
5849
  If the open operation succeeds and `ios_base::ate` is set in `mode`,
5850
  positions the file to the end (as if by calling
5851
  `fseek(file, 0, SEEK_END)`, where `file` is the pointer returned by
5852
- calling `fopen`). [^40]
5853
 
5854
  If the repositioning operation fails, calls `close()` and returns a null
5855
  pointer to indicate failure.
5856
 
5857
  *Returns:* `this` if successful, a null pointer otherwise.
@@ -5878,25 +6925,25 @@ or throws an exception, the function closes the file (as if by calling
5878
  `fclose(file)`). If any of the calls made by the function, including
5879
  `fclose`, fails, `close` fails by returning a null pointer. If one of
5880
  these calls throws an exception, the exception is caught and rethrown
5881
  after closing the file.
5882
 
 
 
5883
  *Returns:* `this` on success, a null pointer otherwise.
5884
 
5885
- *Ensures:* `is_open() == false`.
5886
-
5887
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
5888
 
5889
  ``` cpp
5890
  streamsize showmanyc() override;
5891
  ```
5892
 
5893
  *Effects:* Behaves the same as `basic_streambuf::showmanyc()`
5894
  [[streambuf.virtuals]].
5895
 
5896
- *Remarks:* An implementation might well provide an overriding definition
5897
- for this function signature if it can determine that more characters can
5898
  be read from the input sequence.
5899
 
5900
  ``` cpp
5901
  int_type underflow() override;
5902
  ```
@@ -6018,10 +7065,15 @@ operation fails. Otherwise, if `way != basic_ios::cur` or `off != 0`,
6018
  and if the last operation was output, then update the output sequence
6019
  and write any unshift sequence. Next, seek to the new position: if
6020
  `width > 0`, call `fseek(file, width * off, whence)`, otherwise call
6021
  `fseek(file, 0, whence)`.
6022
 
 
 
 
 
 
6023
  *Remarks:* “The last operation was output” means either the last virtual
6024
  operation was overflow or the put buffer is non-empty. “Write any
6025
  unshift sequence” means, if `width` if less than zero then call
6026
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
6027
  resulting unshift sequence. The function determines one of three values
@@ -6034,16 +7086,10 @@ for the argument `whence`, of type `int`, as indicated in
6034
  | ---------------- | ------------------ |
6035
  | `basic_ios::beg` | `SEEK_SET` |
6036
  | `basic_ios::cur` | `SEEK_CUR` |
6037
  | `basic_ios::end` | `SEEK_END` |
6038
 
6039
-
6040
- *Returns:* A newly constructed `pos_type` object that stores the
6041
- resultant stream position, if possible. If the positioning operation
6042
- fails, or if the object cannot represent the resultant stream position,
6043
- returns `pos_type(off_type(-1))`.
6044
-
6045
  ``` cpp
6046
  pos_type seekpos(pos_type sp,
6047
  ios_base::openmode which
6048
  = ios_base::in | ios_base::out) override;
6049
  ```
@@ -6093,10 +7139,12 @@ converted according to `loc` until another call of `imbue`.
6093
  characters. This in turn may require the implementation to be able to
6094
  reconstruct the original contents of the file.
6095
 
6096
  ### Class template `basic_ifstream` <a id="ifstream">[[ifstream]]</a>
6097
 
 
 
6098
  ``` cpp
6099
  namespace std {
6100
  template<class charT, class traits = char_traits<charT>>
6101
  class basic_ifstream : public basic_istream<charT, traits> {
6102
  public:
@@ -6112,18 +7160,19 @@ namespace std {
6112
  ios_base::openmode mode = ios_base::in);
6113
  explicit basic_ifstream(const filesystem::path::value_type* s,
6114
  ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
6115
  explicit basic_ifstream(const string& s,
6116
  ios_base::openmode mode = ios_base::in);
6117
- explicit basic_ifstream(const filesystem::path& s,
6118
- ios_base::openmode mode = ios_base::in);
6119
  basic_ifstream(const basic_ifstream&) = delete;
6120
  basic_ifstream(basic_ifstream&& rhs);
6121
 
6122
- // [ifstream.assign], assign and swap
6123
  basic_ifstream& operator=(const basic_ifstream&) = delete;
6124
  basic_ifstream& operator=(basic_ifstream&& rhs);
 
 
6125
  void swap(basic_ifstream& rhs);
6126
 
6127
  // [ifstream.members], members
6128
  basic_filebuf<charT, traits>* rdbuf() const;
6129
 
@@ -6132,17 +7181,14 @@ namespace std {
6132
  void open(const filesystem::path::value_type* s,
6133
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
6134
  void open(const string& s, ios_base::openmode mode = ios_base::in);
6135
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
6136
  void close();
 
6137
  private:
6138
  basic_filebuf<charT, traits> sb; // exposition only
6139
  };
6140
-
6141
- template<class charT, class traits>
6142
- void swap(basic_ifstream<charT, traits>& x,
6143
- basic_ifstream<charT, traits>& y);
6144
  }
6145
  ```
6146
 
6147
  The class `basic_ifstream<charT, traits>` supports reading from named
6148
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
@@ -6175,38 +7221,44 @@ with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
6175
  pointer, calls `setstate(failbit)`.
6176
 
6177
  ``` cpp
6178
  explicit basic_ifstream(const string& s,
6179
  ios_base::openmode mode = ios_base::in);
6180
- explicit basic_ifstream(const filesystem::path& s,
6181
- ios_base::openmode mode = ios_base::in);
6182
  ```
6183
 
6184
  *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
6185
 
 
 
 
 
 
 
 
 
 
6186
  ``` cpp
6187
  basic_ifstream(basic_ifstream&& rhs);
6188
  ```
6189
 
6190
  *Effects:* Move constructs the base class, and the contained
6191
  `basic_filebuf`. Then calls
6192
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
6193
  contained `basic_filebuf`.
6194
 
6195
- #### Assignment and swap <a id="ifstream.assign">[[ifstream.assign]]</a>
6196
 
6197
  ``` cpp
6198
  void swap(basic_ifstream& rhs);
6199
  ```
6200
 
6201
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
6202
  `basic_istream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
6203
 
6204
  ``` cpp
6205
  template<class charT, class traits>
6206
- void swap(basic_ifstream<charT, traits>& x,
6207
- basic_ifstream<charT, traits>& y);
6208
  ```
6209
 
6210
  *Effects:* Equivalent to: `x.swap(y)`.
6211
 
6212
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
@@ -6249,10 +7301,12 @@ void close();
6249
  pointer, calls `setstate(failbit)` (which may throw
6250
  `ios_base::failure`) [[iostate.flags]].
6251
 
6252
  ### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
6253
 
 
 
6254
  ``` cpp
6255
  namespace std {
6256
  template<class charT, class traits = char_traits<charT>>
6257
  class basic_ofstream : public basic_ostream<charT, traits> {
6258
  public:
@@ -6268,18 +7322,19 @@ namespace std {
6268
  ios_base::openmode mode = ios_base::out);
6269
  explicit basic_ofstream(const filesystem::path::value_type* s, // wide systems only; see [fstream.syn]
6270
  ios_base::openmode mode = ios_base::out);
6271
  explicit basic_ofstream(const string& s,
6272
  ios_base::openmode mode = ios_base::out);
6273
- explicit basic_ofstream(const filesystem::path& s,
6274
- ios_base::openmode mode = ios_base::out);
6275
  basic_ofstream(const basic_ofstream&) = delete;
6276
  basic_ofstream(basic_ofstream&& rhs);
6277
 
6278
- // [ofstream.assign], assign and swap
6279
  basic_ofstream& operator=(const basic_ofstream&) = delete;
6280
  basic_ofstream& operator=(basic_ofstream&& rhs);
 
 
6281
  void swap(basic_ofstream& rhs);
6282
 
6283
  // [ofstream.members], members
6284
  basic_filebuf<charT, traits>* rdbuf() const;
6285
 
@@ -6288,17 +7343,14 @@ namespace std {
6288
  void open(const filesystem::path::value_type* s,
6289
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
6290
  void open(const string& s, ios_base::openmode mode = ios_base::out);
6291
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
6292
  void close();
 
6293
  private:
6294
  basic_filebuf<charT, traits> sb; // exposition only
6295
  };
6296
-
6297
- template<class charT, class traits>
6298
- void swap(basic_ofstream<charT, traits>& x,
6299
- basic_ofstream<charT, traits>& y);
6300
  }
6301
  ```
6302
 
6303
  The class `basic_ofstream<charT, traits>` supports writing to named
6304
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
@@ -6331,38 +7383,44 @@ with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
6331
  null pointer, calls `setstate(failbit)`.
6332
 
6333
  ``` cpp
6334
  explicit basic_ofstream(const string& s,
6335
  ios_base::openmode mode = ios_base::out);
6336
- explicit basic_ofstream(const filesystem::path& s,
6337
- ios_base::openmode mode = ios_base::out);
6338
  ```
6339
 
6340
  *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
6341
 
 
 
 
 
 
 
 
 
 
6342
  ``` cpp
6343
  basic_ofstream(basic_ofstream&& rhs);
6344
  ```
6345
 
6346
  *Effects:* Move constructs the base class, and the contained
6347
  `basic_filebuf`. Then calls
6348
  `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
6349
  contained `basic_filebuf`.
6350
 
6351
- #### Assignment and swap <a id="ofstream.assign">[[ofstream.assign]]</a>
6352
 
6353
  ``` cpp
6354
  void swap(basic_ofstream& rhs);
6355
  ```
6356
 
6357
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
6358
  `basic_ostream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
6359
 
6360
  ``` cpp
6361
  template<class charT, class traits>
6362
- void swap(basic_ofstream<charT, traits>& x,
6363
- basic_ofstream<charT, traits>& y);
6364
  ```
6365
 
6366
  *Effects:* Equivalent to: `x.swap(y)`.
6367
 
6368
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
@@ -6405,10 +7463,12 @@ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
6405
 
6406
  *Effects:* Calls `open(s.c_str(), mode)`.
6407
 
6408
  ### Class template `basic_fstream` <a id="fstream">[[fstream]]</a>
6409
 
 
 
6410
  ``` cpp
6411
  namespace std {
6412
  template<class charT, class traits = char_traits<charT>>
6413
  class basic_fstream : public basic_iostream<charT, traits> {
6414
  public:
@@ -6427,19 +7487,19 @@ namespace std {
6427
  const filesystem::path::value_type* s,
6428
  ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
6429
  explicit basic_fstream(
6430
  const string& s,
6431
  ios_base::openmode mode = ios_base::in | ios_base::out);
6432
- explicit basic_fstream(
6433
- const filesystem::path& s,
6434
- ios_base::openmode mode = ios_base::in | ios_base::out);
6435
  basic_fstream(const basic_fstream&) = delete;
6436
  basic_fstream(basic_fstream&& rhs);
6437
 
6438
- // [fstream.assign], assign and swap
6439
  basic_fstream& operator=(const basic_fstream&) = delete;
6440
  basic_fstream& operator=(basic_fstream&& rhs);
 
 
6441
  void swap(basic_fstream& rhs);
6442
 
6443
  // [fstream.members], members
6444
  basic_filebuf<charT, traits>* rdbuf() const;
6445
  bool is_open() const;
@@ -6458,14 +7518,10 @@ namespace std {
6458
  void close();
6459
 
6460
  private:
6461
  basic_filebuf<charT, traits> sb; // exposition only
6462
  };
6463
-
6464
- template<class charT, class traits>
6465
- void swap(basic_fstream<charT, traits>& x,
6466
- basic_fstream<charT, traits>& y);
6467
  }
6468
  ```
6469
 
6470
  The class template `basic_fstream<charT, traits>` supports reading and
6471
  writing from named files. It uses a `basic_filebuf<charT, traits>`
@@ -6501,27 +7557,33 @@ explicit basic_fstream(
6501
 
6502
  ``` cpp
6503
  explicit basic_fstream(
6504
  const string& s,
6505
  ios_base::openmode mode = ios_base::in | ios_base::out);
6506
- explicit basic_fstream(
6507
- const filesystem::path& s,
6508
- ios_base::openmode mode = ios_base::in | ios_base::out);
6509
  ```
6510
 
6511
  *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
6512
 
 
 
 
 
 
 
 
 
 
6513
  ``` cpp
6514
  basic_fstream(basic_fstream&& rhs);
6515
  ```
6516
 
6517
  *Effects:* Move constructs the base class, and the contained
6518
  `basic_filebuf`. Then calls
6519
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
6520
  contained `basic_filebuf`.
6521
 
6522
- #### Assignment and swap <a id="fstream.assign">[[fstream.assign]]</a>
6523
 
6524
  ``` cpp
6525
  void swap(basic_fstream& rhs);
6526
  ```
6527
 
@@ -6592,10 +7654,15 @@ pointer, calls `setstate(failbit)` (which may throw
6592
 
6593
  namespace std {
6594
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
6595
  class basic_syncbuf;
6596
 
 
 
 
 
 
6597
  using syncbuf = basic_syncbuf<char>;
6598
  using wsyncbuf = basic_syncbuf<wchar_t>;
6599
 
6600
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
6601
  class basic_osyncstream;
@@ -6651,15 +7718,10 @@ namespace std {
6651
 
6652
  private:
6653
  streambuf_type* wrapped; // exposition only
6654
  bool emit_on_sync{}; // exposition only
6655
  };
6656
-
6657
- // [syncstream.syncbuf.special], specialized algorithms
6658
- template<class charT, class traits, class Allocator>
6659
- void swap(basic_syncbuf<charT, traits, Allocator>&,
6660
- basic_syncbuf<charT, traits, Allocator>&);
6661
  }
6662
  ```
6663
 
6664
  Class template `basic_syncbuf` stores character data written to it,
6665
  known as the associated output, into internal buffers allocated using
@@ -6675,28 +7737,27 @@ wrapped stream buffer object.
6675
  basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
6676
  ```
6677
 
6678
  *Effects:* Sets `wrapped` to `obuf`.
6679
 
6680
- *Remarks:* A copy of `allocator` is used to allocate memory for internal
6681
- buffers holding the associated output.
6682
-
6683
- *Throws:* Nothing unless an exception is thrown by the construction of a
6684
- mutex or by memory allocation.
6685
-
6686
  *Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
6687
  are `true`.
6688
 
 
 
 
 
 
 
6689
  ``` cpp
6690
  basic_syncbuf(basic_syncbuf&& other);
6691
  ```
6692
 
6693
  *Ensures:* The value returned by `this->get_wrapped()` is the value
6694
  returned by `other.get_wrapped()` prior to calling this constructor.
6695
  Output stored in `other` prior to calling this constructor will be
6696
- stored in `*this` afterwards.
6697
- `other.rdbuf()->pbase() == other.rdbuf()->pptr()` and
6698
  `other.get_wrapped() == nullptr` are `true`.
6699
 
6700
  *Remarks:* This constructor disassociates `other` from its wrapped
6701
  stream buffer, ensuring destruction of `other` produces no output.
6702
 
@@ -6710,34 +7771,34 @@ stream buffer, ensuring destruction of `other` produces no output.
6710
  destructor catches and ignores that exception.
6711
 
6712
  #### Assignment and swap <a id="syncstream.syncbuf.assign">[[syncstream.syncbuf.assign]]</a>
6713
 
6714
  ``` cpp
6715
- basic_syncbuf& operator=(basic_syncbuf&& rhs) noexcept;
6716
  ```
6717
 
6718
  *Effects:* Calls `emit()` then move assigns from `rhs`. After the move
6719
  assignment `*this` has the observable state it would have had if it had
6720
  been move constructed from `rhs` [[syncstream.syncbuf.cons]].
6721
 
6722
- *Returns:* `*this`.
6723
-
6724
  *Ensures:*
6725
 
6726
  - `rhs.get_wrapped() == nullptr` is `true`.
6727
  - `this->get_allocator() == rhs.get_allocator()` is `true` when
6728
  ``` cpp
6729
  allocator_traits<Allocator>::propagate_on_container_move_assignment::value
6730
  ```
6731
 
6732
  is `true`; otherwise, the allocator is unchanged.
6733
 
 
 
6734
  *Remarks:* This assignment operator disassociates `rhs` from its wrapped
6735
  stream buffer, ensuring destruction of `rhs` produces no output.
6736
 
6737
  ``` cpp
6738
- void swap(basic_syncbuf& other) noexcept;
6739
  ```
6740
 
6741
  *Preconditions:* Either
6742
  `allocator_traits<Allocator>::propagate_on_container_swap::value` is
6743
  `true` or `this->get_allocator() == other.get_allocator()` is `true`.
@@ -6754,25 +7815,25 @@ bool emit();
6754
  stream buffer `*wrapped`, so that it appears in the output stream as a
6755
  contiguous sequence of characters. `wrapped->pubsync()` is called if and
6756
  only if a call was made to `sync()` since the most recent call to
6757
  `emit()`, if any.
6758
 
 
 
 
 
 
 
 
6759
  *Returns:* `true` if all of the following conditions hold; otherwise
6760
  `false`:
6761
 
6762
  - `wrapped == nullptr` is `false`.
6763
  - All of the characters in the associated output were successfully
6764
  transferred.
6765
  - The call to `wrapped->pubsync()` (if any) succeeded.
6766
 
6767
- *Ensures:* On success, the associated output is empty.
6768
-
6769
- *Synchronization:* All `emit()` calls transferring characters to the
6770
- same stream buffer object appear to execute in a total order consistent
6771
- with the “happens before” relation [[intro.races]], where each `emit()`
6772
- call synchronizes with subsequent `emit()` calls in that total order.
6773
-
6774
  *Remarks:* May call member functions of `wrapped` while holding a lock
6775
  uniquely associated with `wrapped`.
6776
 
6777
  ``` cpp
6778
  streambuf_type* get_wrapped() const noexcept;
@@ -6811,11 +7872,11 @@ otherwise `0`.
6811
  #### Specialized algorithms <a id="syncstream.syncbuf.special">[[syncstream.syncbuf.special]]</a>
6812
 
6813
  ``` cpp
6814
  template<class charT, class traits, class Allocator>
6815
  void swap(basic_syncbuf<charT, traits, Allocator>& a,
6816
- basic_syncbuf<charT, traits, Allocator>& b) noexcept;
6817
  ```
6818
 
6819
  *Effects:* Equivalent to `a.swap(b)`.
6820
 
6821
  ### Class template `basic_osyncstream` <a id="syncstream.osyncstream">[[syncstream.osyncstream]]</a>
@@ -6847,11 +7908,11 @@ namespace std {
6847
  : basic_osyncstream(os, Allocator()) {}
6848
  basic_osyncstream(basic_osyncstream&&) noexcept;
6849
  ~basic_osyncstream();
6850
 
6851
  // assignment
6852
- basic_osyncstream& operator=(basic_osyncstream&&) noexcept;
6853
 
6854
  // [syncstream.osyncstream.members], member functions
6855
  void emit();
6856
  streambuf_type* get_wrapped() const noexcept;
6857
  syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); }
@@ -6860,12 +7921,12 @@ namespace std {
6860
  syncbuf_type sb; // exposition only
6861
  };
6862
  }
6863
  ```
6864
 
6865
- `Allocator` shall meet the *Cpp17Allocator* requirements (
6866
- [[cpp17.allocator]]).
6867
 
6868
  [*Example 1*:
6869
 
6870
  A named variable can be used within a block statement for streaming.
6871
 
@@ -6900,13 +7961,13 @@ basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
6900
  ```
6901
 
6902
  *Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
6903
  base class with `basic_ostream<charT, traits>(addressof(sb))`.
6904
 
6905
- [*Note 1*: The member functions of the provided stream buffer might be
6906
- called from `emit()` while a lock is held. Care should be taken to
6907
- ensure that this does not result in deadlock. — *end note*]
6908
 
6909
  *Ensures:* `get_wrapped() == buf` is `true`.
6910
 
6911
  ``` cpp
6912
  basic_osyncstream(basic_osyncstream&& other) noexcept;
@@ -6915,20 +7976,22 @@ basic_osyncstream(basic_osyncstream&& other) noexcept;
6915
  *Effects:* Move constructs the base class and `sb` from the
6916
  corresponding subobjects of `other`, and calls
6917
  `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
6918
 
6919
  *Ensures:* The value returned by `get_wrapped()` is the value returned
6920
- by `os.get_wrapped()` prior to calling this constructor.
6921
  `nullptr == other.get_wrapped()` is `true`.
6922
 
6923
  #### Member functions <a id="syncstream.osyncstream.members">[[syncstream.osyncstream.members]]</a>
6924
 
6925
  ``` cpp
6926
  void emit();
6927
  ```
6928
 
6929
- *Effects:* Calls `sb.emit()`. If that call returns `false`, calls
 
 
6930
  `setstate(ios_base::badbit)`.
6931
 
6932
  [*Example 1*:
6933
 
6934
  A flush on a `basic_osyncstream` does not flush immediately:
@@ -7038,18 +8101,20 @@ can be thought of as a raw pointer to a file. If the file pointed to
7038
  does not exist, the symbolic link is said to be a “dangling” symbolic
7039
  link. — *end note*]
7040
 
7041
  ### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
7042
 
 
 
7043
  Conformance is specified in terms of behavior. Ideal behavior is not
7044
  always implementable, so the conformance subclauses take that into
7045
  account.
7046
 
7047
  #### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
7048
 
7049
- Some behavior is specified by reference to POSIX [[fs.norm.ref]]. How
7050
- such behavior is actually implemented is unspecified.
7051
 
7052
  [*Note 1*: This constitutes an “as if” rule allowing implementations to
7053
  call native operating system or other APIs. — *end note*]
7054
 
7055
  Implementations should provide such behavior as it is defined by POSIX.
@@ -7088,26 +8153,20 @@ system.
7088
  #### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
7089
 
7090
  A *file system race* is the condition that occurs when multiple threads,
7091
  processes, or computers interleave access and modification of the same
7092
  object within a file system. Behavior is undefined if calls to functions
7093
- provided by subclause  [[fs.race.behavior]] introduce a file system
7094
- race.
7095
 
7096
  If the possibility of a file system race would make it unreliable for a
7097
  program to test for a precondition before calling a function described
7098
  herein, *Preconditions:* is not specified for the function.
7099
 
7100
  [*Note 1*: As a design practice, preconditions are not specified when
7101
  it is unreasonable for a program to detect them prior to calling the
7102
  function. — *end note*]
7103
 
7104
- ### Normative references <a id="fs.norm.ref">[[fs.norm.ref]]</a>
7105
-
7106
- Subclause  [[filesystems]] mentions commercially available operating
7107
- systems for purposes of exposition.[^41]
7108
-
7109
  ### Requirements <a id="fs.req">[[fs.req]]</a>
7110
 
7111
  Throughout subclause  [[filesystems]], `char`, `wchar_t`, `char8_t`,
7112
  `char16_t`, and `char32_t` are collectively called *encoded character
7113
  types*.
@@ -7124,17 +8183,11 @@ value type that is one of the encoded character types.
7124
  character set and encoding. Since `signed char` and `unsigned char` have
7125
  no implied character set and encoding, they are not included as
7126
  permitted types. — *end note*]
7127
 
7128
  Template parameters named `Allocator` shall meet the *Cpp17Allocator*
7129
- requirements ([[cpp17.allocator]]).
7130
-
7131
- #### Namespaces and headers <a id="fs.req.namespace">[[fs.req.namespace]]</a>
7132
-
7133
- Unless otherwise specified, references to entities described in
7134
- subclause  [[filesystems]] are assumed to be qualified with
7135
- `::std::filesystem::`.
7136
 
7137
  ### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
7138
 
7139
  ``` cpp
7140
  #include <compare> // see [compare.syn]
@@ -7156,18 +8209,18 @@ namespace std::filesystem {
7156
  // [fs.class.directory.iterator], directory iterators
7157
  class directory_iterator;
7158
 
7159
  // [fs.dir.itr.nonmembers], range access for directory iterators
7160
  directory_iterator begin(directory_iterator iter) noexcept;
7161
- directory_iterator end(const directory_iterator&) noexcept;
7162
 
7163
  // [fs.class.rec.dir.itr], recursive directory iterators
7164
  class recursive_directory_iterator;
7165
 
7166
  // [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
7167
  recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
7168
- recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
7169
 
7170
  // [fs.class.file.status], file status
7171
  class file_status;
7172
 
7173
  struct space_info {
@@ -7333,10 +8386,28 @@ namespace std::filesystem {
7333
  path temp_directory_path(error_code& ec);
7334
 
7335
  path weakly_canonical(const path& p);
7336
  path weakly_canonical(const path& p, error_code& ec);
7337
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7338
  ```
7339
 
7340
  Implementations should ensure that the resolution and range of
7341
  `file_time_type` reflect the operating system dependent resolution and
7342
  range of file time values.
@@ -7387,10 +8458,12 @@ follows, unless otherwise specified:
7387
  appropriate for the specific operating system dependent error.
7388
  Otherwise, `clear()` is called on the `error_code&` argument.
7389
 
7390
  ### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
7391
 
 
 
7392
  An object of class `path` represents a path and contains a pathname.
7393
  Such an object is concerned only with the lexical and syntactic aspects
7394
  of a path. The path does not necessarily exist in external storage, and
7395
  the pathname is not necessarily valid for the current operating system
7396
  or for a particular file system.
@@ -7412,22 +8485,22 @@ elements of a path that determine if it is absolute are operating system
7412
  dependent. A *relative path* is a path that is not absolute, and as
7413
  such, only unambiguously identifies the location of a file when resolved
7414
  relative to an implied starting location. The elements of a path that
7415
  determine if it is relative are operating system dependent.
7416
 
7417
- [*Note 2*: Pathnames “.” and “..” are relative paths. — *end note*]
7418
 
7419
  A *pathname* is a character string that represents the name of a path.
7420
  Pathnames are formatted according to the generic pathname format grammar
7421
  [[fs.path.generic]] or according to an operating system dependent
7422
  *native pathname format* accepted by the host operating system.
7423
 
7424
  *Pathname resolution* is the operating system dependent mechanism for
7425
  resolving a pathname to a particular file in a file hierarchy. There may
7426
  be multiple pathnames that resolve to the same file.
7427
 
7428
- [*Example 1*: POSIX specifies the mechanism in section 4.11, Pathname
7429
  resolution. — *end example*]
7430
 
7431
  ``` cpp
7432
  namespace std::filesystem {
7433
  class path {
@@ -7645,13 +8718,13 @@ consisting solely of one and two period characters respectively, have
7645
  special meaning. The following characteristics of filenames are
7646
  operating system dependent:
7647
 
7648
  - The permitted characters. \[*Example 1*: Some operating systems
7649
  prohibit the ASCII control characters (0x00 – 0x1F) in
7650
- filenames. — *end example*] \[*Note 1*: For wide portability, users
7651
- may wish to limit *filename* characters to the POSIX Portable Filename
7652
- Character Set:
7653
  `A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
7654
  `a b c d e f g h i j k l m n o p q r s t u v w x y z`
7655
  `0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
7656
  - The maximum permitted length.
7657
  - Filenames that are not permitted.
@@ -7676,11 +8749,11 @@ A *root-name* identifies the starting location for pathname resolution
7676
  required.
7677
 
7678
  [*Note 2*: Many operating systems define a name beginning with two
7679
  *directory-separator* characters as a *root-name* that identifies
7680
  network or other resource locations. Some operating systems define a
7681
- single letter followed by a colon as a drive specifier a *root-name*
7682
  identifying a specific device such as a disk drive. — *end note*]
7683
 
7684
  If a *root-name* is otherwise ambiguous, the possibility with the
7685
  longest sequence of characters is chosen.
7686
 
@@ -7692,11 +8765,11 @@ longest sequence of characters is chosen.
7692
 
7693
  1. If the path is empty, stop.
7694
  2. Replace each slash character in the *root-name* with a
7695
  *preferred-separator*.
7696
  3. Replace each *directory-separator* with a *preferred-separator*.
7697
- \[*Note 4*: The generic pathname grammar [[fs.path.generic]] defines
7698
  *directory-separator* as one or more slashes and
7699
  *preferred-separator*s. — *end note*]
7700
  4. Remove each dot filename and any immediately following
7701
  *directory-separator*.
7702
  5. As long as any appear, remove a non-dot-dot filename immediately
@@ -7736,11 +8809,11 @@ path using either a pathname in the generic format [[fs.path.generic]]
7736
  or a pathname in the native format [[fs.class.path]]. Such an argument
7737
  is taken to be in the generic format if and only if it matches the
7738
  generic format and is not acceptable to the operating system as a native
7739
  path.
7740
 
7741
- [*Note 2*: Some operating systems may have no unambiguous way to
7742
  distinguish between native format and generic format arguments. This is
7743
  by design as it simplifies use for operating systems that do not require
7744
  disambiguation. An implementation for an operating system where
7745
  disambiguation is required is permitted to distinguish between the
7746
  formats. — *end note*]
@@ -7759,11 +8832,11 @@ differently from paths for directories, the path shall be treated as a
7759
  directory path if its last element is a *directory-separator*, otherwise
7760
  it shall be treated as a path to a regular file.
7761
 
7762
  [*Note 4*: A path stores a native format pathname
7763
  [[fs.path.native.obs]] and acts as if it also stores a generic format
7764
- pathname, related as given below. The implementation may generate the
7765
  generic format pathname based on the native format pathname (and
7766
  possibly other information) when requested. — *end note*]
7767
 
7768
  When a path is constructed from or is assigned a single representation
7769
  separate from any path, the other representation is selected by the
@@ -7781,11 +8854,11 @@ the result of converting *p*. — *end note*]
7781
 
7782
  The *native encoding* of an ordinary character string is the operating
7783
  system dependent current encoding for pathnames [[fs.class.path]]. The
7784
  *native encoding* for wide character strings is the
7785
  implementation-defined execution wide-character set encoding
7786
- [[lex.charset]].
7787
 
7788
  For member function arguments that take character sequences representing
7789
  paths and for member functions returning strings, value type and
7790
  encoding conversion is performed if the value type of the argument or
7791
  return value differs from `path::value_type`. For the argument or return
@@ -7799,12 +8872,12 @@ determined by its value type:
7799
  return values is performed. For Windows-based operating systems, the
7800
  native ordinary encoding is determined by calling a Windows API
7801
  function. — *end note*] \[*Note 7*: This results in behavior
7802
  identical to other C and C++ standard library functions that perform
7803
  file operations using ordinary character strings to identify paths.
7804
- Changing this behavior would be surprising and error
7805
- prone. — *end note*]
7806
  - `wchar_t`: The encoding is the native wide encoding. The method of
7807
  conversion is unspecified. \[*Note 8*: For Windows-based operating
7808
  systems `path::value_type` is `wchar_t` so no conversion from
7809
  `wchar_t` value type arguments or to `wchar_t` value type return
7810
  values is performed. — *end note*]
@@ -7848,11 +8921,11 @@ participate in overload resolution unless `Source` denotes a type other
7848
  than `path`, and either
7849
 
7850
  - `Source` is a specialization of `basic_string` or `basic_string_view`,
7851
  or
7852
  - the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
7853
- valid and denotes a possibly `const` encoded character type
7854
  [[temp.deduct]].
7855
 
7856
  [*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
7857
  above and their encodings convert to `path::value_type` and its
7858
  encoding. — *end note*]
@@ -8087,12 +9160,12 @@ template<class Source>
8087
  ```
8088
 
8089
  *Effects:* Appends `path(x).native()` to the pathname in the native
8090
  format.
8091
 
8092
- [*Note 2*: This directly manipulates the value of `native()` and may
8093
- not be portable between operating systems. — *end note*]
8094
 
8095
  *Returns:* `*this`.
8096
 
8097
  ``` cpp
8098
  path& operator+=(value_type x);
@@ -8241,14 +9314,10 @@ const value_type* c_str() const noexcept;
8241
  operator string_type() const;
8242
  ```
8243
 
8244
  *Returns:* `native()`.
8245
 
8246
- [*Note 3*: Conversion to `string_type` is provided so that an object of
8247
- class `path` can be given as an argument to existing standard library
8248
- file stream constructors and open functions. — *end note*]
8249
-
8250
  ``` cpp
8251
  template<class EcharT, class traits = char_traits<EcharT>,
8252
  class Allocator = allocator<EcharT>>
8253
  basic_string<EcharT, traits, Allocator>
8254
  string(const Allocator& a = Allocator()) const;
@@ -8448,17 +9517,17 @@ path(".bar").extension(); // yields "" and stem() is ".bar"
8448
  path("..bar").extension(); // yields ".bar" and stem() is "."
8449
  ```
8450
 
8451
  — *end example*]
8452
 
8453
- [*Note 4*: The period is included in the return value so that it is
8454
  possible to distinguish between no extension and an empty
8455
  extension. — *end note*]
8456
 
8457
- [*Note 5*: On non-POSIX operating systems, for a path `p`, it may not
8458
- be the case that `p.stem() + p.extension() == p.filename()`, even though
8459
- the generic format pathnames are the same. — *end note*]
8460
 
8461
  ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
8462
 
8463
  ``` cpp
8464
  [[nodiscard]] bool empty() const noexcept;
@@ -8557,25 +9626,21 @@ slashes, but that does not affect `path` equality.
8557
 
8558
  ``` cpp
8559
  path lexically_relative(const path& base) const;
8560
  ```
8561
 
8562
- *Returns:* `*this` made relative to `base`. Does not
8563
- resolve [[fs.class.path]] symlinks. Does not first
8564
- normalize [[fs.path.generic]] `*this` or `base`.
8565
-
8566
  *Effects:* If:
8567
 
8568
  - `root_name() != base.root_name()` is `true`, or
8569
  - `is_absolute() != base.is_absolute()` is `true`, or
8570
  - `!has_root_directory() && base.has_root_directory()` is `true`, or
8571
  - any *filename* in `relative_path()` or `base.relative_path()` can be
8572
  interpreted as a *root-name*,
8573
 
8574
  returns `path()`.
8575
 
8576
- [*Note 6*: On a POSIX implementation, no *filename* in a
8577
  *relative-path* is acceptable as a *root-name*. — *end note*]
8578
 
8579
  Determines the first mismatched element of `*this` and `base` as if by:
8580
 
8581
  ``` cpp
@@ -8593,10 +9658,14 @@ Then,
8593
  - returns an object of class `path` that is default-constructed,
8594
  followed by
8595
  - application of `operator/=(path(".."))` `n` times, and then
8596
  - application of `operator/=` for each element in \[`a`, `end()`).
8597
 
 
 
 
 
8598
  [*Example 11*:
8599
 
8600
  ``` cpp
8601
  assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
8602
  assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
@@ -8610,28 +9679,28 @@ The above assertions will succeed. On Windows, the returned path’s
8610
  *directory-separator* characters will be backslashes rather than
8611
  slashes, but that does not affect `path` equality.
8612
 
8613
  — *end example*]
8614
 
8615
- [*Note 7*: If symlink following semantics are desired, use the
8616
  operational function `relative()`. — *end note*]
8617
 
8618
- [*Note 8*: If normalization [[fs.path.generic]] is needed to ensure
8619
  consistent matching of elements, apply `lexically_normal()` to `*this`,
8620
  `base`, or both. — *end note*]
8621
 
8622
  ``` cpp
8623
  path lexically_proximate(const path& base) const;
8624
  ```
8625
 
8626
  *Returns:* If the value of `lexically_relative(base)` is not an empty
8627
  path, return it. Otherwise return `*this`.
8628
 
8629
- [*Note 9*: If symlink following semantics are desired, use the
8630
  operational function `proximate()`. — *end note*]
8631
 
8632
- [*Note 10*: If normalization [[fs.path.generic]] is needed to ensure
8633
  consistent matching of elements, apply `lexically_normal()` to `*this`,
8634
  `base`, or both. — *end note*]
8635
 
8636
  #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
8637
 
@@ -8736,14 +9805,10 @@ Path equality and path equivalence have different semantics.
8736
  - Equivalence is determined by the `equivalent()` non-member function,
8737
  which determines if two paths resolve [[fs.class.path]] to the same
8738
  file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
8739
  `true` when both paths resolve to the same file. — *end example*]
8740
 
8741
- Programmers wishing to determine if two paths are “the same” must decide
8742
- if “the same” means “the same representation” or “resolve to the same
8743
- actual file”, and choose the appropriate function accordingly.
8744
-
8745
  — *end note*]
8746
 
8747
  ``` cpp
8748
  friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
8749
  ```
@@ -8754,12 +9819,24 @@ friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
8754
  friend path operator/(const path& lhs, const path& rhs);
8755
  ```
8756
 
8757
  *Effects:* Equivalent to: `return path(lhs) /= rhs;`
8758
 
 
 
 
 
 
 
 
 
 
 
8759
  ### Class `filesystem_error` <a id="fs.class.filesystem.error">[[fs.class.filesystem.error]]</a>
8760
 
 
 
8761
  ``` cpp
8762
  namespace std::filesystem {
8763
  class filesystem_error : public system_error {
8764
  public:
8765
  filesystem_error(const string& what_arg, error_code ec);
@@ -8845,22 +9922,41 @@ and `path2` in the native format in the returned string.
8845
  #### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
8846
 
8847
  This enum specifies constants used to identify the format of the
8848
  character sequence, with the meanings listed in [[fs.enum.path.format]].
8849
 
8850
- [*Note 1*: For POSIX-based systems, native and generic formats are
8851
- equivalent and the character sequence should always be interpreted in
8852
- the same way. — *end note*]
 
 
 
 
 
8853
 
8854
  #### Enum class `file_type` <a id="fs.enum.file.type">[[fs.enum.file.type]]</a>
8855
 
8856
  This enum class specifies constants used to identify file types, with
8857
  the meanings listed in [[fs.enum.file.type]]. The values of the
8858
  constants are distinct.
8859
 
8860
- [*Note 1*: The file not being found is not considered an error while
8861
- determining the type of a file. — *end note*]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8862
 
8863
  #### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
8864
 
8865
  The `enum class` type `copy_options` is a bitmask type [[bitmask.types]]
8866
  that specifies bitmask constants used to control the semantics of copy
@@ -8871,16 +9967,16 @@ exposition; implementations shall provide only a single definition.
8871
  Every other constant in the table represents a distinct bitmask element.
8872
 
8873
  **Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
8874
 
8875
  | Constant | Meaning |
8876
- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
8877
  | `none` | (Default) Error; file already exists. |
8878
  | `skip_existing` | Do not overwrite existing file, do not report an error. |
8879
  | `overwrite_existing` | Overwrite the existing file. |
8880
- | `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} |
8881
- | `recursive` | Recursively copy sub-directories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links} |
8882
  | `copy_symlinks` | Copy symbolic links as symbolic links rather than copying the files that they point to. |
8883
  | `skip_symlinks` | Ignore symbolic links. \ohdrx{2}{Option group controlling `copy` function effects for choosing the form of copying} |
8884
  | `directories_only` | Copy directory structure only, do not copy non-directory files. |
8885
  | `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. |
8886
  | `create_hard_links` | Make hard links instead of copies of files. |
@@ -8929,12 +10025,12 @@ permissions operations, with the meanings listed in
8929
  **Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
8930
 
8931
  | Name | Meaning |
8932
  | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
8933
  | `replace` | `permissions` shall replace the file's permission bits with `perm` |
8934
- | `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{OR} of `perm` and the file's current permission bits. |
8935
- | `remove` | `permissions` shall replace the file's permission bits with the bitwise \logop{AND} of the complement of `perm` and the file's current permission bits. |
8936
  | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
8937
 
8938
 
8939
  #### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
8940
 
@@ -8953,10 +10049,12 @@ every other constant in the table represents a distinct bitmask element.
8953
  | `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
8954
 
8955
 
8956
  ### Class `file_status` <a id="fs.class.file.status">[[fs.class.file.status]]</a>
8957
 
 
 
8958
  ``` cpp
8959
  namespace std::filesystem {
8960
  class file_status {
8961
  public:
8962
  // [fs.file.status.cons], constructors and destructor
@@ -9025,10 +10123,12 @@ void permissions(perms prms) noexcept;
9025
 
9026
  *Ensures:* `permissions() == prms`.
9027
 
9028
  ### Class `directory_entry` <a id="fs.class.directory.entry">[[fs.class.directory.entry]]</a>
9029
 
 
 
9030
  ``` cpp
9031
  namespace std::filesystem {
9032
  class directory_entry {
9033
  public:
9034
  // [fs.dir.entry.cons], constructors and destructor
@@ -9084,10 +10184,15 @@ namespace std::filesystem {
9084
  file_status symlink_status(error_code& ec) const noexcept;
9085
 
9086
  bool operator==(const directory_entry& rhs) const noexcept;
9087
  strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
9088
 
 
 
 
 
 
9089
  private:
9090
  filesystem::path pathobject; // exposition only
9091
  friend class directory_iterator; // exposition only
9092
  };
9093
  }
@@ -9190,13 +10295,12 @@ unspecified.
9190
 
9191
  *Throws:* As specified in  [[fs.err.report]].
9192
 
9193
  [*Note 1*: Implementations of `directory_iterator`
9194
  [[fs.class.directory.iterator]] are prohibited from directly or
9195
- indirectly calling the `refresh` function since it must access the
9196
- external file system, and the objective of caching is to avoid
9197
- unnecessary file system accesses. — *end note*]
9198
 
9199
  #### Observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
9200
 
9201
  Unqualified function names in the *Returns:* elements of the
9202
  `directory_entry` observers described below refer to members of the
@@ -9361,18 +10465,30 @@ bool operator==(const directory_entry& rhs) const noexcept;
9361
  strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
9362
  ```
9363
 
9364
  *Returns:* `pathobject <=> rhs.pathobject`.
9365
 
 
 
 
 
 
 
 
 
 
 
9366
  ### Class `directory_iterator` <a id="fs.class.directory.iterator">[[fs.class.directory.iterator]]</a>
9367
 
 
 
9368
  An object of type `directory_iterator` provides an iterator for a
9369
  sequence of `directory_entry` elements representing the path and any
9370
  cached attribute values [[fs.class.directory.entry]] for each file in a
9371
  directory or in an *implementation-defined* directory-like file type.
9372
 
9373
- [*Note 1*: For iteration into sub-directories, see class
9374
  `recursive_directory_iterator` [[fs.class.rec.dir.itr]]. — *end note*]
9375
 
9376
  ``` cpp
9377
  namespace std::filesystem {
9378
  class directory_iterator {
@@ -9400,10 +10516,14 @@ namespace std::filesystem {
9400
  const directory_entry& operator*() const;
9401
  const directory_entry* operator->() const;
9402
  directory_iterator& operator++();
9403
  directory_iterator& increment(error_code& ec);
9404
 
 
 
 
 
9405
  // other members as required by [input.iterators], input iterators
9406
  };
9407
  }
9408
  ```
9409
 
@@ -9422,12 +10542,12 @@ Two end iterators are always equal. An end iterator shall not be equal
9422
  to a non-end iterator.
9423
 
9424
  The result of calling the `path()` member of the `directory_entry`
9425
  object obtained by dereferencing a `directory_iterator` is a reference
9426
  to a `path` object composed of the directory argument from which the
9427
- iterator was constructed with filename of the directory entry appended
9428
- as if by `operator/=`.
9429
 
9430
  Directory iteration shall not yield directory entries for the current
9431
  (dot) and parent (dot-dot) directories.
9432
 
9433
  The order of directory entries obtained by dereferencing successive
@@ -9442,21 +10562,21 @@ call any `directory_entry` `refresh` function.
9442
  [*Note 2*: The exact mechanism for storing cached attribute values is
9443
  not exposed to users. For exposition, class `directory_iterator` is
9444
  shown in [[fs.class.directory.entry]] as a friend of class
9445
  `directory_entry`. — *end note*]
9446
 
9447
- [*Note 3*: Programs performing directory iteration may wish to test if
9448
- the path obtained by dereferencing a directory iterator actually exists.
9449
- It could be a symbolic link to a non-existent file. Programs recursively
9450
- walking directory trees for purposes of removing and renaming entries
9451
- may wish to avoid following symbolic links. — *end note*]
9452
 
9453
  [*Note 4*: If a file is removed from or added to a directory after the
9454
  construction of a `directory_iterator` for the directory, it is
9455
  unspecified whether or not subsequently incrementing the iterator will
9456
  ever result in an iterator referencing the removed or added directory
9457
- entry. See POSIX `readdir_r`. — *end note*]
9458
 
9459
  #### Members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
9460
 
9461
  ``` cpp
9462
  directory_iterator() noexcept;
@@ -9530,21 +10650,23 @@ directory_iterator begin(directory_iterator iter) noexcept;
9530
  ```
9531
 
9532
  *Returns:* `iter`.
9533
 
9534
  ``` cpp
9535
- directory_iterator end(const directory_iterator&) noexcept;
9536
  ```
9537
 
9538
  *Returns:* `directory_iterator()`.
9539
 
9540
  ### Class `recursive_directory_iterator` <a id="fs.class.rec.dir.itr">[[fs.class.rec.dir.itr]]</a>
9541
 
 
 
9542
  An object of type `recursive_directory_iterator` provides an iterator
9543
  for a sequence of `directory_entry` elements representing the files in a
9544
  directory or in an *implementation-defined* directory-like file type,
9545
- and its sub-directories.
9546
 
9547
  ``` cpp
9548
  namespace std::filesystem {
9549
  class recursive_directory_iterator {
9550
  public:
@@ -9584,10 +10706,14 @@ namespace std::filesystem {
9584
 
9585
  void pop();
9586
  void pop(error_code& ec);
9587
  void disable_recursion_pending();
9588
 
 
 
 
 
9589
  // other members as required by [input.iterators], input iterators
9590
  };
9591
  }
9592
  ```
9593
 
@@ -9597,11 +10723,12 @@ results in undefined behavior.
9597
 
9598
  The behavior of a `recursive_directory_iterator` is the same as a
9599
  `directory_iterator` unless otherwise specified.
9600
 
9601
  [*Note 1*: If the directory structure being iterated over contains
9602
- cycles then the end iterator may be unreachable. — *end note*]
 
9603
 
9604
  #### Members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
9605
 
9606
  ``` cpp
9607
  recursive_directory_iterator() noexcept;
@@ -9632,13 +10759,13 @@ error.
9632
  `directory_options` argument, otherwise
9633
  `options() == directory_options::none`.
9634
 
9635
  *Throws:* As specified in  [[fs.err.report]].
9636
 
9637
- [*Note 1*: To iterate over the current directory, use
9638
- `recursive_directory_iterator(".")` rather than
9639
- `recursive_directory_iterator("")`. — *end note*]
9640
 
9641
  [*Note 2*: By default, `recursive_directory_iterator` does not follow
9642
  directory symlinks. To follow directory symlinks, specify `options` as
9643
  `directory_options::follow_directory_symlink`. — *end note*]
9644
 
@@ -9775,40 +10902,42 @@ void disable_recursion_pending();
9775
  recursion into a directory. — *end note*]
9776
 
9777
  #### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
9778
 
9779
  These functions enable use of `recursive_directory_iterator` with
9780
- range-based for statements.
9781
 
9782
  ``` cpp
9783
  recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
9784
  ```
9785
 
9786
  *Returns:* `iter`.
9787
 
9788
  ``` cpp
9789
- recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
9790
  ```
9791
 
9792
  *Returns:* `recursive_directory_iterator()`.
9793
 
9794
  ### Filesystem operation functions <a id="fs.op.funcs">[[fs.op.funcs]]</a>
9795
 
 
 
9796
  Filesystem operation functions query or modify files, including
9797
  directories, in external storage.
9798
 
9799
  [*Note 1*: Because hardware failures, network failures, file system
9800
  races [[fs.race.behavior]], and many other kinds of errors occur
9801
- frequently in file system operations, users should be aware that any
9802
- filesystem operation function, no matter how apparently innocuous, may
9803
- encounter an error; see  [[fs.err.report]]. — *end note*]
9804
 
9805
  #### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
9806
 
9807
  ``` cpp
9808
- path absolute(const path& p);
9809
- path absolute(const path& p, error_code& ec);
9810
  ```
9811
 
9812
  *Effects:* Composes an absolute path referencing the same file system
9813
  location as `p` according to the operating system [[fs.conform.os]].
9814
 
@@ -9818,12 +10947,12 @@ location as `p` according to the operating system [[fs.conform.os]].
9818
  [*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
9819
  unless an error occurs. — *end note*]
9820
 
9821
  *Throws:* As specified in  [[fs.err.report]].
9822
 
9823
- [*Note 2*: To resolve symlinks, or perform other sanitization which
9824
- might require queries to secondary storage, such as hard disks, consider
9825
  `canonical` [[fs.op.canonical]]. — *end note*]
9826
 
9827
  [*Note 3*: Implementations are strongly encouraged to not query
9828
  secondary storage, and not consider `!exists(p)` an
9829
  error. — *end note*]
@@ -9834,12 +10963,12 @@ simply `current_path()/p`. For Windows-based operating systems,
9834
  `GetFullPathNameW`. — *end example*]
9835
 
9836
  #### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
9837
 
9838
  ``` cpp
9839
- path canonical(const path& p);
9840
- path canonical(const path& p, error_code& ec);
9841
  ```
9842
 
9843
  *Effects:* Converts `p` to an absolute path that has no symbolic link,
9844
  dot, or dot-dot elements in its pathname in the generic format.
9845
 
@@ -9852,24 +10981,24 @@ error occurs.
9852
  *Remarks:* `!exists(p)` is an error.
9853
 
9854
  #### Copy <a id="fs.op.copy">[[fs.op.copy]]</a>
9855
 
9856
  ``` cpp
9857
- void copy(const path& from, const path& to);
9858
  ```
9859
 
9860
  *Effects:* Equivalent to `copy(from, to, copy_options::none)`.
9861
 
9862
  ``` cpp
9863
- void copy(const path& from, const path& to, error_code& ec);
9864
  ```
9865
 
9866
  *Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
9867
 
9868
  ``` cpp
9869
- void copy(const path& from, const path& to, copy_options options);
9870
- void copy(const path& from, const path& to, copy_options options,
9871
  error_code& ec);
9872
  ```
9873
 
9874
  *Preconditions:* At most one element from each option
9875
  group [[fs.enum.copy.opts]] is set in `options`.
@@ -10006,22 +11135,22 @@ would result in:
10006
  — *end example*]
10007
 
10008
  #### Copy file <a id="fs.op.copy.file">[[fs.op.copy.file]]</a>
10009
 
10010
  ``` cpp
10011
- bool copy_file(const path& from, const path& to);
10012
- bool copy_file(const path& from, const path& to, error_code& ec);
10013
  ```
10014
 
10015
  *Returns:* `copy_file(from, to, copy_options::none)` or
10016
  `copy_file(from, to, copy_options::none, ec)`, respectively.
10017
 
10018
  *Throws:* As specified in  [[fs.err.report]].
10019
 
10020
  ``` cpp
10021
- bool copy_file(const path& from, const path& to, copy_options options);
10022
- bool copy_file(const path& from, const path& to, copy_options options,
10023
  error_code& ec);
10024
  ```
10025
 
10026
  *Preconditions:* At most one element from each option
10027
  group [[fs.enum.copy.opts]] is set in `options`.
@@ -10056,12 +11185,12 @@ signature with argument `ec` returns `false` if an error occurs.
10056
  *Complexity:* At most one direct or indirect invocation of `status(to)`.
10057
 
10058
  #### Copy symlink <a id="fs.op.copy.symlink">[[fs.op.copy.symlink]]</a>
10059
 
10060
  ``` cpp
10061
- void copy_symlink(const path& existing_symlink, const path& new_symlink);
10062
- void copy_symlink(const path& existing_symlink, const path& new_symlink,
10063
  error_code& ec) noexcept;
10064
  ```
10065
 
10066
  *Effects:* Equivalent to
10067
  *`function`*`(read_symlink(existing_symlink), new_symlink)` or
@@ -10072,12 +11201,12 @@ respectively, where in each case *`function`* is `create_symlink` or
10072
  *Throws:* As specified in  [[fs.err.report]].
10073
 
10074
  #### Create directories <a id="fs.op.create.directories">[[fs.op.create.directories]]</a>
10075
 
10076
  ``` cpp
10077
- bool create_directories(const path& p);
10078
- bool create_directories(const path& p, error_code& ec);
10079
  ```
10080
 
10081
  *Effects:* Calls `create_directory()` for each element of `p` that does
10082
  not exist.
10083
 
@@ -10089,12 +11218,12 @@ resolves to, otherwise `false`.
10089
  *Complexity:* 𝑂(n) where *n* is the number of elements of `p`.
10090
 
10091
  #### Create directory <a id="fs.op.create.directory">[[fs.op.create.directory]]</a>
10092
 
10093
  ``` cpp
10094
- bool create_directory(const path& p);
10095
- bool create_directory(const path& p, error_code& ec) noexcept;
10096
  ```
10097
 
10098
  *Effects:* Creates the directory `p` resolves to, as if by POSIX `mkdir`
10099
  with a second argument of `static_cast<int>(perms::all)`. If `mkdir`
10100
  fails because `p` resolves to an existing directory, no error is
@@ -10103,12 +11232,12 @@ reported. Otherwise on failure an error is reported.
10103
  *Returns:* `true` if a new directory was created, otherwise `false`.
10104
 
10105
  *Throws:* As specified in  [[fs.err.report]].
10106
 
10107
  ``` cpp
10108
- bool create_directory(const path& p, const path& existing_p);
10109
- bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
10110
  ```
10111
 
10112
  *Effects:* Creates the directory `p` resolves to, with attributes copied
10113
  from directory `existing_p`. The set of attributes copied is operating
10114
  system dependent. If `mkdir` fails because `p` resolves to an existing
@@ -10128,12 +11257,12 @@ from directory `existing_p`, otherwise `false`.
10128
  *Throws:* As specified in  [[fs.err.report]].
10129
 
10130
  #### Create directory symlink <a id="fs.op.create.dir.symlk">[[fs.op.create.dir.symlk]]</a>
10131
 
10132
  ``` cpp
10133
- void create_directory_symlink(const path& to, const path& new_symlink);
10134
- void create_directory_symlink(const path& to, const path& new_symlink,
10135
  error_code& ec) noexcept;
10136
  ```
10137
 
10138
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
10139
 
@@ -10141,24 +11270,24 @@ void create_directory_symlink(const path& to, const path& new_symlink,
10141
  an unspecified representation of `to`.
10142
 
10143
  *Throws:* As specified in  [[fs.err.report]].
10144
 
10145
  [*Note 1*: Some operating systems require symlink creation to identify
10146
- that the link is to a directory. Portable code should use
10147
- `create_directory_symlink()` to create directory symlinks rather than
10148
- `create_symlink()` — *end note*]
10149
 
10150
  [*Note 2*: Some operating systems do not support symbolic links at all
10151
  or support them only for regular files. Some file systems (such as the
10152
  FAT file system) do not support symbolic links regardless of the
10153
  operating system. — *end note*]
10154
 
10155
  #### Create hard link <a id="fs.op.create.hard.lk">[[fs.op.create.hard.lk]]</a>
10156
 
10157
  ``` cpp
10158
- void create_hard_link(const path& to, const path& new_hard_link);
10159
- void create_hard_link(const path& to, const path& new_hard_link,
10160
  error_code& ec) noexcept;
10161
  ```
10162
 
10163
  *Effects:* Establishes the postcondition, as if by POSIX `link()`.
10164
 
@@ -10176,12 +11305,12 @@ system. Some file systems limit the number of links per
10176
  file. — *end note*]
10177
 
10178
  #### Create symlink <a id="fs.op.create.symlink">[[fs.op.create.symlink]]</a>
10179
 
10180
  ``` cpp
10181
- void create_symlink(const path& to, const path& new_symlink);
10182
- void create_symlink(const path& to, const path& new_symlink,
10183
  error_code& ec) noexcept;
10184
  ```
10185
 
10186
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
10187
 
@@ -10196,12 +11325,12 @@ FAT file system) do not support symbolic links regardless of the
10196
  operating system. — *end note*]
10197
 
10198
  #### Current path <a id="fs.op.current.path">[[fs.op.current.path]]</a>
10199
 
10200
  ``` cpp
10201
- path current_path();
10202
- path current_path(error_code& ec);
10203
  ```
10204
 
10205
  *Returns:* The absolute path of the current working directory, whose
10206
  pathname in the native format is obtained as if by POSIX `getcwd()`. The
10207
  signature with argument `ec` returns `path()` if an error occurs.
@@ -10215,61 +11344,61 @@ resolution for relative paths.
10215
  [*Note 1*: The `current_path()` name was chosen to emphasize that the
10216
  returned value is a path, not just a single directory
10217
  name. — *end note*]
10218
 
10219
  [*Note 2*: The current path as returned by many operating systems is a
10220
- dangerous global variable. It may be changed unexpectedly by third-party
10221
  or system library functions, or by another thread. — *end note*]
10222
 
10223
  ``` cpp
10224
- void current_path(const path& p);
10225
- void current_path(const path& p, error_code& ec) noexcept;
10226
  ```
10227
 
10228
  *Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
10229
 
10230
  *Ensures:* `equivalent(p, current_path())`.
10231
 
10232
  *Throws:* As specified in  [[fs.err.report]].
10233
 
10234
  [*Note 3*: The current path for many operating systems is a dangerous
10235
- global state. It may be changed unexpectedly by a third-party or system
10236
  library functions, or by another thread. — *end note*]
10237
 
10238
  #### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
10239
 
10240
  ``` cpp
10241
- bool equivalent(const path& p1, const path& p2);
10242
- bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
10243
  ```
10244
 
10245
- *Returns:* `true`, if `p1` and `p2` resolve to the same file system
10246
- entity, otherwise `false`. The signature with argument `ec` returns
10247
- `false` if an error occurs.
10248
-
10249
  Two paths are considered to resolve to the same file system entity if
10250
  two candidate entities reside on the same device at the same location.
10251
 
10252
  [*Note 1*: On POSIX platforms, this is determined as if by the values
10253
  of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
10254
  having equal `st_dev` values and equal `st_ino` values. — *end note*]
10255
 
 
 
 
 
 
 
10256
  *Remarks:* `!exists(p1) || !exists(p2)` is an error.
10257
 
10258
- *Throws:* As specified in  [[fs.err.report]].
10259
-
10260
  #### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
10261
 
10262
  ``` cpp
10263
- bool exists(file_status s) noexcept;
10264
  ```
10265
 
10266
  *Returns:* `status_known(s) && s.type() != file_type::not_found`.
10267
 
10268
  ``` cpp
10269
- bool exists(const path& p);
10270
- bool exists(const path& p, error_code& ec) noexcept;
10271
  ```
10272
 
10273
  Let `s` be a `file_status`, determined as if by `status(p)` or
10274
  `status(p, ec)`, respectively.
10275
 
@@ -10281,12 +11410,12 @@ Let `s` be a `file_status`, determined as if by `status(p)` or
10281
  *Throws:* As specified in  [[fs.err.report]].
10282
 
10283
  #### File size <a id="fs.op.file.size">[[fs.op.file.size]]</a>
10284
 
10285
  ``` cpp
10286
- uintmax_t file_size(const path& p);
10287
- uintmax_t file_size(const path& p, error_code& ec) noexcept;
10288
  ```
10289
 
10290
  *Effects:* If `exists(p)` is `false`, an error is
10291
  reported [[fs.err.report]].
10292
 
@@ -10303,30 +11432,30 @@ an error occurs.
10303
  *Throws:* As specified in  [[fs.err.report]].
10304
 
10305
  #### Hard link count <a id="fs.op.hard.lk.ct">[[fs.op.hard.lk.ct]]</a>
10306
 
10307
  ``` cpp
10308
- uintmax_t hard_link_count(const path& p);
10309
- uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
10310
  ```
10311
 
10312
  *Returns:* The number of hard links for `p`. The signature with argument
10313
  `ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
10314
 
10315
  *Throws:* As specified in  [[fs.err.report]].
10316
 
10317
  #### Is block file <a id="fs.op.is.block.file">[[fs.op.is.block.file]]</a>
10318
 
10319
  ``` cpp
10320
- bool is_block_file(file_status s) noexcept;
10321
  ```
10322
 
10323
  *Returns:* `s.type() == file_type::block`.
10324
 
10325
  ``` cpp
10326
- bool is_block_file(const path& p);
10327
- bool is_block_file(const path& p, error_code& ec) noexcept;
10328
  ```
10329
 
10330
  *Returns:* `is_block_file(status(p))` or `is_block_file(status(p, ec))`,
10331
  respectively. The signature with argument `ec` returns `false` if an
10332
  error occurs.
@@ -10334,18 +11463,18 @@ error occurs.
10334
  *Throws:* As specified in  [[fs.err.report]].
10335
 
10336
  #### Is character file <a id="fs.op.is.char.file">[[fs.op.is.char.file]]</a>
10337
 
10338
  ``` cpp
10339
- bool is_character_file(file_status s) noexcept;
10340
  ```
10341
 
10342
  *Returns:* `s.type() == file_type::character`.
10343
 
10344
  ``` cpp
10345
- bool is_character_file(const path& p);
10346
- bool is_character_file(const path& p, error_code& ec) noexcept;
10347
  ```
10348
 
10349
  *Returns:* `is_character_file(status(p))` or
10350
  `is_character_file(status(p, ec))`, respectively.
10351
  The signature with argument `ec` returns `false` if an error occurs.
@@ -10353,18 +11482,18 @@ The signature with argument `ec` returns `false` if an error occurs.
10353
  *Throws:* As specified in  [[fs.err.report]].
10354
 
10355
  #### Is directory <a id="fs.op.is.directory">[[fs.op.is.directory]]</a>
10356
 
10357
  ``` cpp
10358
- bool is_directory(file_status s) noexcept;
10359
  ```
10360
 
10361
  *Returns:* `s.type() == file_type::directory`.
10362
 
10363
  ``` cpp
10364
- bool is_directory(const path& p);
10365
- bool is_directory(const path& p, error_code& ec) noexcept;
10366
  ```
10367
 
10368
  *Returns:* `is_directory(status(p))` or `is_directory(status(p, ec))`,
10369
  respectively. The signature with argument `ec` returns `false` if an
10370
  error occurs.
@@ -10372,12 +11501,12 @@ error occurs.
10372
  *Throws:* As specified in  [[fs.err.report]].
10373
 
10374
  #### Is empty <a id="fs.op.is.empty">[[fs.op.is.empty]]</a>
10375
 
10376
  ``` cpp
10377
- bool is_empty(const path& p);
10378
- bool is_empty(const path& p, error_code& ec);
10379
  ```
10380
 
10381
  *Effects:*
10382
 
10383
  - Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
@@ -10400,18 +11529,18 @@ bool is_empty(const path& p, error_code& ec);
10400
  *Throws:* As specified in  [[fs.err.report]].
10401
 
10402
  #### Is fifo <a id="fs.op.is.fifo">[[fs.op.is.fifo]]</a>
10403
 
10404
  ``` cpp
10405
- bool is_fifo(file_status s) noexcept;
10406
  ```
10407
 
10408
  *Returns:* `s.type() == file_type::fifo`.
10409
 
10410
  ``` cpp
10411
- bool is_fifo(const path& p);
10412
- bool is_fifo(const path& p, error_code& ec) noexcept;
10413
  ```
10414
 
10415
  *Returns:* `is_fifo(status(p))` or `is_fifo(status(p, ec))`,
10416
  respectively. The signature with argument `ec` returns `false` if an
10417
  error occurs.
@@ -10419,19 +11548,19 @@ error occurs.
10419
  *Throws:* As specified in  [[fs.err.report]].
10420
 
10421
  #### Is other <a id="fs.op.is.other">[[fs.op.is.other]]</a>
10422
 
10423
  ``` cpp
10424
- bool is_other(file_status s) noexcept;
10425
  ```
10426
 
10427
  *Returns:*
10428
  `exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)`.
10429
 
10430
  ``` cpp
10431
- bool is_other(const path& p);
10432
- bool is_other(const path& p, error_code& ec) noexcept;
10433
  ```
10434
 
10435
  *Returns:* `is_other(status(p))` or `is_other(status(p, ec))`,
10436
  respectively. The signature with argument `ec` returns `false` if an
10437
  error occurs.
@@ -10439,26 +11568,26 @@ error occurs.
10439
  *Throws:* As specified in  [[fs.err.report]].
10440
 
10441
  #### Is regular file <a id="fs.op.is.regular.file">[[fs.op.is.regular.file]]</a>
10442
 
10443
  ``` cpp
10444
- bool is_regular_file(file_status s) noexcept;
10445
  ```
10446
 
10447
  *Returns:* `s.type() == file_type::regular`.
10448
 
10449
  ``` cpp
10450
- bool is_regular_file(const path& p);
10451
  ```
10452
 
10453
  *Returns:* `is_regular_file(status(p))`.
10454
 
10455
  *Throws:* `filesystem_error` if `status(p)` would throw
10456
  `filesystem_error`.
10457
 
10458
  ``` cpp
10459
- bool is_regular_file(const path& p, error_code& ec) noexcept;
10460
  ```
10461
 
10462
  *Effects:* Sets `ec` as if by `status(p, ec)`.
10463
 
10464
  [*Note 1*: `file_type::none`, `file_type::not_found` and
@@ -10469,18 +11598,18 @@ between cases, call the `status` function directly. — *end note*]
10469
  occurs.
10470
 
10471
  #### Is socket <a id="fs.op.is.socket">[[fs.op.is.socket]]</a>
10472
 
10473
  ``` cpp
10474
- bool is_socket(file_status s) noexcept;
10475
  ```
10476
 
10477
  *Returns:* `s.type() == file_type::socket`.
10478
 
10479
  ``` cpp
10480
- bool is_socket(const path& p);
10481
- bool is_socket(const path& p, error_code& ec) noexcept;
10482
  ```
10483
 
10484
  *Returns:* `is_socket(status(p))` or `is_socket(status(p, ec))`,
10485
  respectively. The signature with argument `ec` returns `false` if an
10486
  error occurs.
@@ -10488,18 +11617,18 @@ error occurs.
10488
  *Throws:* As specified in  [[fs.err.report]].
10489
 
10490
  #### Is symlink <a id="fs.op.is.symlink">[[fs.op.is.symlink]]</a>
10491
 
10492
  ``` cpp
10493
- bool is_symlink(file_status s) noexcept;
10494
  ```
10495
 
10496
  *Returns:* `s.type() == file_type::symlink`.
10497
 
10498
  ``` cpp
10499
- bool is_symlink(const path& p);
10500
- bool is_symlink(const path& p, error_code& ec) noexcept;
10501
  ```
10502
 
10503
  *Returns:* `is_symlink(symlink_status(p))` or
10504
  `is_symlink(symlink_status(p, ec))`, respectively. The signature with
10505
  argument `ec` returns `false` if an error occurs.
@@ -10507,74 +11636,74 @@ argument `ec` returns `false` if an error occurs.
10507
  *Throws:* As specified in  [[fs.err.report]].
10508
 
10509
  #### Last write time <a id="fs.op.last.write.time">[[fs.op.last.write.time]]</a>
10510
 
10511
  ``` cpp
10512
- file_time_type last_write_time(const path& p);
10513
- file_time_type last_write_time(const path& p, error_code& ec) noexcept;
10514
  ```
10515
 
10516
  *Returns:* The time of last data modification of `p`, determined as if
10517
  by the value of the POSIX `stat` class member `st_mtime` obtained as if
10518
  by POSIX `stat()`. The signature with argument `ec` returns
10519
  `file_time_type::min()` if an error occurs.
10520
 
10521
  *Throws:* As specified in  [[fs.err.report]].
10522
 
10523
  ``` cpp
10524
- void last_write_time(const path& p, file_time_type new_time);
10525
- void last_write_time(const path& p, file_time_type new_time,
10526
  error_code& ec) noexcept;
10527
  ```
10528
 
10529
  *Effects:* Sets the time of last data modification of the file resolved
10530
  to by `p` to `new_time`, as if by POSIX `futimens()`.
10531
 
10532
  *Throws:* As specified in  [[fs.err.report]].
10533
 
10534
  [*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
10535
- specified since it might not hold for file systems with coarse time
10536
- granularity. — *end note*]
10537
 
10538
  #### Permissions <a id="fs.op.permissions">[[fs.op.permissions]]</a>
10539
 
10540
  ``` cpp
10541
- void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
10542
- void permissions(const path& p, perms prms, error_code& ec) noexcept;
10543
- void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
10544
  ```
10545
 
10546
  *Preconditions:* Exactly one of the `perm_options` constants `replace`,
10547
  `add`, or `remove` is present in `opts`.
10548
 
10549
- *Remarks:* The second signature behaves as if it had an additional
10550
- parameter `perm_options` `opts` with an argument of
10551
- `perm_options::replace`.
10552
-
10553
  *Effects:* Applies the action specified by `opts` to the file `p`
10554
  resolves to, or to file `p` itself if `p` is a symbolic link and
10555
  `perm_options::nofollow` is set in `opts`. The action is applied as if
10556
  by POSIX `fchmodat()`.
10557
 
10558
  [*Note 1*: Conceptually permissions are viewed as bits, but the actual
10559
- implementation may use some other mechanism. — *end note*]
10560
 
10561
  *Throws:* As specified in  [[fs.err.report]].
10562
 
 
 
 
 
10563
  #### Proximate <a id="fs.op.proximate">[[fs.op.proximate]]</a>
10564
 
10565
  ``` cpp
10566
- path proximate(const path& p, error_code& ec);
10567
  ```
10568
 
10569
  *Returns:* `proximate(p, current_path(), ec)`.
10570
 
10571
  *Throws:* As specified in  [[fs.err.report]].
10572
 
10573
  ``` cpp
10574
- path proximate(const path& p, const path& base = current_path());
10575
- path proximate(const path& p, const path& base, error_code& ec);
10576
  ```
10577
 
10578
  *Returns:* For the first form:
10579
 
10580
  ``` cpp
@@ -10592,12 +11721,12 @@ or `path()` at the first error occurrence, if any.
10592
  *Throws:* As specified in  [[fs.err.report]].
10593
 
10594
  #### Read symlink <a id="fs.op.read.symlink">[[fs.op.read.symlink]]</a>
10595
 
10596
  ``` cpp
10597
- path read_symlink(const path& p);
10598
- path read_symlink(const path& p, error_code& ec);
10599
  ```
10600
 
10601
  *Returns:* If `p` resolves to a symbolic link, a `path` object
10602
  containing the contents of that symbolic link. The signature with
10603
  argument `ec` returns `path()` if an error occurs.
@@ -10608,20 +11737,20 @@ argument `ec` returns `path()` if an error occurs.
10608
  link. — *end note*]
10609
 
10610
  #### Relative <a id="fs.op.relative">[[fs.op.relative]]</a>
10611
 
10612
  ``` cpp
10613
- path relative(const path& p, error_code& ec);
10614
  ```
10615
 
10616
  *Returns:* `relative(p, current_path(), ec)`.
10617
 
10618
  *Throws:* As specified in  [[fs.err.report]].
10619
 
10620
  ``` cpp
10621
- path relative(const path& p, const path& base = current_path());
10622
- path relative(const path& p, const path& base, error_code& ec);
10623
  ```
10624
 
10625
  *Returns:* For the first form:
10626
 
10627
  ``` cpp
@@ -10639,12 +11768,12 @@ or `path()` at the first error occurrence, if any.
10639
  *Throws:* As specified in  [[fs.err.report]].
10640
 
10641
  #### Remove <a id="fs.op.remove">[[fs.op.remove]]</a>
10642
 
10643
  ``` cpp
10644
- bool remove(const path& p);
10645
- bool remove(const path& p, error_code& ec) noexcept;
10646
  ```
10647
 
10648
  *Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
10649
  as if by POSIX `remove()`.
10650
 
@@ -10659,12 +11788,12 @@ with argument `ec` returns `false` if an error occurs.
10659
  *Throws:* As specified in  [[fs.err.report]].
10660
 
10661
  #### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
10662
 
10663
  ``` cpp
10664
- uintmax_t remove_all(const path& p);
10665
- uintmax_t remove_all(const path& p, error_code& ec);
10666
  ```
10667
 
10668
  *Effects:* Recursively deletes the contents of `p` if it exists, then
10669
  deletes file `p` itself, as if by POSIX `remove()`.
10670
 
@@ -10679,25 +11808,25 @@ returns `static_cast< uintmax_t>(-1)` if an error occurs.
10679
  *Throws:* As specified in  [[fs.err.report]].
10680
 
10681
  #### Rename <a id="fs.op.rename">[[fs.op.rename]]</a>
10682
 
10683
  ``` cpp
10684
- void rename(const path& old_p, const path& new_p);
10685
- void rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
10686
  ```
10687
 
10688
  *Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
10689
 
10690
  [*Note 1*:
10691
 
10692
  - If `old_p` and `new_p` resolve to the same existing file, no action is
10693
  taken.
10694
- - Otherwise, the rename may include the following effects:
10695
  - if `new_p` resolves to an existing non-directory file, `new_p` is
10696
  removed; otherwise,
10697
  - if `new_p` resolves to an existing directory, `new_p` is removed if
10698
- empty on POSIX compliant operating systems but may be an error on
10699
  other operating systems.
10700
 
10701
  A symbolic link is itself renamed, rather than the file it resolves to.
10702
 
10703
  — *end note*]
@@ -10705,24 +11834,24 @@ A symbolic link is itself renamed, rather than the file it resolves to.
10705
  *Throws:* As specified in  [[fs.err.report]].
10706
 
10707
  #### Resize file <a id="fs.op.resize.file">[[fs.op.resize.file]]</a>
10708
 
10709
  ``` cpp
10710
- void resize_file(const path& p, uintmax_t new_size);
10711
- void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
10712
  ```
10713
 
10714
  *Effects:* Causes the size that would be returned by `file_size(p)` to
10715
  be equal to `new_size`, as if by POSIX `truncate()`.
10716
 
10717
  *Throws:* As specified in  [[fs.err.report]].
10718
 
10719
  #### Space <a id="fs.op.space">[[fs.op.space]]</a>
10720
 
10721
  ``` cpp
10722
- space_info space(const path& p);
10723
- space_info space(const path& p, error_code& ec) noexcept;
10724
  ```
10725
 
10726
  *Returns:* An object of type `space_info`. The value of the `space_info`
10727
  object is determined as if by using POSIX `statvfs` to obtain a POSIX
10728
  `struct statvfs`, and then multiplying its `f_blocks`, `f_bfree`, and
@@ -10735,16 +11864,16 @@ members are set to `static_cast<uintmax_t>(-1)` if an error occurs.
10735
  *Throws:* As specified in  [[fs.err.report]].
10736
 
10737
  *Remarks:* The value of member `space_info::available` is operating
10738
  system dependent.
10739
 
10740
- [*Note 1*: `available` may be less than `free`. — *end note*]
10741
 
10742
  #### Status <a id="fs.op.status">[[fs.op.status]]</a>
10743
 
10744
  ``` cpp
10745
- file_status status(const path& p);
10746
  ```
10747
 
10748
  *Effects:* As if:
10749
 
10750
  ``` cpp
@@ -10762,11 +11891,11 @@ return result;
10762
  [*Note 1*: `result` values of `file_status(file_type::not_found)` and
10763
  `file_status(file_type::unknown)` are not considered failures and do not
10764
  cause an exception to be thrown. — *end note*]
10765
 
10766
  ``` cpp
10767
- file_status status(const path& p, error_code& ec) noexcept;
10768
  ```
10769
 
10770
  *Effects:* If possible, determines the attributes of the file `p`
10771
  resolves to, as if by using POSIX `stat()` to obtain a POSIX
10772
  `struct stat`. If, during attribute determination, the underlying file
@@ -10827,20 +11956,20 @@ determined as if by converting the `st_mode` member of the obtained
10827
  pathname resolution continues using the contents of the symbolic link.
10828
 
10829
  #### Status known <a id="fs.op.status.known">[[fs.op.status.known]]</a>
10830
 
10831
  ``` cpp
10832
- bool status_known(file_status s) noexcept;
10833
  ```
10834
 
10835
  *Returns:* `s.type() != file_type::none`.
10836
 
10837
  #### Symlink status <a id="fs.op.symlink.status">[[fs.op.symlink.status]]</a>
10838
 
10839
  ``` cpp
10840
- file_status symlink_status(const path& p);
10841
- file_status symlink_status(const path& p, error_code& ec) noexcept;
10842
  ```
10843
 
10844
  *Effects:* Same as `status()`, above, except that the attributes of `p`
10845
  are determined as if by using POSIX `lstat()` to obtain a POSIX
10846
  `struct stat`.
@@ -10852,19 +11981,19 @@ determined as if by converting the `st_mode` member of the obtained
10852
  *Returns:* Same as `status()`, above, except that if the attributes
10853
  indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
10854
  `file_status(file_type::symlink, prms)`. The signature with argument
10855
  `ec` returns `file_status(file_type::none)` if an error occurs.
10856
 
 
 
10857
  *Remarks:* Pathname resolution terminates if `p` names a symbolic link.
10858
 
10859
- *Throws:* As specified in  [[fs.err.report]].
10860
-
10861
  #### Temporary directory path <a id="fs.op.temp.dir.path">[[fs.op.temp.dir.path]]</a>
10862
 
10863
  ``` cpp
10864
- path temp_directory_path();
10865
- path temp_directory_path(error_code& ec);
10866
  ```
10867
 
10868
  Let `p` be an unspecified directory path suitable for temporary files.
10869
 
10870
  *Effects:* If `exists(p)` is `false` or `is_directory(p)` is `false`, an
@@ -10883,17 +12012,14 @@ return the path reported by the Windows `GetTempPath` API
10883
  function. — *end example*]
10884
 
10885
  #### Weakly canonical <a id="fs.op.weakly.canonical">[[fs.op.weakly.canonical]]</a>
10886
 
10887
  ``` cpp
10888
- path weakly_canonical(const path& p);
10889
- path weakly_canonical(const path& p, error_code& ec);
10890
  ```
10891
 
10892
- *Returns:* `p` with symlinks resolved and the result
10893
- normalized [[fs.path.generic]].
10894
-
10895
  *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
10896
  determine existence, return a path composed by `operator/=` from the
10897
  result of calling `canonical()` with a path argument composed of the
10898
  leading elements of `p` that exist, if any, followed by the elements of
10899
  `p` that do not exist, if any. For the first form, `canonical()` is
@@ -10901,12 +12027,12 @@ called without an `error_code` argument. For the second form,
10901
  `canonical()` is called with `ec` as an `error_code` argument, and
10902
  `path()` is returned at the first error occurrence, if any.
10903
 
10904
  *Ensures:* The returned path is in normal form [[fs.path.generic]].
10905
 
10906
- *Remarks:* Implementations should avoid unnecessary normalization such
10907
- as when `canonical` has already been called on the entirety of `p`.
10908
 
10909
  *Throws:* As specified in  [[fs.err.report]].
10910
 
10911
  ## C library files <a id="c.files">[[c.files]]</a>
10912
 
@@ -11000,19 +12126,19 @@ See also: ISO C 7.21
11000
  #include <cstdint> // see [cstdint.syn]
11001
 
11002
  namespace std {
11003
  using imaxdiv_t = see below;
11004
 
11005
- intmax_t imaxabs(intmax_t j);
11006
- imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
11007
  intmax_t strtoimax(const char* nptr, char** endptr, int base);
11008
  uintmax_t strtoumax(const char* nptr, char** endptr, int base);
11009
  intmax_t wcstoimax(const wchar_t* nptr, wchar_t** endptr, int base);
11010
  uintmax_t wcstoumax(const wchar_t* nptr, wchar_t** endptr, int base);
11011
 
11012
- intmax_t abs(intmax_t); // optional, see below
11013
- imaxdiv_t div(intmax_t, intmax_t); // optional, see below
11014
  }
11015
 
11016
  #define PRIdN see below
11017
  #define PRIiN see below
11018
  #define PRIoN see below
@@ -11073,73 +12199,97 @@ namespace std {
11073
  The contents and meaning of the header `<cinttypes>` are the same as the
11074
  C standard library header `<inttypes.h>`, with the following changes:
11075
 
11076
  - The header `<cinttypes>` includes the header `<cstdint>` instead of
11077
  `<stdint.h>`, and
 
 
 
11078
  - if and only if the type `intmax_t` designates an extended integer type
11079
  [[basic.fundamental]], the following function signatures are added:
11080
  ``` cpp
11081
- intmax_t abs(intmax_t);
11082
- imaxdiv_t div(intmax_t, intmax_t);
11083
  ```
11084
 
11085
  which shall have the same semantics as the function signatures
11086
- `intmax_t imaxabs(intmax_t)` and
11087
- `imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
11088
 
11089
  See also: ISO C 7.8
11090
 
 
 
 
 
 
 
 
11091
  <!-- Link reference definitions -->
11092
  [adjustfield.manip]: #adjustfield.manip
 
11093
  [basefield.manip]: #basefield.manip
11094
  [basic.fundamental]: basic.md#basic.fundamental
11095
  [basic.ios.cons]: #basic.ios.cons
11096
  [basic.ios.copyfmt]: #basic.ios.copyfmt
11097
  [basic.ios.members]: #basic.ios.members
 
11098
  [basic.start.main]: basic.md#basic.start.main
11099
  [bidirectional.iterators]: iterators.md#bidirectional.iterators
11100
  [bitmask.types]: library.md#bitmask.types
11101
  [c.files]: #c.files
11102
  [char.traits]: strings.md#char.traits
 
 
11103
  [cinttypes.syn]: #cinttypes.syn
11104
  [container.requirements.general]: containers.md#container.requirements.general
11105
- [cpp17.allocator]: #cpp17.allocator
11106
  [cpp17.copyassignable]: #cpp17.copyassignable
11107
  [cpp17.copyconstructible]: #cpp17.copyconstructible
11108
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
11109
  [cpp17.destructible]: #cpp17.destructible
11110
  [cpp17.equalitycomparable]: #cpp17.equalitycomparable
 
11111
  [cstdio.syn]: #cstdio.syn
11112
- [defns.ntcts]: library.md#defns.ntcts
11113
  [enumerated.types]: library.md#enumerated.types
11114
  [error.reporting]: #error.reporting
11115
  [ext.manip]: #ext.manip
11116
  [file.streams]: #file.streams
11117
  [filebuf]: #filebuf
11118
  [filebuf.assign]: #filebuf.assign
11119
  [filebuf.cons]: #filebuf.cons
 
11120
  [filebuf.members]: #filebuf.members
11121
  [filebuf.open.modes]: #filebuf.open.modes
11122
  [filebuf.seekoff]: #filebuf.seekoff
11123
  [filebuf.virtuals]: #filebuf.virtuals
11124
  [filesystems]: #filesystems
11125
  [floatfield.manip]: #floatfield.manip
11126
  [fmtflags.manip]: #fmtflags.manip
11127
  [fmtflags.state]: #fmtflags.state
 
11128
  [fpos]: #fpos
11129
  [fpos.members]: #fpos.members
11130
  [fpos.operations]: #fpos.operations
11131
  [fs.class.directory.entry]: #fs.class.directory.entry
 
11132
  [fs.class.directory.iterator]: #fs.class.directory.iterator
 
11133
  [fs.class.file.status]: #fs.class.file.status
 
11134
  [fs.class.filesystem.error]: #fs.class.filesystem.error
 
11135
  [fs.class.path]: #fs.class.path
 
11136
  [fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
 
11137
  [fs.conform.9945]: #fs.conform.9945
11138
  [fs.conform.os]: #fs.conform.os
11139
  [fs.conformance]: #fs.conformance
 
11140
  [fs.dir.entry.cons]: #fs.dir.entry.cons
 
11141
  [fs.dir.entry.mods]: #fs.dir.entry.mods
11142
  [fs.dir.entry.obs]: #fs.dir.entry.obs
11143
  [fs.dir.itr.members]: #fs.dir.itr.members
11144
  [fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
11145
  [fs.enum]: #fs.enum
@@ -11154,11 +12304,10 @@ See also: ISO C 7.8
11154
  [fs.file.status.mods]: #fs.file.status.mods
11155
  [fs.file.status.obs]: #fs.file.status.obs
11156
  [fs.filesystem.error.members]: #fs.filesystem.error.members
11157
  [fs.filesystem.syn]: #fs.filesystem.syn
11158
  [fs.general]: #fs.general
11159
- [fs.norm.ref]: #fs.norm.ref
11160
  [fs.op.absolute]: #fs.op.absolute
11161
  [fs.op.canonical]: #fs.op.canonical
11162
  [fs.op.copy]: #fs.op.copy
11163
  [fs.op.copy.file]: #fs.op.copy.file
11164
  [fs.op.copy.symlink]: #fs.op.copy.symlink
@@ -11170,10 +12319,11 @@ See also: ISO C 7.8
11170
  [fs.op.current.path]: #fs.op.current.path
11171
  [fs.op.equivalent]: #fs.op.equivalent
11172
  [fs.op.exists]: #fs.op.exists
11173
  [fs.op.file.size]: #fs.op.file.size
11174
  [fs.op.funcs]: #fs.op.funcs
 
11175
  [fs.op.hard.lk.ct]: #fs.op.hard.lk.ct
11176
  [fs.op.is.block.file]: #fs.op.is.block.file
11177
  [fs.op.is.char.file]: #fs.op.is.char.file
11178
  [fs.op.is.directory]: #fs.op.is.directory
11179
  [fs.op.is.empty]: #fs.op.is.empty
@@ -11206,10 +12356,11 @@ See also: ISO C 7.8
11206
  [fs.path.decompose]: #fs.path.decompose
11207
  [fs.path.fmt.cvt]: #fs.path.fmt.cvt
11208
  [fs.path.gen]: #fs.path.gen
11209
  [fs.path.generic]: #fs.path.generic
11210
  [fs.path.generic.obs]: #fs.path.generic.obs
 
11211
  [fs.path.io]: #fs.path.io
11212
  [fs.path.itr]: #fs.path.itr
11213
  [fs.path.member]: #fs.path.member
11214
  [fs.path.modifiers]: #fs.path.modifiers
11215
  [fs.path.native.obs]: #fs.path.native.obs
@@ -11219,31 +12370,34 @@ See also: ISO C 7.8
11219
  [fs.path.type.cvt]: #fs.path.type.cvt
11220
  [fs.race.behavior]: #fs.race.behavior
11221
  [fs.rec.dir.itr.members]: #fs.rec.dir.itr.members
11222
  [fs.rec.dir.itr.nonmembers]: #fs.rec.dir.itr.nonmembers
11223
  [fs.req]: #fs.req
11224
- [fs.req.namespace]: #fs.req.namespace
11225
  [fstream]: #fstream
11226
- [fstream.assign]: #fstream.assign
11227
  [fstream.cons]: #fstream.cons
 
11228
  [fstream.members]: #fstream.members
 
11229
  [fstream.syn]: #fstream.syn
11230
  [ifstream]: #ifstream
11231
- [ifstream.assign]: #ifstream.assign
11232
  [ifstream.cons]: #ifstream.cons
 
11233
  [ifstream.members]: #ifstream.members
 
11234
  [input.iterators]: iterators.md#input.iterators
11235
  [input.output]: #input.output
11236
  [input.output.general]: #input.output.general
11237
  [input.streams]: #input.streams
 
11238
  [intro.multithread]: basic.md#intro.multithread
11239
  [intro.races]: basic.md#intro.races
11240
  [iomanip.syn]: #iomanip.syn
11241
  [ios]: #ios
11242
  [ios.base]: #ios.base
11243
  [ios.base.callback]: #ios.base.callback
11244
  [ios.base.cons]: #ios.base.cons
 
11245
  [ios.base.locales]: #ios.base.locales
11246
  [ios.base.storage]: #ios.base.storage
11247
  [ios.failure]: #ios.failure
11248
  [ios.fmtflags]: #ios.fmtflags
11249
  [ios.fmtflags.const]: #ios.fmtflags.const
@@ -11266,72 +12420,108 @@ See also: ISO C 7.8
11266
  [iostream.limits.imbue]: #iostream.limits.imbue
11267
  [iostream.objects]: #iostream.objects
11268
  [iostream.objects.overview]: #iostream.objects.overview
11269
  [iostream.syn]: #iostream.syn
11270
  [iostreamclass]: #iostreamclass
 
11271
  [iostreams.base]: #iostreams.base
11272
  [iostreams.limits.pos]: #iostreams.limits.pos
11273
  [iostreams.requirements]: #iostreams.requirements
11274
  [iostreams.summary]: #iostreams.summary
11275
  [iostreams.threadsafety]: #iostreams.threadsafety
 
 
 
 
 
11276
  [istream]: #istream
11277
  [istream.assign]: #istream.assign
11278
  [istream.cons]: #istream.cons
11279
  [istream.extractors]: #istream.extractors
11280
  [istream.formatted]: #istream.formatted
11281
  [istream.formatted.arithmetic]: #istream.formatted.arithmetic
11282
  [istream.formatted.reqmts]: #istream.formatted.reqmts
 
11283
  [istream.manip]: #istream.manip
11284
  [istream.rvalue]: #istream.rvalue
11285
  [istream.sentry]: #istream.sentry
11286
  [istream.syn]: #istream.syn
11287
  [istream.unformatted]: #istream.unformatted
11288
  [istringstream]: #istringstream
11289
- [istringstream.assign]: #istringstream.assign
11290
  [istringstream.cons]: #istringstream.cons
 
11291
  [istringstream.members]: #istringstream.members
 
11292
  [lex.charset]: lex.md#lex.charset
11293
  [locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
11294
  [locale.num.get]: localization.md#locale.num.get
11295
  [namespace.std]: library.md#namespace.std
11296
  [narrow.stream.objects]: #narrow.stream.objects
11297
  [numeric.limits]: support.md#numeric.limits
11298
  [ofstream]: #ofstream
11299
- [ofstream.assign]: #ofstream.assign
11300
  [ofstream.cons]: #ofstream.cons
 
11301
  [ofstream.members]: #ofstream.members
 
 
 
 
 
 
11302
  [ostream]: #ostream
11303
  [ostream.assign]: #ostream.assign
11304
  [ostream.cons]: #ostream.cons
11305
  [ostream.formatted]: #ostream.formatted
 
11306
  [ostream.formatted.reqmts]: #ostream.formatted.reqmts
 
11307
  [ostream.inserters]: #ostream.inserters
11308
  [ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
11309
  [ostream.inserters.character]: #ostream.inserters.character
11310
  [ostream.manip]: #ostream.manip
11311
  [ostream.rvalue]: #ostream.rvalue
11312
  [ostream.seeks]: #ostream.seeks
11313
  [ostream.sentry]: #ostream.sentry
11314
  [ostream.syn]: #ostream.syn
11315
  [ostream.unformatted]: #ostream.unformatted
11316
  [ostringstream]: #ostringstream
11317
- [ostringstream.assign]: #ostringstream.assign
11318
  [ostringstream.cons]: #ostringstream.cons
 
11319
  [ostringstream.members]: #ostringstream.members
 
11320
  [output.streams]: #output.streams
 
 
 
11321
  [quoted.manip]: #quoted.manip
11322
  [res.on.data.races]: library.md#res.on.data.races
11323
  [res.on.exception.handling]: library.md#res.on.exception.handling
 
 
 
 
 
 
 
 
 
 
 
 
 
 
11324
  [sstream.syn]: #sstream.syn
11325
  [std.ios.manip]: #std.ios.manip
11326
  [std.manip]: #std.manip
 
11327
  [stream.buffers]: #stream.buffers
11328
  [stream.types]: #stream.types
11329
  [streambuf]: #streambuf
11330
  [streambuf.assign]: #streambuf.assign
11331
  [streambuf.buffer]: #streambuf.buffer
11332
  [streambuf.cons]: #streambuf.cons
 
11333
  [streambuf.get.area]: #streambuf.get.area
11334
  [streambuf.locales]: #streambuf.locales
11335
  [streambuf.members]: #streambuf.members
11336
  [streambuf.protected]: #streambuf.protected
11337
  [streambuf.pub.get]: #streambuf.pub.get
@@ -11349,19 +12539,21 @@ See also: ISO C 7.8
11349
  [string.classes]: strings.md#string.classes
11350
  [string.streams]: #string.streams
11351
  [stringbuf]: #stringbuf
11352
  [stringbuf.assign]: #stringbuf.assign
11353
  [stringbuf.cons]: #stringbuf.cons
 
11354
  [stringbuf.members]: #stringbuf.members
11355
  [stringbuf.seekoff.newoff]: #stringbuf.seekoff.newoff
11356
  [stringbuf.seekoff.pos]: #stringbuf.seekoff.pos
11357
  [stringbuf.virtuals]: #stringbuf.virtuals
11358
  [strings]: strings.md#strings
11359
  [stringstream]: #stringstream
11360
- [stringstream.assign]: #stringstream.assign
11361
  [stringstream.cons]: #stringstream.cons
 
11362
  [stringstream.members]: #stringstream.members
 
11363
  [syncstream]: #syncstream
11364
  [syncstream.osyncstream]: #syncstream.osyncstream
11365
  [syncstream.osyncstream.cons]: #syncstream.osyncstream.cons
11366
  [syncstream.osyncstream.members]: #syncstream.osyncstream.members
11367
  [syncstream.osyncstream.overview]: #syncstream.osyncstream.overview
@@ -11372,71 +12564,73 @@ See also: ISO C 7.8
11372
  [syncstream.syncbuf.members]: #syncstream.syncbuf.members
11373
  [syncstream.syncbuf.overview]: #syncstream.syncbuf.overview
11374
  [syncstream.syncbuf.special]: #syncstream.syncbuf.special
11375
  [syncstream.syncbuf.virtuals]: #syncstream.syncbuf.virtuals
11376
  [temp.deduct]: temp.md#temp.deduct
 
 
11377
  [wide.stream.objects]: #wide.stream.objects
11378
 
11379
- [^1]: It is the implementation’s responsibility to implement headers so
 
 
 
 
 
11380
  that including `<iosfwd>` and other headers does not violate the
11381
  rules about multiple occurrences of default arguments.
11382
 
11383
- [^2]: If it is possible for them to do so, implementations should
11384
- initialize the objects earlier than required.
11385
-
11386
- [^3]: Constructors and destructors for objects with static storage
11387
  duration can access these objects to read input from `stdin` or
11388
  write output to `stdout` or `stderr`.
11389
 
11390
- [^4]: Typically `long long`.
11391
-
11392
- [^5]: `streamsize` is used in most places where ISO C would use
11393
- `size_t`.
11394
-
11395
- [^6]: This implies that operations on a standard iostream object can be
11396
  mixed arbitrarily with operations on the corresponding stdio stream.
11397
  In practical terms, synchronization usually means that a standard
11398
  iostream object and a standard stdio object share a buffer.
11399
 
11400
- [^7]: An implementation is free to implement both the integer array
11401
  pointed at by `iarray` and the pointer array pointed at by `parray`
11402
  as sparse data structures, possibly with a one-element cache for
11403
  each.
11404
 
 
 
11405
  [^8]: For example, because it cannot allocate space.
11406
 
11407
- [^9]: For example, because it cannot allocate space.
11408
-
11409
- [^10]: This suggests an infinite amount of copying, but the
11410
  implementation can keep track of the maximum element of the arrays
11411
  that is nonzero.
11412
 
11413
- [^11]: Checking `badbit` also for `fail()` is historical practice.
11414
 
11415
- [^12]: The function signature `dec(ios_base&)` can be called by the
11416
  function signature
11417
  `basic_ostream& stream::operator<<(ios_base& (*)(ios_base&))` to
11418
  permit expressions of the form `cout << dec` to change the format
11419
  flags stored in `cout`.
11420
 
11421
- [^13]: The default constructor is protected for class `basic_streambuf`
11422
- to assure that only objects for classes derived from this class may
11423
  be constructed.
11424
 
11425
- [^14]: `underflow` or `uflow` might fail by throwing an exception
 
 
 
11426
  prematurely. The intention is not only that the calls will not
11427
  return `eof()` but that they will return “immediately”.
11428
 
11429
  [^15]: Classes derived from `basic_streambuf` can provide more efficient
11430
  ways to implement `xsgetn()` and `xsputn()` by overriding these
11431
  definitions from the base class.
11432
 
11433
- [^16]: That is, for each class derived from an instance of
11434
- `basic_streambuf` in this Clause ([[stringbuf]],
11435
- [[filebuf]]), a specification of how consuming a character
11436
- effects the associated output sequence is given. There is no
11437
- requirement on a program-defined class.
11438
 
11439
  [^17]: Typically, `overflow` returns `c` to indicate success, except
11440
  when `traits::eq_int_type(c, traits::eof())` returns `true`, in
11441
  which case it returns `traits::not_eof(c)`.
11442
 
@@ -11445,76 +12639,67 @@ See also: ISO C 7.8
11445
  specified.
11446
 
11447
  [^19]: The `sentry` constructor and destructor can also perform
11448
  additional implementation-dependent operations.
11449
 
11450
- [^20]: This is done without causing an `ios_base::failure` to be thrown.
11451
-
11452
- [^21]: See, for example, the function signature
11453
  `ws(basic_istream&)`[[istream.manip]].
11454
 
11455
- [^22]: See, for example, the function signature
11456
  `dec(ios_base&)`[[basefield.manip]].
11457
 
11458
- [^23]: This is done without causing an `ios_base::failure` to be thrown.
 
 
 
 
11459
 
11460
  [^24]: Note that this function is not overloaded on types `signed char`
11461
  and `unsigned char`.
11462
 
11463
- [^25]: Note that this function is not overloaded on types `signed char`
11464
- and `unsigned char`.
11465
-
11466
- [^26]: Note that this function is not overloaded on types `signed char`
11467
- and `unsigned char`.
11468
-
11469
- [^27]: Since the final input character is “extracted”, it is counted in
11470
  the `gcount()`, even though it is not stored.
11471
 
11472
- [^28]: This allows an input line which exactly fills the buffer, without
11473
  setting `failbit`. This is different behavior than the historical
11474
  AT&T implementation.
11475
 
11476
- [^29]: This implies an empty input line will not cause `failbit` to be
11477
  set.
11478
 
11479
- [^30]: Note that this function is not overloaded on types `signed char`
11480
  and `unsigned char`.
11481
 
11482
- [^31]: The call `os.tie()->flush()` does not necessarily occur if the
11483
  function can determine that no synchronization is necessary.
11484
 
11485
- [^32]: The `sentry` constructor and destructor can also perform
11486
  additional implementation-dependent operations.
11487
 
11488
- [^33]: without causing an `ios_base::failure` to be thrown.
11489
 
11490
- [^34]: See, for example, the function signature
11491
  `endl(basic_ostream&)`[[ostream.manip]].
11492
 
11493
- [^35]: See, for example, the function signature
11494
  `dec(ios_base&)`[[basefield.manip]].
11495
 
11496
- [^36]: without causing an `ios_base::failure` to be thrown.
11497
 
11498
- [^37]: Note that this function is not overloaded on types `signed char`
11499
  and `unsigned char`.
11500
 
11501
- [^38]: Note that this function is not overloaded on types `signed char`
11502
  and `unsigned char`.
11503
 
11504
- [^39]: The expression `cin >> resetiosflags(ios_base::skipws)` clears
11505
  `ios_base::skipws` in the format flags stored in the
11506
  `basic_istream<charT, traits>` object `cin` (the same as
11507
  `cin >> noskipws`), and the expression
11508
  `cout << resetiosflags(ios_base::showbase)` clears
11509
  `ios_base::showbase` in the format flags stored in the
11510
  `basic_ostream<charT, traits>` object `cout` (the same as
11511
  `cout << noshowbase`).
11512
 
11513
- [^40]: The macro `SEEK_END` is defined, and the function signatures
11514
  `fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
11515
  declared, in `<cstdio>`.
11516
-
11517
- [^41]: POSIX® is a registered trademark of The IEEE. Windows® is a
11518
- registered trademark of Microsoft Corporation. This information is
11519
- given for the convenience of users of this document and does not
11520
- constitute an endorsement by ISO or IEC of these products.
 
12
  summarized in [[iostreams.summary]].
13
 
14
  **Table: Input/output library summary** <a id="iostreams.summary">[iostreams.summary]</a>
15
 
16
  | Subclause | | Header |
17
+ | -------------------------- | --------------------------- | ------------------------------------------------ |
18
  | [[iostreams.requirements]] | Requirements | |
19
  | [[iostream.forward]] | Forward declarations | `<iosfwd>` |
20
  | [[iostream.objects]] | Standard iostream objects | `<iostream>` |
21
  | [[iostreams.base]] | Iostreams base classes | `<ios>` |
22
  | [[stream.buffers]] | Stream buffers | `<streambuf>` |
23
+ | [[iostream.format]] | Formatting and manipulators | `<istream>`, `<ostream>`, `<iomanip>`, `<print>` |
24
  | [[string.streams]] | String streams | `<sstream>` |
25
+ | [[span.streams]] | Span-based streams | `<spanstream>` |
26
  | [[file.streams]] | File streams | `<fstream>` |
27
  | [[syncstream]] | Synchronized output streams | `<syncstream>` |
28
  | [[filesystems]] | File systems | `<filesystem>` |
29
  | [[c.files]] | C library files | `<cstdio>`, `<cinttypes>` |
30
 
31
 
 
 
 
 
 
 
 
 
 
 
 
32
  ## Iostreams requirements <a id="iostreams.requirements">[[iostreams.requirements]]</a>
33
 
34
  ### Imbue limitations <a id="iostream.limits.imbue">[[iostream.limits.imbue]]</a>
35
 
36
  No function described in [[input.output]] except for `ios_base::imbue`
 
38
  or `basic_streambuf::imbue` to be called. If any user function called
39
  from a function declared in [[input.output]] or as an overriding virtual
40
  function of any class declared in [[input.output]] calls `imbue`, the
41
  behavior is undefined.
42
 
43
+ ### Types <a id="stream.types">[[stream.types]]</a>
44
+
45
+ ``` cpp
46
+ using streamoff = implementation-defined // type of streamoff;
47
+ ```
48
+
49
+ The type `streamoff` is a synonym for one of the signed basic integral
50
+ types of sufficient size to represent the maximum possible file size for
51
+ the operating system.[^1]
52
+
53
+ ``` cpp
54
+ using streamsize = implementation-defined;
55
+ ```
56
+
57
+ The type `streamsize` is a synonym for one of the signed basic integral
58
+ types. It is used to represent the number of characters transferred in
59
+ an I/O operation, or the size of I/O buffers.[^2]
60
+
61
  ### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
62
 
63
  The classes of [[input.output]] with template arguments `charT` and
64
  `traits` behave as described if `traits::pos_type` and
65
  `traits::off_type` are `streampos` and `streamoff` respectively. Except
66
  as noted explicitly below, their behavior when `traits::pos_type` and
67
  `traits::off_type` are other types is *implementation-defined*.
68
 
69
+ [*Note 1*: For each of the specializations of `char_traits` defined in
70
+ [[char.traits.specializations]], `state_type` denotes `mbstate_t`,
71
+ `pos_type` denotes `fpos<mbstate_t>`, and `off_type` denotes
72
+ `streamoff`. — *end note*]
73
+
74
  In the classes of [[input.output]], a template parameter with name
75
  `charT` represents a member of the set of types containing `char`,
76
  `wchar_t`, and any other *implementation-defined* character types that
77
  meet the requirements for a character on which any of the iostream
78
  components can be instantiated.
79
 
80
  ### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
81
 
82
+ Concurrent access to a stream object
83
+ [[string.streams]], [[file.streams]], stream buffer object
84
+ [[stream.buffers]], or C Library stream [[c.files]] by multiple threads
85
+ may result in a data race [[intro.multithread]] unless otherwise
86
+ specified [[iostream.objects]].
87
 
88
  [*Note 1*: Data races result in undefined behavior
89
  [[intro.multithread]]. — *end note*]
90
 
91
  If one thread makes a library call *a* that writes a value to a stream
 
130
  class basic_ostringstream;
131
  template<class charT, class traits = char_traits<charT>,
132
  class Allocator = allocator<charT>>
133
  class basic_stringstream;
134
 
135
+ template<class charT, class traits = char_traits<charT>>
136
+ class basic_spanbuf;
137
+ template<class charT, class traits = char_traits<charT>>
138
+ class basic_ispanstream;
139
+ template<class charT, class traits = char_traits<charT>>
140
+ class basic_ospanstream;
141
+ template<class charT, class traits = char_traits<charT>>
142
+ class basic_spanstream;
143
+
144
  template<class charT, class traits = char_traits<charT>>
145
  class basic_filebuf;
146
  template<class charT, class traits = char_traits<charT>>
147
  class basic_ifstream;
148
  template<class charT, class traits = char_traits<charT>>
 
173
  using stringbuf = basic_stringbuf<char>;
174
  using istringstream = basic_istringstream<char>;
175
  using ostringstream = basic_ostringstream<char>;
176
  using stringstream = basic_stringstream<char>;
177
 
178
+ using spanbuf = basic_spanbuf<char>;
179
+ using ispanstream = basic_ispanstream<char>;
180
+ using ospanstream = basic_ospanstream<char>;
181
+ using spanstream = basic_spanstream<char>;
182
+
183
  using filebuf = basic_filebuf<char>;
184
  using ifstream = basic_ifstream<char>;
185
  using ofstream = basic_ofstream<char>;
186
  using fstream = basic_fstream<char>;
187
 
 
196
  using wstringbuf = basic_stringbuf<wchar_t>;
197
  using wistringstream = basic_istringstream<wchar_t>;
198
  using wostringstream = basic_ostringstream<wchar_t>;
199
  using wstringstream = basic_stringstream<wchar_t>;
200
 
201
+ using wspanbuf = basic_spanbuf<wchar_t>;
202
+ using wispanstream = basic_ispanstream<wchar_t>;
203
+ using wospanstream = basic_ospanstream<wchar_t>;
204
+ using wspanstream = basic_spanstream<wchar_t>;
205
+
206
  using wfilebuf = basic_filebuf<wchar_t>;
207
  using wifstream = basic_ifstream<wchar_t>;
208
  using wofstream = basic_ofstream<wchar_t>;
209
  using wfstream = basic_fstream<wchar_t>;
210
 
 
220
  }
221
  ```
222
 
223
  Default template arguments are described as appearing both in `<iosfwd>`
224
  and in the synopsis of other headers but it is well-formed to include
225
+ both `<iosfwd>` and one or more of the other headers.[^3]
226
 
227
  ### Overview <a id="iostream.forward.overview">[[iostream.forward.overview]]</a>
228
 
229
  The class template specialization `basic_ios<charT, traits>` serves as a
230
  virtual base class for the class templates `basic_istream`,
 
299
  and includes all the headers necessary to use these objects.
300
 
301
  The objects are constructed and the associations are established at some
302
  time prior to or during the first time an object of class
303
  `ios_base::Init` is constructed, and in any case before the body of
304
+ `main` [[basic.start.main]] begins execution. The objects are not
305
+ destroyed during program execution.[^4]
306
+
307
+ *Recommended practice:* If it is possible for them to do so,
308
+ implementations should initialize the objects earlier than required.
309
+
310
+ The results of including `<iostream>` in a translation unit shall be as
311
+ if `<iostream>` defined an instance of `ios_base::Init` with static
312
+ storage duration. Each C++ library module [[std.modules]] in a hosted
313
+ implementation shall behave as if it contains an interface unit that
314
+ defines an unexported `ios_base::Init` variable with ordered
315
+ initialization [[basic.start.dynamic]].
316
+
317
+ [*Note 1*: As a result, the definition of that variable is
318
+ appearance-ordered before any declaration following the point of
319
+ importation of a C++ library module. Whether such a definition exists is
320
+ unobservable by a program that does not reference any of the standard
321
+ iostream objects. — *end note*]
322
 
323
  Mixing operations on corresponding wide- and narrow-character streams
324
  follows the same semantics as mixing such operations on `FILE`s, as
325
  specified in the C standard library.
326
 
327
  Concurrent access to a synchronized [[ios.members.static]] standard
328
  iostream object’s formatted and unformatted input [[istream]] and output
329
  [[ostream]] functions or a standard C stream by multiple threads does
330
  not result in a data race [[intro.multithread]].
331
 
332
+ [*Note 2*: Unsynchronized concurrent use of these objects and streams
333
+ by multiple threads can result in interleaved characters. — *end note*]
 
334
 
335
  See also: ISO C 7.21.2
336
 
337
  ### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
338
 
 
474
  error_condition make_error_condition(io_errc e) noexcept;
475
  const error_category& iostream_category() noexcept;
476
  }
477
  ```
478
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
479
  ### Class `ios_base` <a id="ios.base">[[ios.base]]</a>
480
 
481
+ #### General <a id="ios.base.general">[[ios.base.general]]</a>
482
+
483
  ``` cpp
484
  namespace std {
485
  class ios_base {
486
  public:
487
  class failure; // see below
 
518
  using openmode = T3;
519
  static constexpr openmode app = unspecified;
520
  static constexpr openmode ate = unspecified;
521
  static constexpr openmode binary = unspecified;
522
  static constexpr openmode in = unspecified;
523
+ static constexpr openmode noreplace = unspecified;
524
  static constexpr openmode out = unspecified;
525
  static constexpr openmode trunc = unspecified;
526
 
527
  // [ios.seekdir], seekdir
528
  using seekdir = T4;
 
732
  elements indicated in [[ios.openmode]].
733
 
734
  **Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
735
 
736
  | Element | Effect(s) if set |
737
+ | ----------- | ----------------------------------------------------------------- |
738
  | `app` | seek to end before each write |
739
  | `ate` | open and seek to end immediately after opening |
740
  | `binary` | perform input and output in binary mode (as opposed to text mode) |
741
  | `in` | open for input |
742
+ | `noreplace` | open in exclusive mode |
743
  | `out` | open for output |
744
  | `trunc` | truncate an existing stream when opening |
745
 
746
 
747
  ##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
 
770
  public:
771
  Init();
772
  Init(const Init&) = default;
773
  ~Init();
774
  Init& operator=(const Init&) = default;
775
+
776
  private:
777
  static int init_cnt; // exposition only
778
  };
779
  }
780
  ```
 
900
 
901
  ``` cpp
902
  static bool sync_with_stdio(bool sync = true);
903
  ```
904
 
 
 
 
 
905
  *Effects:* If any input or output operation has occurred using the
906
  standard streams prior to the call, the effect is
907
  *implementation-defined*. Otherwise, called with a `false` argument, it
908
  allows the standard streams to operate independently of the standard C
909
  streams.
910
 
911
+ *Returns:* `true` if the previous state of the standard iostream
912
+ objects [[iostream.objects]] was synchronized and otherwise returns
913
+ `false`. The first time it is called, the function returns `true`.
914
+
915
+ *Remarks:* When a standard iostream object `str` is *synchronized* with
916
+ a standard stdio stream `f`, the effect of inserting a character `c` by
917
 
918
  ``` cpp
919
  fputc(f, c);
920
  ```
921
 
 
949
 
950
  ``` cpp
951
  str.rdbuf()->sputbackc(c);
952
  ```
953
 
954
+ for any sequence of characters.[^5]
955
 
956
  #### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
957
 
958
  ``` cpp
959
  static int xalloc();
 
973
  *Effects:* If `iarray` is a null pointer, allocates an array of `long`
974
  of unspecified size and stores a pointer to its first element in
975
  `iarray`. The function then extends the array pointed at by `iarray` as
976
  necessary to include the element `iarray[idx]`. Each newly allocated
977
  element of the array is initialized to zero. The reference returned is
978
+ invalid after any other operation on the object.[^6]
979
+
980
+ However, the value of the storage referred to is retained, so that until
981
+ the next call to `copyfmt`, calling `iword` with the same index yields
982
+ another reference to the same value. If the function fails[^7]
983
+
984
+ and `*this` is a base class subobject of a `basic_ios<>` object or
985
+ subobject, the effect is equivalent to calling
986
+ `basic_ios<>::setstate(badbit)` on the derived object (which may throw
987
+ `failure`).
988
 
989
  *Returns:* On success `iarray[idx]`. On failure, a valid `long&`
990
  initialized to 0.
991
 
992
  ``` cpp
 
998
  *Effects:* If `parray` is a null pointer, allocates an array of pointers
999
  to `void` of unspecified size and stores a pointer to its first element
1000
  in `parray`. The function then extends the array pointed at by `parray`
1001
  as necessary to include the element `parray[idx]`. Each newly allocated
1002
  element of the array is initialized to a null pointer. The reference
1003
+ returned is invalid after any other operation on the object. However,
1004
  the value of the storage referred to is retained, so that until the next
1005
  call to `copyfmt`, calling `pword` with the same index yields another
1006
+ reference to the same value. If the function fails[^8]
1007
+
1008
+ and `*this` is a base class subobject of a `basic_ios<>` object or
1009
+ subobject, the effect is equivalent to calling
1010
+ `basic_ios<>::setstate(badbit)` on the derived object (which may throw
1011
+ `failure`).
1012
 
1013
  *Returns:* On success `parray[idx]`. On failure a valid `void*&`
1014
  initialized to 0.
1015
 
1016
  *Remarks:* After a subsequent call to `pword(int)` for the same object,
 
1050
  ```
1051
 
1052
  *Effects:* Calls each registered callback pair `(fn, idx)`
1053
  [[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
1054
  that any `ios_base` member function called from within `fn` has
1055
+ well-defined results. Then, any memory obtained is deallocated.
1056
 
1057
  ### Class template `fpos` <a id="fpos">[[fpos]]</a>
1058
 
1059
  ``` cpp
1060
  namespace std {
1061
  template<class stateT> class fpos {
1062
  public:
1063
  // [fpos.members], members
1064
  stateT state() const;
1065
  void state(stateT);
1066
+
1067
+ private:
1068
  stateT st; // exposition only
1069
  };
1070
  }
1071
  ```
1072
 
 
1093
  [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
1094
  [[cpp17.copyassignable]]), and *Cpp17Destructible* (
1095
  [[cpp17.destructible]]) requirements. If
1096
  `is_trivially_copy_constructible_v<stateT>` is `true`, then
1097
  `fpos<stateT>` has a trivial copy constructor. If
1098
+ `is_trivially_copy_assignable_v<stateT>` is `true`, then `fpos<stateT>`
1099
  has a trivial copy assignment operator. If
1100
  `is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
1101
  a trivial destructor. All specializations of `fpos` meet the
1102
  *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
1103
  *Cpp17CopyAssignable*, *Cpp17Destructible*, and
1104
  *Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
1105
  In addition, the expressions shown in [[fpos.operations]] are valid and
1106
  have the indicated semantics. In that table,
1107
 
1108
+ - `P` refers to a specialization of `fpos`,
1109
  - `p` and `q` refer to values of type `P` or `const P`,
1110
  - `pl` and `ql` refer to modifiable lvalues of type `P`,
1111
  - `O` refers to type `streamoff`, and
1112
+ - `o` and `o2` refer to values of type `streamoff` or `const streamoff`.
1113
 
1114
  Stream operations that return a value of type `traits::pos_type` return
1115
  `P(O(-1))` as an invalid value to signal an error. If this value is used
1116
  as an argument to any `istream`, `ostream`, or `streambuf` member that
1117
  accepts a value of type `traits::pos_type` then the behavior of that
 
1175
  void init(basic_streambuf<charT, traits>* sb);
1176
  void move(basic_ios& rhs);
1177
  void move(basic_ios&& rhs);
1178
  void swap(basic_ios& rhs) noexcept;
1179
  void set_rdbuf(basic_streambuf<charT, traits>* sb);
 
1180
  };
1181
  }
1182
  ```
1183
 
1184
  #### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
 
1314
  `(*fn)(erase_event, *this, idx)`;
1315
  - then, assigns to the member objects of `*this` the corresponding
1316
  member objects of `rhs`, except that
1317
  - `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
1318
  - the contents of arrays pointed at by `pword` and `iword` are copied,
1319
+ not the pointers themselves;[^9] and
1320
  - if any newly stored pointer values in `*this` point at objects
1321
  stored outside the object `rhs` and those objects are destroyed when
1322
  `rhs` is destroyed, the newly stored pointer values are altered to
1323
  point at newly constructed copies of the objects;
1324
  - then, calls each callback pair that was copied from `rhs` as
 
1403
 
1404
  ``` cpp
1405
  void clear(iostate state = goodbit);
1406
  ```
1407
 
 
 
 
1408
  *Effects:* If
1409
  `((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
1410
  Otherwise, the function throws an object of class `ios_base::failure`
1411
  [[ios.failure]], constructed with *implementation-defined* argument
1412
  values.
1413
 
1414
+ *Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
1415
+ `rdstate() == (state | ios_base::badbit)`.
1416
+
1417
  ``` cpp
1418
  void setstate(iostate state);
1419
  ```
1420
 
1421
  *Effects:* Calls `clear(rdstate() | state)` (which may throw
 
1435
 
1436
  ``` cpp
1437
  bool fail() const;
1438
  ```
1439
 
1440
+ *Returns:* `true` if `failbit` or `badbit` is set in `rdstate()`.[^10]
1441
 
1442
  ``` cpp
1443
  bool bad() const;
1444
  ```
1445
 
 
1454
 
1455
  ``` cpp
1456
  void exceptions(iostate except);
1457
  ```
1458
 
 
 
1459
  *Effects:* Calls `clear(rdstate())`.
1460
 
1461
+ *Ensures:* `except == exceptions()`.
1462
+
1463
  ### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
1464
 
1465
  #### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
1466
 
1467
  Each function specified in this subclause is a designated addressable
 
1617
  ios_base& dec(ios_base& str);
1618
  ```
1619
 
1620
  *Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
1621
 
1622
+ *Returns:* `str`.[^11]
1623
 
1624
  ``` cpp
1625
  ios_base& hex(ios_base& str);
1626
  ```
1627
 
 
1665
  *Effects:* Calls
1666
  `str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
1667
 
1668
  *Returns:* `str`.
1669
 
1670
+ [*Note 1*: `ios_base::hex` cannot be used to specify a hexadecimal
1671
+ floating-point format, because it is not part of `ios_base::floatfield`
1672
+ ([[ios.fmtflags.const]]). *end note*]
 
1673
 
1674
  ``` cpp
1675
  ios_base& defaultfloat(ios_base& str);
1676
  ```
1677
 
 
1772
  shall have a defined value and is the next element to read (to get, or
1773
  to obtain a character value, from the sequence).
1774
 
1775
  ### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
1776
 
1777
+ #### General <a id="streambuf.general">[[streambuf.general]]</a>
1778
+
1779
  ``` cpp
1780
  namespace std {
1781
  template<class charT, class traits = char_traits<charT>>
1782
  class basic_streambuf {
1783
  public:
 
1881
 
1882
  ``` cpp
1883
  basic_streambuf();
1884
  ```
1885
 
1886
+ *Effects:* Initializes:[^12]
1887
 
1888
  - all pointer member objects to null pointers,
1889
+ - the `getloc()` member to a copy of the global locale, `locale()`, at
1890
+ the time of construction.
1891
 
1892
  *Remarks:* Once the `getloc()` member is initialized, results of calling
1893
  locale member functions, and of members of facets so obtained, can
1894
  safely be cached until the next time the member `imbue` is called.
1895
 
 
2158
  basic_streambuf* setbuf(char_type* s, streamsize n);
2159
  ```
2160
 
2161
  *Effects:* Influences stream buffering in a way that is defined
2162
  separately for each class derived from `basic_streambuf` in this
2163
+ Clause [[stringbuf.virtuals]], [[filebuf.virtuals]].
2164
 
2165
  *Default behavior:* Does nothing. Returns `this`.
2166
 
2167
  ``` cpp
2168
  pos_type seekoff(off_type off, ios_base::seekdir way,
 
2170
  = ios_base::in | ios_base::out);
2171
  ```
2172
 
2173
  *Effects:* Alters the stream positions within one or more of the
2174
  controlled sequences in a way that is defined separately for each class
2175
+ derived from `basic_streambuf` in this
2176
+ Clause [[stringbuf.virtuals]], [[filebuf.virtuals]].
2177
 
2178
  *Default behavior:* Returns `pos_type(off_type(-1))`.
2179
 
2180
  ``` cpp
2181
  pos_type seekpos(pos_type sp,
 
2183
  = ios_base::in | ios_base::out);
2184
  ```
2185
 
2186
  *Effects:* Alters the stream positions within one or more of the
2187
  controlled sequences in a way that is defined separately for each class
2188
+ derived from `basic_streambuf` in this
2189
+ Clause [[stringbuf]], [[filebuf]].
2190
 
2191
  *Default behavior:* Returns `pos_type(off_type(-1))`.
2192
 
2193
  ``` cpp
2194
  int sync();
 
2205
  *Default behavior:* Returns zero.
2206
 
2207
  ##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
2208
 
2209
  ``` cpp
2210
+ streamsize showmanyc();
 
2211
  ```
2212
 
2213
+ [^13]
2214
+
2215
  *Returns:* An estimate of the number of characters available in the
2216
  sequence, or -1. If it returns a positive value, then successive calls
2217
  to `underflow()` will not return `traits::eof()` until at least that
2218
  number of characters have been extracted from the stream. If
2219
  `showmanyc()` returns -1, then calls to `underflow()` or `uflow()` will
 
2239
 
2240
  ``` cpp
2241
  int_type underflow();
2242
  ```
2243
 
 
 
 
 
 
 
 
 
2244
  The *pending sequence* of characters is defined as the concatenation of
2245
 
2246
  - the empty sequence if `gptr()` is null, otherwise the characters in
2247
  \[`gptr()`, `egptr()`), followed by
2248
  - some (possibly empty) sequence of characters read from the input
 
2268
  in which case the characters in \[`eback()`, `gptr()`) agree with the
2269
  last `gptr() - eback()` characters of the backup sequence, or
2270
  - the characters in \[`gptr() - n`, `gptr()`) agree with the backup
2271
  sequence (where `n` is the length of the backup sequence).
2272
 
2273
+ *Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
2274
+ of the *pending sequence*, without moving the input sequence position
2275
+ past it. If the pending sequence is null then the function returns
2276
+ `traits::eof()` to indicate failure.
2277
+
2278
  *Default behavior:* Returns `traits::eof()`.
2279
 
2280
+ *Remarks:* The public members of `basic_streambuf` call this virtual
2281
+ function only if `gptr()` is null or `gptr() >= egptr()`.
2282
+
2283
  ``` cpp
2284
  int_type uflow();
2285
  ```
2286
 
2287
  *Preconditions:* The constraints are the same as for `underflow()`,
 
2289
  sequence to the backup sequence, and the pending sequence is not empty
2290
  before the transfer.
2291
 
2292
  *Default behavior:* Calls `underflow()`. If `underflow()` returns
2293
  `traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
2294
+ of `traits::to_int_type(*gptr())` and increments the value of the next
2295
  pointer for the input sequence.
2296
 
2297
  *Returns:* `traits::eof()` to indicate failure.
2298
 
2299
  ##### Putback <a id="streambuf.virt.pback">[[streambuf.virt.pback]]</a>
2300
 
2301
  ``` cpp
2302
  int_type pbackfail(int_type c = traits::eof());
2303
  ```
2304
 
 
 
 
 
 
2305
  The *pending sequence* is defined as for `underflow()`, with the
2306
  modifications that
2307
 
2308
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
2309
  input sequence is backed up one character before the pending sequence
 
2315
  *Ensures:* On return, the constraints of `gptr()`, `eback()`, and
2316
  `pptr()` are the same as for `underflow()`.
2317
 
2318
  *Returns:* `traits::eof()` to indicate failure. Failure may occur
2319
  because the input sequence could not be backed up, or if for some other
2320
+ reason the pointers cannot be set consistent with the constraints.
2321
  `pbackfail()` is called only when put back has really failed.
2322
 
2323
  Returns some value other than `traits::eof()` to indicate success.
2324
 
2325
  *Default behavior:* Returns `traits::eof()`.
2326
 
2327
+ *Remarks:* The public functions of `basic_streambuf` call this virtual
2328
+ function only when `gptr()` is null, `gptr() == eback()`, or
2329
+ `traits::eq(traits::to_char_type(c), gptr()[-1])` returns `false`. Other
2330
+ calls shall also satisfy that constraint.
2331
+
2332
  ##### Put area <a id="streambuf.virt.put">[[streambuf.virt.put]]</a>
2333
 
2334
  ``` cpp
2335
  streamsize xsputn(const char_type* s, streamsize n);
2336
  ```
 
2356
  - the empty sequence if `pbase()` is null, otherwise the
2357
  `pptr() - pbase()` characters beginning at `pbase()`, followed by
2358
  - the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
2359
  `true`, otherwise the sequence consisting of `c`.
2360
 
 
 
 
 
2361
  *Preconditions:* Every overriding definition of this virtual function
2362
  obeys the following constraints:
2363
 
2364
  - The effect of consuming a character on the associated output sequence
2365
  is specified.[^16]
 
2379
  Otherwise, returns some value other than `traits::eof()` to indicate
2380
  success.[^17]
2381
 
2382
  *Default behavior:* Returns `traits::eof()`.
2383
 
2384
+ *Remarks:* The member functions `sputc()` and `sputn()` call this
2385
+ function in case that no room can be found in the put buffer enough to
2386
+ accommodate the argument character sequence.
2387
+
2388
  ## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
2389
 
2390
  ### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
2391
 
2392
  ``` cpp
 
2404
  using wiostream = basic_iostream<wchar_t>;
2405
 
2406
  template<class charT, class traits>
2407
  basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
2408
 
2409
+ template<class Istream, class T>
2410
+ Istream&& operator>>(Istream&& is, T&& x);
2411
  }
2412
  ```
2413
 
2414
  ### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
2415
 
 
2433
  template<class charT, class traits>
2434
  basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
2435
  template<class charT, class traits>
2436
  basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
2437
 
2438
+ template<class Ostream, class T>
2439
+ Ostream&& operator<<(Ostream&& os, const T& x);
2440
+
2441
+ // [ostream.formatted.print], print functions
2442
+ template<class... Args>
2443
+ void print(ostream& os, format_string<Args...> fmt, Args&&... args);
2444
+ template<class... Args>
2445
+ void println(ostream& os, format_string<Args...> fmt, Args&&... args);
2446
+
2447
+ void vprint_unicode(ostream& os, string_view fmt, format_args args);
2448
+ void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
2449
  }
2450
  ```
2451
 
2452
  ### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
2453
 
2454
  ``` cpp
2455
  namespace std {
2456
+ unspecified resetiosflags(ios_base::fmtflags mask);
2457
+ unspecified setiosflags (ios_base::fmtflags mask);
2458
+ unspecified setbase(int base);
2459
+ template<class charT> unspecified setfill(charT c);
2460
+ unspecified setprecision(int n);
2461
+ unspecified setw(int n);
2462
+ template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
2463
+ template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
2464
+ template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
2465
+ template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
 
2466
 
2467
  template<class charT>
2468
+ unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
2469
 
2470
  template<class charT, class traits, class Allocator>
2471
+ unspecified quoted(const basic_string<charT, traits, Allocator>& s,
2472
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2473
 
2474
  template<class charT, class traits, class Allocator>
2475
+ unspecified quoted(basic_string<charT, traits, Allocator>& s,
2476
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2477
 
2478
  template<class charT, class traits>
2479
+ unspecified quoted(basic_string_view<charT, traits> s,
2480
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
2481
  }
2482
  ```
2483
 
2484
+ ### Header `<print>` synopsis <a id="print.syn">[[print.syn]]</a>
2485
+
2486
+ ``` cpp
2487
+ namespace std {
2488
+ // [print.fun], print functions
2489
+ template<class... Args>
2490
+ void print(format_string<Args...> fmt, Args&&... args);
2491
+ template<class... Args>
2492
+ void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
2493
+
2494
+ template<class... Args>
2495
+ void println(format_string<Args...> fmt, Args&&... args);
2496
+ template<class... Args>
2497
+ void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
2498
+
2499
+ void vprint_unicode(string_view fmt, format_args args);
2500
+ void vprint_unicode(FILE* stream, string_view fmt, format_args args);
2501
+
2502
+ void vprint_nonunicode(string_view fmt, format_args args);
2503
+ void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
2504
+ }
2505
+ ```
2506
+
2507
  ### Input streams <a id="input.streams">[[input.streams]]</a>
2508
 
2509
+ #### General <a id="input.streams.general">[[input.streams.general]]</a>
2510
+
2511
+ The header `<istream>` defines two class templates and a function
2512
+ template that control input from a stream buffer, along with a function
2513
+ template that extracts from stream rvalues.
2514
 
2515
  #### Class template `basic_istream` <a id="istream">[[istream]]</a>
2516
 
2517
+ ##### General <a id="istream.general">[[istream.general]]</a>
2518
+
2519
+ When a function is specified with a type placeholder of
2520
+ `extended-floating-point-type`, the implementation provides overloads
2521
+ for all cv-unqualified extended floating-point types
2522
+ [[basic.fundamental]] in lieu of `extended-floating-{point-type}`.
2523
+
2524
  ``` cpp
2525
  namespace std {
2526
  template<class charT, class traits = char_traits<charT>>
2527
  class basic_istream : virtual public basic_ios<charT, traits> {
2528
  public:
 
2539
 
2540
  // [istream.sentry], prefix/suffix
2541
  class sentry;
2542
 
2543
  // [istream.formatted], formatted input
2544
+ basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
2545
+ basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
2546
+ basic_istream& operator>>(ios_base& (*pf)(ios_base&));
 
 
 
2547
 
2548
+ basic_istream& operator>>(bool& n);
2549
+ basic_istream& operator>>(short& n);
2550
+ basic_istream& operator>>(unsigned short& n);
2551
+ basic_istream& operator>>(int& n);
2552
+ basic_istream& operator>>(unsigned int& n);
2553
+ basic_istream& operator>>(long& n);
2554
+ basic_istream& operator>>(unsigned long& n);
2555
+ basic_istream& operator>>(long long& n);
2556
+ basic_istream& operator>>(unsigned long long& n);
2557
+ basic_istream& operator>>(float& f);
2558
+ basic_istream& operator>>(double& f);
2559
+ basic_istream& operator>>(long double& f);
2560
+ basic_istream& operator>>(extended-floating-point-type& f);
2561
 
2562
+ basic_istream& operator>>(void*& p);
2563
+ basic_istream& operator>>(basic_streambuf<char_type, traits>* sb);
2564
 
2565
  // [istream.unformatted], unformatted input
2566
  streamsize gcount() const;
2567
  int_type get();
2568
+ basic_istream& get(char_type& c);
2569
+ basic_istream& get(char_type* s, streamsize n);
2570
+ basic_istream& get(char_type* s, streamsize n, char_type delim);
2571
+ basic_istream& get(basic_streambuf<char_type, traits>& sb);
2572
+ basic_istream& get(basic_streambuf<char_type, traits>& sb, char_type delim);
2573
 
2574
+ basic_istream& getline(char_type* s, streamsize n);
2575
+ basic_istream& getline(char_type* s, streamsize n, char_type delim);
2576
 
2577
+ basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
2578
  int_type peek();
2579
+ basic_istream& read (char_type* s, streamsize n);
2580
  streamsize readsome(char_type* s, streamsize n);
2581
 
2582
+ basic_istream& putback(char_type c);
2583
+ basic_istream& unget();
2584
  int sync();
2585
 
2586
  pos_type tellg();
2587
+ basic_istream& seekg(pos_type);
2588
+ basic_istream& seekg(off_type, ios_base::seekdir);
2589
 
2590
  protected:
2591
  // [istream.cons], copy/move constructor
2592
  basic_istream(const basic_istream&) = delete;
2593
  basic_istream(basic_istream&& rhs);
2594
 
2595
+ // [istream.assign], assignment and swap
2596
  basic_istream& operator=(const basic_istream&) = delete;
2597
  basic_istream& operator=(basic_istream&& rhs);
2598
  void swap(basic_istream& rhs);
2599
  };
2600
 
 
2623
  *formatted input functions* (or *extractors*) and the *unformatted input
2624
  functions.* Both groups of input functions are described as if they
2625
  obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
2626
  or `rdbuf()->sgetc()`. They may use other public members of `istream`.
2627
 
 
 
 
 
 
 
 
 
 
 
 
 
2628
  ##### Constructors <a id="istream.cons">[[istream.cons]]</a>
2629
 
2630
  ``` cpp
2631
  explicit basic_istream(basic_streambuf<charT, traits>* sb);
2632
  ```
 
2669
 
2670
  ##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
2671
 
2672
  ``` cpp
2673
  namespace std {
2674
+ template<class charT, class traits>
2675
  class basic_istream<charT, traits>::sentry {
2676
  bool ok_; // exposition only
2677
+
2678
  public:
2679
+ explicit sentry(basic_istream& is, bool noskipws = false);
2680
  ~sentry();
2681
  explicit operator bool() const { return ok_; }
2682
  sentry(const sentry&) = delete;
2683
  sentry& operator=(const sentry&) = delete;
2684
  };
 
2687
 
2688
  The class `sentry` defines a class that is responsible for doing
2689
  exception safe prefix and suffix operations.
2690
 
2691
  ``` cpp
2692
+ explicit sentry(basic_istream& is, bool noskipws = false);
2693
  ```
2694
 
2695
  *Effects:* If `is.good()` is `false`, calls `is.setstate(failbit)`.
2696
  Otherwise, prepares for formatted or unformatted input. First, if
2697
  `is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
2698
  to synchronize the output sequence with any associated external C
2699
  stream. Except that this call can be suppressed if the put area of
2700
  `is.tie()` is empty. Further an implementation is allowed to defer the
2701
  call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
2702
  such call occurs before the `sentry` object is destroyed, the call to
2703
+ `flush` may be eliminated entirely.[^18]
2704
+
2705
+ If `noskipws` is zero and `is.flags() & ios_base::skipws` is nonzero,
2706
+ the function extracts and discards each character as long as the next
2707
+ available input character `c` is a whitespace character. If
2708
+ `is.rdbuf()->sbumpc()` or `is.rdbuf()->sgetc()` returns `traits::eof()`,
2709
+ the function calls `setstate(failbit | eofbit)` (which may throw
2710
+ `ios_base::failure`).
2711
 
2712
  *Remarks:* The constructor
2713
 
2714
  ``` cpp
2715
+ explicit sentry(basic_istream& is, bool noskipws = false)
2716
  ```
2717
 
2718
  uses the currently imbued locale in `is`, to determine whether the next
2719
  input character is whitespace or not.
2720
 
 
2747
  #### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
2748
 
2749
  ##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
2750
 
2751
  Each formatted input function begins execution by constructing an object
2752
+ of type `ios_base::iostate`, termed the local error state, and
2753
+ initializing it to `ios_base::goodbit`. It then creates an object of
2754
+ class `sentry` with the `noskipws` (second) argument `false`. If the
2755
  `sentry` object returns `true`, when converted to a value of type
2756
+ `bool`, the function endeavors to obtain the requested input. Otherwise,
2757
+ if the `sentry` constructor exits by throwing an exception or if the
2758
+ `sentry` object produces `false` when converted to a value of type
2759
+ `bool`, the function returns without attempting to obtain any input. If
2760
+ `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`, then
2761
+ `ios_base::eofbit` is set in the local error state and the input
2762
+ function stops trying to obtain the requested input. If an exception is
2763
+ thrown during input then `ios_base::badbit` is set in the local error
2764
+ state, `*this`’s error state is set to the local error state, and the
2765
+ exception is rethrown if `(exceptions() & badbit) != 0`. After
2766
+ extraction is done, the input function calls `setstate`, which sets
2767
+ `*this`’s error state to the local error state, and may throw an
2768
+ exception. In any case, the formatted input function destroys the
2769
+ `sentry` object. If no exception has been thrown, it returns `*this`.
2770
 
2771
  ##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
2772
 
2773
  ``` cpp
2774
+ basic_istream& operator>>(unsigned short& val);
2775
+ basic_istream& operator>>(unsigned int& val);
2776
+ basic_istream& operator>>(long& val);
2777
+ basic_istream& operator>>(unsigned long& val);
2778
+ basic_istream& operator>>(long long& val);
2779
+ basic_istream& operator>>(unsigned long long& val);
2780
+ basic_istream& operator>>(float& val);
2781
+ basic_istream& operator>>(double& val);
2782
+ basic_istream& operator>>(long double& val);
2783
+ basic_istream& operator>>(bool& val);
2784
+ basic_istream& operator>>(void*& val);
2785
  ```
2786
 
2787
  As in the case of the inserters, these extractors depend on the locale’s
2788
  `num_get<>` [[locale.num.get]] object to perform parsing the input
2789
  stream data. These extractors behave as formatted input functions (as
2790
+ described in  [[istream.formatted.reqmts]]). After a `sentry` object is
2791
  constructed, the conversion occurs as if performed by the following code
2792
+ fragment, where `state` represents the input function’s local error
2793
+ state:
2794
 
2795
  ``` cpp
2796
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2797
+ use_facet<numget>(loc).get(*this, 0, *this, state, val);
 
 
2798
  ```
2799
 
2800
  In the above fragment, `loc` stands for the private member of the
2801
  `basic_ios` class.
2802
 
 
2807
 
2808
  Class `locale` relies on this type as its interface to `istream`, so
2809
  that it does not need to depend directly on `istream`.
2810
 
2811
  ``` cpp
2812
+ basic_istream& operator>>(short& val);
2813
  ```
2814
 
2815
  The conversion occurs as if performed by the following code fragment
2816
  (using the same notation as for the preceding code fragment):
2817
 
2818
  ``` cpp
2819
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
 
2820
  long lval;
2821
+ use_facet<numget>(loc).get(*this, 0, *this, state, lval);
2822
  if (lval < numeric_limits<short>::min()) {
2823
+ state |= ios_base::failbit;
2824
  val = numeric_limits<short>::min();
2825
  } else if (numeric_limits<short>::max() < lval) {
2826
+ state |= ios_base::failbit;
2827
  val = numeric_limits<short>::max();
2828
  } else
2829
  val = static_cast<short>(lval);
 
2830
  ```
2831
 
2832
  ``` cpp
2833
+ basic_istream& operator>>(int& val);
2834
  ```
2835
 
2836
  The conversion occurs as if performed by the following code fragment
2837
  (using the same notation as for the preceding code fragment):
2838
 
2839
  ``` cpp
2840
  using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
 
2841
  long lval;
2842
+ use_facet<numget>(loc).get(*this, 0, *this, state, lval);
2843
  if (lval < numeric_limits<int>::min()) {
2844
+ state |= ios_base::failbit;
2845
  val = numeric_limits<int>::min();
2846
  } else if (numeric_limits<int>::max() < lval) {
2847
+ state |= ios_base::failbit;
2848
  val = numeric_limits<int>::max();
2849
  } else
2850
  val = static_cast<int>(lval);
 
2851
  ```
2852
 
2853
+ ``` cpp
2854
+ basic_istream& operator>>(extended-floating-point-type& val);
2855
+ ```
2856
+
2857
+ If the floating-point conversion rank of
2858
+ *`extended-floating-point-type`* is not less than or equal to that of
2859
+ `long double`, then an invocation of the operator function is
2860
+ conditionally supported with *implementation-defined* semantics.
2861
+
2862
+ Otherwise, let `FP` be a standard floating-point type:
2863
+
2864
+ - if the floating-point conversion rank of
2865
+ *`extended-floating-point-type`* is less than or equal to that of
2866
+ `float`, then `FP` is `float`,
2867
+ - otherwise, if the floating-point conversion rank of
2868
+ *`extended-floating-point-type`* is less than or equal to that of
2869
+ `double`, then `FP` is `double`,
2870
+ - otherwise, `FP` is `long double`.
2871
+
2872
+ The conversion occurs as if performed by the following code fragment
2873
+ (using the same notation as for the preceding code fragment):
2874
+
2875
+ ``` cpp
2876
+ using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
2877
+ FP fval;
2878
+ use_facet<numget>(loc).get(*this, 0, *this, state, fval);
2879
+ if (fval < -numeric_limits<extended-floating-point-type>::max()) {
2880
+ state |= ios_base::failbit;
2881
+ val = -numeric_limits<extended-floating-point-type>::max();
2882
+ } else if (numeric_limits<extended-floating-point-type>::max() < fval) {
2883
+ state |= ios_base::failbit;
2884
+ val = numeric_limits<extended-floating-point-type>::max();
2885
+ } else {
2886
+ val = static_cast<extended-floating-point-type>(fval);
2887
+ }
2888
+ ```
2889
+
2890
+ [*Note 2*: When the extended floating-point type has a floating-point
2891
+ conversion rank that is not equal to the rank of any standard
2892
+ floating-point type, then double rounding during the conversion can
2893
+ result in inaccurate results. `from_chars` can be used in situations
2894
+ where maximum accuracy is important. — *end note*]
2895
+
2896
  ##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
2897
 
2898
  ``` cpp
2899
+ basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
 
2900
  ```
2901
 
2902
  *Effects:* None. This extractor does not behave as a formatted input
2903
  function (as described in  [[istream.formatted.reqmts]]).
2904
 
2905
+ *Returns:* `pf(*this)`. [^20]
2906
 
2907
  ``` cpp
2908
+ basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
 
2909
  ```
2910
 
2911
  *Effects:* Calls `pf(*this)`. This extractor does not behave as a
2912
  formatted input function (as described
2913
  in  [[istream.formatted.reqmts]]).
2914
 
2915
  *Returns:* `*this`.
2916
 
2917
  ``` cpp
2918
+ basic_istream& operator>>(ios_base& (*pf)(ios_base&));
2919
  ```
2920
 
2921
+ *Effects:* Calls `pf(*this)`.[^21]
2922
+
2923
+ This extractor does not behave as a formatted input function (as
2924
+ described in  [[istream.formatted.reqmts]]).
2925
 
2926
  *Returns:* `*this`.
2927
 
2928
  ``` cpp
2929
  template<class charT, class traits, size_t N>
 
2949
 
2950
  `operator>>` then stores a null byte (`charT()`) in the next position,
2951
  which may be the first position if no characters were extracted.
2952
  `operator>>` then calls `width(0)`.
2953
 
2954
+ If the function extracted no characters, `ios_base::failbit` is set in
2955
+ the input function’s local error state before `setstate` is called.
2956
 
2957
  *Returns:* `in`.
2958
 
2959
  ``` cpp
2960
  template<class charT, class traits>
 
2964
  template<class traits>
2965
  basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
2966
  ```
2967
 
2968
  *Effects:* Behaves like a formatted input member (as described
2969
+ in  [[istream.formatted.reqmts]]) of `in`. A character is extracted from
2970
+ `in`, if one is available, and stored in `c`. Otherwise,
2971
+ `ios_base::failbit` is set in the input function’s local error state
2972
+ before `setstate` is called.
2973
 
2974
  *Returns:* `in`.
2975
 
2976
  ``` cpp
2977
+ basic_istream& operator>>(basic_streambuf<charT, traits>* sb);
2978
  ```
2979
 
2980
  *Effects:* Behaves as an unformatted input
2981
  function [[istream.unformatted]]. If `sb` is null, calls
2982
  `setstate(failbit)`, which may throw `ios_base::failure`
2983
+ [[iostate.flags]]. After a `sentry` object is constructed, extracts
2984
  characters from `*this` and inserts them in the output sequence
2985
  controlled by `sb`. Characters are extracted and inserted until any of
2986
  the following occurs:
2987
 
2988
  - end-of-file occurs on the input sequence;
2989
  - inserting in the output sequence fails (in which case the character to
2990
  be inserted is not extracted);
2991
  - an exception occurs (in which case the exception is caught).
2992
 
2993
+ If the function inserts no characters, `ios_base::failbit` is set in the
2994
+ input function’s local error state before `setstate` is called.
 
 
 
2995
 
2996
  *Returns:* `*this`.
2997
 
2998
  #### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
2999
 
3000
  Each unformatted input function begins execution by constructing an
3001
+ object of type `ios_base::iostate`, termed the local error state, and
3002
+ initializing it to `ios_base::goodbit`. It then creates an object of
3003
+ class `sentry` with the default argument `noskipws` (second) argument
3004
+ `true`. If the `sentry` object returns `true`, when converted to a value
3005
+ of type `bool`, the function endeavors to obtain the requested input.
3006
+ Otherwise, if the `sentry` constructor exits by throwing an exception or
3007
+ if the `sentry` object produces `false`, when converted to a value of
3008
+ type `bool`, the function returns without attempting to obtain any
3009
+ input. In either case the number of extracted characters is set to 0;
3010
+ unformatted input functions taking a character array of nonzero size as
3011
+ an argument shall also store a null character (using `charT()`) in the
3012
+ first location of the array. If `rdbuf()->sbumpc()` or
3013
+ `rdbuf()->sgetc()` returns `traits::eof()`, then `ios_base::eofbit` is
3014
+ set in the local error state and the input function stops trying to
3015
+ obtain the requested input. If an exception is thrown during input then
3016
+ `ios_base::badbit` is set in the local error state, `*this`’s error
3017
+ state is set to the local error state, and the exception is rethrown if
3018
+ `(exceptions() & badbit) != 0`. If no exception has been thrown it
3019
+ stores the number of characters extracted in a member object. After
3020
+ extraction is done, the input function calls `setstate`, which sets
3021
+ `*this`’s error state to the local error state, and may throw an
3022
+ exception. In any event the `sentry` object is destroyed before leaving
3023
+ the unformatted input function.
3024
 
3025
  ``` cpp
3026
  streamsize gcount() const;
3027
  ```
3028
 
3029
  *Effects:* None. This member function does not behave as an unformatted
3030
  input function (as described above).
3031
 
3032
  *Returns:* The number of characters extracted by the last unformatted
3033
+ input member function called for the object. If the number cannot be
3034
+ represented, returns `numeric_limits<streamsize>::max()`.
3035
 
3036
  ``` cpp
3037
  int_type get();
3038
  ```
3039
 
3040
  *Effects:* Behaves as an unformatted input function (as described
3041
+ above). After constructing a `sentry` object, extracts a character `c`,
3042
+ if one is available. Otherwise, `ios_base::failbit` is set in the input
3043
+ function’s local error state before `setstate` is called.
3044
 
3045
  *Returns:* `c` if available, otherwise `traits::eof()`.
3046
 
3047
  ``` cpp
3048
+ basic_istream& get(char_type& c);
3049
  ```
3050
 
3051
  *Effects:* Behaves as an unformatted input function (as described
3052
+ above). After constructing a `sentry` object, extracts a character, if
3053
+ one is available, and assigns it to `c`.[^22]
3054
+
3055
+ Otherwise, `ios_base::failbit` is set in the input function’s local
3056
+ error state before `setstate` is called.
3057
 
3058
  *Returns:* `*this`.
3059
 
3060
  ``` cpp
3061
+ basic_istream& get(char_type* s, streamsize n, char_type delim);
3062
  ```
3063
 
3064
  *Effects:* Behaves as an unformatted input function (as described
3065
+ above). After constructing a `sentry` object, extracts characters and
3066
  stores them into successive locations of an array whose first element is
3067
+ designated by `s`.[^23]
3068
+
3069
+ Characters are extracted and stored until any of the following occurs:
3070
 
3071
  - `n` is less than one or `n - 1` characters are stored;
3072
+ - end-of-file occurs on the input sequence;
 
3073
  - `traits::eq(c, delim)` for the next available input character `c` (in
3074
  which case `c` is not extracted).
3075
 
3076
+ If the function stores no characters, `ios_base::failbit` is set in the
3077
+ input function’s local error state before `setstate` is called. In any
3078
+ case, if `n` is greater than zero it then stores a null character into
3079
+ the next successive location of the array.
3080
 
3081
  *Returns:* `*this`.
3082
 
3083
  ``` cpp
3084
+ basic_istream& get(char_type* s, streamsize n);
3085
  ```
3086
 
3087
  *Effects:* Calls `get(s, n, widen(’\n’))`.
3088
 
3089
  *Returns:* Value returned by the call.
3090
 
3091
  ``` cpp
3092
+ basic_istream& get(basic_streambuf<char_type, traits>& sb, char_type delim);
3093
  ```
3094
 
3095
  *Effects:* Behaves as an unformatted input function (as described
3096
+ above). After constructing a `sentry` object, extracts characters and
3097
  inserts them in the output sequence controlled by `sb`. Characters are
3098
  extracted and inserted until any of the following occurs:
3099
 
3100
  - end-of-file occurs on the input sequence;
3101
  - inserting in the output sequence fails (in which case the character to
 
3103
  - `traits::eq(c, delim)` for the next available input character `c` (in
3104
  which case `c` is not extracted);
3105
  - an exception occurs (in which case, the exception is caught but not
3106
  rethrown).
3107
 
3108
+ If the function inserts no characters, `ios_base::failbit` is set in the
3109
+ input function’s local error state before `setstate` is called.
3110
 
3111
  *Returns:* `*this`.
3112
 
3113
  ``` cpp
3114
+ basic_istream& get(basic_streambuf<char_type, traits>& sb);
3115
  ```
3116
 
3117
  *Effects:* Calls `get(sb, widen(’\n’))`.
3118
 
3119
  *Returns:* Value returned by the call.
3120
 
3121
  ``` cpp
3122
+ basic_istream& getline(char_type* s, streamsize n, char_type delim);
3123
  ```
3124
 
3125
  *Effects:* Behaves as an unformatted input function (as described
3126
+ above). After constructing a `sentry` object, extracts characters and
3127
  stores them into successive locations of an array whose first element is
3128
+ designated by `s`.[^24]
 
3129
 
3130
+ Characters are extracted and stored until one of the following occurs:
3131
+
3132
+ 1. end-of-file occurs on the input sequence;
3133
  2. `traits::eq(c, delim)` for the next available input character `c`
3134
  (in which case the input character is extracted but not
3135
+ stored);[^25]
3136
  3. `n` is less than one or `n - 1` characters are stored (in which case
3137
  the function calls `setstate(failbit)`).
3138
 
3139
+ These conditions are tested in the order shown.[^26]
3140
 
3141
+ If the function extracts no characters, `ios_base::failbit` is set in
3142
+ the input function’s local error state before `setstate` is called.[^27]
3143
 
3144
  In any case, if `n` is greater than zero, it then stores a null
3145
  character (using `charT()`) into the next successive location of the
3146
  array.
3147
 
 
3175
  ```
3176
 
3177
  — *end example*]
3178
 
3179
  ``` cpp
3180
+ basic_istream& getline(char_type* s, streamsize n);
3181
  ```
3182
 
3183
  *Returns:* `getline(s, n, widen(’\n’))`
3184
 
3185
  ``` cpp
3186
+ basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
3187
  ```
3188
 
3189
  *Effects:* Behaves as an unformatted input function (as described
3190
+ above). After constructing a `sentry` object, extracts characters and
3191
  discards them. Characters are extracted until any of the following
3192
  occurs:
3193
 
3194
  - `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
3195
  characters have been extracted so far
 
3197
  calls `setstate(eofbit)`, which may throw `ios_base::failure`
3198
  [[iostate.flags]]);
3199
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
3200
  available input character `c` (in which case `c` is extracted).
3201
 
3202
+ [*Note 1*: The last condition will never occur if
3203
+ `traits::eq_int_type(delim, traits::eof())`. — *end note*]
3204
 
3205
  *Returns:* `*this`.
3206
 
3207
  ``` cpp
3208
  int_type peek();
3209
  ```
3210
 
3211
  *Effects:* Behaves as an unformatted input function (as described
3212
+ above). After constructing a `sentry` object, reads but does not extract
3213
  the current input character.
3214
 
3215
  *Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
3216
  `rdbuf()->sgetc()`.
3217
 
3218
  ``` cpp
3219
+ basic_istream& read(char_type* s, streamsize n);
3220
  ```
3221
 
3222
  *Effects:* Behaves as an unformatted input function (as described
3223
+ above). After constructing a `sentry` object, if `!good()` calls
3224
  `setstate(failbit)` which may throw an exception, and return. Otherwise
3225
  extracts characters and stores them into successive locations of an
3226
+ array whose first element is designated by `s`.[^28]
3227
+
3228
+ Characters are extracted and stored until either of the following
3229
+ occurs:
3230
 
3231
  - `n` characters are stored;
3232
  - end-of-file occurs on the input sequence (in which case the function
3233
  calls `setstate(failbit | eofbit)`, which may throw
3234
  `ios_base::failure` [[iostate.flags]]).
 
3238
  ``` cpp
3239
  streamsize readsome(char_type* s, streamsize n);
3240
  ```
3241
 
3242
  *Effects:* Behaves as an unformatted input function (as described
3243
+ above). After constructing a `sentry` object, if `!good()` calls
3244
  `setstate(failbit)` which may throw an exception, and return. Otherwise
3245
  extracts characters and stores them into successive locations of an
3246
  array whose first element is designated by `s`. If
3247
  `rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
3248
  `ios_base::failure` [[iostate.flags]]), and extracts no characters;
 
3251
  - If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
3252
 
3253
  *Returns:* The number of characters extracted.
3254
 
3255
  ``` cpp
3256
+ basic_istream& putback(char_type c);
3257
  ```
3258
 
3259
  *Effects:* Behaves as an unformatted input function (as described
3260
  above), except that the function first clears `eofbit`. After
3261
+ constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
3262
  which may throw an exception, and return. If `rdbuf()` is not null,
3263
  calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
3264
  returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3265
  `ios_base::failure` [[iostate.flags]]).
3266
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3267
  [*Note 2*: This function extracts no characters, so the value returned
3268
  by the next call to `gcount()` is 0. — *end note*]
3269
 
3270
  *Returns:* `*this`.
3271
 
3272
+ ``` cpp
3273
+ basic_istream& unget();
3274
+ ```
3275
+
3276
+ *Effects:* Behaves as an unformatted input function (as described
3277
+ above), except that the function first clears `eofbit`. After
3278
+ constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
3279
+ which may throw an exception, and return. If `rdbuf()` is not null,
3280
+ calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
3281
+ returns `traits::eof()`, calls `setstate(badbit)` (which may throw
3282
+ `ios_base::failure` [[iostate.flags]]).
3283
+
3284
+ [*Note 3*: This function extracts no characters, so the value returned
3285
+ by the next call to `gcount()` is 0. — *end note*]
3286
+
3287
+ *Returns:* `*this`.
3288
+
3289
  ``` cpp
3290
  int sync();
3291
  ```
3292
 
3293
  *Effects:* Behaves as an unformatted input function (as described
3294
  above), except that it does not count the number of characters extracted
3295
  and does not affect the value returned by subsequent calls to
3296
+ `gcount()`. After constructing a `sentry` object, if `rdbuf()` is a null
3297
  pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
3298
  that function returns `-1` calls `setstate(badbit)` (which may throw
3299
  `ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
3300
  returns zero.
3301
 
 
3306
  *Effects:* Behaves as an unformatted input function (as described
3307
  above), except that it does not count the number of characters extracted
3308
  and does not affect the value returned by subsequent calls to
3309
  `gcount()`.
3310
 
3311
+ *Returns:* After constructing a `sentry` object, if `fail() != false`,
3312
  returns `pos_type(-1)` to indicate failure. Otherwise, returns
3313
  `rdbuf()->pubseekoff(0, cur, in)`.
3314
 
3315
  ``` cpp
3316
+ basic_istream& seekg(pos_type pos);
3317
  ```
3318
 
3319
  *Effects:* Behaves as an unformatted input function (as described
3320
  above), except that the function first clears `eofbit`, it does not
3321
  count the number of characters extracted, and it does not affect the
3322
  value returned by subsequent calls to `gcount()`. After constructing a
3323
+ `sentry` object, if `fail() != true`, executes
3324
  `rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
3325
  function calls `setstate(failbit)` (which may throw
3326
  `ios_base::failure`).
3327
 
3328
  *Returns:* `*this`.
3329
 
3330
  ``` cpp
3331
+ basic_istream& seekg(off_type off, ios_base::seekdir dir);
3332
  ```
3333
 
3334
  *Effects:* Behaves as an unformatted input function (as described
3335
  above), except that the function first clears `eofbit`, does not count
3336
  the number of characters extracted, and does not affect the value
3337
+ returned by subsequent calls to `gcount()`. After constructing a
3338
+ `sentry` object, if `fail() != true`, executes
3339
  `rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
3340
  function calls `setstate(failbit)` (which may throw
3341
  `ios_base::failure`).
3342
 
3343
  *Returns:* `*this`.
 
3353
  ```
3354
 
3355
  *Effects:* Behaves as an unformatted input
3356
  function [[istream.unformatted]], except that it does not count the
3357
  number of characters extracted and does not affect the value returned by
3358
+ subsequent calls to `is.gcount()`. After constructing a `sentry` object
3359
  extracts characters as long as the next available character `c` is
3360
  whitespace or until there are no more characters in the sequence.
3361
  Whitespace characters are distinguished with the same criterion as used
3362
  by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
3363
  characters because there are no more available it sets `eofbit`, but not
 
3371
  template<class Istream, class T>
3372
  Istream&& operator>>(Istream&& is, T&& x);
3373
  ```
3374
 
3375
  *Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
3376
+ when treated as an unevaluated operand [[term.unevaluated.operand]] and
3377
+ `Istream` is publicly and unambiguously derived from `ios_base`.
3378
 
3379
  *Effects:* Equivalent to:
3380
 
3381
  ``` cpp
3382
  is >> std::forward<T>(x);
3383
  return std::move(is);
3384
  ```
3385
 
3386
  #### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
3387
 
3388
+ ##### General <a id="iostreamclass.general">[[iostreamclass.general]]</a>
3389
+
3390
  ``` cpp
3391
  namespace std {
3392
  template<class charT, class traits = char_traits<charT>>
3393
  class basic_iostream
3394
  : public basic_istream<charT, traits>,
 
3409
  protected:
3410
  // [iostream.cons], constructor
3411
  basic_iostream(const basic_iostream&) = delete;
3412
  basic_iostream(basic_iostream&& rhs);
3413
 
3414
+ // [iostream.assign], assignment and swap
3415
  basic_iostream& operator=(const basic_iostream&) = delete;
3416
  basic_iostream& operator=(basic_iostream&& rhs);
3417
  void swap(basic_iostream& rhs);
3418
  };
3419
  }
 
3438
  ``` cpp
3439
  basic_iostream(basic_iostream&& rhs);
3440
  ```
3441
 
3442
  *Effects:* Move constructs from the rvalue `rhs` by constructing the
3443
+ `basic_istream` base class with `std::move(rhs)`.
3444
 
3445
  ##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
3446
 
3447
  ``` cpp
3448
  virtual ~basic_iostream();
 
3464
 
3465
  *Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
3466
 
3467
  ### Output streams <a id="output.streams">[[output.streams]]</a>
3468
 
3469
+ #### General <a id="output.streams.general">[[output.streams.general]]</a>
3470
+
3471
+ The header `<ostream>` defines a class template and several function
3472
+ templates that control output to a stream buffer, along with a function
3473
+ template that inserts into stream rvalues.
3474
 
3475
  #### Class template `basic_ostream` <a id="ostream">[[ostream]]</a>
3476
 
3477
+ ##### General <a id="ostream.general">[[ostream.general]]</a>
3478
+
3479
+ When a function has a parameter type `extended-floating-point-type`, the
3480
+ implementation provides overloads for all cv-unqualified extended
3481
+ floating-point types [[basic.fundamental]].
3482
+
3483
  ``` cpp
3484
  namespace std {
3485
  template<class charT, class traits = char_traits<charT>>
3486
  class basic_ostream : virtual public basic_ios<charT, traits> {
3487
  public:
 
3498
 
3499
  // [ostream.sentry], prefix/suffix
3500
  class sentry;
3501
 
3502
  // [ostream.formatted], formatted output
3503
+ basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&));
3504
+ basic_ostream& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
3505
+ basic_ostream& operator<<(ios_base& (*pf)(ios_base&));
 
 
 
3506
 
3507
+ basic_ostream& operator<<(bool n);
3508
+ basic_ostream& operator<<(short n);
3509
+ basic_ostream& operator<<(unsigned short n);
3510
+ basic_ostream& operator<<(int n);
3511
+ basic_ostream& operator<<(unsigned int n);
3512
+ basic_ostream& operator<<(long n);
3513
+ basic_ostream& operator<<(unsigned long n);
3514
+ basic_ostream& operator<<(long long n);
3515
+ basic_ostream& operator<<(unsigned long long n);
3516
+ basic_ostream& operator<<(float f);
3517
+ basic_ostream& operator<<(double f);
3518
+ basic_ostream& operator<<(long double f);
3519
+ basic_ostream& operator<<(extended-floating-point-type f);
3520
 
3521
+ basic_ostream& operator<<(const void* p);
3522
+ basic_ostream& operator<<(const volatile void* p);
3523
+ basic_ostream& operator<<(nullptr_t);
3524
+ basic_ostream& operator<<(basic_streambuf<char_type, traits>* sb);
3525
 
3526
  // [ostream.unformatted], unformatted output
3527
+ basic_ostream& put(char_type c);
3528
+ basic_ostream& write(const char_type* s, streamsize n);
3529
 
3530
+ basic_ostream& flush();
3531
 
3532
  // [ostream.seeks], seeks
3533
  pos_type tellp();
3534
+ basic_ostream& seekp(pos_type);
3535
+ basic_ostream& seekp(off_type, ios_base::seekdir);
3536
 
3537
  protected:
3538
  // [ostream.cons], copy/move constructor
3539
  basic_ostream(const basic_ostream&) = delete;
3540
  basic_ostream(basic_ostream&& rhs);
3541
 
3542
+ // [ostream.assign], assignment and swap
3543
  basic_ostream& operator=(const basic_ostream&) = delete;
3544
  basic_ostream& operator=(basic_ostream&& rhs);
3545
  void swap(basic_ostream& rhs);
3546
  };
3547
 
 
3677
 
3678
  ##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
3679
 
3680
  ``` cpp
3681
  namespace std {
3682
+ template<class charT, class traits>
3683
  class basic_ostream<charT, traits>::sentry {
3684
  bool ok_; // exposition only
3685
+
3686
  public:
3687
+ explicit sentry(basic_ostream& os);
3688
  ~sentry();
3689
  explicit operator bool() const { return ok_; }
3690
 
3691
  sentry(const sentry&) = delete;
3692
  sentry& operator=(const sentry&) = delete;
 
3696
 
3697
  The class `sentry` defines a class that is responsible for doing
3698
  exception safe prefix and suffix operations.
3699
 
3700
  ``` cpp
3701
+ explicit sentry(basic_ostream& os);
3702
  ```
3703
 
3704
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
3705
+ If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
3706
 
3707
  If, after any preparation is completed, `os.good()` is `true`,
3708
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
3709
  constructor may call `setstate(failbit)` (which may throw
3710
+ `ios_base::failure` [[iostate.flags]]).[^30]
3711
 
3712
  ``` cpp
3713
  ~sentry();
3714
  ```
3715
 
 
3735
 
3736
  *Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
3737
  failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
3738
 
3739
  ``` cpp
3740
+ basic_ostream& seekp(pos_type pos);
3741
  ```
3742
 
3743
  *Effects:* If `fail() != true`, executes
3744
  `rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
3745
  function calls `setstate(failbit)` (which may throw
3746
  `ios_base::failure`).
3747
 
3748
  *Returns:* `*this`.
3749
 
3750
  ``` cpp
3751
+ basic_ostream& seekp(off_type off, ios_base::seekdir dir);
3752
  ```
3753
 
3754
  *Effects:* If `fail() != true`, executes
3755
  `rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
3756
  function calls `setstate(failbit)` (which may throw
 
3761
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
3762
 
3763
  ##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
3764
 
3765
  Each formatted output function begins execution by constructing an
3766
+ object of class `sentry`. If that object returns `true` when converted
3767
  to a value of type `bool`, the function endeavors to generate the
3768
  requested output. If the generation fails, then the formatted output
3769
+ function does `setstate(ios_base::failbit)`, which can throw an
3770
  exception. If an exception is thrown during output, then
3771
+ `ios_base::badbit` is set[^31]
3772
+
3773
+ in `*this`’s error state. If `(exceptions()&badbit) != 0` then the
3774
+ exception is rethrown. Whether or not an exception is thrown, the
3775
+ `sentry` object is destroyed before leaving the formatted output
3776
+ function. If no exception is thrown, the result of the formatted output
3777
+ function is `*this`.
3778
 
3779
  The descriptions of the individual formatted output functions describe
3780
  how they perform output and do not mention the `sentry` object.
3781
 
3782
  If a formatted output function of a stream `os` determines padding, it
 
3789
  they are placed before the character sequence.
3790
 
3791
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
3792
 
3793
  ``` cpp
3794
+ basic_ostream& operator<<(bool val);
3795
+ basic_ostream& operator<<(short val);
3796
+ basic_ostream& operator<<(unsigned short val);
3797
+ basic_ostream& operator<<(int val);
3798
+ basic_ostream& operator<<(unsigned int val);
3799
+ basic_ostream& operator<<(long val);
3800
+ basic_ostream& operator<<(unsigned long val);
3801
+ basic_ostream& operator<<(long long val);
3802
+ basic_ostream& operator<<(unsigned long long val);
3803
+ basic_ostream& operator<<(float val);
3804
+ basic_ostream& operator<<(double val);
3805
+ basic_ostream& operator<<(long double val);
3806
+ basic_ostream& operator<<(const void* val);
3807
  ```
3808
 
3809
  *Effects:* The classes `num_get<>` and `num_put<>` handle
3810
  locale-dependent numeric formatting and parsing. These inserter
3811
  functions use the imbued `locale` value to perform numeric formatting.
 
3876
  from which to obtain other facets. If `failed` is `true` then does
3877
  `setstate(badbit)`, which may throw an exception, and returns.
3878
 
3879
  *Returns:* `*this`.
3880
 
3881
+ ``` cpp
3882
+ basic_ostream& operator<<(const volatile void* p);
3883
+ ```
3884
+
3885
+ *Effects:* Equivalent to:
3886
+ `return operator<<(const_cast<const void*>(p));`
3887
+
3888
+ ``` cpp
3889
+ basic_ostream& operator<<(extended-floating-point-type val);
3890
+ ```
3891
+
3892
+ *Effects:* If the floating-point conversion rank of
3893
+ *`extended-floating-point-type`* is less than or equal to that of
3894
+ `double`, the formatting conversion occurs as if it performed the
3895
+ following code fragment:
3896
+
3897
+ ``` cpp
3898
+ bool failed = use_facet<
3899
+ num_put<charT, ostreambuf_iterator<charT, traits>>
3900
+ >(getloc()).put(*this, *this, fill(),
3901
+ static_cast<double>(val)).failed();
3902
+ ```
3903
+
3904
+ Otherwise, if the floating-point conversion rank of
3905
+ *`extended-floating-point-type`* is less than or equal to that of
3906
+ `long double`, the formatting conversion occurs as if it performed the
3907
+ following code fragment:
3908
+
3909
+ ``` cpp
3910
+ bool failed = use_facet<
3911
+ num_put<charT, ostreambuf_iterator<charT, traits>>
3912
+ >(getloc()).put(*this, *this, fill(),
3913
+ static_cast<long double>(val)).failed();
3914
+ ```
3915
+
3916
+ Otherwise, an invocation of the operator function is conditionally
3917
+ supported with *implementation-defined* semantics.
3918
+
3919
+ If `failed` is `true` then does `setstate(badbit)`, which may throw an
3920
+ exception, and returns.
3921
+
3922
+ *Returns:* `*this`.
3923
+
3924
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
3925
 
3926
  ``` cpp
3927
+ basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&));
 
3928
  ```
3929
 
3930
  *Effects:* None. Does not behave as a formatted output function (as
3931
  described in  [[ostream.formatted.reqmts]]).
3932
 
3933
+ *Returns:* `pf(*this)`.[^32]
3934
 
3935
  ``` cpp
3936
+ basic_ostream& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
 
3937
  ```
3938
 
3939
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3940
  formatted output function (as described
3941
  in  [[ostream.formatted.reqmts]]).
3942
 
3943
+ *Returns:* `*this`.[^33]
3944
 
3945
  ``` cpp
3946
+ basic_ostream& operator<<(ios_base& (*pf)(ios_base&));
3947
  ```
3948
 
3949
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
3950
  formatted output function (as described
3951
  in  [[ostream.formatted.reqmts]]).
3952
 
3953
  *Returns:* `*this`.
3954
 
3955
  ``` cpp
3956
+ basic_ostream& operator<<(basic_streambuf<charT, traits>* sb);
3957
  ```
3958
 
3959
  *Effects:* Behaves as an unformatted output
3960
+ function [[ostream.unformatted]]. After the `sentry` object is
3961
  constructed, if `sb` is null calls `setstate(badbit)` (which may throw
3962
  `ios_base::failure`).
3963
 
3964
  Gets characters from `sb` and inserts them in `*this`. Characters are
3965
  read from `sb` and inserted until any of the following occurs:
 
3976
  exception is rethrown.
3977
 
3978
  *Returns:* `*this`.
3979
 
3980
  ``` cpp
3981
+ basic_ostream& operator<<(nullptr_t);
3982
  ```
3983
 
3984
  *Effects:* Equivalent to:
3985
 
3986
  ``` cpp
 
4053
  in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
4054
  `width(0)`.
4055
 
4056
  *Returns:* `out`.
4057
 
4058
+ ##### Print <a id="ostream.formatted.print">[[ostream.formatted.print]]</a>
4059
+
4060
+ ``` cpp
4061
+ template<class... Args>
4062
+ void print(ostream& os, format_string<Args...> fmt, Args&&... args);
4063
+ ```
4064
+
4065
+ *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
4066
+ equivalent to:
4067
+
4068
+ ``` cpp
4069
+ vprint_unicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
4070
+ ```
4071
+
4072
+ Otherwise, equivalent to:
4073
+
4074
+ ``` cpp
4075
+ vprint_nonunicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
4076
+ ```
4077
+
4078
+ ``` cpp
4079
+ template<class... Args>
4080
+ void println(ostream& os, format_string<Args...> fmt, Args&&... args);
4081
+ ```
4082
+
4083
+ *Effects:* Equivalent to:
4084
+
4085
+ ``` cpp
4086
+ print(os, "{}\n", format(fmt, std::forward<Args>(args)...));
4087
+ ```
4088
+
4089
+ ``` cpp
4090
+ void vprint_unicode(ostream& os, string_view fmt, format_args args);
4091
+ void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
4092
+ ```
4093
+
4094
+ *Effects:* Behaves as a formatted output
4095
+ function [[ostream.formatted.reqmts]] of `os`, except that:
4096
+
4097
+ - failure to generate output is reported as specified below, and
4098
+ - any exception thrown by the call to `vformat` is propagated without
4099
+ regard to the value of `os.exceptions()` and without turning on
4100
+ `ios_base::badbit` in the error state of `os`.
4101
+
4102
+ After constructing a `sentry` object, the function initializes an
4103
+ automatic variable via
4104
+
4105
+ ``` cpp
4106
+ string out = vformat(os.getloc(), fmt, args);
4107
+ ```
4108
+
4109
+ If the function is `vprint_unicode` and `os` is a stream that refers to
4110
+ a terminal capable of displaying Unicode which is determined in an
4111
+ implementation-defined manner, writes `out` to the terminal using the
4112
+ native Unicode API; if `out` contains invalid code units, the behavior
4113
+ is undefined and implementations are encouraged to diagnose it. If the
4114
+ native Unicode API is used, the function flushes `os` before writing
4115
+ `out`. Otherwise (if `os` is not such a stream or the function is
4116
+ `vprint_nonunicode`), inserts the character sequence \[`out.begin()`,
4117
+ `out.end()`) into `os`. If writing to the terminal or inserting into
4118
+ `os` fails, calls `os.setstate(ios_base::badbit)` (which may throw
4119
+ `ios_base::failure`).
4120
+
4121
+ *Recommended practice:* For `vprint_unicode`, if invoking the native
4122
+ Unicode API requires transcoding, implementations should substitute
4123
+ invalid code units with U+fffd (replacement character) per the Unicode
4124
+ Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
4125
+
4126
  #### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
4127
 
4128
  Each unformatted output function begins execution by constructing an
4129
+ object of class `sentry`. If that object returns `true`, while
4130
  converting to a value of type `bool`, the function endeavors to generate
4131
  the requested output. If an exception is thrown during output, then
4132
+ `ios_base::badbit` is set[^34]
4133
+
4134
+ in `*this`’s error state. If `(exceptions() & badbit) != 0` then the
4135
+ exception is rethrown. In any case, the unformatted output function ends
4136
+ by destroying the `sentry` object, then, if no exception was thrown,
4137
+ returning the value specified for the unformatted output function.
4138
 
4139
  ``` cpp
4140
+ basic_ostream& put(char_type c);
4141
  ```
4142
 
4143
  *Effects:* Behaves as an unformatted output function (as described
4144
+ above). After constructing a `sentry` object, inserts the character `c`,
4145
+ if possible.[^35]
4146
 
4147
  Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
4148
  [[iostate.flags]]).
4149
 
4150
  *Returns:* `*this`.
 
4152
  ``` cpp
4153
  basic_ostream& write(const char_type* s, streamsize n);
4154
  ```
4155
 
4156
  *Effects:* Behaves as an unformatted output function (as described
4157
+ above). After constructing a `sentry` object, obtains characters to
4158
+ insert from successive locations of an array whose first element is
4159
+ designated by `s`.[^36]
4160
+
4161
+ Characters are inserted until either of the following occurs:
4162
 
4163
  - `n` characters are inserted;
4164
  - inserting in the output sequence fails (in which case the function
4165
  calls `setstate(badbit)`, which may throw `ios_base::failure`
4166
  [[iostate.flags]]).
 
4170
  ``` cpp
4171
  basic_ostream& flush();
4172
  ```
4173
 
4174
  *Effects:* Behaves as an unformatted output function (as described
4175
+ above). If `rdbuf()` is not a null pointer, constructs a `sentry`
4176
+ object. If that object returns `true` when converted to a value of type
4177
+ `bool` the function calls `rdbuf()->pubsync()`. If that function returns
4178
+ -1 calls `setstate(badbit)` (which may throw `ios_base::failure`
4179
+ [[iostate.flags]]). Otherwise, if the `sentry` object returns `false`,
4180
  does nothing.
4181
 
4182
  *Returns:* `*this`.
4183
 
4184
  #### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
 
4248
  basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
4249
  ```
4250
 
4251
  *Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
4252
  `basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
4253
+ of exposition, behaves as an unformatted output
4254
+ function [[ostream.unformatted]] of `os`. After constructing a `sentry`
4255
+ object, calls `buf->emit()`. If that call returns `false`, calls
4256
+ `os.setstate(ios_base::badbit)`.
4257
 
4258
  *Returns:* `os`.
4259
 
4260
  #### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
4261
 
 
4285
  *Returns:* An object of unspecified type such that if `out` is an object
4286
  of type `basic_ostream<charT, traits>` then the expression
4287
  `out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
4288
  if `in` is an object of type `basic_istream<charT, traits>` then the
4289
  expression `in >> resetiosflags(mask)` behaves as if it called
4290
+ `f(in, mask)`, where the function `f` is defined as:[^37]
4291
 
4292
  ``` cpp
4293
  void f(ios_base& str, ios_base::fmtflags mask) {
4294
  // reset specified flags
4295
  str.setf(ios_base::fmtflags(0), mask);
 
4484
 
4485
  The expression `out << put_money(mon, intl)` has type
4486
  `basic_ostream<charT, traits>&` and value `out`.
4487
 
4488
  ``` cpp
4489
+ template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
4490
  ```
4491
 
4492
  *Preconditions:* The argument `tmb` is a valid pointer to an object of
4493
+ type `tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`) is a
4494
+ valid range.
4495
 
4496
  *Returns:* An object of unspecified type such that if `in` is an object
4497
  of type `basic_istream<charT, traits>` then the expression
4498
  `in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
4499
  where the function `f` is defined as:
4500
 
4501
  ``` cpp
4502
  template<class charT, class traits>
4503
+ void f(basic_ios<charT, traits>& str, tm* tmb, const charT* fmt) {
4504
  using Iter = istreambuf_iterator<charT, traits>;
4505
  using TimeGet = time_get<charT, Iter>;
4506
 
4507
  ios_base::iostate err = ios_base::goodbit;
4508
  const TimeGet& tg = use_facet<TimeGet>(str.getloc());
 
4517
 
4518
  The expression `in >> get_time(tmb, fmt)` has type
4519
  `basic_istream<charT, traits>&` and value `in`.
4520
 
4521
  ``` cpp
4522
+ template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
4523
  ```
4524
 
4525
  *Preconditions:* The argument `tmb` is a valid pointer to an object of
4526
+ type `tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`) is a
4527
+ valid range.
4528
 
4529
  *Returns:* An object of unspecified type such that if `out` is an object
4530
  of type `basic_ostream<charT, traits>` then the expression
4531
  `out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
4532
  where the function `f` is defined as:
4533
 
4534
  ``` cpp
4535
  template<class charT, class traits>
4536
+ void f(basic_ios<charT, traits>& str, const tm* tmb, const charT* fmt) {
4537
  using Iter = ostreambuf_iterator<charT, traits>;
4538
  using TimePut = time_put<charT, Iter>;
4539
 
4540
  const TimePut& tp = use_facet<TimePut>(str.getloc());
4541
  const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
 
4624
  - The expression `in >> quoted(s, delim, escape)` has type
4625
  `basic_istream<charT, traits>&` and value `in`.
4626
  - The expression `out << quoted(s, delim, escape)` has type
4627
  `basic_ostream<charT, traits>&` and value `out`.
4628
 
4629
+ ### Print functions <a id="print.fun">[[print.fun]]</a>
4630
+
4631
+ ``` cpp
4632
+ template<class... Args>
4633
+ void print(format_string<Args...> fmt, Args&&... args);
4634
+ ```
4635
+
4636
+ *Effects:* Equivalent to:
4637
+
4638
+ ``` cpp
4639
+ print(stdout, fmt, std::forward<Args>(args)...);
4640
+ ```
4641
+
4642
+ ``` cpp
4643
+ template<class... Args>
4644
+ void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
4645
+ ```
4646
+
4647
+ *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
4648
+ equivalent to:
4649
+
4650
+ ``` cpp
4651
+ vprint_unicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
4652
+ ```
4653
+
4654
+ Otherwise, equivalent to:
4655
+
4656
+ ``` cpp
4657
+ vprint_nonunicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
4658
+ ```
4659
+
4660
+ ``` cpp
4661
+ template<class... Args>
4662
+ void println(format_string<Args...> fmt, Args&&... args);
4663
+ ```
4664
+
4665
+ *Effects:* Equivalent to:
4666
+
4667
+ ``` cpp
4668
+ println(stdout, fmt, std::forward<Args>(args)...);
4669
+ ```
4670
+
4671
+ ``` cpp
4672
+ template<class... Args>
4673
+ void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
4674
+ ```
4675
+
4676
+ *Effects:* Equivalent to:
4677
+
4678
+ ``` cpp
4679
+ print(stream, "{}\n", format(fmt, std::forward<Args>(args)...));
4680
+ ```
4681
+
4682
+ ``` cpp
4683
+ void vprint_unicode(string_view fmt, format_args args);
4684
+ ```
4685
+
4686
+ *Effects:* Equivalent to:
4687
+
4688
+ ``` cpp
4689
+ vprint_unicode(stdout, fmt, args);
4690
+ ```
4691
+
4692
+ ``` cpp
4693
+ void vprint_unicode(FILE* stream, string_view fmt, format_args args);
4694
+ ```
4695
+
4696
+ *Preconditions:* `stream` is a valid pointer to an output C stream.
4697
+
4698
+ *Effects:* The function initializes an automatic variable via
4699
+
4700
+ ``` cpp
4701
+ string out = vformat(fmt, args);
4702
+ ```
4703
+
4704
+ If `stream` refers to a terminal capable of displaying Unicode, writes
4705
+ `out` to the terminal using the native Unicode API; if `out` contains
4706
+ invalid code units, the behavior is undefined and implementations are
4707
+ encouraged to diagnose it. Otherwise writes `out` to `stream` unchanged.
4708
+ If the native Unicode API is used, the function flushes `stream` before
4709
+ writing `out`.
4710
+
4711
+ [*Note 1*: On POSIX and Windows, `stream` referring to a terminal means
4712
+ that, respectively, `isatty(fileno(stream))` and
4713
+ `GetConsoleMode(_get_osfhandle(_fileno(stream)), ...)` return
4714
+ nonzero. — *end note*]
4715
+
4716
+ [*Note 2*: On Windows, the native Unicode API is
4717
+ `WriteConsoleW`. — *end note*]
4718
+
4719
+ *Throws:* Any exception thrown by the call to `vformat`
4720
+ [[format.err.report]]. `system_error` if writing to the terminal or
4721
+ `stream` fails. May throw `bad_alloc`.
4722
+
4723
+ *Recommended practice:* If invoking the native Unicode API requires
4724
+ transcoding, implementations should substitute invalid code units with
4725
+ U+fffd (replacement character) per the Unicode Standard, Chapter 3.9
4726
+ ‘U+fffd‘ Substitution in Conversion.
4727
+
4728
+ ``` cpp
4729
+ void vprint_nonunicode(string_view fmt, format_args args);
4730
+ ```
4731
+
4732
+ *Effects:* Equivalent to:
4733
+
4734
+ ``` cpp
4735
+ vprint_nonunicode(stdout, fmt, args);
4736
+ ```
4737
+
4738
+ ``` cpp
4739
+ void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
4740
+ ```
4741
+
4742
+ *Preconditions:* `stream` is a valid pointer to an output C stream.
4743
+
4744
+ *Effects:* Writes the result of `vformat(fmt, args)` to `stream`.
4745
+
4746
+ *Throws:* Any exception thrown by the call to `vformat`
4747
+ [[format.err.report]]. `system_error` if writing to `stream` fails. May
4748
+ throw `bad_alloc`.
4749
+
4750
  ## String-based streams <a id="string.streams">[[string.streams]]</a>
4751
 
4752
  ### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
4753
 
4754
  ``` cpp
4755
  namespace std {
4756
  template<class charT, class traits = char_traits<charT>,
4757
  class Allocator = allocator<charT>>
4758
  class basic_stringbuf;
4759
 
4760
+ template<class charT, class traits, class Allocator>
4761
+ void swap(basic_stringbuf<charT, traits, Allocator>& x,
4762
+ basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
4763
+
4764
  using stringbuf = basic_stringbuf<char>;
4765
  using wstringbuf = basic_stringbuf<wchar_t>;
4766
 
4767
  template<class charT, class traits = char_traits<charT>,
4768
  class Allocator = allocator<charT>>
4769
  class basic_istringstream;
4770
 
4771
+ template<class charT, class traits, class Allocator>
4772
+ void swap(basic_istringstream<charT, traits, Allocator>& x,
4773
+ basic_istringstream<charT, traits, Allocator>& y);
4774
+
4775
  using istringstream = basic_istringstream<char>;
4776
  using wistringstream = basic_istringstream<wchar_t>;
4777
 
4778
  template<class charT, class traits = char_traits<charT>,
4779
  class Allocator = allocator<charT>>
4780
  class basic_ostringstream;
4781
+
4782
+ template<class charT, class traits, class Allocator>
4783
+ void swap(basic_ostringstream<charT, traits, Allocator>& x,
4784
+ basic_ostringstream<charT, traits, Allocator>& y);
4785
+
4786
  using ostringstream = basic_ostringstream<char>;
4787
  using wostringstream = basic_ostringstream<wchar_t>;
4788
 
4789
  template<class charT, class traits = char_traits<charT>,
4790
  class Allocator = allocator<charT>>
4791
  class basic_stringstream;
4792
+
4793
+ template<class charT, class traits, class Allocator>
4794
+ void swap(basic_stringstream<charT, traits, Allocator>& x,
4795
+ basic_stringstream<charT, traits, Allocator>& y);
4796
+
4797
  using stringstream = basic_stringstream<char>;
4798
  using wstringstream = basic_stringstream<wchar_t>;
4799
  }
4800
  ```
4801
 
 
4803
  associate stream buffers with objects of class `basic_string`, as
4804
  described in  [[string.classes]].
4805
 
4806
  ### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
4807
 
4808
+ #### General <a id="stringbuf.general">[[stringbuf.general]]</a>
4809
+
4810
  ``` cpp
4811
  namespace std {
4812
  template<class charT, class traits = char_traits<charT>,
4813
  class Allocator = allocator<charT>>
4814
  class basic_stringbuf : public basic_streambuf<charT, traits> {
 
4846
  ios_base::openmode which = ios_base::in | ios_base::out);
4847
  basic_stringbuf(const basic_stringbuf&) = delete;
4848
  basic_stringbuf(basic_stringbuf&& rhs);
4849
  basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
4850
 
4851
+ // [stringbuf.assign], assignment and swap
4852
  basic_stringbuf& operator=(const basic_stringbuf&) = delete;
4853
  basic_stringbuf& operator=(basic_stringbuf&& rhs);
4854
  void swap(basic_stringbuf& rhs) noexcept(see below);
4855
 
4856
  // [stringbuf.members], getters and setters
 
4884
  private:
4885
  ios_base::openmode mode; // exposition only
4886
  basic_string<charT, traits, Allocator> buf; // exposition only
4887
  void init_buf_ptrs(); // exposition only
4888
  };
 
 
 
 
4889
  }
4890
  ```
4891
 
4892
  The class `basic_stringbuf` is derived from `basic_streambuf` to
4893
  associate possibly the input sequence and possibly the output sequence
 
5020
  void swap(basic_stringbuf& rhs) noexcept(see below);
5021
  ```
5022
 
5023
  *Preconditions:*
5024
  `allocator_traits<Allocator>::propagate_on_container_swap::value` is
5025
+ `true` or `get_allocator() == rhs.get_allocator()` is `true`.
5026
 
5027
  *Effects:* Exchanges the state of `*this` and `rhs`.
5028
 
5029
+ *Remarks:* The exception specification is equivalent to:
5030
  `allocator_traits<Allocator>::propagate_on_container_swap::value ||`
5031
  `allocator_traits<Allocator>::is_always_equal::value`.
5032
 
5033
  ``` cpp
5034
  template<class charT, class traits, class Allocator>
 
5066
  - otherwise `pptr() == pbase()` is `true`.
5067
  - If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
5068
  and `(gptr() == eback() && egptr() == eback() + buf.size())` is
5069
  `true`.
5070
 
5071
+ [*Note 1*: For efficiency reasons, stream buffer operations can violate
5072
+ invariants of `buf` while it is held encapsulated in the
5073
  `basic_stringbuf`, e.g., by writing to characters in the range
5074
  \[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
5075
  operations retrieving a `basic_string` from `buf` ensure that the
5076
  `basic_string` invariants hold on the returned value. — *end note*]
5077
 
 
5107
 
5108
  ``` cpp
5109
  basic_string<charT, traits, Allocator> str() &&;
5110
  ```
5111
 
5112
+ *Ensures:* The underlying character sequence `buf` is empty and
5113
+ `pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
5114
+ initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
5115
+
5116
  *Returns:* A `basic_string<charT, traits, Allocator>` object move
5117
  constructed from the `basic_stringbuf`’s underlying character sequence
5118
  in `buf`. This can be achieved by first adjusting `buf` to have the same
5119
  content as `view()`.
5120
 
 
 
 
 
5121
  ``` cpp
5122
  basic_string_view<charT, traits> view() const noexcept;
5123
  ```
5124
 
5125
  Let `sv` be `basic_string_view<charT, traits>`.
 
5195
  input sequence has a putback position available, and if
5196
  `traits::eq(to_char_type(c), gptr()[-1])` returns `true`, assigns
5197
  `gptr() - 1` to `gptr()`. Returns: `c`.
5198
  - If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
5199
  input sequence has a putback position available, and if `mode` `&`
5200
+ `ios_base::out` is nonzero, assigns `c` to `*gptr()`. Returns: `c`.
5201
  - If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
5202
  input sequence has a putback position available, assigns `gptr() - 1`
5203
  to `gptr()`. Returns: `traits::not_eof(c)`.
5204
 
5205
  *Returns:* As specified above, or `traits::eof()` to indicate failure.
 
5220
  function calls `sputc(c)`. Signals success by returning `c`.
5221
  - If `traits::eq_int_type(c, traits::eof())` returns `true`, there is no
5222
  character to append. Signals success by returning a value other than
5223
  `traits::eof()`.
5224
 
5225
+ *Returns:* As specified above, or `traits::eof()` to indicate failure.
5226
+
5227
  *Remarks:* The function can alter the number of write positions
5228
  available as a result of any call.
5229
 
 
 
5230
  The function can make a write position available only if `ios_base::out`
5231
  is set in `mode`. To make a write position available, the function
5232
  reallocates (or initially allocates) an array object with a sufficient
5233
  number of elements to hold the current array object (if any), plus at
5234
  least one additional write position. If `ios_base::in` is set in `mode`,
 
5289
 
5290
  *Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
5291
  indicate failure.
5292
 
5293
  ``` cpp
5294
+ basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n) override;
5295
  ```
5296
 
5297
  *Effects:* *implementation-defined*, except that `setbuf(0, 0)` has no
5298
  effect.
5299
 
5300
  *Returns:* `this`.
5301
 
5302
  ### Class template `basic_istringstream` <a id="istringstream">[[istringstream]]</a>
5303
 
5304
+ #### General <a id="istringstream.general">[[istringstream.general]]</a>
5305
+
5306
  ``` cpp
5307
  namespace std {
5308
  template<class charT, class traits = char_traits<charT>,
5309
  class Allocator = allocator<charT>>
5310
  class basic_istringstream : public basic_istream<charT, traits> {
 
5339
  const basic_string<charT, traits, SAlloc>& s,
5340
  ios_base::openmode which = ios_base::in);
5341
  basic_istringstream(const basic_istringstream&) = delete;
5342
  basic_istringstream(basic_istringstream&& rhs);
5343
 
 
5344
  basic_istringstream& operator=(const basic_istringstream&) = delete;
5345
  basic_istringstream& operator=(basic_istringstream&& rhs);
5346
+
5347
+ // [istringstream.swap], swap
5348
  void swap(basic_istringstream& rhs);
5349
 
5350
  // [istringstream.members], members
5351
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5352
  basic_string<charT, traits, Allocator> str() const &;
 
5361
  void str(basic_string<charT, traits, Allocator>&& s);
5362
 
5363
  private:
5364
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5365
  };
 
 
 
 
5366
  }
5367
  ```
5368
 
5369
  The class `basic_istringstream<charT, traits, Allocator>` supports
5370
  reading objects of class `basic_string<{}charT, traits, Allocator>`. It
 
5391
  ios_base::openmode which = ios_base::in);
5392
  ```
5393
 
5394
  *Effects:* Initializes the base class with
5395
  `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5396
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
5397
+ [[stringbuf.cons]].
5398
 
5399
  ``` cpp
5400
  basic_istringstream(ios_base::openmode which, const Allocator& a);
5401
  ```
5402
 
 
5423
  ios_base::openmode which, const Allocator& a);
5424
  ```
5425
 
5426
  *Effects:* Initializes the base class with
5427
  `basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
5428
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`
5429
+ [[stringbuf.cons]].
5430
 
5431
  ``` cpp
5432
  template<class SAlloc>
5433
  explicit basic_istringstream(
5434
  const basic_string<charT, traits, SAlloc>& s,
 
5448
  by move constructing the base class, and the contained
5449
  `basic_stringbuf`. Then calls
5450
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5451
  contained `basic_stringbuf`.
5452
 
5453
+ #### Swap <a id="istringstream.swap">[[istringstream.swap]]</a>
5454
 
5455
  ``` cpp
5456
  void swap(basic_istringstream& rhs);
5457
  ```
5458
 
 
5524
 
5525
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5526
 
5527
  ### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
5528
 
5529
+ #### General <a id="ostringstream.general">[[ostringstream.general]]</a>
5530
+
5531
  ``` cpp
5532
  namespace std {
5533
  template<class charT, class traits = char_traits<charT>,
5534
  class Allocator = allocator<charT>>
5535
  class basic_ostringstream : public basic_ostream<charT, traits> {
 
5564
  const basic_string<charT, traits, SAlloc>& s,
5565
  ios_base::openmode which = ios_base::out);
5566
  basic_ostringstream(const basic_ostringstream&) = delete;
5567
  basic_ostringstream(basic_ostringstream&& rhs);
5568
 
 
5569
  basic_ostringstream& operator=(const basic_ostringstream&) = delete;
5570
  basic_ostringstream& operator=(basic_ostringstream&& rhs);
5571
+
5572
+ // [ostringstream.swap], swap
5573
  void swap(basic_ostringstream& rhs);
5574
 
5575
  // [ostringstream.members], members
5576
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5577
 
 
5587
  void str(basic_string<charT, traits, Allocator>&& s);
5588
 
5589
  private:
5590
  basic_stringbuf<charT, traits, Allocator> sb; // exposition only
5591
  };
 
 
 
 
5592
  }
5593
  ```
5594
 
5595
  The class `basic_ostringstream<charT, traits, Allocator>` supports
5596
  writing objects of class `basic_string<{}charT, traits, Allocator>`. It
 
5616
  ios_base::openmode which = ios_base::out);
5617
  ```
5618
 
5619
  *Effects:* Initializes the base class with
5620
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5621
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
5622
+ [[stringbuf.cons]].
5623
 
5624
  ``` cpp
5625
  basic_ostringstream(ios_base::openmode which, const Allocator& a);
5626
  ```
5627
 
5628
  *Effects:* Initializes the base class with
5629
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5630
+ `basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`
5631
+ [[stringbuf.cons]].
5632
 
5633
  ``` cpp
5634
  explicit basic_ostringstream(
5635
  basic_string<charT, traits, Allocator>&& s,
5636
  ios_base::openmode which = ios_base::out);
 
5648
  ios_base::openmode which, const Allocator& a);
5649
  ```
5650
 
5651
  *Effects:* Initializes the base class with
5652
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5653
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`
5654
+ [[stringbuf.cons]].
5655
 
5656
  ``` cpp
5657
  template<class SAlloc>
5658
  explicit basic_ostringstream(
5659
  const basic_string<charT, traits, SAlloc>& s,
 
5662
 
5663
  *Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
5664
 
5665
  *Effects:* Initializes the base class with
5666
  `basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
5667
+ `basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
5668
+ [[stringbuf.cons]].
5669
 
5670
  ``` cpp
5671
  basic_ostringstream(basic_ostringstream&& rhs);
5672
  ```
5673
 
 
5675
  by move constructing the base class, and the contained
5676
  `basic_stringbuf`. Then calls
5677
  `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5678
  contained `basic_stringbuf`.
5679
 
5680
+ #### Swap <a id="ostringstream.swap">[[ostringstream.swap]]</a>
5681
 
5682
  ``` cpp
5683
  void swap(basic_ostringstream& rhs);
5684
  ```
5685
 
 
5751
 
5752
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5753
 
5754
  ### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
5755
 
5756
+ #### General <a id="stringstream.general">[[stringstream.general]]</a>
5757
+
5758
  ``` cpp
5759
  namespace std {
5760
  template<class charT, class traits = char_traits<charT>,
5761
  class Allocator = allocator<charT>>
5762
  class basic_stringstream : public basic_iostream<charT, traits> {
 
5791
  const basic_string<charT, traits, SAlloc>& s,
5792
  ios_base::openmode which = ios_base::out | ios_base::in);
5793
  basic_stringstream(const basic_stringstream&) = delete;
5794
  basic_stringstream(basic_stringstream&& rhs);
5795
 
 
5796
  basic_stringstream& operator=(const basic_stringstream&) = delete;
5797
  basic_stringstream& operator=(basic_stringstream&& rhs);
5798
+
5799
+ // [stringstream.swap], swap
5800
  void swap(basic_stringstream& rhs);
5801
 
5802
  // [stringstream.members], members
5803
  basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
5804
 
 
5814
  void str(basic_string<charT, traits, Allocator>&& s);
5815
 
5816
  private:
5817
  basic_stringbuf<charT, traits> sb; // exposition only
5818
  };
 
 
 
 
5819
  }
5820
  ```
5821
 
5822
  The class template `basic_stringstream<charT, traits>` supports reading
5823
  and writing from objects of class
 
5903
  by move constructing the base class, and the contained
5904
  `basic_stringbuf`. Then calls
5905
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
5906
  contained `basic_stringbuf`.
5907
 
5908
+ #### Swap <a id="stringstream.swap">[[stringstream.swap]]</a>
5909
 
5910
  ``` cpp
5911
  void swap(basic_stringstream& rhs);
5912
  ```
5913
 
 
5977
  void str(basic_string<charT, traits, Allocator>&& s);
5978
  ```
5979
 
5980
  *Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
5981
 
5982
+ ## Span-based streams <a id="span.streams">[[span.streams]]</a>
5983
+
5984
+ ### Overview <a id="span.streams.overview">[[span.streams.overview]]</a>
5985
+
5986
+ The header `<spanstream>` defines class templates and types that
5987
+ associate stream buffers with objects whose types are specializations of
5988
+ `span` as described in [[views.span]].
5989
+
5990
+ [*Note 1*: A user of these classes is responsible for ensuring that the
5991
+ character sequence represented by the given `span` outlives the use of
5992
+ the sequence by objects of the classes in subclause [[span.streams]].
5993
+ Using multiple `basic_spanbuf` objects referring to overlapping
5994
+ underlying sequences from different threads, where at least one
5995
+ `basic_spanbuf` object is used for writing to the sequence, results in a
5996
+ data race. — *end note*]
5997
+
5998
+ ### Header `<spanstream>` synopsis <a id="spanstream.syn">[[spanstream.syn]]</a>
5999
+
6000
+ ``` cpp
6001
+ namespace std {
6002
+ template<class charT, class traits = char_traits<charT>>
6003
+ class basic_spanbuf;
6004
+
6005
+ template<class charT, class traits>
6006
+ void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
6007
+
6008
+ using spanbuf = basic_spanbuf<char>;
6009
+ using wspanbuf = basic_spanbuf<wchar_t>;
6010
+
6011
+ template<class charT, class traits = char_traits<charT>>
6012
+ class basic_ispanstream;
6013
+
6014
+ template<class charT, class traits>
6015
+ void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
6016
+
6017
+ using ispanstream = basic_ispanstream<char>;
6018
+ using wispanstream = basic_ispanstream<wchar_t>;
6019
+
6020
+ template<class charT, class traits = char_traits<charT>>
6021
+ class basic_ospanstream;
6022
+
6023
+ template<class charT, class traits>
6024
+ void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
6025
+
6026
+ using ospanstream = basic_ospanstream<char>;
6027
+ using wospanstream = basic_ospanstream<wchar_t>;
6028
+
6029
+ template<class charT, class traits = char_traits<charT>>
6030
+ class basic_spanstream;
6031
+
6032
+ template<class charT, class traits>
6033
+ void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
6034
+
6035
+ using spanstream = basic_spanstream<char>;
6036
+ using wspanstream = basic_spanstream<wchar_t>;
6037
+ }
6038
+ ```
6039
+
6040
+ ### Class template `basic_spanbuf` <a id="spanbuf">[[spanbuf]]</a>
6041
+
6042
+ #### General <a id="spanbuf.general">[[spanbuf.general]]</a>
6043
+
6044
+ ``` cpp
6045
+ namespace std {
6046
+ template<class charT, class traits = char_traits<charT>>
6047
+ class basic_spanbuf
6048
+ : public basic_streambuf<charT, traits> {
6049
+ public:
6050
+ using char_type = charT;
6051
+ using int_type = typename traits::int_type;
6052
+ using pos_type = typename traits::pos_type;
6053
+ using off_type = typename traits::off_type;
6054
+ using traits_type = traits;
6055
+
6056
+ // [spanbuf.cons], constructors
6057
+ basic_spanbuf() : basic_spanbuf(ios_base::in | ios_base::out) {}
6058
+ explicit basic_spanbuf(ios_base::openmode which)
6059
+ : basic_spanbuf(std::span<charT>(), which) {}
6060
+ explicit basic_spanbuf(std::span<charT> s,
6061
+ ios_base::openmode which = ios_base::in | ios_base::out);
6062
+ basic_spanbuf(const basic_spanbuf&) = delete;
6063
+ basic_spanbuf(basic_spanbuf&& rhs);
6064
+
6065
+ // [spanbuf.assign], assignment and swap
6066
+ basic_spanbuf& operator=(const basic_spanbuf&) = delete;
6067
+ basic_spanbuf& operator=(basic_spanbuf&& rhs);
6068
+ void swap(basic_spanbuf& rhs);
6069
+
6070
+ // [spanbuf.members], member functions
6071
+ std::span<charT> span() const noexcept;
6072
+ void span(std::span<charT> s) noexcept;
6073
+
6074
+ protected:
6075
+ // [spanbuf.virtuals], overridden virtual functions
6076
+ basic_streambuf<charT, traits>* setbuf(charT*, streamsize) override;
6077
+ pos_type seekoff(off_type off, ios_base::seekdir way,
6078
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
6079
+ pos_type seekpos(pos_type sp,
6080
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
6081
+
6082
+ private:
6083
+ ios_base::openmode mode; // exposition only
6084
+ std::span<charT> buf; // exposition only
6085
+ };
6086
+ }
6087
+ ```
6088
+
6089
+ The class template `basic_spanbuf` is derived from `basic_streambuf` to
6090
+ associate possibly the input sequence and possibly the output sequence
6091
+ with a sequence of arbitrary characters. The sequence is provided by an
6092
+ object of class `span<charT>`.
6093
+
6094
+ For the sake of exposition, the maintained data is presented here as:
6095
+
6096
+ - `ios_base::openmode mode`, has `in` set if the input sequence can be
6097
+ read, and `out` set if the output sequence can be written.
6098
+ - `std::span<charT> buf` is the view to the underlying character
6099
+ sequence.
6100
+
6101
+ #### Constructors <a id="spanbuf.cons">[[spanbuf.cons]]</a>
6102
+
6103
+ ``` cpp
6104
+ explicit basic_spanbuf(std::span<charT> s,
6105
+ ios_base::openmode which = ios_base::in | ios_base::out);
6106
+ ```
6107
+
6108
+ *Effects:* Initializes the base class with `basic_streambuf()`
6109
+ [[streambuf.cons]], and *mode* with `which`. Initializes the internal
6110
+ pointers as if calling `span(s)`.
6111
+
6112
+ ``` cpp
6113
+ basic_spanbuf(basic_spanbuf&& rhs);
6114
+ ```
6115
+
6116
+ *Effects:* Initializes the base class with `std::move(rhs)` and *mode*
6117
+ with `std::move(rhs.`*`mode`*`)` and *buf* with
6118
+ `std::move(rhs.`*`buf`*`)`. The sequence pointers in `*this` (`eback()`,
6119
+ `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) obtain the values
6120
+ which `rhs` had. It is *implementation-defined* whether
6121
+ `rhs.`*`buf`*`.empty()` returns `true` after the move.
6122
+
6123
+ *Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
6124
+ construction.
6125
+
6126
+ - `span().data() == rhs_p.span().data()`
6127
+ - `span().size() == rhs_p.span().size()`
6128
+ - `eback() == rhs_p.eback()`
6129
+ - `gptr() == rhs_p.gptr()`
6130
+ - `egptr() == rhs_p.egptr()`
6131
+ - `pbase() == rhs_p.pbase()`
6132
+ - `pptr() == rhs_p.pptr()`
6133
+ - `epptr() == rhs_p.epptr()`
6134
+ - `getloc() == rhs_p.getloc()`
6135
+
6136
+ #### Assignment and swap <a id="spanbuf.assign">[[spanbuf.assign]]</a>
6137
+
6138
+ ``` cpp
6139
+ basic_spanbuf& operator=(basic_spanbuf&& rhs);
6140
+ ```
6141
+
6142
+ *Effects:* Equivalent to:
6143
+
6144
+ ``` cpp
6145
+ basic_spanbuf tmp{std::move(rhs)};
6146
+ this->swap(tmp);
6147
+ return *this;
6148
+ ```
6149
+
6150
+ ``` cpp
6151
+ void swap(basic_spanbuf& rhs);
6152
+ ```
6153
+
6154
+ *Effects:* Equivalent to:
6155
+
6156
+ ``` cpp
6157
+ basic_streambuf<charT, traits>::swap(rhs);
6158
+ std::swap(mode, rhs.mode);
6159
+ std::swap(buf, rhs.buf);
6160
+ ```
6161
+
6162
+ ``` cpp
6163
+ template<class charT, class traits>
6164
+ void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
6165
+ ```
6166
+
6167
+ *Effects:* Equivalent to `x.swap(y)`.
6168
+
6169
+ #### Member functions <a id="spanbuf.members">[[spanbuf.members]]</a>
6170
+
6171
+ ``` cpp
6172
+ std::span<charT> span() const noexcept;
6173
+ ```
6174
+
6175
+ *Returns:* If `ios_base::out` is set in *mode*, returns
6176
+ `std::span<charT>(pbase(), pptr())`, otherwise returns *buf*.
6177
+
6178
+ [*Note 1*: In contrast to `basic_stringbuf`, the underlying sequence
6179
+ never grows and is not owned. An owning copy can be obtained by
6180
+ converting the result to `basic_string<charT>`. — *end note*]
6181
+
6182
+ ``` cpp
6183
+ void span(std::span<charT> s) noexcept;
6184
+ ```
6185
+
6186
+ *Effects:* *`buf`*` = s`. Initializes the input and output sequences
6187
+ according to *mode*.
6188
+
6189
+ *Ensures:*
6190
+
6191
+ - If `ios_base::out` is set in *mode*,
6192
+ `pbase() == s.data() && epptr() == pbase() + s.size()` is `true`;
6193
+ - in addition, if `ios_base::ate` is set in *mode*,
6194
+ `pptr() == pbase() + s.size()` is `true`,
6195
+ - otherwise `pptr() == pbase()` is `true`.
6196
+ - If `ios_base::in` is set in *mode*,
6197
+ `eback() == s.data() && gptr() == eback() && egptr() == eback() + s.size()`
6198
+ is `true`.
6199
+
6200
+ #### Overridden virtual functions <a id="spanbuf.virtuals">[[spanbuf.virtuals]]</a>
6201
+
6202
+ [*Note 1*: Because the underlying buffer is of fixed size, neither
6203
+ `overflow`, `underflow`, nor `pbackfail` can provide useful
6204
+ behavior. — *end note*]
6205
+
6206
+ ``` cpp
6207
+ pos_type seekoff(off_type off, ios_base::seekdir way,
6208
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
6209
+ ```
6210
+
6211
+ *Effects:* Alters the stream position within one or both of the
6212
+ controlled sequences, if possible, as follows:
6213
+
6214
+ - If `ios_base::in` is set in `which`, positions the input sequence;
6215
+ `xnext` is `gptr()`, `xbeg` is `eback()`.
6216
+ - If `ios_base::out` is set in `which`, positions the output sequence;
6217
+ `xnext` is `pptr()`, `xbeg` is `pbase()`.
6218
+
6219
+ If both `ios_base::in` and `ios_base::out` are set in `which` and `way`
6220
+ is `ios_base::cur`, the positioning operation fails.
6221
+
6222
+ For a sequence to be positioned, if its next pointer `xnext` (either
6223
+ `gptr()` or `pptr()`) is a null pointer and the new offset `newoff` as
6224
+ computed below is nonzero, the positioning operation fails. Otherwise,
6225
+ the function determines `baseoff` as a value of type `off_type` as
6226
+ follows:
6227
+
6228
+ - `0` when `way` is `ios_base::beg`;
6229
+ - `(pptr() - pbase())` for the output sequence, or `(gptr() - eback())`
6230
+ for the input sequence when `way` is `ios_base::cur`;
6231
+ - when `way` is `ios_base::end` :
6232
+ - `(pptr() - pbase())` if `ios_base::out` is set in *mode* and
6233
+ `ios_base::in` is not set in *mode*,
6234
+ - `buf.size()` otherwise.
6235
+
6236
+ If `baseoff` + `off` would overflow, or if `baseoff` + `off` is less
6237
+ than zero, or if `baseoff` + `off` is greater than *`buf`*`.size()`, the
6238
+ positioning operation fails. Otherwise, the function computes
6239
+
6240
+ ``` cpp
6241
+ off_type newoff = baseoff + off;
6242
+ ```
6243
+
6244
+ and assigns `xbeg + newoff` to the next pointer `xnext`.
6245
+
6246
+ *Returns:* `pos_type(off_type(-1))` if the positioning operation fails;
6247
+ `pos_type(newoff)` otherwise.
6248
+
6249
+ ``` cpp
6250
+ pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override;
6251
+ ```
6252
+
6253
+ *Effects:* Equivalent to:
6254
+
6255
+ ``` cpp
6256
+ return seekoff(off_type(sp), ios_base::beg, which);
6257
+ ```
6258
+
6259
+ ``` cpp
6260
+ basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n) override;
6261
+ ```
6262
+
6263
+ *Effects:* Equivalent to:
6264
+
6265
+ ``` cpp
6266
+ this->span(std::span<charT>(s, n));
6267
+ return this;
6268
+ ```
6269
+
6270
+ ### Class template `basic_ispanstream` <a id="ispanstream">[[ispanstream]]</a>
6271
+
6272
+ #### General <a id="ispanstream.general">[[ispanstream.general]]</a>
6273
+
6274
+ ``` cpp
6275
+ namespace std {
6276
+ template<class charT, class traits = char_traits<charT>>
6277
+ class basic_ispanstream
6278
+ : public basic_istream<charT, traits> {
6279
+ public:
6280
+ using char_type = charT;
6281
+ using int_type = typename traits::int_type;
6282
+ using pos_type = typename traits::pos_type;
6283
+ using off_type = typename traits::off_type;
6284
+ using traits_type = traits;
6285
+
6286
+ // [ispanstream.cons], constructors
6287
+ explicit basic_ispanstream(std::span<charT> s,
6288
+ ios_base::openmode which = ios_base::in);
6289
+ basic_ispanstream(const basic_ispanstream&) = delete;
6290
+ basic_ispanstream(basic_ispanstream&& rhs);
6291
+ template<class ROS> explicit basic_ispanstream(ROS&& s);
6292
+
6293
+ basic_ispanstream& operator=(const basic_ispanstream&) = delete;
6294
+ basic_ispanstream& operator=(basic_ispanstream&& rhs);
6295
+
6296
+ // [ispanstream.swap], swap
6297
+ void swap(basic_ispanstream& rhs);
6298
+
6299
+ // [ispanstream.members], member functions
6300
+ basic_spanbuf<charT, traits>* rdbuf() const noexcept;
6301
+
6302
+ std::span<const charT> span() const noexcept;
6303
+ void span(std::span<charT> s) noexcept;
6304
+ template<class ROS> void span(ROS&& s) noexcept;
6305
+
6306
+ private:
6307
+ basic_spanbuf<charT, traits> sb; // exposition only
6308
+ };
6309
+ }
6310
+ ```
6311
+
6312
+ [*Note 1*: Constructing an `ispanstream` from a *string-literal*
6313
+ includes the termination character `'\0'` in the underlying
6314
+ `spanbuf`. — *end note*]
6315
+
6316
+ #### Constructors <a id="ispanstream.cons">[[ispanstream.cons]]</a>
6317
+
6318
+ ``` cpp
6319
+ explicit basic_ispanstream(std::span<charT> s, ios_base::openmode which = ios_base::in);
6320
+ ```
6321
+
6322
+ *Effects:* Initializes the base class with
6323
+ `basic_istream<charT, traits>(addressof(sb))` and `sb` with
6324
+ `basic_spanbuf<charT, traits>(s, which | ios_base::in)`
6325
+ [[spanbuf.cons]].
6326
+
6327
+ ``` cpp
6328
+ basic_ispanstream(basic_ispanstream&& rhs);
6329
+ ```
6330
+
6331
+ *Effects:* Initializes the base class with `std::move(rhs)` and `sb`
6332
+ with `std::move(rhs.sb)`. Next,
6333
+ `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` is called to
6334
+ install the contained `basic_spanbuf`.
6335
+
6336
+ ``` cpp
6337
+ template<class ROS> explicit basic_ispanstream(ROS&& s)
6338
+ ```
6339
+
6340
+ *Constraints:* `ROS` models `ranges::borrowed_range`.
6341
+ `!convertible_to<ROS, std::span<charT>> && convertible_to<ROS, std::span<charT const>>`
6342
+ is `true`.
6343
+
6344
+ *Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
6345
+ Equivalent to
6346
+
6347
+ ``` cpp
6348
+ basic_ispanstream(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
6349
+ ```
6350
+
6351
+ #### Swap <a id="ispanstream.swap">[[ispanstream.swap]]</a>
6352
+
6353
+ ``` cpp
6354
+ void swap(basic_ispanstream& rhs);
6355
+ ```
6356
+
6357
+ *Effects:* Equivalent to:
6358
+
6359
+ ``` cpp
6360
+ basic_istream<charT, traits>::swap(rhs);
6361
+ sb.swap(rhs.sb);
6362
+ ```
6363
+
6364
+ ``` cpp
6365
+ template<class charT, class traits>
6366
+ void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
6367
+ ```
6368
+
6369
+ *Effects:* Equivalent to `x.swap(y)`.
6370
+
6371
+ #### Member functions <a id="ispanstream.members">[[ispanstream.members]]</a>
6372
+
6373
+ ``` cpp
6374
+ basic_spanbuf<charT, traits>* rdbuf() const noexcept;
6375
+ ```
6376
+
6377
+ *Effects:* Equivalent to:
6378
+
6379
+ ``` cpp
6380
+ return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
6381
+ ```
6382
+
6383
+ ``` cpp
6384
+ std::span<const charT> span() const noexcept;
6385
+ ```
6386
+
6387
+ *Effects:* Equivalent to: `return rdbuf()->span();`
6388
+
6389
+ ``` cpp
6390
+ void span(std::span<charT> s) noexcept;
6391
+ ```
6392
+
6393
+ *Effects:* Equivalent to `rdbuf()->span(s)`.
6394
+
6395
+ ``` cpp
6396
+ template<class ROS> void span(ROS&& s) noexcept;
6397
+ ```
6398
+
6399
+ *Constraints:* `ROS` models `ranges::borrowed_range`.
6400
+ `(!convertible_to<ROS, std::span<charT>>) && convertible_to<ROS, std::span<const charT>>`
6401
+ is `true`.
6402
+
6403
+ *Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
6404
+ Equivalent to:
6405
+
6406
+ ``` cpp
6407
+ this->span(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
6408
+ ```
6409
+
6410
+ ### Class template `basic_ospanstream` <a id="ospanstream">[[ospanstream]]</a>
6411
+
6412
+ #### General <a id="ospanstream.general">[[ospanstream.general]]</a>
6413
+
6414
+ ``` cpp
6415
+ namespace std {
6416
+ template<class charT, class traits = char_traits<charT>>
6417
+ class basic_ospanstream
6418
+ : public basic_ostream<charT, traits> {
6419
+ public:
6420
+ using char_type = charT;
6421
+ using int_type = typename traits::int_type;
6422
+ using pos_type = typename traits::pos_type;
6423
+ using off_type = typename traits::off_type;
6424
+ using traits_type = traits;
6425
+
6426
+ // [ospanstream.cons], constructors
6427
+ explicit basic_ospanstream(std::span<charT> s,
6428
+ ios_base::openmode which = ios_base::out);
6429
+ basic_ospanstream(const basic_ospanstream&) = delete;
6430
+ basic_ospanstream(basic_ospanstream&& rhs);
6431
+
6432
+ basic_ospanstream& operator=(const basic_ospanstream&) = delete;
6433
+ basic_ospanstream& operator=(basic_ospanstream&& rhs);
6434
+
6435
+ // [ospanstream.swap], swap
6436
+ void swap(basic_ospanstream& rhs);
6437
+
6438
+ // [ospanstream.members], member functions
6439
+ basic_spanbuf<charT, traits>* rdbuf() const noexcept;
6440
+
6441
+ std::span<charT> span() const noexcept;
6442
+ void span(std::span<charT> s) noexcept;
6443
+
6444
+ private:
6445
+ basic_spanbuf<charT, traits> sb; // exposition only
6446
+ };
6447
+ }
6448
+ ```
6449
+
6450
+ #### Constructors <a id="ospanstream.cons">[[ospanstream.cons]]</a>
6451
+
6452
+ ``` cpp
6453
+ explicit basic_ospanstream(std::span<charT> s,
6454
+ ios_base::openmode which = ios_base::out);
6455
+ ```
6456
+
6457
+ *Effects:* Initializes the base class with
6458
+ `basic_ostream<charT, traits>(addressof(sb))` and `sb` with
6459
+ `basic_spanbuf<charT, traits>(s, which | ios_base::out)`
6460
+ [[spanbuf.cons]].
6461
+
6462
+ ``` cpp
6463
+ basic_ospanstream(basic_ospanstream&& rhs) noexcept;
6464
+ ```
6465
+
6466
+ *Effects:* Initializes the base class with `std::move(rhs)` and `sb`
6467
+ with `std::move(rhs.sb)`. Next,
6468
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` is called to
6469
+ install the contained `basic_spanbuf`.
6470
+
6471
+ #### Swap <a id="ospanstream.swap">[[ospanstream.swap]]</a>
6472
+
6473
+ ``` cpp
6474
+ void swap(basic_ospanstream& rhs);
6475
+ ```
6476
+
6477
+ *Effects:* Equivalent to:
6478
+
6479
+ ``` cpp
6480
+ basic_ostream<charT, traits>::swap(rhs);
6481
+ sb.swap(rhs.sb);
6482
+ ```
6483
+
6484
+ ``` cpp
6485
+ template<class charT, class traits>
6486
+ void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
6487
+ ```
6488
+
6489
+ *Effects:* Equivalent to `x.swap(y)`.
6490
+
6491
+ #### Member functions <a id="ospanstream.members">[[ospanstream.members]]</a>
6492
+
6493
+ ``` cpp
6494
+ basic_spanbuf<charT, traits>* rdbuf() const noexcept;
6495
+ ```
6496
+
6497
+ *Effects:* Equivalent to:
6498
+
6499
+ ``` cpp
6500
+ return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
6501
+ ```
6502
+
6503
+ ``` cpp
6504
+ std::span<charT> span() const noexcept;
6505
+ ```
6506
+
6507
+ *Effects:* Equivalent to: `return rdbuf()->span();`
6508
+
6509
+ ``` cpp
6510
+ void span(std::span<charT> s) noexcept;
6511
+ ```
6512
+
6513
+ *Effects:* Equivalent to `rdbuf()->span(s)`.
6514
+
6515
+ ### Class template `basic_spanstream` <a id="spanstream">[[spanstream]]</a>
6516
+
6517
+ #### General <a id="spanstream.general">[[spanstream.general]]</a>
6518
+
6519
+ ``` cpp
6520
+ namespace std {
6521
+ template<class charT, class traits = char_traits<charT>>
6522
+ class basic_spanstream
6523
+ : public basic_iostream<charT, traits> {
6524
+ public:
6525
+ using char_type = charT;
6526
+ using int_type = typename traits::int_type;
6527
+ using pos_type = typename traits::pos_type;
6528
+ using off_type = typename traits::off_type;
6529
+ using traits_type = traits;
6530
+
6531
+ // [spanstream.cons], constructors
6532
+ explicit basic_spanstream(std::span<charT> s,
6533
+ ios_base::openmode which = ios_base::out | ios_base::in);
6534
+ basic_spanstream(const basic_spanstream&) = delete;
6535
+ basic_spanstream(basic_spanstream&& rhs);
6536
+
6537
+ basic_spanstream& operator=(const basic_spanstream&) = delete;
6538
+ basic_spanstream& operator=(basic_spanstream&& rhs);
6539
+
6540
+ // [spanstream.swap], swap
6541
+ void swap(basic_spanstream& rhs);
6542
+
6543
+ // [spanstream.members], members
6544
+ basic_spanbuf<charT, traits>* rdbuf() const noexcept;
6545
+
6546
+ std::span<charT> span() const noexcept;
6547
+ void span(std::span<charT> s) noexcept;
6548
+
6549
+ private:
6550
+ basic_spanbuf<charT, traits> sb; // exposition only
6551
+ };
6552
+ }
6553
+ ```
6554
+
6555
+ #### Constructors <a id="spanstream.cons">[[spanstream.cons]]</a>
6556
+
6557
+ ``` cpp
6558
+ explicit basic_spanstream(std::span<charT> s,
6559
+ ios_base::openmode which = ios_base::out | ios_bas::in);
6560
+ ```
6561
+
6562
+ *Effects:* Initializes the base class with
6563
+ `basic_iostream<charT, traits>(addressof(sb))` and `sb` with
6564
+ `basic_spanbuf<charT, traits>(s, which)` [[spanbuf.cons]].
6565
+
6566
+ ``` cpp
6567
+ basic_spanstream(basic_spanstream&& rhs);
6568
+ ```
6569
+
6570
+ *Effects:* Initializes the base class with `std::move(rhs)` and `sb`
6571
+ with `std::move(rhs.sb)`. Next,
6572
+ `basic_iostream<charT, traits>::set_rdbuf(addressof(sb))` is called to
6573
+ install the contained `basic_spanbuf`.
6574
+
6575
+ #### Swap <a id="spanstream.swap">[[spanstream.swap]]</a>
6576
+
6577
+ ``` cpp
6578
+ void swap(basic_spanstream& rhs);
6579
+ ```
6580
+
6581
+ *Effects:* Equivalent to:
6582
+
6583
+ ``` cpp
6584
+ basic_iostream<charT, traits>::swap(rhs);
6585
+ sb.swap(rhs.sb);
6586
+ ```
6587
+
6588
+ ``` cpp
6589
+ template<class charT, class traits>
6590
+ void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
6591
+ ```
6592
+
6593
+ *Effects:* Equivalent to `x.swap(y)`.
6594
+
6595
+ #### Member functions <a id="spanstream.members">[[spanstream.members]]</a>
6596
+
6597
+ ``` cpp
6598
+ basic_spanbuf<charT, traits>* rdbuf() const noexcept;
6599
+ ```
6600
+
6601
+ *Effects:* Equivalent to:
6602
+
6603
+ ``` cpp
6604
+ return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
6605
+ ```
6606
+
6607
+ ``` cpp
6608
+ std::span<charT> span() const noexcept;
6609
+ ```
6610
+
6611
+ *Effects:* Equivalent to: `return rdbuf()->span();`
6612
+
6613
+ ``` cpp
6614
+ void span(std::span<charT> s) noexcept;
6615
+ ```
6616
+
6617
+ *Effects:* Equivalent to `rdbuf()->span(s)`.
6618
+
6619
  ## File-based streams <a id="file.streams">[[file.streams]]</a>
6620
 
6621
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
6622
 
6623
  ``` cpp
6624
  namespace std {
6625
  template<class charT, class traits = char_traits<charT>>
6626
  class basic_filebuf;
6627
+
6628
+ template<class charT, class traits>
6629
+ void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
6630
+
6631
  using filebuf = basic_filebuf<char>;
6632
  using wfilebuf = basic_filebuf<wchar_t>;
6633
 
6634
  template<class charT, class traits = char_traits<charT>>
6635
  class basic_ifstream;
6636
+
6637
+ template<class charT, class traits>
6638
+ void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
6639
+
6640
  using ifstream = basic_ifstream<char>;
6641
  using wifstream = basic_ifstream<wchar_t>;
6642
 
6643
  template<class charT, class traits = char_traits<charT>>
6644
  class basic_ofstream;
6645
+
6646
+ template<class charT, class traits>
6647
+ void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
6648
+
6649
  using ofstream = basic_ofstream<char>;
6650
  using wofstream = basic_ofstream<wchar_t>;
6651
 
6652
  template<class charT, class traits = char_traits<charT>>
6653
  class basic_fstream;
6654
+
6655
+ template<class charT, class traits>
6656
+ void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);
6657
+
6658
  using fstream = basic_fstream<char>;
6659
  using wfstream = basic_fstream<wchar_t>;
6660
  }
6661
  ```
6662
 
 
6669
  file typically holds multibyte character sequences and the
6670
  `basic_filebuf` object converts those multibyte sequences into wide
6671
  character sequences. — *end note*]
6672
 
6673
  In subclause  [[file.streams]], member functions taking arguments of
6674
+ `const filesystem::path::value_type*` are only provided on systems where
6675
+ `filesystem::path::value_type` [[fs.class.path]] is not `char`.
6676
 
6677
  [*Note 2*: These functions enable class `path` support for systems with
6678
  a wide native path character type, such as `wchar_t`. — *end note*]
6679
 
6680
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
6681
 
6682
+ #### General <a id="filebuf.general">[[filebuf.general]]</a>
6683
+
6684
  ``` cpp
6685
  namespace std {
6686
  template<class charT, class traits = char_traits<charT>>
6687
  class basic_filebuf : public basic_streambuf<charT, traits> {
6688
  public:
 
6696
  basic_filebuf();
6697
  basic_filebuf(const basic_filebuf&) = delete;
6698
  basic_filebuf(basic_filebuf&& rhs);
6699
  virtual ~basic_filebuf();
6700
 
6701
+ // [filebuf.assign], assignment and swap
6702
  basic_filebuf& operator=(const basic_filebuf&) = delete;
6703
  basic_filebuf& operator=(basic_filebuf&& rhs);
6704
  void swap(basic_filebuf& rhs);
6705
 
6706
  // [filebuf.members], members
 
6731
  ios_base::openmode which
6732
  = ios_base::in | ios_base::out) override;
6733
  int sync() override;
6734
  void imbue(const locale& loc) override;
6735
  };
 
 
 
 
6736
  }
6737
  ```
6738
 
6739
  The class `basic_filebuf<charT, traits>` associates both the input
6740
  sequence and the output sequence with a file.
 
6832
 
6833
  *Effects:* Exchanges the state of `*this` and `rhs`.
6834
 
6835
  ``` cpp
6836
  template<class charT, class traits>
6837
+ void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
 
6838
  ```
6839
 
6840
  *Effects:* Equivalent to: `x.swap(y)`.
6841
 
6842
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
 
6863
  [[filebuf.open.modes]]. If `mode` is not some combination of flags shown
6864
  in the table then the open fails.
6865
 
6866
  **Table: File open modes** <a id="filebuf.open.modes">[filebuf.open.modes]</a>
6867
 
6868
+ | `binary` | `in` | `out` | `trunc` | `app` | `noreplace` | `stdio` equivalent |
6869
+ | -------- | ---- | ----- | ------- | ----- | ----------- | ------------------ |
6870
+ | | | + | | | | `"w"` |
6871
+ | | | + | | | + | `"wx"` |
6872
+ | | | + | + | | | `"w"` |
6873
+ | | | + | + | | + | `"wx"` |
6874
+ | | | + | | + | | `"a"` |
6875
+ | | | | | + | | `"a"` |
6876
+ | | + | | | | | `"r"` |
6877
+ | | + | + | | | | `"r+"` |
6878
+ | | + | + | + | | | `"w+"` |
6879
+ | | + | + | + | | + | `"w+x"` |
6880
+ | | + | + | | + | | `"a+"` |
6881
+ | | + | | | + | | `"a+"` |
6882
+ | + | | + | | | | `"wb"` |
6883
+ | + | | + | | | + | `"wbx"` |
6884
+ | + | | + | + | | | `"wb"` |
6885
+ | + | | + | + | | + | `"wbx"` |
6886
+ | + | | + | | + | | `"ab"` |
6887
+ | + | | | | + | | `"ab"` |
6888
+ | + | + | | | | | `"rb"` |
6889
+ | + | + | + | | | | `"r+b"` |
6890
+ | + | + | + | + | | | `"w+b"` |
6891
+ | + | + | + | + | | + | `"w+bx"` |
6892
+ | + | + | + | | + | | `"a+b"` |
6893
+ | + | + | | | + | | `"a+b"` |
6894
 
6895
 
6896
  If the open operation succeeds and `ios_base::ate` is set in `mode`,
6897
  positions the file to the end (as if by calling
6898
  `fseek(file, 0, SEEK_END)`, where `file` is the pointer returned by
6899
+ calling `fopen`).[^38]
6900
 
6901
  If the repositioning operation fails, calls `close()` and returns a null
6902
  pointer to indicate failure.
6903
 
6904
  *Returns:* `this` if successful, a null pointer otherwise.
 
6925
  `fclose(file)`). If any of the calls made by the function, including
6926
  `fclose`, fails, `close` fails by returning a null pointer. If one of
6927
  these calls throws an exception, the exception is caught and rethrown
6928
  after closing the file.
6929
 
6930
+ *Ensures:* `is_open() == false`.
6931
+
6932
  *Returns:* `this` on success, a null pointer otherwise.
6933
 
 
 
6934
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
6935
 
6936
  ``` cpp
6937
  streamsize showmanyc() override;
6938
  ```
6939
 
6940
  *Effects:* Behaves the same as `basic_streambuf::showmanyc()`
6941
  [[streambuf.virtuals]].
6942
 
6943
+ *Remarks:* An implementation may provide an overriding definition for
6944
+ this function signature if it can determine whether more characters can
6945
  be read from the input sequence.
6946
 
6947
  ``` cpp
6948
  int_type underflow() override;
6949
  ```
 
7065
  and if the last operation was output, then update the output sequence
7066
  and write any unshift sequence. Next, seek to the new position: if
7067
  `width > 0`, call `fseek(file, width * off, whence)`, otherwise call
7068
  `fseek(file, 0, whence)`.
7069
 
7070
+ *Returns:* A newly constructed `pos_type` object that stores the
7071
+ resultant stream position, if possible. If the positioning operation
7072
+ fails, or if the object cannot represent the resultant stream position,
7073
+ returns `pos_type(off_type(-1))`.
7074
+
7075
  *Remarks:* “The last operation was output” means either the last virtual
7076
  operation was overflow or the put buffer is non-empty. “Write any
7077
  unshift sequence” means, if `width` if less than zero then call
7078
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
7079
  resulting unshift sequence. The function determines one of three values
 
7086
  | ---------------- | ------------------ |
7087
  | `basic_ios::beg` | `SEEK_SET` |
7088
  | `basic_ios::cur` | `SEEK_CUR` |
7089
  | `basic_ios::end` | `SEEK_END` |
7090
 
 
 
 
 
 
 
7091
  ``` cpp
7092
  pos_type seekpos(pos_type sp,
7093
  ios_base::openmode which
7094
  = ios_base::in | ios_base::out) override;
7095
  ```
 
7139
  characters. This in turn may require the implementation to be able to
7140
  reconstruct the original contents of the file.
7141
 
7142
  ### Class template `basic_ifstream` <a id="ifstream">[[ifstream]]</a>
7143
 
7144
+ #### General <a id="ifstream.general">[[ifstream.general]]</a>
7145
+
7146
  ``` cpp
7147
  namespace std {
7148
  template<class charT, class traits = char_traits<charT>>
7149
  class basic_ifstream : public basic_istream<charT, traits> {
7150
  public:
 
7160
  ios_base::openmode mode = ios_base::in);
7161
  explicit basic_ifstream(const filesystem::path::value_type* s,
7162
  ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
7163
  explicit basic_ifstream(const string& s,
7164
  ios_base::openmode mode = ios_base::in);
7165
+ template<class T>
7166
+ explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
7167
  basic_ifstream(const basic_ifstream&) = delete;
7168
  basic_ifstream(basic_ifstream&& rhs);
7169
 
 
7170
  basic_ifstream& operator=(const basic_ifstream&) = delete;
7171
  basic_ifstream& operator=(basic_ifstream&& rhs);
7172
+
7173
+ // [ifstream.swap], swap
7174
  void swap(basic_ifstream& rhs);
7175
 
7176
  // [ifstream.members], members
7177
  basic_filebuf<charT, traits>* rdbuf() const;
7178
 
 
7181
  void open(const filesystem::path::value_type* s,
7182
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
7183
  void open(const string& s, ios_base::openmode mode = ios_base::in);
7184
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
7185
  void close();
7186
+
7187
  private:
7188
  basic_filebuf<charT, traits> sb; // exposition only
7189
  };
 
 
 
 
7190
  }
7191
  ```
7192
 
7193
  The class `basic_ifstream<charT, traits>` supports reading from named
7194
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
 
7221
  pointer, calls `setstate(failbit)`.
7222
 
7223
  ``` cpp
7224
  explicit basic_ifstream(const string& s,
7225
  ios_base::openmode mode = ios_base::in);
 
 
7226
  ```
7227
 
7228
  *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
7229
 
7230
+ ``` cpp
7231
+ template<class T>
7232
+ explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
7233
+ ```
7234
+
7235
+ *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7236
+
7237
+ *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
7238
+
7239
  ``` cpp
7240
  basic_ifstream(basic_ifstream&& rhs);
7241
  ```
7242
 
7243
  *Effects:* Move constructs the base class, and the contained
7244
  `basic_filebuf`. Then calls
7245
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
7246
  contained `basic_filebuf`.
7247
 
7248
+ #### Swap <a id="ifstream.swap">[[ifstream.swap]]</a>
7249
 
7250
  ``` cpp
7251
  void swap(basic_ifstream& rhs);
7252
  ```
7253
 
7254
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7255
  `basic_istream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
7256
 
7257
  ``` cpp
7258
  template<class charT, class traits>
7259
+ void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
 
7260
  ```
7261
 
7262
  *Effects:* Equivalent to: `x.swap(y)`.
7263
 
7264
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
 
7301
  pointer, calls `setstate(failbit)` (which may throw
7302
  `ios_base::failure`) [[iostate.flags]].
7303
 
7304
  ### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
7305
 
7306
+ #### General <a id="ofstream.general">[[ofstream.general]]</a>
7307
+
7308
  ``` cpp
7309
  namespace std {
7310
  template<class charT, class traits = char_traits<charT>>
7311
  class basic_ofstream : public basic_ostream<charT, traits> {
7312
  public:
 
7322
  ios_base::openmode mode = ios_base::out);
7323
  explicit basic_ofstream(const filesystem::path::value_type* s, // wide systems only; see [fstream.syn]
7324
  ios_base::openmode mode = ios_base::out);
7325
  explicit basic_ofstream(const string& s,
7326
  ios_base::openmode mode = ios_base::out);
7327
+ template<class T>
7328
+ explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
7329
  basic_ofstream(const basic_ofstream&) = delete;
7330
  basic_ofstream(basic_ofstream&& rhs);
7331
 
 
7332
  basic_ofstream& operator=(const basic_ofstream&) = delete;
7333
  basic_ofstream& operator=(basic_ofstream&& rhs);
7334
+
7335
+ // [ofstream.swap], swap
7336
  void swap(basic_ofstream& rhs);
7337
 
7338
  // [ofstream.members], members
7339
  basic_filebuf<charT, traits>* rdbuf() const;
7340
 
 
7343
  void open(const filesystem::path::value_type* s,
7344
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
7345
  void open(const string& s, ios_base::openmode mode = ios_base::out);
7346
  void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
7347
  void close();
7348
+
7349
  private:
7350
  basic_filebuf<charT, traits> sb; // exposition only
7351
  };
 
 
 
 
7352
  }
7353
  ```
7354
 
7355
  The class `basic_ofstream<charT, traits>` supports writing to named
7356
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
 
7383
  null pointer, calls `setstate(failbit)`.
7384
 
7385
  ``` cpp
7386
  explicit basic_ofstream(const string& s,
7387
  ios_base::openmode mode = ios_base::out);
 
 
7388
  ```
7389
 
7390
  *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
7391
 
7392
+ ``` cpp
7393
+ template<class T>
7394
+ explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
7395
+ ```
7396
+
7397
+ *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7398
+
7399
+ *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
7400
+
7401
  ``` cpp
7402
  basic_ofstream(basic_ofstream&& rhs);
7403
  ```
7404
 
7405
  *Effects:* Move constructs the base class, and the contained
7406
  `basic_filebuf`. Then calls
7407
  `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
7408
  contained `basic_filebuf`.
7409
 
7410
+ #### Swap <a id="ofstream.swap">[[ofstream.swap]]</a>
7411
 
7412
  ``` cpp
7413
  void swap(basic_ofstream& rhs);
7414
  ```
7415
 
7416
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
7417
  `basic_ostream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
7418
 
7419
  ``` cpp
7420
  template<class charT, class traits>
7421
+ void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
 
7422
  ```
7423
 
7424
  *Effects:* Equivalent to: `x.swap(y)`.
7425
 
7426
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
 
7463
 
7464
  *Effects:* Calls `open(s.c_str(), mode)`.
7465
 
7466
  ### Class template `basic_fstream` <a id="fstream">[[fstream]]</a>
7467
 
7468
+ #### General <a id="fstream.general">[[fstream.general]]</a>
7469
+
7470
  ``` cpp
7471
  namespace std {
7472
  template<class charT, class traits = char_traits<charT>>
7473
  class basic_fstream : public basic_iostream<charT, traits> {
7474
  public:
 
7487
  const filesystem::path::value_type* s,
7488
  ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
7489
  explicit basic_fstream(
7490
  const string& s,
7491
  ios_base::openmode mode = ios_base::in | ios_base::out);
7492
+ template<class T>
7493
+ explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
 
7494
  basic_fstream(const basic_fstream&) = delete;
7495
  basic_fstream(basic_fstream&& rhs);
7496
 
 
7497
  basic_fstream& operator=(const basic_fstream&) = delete;
7498
  basic_fstream& operator=(basic_fstream&& rhs);
7499
+
7500
+ // [fstream.swap], swap
7501
  void swap(basic_fstream& rhs);
7502
 
7503
  // [fstream.members], members
7504
  basic_filebuf<charT, traits>* rdbuf() const;
7505
  bool is_open() const;
 
7518
  void close();
7519
 
7520
  private:
7521
  basic_filebuf<charT, traits> sb; // exposition only
7522
  };
 
 
 
 
7523
  }
7524
  ```
7525
 
7526
  The class template `basic_fstream<charT, traits>` supports reading and
7527
  writing from named files. It uses a `basic_filebuf<charT, traits>`
 
7557
 
7558
  ``` cpp
7559
  explicit basic_fstream(
7560
  const string& s,
7561
  ios_base::openmode mode = ios_base::in | ios_base::out);
 
 
 
7562
  ```
7563
 
7564
  *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
7565
 
7566
+ ``` cpp
7567
+ template<class T>
7568
+ explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
7569
+ ```
7570
+
7571
+ *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
7572
+
7573
+ *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
7574
+
7575
  ``` cpp
7576
  basic_fstream(basic_fstream&& rhs);
7577
  ```
7578
 
7579
  *Effects:* Move constructs the base class, and the contained
7580
  `basic_filebuf`. Then calls
7581
  `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
7582
  contained `basic_filebuf`.
7583
 
7584
+ #### Swap <a id="fstream.swap">[[fstream.swap]]</a>
7585
 
7586
  ``` cpp
7587
  void swap(basic_fstream& rhs);
7588
  ```
7589
 
 
7654
 
7655
  namespace std {
7656
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7657
  class basic_syncbuf;
7658
 
7659
+ // [syncstream.syncbuf.special], specialized algorithms
7660
+ template<class charT, class traits, class Allocator>
7661
+ void swap(basic_syncbuf<charT, traits, Allocator>&,
7662
+ basic_syncbuf<charT, traits, Allocator>&);
7663
+
7664
  using syncbuf = basic_syncbuf<char>;
7665
  using wsyncbuf = basic_syncbuf<wchar_t>;
7666
 
7667
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
7668
  class basic_osyncstream;
 
7718
 
7719
  private:
7720
  streambuf_type* wrapped; // exposition only
7721
  bool emit_on_sync{}; // exposition only
7722
  };
 
 
 
 
 
7723
  }
7724
  ```
7725
 
7726
  Class template `basic_syncbuf` stores character data written to it,
7727
  known as the associated output, into internal buffers allocated using
 
7737
  basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
7738
  ```
7739
 
7740
  *Effects:* Sets `wrapped` to `obuf`.
7741
 
 
 
 
 
 
 
7742
  *Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
7743
  are `true`.
7744
 
7745
+ *Throws:* Nothing unless an exception is thrown by the construction of a
7746
+ mutex or by memory allocation.
7747
+
7748
+ *Remarks:* A copy of `allocator` is used to allocate memory for internal
7749
+ buffers holding the associated output.
7750
+
7751
  ``` cpp
7752
  basic_syncbuf(basic_syncbuf&& other);
7753
  ```
7754
 
7755
  *Ensures:* The value returned by `this->get_wrapped()` is the value
7756
  returned by `other.get_wrapped()` prior to calling this constructor.
7757
  Output stored in `other` prior to calling this constructor will be
7758
+ stored in `*this` afterwards. `other.pbase() == other.pptr()` and
 
7759
  `other.get_wrapped() == nullptr` are `true`.
7760
 
7761
  *Remarks:* This constructor disassociates `other` from its wrapped
7762
  stream buffer, ensuring destruction of `other` produces no output.
7763
 
 
7771
  destructor catches and ignores that exception.
7772
 
7773
  #### Assignment and swap <a id="syncstream.syncbuf.assign">[[syncstream.syncbuf.assign]]</a>
7774
 
7775
  ``` cpp
7776
+ basic_syncbuf& operator=(basic_syncbuf&& rhs);
7777
  ```
7778
 
7779
  *Effects:* Calls `emit()` then move assigns from `rhs`. After the move
7780
  assignment `*this` has the observable state it would have had if it had
7781
  been move constructed from `rhs` [[syncstream.syncbuf.cons]].
7782
 
 
 
7783
  *Ensures:*
7784
 
7785
  - `rhs.get_wrapped() == nullptr` is `true`.
7786
  - `this->get_allocator() == rhs.get_allocator()` is `true` when
7787
  ``` cpp
7788
  allocator_traits<Allocator>::propagate_on_container_move_assignment::value
7789
  ```
7790
 
7791
  is `true`; otherwise, the allocator is unchanged.
7792
 
7793
+ *Returns:* `*this`.
7794
+
7795
  *Remarks:* This assignment operator disassociates `rhs` from its wrapped
7796
  stream buffer, ensuring destruction of `rhs` produces no output.
7797
 
7798
  ``` cpp
7799
+ void swap(basic_syncbuf& other);
7800
  ```
7801
 
7802
  *Preconditions:* Either
7803
  `allocator_traits<Allocator>::propagate_on_container_swap::value` is
7804
  `true` or `this->get_allocator() == other.get_allocator()` is `true`.
 
7815
  stream buffer `*wrapped`, so that it appears in the output stream as a
7816
  contiguous sequence of characters. `wrapped->pubsync()` is called if and
7817
  only if a call was made to `sync()` since the most recent call to
7818
  `emit()`, if any.
7819
 
7820
+ *Synchronization:* All `emit()` calls transferring characters to the
7821
+ same stream buffer object appear to execute in a total order consistent
7822
+ with the “happens before” relation [[intro.races]], where each `emit()`
7823
+ call synchronizes with subsequent `emit()` calls in that total order.
7824
+
7825
+ *Ensures:* On success, the associated output is empty.
7826
+
7827
  *Returns:* `true` if all of the following conditions hold; otherwise
7828
  `false`:
7829
 
7830
  - `wrapped == nullptr` is `false`.
7831
  - All of the characters in the associated output were successfully
7832
  transferred.
7833
  - The call to `wrapped->pubsync()` (if any) succeeded.
7834
 
 
 
 
 
 
 
 
7835
  *Remarks:* May call member functions of `wrapped` while holding a lock
7836
  uniquely associated with `wrapped`.
7837
 
7838
  ``` cpp
7839
  streambuf_type* get_wrapped() const noexcept;
 
7872
  #### Specialized algorithms <a id="syncstream.syncbuf.special">[[syncstream.syncbuf.special]]</a>
7873
 
7874
  ``` cpp
7875
  template<class charT, class traits, class Allocator>
7876
  void swap(basic_syncbuf<charT, traits, Allocator>& a,
7877
+ basic_syncbuf<charT, traits, Allocator>& b);
7878
  ```
7879
 
7880
  *Effects:* Equivalent to `a.swap(b)`.
7881
 
7882
  ### Class template `basic_osyncstream` <a id="syncstream.osyncstream">[[syncstream.osyncstream]]</a>
 
7908
  : basic_osyncstream(os, Allocator()) {}
7909
  basic_osyncstream(basic_osyncstream&&) noexcept;
7910
  ~basic_osyncstream();
7911
 
7912
  // assignment
7913
+ basic_osyncstream& operator=(basic_osyncstream&&);
7914
 
7915
  // [syncstream.osyncstream.members], member functions
7916
  void emit();
7917
  streambuf_type* get_wrapped() const noexcept;
7918
  syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); }
 
7921
  syncbuf_type sb; // exposition only
7922
  };
7923
  }
7924
  ```
7925
 
7926
+ `Allocator` shall meet the *Cpp17Allocator* requirements
7927
+ [[allocator.requirements.general]].
7928
 
7929
  [*Example 1*:
7930
 
7931
  A named variable can be used within a block statement for streaming.
7932
 
 
7961
  ```
7962
 
7963
  *Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
7964
  base class with `basic_ostream<charT, traits>(addressof(sb))`.
7965
 
7966
+ [*Note 1*: The member functions of the provided stream buffer can be
7967
+ called from `emit()` while a lock is held, which might result in a
7968
+ deadlock if used incautiously. — *end note*]
7969
 
7970
  *Ensures:* `get_wrapped() == buf` is `true`.
7971
 
7972
  ``` cpp
7973
  basic_osyncstream(basic_osyncstream&& other) noexcept;
 
7976
  *Effects:* Move constructs the base class and `sb` from the
7977
  corresponding subobjects of `other`, and calls
7978
  `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
7979
 
7980
  *Ensures:* The value returned by `get_wrapped()` is the value returned
7981
+ by `other.get_wrapped()` prior to calling this constructor.
7982
  `nullptr == other.get_wrapped()` is `true`.
7983
 
7984
  #### Member functions <a id="syncstream.osyncstream.members">[[syncstream.osyncstream.members]]</a>
7985
 
7986
  ``` cpp
7987
  void emit();
7988
  ```
7989
 
7990
+ *Effects:* Behaves as an unformatted output
7991
+ function [[ostream.unformatted]]. After constructing a `sentry` object,
7992
+ calls `sb.emit()`. If that call returns `false`, calls
7993
  `setstate(ios_base::badbit)`.
7994
 
7995
  [*Example 1*:
7996
 
7997
  A flush on a `basic_osyncstream` does not flush immediately:
 
8101
  does not exist, the symbolic link is said to be a “dangling” symbolic
8102
  link. — *end note*]
8103
 
8104
  ### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
8105
 
8106
+ #### General <a id="fs.conformance.general">[[fs.conformance.general]]</a>
8107
+
8108
  Conformance is specified in terms of behavior. Ideal behavior is not
8109
  always implementable, so the conformance subclauses take that into
8110
  account.
8111
 
8112
  #### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
8113
 
8114
+ Some behavior is specified by reference to POSIX. How such behavior is
8115
+ actually implemented is unspecified.
8116
 
8117
  [*Note 1*: This constitutes an “as if” rule allowing implementations to
8118
  call native operating system or other APIs. — *end note*]
8119
 
8120
  Implementations should provide such behavior as it is defined by POSIX.
 
8153
  #### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
8154
 
8155
  A *file system race* is the condition that occurs when multiple threads,
8156
  processes, or computers interleave access and modification of the same
8157
  object within a file system. Behavior is undefined if calls to functions
8158
+ provided by subclause  [[filesystems]] introduce a file system race.
 
8159
 
8160
  If the possibility of a file system race would make it unreliable for a
8161
  program to test for a precondition before calling a function described
8162
  herein, *Preconditions:* is not specified for the function.
8163
 
8164
  [*Note 1*: As a design practice, preconditions are not specified when
8165
  it is unreasonable for a program to detect them prior to calling the
8166
  function. — *end note*]
8167
 
 
 
 
 
 
8168
  ### Requirements <a id="fs.req">[[fs.req]]</a>
8169
 
8170
  Throughout subclause  [[filesystems]], `char`, `wchar_t`, `char8_t`,
8171
  `char16_t`, and `char32_t` are collectively called *encoded character
8172
  types*.
 
8183
  character set and encoding. Since `signed char` and `unsigned char` have
8184
  no implied character set and encoding, they are not included as
8185
  permitted types. — *end note*]
8186
 
8187
  Template parameters named `Allocator` shall meet the *Cpp17Allocator*
8188
+ requirements [[allocator.requirements.general]].
 
 
 
 
 
 
8189
 
8190
  ### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
8191
 
8192
  ``` cpp
8193
  #include <compare> // see [compare.syn]
 
8209
  // [fs.class.directory.iterator], directory iterators
8210
  class directory_iterator;
8211
 
8212
  // [fs.dir.itr.nonmembers], range access for directory iterators
8213
  directory_iterator begin(directory_iterator iter) noexcept;
8214
+ directory_iterator end(directory_iterator) noexcept;
8215
 
8216
  // [fs.class.rec.dir.itr], recursive directory iterators
8217
  class recursive_directory_iterator;
8218
 
8219
  // [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
8220
  recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
8221
+ recursive_directory_iterator end(recursive_directory_iterator) noexcept;
8222
 
8223
  // [fs.class.file.status], file status
8224
  class file_status;
8225
 
8226
  struct space_info {
 
8386
  path temp_directory_path(error_code& ec);
8387
 
8388
  path weakly_canonical(const path& p);
8389
  path weakly_canonical(const path& p, error_code& ec);
8390
  }
8391
+
8392
+ // [fs.path.hash], hash support
8393
+ namespace std {
8394
+ template<class T> struct hash;
8395
+ template<> struct hash<filesystem::path>;
8396
+ }
8397
+
8398
+ namespace std::ranges {
8399
+ template<>
8400
+ inline constexpr bool enable_borrowed_range<filesystem::directory_iterator> = true;
8401
+ template<>
8402
+ inline constexpr bool enable_borrowed_range<filesystem::recursive_directory_iterator> = true;
8403
+
8404
+ template<>
8405
+ inline constexpr bool enable_view<filesystem::directory_iterator> = true;
8406
+ template<>
8407
+ inline constexpr bool enable_view<filesystem::recursive_directory_iterator> = true;
8408
+ }
8409
  ```
8410
 
8411
  Implementations should ensure that the resolution and range of
8412
  `file_time_type` reflect the operating system dependent resolution and
8413
  range of file time values.
 
8458
  appropriate for the specific operating system dependent error.
8459
  Otherwise, `clear()` is called on the `error_code&` argument.
8460
 
8461
  ### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
8462
 
8463
+ #### General <a id="fs.class.path.general">[[fs.class.path.general]]</a>
8464
+
8465
  An object of class `path` represents a path and contains a pathname.
8466
  Such an object is concerned only with the lexical and syntactic aspects
8467
  of a path. The path does not necessarily exist in external storage, and
8468
  the pathname is not necessarily valid for the current operating system
8469
  or for a particular file system.
 
8485
  dependent. A *relative path* is a path that is not absolute, and as
8486
  such, only unambiguously identifies the location of a file when resolved
8487
  relative to an implied starting location. The elements of a path that
8488
  determine if it is relative are operating system dependent.
8489
 
8490
+ [*Note 2*: Pathnames “.” and “..” are relative paths. — *end note*]
8491
 
8492
  A *pathname* is a character string that represents the name of a path.
8493
  Pathnames are formatted according to the generic pathname format grammar
8494
  [[fs.path.generic]] or according to an operating system dependent
8495
  *native pathname format* accepted by the host operating system.
8496
 
8497
  *Pathname resolution* is the operating system dependent mechanism for
8498
  resolving a pathname to a particular file in a file hierarchy. There may
8499
  be multiple pathnames that resolve to the same file.
8500
 
8501
+ [*Example 1*: POSIX specifies the mechanism in section 4.12, Pathname
8502
  resolution. — *end example*]
8503
 
8504
  ``` cpp
8505
  namespace std::filesystem {
8506
  class path {
 
8718
  special meaning. The following characteristics of filenames are
8719
  operating system dependent:
8720
 
8721
  - The permitted characters. \[*Example 1*: Some operating systems
8722
  prohibit the ASCII control characters (0x00 – 0x1F) in
8723
+ filenames. — *end example*] \[*Note 1*: Wider portability can be
8724
+ achieved by limiting *filename* characters to the POSIX Portable
8725
+ Filename Character Set:
8726
  `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`
8727
  `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`
8728
  `0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
8729
  - The maximum permitted length.
8730
  - Filenames that are not permitted.
 
8749
  required.
8750
 
8751
  [*Note 2*: Many operating systems define a name beginning with two
8752
  *directory-separator* characters as a *root-name* that identifies
8753
  network or other resource locations. Some operating systems define a
8754
+ single letter followed by a colon as a drive specifier a *root-name*
8755
  identifying a specific device such as a disk drive. — *end note*]
8756
 
8757
  If a *root-name* is otherwise ambiguous, the possibility with the
8758
  longest sequence of characters is chosen.
8759
 
 
8765
 
8766
  1. If the path is empty, stop.
8767
  2. Replace each slash character in the *root-name* with a
8768
  *preferred-separator*.
8769
  3. Replace each *directory-separator* with a *preferred-separator*.
8770
+ \[*Note 4*: The generic pathname grammar defines
8771
  *directory-separator* as one or more slashes and
8772
  *preferred-separator*s. — *end note*]
8773
  4. Remove each dot filename and any immediately following
8774
  *directory-separator*.
8775
  5. As long as any appear, remove a non-dot-dot filename immediately
 
8809
  or a pathname in the native format [[fs.class.path]]. Such an argument
8810
  is taken to be in the generic format if and only if it matches the
8811
  generic format and is not acceptable to the operating system as a native
8812
  path.
8813
 
8814
+ [*Note 2*: Some operating systems have no unambiguous way to
8815
  distinguish between native format and generic format arguments. This is
8816
  by design as it simplifies use for operating systems that do not require
8817
  disambiguation. An implementation for an operating system where
8818
  disambiguation is required is permitted to distinguish between the
8819
  formats. — *end note*]
 
8832
  directory path if its last element is a *directory-separator*, otherwise
8833
  it shall be treated as a path to a regular file.
8834
 
8835
  [*Note 4*: A path stores a native format pathname
8836
  [[fs.path.native.obs]] and acts as if it also stores a generic format
8837
+ pathname, related as given below. The implementation can generate the
8838
  generic format pathname based on the native format pathname (and
8839
  possibly other information) when requested. — *end note*]
8840
 
8841
  When a path is constructed from or is assigned a single representation
8842
  separate from any path, the other representation is selected by the
 
8854
 
8855
  The *native encoding* of an ordinary character string is the operating
8856
  system dependent current encoding for pathnames [[fs.class.path]]. The
8857
  *native encoding* for wide character strings is the
8858
  implementation-defined execution wide-character set encoding
8859
+ [[character.seq]].
8860
 
8861
  For member function arguments that take character sequences representing
8862
  paths and for member functions returning strings, value type and
8863
  encoding conversion is performed if the value type of the argument or
8864
  return value differs from `path::value_type`. For the argument or return
 
8872
  return values is performed. For Windows-based operating systems, the
8873
  native ordinary encoding is determined by calling a Windows API
8874
  function. — *end note*] \[*Note 7*: This results in behavior
8875
  identical to other C and C++ standard library functions that perform
8876
  file operations using ordinary character strings to identify paths.
8877
+ Changing this behavior would be surprising and
8878
+ error-prone. — *end note*]
8879
  - `wchar_t`: The encoding is the native wide encoding. The method of
8880
  conversion is unspecified. \[*Note 8*: For Windows-based operating
8881
  systems `path::value_type` is `wchar_t` so no conversion from
8882
  `wchar_t` value type arguments or to `wchar_t` value type return
8883
  values is performed. — *end note*]
 
8921
  than `path`, and either
8922
 
8923
  - `Source` is a specialization of `basic_string` or `basic_string_view`,
8924
  or
8925
  - the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
8926
+ valid and denotes a possibly const encoded character type
8927
  [[temp.deduct]].
8928
 
8929
  [*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
8930
  above and their encodings convert to `path::value_type` and its
8931
  encoding. — *end note*]
 
9160
  ```
9161
 
9162
  *Effects:* Appends `path(x).native()` to the pathname in the native
9163
  format.
9164
 
9165
+ [*Note 2*: This directly manipulates the value of `native()`, which is
9166
+ not necessarily portable between operating systems. — *end note*]
9167
 
9168
  *Returns:* `*this`.
9169
 
9170
  ``` cpp
9171
  path& operator+=(value_type x);
 
9314
  operator string_type() const;
9315
  ```
9316
 
9317
  *Returns:* `native()`.
9318
 
 
 
 
 
9319
  ``` cpp
9320
  template<class EcharT, class traits = char_traits<EcharT>,
9321
  class Allocator = allocator<EcharT>>
9322
  basic_string<EcharT, traits, Allocator>
9323
  string(const Allocator& a = Allocator()) const;
 
9517
  path("..bar").extension(); // yields ".bar" and stem() is "."
9518
  ```
9519
 
9520
  — *end example*]
9521
 
9522
+ [*Note 3*: The period is included in the return value so that it is
9523
  possible to distinguish between no extension and an empty
9524
  extension. — *end note*]
9525
 
9526
+ [*Note 4*: On non-POSIX operating systems, for a path `p`, it is
9527
+ possible that `p.stem() + p.extension() == p.filename()` is `false`,
9528
+ even though the generic format pathnames are the same. — *end note*]
9529
 
9530
  ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
9531
 
9532
  ``` cpp
9533
  [[nodiscard]] bool empty() const noexcept;
 
9626
 
9627
  ``` cpp
9628
  path lexically_relative(const path& base) const;
9629
  ```
9630
 
 
 
 
 
9631
  *Effects:* If:
9632
 
9633
  - `root_name() != base.root_name()` is `true`, or
9634
  - `is_absolute() != base.is_absolute()` is `true`, or
9635
  - `!has_root_directory() && base.has_root_directory()` is `true`, or
9636
  - any *filename* in `relative_path()` or `base.relative_path()` can be
9637
  interpreted as a *root-name*,
9638
 
9639
  returns `path()`.
9640
 
9641
+ [*Note 5*: On a POSIX implementation, no *filename* in a
9642
  *relative-path* is acceptable as a *root-name*. — *end note*]
9643
 
9644
  Determines the first mismatched element of `*this` and `base` as if by:
9645
 
9646
  ``` cpp
 
9658
  - returns an object of class `path` that is default-constructed,
9659
  followed by
9660
  - application of `operator/=(path(".."))` `n` times, and then
9661
  - application of `operator/=` for each element in \[`a`, `end()`).
9662
 
9663
+ *Returns:* `*this` made relative to `base`. Does not
9664
+ resolve [[fs.class.path]] symlinks. Does not first
9665
+ normalize [[fs.path.generic]] `*this` or `base`.
9666
+
9667
  [*Example 11*:
9668
 
9669
  ``` cpp
9670
  assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
9671
  assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
 
9679
  *directory-separator* characters will be backslashes rather than
9680
  slashes, but that does not affect `path` equality.
9681
 
9682
  — *end example*]
9683
 
9684
+ [*Note 6*: If symlink following semantics are desired, use the
9685
  operational function `relative()`. — *end note*]
9686
 
9687
+ [*Note 7*: If normalization [[fs.path.generic]] is needed to ensure
9688
  consistent matching of elements, apply `lexically_normal()` to `*this`,
9689
  `base`, or both. — *end note*]
9690
 
9691
  ``` cpp
9692
  path lexically_proximate(const path& base) const;
9693
  ```
9694
 
9695
  *Returns:* If the value of `lexically_relative(base)` is not an empty
9696
  path, return it. Otherwise return `*this`.
9697
 
9698
+ [*Note 8*: If symlink following semantics are desired, use the
9699
  operational function `proximate()`. — *end note*]
9700
 
9701
+ [*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
9702
  consistent matching of elements, apply `lexically_normal()` to `*this`,
9703
  `base`, or both. — *end note*]
9704
 
9705
  #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
9706
 
 
9805
  - Equivalence is determined by the `equivalent()` non-member function,
9806
  which determines if two paths resolve [[fs.class.path]] to the same
9807
  file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
9808
  `true` when both paths resolve to the same file. — *end example*]
9809
 
 
 
 
 
9810
  — *end note*]
9811
 
9812
  ``` cpp
9813
  friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
9814
  ```
 
9819
  friend path operator/(const path& lhs, const path& rhs);
9820
  ```
9821
 
9822
  *Effects:* Equivalent to: `return path(lhs) /= rhs;`
9823
 
9824
+ #### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
9825
+
9826
+ ``` cpp
9827
+ template<> struct hash<filesystem::path>;
9828
+ ```
9829
+
9830
+ For an object `p` of type `filesystem::path`,
9831
+ `hash<filesystem::path>()(p)` evaluates to the same result as
9832
+ `filesystem::hash_value(p)`.
9833
+
9834
  ### Class `filesystem_error` <a id="fs.class.filesystem.error">[[fs.class.filesystem.error]]</a>
9835
 
9836
+ #### General <a id="fs.class.filesystem.error.general">[[fs.class.filesystem.error.general]]</a>
9837
+
9838
  ``` cpp
9839
  namespace std::filesystem {
9840
  class filesystem_error : public system_error {
9841
  public:
9842
  filesystem_error(const string& what_arg, error_code ec);
 
9922
  #### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
9923
 
9924
  This enum specifies constants used to identify the format of the
9925
  character sequence, with the meanings listed in [[fs.enum.path.format]].
9926
 
9927
+ **Table: Enum `path::format`** <a id="fs.enum.path.format">[fs.enum.path.format]</a>
9928
+
9929
+ | Name | Meaning |
9930
+ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9931
+ | `native_format` | The native pathname format. |
9932
+ | `generic_format` | The generic pathname format. |
9933
+ | `auto_format` | The interpretation of the format of the character sequence is implementation-defined. The implementation may inspect the content of the character sequence to determine the format. Recommended practice: For POSIX-based systems, native and generic formats are equivalent and the character sequence should always be interpreted in the same way. |
9934
+
9935
 
9936
  #### Enum class `file_type` <a id="fs.enum.file.type">[[fs.enum.file.type]]</a>
9937
 
9938
  This enum class specifies constants used to identify file types, with
9939
  the meanings listed in [[fs.enum.file.type]]. The values of the
9940
  constants are distinct.
9941
 
9942
+ **Table: Enum class `file_type`** <a id="fs.enum.file.type">[fs.enum.file.type]</a>
9943
+
9944
+ | Constant | Meaning |
9945
+ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9946
+ | `none` | The type of the file has not been determined or an error occurred while trying to determine the type. |
9947
+ | `not_found` | Pseudo-type indicating the file was not found. *The file not being found is not considered an error while determining the type of a file.* |
9948
+ | `regular` | Regular file |
9949
+ | `directory` | Directory file |
9950
+ | `symlink` | Symbolic link file |
9951
+ | `block` | Block special file |
9952
+ | `character` | Character special file |
9953
+ | `fifo` | FIFO or pipe file |
9954
+ | `socket` | Socket file |
9955
+ | `implementation-defined` | Implementations that support file systems having file types in addition to the above `file_type` types shall supply implementation-defined `file_type` constants to separately identify each of those additional file types |
9956
+ | `unknown` | The file exists but the type cannot be determined |
9957
+
9958
 
9959
  #### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
9960
 
9961
  The `enum class` type `copy_options` is a bitmask type [[bitmask.types]]
9962
  that specifies bitmask constants used to control the semantics of copy
 
9967
  Every other constant in the table represents a distinct bitmask element.
9968
 
9969
  **Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
9970
 
9971
  | Constant | Meaning |
9972
+ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
9973
  | `none` | (Default) Error; file already exists. |
9974
  | `skip_existing` | Do not overwrite existing file, do not report an error. |
9975
  | `overwrite_existing` | Overwrite the existing file. |
9976
+ | `update_existing` | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for subdirectories} |
9977
+ | `recursive` | Recursively copy subdirectories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links} |
9978
  | `copy_symlinks` | Copy symbolic links as symbolic links rather than copying the files that they point to. |
9979
  | `skip_symlinks` | Ignore symbolic links. \ohdrx{2}{Option group controlling `copy` function effects for choosing the form of copying} |
9980
  | `directories_only` | Copy directory structure only, do not copy non-directory files. |
9981
  | `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. |
9982
  | `create_hard_links` | Make hard links instead of copies of files. |
 
10025
  **Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
10026
 
10027
  | Name | Meaning |
10028
  | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
10029
  | `replace` | `permissions` shall replace the file's permission bits with `perm` |
10030
+ | `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{or} of `perm` and the file's current permission bits. |
10031
+ | `remove` | `permissions` shall replace the file's permission bits with the bitwise \logop{and} of the complement of `perm` and the file's current permission bits. |
10032
  | `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
10033
 
10034
 
10035
  #### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
10036
 
 
10049
  | `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
10050
 
10051
 
10052
  ### Class `file_status` <a id="fs.class.file.status">[[fs.class.file.status]]</a>
10053
 
10054
+ #### General <a id="fs.class.file.status.general">[[fs.class.file.status.general]]</a>
10055
+
10056
  ``` cpp
10057
  namespace std::filesystem {
10058
  class file_status {
10059
  public:
10060
  // [fs.file.status.cons], constructors and destructor
 
10123
 
10124
  *Ensures:* `permissions() == prms`.
10125
 
10126
  ### Class `directory_entry` <a id="fs.class.directory.entry">[[fs.class.directory.entry]]</a>
10127
 
10128
+ #### General <a id="fs.class.directory.entry.general">[[fs.class.directory.entry.general]]</a>
10129
+
10130
  ``` cpp
10131
  namespace std::filesystem {
10132
  class directory_entry {
10133
  public:
10134
  // [fs.dir.entry.cons], constructors and destructor
 
10184
  file_status symlink_status(error_code& ec) const noexcept;
10185
 
10186
  bool operator==(const directory_entry& rhs) const noexcept;
10187
  strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
10188
 
10189
+ // [fs.dir.entry.io], inserter
10190
+ template<class charT, class traits>
10191
+ friend basic_ostream<charT, traits>&
10192
+ operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
10193
+
10194
  private:
10195
  filesystem::path pathobject; // exposition only
10196
  friend class directory_iterator; // exposition only
10197
  };
10198
  }
 
10295
 
10296
  *Throws:* As specified in  [[fs.err.report]].
10297
 
10298
  [*Note 1*: Implementations of `directory_iterator`
10299
  [[fs.class.directory.iterator]] are prohibited from directly or
10300
+ indirectly calling the `refresh` function as described in
10301
+ [[fs.class.directory.iterator.general]]. *end note*]
 
10302
 
10303
  #### Observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
10304
 
10305
  Unqualified function names in the *Returns:* elements of the
10306
  `directory_entry` observers described below refer to members of the
 
10465
  strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
10466
  ```
10467
 
10468
  *Returns:* `pathobject <=> rhs.pathobject`.
10469
 
10470
+ #### Inserter <a id="fs.dir.entry.io">[[fs.dir.entry.io]]</a>
10471
+
10472
+ ``` cpp
10473
+ template<class charT, class traits>
10474
+ friend basic_ostream<charT, traits>&
10475
+ operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
10476
+ ```
10477
+
10478
+ *Effects:* Equivalent to: `return os << d.path();`
10479
+
10480
  ### Class `directory_iterator` <a id="fs.class.directory.iterator">[[fs.class.directory.iterator]]</a>
10481
 
10482
+ #### General <a id="fs.class.directory.iterator.general">[[fs.class.directory.iterator.general]]</a>
10483
+
10484
  An object of type `directory_iterator` provides an iterator for a
10485
  sequence of `directory_entry` elements representing the path and any
10486
  cached attribute values [[fs.class.directory.entry]] for each file in a
10487
  directory or in an *implementation-defined* directory-like file type.
10488
 
10489
+ [*Note 1*: For iteration into subdirectories, see class
10490
  `recursive_directory_iterator` [[fs.class.rec.dir.itr]]. — *end note*]
10491
 
10492
  ``` cpp
10493
  namespace std::filesystem {
10494
  class directory_iterator {
 
10516
  const directory_entry& operator*() const;
10517
  const directory_entry* operator->() const;
10518
  directory_iterator& operator++();
10519
  directory_iterator& increment(error_code& ec);
10520
 
10521
+ bool operator==(default_sentinel_t) const noexcept {
10522
+ return *this == directory_iterator();
10523
+ }
10524
+
10525
  // other members as required by [input.iterators], input iterators
10526
  };
10527
  }
10528
  ```
10529
 
 
10542
  to a non-end iterator.
10543
 
10544
  The result of calling the `path()` member of the `directory_entry`
10545
  object obtained by dereferencing a `directory_iterator` is a reference
10546
  to a `path` object composed of the directory argument from which the
10547
+ iterator was constructed with the filename of the directory entry
10548
+ appended as if by `operator/=`.
10549
 
10550
  Directory iteration shall not yield directory entries for the current
10551
  (dot) and parent (dot-dot) directories.
10552
 
10553
  The order of directory entries obtained by dereferencing successive
 
10562
  [*Note 2*: The exact mechanism for storing cached attribute values is
10563
  not exposed to users. For exposition, class `directory_iterator` is
10564
  shown in [[fs.class.directory.entry]] as a friend of class
10565
  `directory_entry`. — *end note*]
10566
 
10567
+ [*Note 3*: A path obtained by dereferencing a directory iterator might
10568
+ not actually exist; it could be a symbolic link to a non-existent file.
10569
+ Recursively walking directory trees for purposes of removing and
10570
+ renaming entries might invalidate symbolic links that are being
10571
+ followed. — *end note*]
10572
 
10573
  [*Note 4*: If a file is removed from or added to a directory after the
10574
  construction of a `directory_iterator` for the directory, it is
10575
  unspecified whether or not subsequently incrementing the iterator will
10576
  ever result in an iterator referencing the removed or added directory
10577
+ entry. See POSIX `readdir`. — *end note*]
10578
 
10579
  #### Members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
10580
 
10581
  ``` cpp
10582
  directory_iterator() noexcept;
 
10650
  ```
10651
 
10652
  *Returns:* `iter`.
10653
 
10654
  ``` cpp
10655
+ directory_iterator end(directory_iterator) noexcept;
10656
  ```
10657
 
10658
  *Returns:* `directory_iterator()`.
10659
 
10660
  ### Class `recursive_directory_iterator` <a id="fs.class.rec.dir.itr">[[fs.class.rec.dir.itr]]</a>
10661
 
10662
+ #### General <a id="fs.class.rec.dir.itr.general">[[fs.class.rec.dir.itr.general]]</a>
10663
+
10664
  An object of type `recursive_directory_iterator` provides an iterator
10665
  for a sequence of `directory_entry` elements representing the files in a
10666
  directory or in an *implementation-defined* directory-like file type,
10667
+ and its subdirectories.
10668
 
10669
  ``` cpp
10670
  namespace std::filesystem {
10671
  class recursive_directory_iterator {
10672
  public:
 
10706
 
10707
  void pop();
10708
  void pop(error_code& ec);
10709
  void disable_recursion_pending();
10710
 
10711
+ bool operator==(default_sentinel_t) const noexcept {
10712
+ return *this == recursive_directory_iterator();
10713
+ }
10714
+
10715
  // other members as required by [input.iterators], input iterators
10716
  };
10717
  }
10718
  ```
10719
 
 
10723
 
10724
  The behavior of a `recursive_directory_iterator` is the same as a
10725
  `directory_iterator` unless otherwise specified.
10726
 
10727
  [*Note 1*: If the directory structure being iterated over contains
10728
+ cycles then it is possible that the end iterator is
10729
+ unreachable. — *end note*]
10730
 
10731
  #### Members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
10732
 
10733
  ``` cpp
10734
  recursive_directory_iterator() noexcept;
 
10759
  `directory_options` argument, otherwise
10760
  `options() == directory_options::none`.
10761
 
10762
  *Throws:* As specified in  [[fs.err.report]].
10763
 
10764
+ [*Note 1*: Use `recursive_directory_iterator(".")` rather than
10765
+ `recursive_directory_iterator("")` to iterate over the current
10766
+ directory. — *end note*]
10767
 
10768
  [*Note 2*: By default, `recursive_directory_iterator` does not follow
10769
  directory symlinks. To follow directory symlinks, specify `options` as
10770
  `directory_options::follow_directory_symlink`. — *end note*]
10771
 
 
10902
  recursion into a directory. — *end note*]
10903
 
10904
  #### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
10905
 
10906
  These functions enable use of `recursive_directory_iterator` with
10907
+ range-based `for` statements.
10908
 
10909
  ``` cpp
10910
  recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
10911
  ```
10912
 
10913
  *Returns:* `iter`.
10914
 
10915
  ``` cpp
10916
+ recursive_directory_iterator end(recursive_directory_iterator) noexcept;
10917
  ```
10918
 
10919
  *Returns:* `recursive_directory_iterator()`.
10920
 
10921
  ### Filesystem operation functions <a id="fs.op.funcs">[[fs.op.funcs]]</a>
10922
 
10923
+ #### General <a id="fs.op.funcs.general">[[fs.op.funcs.general]]</a>
10924
+
10925
  Filesystem operation functions query or modify files, including
10926
  directories, in external storage.
10927
 
10928
  [*Note 1*: Because hardware failures, network failures, file system
10929
  races [[fs.race.behavior]], and many other kinds of errors occur
10930
+ frequently in file system operations, any filesystem operation function,
10931
+ no matter how apparently innocuous, can encounter an error; see 
10932
+ [[fs.err.report]]. — *end note*]
10933
 
10934
  #### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
10935
 
10936
  ``` cpp
10937
+ path filesystem::absolute(const path& p);
10938
+ path filesystem::absolute(const path& p, error_code& ec);
10939
  ```
10940
 
10941
  *Effects:* Composes an absolute path referencing the same file system
10942
  location as `p` according to the operating system [[fs.conform.os]].
10943
 
 
10947
  [*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
10948
  unless an error occurs. — *end note*]
10949
 
10950
  *Throws:* As specified in  [[fs.err.report]].
10951
 
10952
+ [*Note 2*: To resolve symlinks or perform other sanitization that can
10953
+ involve queries to secondary storage, such as hard disks, consider
10954
  `canonical` [[fs.op.canonical]]. — *end note*]
10955
 
10956
  [*Note 3*: Implementations are strongly encouraged to not query
10957
  secondary storage, and not consider `!exists(p)` an
10958
  error. — *end note*]
 
10963
  `GetFullPathNameW`. — *end example*]
10964
 
10965
  #### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
10966
 
10967
  ``` cpp
10968
+ path filesystem::canonical(const path& p);
10969
+ path filesystem::canonical(const path& p, error_code& ec);
10970
  ```
10971
 
10972
  *Effects:* Converts `p` to an absolute path that has no symbolic link,
10973
  dot, or dot-dot elements in its pathname in the generic format.
10974
 
 
10981
  *Remarks:* `!exists(p)` is an error.
10982
 
10983
  #### Copy <a id="fs.op.copy">[[fs.op.copy]]</a>
10984
 
10985
  ``` cpp
10986
+ void filesystem::copy(const path& from, const path& to);
10987
  ```
10988
 
10989
  *Effects:* Equivalent to `copy(from, to, copy_options::none)`.
10990
 
10991
  ``` cpp
10992
+ void filesystem::copy(const path& from, const path& to, error_code& ec);
10993
  ```
10994
 
10995
  *Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
10996
 
10997
  ``` cpp
10998
+ void filesystem::copy(const path& from, const path& to, copy_options options);
10999
+ void filesystem::copy(const path& from, const path& to, copy_options options,
11000
  error_code& ec);
11001
  ```
11002
 
11003
  *Preconditions:* At most one element from each option
11004
  group [[fs.enum.copy.opts]] is set in `options`.
 
11135
  — *end example*]
11136
 
11137
  #### Copy file <a id="fs.op.copy.file">[[fs.op.copy.file]]</a>
11138
 
11139
  ``` cpp
11140
+ bool filesystem::copy_file(const path& from, const path& to);
11141
+ bool filesystem::copy_file(const path& from, const path& to, error_code& ec);
11142
  ```
11143
 
11144
  *Returns:* `copy_file(from, to, copy_options::none)` or
11145
  `copy_file(from, to, copy_options::none, ec)`, respectively.
11146
 
11147
  *Throws:* As specified in  [[fs.err.report]].
11148
 
11149
  ``` cpp
11150
+ bool filesystem::copy_file(const path& from, const path& to, copy_options options);
11151
+ bool filesystem::copy_file(const path& from, const path& to, copy_options options,
11152
  error_code& ec);
11153
  ```
11154
 
11155
  *Preconditions:* At most one element from each option
11156
  group [[fs.enum.copy.opts]] is set in `options`.
 
11185
  *Complexity:* At most one direct or indirect invocation of `status(to)`.
11186
 
11187
  #### Copy symlink <a id="fs.op.copy.symlink">[[fs.op.copy.symlink]]</a>
11188
 
11189
  ``` cpp
11190
+ void filesystem::copy_symlink(const path& existing_symlink, const path& new_symlink);
11191
+ void filesystem::copy_symlink(const path& existing_symlink, const path& new_symlink,
11192
  error_code& ec) noexcept;
11193
  ```
11194
 
11195
  *Effects:* Equivalent to
11196
  *`function`*`(read_symlink(existing_symlink), new_symlink)` or
 
11201
  *Throws:* As specified in  [[fs.err.report]].
11202
 
11203
  #### Create directories <a id="fs.op.create.directories">[[fs.op.create.directories]]</a>
11204
 
11205
  ``` cpp
11206
+ bool filesystem::create_directories(const path& p);
11207
+ bool filesystem::create_directories(const path& p, error_code& ec);
11208
  ```
11209
 
11210
  *Effects:* Calls `create_directory()` for each element of `p` that does
11211
  not exist.
11212
 
 
11218
  *Complexity:* 𝑂(n) where *n* is the number of elements of `p`.
11219
 
11220
  #### Create directory <a id="fs.op.create.directory">[[fs.op.create.directory]]</a>
11221
 
11222
  ``` cpp
11223
+ bool filesystem::create_directory(const path& p);
11224
+ bool filesystem::create_directory(const path& p, error_code& ec) noexcept;
11225
  ```
11226
 
11227
  *Effects:* Creates the directory `p` resolves to, as if by POSIX `mkdir`
11228
  with a second argument of `static_cast<int>(perms::all)`. If `mkdir`
11229
  fails because `p` resolves to an existing directory, no error is
 
11232
  *Returns:* `true` if a new directory was created, otherwise `false`.
11233
 
11234
  *Throws:* As specified in  [[fs.err.report]].
11235
 
11236
  ``` cpp
11237
+ bool filesystem::create_directory(const path& p, const path& existing_p);
11238
+ bool filesystem::create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
11239
  ```
11240
 
11241
  *Effects:* Creates the directory `p` resolves to, with attributes copied
11242
  from directory `existing_p`. The set of attributes copied is operating
11243
  system dependent. If `mkdir` fails because `p` resolves to an existing
 
11257
  *Throws:* As specified in  [[fs.err.report]].
11258
 
11259
  #### Create directory symlink <a id="fs.op.create.dir.symlk">[[fs.op.create.dir.symlk]]</a>
11260
 
11261
  ``` cpp
11262
+ void filesystem::create_directory_symlink(const path& to, const path& new_symlink);
11263
+ void filesystem::create_directory_symlink(const path& to, const path& new_symlink,
11264
  error_code& ec) noexcept;
11265
  ```
11266
 
11267
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
11268
 
 
11270
  an unspecified representation of `to`.
11271
 
11272
  *Throws:* As specified in  [[fs.err.report]].
11273
 
11274
  [*Note 1*: Some operating systems require symlink creation to identify
11275
+ that the link is to a directory. Thus, `create_symlink()` (instead of
11276
+ `create_directory_symlink()`) cannot be used reliably to create
11277
+ directory symlinks. — *end note*]
11278
 
11279
  [*Note 2*: Some operating systems do not support symbolic links at all
11280
  or support them only for regular files. Some file systems (such as the
11281
  FAT file system) do not support symbolic links regardless of the
11282
  operating system. — *end note*]
11283
 
11284
  #### Create hard link <a id="fs.op.create.hard.lk">[[fs.op.create.hard.lk]]</a>
11285
 
11286
  ``` cpp
11287
+ void filesystem::create_hard_link(const path& to, const path& new_hard_link);
11288
+ void filesystem::create_hard_link(const path& to, const path& new_hard_link,
11289
  error_code& ec) noexcept;
11290
  ```
11291
 
11292
  *Effects:* Establishes the postcondition, as if by POSIX `link()`.
11293
 
 
11305
  file. — *end note*]
11306
 
11307
  #### Create symlink <a id="fs.op.create.symlink">[[fs.op.create.symlink]]</a>
11308
 
11309
  ``` cpp
11310
+ void filesystem::create_symlink(const path& to, const path& new_symlink);
11311
+ void filesystem::create_symlink(const path& to, const path& new_symlink,
11312
  error_code& ec) noexcept;
11313
  ```
11314
 
11315
  *Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
11316
 
 
11325
  operating system. — *end note*]
11326
 
11327
  #### Current path <a id="fs.op.current.path">[[fs.op.current.path]]</a>
11328
 
11329
  ``` cpp
11330
+ path filesystem::current_path();
11331
+ path filesystem::current_path(error_code& ec);
11332
  ```
11333
 
11334
  *Returns:* The absolute path of the current working directory, whose
11335
  pathname in the native format is obtained as if by POSIX `getcwd()`. The
11336
  signature with argument `ec` returns `path()` if an error occurs.
 
11344
  [*Note 1*: The `current_path()` name was chosen to emphasize that the
11345
  returned value is a path, not just a single directory
11346
  name. — *end note*]
11347
 
11348
  [*Note 2*: The current path as returned by many operating systems is a
11349
+ dangerous global variable and can be changed unexpectedly by third-party
11350
  or system library functions, or by another thread. — *end note*]
11351
 
11352
  ``` cpp
11353
+ void filesystem::current_path(const path& p);
11354
+ void filesystem::current_path(const path& p, error_code& ec) noexcept;
11355
  ```
11356
 
11357
  *Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
11358
 
11359
  *Ensures:* `equivalent(p, current_path())`.
11360
 
11361
  *Throws:* As specified in  [[fs.err.report]].
11362
 
11363
  [*Note 3*: The current path for many operating systems is a dangerous
11364
+ global state and can be changed unexpectedly by third-party or system
11365
  library functions, or by another thread. — *end note*]
11366
 
11367
  #### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
11368
 
11369
  ``` cpp
11370
+ bool filesystem::equivalent(const path& p1, const path& p2);
11371
+ bool filesystem::equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
11372
  ```
11373
 
 
 
 
 
11374
  Two paths are considered to resolve to the same file system entity if
11375
  two candidate entities reside on the same device at the same location.
11376
 
11377
  [*Note 1*: On POSIX platforms, this is determined as if by the values
11378
  of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
11379
  having equal `st_dev` values and equal `st_ino` values. — *end note*]
11380
 
11381
+ *Returns:* `true`, if `p1` and `p2` resolve to the same file system
11382
+ entity, otherwise `false`. The signature with argument `ec` returns
11383
+ `false` if an error occurs.
11384
+
11385
+ *Throws:* As specified in  [[fs.err.report]].
11386
+
11387
  *Remarks:* `!exists(p1) || !exists(p2)` is an error.
11388
 
 
 
11389
  #### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
11390
 
11391
  ``` cpp
11392
+ bool filesystem::exists(file_status s) noexcept;
11393
  ```
11394
 
11395
  *Returns:* `status_known(s) && s.type() != file_type::not_found`.
11396
 
11397
  ``` cpp
11398
+ bool filesystem::exists(const path& p);
11399
+ bool filesystem::exists(const path& p, error_code& ec) noexcept;
11400
  ```
11401
 
11402
  Let `s` be a `file_status`, determined as if by `status(p)` or
11403
  `status(p, ec)`, respectively.
11404
 
 
11410
  *Throws:* As specified in  [[fs.err.report]].
11411
 
11412
  #### File size <a id="fs.op.file.size">[[fs.op.file.size]]</a>
11413
 
11414
  ``` cpp
11415
+ uintmax_t filesystem::file_size(const path& p);
11416
+ uintmax_t filesystem::file_size(const path& p, error_code& ec) noexcept;
11417
  ```
11418
 
11419
  *Effects:* If `exists(p)` is `false`, an error is
11420
  reported [[fs.err.report]].
11421
 
 
11432
  *Throws:* As specified in  [[fs.err.report]].
11433
 
11434
  #### Hard link count <a id="fs.op.hard.lk.ct">[[fs.op.hard.lk.ct]]</a>
11435
 
11436
  ``` cpp
11437
+ uintmax_t filesystem::hard_link_count(const path& p);
11438
+ uintmax_t filesystem::hard_link_count(const path& p, error_code& ec) noexcept;
11439
  ```
11440
 
11441
  *Returns:* The number of hard links for `p`. The signature with argument
11442
  `ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
11443
 
11444
  *Throws:* As specified in  [[fs.err.report]].
11445
 
11446
  #### Is block file <a id="fs.op.is.block.file">[[fs.op.is.block.file]]</a>
11447
 
11448
  ``` cpp
11449
+ bool filesystem::is_block_file(file_status s) noexcept;
11450
  ```
11451
 
11452
  *Returns:* `s.type() == file_type::block`.
11453
 
11454
  ``` cpp
11455
+ bool filesystem::is_block_file(const path& p);
11456
+ bool filesystem::is_block_file(const path& p, error_code& ec) noexcept;
11457
  ```
11458
 
11459
  *Returns:* `is_block_file(status(p))` or `is_block_file(status(p, ec))`,
11460
  respectively. The signature with argument `ec` returns `false` if an
11461
  error occurs.
 
11463
  *Throws:* As specified in  [[fs.err.report]].
11464
 
11465
  #### Is character file <a id="fs.op.is.char.file">[[fs.op.is.char.file]]</a>
11466
 
11467
  ``` cpp
11468
+ bool filesystem::is_character_file(file_status s) noexcept;
11469
  ```
11470
 
11471
  *Returns:* `s.type() == file_type::character`.
11472
 
11473
  ``` cpp
11474
+ bool filesystem::is_character_file(const path& p);
11475
+ bool filesystem::is_character_file(const path& p, error_code& ec) noexcept;
11476
  ```
11477
 
11478
  *Returns:* `is_character_file(status(p))` or
11479
  `is_character_file(status(p, ec))`, respectively.
11480
  The signature with argument `ec` returns `false` if an error occurs.
 
11482
  *Throws:* As specified in  [[fs.err.report]].
11483
 
11484
  #### Is directory <a id="fs.op.is.directory">[[fs.op.is.directory]]</a>
11485
 
11486
  ``` cpp
11487
+ bool filesystem::is_directory(file_status s) noexcept;
11488
  ```
11489
 
11490
  *Returns:* `s.type() == file_type::directory`.
11491
 
11492
  ``` cpp
11493
+ bool filesystem::is_directory(const path& p);
11494
+ bool filesystem::is_directory(const path& p, error_code& ec) noexcept;
11495
  ```
11496
 
11497
  *Returns:* `is_directory(status(p))` or `is_directory(status(p, ec))`,
11498
  respectively. The signature with argument `ec` returns `false` if an
11499
  error occurs.
 
11501
  *Throws:* As specified in  [[fs.err.report]].
11502
 
11503
  #### Is empty <a id="fs.op.is.empty">[[fs.op.is.empty]]</a>
11504
 
11505
  ``` cpp
11506
+ bool filesystem::is_empty(const path& p);
11507
+ bool filesystem::is_empty(const path& p, error_code& ec);
11508
  ```
11509
 
11510
  *Effects:*
11511
 
11512
  - Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
 
11529
  *Throws:* As specified in  [[fs.err.report]].
11530
 
11531
  #### Is fifo <a id="fs.op.is.fifo">[[fs.op.is.fifo]]</a>
11532
 
11533
  ``` cpp
11534
+ bool filesystem::is_fifo(file_status s) noexcept;
11535
  ```
11536
 
11537
  *Returns:* `s.type() == file_type::fifo`.
11538
 
11539
  ``` cpp
11540
+ bool filesystem::is_fifo(const path& p);
11541
+ bool filesystem::is_fifo(const path& p, error_code& ec) noexcept;
11542
  ```
11543
 
11544
  *Returns:* `is_fifo(status(p))` or `is_fifo(status(p, ec))`,
11545
  respectively. The signature with argument `ec` returns `false` if an
11546
  error occurs.
 
11548
  *Throws:* As specified in  [[fs.err.report]].
11549
 
11550
  #### Is other <a id="fs.op.is.other">[[fs.op.is.other]]</a>
11551
 
11552
  ``` cpp
11553
+ bool filesystem::is_other(file_status s) noexcept;
11554
  ```
11555
 
11556
  *Returns:*
11557
  `exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)`.
11558
 
11559
  ``` cpp
11560
+ bool filesystem::is_other(const path& p);
11561
+ bool filesystem::is_other(const path& p, error_code& ec) noexcept;
11562
  ```
11563
 
11564
  *Returns:* `is_other(status(p))` or `is_other(status(p, ec))`,
11565
  respectively. The signature with argument `ec` returns `false` if an
11566
  error occurs.
 
11568
  *Throws:* As specified in  [[fs.err.report]].
11569
 
11570
  #### Is regular file <a id="fs.op.is.regular.file">[[fs.op.is.regular.file]]</a>
11571
 
11572
  ``` cpp
11573
+ bool filesystem::is_regular_file(file_status s) noexcept;
11574
  ```
11575
 
11576
  *Returns:* `s.type() == file_type::regular`.
11577
 
11578
  ``` cpp
11579
+ bool filesystem::is_regular_file(const path& p);
11580
  ```
11581
 
11582
  *Returns:* `is_regular_file(status(p))`.
11583
 
11584
  *Throws:* `filesystem_error` if `status(p)` would throw
11585
  `filesystem_error`.
11586
 
11587
  ``` cpp
11588
+ bool filesystem::is_regular_file(const path& p, error_code& ec) noexcept;
11589
  ```
11590
 
11591
  *Effects:* Sets `ec` as if by `status(p, ec)`.
11592
 
11593
  [*Note 1*: `file_type::none`, `file_type::not_found` and
 
11598
  occurs.
11599
 
11600
  #### Is socket <a id="fs.op.is.socket">[[fs.op.is.socket]]</a>
11601
 
11602
  ``` cpp
11603
+ bool filesystem::is_socket(file_status s) noexcept;
11604
  ```
11605
 
11606
  *Returns:* `s.type() == file_type::socket`.
11607
 
11608
  ``` cpp
11609
+ bool filesystem::is_socket(const path& p);
11610
+ bool filesystem::is_socket(const path& p, error_code& ec) noexcept;
11611
  ```
11612
 
11613
  *Returns:* `is_socket(status(p))` or `is_socket(status(p, ec))`,
11614
  respectively. The signature with argument `ec` returns `false` if an
11615
  error occurs.
 
11617
  *Throws:* As specified in  [[fs.err.report]].
11618
 
11619
  #### Is symlink <a id="fs.op.is.symlink">[[fs.op.is.symlink]]</a>
11620
 
11621
  ``` cpp
11622
+ bool filesystem::is_symlink(file_status s) noexcept;
11623
  ```
11624
 
11625
  *Returns:* `s.type() == file_type::symlink`.
11626
 
11627
  ``` cpp
11628
+ bool filesystem::is_symlink(const path& p);
11629
+ bool filesystem::is_symlink(const path& p, error_code& ec) noexcept;
11630
  ```
11631
 
11632
  *Returns:* `is_symlink(symlink_status(p))` or
11633
  `is_symlink(symlink_status(p, ec))`, respectively. The signature with
11634
  argument `ec` returns `false` if an error occurs.
 
11636
  *Throws:* As specified in  [[fs.err.report]].
11637
 
11638
  #### Last write time <a id="fs.op.last.write.time">[[fs.op.last.write.time]]</a>
11639
 
11640
  ``` cpp
11641
+ file_time_type filesystem::last_write_time(const path& p);
11642
+ file_time_type filesystem::last_write_time(const path& p, error_code& ec) noexcept;
11643
  ```
11644
 
11645
  *Returns:* The time of last data modification of `p`, determined as if
11646
  by the value of the POSIX `stat` class member `st_mtime` obtained as if
11647
  by POSIX `stat()`. The signature with argument `ec` returns
11648
  `file_time_type::min()` if an error occurs.
11649
 
11650
  *Throws:* As specified in  [[fs.err.report]].
11651
 
11652
  ``` cpp
11653
+ void filesystem::last_write_time(const path& p, file_time_type new_time);
11654
+ void filesystem::last_write_time(const path& p, file_time_type new_time,
11655
  error_code& ec) noexcept;
11656
  ```
11657
 
11658
  *Effects:* Sets the time of last data modification of the file resolved
11659
  to by `p` to `new_time`, as if by POSIX `futimens()`.
11660
 
11661
  *Throws:* As specified in  [[fs.err.report]].
11662
 
11663
  [*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
11664
+ specified because it does not necessarily hold for file systems with
11665
+ coarse time granularity. — *end note*]
11666
 
11667
  #### Permissions <a id="fs.op.permissions">[[fs.op.permissions]]</a>
11668
 
11669
  ``` cpp
11670
+ void filesystem::permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
11671
+ void filesystem::permissions(const path& p, perms prms, error_code& ec) noexcept;
11672
+ void filesystem::permissions(const path& p, perms prms, perm_options opts, error_code& ec);
11673
  ```
11674
 
11675
  *Preconditions:* Exactly one of the `perm_options` constants `replace`,
11676
  `add`, or `remove` is present in `opts`.
11677
 
 
 
 
 
11678
  *Effects:* Applies the action specified by `opts` to the file `p`
11679
  resolves to, or to file `p` itself if `p` is a symbolic link and
11680
  `perm_options::nofollow` is set in `opts`. The action is applied as if
11681
  by POSIX `fchmodat()`.
11682
 
11683
  [*Note 1*: Conceptually permissions are viewed as bits, but the actual
11684
+ implementation can use some other mechanism. — *end note*]
11685
 
11686
  *Throws:* As specified in  [[fs.err.report]].
11687
 
11688
+ *Remarks:* The second signature behaves as if it had an additional
11689
+ parameter `perm_options` `opts` with an argument of
11690
+ `perm_options::replace`.
11691
+
11692
  #### Proximate <a id="fs.op.proximate">[[fs.op.proximate]]</a>
11693
 
11694
  ``` cpp
11695
+ path filesystem::proximate(const path& p, error_code& ec);
11696
  ```
11697
 
11698
  *Returns:* `proximate(p, current_path(), ec)`.
11699
 
11700
  *Throws:* As specified in  [[fs.err.report]].
11701
 
11702
  ``` cpp
11703
+ path filesystem::proximate(const path& p, const path& base = current_path());
11704
+ path filesystem::proximate(const path& p, const path& base, error_code& ec);
11705
  ```
11706
 
11707
  *Returns:* For the first form:
11708
 
11709
  ``` cpp
 
11721
  *Throws:* As specified in  [[fs.err.report]].
11722
 
11723
  #### Read symlink <a id="fs.op.read.symlink">[[fs.op.read.symlink]]</a>
11724
 
11725
  ``` cpp
11726
+ path filesystem::read_symlink(const path& p);
11727
+ path filesystem::read_symlink(const path& p, error_code& ec);
11728
  ```
11729
 
11730
  *Returns:* If `p` resolves to a symbolic link, a `path` object
11731
  containing the contents of that symbolic link. The signature with
11732
  argument `ec` returns `path()` if an error occurs.
 
11737
  link. — *end note*]
11738
 
11739
  #### Relative <a id="fs.op.relative">[[fs.op.relative]]</a>
11740
 
11741
  ``` cpp
11742
+ path filesystem::relative(const path& p, error_code& ec);
11743
  ```
11744
 
11745
  *Returns:* `relative(p, current_path(), ec)`.
11746
 
11747
  *Throws:* As specified in  [[fs.err.report]].
11748
 
11749
  ``` cpp
11750
+ path filesystem::relative(const path& p, const path& base = current_path());
11751
+ path filesystem::relative(const path& p, const path& base, error_code& ec);
11752
  ```
11753
 
11754
  *Returns:* For the first form:
11755
 
11756
  ``` cpp
 
11768
  *Throws:* As specified in  [[fs.err.report]].
11769
 
11770
  #### Remove <a id="fs.op.remove">[[fs.op.remove]]</a>
11771
 
11772
  ``` cpp
11773
+ bool filesystem::remove(const path& p);
11774
+ bool filesystem::remove(const path& p, error_code& ec) noexcept;
11775
  ```
11776
 
11777
  *Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
11778
  as if by POSIX `remove()`.
11779
 
 
11788
  *Throws:* As specified in  [[fs.err.report]].
11789
 
11790
  #### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
11791
 
11792
  ``` cpp
11793
+ uintmax_t filesystem::remove_all(const path& p);
11794
+ uintmax_t filesystem::remove_all(const path& p, error_code& ec);
11795
  ```
11796
 
11797
  *Effects:* Recursively deletes the contents of `p` if it exists, then
11798
  deletes file `p` itself, as if by POSIX `remove()`.
11799
 
 
11808
  *Throws:* As specified in  [[fs.err.report]].
11809
 
11810
  #### Rename <a id="fs.op.rename">[[fs.op.rename]]</a>
11811
 
11812
  ``` cpp
11813
+ void filesystem::rename(const path& old_p, const path& new_p);
11814
+ void filesystem::rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
11815
  ```
11816
 
11817
  *Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
11818
 
11819
  [*Note 1*:
11820
 
11821
  - If `old_p` and `new_p` resolve to the same existing file, no action is
11822
  taken.
11823
+ - Otherwise, the rename can include the following effects:
11824
  - if `new_p` resolves to an existing non-directory file, `new_p` is
11825
  removed; otherwise,
11826
  - if `new_p` resolves to an existing directory, `new_p` is removed if
11827
+ empty on POSIX compliant operating systems but might be an error on
11828
  other operating systems.
11829
 
11830
  A symbolic link is itself renamed, rather than the file it resolves to.
11831
 
11832
  — *end note*]
 
11834
  *Throws:* As specified in  [[fs.err.report]].
11835
 
11836
  #### Resize file <a id="fs.op.resize.file">[[fs.op.resize.file]]</a>
11837
 
11838
  ``` cpp
11839
+ void filesystem::resize_file(const path& p, uintmax_t new_size);
11840
+ void filesystem::resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
11841
  ```
11842
 
11843
  *Effects:* Causes the size that would be returned by `file_size(p)` to
11844
  be equal to `new_size`, as if by POSIX `truncate()`.
11845
 
11846
  *Throws:* As specified in  [[fs.err.report]].
11847
 
11848
  #### Space <a id="fs.op.space">[[fs.op.space]]</a>
11849
 
11850
  ``` cpp
11851
+ space_info filesystem::space(const path& p);
11852
+ space_info filesystem::space(const path& p, error_code& ec) noexcept;
11853
  ```
11854
 
11855
  *Returns:* An object of type `space_info`. The value of the `space_info`
11856
  object is determined as if by using POSIX `statvfs` to obtain a POSIX
11857
  `struct statvfs`, and then multiplying its `f_blocks`, `f_bfree`, and
 
11864
  *Throws:* As specified in  [[fs.err.report]].
11865
 
11866
  *Remarks:* The value of member `space_info::available` is operating
11867
  system dependent.
11868
 
11869
+ [*Note 1*: `available` might be less than `free`. — *end note*]
11870
 
11871
  #### Status <a id="fs.op.status">[[fs.op.status]]</a>
11872
 
11873
  ``` cpp
11874
+ file_status filesystem::status(const path& p);
11875
  ```
11876
 
11877
  *Effects:* As if:
11878
 
11879
  ``` cpp
 
11891
  [*Note 1*: `result` values of `file_status(file_type::not_found)` and
11892
  `file_status(file_type::unknown)` are not considered failures and do not
11893
  cause an exception to be thrown. — *end note*]
11894
 
11895
  ``` cpp
11896
+ file_status filesystem::status(const path& p, error_code& ec) noexcept;
11897
  ```
11898
 
11899
  *Effects:* If possible, determines the attributes of the file `p`
11900
  resolves to, as if by using POSIX `stat()` to obtain a POSIX
11901
  `struct stat`. If, during attribute determination, the underlying file
 
11956
  pathname resolution continues using the contents of the symbolic link.
11957
 
11958
  #### Status known <a id="fs.op.status.known">[[fs.op.status.known]]</a>
11959
 
11960
  ``` cpp
11961
+ bool filesystem::status_known(file_status s) noexcept;
11962
  ```
11963
 
11964
  *Returns:* `s.type() != file_type::none`.
11965
 
11966
  #### Symlink status <a id="fs.op.symlink.status">[[fs.op.symlink.status]]</a>
11967
 
11968
  ``` cpp
11969
+ file_status filesystem::symlink_status(const path& p);
11970
+ file_status filesystem::symlink_status(const path& p, error_code& ec) noexcept;
11971
  ```
11972
 
11973
  *Effects:* Same as `status()`, above, except that the attributes of `p`
11974
  are determined as if by using POSIX `lstat()` to obtain a POSIX
11975
  `struct stat`.
 
11981
  *Returns:* Same as `status()`, above, except that if the attributes
11982
  indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
11983
  `file_status(file_type::symlink, prms)`. The signature with argument
11984
  `ec` returns `file_status(file_type::none)` if an error occurs.
11985
 
11986
+ *Throws:* As specified in  [[fs.err.report]].
11987
+
11988
  *Remarks:* Pathname resolution terminates if `p` names a symbolic link.
11989
 
 
 
11990
  #### Temporary directory path <a id="fs.op.temp.dir.path">[[fs.op.temp.dir.path]]</a>
11991
 
11992
  ``` cpp
11993
+ path filesystem::temp_directory_path();
11994
+ path filesystem::temp_directory_path(error_code& ec);
11995
  ```
11996
 
11997
  Let `p` be an unspecified directory path suitable for temporary files.
11998
 
11999
  *Effects:* If `exists(p)` is `false` or `is_directory(p)` is `false`, an
 
12012
  function. — *end example*]
12013
 
12014
  #### Weakly canonical <a id="fs.op.weakly.canonical">[[fs.op.weakly.canonical]]</a>
12015
 
12016
  ``` cpp
12017
+ path filesystem::weakly_canonical(const path& p);
12018
+ path filesystem::weakly_canonical(const path& p, error_code& ec);
12019
  ```
12020
 
 
 
 
12021
  *Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
12022
  determine existence, return a path composed by `operator/=` from the
12023
  result of calling `canonical()` with a path argument composed of the
12024
  leading elements of `p` that exist, if any, followed by the elements of
12025
  `p` that do not exist, if any. For the first form, `canonical()` is
 
12027
  `canonical()` is called with `ec` as an `error_code` argument, and
12028
  `path()` is returned at the first error occurrence, if any.
12029
 
12030
  *Ensures:* The returned path is in normal form [[fs.path.generic]].
12031
 
12032
+ *Returns:* `p` with symlinks resolved and the result
12033
+ normalized [[fs.path.generic]].
12034
 
12035
  *Throws:* As specified in  [[fs.err.report]].
12036
 
12037
  ## C library files <a id="c.files">[[c.files]]</a>
12038
 
 
12126
  #include <cstdint> // see [cstdint.syn]
12127
 
12128
  namespace std {
12129
  using imaxdiv_t = see below;
12130
 
12131
+ constexpr intmax_t imaxabs(intmax_t j);
12132
+ constexpr imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
12133
  intmax_t strtoimax(const char* nptr, char** endptr, int base);
12134
  uintmax_t strtoumax(const char* nptr, char** endptr, int base);
12135
  intmax_t wcstoimax(const wchar_t* nptr, wchar_t** endptr, int base);
12136
  uintmax_t wcstoumax(const wchar_t* nptr, wchar_t** endptr, int base);
12137
 
12138
+ constexpr intmax_t abs(intmax_t); // optional, see below
12139
+ constexpr imaxdiv_t div(intmax_t, intmax_t); // optional, see below
12140
  }
12141
 
12142
  #define PRIdN see below
12143
  #define PRIiN see below
12144
  #define PRIoN see below
 
12199
  The contents and meaning of the header `<cinttypes>` are the same as the
12200
  C standard library header `<inttypes.h>`, with the following changes:
12201
 
12202
  - The header `<cinttypes>` includes the header `<cstdint>` instead of
12203
  `<stdint.h>`, and
12204
+ - `intmax_t` and `uintmax_t` are not required to be able to represent
12205
+ all values of extended integer types wider than `long long` and
12206
+ `unsigned long long`, respectively, and
12207
  - if and only if the type `intmax_t` designates an extended integer type
12208
  [[basic.fundamental]], the following function signatures are added:
12209
  ``` cpp
12210
+ constexpr intmax_t abs(intmax_t);
12211
+ constexpr imaxdiv_t div(intmax_t, intmax_t);
12212
  ```
12213
 
12214
  which shall have the same semantics as the function signatures
12215
+ `constexpr intmax_t imaxabs(intmax_t)` and
12216
+ `constexpr imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
12217
 
12218
  See also: ISO C 7.8
12219
 
12220
+ Each of the `PRI` macros listed in this subclause is defined if and only
12221
+ if the implementation defines the corresponding *typedef-name* in 
12222
+ [[cstdint.syn]]. Each of the `SCN` macros listed in this subclause is
12223
+ defined if and only if the implementation defines the corresponding
12224
+ *typedef-name* in  [[cstdint.syn]] and has a suitable `fscanf` length
12225
+ modifier for the type.
12226
+
12227
  <!-- Link reference definitions -->
12228
  [adjustfield.manip]: #adjustfield.manip
12229
+ [allocator.requirements.general]: library.md#allocator.requirements.general
12230
  [basefield.manip]: #basefield.manip
12231
  [basic.fundamental]: basic.md#basic.fundamental
12232
  [basic.ios.cons]: #basic.ios.cons
12233
  [basic.ios.copyfmt]: #basic.ios.copyfmt
12234
  [basic.ios.members]: #basic.ios.members
12235
+ [basic.start.dynamic]: basic.md#basic.start.dynamic
12236
  [basic.start.main]: basic.md#basic.start.main
12237
  [bidirectional.iterators]: iterators.md#bidirectional.iterators
12238
  [bitmask.types]: library.md#bitmask.types
12239
  [c.files]: #c.files
12240
  [char.traits]: strings.md#char.traits
12241
+ [char.traits.specializations]: strings.md#char.traits.specializations
12242
+ [character.seq]: library.md#character.seq
12243
  [cinttypes.syn]: #cinttypes.syn
12244
  [container.requirements.general]: containers.md#container.requirements.general
 
12245
  [cpp17.copyassignable]: #cpp17.copyassignable
12246
  [cpp17.copyconstructible]: #cpp17.copyconstructible
12247
  [cpp17.defaultconstructible]: #cpp17.defaultconstructible
12248
  [cpp17.destructible]: #cpp17.destructible
12249
  [cpp17.equalitycomparable]: #cpp17.equalitycomparable
12250
+ [cstdint.syn]: support.md#cstdint.syn
12251
  [cstdio.syn]: #cstdio.syn
12252
+ [defns.ntcts]: intro.md#defns.ntcts
12253
  [enumerated.types]: library.md#enumerated.types
12254
  [error.reporting]: #error.reporting
12255
  [ext.manip]: #ext.manip
12256
  [file.streams]: #file.streams
12257
  [filebuf]: #filebuf
12258
  [filebuf.assign]: #filebuf.assign
12259
  [filebuf.cons]: #filebuf.cons
12260
+ [filebuf.general]: #filebuf.general
12261
  [filebuf.members]: #filebuf.members
12262
  [filebuf.open.modes]: #filebuf.open.modes
12263
  [filebuf.seekoff]: #filebuf.seekoff
12264
  [filebuf.virtuals]: #filebuf.virtuals
12265
  [filesystems]: #filesystems
12266
  [floatfield.manip]: #floatfield.manip
12267
  [fmtflags.manip]: #fmtflags.manip
12268
  [fmtflags.state]: #fmtflags.state
12269
+ [format.err.report]: utilities.md#format.err.report
12270
  [fpos]: #fpos
12271
  [fpos.members]: #fpos.members
12272
  [fpos.operations]: #fpos.operations
12273
  [fs.class.directory.entry]: #fs.class.directory.entry
12274
+ [fs.class.directory.entry.general]: #fs.class.directory.entry.general
12275
  [fs.class.directory.iterator]: #fs.class.directory.iterator
12276
+ [fs.class.directory.iterator.general]: #fs.class.directory.iterator.general
12277
  [fs.class.file.status]: #fs.class.file.status
12278
+ [fs.class.file.status.general]: #fs.class.file.status.general
12279
  [fs.class.filesystem.error]: #fs.class.filesystem.error
12280
+ [fs.class.filesystem.error.general]: #fs.class.filesystem.error.general
12281
  [fs.class.path]: #fs.class.path
12282
+ [fs.class.path.general]: #fs.class.path.general
12283
  [fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
12284
+ [fs.class.rec.dir.itr.general]: #fs.class.rec.dir.itr.general
12285
  [fs.conform.9945]: #fs.conform.9945
12286
  [fs.conform.os]: #fs.conform.os
12287
  [fs.conformance]: #fs.conformance
12288
+ [fs.conformance.general]: #fs.conformance.general
12289
  [fs.dir.entry.cons]: #fs.dir.entry.cons
12290
+ [fs.dir.entry.io]: #fs.dir.entry.io
12291
  [fs.dir.entry.mods]: #fs.dir.entry.mods
12292
  [fs.dir.entry.obs]: #fs.dir.entry.obs
12293
  [fs.dir.itr.members]: #fs.dir.itr.members
12294
  [fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
12295
  [fs.enum]: #fs.enum
 
12304
  [fs.file.status.mods]: #fs.file.status.mods
12305
  [fs.file.status.obs]: #fs.file.status.obs
12306
  [fs.filesystem.error.members]: #fs.filesystem.error.members
12307
  [fs.filesystem.syn]: #fs.filesystem.syn
12308
  [fs.general]: #fs.general
 
12309
  [fs.op.absolute]: #fs.op.absolute
12310
  [fs.op.canonical]: #fs.op.canonical
12311
  [fs.op.copy]: #fs.op.copy
12312
  [fs.op.copy.file]: #fs.op.copy.file
12313
  [fs.op.copy.symlink]: #fs.op.copy.symlink
 
12319
  [fs.op.current.path]: #fs.op.current.path
12320
  [fs.op.equivalent]: #fs.op.equivalent
12321
  [fs.op.exists]: #fs.op.exists
12322
  [fs.op.file.size]: #fs.op.file.size
12323
  [fs.op.funcs]: #fs.op.funcs
12324
+ [fs.op.funcs.general]: #fs.op.funcs.general
12325
  [fs.op.hard.lk.ct]: #fs.op.hard.lk.ct
12326
  [fs.op.is.block.file]: #fs.op.is.block.file
12327
  [fs.op.is.char.file]: #fs.op.is.char.file
12328
  [fs.op.is.directory]: #fs.op.is.directory
12329
  [fs.op.is.empty]: #fs.op.is.empty
 
12356
  [fs.path.decompose]: #fs.path.decompose
12357
  [fs.path.fmt.cvt]: #fs.path.fmt.cvt
12358
  [fs.path.gen]: #fs.path.gen
12359
  [fs.path.generic]: #fs.path.generic
12360
  [fs.path.generic.obs]: #fs.path.generic.obs
12361
+ [fs.path.hash]: #fs.path.hash
12362
  [fs.path.io]: #fs.path.io
12363
  [fs.path.itr]: #fs.path.itr
12364
  [fs.path.member]: #fs.path.member
12365
  [fs.path.modifiers]: #fs.path.modifiers
12366
  [fs.path.native.obs]: #fs.path.native.obs
 
12370
  [fs.path.type.cvt]: #fs.path.type.cvt
12371
  [fs.race.behavior]: #fs.race.behavior
12372
  [fs.rec.dir.itr.members]: #fs.rec.dir.itr.members
12373
  [fs.rec.dir.itr.nonmembers]: #fs.rec.dir.itr.nonmembers
12374
  [fs.req]: #fs.req
 
12375
  [fstream]: #fstream
 
12376
  [fstream.cons]: #fstream.cons
12377
+ [fstream.general]: #fstream.general
12378
  [fstream.members]: #fstream.members
12379
+ [fstream.swap]: #fstream.swap
12380
  [fstream.syn]: #fstream.syn
12381
  [ifstream]: #ifstream
 
12382
  [ifstream.cons]: #ifstream.cons
12383
+ [ifstream.general]: #ifstream.general
12384
  [ifstream.members]: #ifstream.members
12385
+ [ifstream.swap]: #ifstream.swap
12386
  [input.iterators]: iterators.md#input.iterators
12387
  [input.output]: #input.output
12388
  [input.output.general]: #input.output.general
12389
  [input.streams]: #input.streams
12390
+ [input.streams.general]: #input.streams.general
12391
  [intro.multithread]: basic.md#intro.multithread
12392
  [intro.races]: basic.md#intro.races
12393
  [iomanip.syn]: #iomanip.syn
12394
  [ios]: #ios
12395
  [ios.base]: #ios.base
12396
  [ios.base.callback]: #ios.base.callback
12397
  [ios.base.cons]: #ios.base.cons
12398
+ [ios.base.general]: #ios.base.general
12399
  [ios.base.locales]: #ios.base.locales
12400
  [ios.base.storage]: #ios.base.storage
12401
  [ios.failure]: #ios.failure
12402
  [ios.fmtflags]: #ios.fmtflags
12403
  [ios.fmtflags.const]: #ios.fmtflags.const
 
12420
  [iostream.limits.imbue]: #iostream.limits.imbue
12421
  [iostream.objects]: #iostream.objects
12422
  [iostream.objects.overview]: #iostream.objects.overview
12423
  [iostream.syn]: #iostream.syn
12424
  [iostreamclass]: #iostreamclass
12425
+ [iostreamclass.general]: #iostreamclass.general
12426
  [iostreams.base]: #iostreams.base
12427
  [iostreams.limits.pos]: #iostreams.limits.pos
12428
  [iostreams.requirements]: #iostreams.requirements
12429
  [iostreams.summary]: #iostreams.summary
12430
  [iostreams.threadsafety]: #iostreams.threadsafety
12431
+ [ispanstream]: #ispanstream
12432
+ [ispanstream.cons]: #ispanstream.cons
12433
+ [ispanstream.general]: #ispanstream.general
12434
+ [ispanstream.members]: #ispanstream.members
12435
+ [ispanstream.swap]: #ispanstream.swap
12436
  [istream]: #istream
12437
  [istream.assign]: #istream.assign
12438
  [istream.cons]: #istream.cons
12439
  [istream.extractors]: #istream.extractors
12440
  [istream.formatted]: #istream.formatted
12441
  [istream.formatted.arithmetic]: #istream.formatted.arithmetic
12442
  [istream.formatted.reqmts]: #istream.formatted.reqmts
12443
+ [istream.general]: #istream.general
12444
  [istream.manip]: #istream.manip
12445
  [istream.rvalue]: #istream.rvalue
12446
  [istream.sentry]: #istream.sentry
12447
  [istream.syn]: #istream.syn
12448
  [istream.unformatted]: #istream.unformatted
12449
  [istringstream]: #istringstream
 
12450
  [istringstream.cons]: #istringstream.cons
12451
+ [istringstream.general]: #istringstream.general
12452
  [istringstream.members]: #istringstream.members
12453
+ [istringstream.swap]: #istringstream.swap
12454
  [lex.charset]: lex.md#lex.charset
12455
  [locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
12456
  [locale.num.get]: localization.md#locale.num.get
12457
  [namespace.std]: library.md#namespace.std
12458
  [narrow.stream.objects]: #narrow.stream.objects
12459
  [numeric.limits]: support.md#numeric.limits
12460
  [ofstream]: #ofstream
 
12461
  [ofstream.cons]: #ofstream.cons
12462
+ [ofstream.general]: #ofstream.general
12463
  [ofstream.members]: #ofstream.members
12464
+ [ofstream.swap]: #ofstream.swap
12465
+ [ospanstream]: #ospanstream
12466
+ [ospanstream.cons]: #ospanstream.cons
12467
+ [ospanstream.general]: #ospanstream.general
12468
+ [ospanstream.members]: #ospanstream.members
12469
+ [ospanstream.swap]: #ospanstream.swap
12470
  [ostream]: #ostream
12471
  [ostream.assign]: #ostream.assign
12472
  [ostream.cons]: #ostream.cons
12473
  [ostream.formatted]: #ostream.formatted
12474
+ [ostream.formatted.print]: #ostream.formatted.print
12475
  [ostream.formatted.reqmts]: #ostream.formatted.reqmts
12476
+ [ostream.general]: #ostream.general
12477
  [ostream.inserters]: #ostream.inserters
12478
  [ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
12479
  [ostream.inserters.character]: #ostream.inserters.character
12480
  [ostream.manip]: #ostream.manip
12481
  [ostream.rvalue]: #ostream.rvalue
12482
  [ostream.seeks]: #ostream.seeks
12483
  [ostream.sentry]: #ostream.sentry
12484
  [ostream.syn]: #ostream.syn
12485
  [ostream.unformatted]: #ostream.unformatted
12486
  [ostringstream]: #ostringstream
 
12487
  [ostringstream.cons]: #ostringstream.cons
12488
+ [ostringstream.general]: #ostringstream.general
12489
  [ostringstream.members]: #ostringstream.members
12490
+ [ostringstream.swap]: #ostringstream.swap
12491
  [output.streams]: #output.streams
12492
+ [output.streams.general]: #output.streams.general
12493
+ [print.fun]: #print.fun
12494
+ [print.syn]: #print.syn
12495
  [quoted.manip]: #quoted.manip
12496
  [res.on.data.races]: library.md#res.on.data.races
12497
  [res.on.exception.handling]: library.md#res.on.exception.handling
12498
+ [span.streams]: #span.streams
12499
+ [span.streams.overview]: #span.streams.overview
12500
+ [spanbuf]: #spanbuf
12501
+ [spanbuf.assign]: #spanbuf.assign
12502
+ [spanbuf.cons]: #spanbuf.cons
12503
+ [spanbuf.general]: #spanbuf.general
12504
+ [spanbuf.members]: #spanbuf.members
12505
+ [spanbuf.virtuals]: #spanbuf.virtuals
12506
+ [spanstream]: #spanstream
12507
+ [spanstream.cons]: #spanstream.cons
12508
+ [spanstream.general]: #spanstream.general
12509
+ [spanstream.members]: #spanstream.members
12510
+ [spanstream.swap]: #spanstream.swap
12511
+ [spanstream.syn]: #spanstream.syn
12512
  [sstream.syn]: #sstream.syn
12513
  [std.ios.manip]: #std.ios.manip
12514
  [std.manip]: #std.manip
12515
+ [std.modules]: library.md#std.modules
12516
  [stream.buffers]: #stream.buffers
12517
  [stream.types]: #stream.types
12518
  [streambuf]: #streambuf
12519
  [streambuf.assign]: #streambuf.assign
12520
  [streambuf.buffer]: #streambuf.buffer
12521
  [streambuf.cons]: #streambuf.cons
12522
+ [streambuf.general]: #streambuf.general
12523
  [streambuf.get.area]: #streambuf.get.area
12524
  [streambuf.locales]: #streambuf.locales
12525
  [streambuf.members]: #streambuf.members
12526
  [streambuf.protected]: #streambuf.protected
12527
  [streambuf.pub.get]: #streambuf.pub.get
 
12539
  [string.classes]: strings.md#string.classes
12540
  [string.streams]: #string.streams
12541
  [stringbuf]: #stringbuf
12542
  [stringbuf.assign]: #stringbuf.assign
12543
  [stringbuf.cons]: #stringbuf.cons
12544
+ [stringbuf.general]: #stringbuf.general
12545
  [stringbuf.members]: #stringbuf.members
12546
  [stringbuf.seekoff.newoff]: #stringbuf.seekoff.newoff
12547
  [stringbuf.seekoff.pos]: #stringbuf.seekoff.pos
12548
  [stringbuf.virtuals]: #stringbuf.virtuals
12549
  [strings]: strings.md#strings
12550
  [stringstream]: #stringstream
 
12551
  [stringstream.cons]: #stringstream.cons
12552
+ [stringstream.general]: #stringstream.general
12553
  [stringstream.members]: #stringstream.members
12554
+ [stringstream.swap]: #stringstream.swap
12555
  [syncstream]: #syncstream
12556
  [syncstream.osyncstream]: #syncstream.osyncstream
12557
  [syncstream.osyncstream.cons]: #syncstream.osyncstream.cons
12558
  [syncstream.osyncstream.members]: #syncstream.osyncstream.members
12559
  [syncstream.osyncstream.overview]: #syncstream.osyncstream.overview
 
12564
  [syncstream.syncbuf.members]: #syncstream.syncbuf.members
12565
  [syncstream.syncbuf.overview]: #syncstream.syncbuf.overview
12566
  [syncstream.syncbuf.special]: #syncstream.syncbuf.special
12567
  [syncstream.syncbuf.virtuals]: #syncstream.syncbuf.virtuals
12568
  [temp.deduct]: temp.md#temp.deduct
12569
+ [term.unevaluated.operand]: expr.md#term.unevaluated.operand
12570
+ [views.span]: containers.md#views.span
12571
  [wide.stream.objects]: #wide.stream.objects
12572
 
12573
+ [^1]: Typically `long long`.
12574
+
12575
+ [^2]: Most places where `streamsize` is used would use `size_t` in ISO
12576
+ C, or `ssize_t` in POSIX.
12577
+
12578
+ [^3]: It is the implementation’s responsibility to implement headers so
12579
  that including `<iosfwd>` and other headers does not violate the
12580
  rules about multiple occurrences of default arguments.
12581
 
12582
+ [^4]: Constructors and destructors for objects with static storage
 
 
 
12583
  duration can access these objects to read input from `stdin` or
12584
  write output to `stdout` or `stderr`.
12585
 
12586
+ [^5]: This implies that operations on a standard iostream object can be
 
 
 
 
 
12587
  mixed arbitrarily with operations on the corresponding stdio stream.
12588
  In practical terms, synchronization usually means that a standard
12589
  iostream object and a standard stdio object share a buffer.
12590
 
12591
+ [^6]: An implementation is free to implement both the integer array
12592
  pointed at by `iarray` and the pointer array pointed at by `parray`
12593
  as sparse data structures, possibly with a one-element cache for
12594
  each.
12595
 
12596
+ [^7]: For example, because it cannot allocate space.
12597
+
12598
  [^8]: For example, because it cannot allocate space.
12599
 
12600
+ [^9]: This suggests an infinite amount of copying, but the
 
 
12601
  implementation can keep track of the maximum element of the arrays
12602
  that is nonzero.
12603
 
12604
+ [^10]: Checking `badbit` also for `fail()` is historical practice.
12605
 
12606
+ [^11]: The function signature `dec(ios_base&)` can be called by the
12607
  function signature
12608
  `basic_ostream& stream::operator<<(ios_base& (*)(ios_base&))` to
12609
  permit expressions of the form `cout << dec` to change the format
12610
  flags stored in `cout`.
12611
 
12612
+ [^12]: The default constructor is protected for class `basic_streambuf`
12613
+ to assure that only objects for classes derived from this class can
12614
  be constructed.
12615
 
12616
+ [^13]: The morphemes of `showmanyc` are “es-how-many-see”, not
12617
+ “show-manic”.
12618
+
12619
+ [^14]: `underflow` or `uflow` can fail by throwing an exception
12620
  prematurely. The intention is not only that the calls will not
12621
  return `eof()` but that they will return “immediately”.
12622
 
12623
  [^15]: Classes derived from `basic_streambuf` can provide more efficient
12624
  ways to implement `xsgetn()` and `xsputn()` by overriding these
12625
  definitions from the base class.
12626
 
12627
+ [^16]: That is, for each class derived from a specialization of
12628
+ `basic_streambuf` in this Clause [[stringbuf]], [[filebuf]],
12629
+ a specification of how consuming a character effects the associated
12630
+ output sequence is given. There is no requirement on a
12631
+ program-defined class.
12632
 
12633
  [^17]: Typically, `overflow` returns `c` to indicate success, except
12634
  when `traits::eq_int_type(c, traits::eof())` returns `true`, in
12635
  which case it returns `traits::not_eof(c)`.
12636
 
 
12639
  specified.
12640
 
12641
  [^19]: The `sentry` constructor and destructor can also perform
12642
  additional implementation-dependent operations.
12643
 
12644
+ [^20]: See, for example, the function signature
 
 
12645
  `ws(basic_istream&)`[[istream.manip]].
12646
 
12647
+ [^21]: See, for example, the function signature
12648
  `dec(ios_base&)`[[basefield.manip]].
12649
 
12650
+ [^22]: Note that this function is not overloaded on types `signed char`
12651
+ and `unsigned char`.
12652
+
12653
+ [^23]: Note that this function is not overloaded on types `signed char`
12654
+ and `unsigned char`.
12655
 
12656
  [^24]: Note that this function is not overloaded on types `signed char`
12657
  and `unsigned char`.
12658
 
12659
+ [^25]: Since the final input character is “extracted”, it is counted in
 
 
 
 
 
 
12660
  the `gcount()`, even though it is not stored.
12661
 
12662
+ [^26]: This allows an input line which exactly fills the buffer, without
12663
  setting `failbit`. This is different behavior than the historical
12664
  AT&T implementation.
12665
 
12666
+ [^27]: This implies an empty input line will not cause `failbit` to be
12667
  set.
12668
 
12669
+ [^28]: Note that this function is not overloaded on types `signed char`
12670
  and `unsigned char`.
12671
 
12672
+ [^29]: The call `os.tie()->flush()` does not necessarily occur if the
12673
  function can determine that no synchronization is necessary.
12674
 
12675
+ [^30]: The `sentry` constructor and destructor can also perform
12676
  additional implementation-dependent operations.
12677
 
12678
+ [^31]: This is done without causing an `ios_base::failure` to be thrown.
12679
 
12680
+ [^32]: See, for example, the function signature
12681
  `endl(basic_ostream&)`[[ostream.manip]].
12682
 
12683
+ [^33]: See, for example, the function signature
12684
  `dec(ios_base&)`[[basefield.manip]].
12685
 
12686
+ [^34]: This is done without causing an `ios_base::failure` to be thrown.
12687
 
12688
+ [^35]: Note that this function is not overloaded on types `signed char`
12689
  and `unsigned char`.
12690
 
12691
+ [^36]: Note that this function is not overloaded on types `signed char`
12692
  and `unsigned char`.
12693
 
12694
+ [^37]: The expression `cin >> resetiosflags(ios_base::skipws)` clears
12695
  `ios_base::skipws` in the format flags stored in the
12696
  `basic_istream<charT, traits>` object `cin` (the same as
12697
  `cin >> noskipws`), and the expression
12698
  `cout << resetiosflags(ios_base::showbase)` clears
12699
  `ios_base::showbase` in the format flags stored in the
12700
  `basic_ostream<charT, traits>` object `cout` (the same as
12701
  `cout << noshowbase`).
12702
 
12703
+ [^38]: The macro `SEEK_END` is defined, and the function signatures
12704
  `fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
12705
  declared, in `<cstdio>`.