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