- tmp/tmp0skc848x/{from.md → to.md} +2056 -871
tmp/tmp0skc848x/{from.md → to.md}
RENAMED
|
@@ -12,35 +12,25 @@ formatting and manipulators, string streams, and file streams, as
|
|
| 12 |
summarized in [[iostreams.summary]].
|
| 13 |
|
| 14 |
**Table: Input/output library summary** <a id="iostreams.summary">[iostreams.summary]</a>
|
| 15 |
|
| 16 |
| Subclause | | Header |
|
| 17 |
-
| -------------------------- | --------------------------- | ------------------------------------- |
|
| 18 |
| [[iostreams.requirements]] | Requirements | |
|
| 19 |
| [[iostream.forward]] | Forward declarations | `<iosfwd>` |
|
| 20 |
| [[iostream.objects]] | Standard iostream objects | `<iostream>` |
|
| 21 |
| [[iostreams.base]] | Iostreams base classes | `<ios>` |
|
| 22 |
| [[stream.buffers]] | Stream buffers | `<streambuf>` |
|
| 23 |
-
| [[iostream.format]] | Formatting and manipulators | `<
|
| 24 |
| [[string.streams]] | String streams | `<sstream>` |
|
|
|
|
| 25 |
| [[file.streams]] | File streams | `<fstream>` |
|
| 26 |
| [[syncstream]] | Synchronized output streams | `<syncstream>` |
|
| 27 |
| [[filesystems]] | File systems | `<filesystem>` |
|
| 28 |
| [[c.files]] | C library files | `<cstdio>`, `<cinttypes>` |
|
| 29 |
|
| 30 |
|
| 31 |
-
[*Note 1*: Figure [[fig:iostreams.streampos]] illustrates
|
| 32 |
-
relationships among various types described in this clause. A line from
|
| 33 |
-
**A** to **B** indicates that **A** is an alias (e.g., a typedef) for
|
| 34 |
-
**B** or that **A** is defined in terms of **B**.
|
| 35 |
-
|
| 36 |
-
<a id="fig:iostreams.streampos"></a>
|
| 37 |
-
|
| 38 |
-
![Stream position, offset, and size types \[fig:iostreams.streampos\]](images/figstreampos.svg)
|
| 39 |
-
|
| 40 |
-
— *end note*]
|
| 41 |
-
|
| 42 |
## Iostreams requirements <a id="iostreams.requirements">[[iostreams.requirements]]</a>
|
| 43 |
|
| 44 |
### Imbue limitations <a id="iostream.limits.imbue">[[iostream.limits.imbue]]</a>
|
| 45 |
|
| 46 |
No function described in [[input.output]] except for `ios_base::imbue`
|
|
@@ -48,30 +38,54 @@ and `basic_filebuf::pubimbue` causes any instance of `basic_ios::imbue`
|
|
| 48 |
or `basic_streambuf::imbue` to be called. If any user function called
|
| 49 |
from a function declared in [[input.output]] or as an overriding virtual
|
| 50 |
function of any class declared in [[input.output]] calls `imbue`, the
|
| 51 |
behavior is undefined.
|
| 52 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 53 |
### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
|
| 54 |
|
| 55 |
The classes of [[input.output]] with template arguments `charT` and
|
| 56 |
`traits` behave as described if `traits::pos_type` and
|
| 57 |
`traits::off_type` are `streampos` and `streamoff` respectively. Except
|
| 58 |
as noted explicitly below, their behavior when `traits::pos_type` and
|
| 59 |
`traits::off_type` are other types is *implementation-defined*.
|
| 60 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 61 |
In the classes of [[input.output]], a template parameter with name
|
| 62 |
`charT` represents a member of the set of types containing `char`,
|
| 63 |
`wchar_t`, and any other *implementation-defined* character types that
|
| 64 |
meet the requirements for a character on which any of the iostream
|
| 65 |
components can be instantiated.
|
| 66 |
|
| 67 |
### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
|
| 68 |
|
| 69 |
-
Concurrent access to a stream object
|
| 70 |
-
[[
|
| 71 |
-
stream [[c.files]] by multiple threads
|
| 72 |
-
[[intro.multithread]] unless otherwise
|
|
|
|
| 73 |
|
| 74 |
[*Note 1*: Data races result in undefined behavior
|
| 75 |
[[intro.multithread]]. — *end note*]
|
| 76 |
|
| 77 |
If one thread makes a library call *a* that writes a value to a stream
|
|
@@ -116,10 +130,19 @@ namespace std {
|
|
| 116 |
class basic_ostringstream;
|
| 117 |
template<class charT, class traits = char_traits<charT>,
|
| 118 |
class Allocator = allocator<charT>>
|
| 119 |
class basic_stringstream;
|
| 120 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 121 |
template<class charT, class traits = char_traits<charT>>
|
| 122 |
class basic_filebuf;
|
| 123 |
template<class charT, class traits = char_traits<charT>>
|
| 124 |
class basic_ifstream;
|
| 125 |
template<class charT, class traits = char_traits<charT>>
|
|
@@ -150,10 +173,15 @@ namespace std {
|
|
| 150 |
using stringbuf = basic_stringbuf<char>;
|
| 151 |
using istringstream = basic_istringstream<char>;
|
| 152 |
using ostringstream = basic_ostringstream<char>;
|
| 153 |
using stringstream = basic_stringstream<char>;
|
| 154 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 155 |
using filebuf = basic_filebuf<char>;
|
| 156 |
using ifstream = basic_ifstream<char>;
|
| 157 |
using ofstream = basic_ofstream<char>;
|
| 158 |
using fstream = basic_fstream<char>;
|
| 159 |
|
|
@@ -168,10 +196,15 @@ namespace std {
|
|
| 168 |
using wstringbuf = basic_stringbuf<wchar_t>;
|
| 169 |
using wistringstream = basic_istringstream<wchar_t>;
|
| 170 |
using wostringstream = basic_ostringstream<wchar_t>;
|
| 171 |
using wstringstream = basic_stringstream<wchar_t>;
|
| 172 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 173 |
using wfilebuf = basic_filebuf<wchar_t>;
|
| 174 |
using wifstream = basic_ifstream<wchar_t>;
|
| 175 |
using wofstream = basic_ofstream<wchar_t>;
|
| 176 |
using wfstream = basic_fstream<wchar_t>;
|
| 177 |
|
|
@@ -187,11 +220,11 @@ namespace std {
|
|
| 187 |
}
|
| 188 |
```
|
| 189 |
|
| 190 |
Default template arguments are described as appearing both in `<iosfwd>`
|
| 191 |
and in the synopsis of other headers but it is well-formed to include
|
| 192 |
-
both `<iosfwd>` and one or more of the other headers.[^
|
| 193 |
|
| 194 |
### Overview <a id="iostream.forward.overview">[[iostream.forward.overview]]</a>
|
| 195 |
|
| 196 |
The class template specialization `basic_ios<charT, traits>` serves as a
|
| 197 |
virtual base class for the class templates `basic_istream`,
|
|
@@ -266,27 +299,40 @@ standard C streams provided for by the functions declared in `<cstdio>`,
|
|
| 266 |
and includes all the headers necessary to use these objects.
|
| 267 |
|
| 268 |
The objects are constructed and the associations are established at some
|
| 269 |
time prior to or during the first time an object of class
|
| 270 |
`ios_base::Init` is constructed, and in any case before the body of
|
| 271 |
-
`main` [[basic.start.main]] begins execution.
|
| 272 |
-
destroyed during program execution.[^
|
| 273 |
-
|
| 274 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 275 |
|
| 276 |
Mixing operations on corresponding wide- and narrow-character streams
|
| 277 |
follows the same semantics as mixing such operations on `FILE`s, as
|
| 278 |
specified in the C standard library.
|
| 279 |
|
| 280 |
Concurrent access to a synchronized [[ios.members.static]] standard
|
| 281 |
iostream object’s formatted and unformatted input [[istream]] and output
|
| 282 |
[[ostream]] functions or a standard C stream by multiple threads does
|
| 283 |
not result in a data race [[intro.multithread]].
|
| 284 |
|
| 285 |
-
[*Note
|
| 286 |
-
|
| 287 |
-
characters. — *end note*]
|
| 288 |
|
| 289 |
See also: ISO C 7.21.2
|
| 290 |
|
| 291 |
### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
|
| 292 |
|
|
@@ -428,30 +474,14 @@ namespace std {
|
|
| 428 |
error_condition make_error_condition(io_errc e) noexcept;
|
| 429 |
const error_category& iostream_category() noexcept;
|
| 430 |
}
|
| 431 |
```
|
| 432 |
|
| 433 |
-
### Types <a id="stream.types">[[stream.types]]</a>
|
| 434 |
-
|
| 435 |
-
``` cpp
|
| 436 |
-
using streamoff = implementation-defined;
|
| 437 |
-
```
|
| 438 |
-
|
| 439 |
-
The type `streamoff` is a synonym for one of the signed basic integral
|
| 440 |
-
types of sufficient size to represent the maximum possible file size for
|
| 441 |
-
the operating system.[^4]
|
| 442 |
-
|
| 443 |
-
``` cpp
|
| 444 |
-
using streamsize = implementation-defined;
|
| 445 |
-
```
|
| 446 |
-
|
| 447 |
-
The type `streamsize` is a synonym for one of the signed basic integral
|
| 448 |
-
types. It is used to represent the number of characters transferred in
|
| 449 |
-
an I/O operation, or the size of I/O buffers.[^5]
|
| 450 |
-
|
| 451 |
### Class `ios_base` <a id="ios.base">[[ios.base]]</a>
|
| 452 |
|
|
|
|
|
|
|
| 453 |
``` cpp
|
| 454 |
namespace std {
|
| 455 |
class ios_base {
|
| 456 |
public:
|
| 457 |
class failure; // see below
|
|
@@ -488,10 +518,11 @@ namespace std {
|
|
| 488 |
using openmode = T3;
|
| 489 |
static constexpr openmode app = unspecified;
|
| 490 |
static constexpr openmode ate = unspecified;
|
| 491 |
static constexpr openmode binary = unspecified;
|
| 492 |
static constexpr openmode in = unspecified;
|
|
|
|
| 493 |
static constexpr openmode out = unspecified;
|
| 494 |
static constexpr openmode trunc = unspecified;
|
| 495 |
|
| 496 |
// [ios.seekdir], seekdir
|
| 497 |
using seekdir = T4;
|
|
@@ -701,15 +732,16 @@ The type `openmode` is a bitmask type [[bitmask.types]]. It contains the
|
|
| 701 |
elements indicated in [[ios.openmode]].
|
| 702 |
|
| 703 |
**Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
|
| 704 |
|
| 705 |
| Element | Effect(s) if set |
|
| 706 |
-
| -------- | ----------------------------------------------------------------- |
|
| 707 |
| `app` | seek to end before each write |
|
| 708 |
| `ate` | open and seek to end immediately after opening |
|
| 709 |
| `binary` | perform input and output in binary mode (as opposed to text mode) |
|
| 710 |
| `in` | open for input |
|
|
|
|
| 711 |
| `out` | open for output |
|
| 712 |
| `trunc` | truncate an existing stream when opening |
|
| 713 |
|
| 714 |
|
| 715 |
##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
|
|
@@ -738,10 +770,11 @@ namespace std {
|
|
| 738 |
public:
|
| 739 |
Init();
|
| 740 |
Init(const Init&) = default;
|
| 741 |
~Init();
|
| 742 |
Init& operator=(const Init&) = default;
|
|
|
|
| 743 |
private:
|
| 744 |
static int init_cnt; // exposition only
|
| 745 |
};
|
| 746 |
}
|
| 747 |
```
|
|
@@ -867,22 +900,22 @@ and output operations.
|
|
| 867 |
|
| 868 |
``` cpp
|
| 869 |
static bool sync_with_stdio(bool sync = true);
|
| 870 |
```
|
| 871 |
|
| 872 |
-
*Returns:* `true` if the previous state of the standard iostream
|
| 873 |
-
objects [[iostream.objects]] was synchronized and otherwise returns
|
| 874 |
-
`false`. The first time it is called, the function returns `true`.
|
| 875 |
-
|
| 876 |
*Effects:* If any input or output operation has occurred using the
|
| 877 |
standard streams prior to the call, the effect is
|
| 878 |
*implementation-defined*. Otherwise, called with a `false` argument, it
|
| 879 |
allows the standard streams to operate independently of the standard C
|
| 880 |
streams.
|
| 881 |
|
| 882 |
-
|
| 883 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 884 |
|
| 885 |
``` cpp
|
| 886 |
fputc(f, c);
|
| 887 |
```
|
| 888 |
|
|
@@ -916,11 +949,11 @@ is the same as the effect of
|
|
| 916 |
|
| 917 |
``` cpp
|
| 918 |
str.rdbuf()->sputbackc(c);
|
| 919 |
```
|
| 920 |
|
| 921 |
-
for any sequence of characters.[^
|
| 922 |
|
| 923 |
#### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
|
| 924 |
|
| 925 |
``` cpp
|
| 926 |
static int xalloc();
|
|
@@ -940,17 +973,20 @@ long& iword(int idx);
|
|
| 940 |
*Effects:* If `iarray` is a null pointer, allocates an array of `long`
|
| 941 |
of unspecified size and stores a pointer to its first element in
|
| 942 |
`iarray`. The function then extends the array pointed at by `iarray` as
|
| 943 |
necessary to include the element `iarray[idx]`. Each newly allocated
|
| 944 |
element of the array is initialized to zero. The reference returned is
|
| 945 |
-
invalid after any other
|
| 946 |
-
|
| 947 |
-
|
| 948 |
-
|
| 949 |
-
|
| 950 |
-
|
| 951 |
-
|
|
|
|
|
|
|
|
|
|
| 952 |
|
| 953 |
*Returns:* On success `iarray[idx]`. On failure, a valid `long&`
|
| 954 |
initialized to 0.
|
| 955 |
|
| 956 |
``` cpp
|
|
@@ -962,17 +998,19 @@ void*& pword(int idx);
|
|
| 962 |
*Effects:* If `parray` is a null pointer, allocates an array of pointers
|
| 963 |
to `void` of unspecified size and stores a pointer to its first element
|
| 964 |
in `parray`. The function then extends the array pointed at by `parray`
|
| 965 |
as necessary to include the element `parray[idx]`. Each newly allocated
|
| 966 |
element of the array is initialized to a null pointer. The reference
|
| 967 |
-
returned is invalid after any other
|
| 968 |
the value of the storage referred to is retained, so that until the next
|
| 969 |
call to `copyfmt`, calling `pword` with the same index yields another
|
| 970 |
-
reference to the same value. If the function fails[^
|
| 971 |
-
|
| 972 |
-
is
|
| 973 |
-
|
|
|
|
|
|
|
| 974 |
|
| 975 |
*Returns:* On success `parray[idx]`. On failure a valid `void*&`
|
| 976 |
initialized to 0.
|
| 977 |
|
| 978 |
*Remarks:* After a subsequent call to `pword(int)` for the same object,
|
|
@@ -1012,22 +1050,23 @@ destroyed, whichever comes first; otherwise the behavior is undefined.
|
|
| 1012 |
```
|
| 1013 |
|
| 1014 |
*Effects:* Calls each registered callback pair `(fn, idx)`
|
| 1015 |
[[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
|
| 1016 |
that any `ios_base` member function called from within `fn` has
|
| 1017 |
-
well-defined results.
|
| 1018 |
|
| 1019 |
### Class template `fpos` <a id="fpos">[[fpos]]</a>
|
| 1020 |
|
| 1021 |
``` cpp
|
| 1022 |
namespace std {
|
| 1023 |
template<class stateT> class fpos {
|
| 1024 |
public:
|
| 1025 |
// [fpos.members], members
|
| 1026 |
stateT state() const;
|
| 1027 |
void state(stateT);
|
| 1028 |
-
|
|
|
|
| 1029 |
stateT st; // exposition only
|
| 1030 |
};
|
| 1031 |
}
|
| 1032 |
```
|
| 1033 |
|
|
@@ -1054,25 +1093,25 @@ object whose type is equal to the template parameter `stateT`. Type
|
|
| 1054 |
[[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
|
| 1055 |
[[cpp17.copyassignable]]), and *Cpp17Destructible* (
|
| 1056 |
[[cpp17.destructible]]) requirements. If
|
| 1057 |
`is_trivially_copy_constructible_v<stateT>` is `true`, then
|
| 1058 |
`fpos<stateT>` has a trivial copy constructor. If
|
| 1059 |
-
`
|
| 1060 |
has a trivial copy assignment operator. If
|
| 1061 |
`is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
|
| 1062 |
a trivial destructor. All specializations of `fpos` meet the
|
| 1063 |
*Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
|
| 1064 |
*Cpp17CopyAssignable*, *Cpp17Destructible*, and
|
| 1065 |
*Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
|
| 1066 |
In addition, the expressions shown in [[fpos.operations]] are valid and
|
| 1067 |
have the indicated semantics. In that table,
|
| 1068 |
|
| 1069 |
-
- `P` refers to
|
| 1070 |
- `p` and `q` refer to values of type `P` or `const P`,
|
| 1071 |
- `pl` and `ql` refer to modifiable lvalues of type `P`,
|
| 1072 |
- `O` refers to type `streamoff`, and
|
| 1073 |
-
- `o`
|
| 1074 |
|
| 1075 |
Stream operations that return a value of type `traits::pos_type` return
|
| 1076 |
`P(O(-1))` as an invalid value to signal an error. If this value is used
|
| 1077 |
as an argument to any `istream`, `ostream`, or `streambuf` member that
|
| 1078 |
accepts a value of type `traits::pos_type` then the behavior of that
|
|
@@ -1136,11 +1175,10 @@ namespace std {
|
|
| 1136 |
void init(basic_streambuf<charT, traits>* sb);
|
| 1137 |
void move(basic_ios& rhs);
|
| 1138 |
void move(basic_ios&& rhs);
|
| 1139 |
void swap(basic_ios& rhs) noexcept;
|
| 1140 |
void set_rdbuf(basic_streambuf<charT, traits>* sb);
|
| 1141 |
-
|
| 1142 |
};
|
| 1143 |
}
|
| 1144 |
```
|
| 1145 |
|
| 1146 |
#### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
|
|
@@ -1276,11 +1314,11 @@ member objects of `rhs` as follows:
|
|
| 1276 |
`(*fn)(erase_event, *this, idx)`;
|
| 1277 |
- then, assigns to the member objects of `*this` the corresponding
|
| 1278 |
member objects of `rhs`, except that
|
| 1279 |
- `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
|
| 1280 |
- the contents of arrays pointed at by `pword` and `iword` are copied,
|
| 1281 |
-
not the pointers themselves;[^
|
| 1282 |
- if any newly stored pointer values in `*this` point at objects
|
| 1283 |
stored outside the object `rhs` and those objects are destroyed when
|
| 1284 |
`rhs` is destroyed, the newly stored pointer values are altered to
|
| 1285 |
point at newly constructed copies of the objects;
|
| 1286 |
- then, calls each callback pair that was copied from `rhs` as
|
|
@@ -1365,19 +1403,19 @@ iostate rdstate() const;
|
|
| 1365 |
|
| 1366 |
``` cpp
|
| 1367 |
void clear(iostate state = goodbit);
|
| 1368 |
```
|
| 1369 |
|
| 1370 |
-
*Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
|
| 1371 |
-
`rdstate() == (state | ios_base::badbit)`.
|
| 1372 |
-
|
| 1373 |
*Effects:* If
|
| 1374 |
`((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
|
| 1375 |
Otherwise, the function throws an object of class `ios_base::failure`
|
| 1376 |
[[ios.failure]], constructed with *implementation-defined* argument
|
| 1377 |
values.
|
| 1378 |
|
|
|
|
|
|
|
|
|
|
| 1379 |
``` cpp
|
| 1380 |
void setstate(iostate state);
|
| 1381 |
```
|
| 1382 |
|
| 1383 |
*Effects:* Calls `clear(rdstate() | state)` (which may throw
|
|
@@ -1397,11 +1435,11 @@ bool eof() const;
|
|
| 1397 |
|
| 1398 |
``` cpp
|
| 1399 |
bool fail() const;
|
| 1400 |
```
|
| 1401 |
|
| 1402 |
-
*Returns:* `true` if `failbit` or `badbit` is set in `rdstate()`.[^
|
| 1403 |
|
| 1404 |
``` cpp
|
| 1405 |
bool bad() const;
|
| 1406 |
```
|
| 1407 |
|
|
@@ -1416,14 +1454,14 @@ exceptions to be thrown.
|
|
| 1416 |
|
| 1417 |
``` cpp
|
| 1418 |
void exceptions(iostate except);
|
| 1419 |
```
|
| 1420 |
|
| 1421 |
-
*Ensures:* `except == exceptions()`.
|
| 1422 |
-
|
| 1423 |
*Effects:* Calls `clear(rdstate())`.
|
| 1424 |
|
|
|
|
|
|
|
| 1425 |
### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
|
| 1426 |
|
| 1427 |
#### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
|
| 1428 |
|
| 1429 |
Each function specified in this subclause is a designated addressable
|
|
@@ -1579,11 +1617,11 @@ function [[namespace.std]].
|
|
| 1579 |
ios_base& dec(ios_base& str);
|
| 1580 |
```
|
| 1581 |
|
| 1582 |
*Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
|
| 1583 |
|
| 1584 |
-
*Returns:* `str`[^
|
| 1585 |
|
| 1586 |
``` cpp
|
| 1587 |
ios_base& hex(ios_base& str);
|
| 1588 |
```
|
| 1589 |
|
|
@@ -1627,14 +1665,13 @@ ios_base& hexfloat(ios_base& str);
|
|
| 1627 |
*Effects:* Calls
|
| 1628 |
`str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
|
| 1629 |
|
| 1630 |
*Returns:* `str`.
|
| 1631 |
|
| 1632 |
-
[*Note 1*:
|
| 1633 |
-
|
| 1634 |
-
|
| 1635 |
-
`fixed` and `scientific`. — *end note*]
|
| 1636 |
|
| 1637 |
``` cpp
|
| 1638 |
ios_base& defaultfloat(ios_base& str);
|
| 1639 |
```
|
| 1640 |
|
|
@@ -1735,10 +1772,12 @@ above:
|
|
| 1735 |
shall have a defined value and is the next element to read (to get, or
|
| 1736 |
to obtain a character value, from the sequence).
|
| 1737 |
|
| 1738 |
### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
|
| 1739 |
|
|
|
|
|
|
|
| 1740 |
``` cpp
|
| 1741 |
namespace std {
|
| 1742 |
template<class charT, class traits = char_traits<charT>>
|
| 1743 |
class basic_streambuf {
|
| 1744 |
public:
|
|
@@ -1842,15 +1881,15 @@ for deriving various *stream buffers* whose objects each control two
|
|
| 1842 |
|
| 1843 |
``` cpp
|
| 1844 |
basic_streambuf();
|
| 1845 |
```
|
| 1846 |
|
| 1847 |
-
*Effects:* Initializes:[^
|
| 1848 |
|
| 1849 |
- all pointer member objects to null pointers,
|
| 1850 |
-
- the `getloc()` member to a copy the global locale, `locale()`, at
|
| 1851 |
-
time of construction.
|
| 1852 |
|
| 1853 |
*Remarks:* Once the `getloc()` member is initialized, results of calling
|
| 1854 |
locale member functions, and of members of facets so obtained, can
|
| 1855 |
safely be cached until the next time the member `imbue` is called.
|
| 1856 |
|
|
@@ -2119,11 +2158,11 @@ functions and to members of facets so obtained.
|
|
| 2119 |
basic_streambuf* setbuf(char_type* s, streamsize n);
|
| 2120 |
```
|
| 2121 |
|
| 2122 |
*Effects:* Influences stream buffering in a way that is defined
|
| 2123 |
separately for each class derived from `basic_streambuf` in this
|
| 2124 |
-
Clause
|
| 2125 |
|
| 2126 |
*Default behavior:* Does nothing. Returns `this`.
|
| 2127 |
|
| 2128 |
``` cpp
|
| 2129 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
|
@@ -2131,12 +2170,12 @@ pos_type seekoff(off_type off, ios_base::seekdir way,
|
|
| 2131 |
= ios_base::in | ios_base::out);
|
| 2132 |
```
|
| 2133 |
|
| 2134 |
*Effects:* Alters the stream positions within one or more of the
|
| 2135 |
controlled sequences in a way that is defined separately for each class
|
| 2136 |
-
derived from `basic_streambuf` in this
|
| 2137 |
-
[[filebuf.virtuals]]
|
| 2138 |
|
| 2139 |
*Default behavior:* Returns `pos_type(off_type(-1))`.
|
| 2140 |
|
| 2141 |
``` cpp
|
| 2142 |
pos_type seekpos(pos_type sp,
|
|
@@ -2144,12 +2183,12 @@ pos_type seekpos(pos_type sp,
|
|
| 2144 |
= ios_base::in | ios_base::out);
|
| 2145 |
```
|
| 2146 |
|
| 2147 |
*Effects:* Alters the stream positions within one or more of the
|
| 2148 |
controlled sequences in a way that is defined separately for each class
|
| 2149 |
-
derived from `basic_streambuf` in this
|
| 2150 |
-
[[filebuf]]
|
| 2151 |
|
| 2152 |
*Default behavior:* Returns `pos_type(off_type(-1))`.
|
| 2153 |
|
| 2154 |
``` cpp
|
| 2155 |
int sync();
|
|
@@ -2166,14 +2205,15 @@ each derived class [[filebuf.virtuals]].
|
|
| 2166 |
*Default behavior:* Returns zero.
|
| 2167 |
|
| 2168 |
##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
|
| 2169 |
|
| 2170 |
``` cpp
|
| 2171 |
-
streamsize showmanyc();
|
| 2172 |
-
are ``es-how-many-see'', not ``show-manic''.}
|
| 2173 |
```
|
| 2174 |
|
|
|
|
|
|
|
| 2175 |
*Returns:* An estimate of the number of characters available in the
|
| 2176 |
sequence, or -1. If it returns a positive value, then successive calls
|
| 2177 |
to `underflow()` will not return `traits::eof()` until at least that
|
| 2178 |
number of characters have been extracted from the stream. If
|
| 2179 |
`showmanyc()` returns -1, then calls to `underflow()` or `uflow()` will
|
|
@@ -2199,18 +2239,10 @@ to `sbumpc()` would return `traits::eof()`.
|
|
| 2199 |
|
| 2200 |
``` cpp
|
| 2201 |
int_type underflow();
|
| 2202 |
```
|
| 2203 |
|
| 2204 |
-
*Remarks:* The public members of `basic_streambuf` call this virtual
|
| 2205 |
-
function only if `gptr()` is null or `gptr() >= egptr()`.
|
| 2206 |
-
|
| 2207 |
-
*Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
|
| 2208 |
-
of the *pending sequence*, without moving the input sequence position
|
| 2209 |
-
past it. If the pending sequence is null then the function returns
|
| 2210 |
-
`traits::eof()` to indicate failure.
|
| 2211 |
-
|
| 2212 |
The *pending sequence* of characters is defined as the concatenation of
|
| 2213 |
|
| 2214 |
- the empty sequence if `gptr()` is null, otherwise the characters in
|
| 2215 |
\[`gptr()`, `egptr()`), followed by
|
| 2216 |
- some (possibly empty) sequence of characters read from the input
|
|
@@ -2236,12 +2268,20 @@ that either
|
|
| 2236 |
in which case the characters in \[`eback()`, `gptr()`) agree with the
|
| 2237 |
last `gptr() - eback()` characters of the backup sequence, or
|
| 2238 |
- the characters in \[`gptr() - n`, `gptr()`) agree with the backup
|
| 2239 |
sequence (where `n` is the length of the backup sequence).
|
| 2240 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2241 |
*Default behavior:* Returns `traits::eof()`.
|
| 2242 |
|
|
|
|
|
|
|
|
|
|
| 2243 |
``` cpp
|
| 2244 |
int_type uflow();
|
| 2245 |
```
|
| 2246 |
|
| 2247 |
*Preconditions:* The constraints are the same as for `underflow()`,
|
|
@@ -2249,26 +2289,21 @@ except that the result character is transferred from the pending
|
|
| 2249 |
sequence to the backup sequence, and the pending sequence is not empty
|
| 2250 |
before the transfer.
|
| 2251 |
|
| 2252 |
*Default behavior:* Calls `underflow()`. If `underflow()` returns
|
| 2253 |
`traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
|
| 2254 |
-
of `traits::to_int_type(*gptr())` and
|
| 2255 |
pointer for the input sequence.
|
| 2256 |
|
| 2257 |
*Returns:* `traits::eof()` to indicate failure.
|
| 2258 |
|
| 2259 |
##### Putback <a id="streambuf.virt.pback">[[streambuf.virt.pback]]</a>
|
| 2260 |
|
| 2261 |
``` cpp
|
| 2262 |
int_type pbackfail(int_type c = traits::eof());
|
| 2263 |
```
|
| 2264 |
|
| 2265 |
-
*Remarks:* The public functions of `basic_streambuf` call this virtual
|
| 2266 |
-
function only when `gptr()` is null, `gptr() == eback()`, or
|
| 2267 |
-
`traits::eq(traits::to_char_type(c), gptr()[-1])` returns `false`. Other
|
| 2268 |
-
calls shall also satisfy that constraint.
|
| 2269 |
-
|
| 2270 |
The *pending sequence* is defined as for `underflow()`, with the
|
| 2271 |
modifications that
|
| 2272 |
|
| 2273 |
- If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
|
| 2274 |
input sequence is backed up one character before the pending sequence
|
|
@@ -2280,17 +2315,22 @@ modifications that
|
|
| 2280 |
*Ensures:* On return, the constraints of `gptr()`, `eback()`, and
|
| 2281 |
`pptr()` are the same as for `underflow()`.
|
| 2282 |
|
| 2283 |
*Returns:* `traits::eof()` to indicate failure. Failure may occur
|
| 2284 |
because the input sequence could not be backed up, or if for some other
|
| 2285 |
-
reason the pointers
|
| 2286 |
`pbackfail()` is called only when put back has really failed.
|
| 2287 |
|
| 2288 |
Returns some value other than `traits::eof()` to indicate success.
|
| 2289 |
|
| 2290 |
*Default behavior:* Returns `traits::eof()`.
|
| 2291 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2292 |
##### Put area <a id="streambuf.virt.put">[[streambuf.virt.put]]</a>
|
| 2293 |
|
| 2294 |
``` cpp
|
| 2295 |
streamsize xsputn(const char_type* s, streamsize n);
|
| 2296 |
```
|
|
@@ -2316,14 +2356,10 @@ of
|
|
| 2316 |
- the empty sequence if `pbase()` is null, otherwise the
|
| 2317 |
`pptr() - pbase()` characters beginning at `pbase()`, followed by
|
| 2318 |
- the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
|
| 2319 |
`true`, otherwise the sequence consisting of `c`.
|
| 2320 |
|
| 2321 |
-
*Remarks:* The member functions `sputc()` and `sputn()` call this
|
| 2322 |
-
function in case that no room can be found in the put buffer enough to
|
| 2323 |
-
accommodate the argument character sequence.
|
| 2324 |
-
|
| 2325 |
*Preconditions:* Every overriding definition of this virtual function
|
| 2326 |
obeys the following constraints:
|
| 2327 |
|
| 2328 |
- The effect of consuming a character on the associated output sequence
|
| 2329 |
is specified.[^16]
|
|
@@ -2343,10 +2379,14 @@ obeys the following constraints:
|
|
| 2343 |
Otherwise, returns some value other than `traits::eof()` to indicate
|
| 2344 |
success.[^17]
|
| 2345 |
|
| 2346 |
*Default behavior:* Returns `traits::eof()`.
|
| 2347 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2348 |
## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
|
| 2349 |
|
| 2350 |
### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
|
| 2351 |
|
| 2352 |
``` cpp
|
|
@@ -2364,12 +2404,12 @@ namespace std {
|
|
| 2364 |
using wiostream = basic_iostream<wchar_t>;
|
| 2365 |
|
| 2366 |
template<class charT, class traits>
|
| 2367 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 2368 |
|
| 2369 |
-
template<class
|
| 2370 |
-
|
| 2371 |
}
|
| 2372 |
```
|
| 2373 |
|
| 2374 |
### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
|
| 2375 |
|
|
@@ -2393,56 +2433,96 @@ namespace std {
|
|
| 2393 |
template<class charT, class traits>
|
| 2394 |
basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
|
| 2395 |
template<class charT, class traits>
|
| 2396 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 2397 |
|
| 2398 |
-
template<class
|
| 2399 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2400 |
}
|
| 2401 |
```
|
| 2402 |
|
| 2403 |
### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
|
| 2404 |
|
| 2405 |
``` cpp
|
| 2406 |
namespace std {
|
| 2407 |
-
|
| 2408 |
-
|
| 2409 |
-
|
| 2410 |
-
|
| 2411 |
-
|
| 2412 |
-
|
| 2413 |
-
|
| 2414 |
-
template<class moneyT>
|
| 2415 |
-
template<class
|
| 2416 |
-
template<class charT>
|
| 2417 |
-
template<class charT> T10 put_time(const struct tm* tmb, const charT* fmt);
|
| 2418 |
|
| 2419 |
template<class charT>
|
| 2420 |
-
|
| 2421 |
|
| 2422 |
template<class charT, class traits, class Allocator>
|
| 2423 |
-
|
| 2424 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2425 |
|
| 2426 |
template<class charT, class traits, class Allocator>
|
| 2427 |
-
|
| 2428 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2429 |
|
| 2430 |
template<class charT, class traits>
|
| 2431 |
-
|
| 2432 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2433 |
}
|
| 2434 |
```
|
| 2435 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2436 |
### Input streams <a id="input.streams">[[input.streams]]</a>
|
| 2437 |
|
| 2438 |
-
|
| 2439 |
-
|
| 2440 |
-
|
|
|
|
|
|
|
| 2441 |
|
| 2442 |
#### Class template `basic_istream` <a id="istream">[[istream]]</a>
|
| 2443 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2444 |
``` cpp
|
| 2445 |
namespace std {
|
| 2446 |
template<class charT, class traits = char_traits<charT>>
|
| 2447 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 2448 |
public:
|
|
@@ -2459,64 +2539,62 @@ namespace std {
|
|
| 2459 |
|
| 2460 |
// [istream.sentry], prefix/suffix
|
| 2461 |
class sentry;
|
| 2462 |
|
| 2463 |
// [istream.formatted], formatted input
|
| 2464 |
-
basic_istream
|
| 2465 |
-
|
| 2466 |
-
basic_istream
|
| 2467 |
-
operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 2468 |
-
basic_istream<charT, traits>&
|
| 2469 |
-
operator>>(ios_base& (*pf)(ios_base&));
|
| 2470 |
|
| 2471 |
-
basic_istream
|
| 2472 |
-
basic_istream
|
| 2473 |
-
basic_istream
|
| 2474 |
-
basic_istream
|
| 2475 |
-
basic_istream
|
| 2476 |
-
basic_istream
|
| 2477 |
-
basic_istream
|
| 2478 |
-
basic_istream
|
| 2479 |
-
basic_istream
|
| 2480 |
-
basic_istream
|
| 2481 |
-
basic_istream
|
| 2482 |
-
basic_istream
|
|
|
|
| 2483 |
|
| 2484 |
-
basic_istream
|
| 2485 |
-
basic_istream
|
| 2486 |
|
| 2487 |
// [istream.unformatted], unformatted input
|
| 2488 |
streamsize gcount() const;
|
| 2489 |
int_type get();
|
| 2490 |
-
basic_istream
|
| 2491 |
-
basic_istream
|
| 2492 |
-
basic_istream
|
| 2493 |
-
basic_istream
|
| 2494 |
-
basic_istream
|
| 2495 |
|
| 2496 |
-
basic_istream
|
| 2497 |
-
basic_istream
|
| 2498 |
|
| 2499 |
-
basic_istream
|
| 2500 |
int_type peek();
|
| 2501 |
-
basic_istream
|
| 2502 |
streamsize readsome(char_type* s, streamsize n);
|
| 2503 |
|
| 2504 |
-
basic_istream
|
| 2505 |
-
basic_istream
|
| 2506 |
int sync();
|
| 2507 |
|
| 2508 |
pos_type tellg();
|
| 2509 |
-
basic_istream
|
| 2510 |
-
basic_istream
|
| 2511 |
|
| 2512 |
protected:
|
| 2513 |
// [istream.cons], copy/move constructor
|
| 2514 |
basic_istream(const basic_istream&) = delete;
|
| 2515 |
basic_istream(basic_istream&& rhs);
|
| 2516 |
|
| 2517 |
-
// [istream.assign],
|
| 2518 |
basic_istream& operator=(const basic_istream&) = delete;
|
| 2519 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2520 |
void swap(basic_istream& rhs);
|
| 2521 |
};
|
| 2522 |
|
|
@@ -2545,22 +2623,10 @@ Two groups of member function signatures share common properties: the
|
|
| 2545 |
*formatted input functions* (or *extractors*) and the *unformatted input
|
| 2546 |
functions.* Both groups of input functions are described as if they
|
| 2547 |
obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
|
| 2548 |
or `rdbuf()->sgetc()`. They may use other public members of `istream`.
|
| 2549 |
|
| 2550 |
-
If `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`,
|
| 2551 |
-
then the input function, except as explicitly noted otherwise, completes
|
| 2552 |
-
its actions and does `setstate(eofbit)`, which may throw
|
| 2553 |
-
`ios_base::failure` [[iostate.flags]], before returning.
|
| 2554 |
-
|
| 2555 |
-
If one of these called functions throws an exception, then unless
|
| 2556 |
-
explicitly noted otherwise, the input function sets `badbit` in the
|
| 2557 |
-
error state. If `badbit` is set in `exceptions()`, the input function
|
| 2558 |
-
rethrows the exception without completing its actions, otherwise it does
|
| 2559 |
-
not throw anything and proceeds as if the called function had returned a
|
| 2560 |
-
failure indication.
|
| 2561 |
-
|
| 2562 |
##### Constructors <a id="istream.cons">[[istream.cons]]</a>
|
| 2563 |
|
| 2564 |
``` cpp
|
| 2565 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2566 |
```
|
|
@@ -2603,15 +2669,16 @@ values returned by `gcount()` and `rhs.gcount()`.
|
|
| 2603 |
|
| 2604 |
##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
|
| 2605 |
|
| 2606 |
``` cpp
|
| 2607 |
namespace std {
|
| 2608 |
-
template<class charT, class traits
|
| 2609 |
class basic_istream<charT, traits>::sentry {
|
| 2610 |
bool ok_; // exposition only
|
|
|
|
| 2611 |
public:
|
| 2612 |
-
explicit sentry(basic_istream
|
| 2613 |
~sentry();
|
| 2614 |
explicit operator bool() const { return ok_; }
|
| 2615 |
sentry(const sentry&) = delete;
|
| 2616 |
sentry& operator=(const sentry&) = delete;
|
| 2617 |
};
|
|
@@ -2620,32 +2687,34 @@ namespace std {
|
|
| 2620 |
|
| 2621 |
The class `sentry` defines a class that is responsible for doing
|
| 2622 |
exception safe prefix and suffix operations.
|
| 2623 |
|
| 2624 |
``` cpp
|
| 2625 |
-
explicit sentry(basic_istream
|
| 2626 |
```
|
| 2627 |
|
| 2628 |
*Effects:* If `is.good()` is `false`, calls `is.setstate(failbit)`.
|
| 2629 |
Otherwise, prepares for formatted or unformatted input. First, if
|
| 2630 |
`is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
|
| 2631 |
to synchronize the output sequence with any associated external C
|
| 2632 |
stream. Except that this call can be suppressed if the put area of
|
| 2633 |
`is.tie()` is empty. Further an implementation is allowed to defer the
|
| 2634 |
call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
|
| 2635 |
such call occurs before the `sentry` object is destroyed, the call to
|
| 2636 |
-
`flush` may be eliminated entirely.[^18]
|
| 2637 |
-
|
| 2638 |
-
|
| 2639 |
-
|
| 2640 |
-
|
| 2641 |
-
`
|
|
|
|
|
|
|
| 2642 |
|
| 2643 |
*Remarks:* The constructor
|
| 2644 |
|
| 2645 |
``` cpp
|
| 2646 |
-
explicit sentry(basic_istream
|
| 2647 |
```
|
| 2648 |
|
| 2649 |
uses the currently imbued locale in `is`, to determine whether the next
|
| 2650 |
input character is whitespace or not.
|
| 2651 |
|
|
@@ -2678,47 +2747,56 @@ explicit operator bool() const;
|
|
| 2678 |
#### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
|
| 2679 |
|
| 2680 |
##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
|
| 2681 |
|
| 2682 |
Each formatted input function begins execution by constructing an object
|
| 2683 |
-
of
|
|
|
|
|
|
|
| 2684 |
`sentry` object returns `true`, when converted to a value of type
|
| 2685 |
-
`bool`, the function endeavors to obtain the requested input.
|
| 2686 |
-
|
| 2687 |
-
|
| 2688 |
-
the
|
| 2689 |
-
|
| 2690 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2691 |
|
| 2692 |
##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
|
| 2693 |
|
| 2694 |
``` cpp
|
| 2695 |
-
operator>>(unsigned short& val);
|
| 2696 |
-
operator>>(unsigned int& val);
|
| 2697 |
-
operator>>(long& val);
|
| 2698 |
-
operator>>(unsigned long& val);
|
| 2699 |
-
operator>>(long long& val);
|
| 2700 |
-
operator>>(unsigned long long& val);
|
| 2701 |
-
operator>>(float& val);
|
| 2702 |
-
operator>>(double& val);
|
| 2703 |
-
operator>>(long double& val);
|
| 2704 |
-
operator>>(bool& val);
|
| 2705 |
-
operator>>(void*& val);
|
| 2706 |
```
|
| 2707 |
|
| 2708 |
As in the case of the inserters, these extractors depend on the locale’s
|
| 2709 |
`num_get<>` [[locale.num.get]] object to perform parsing the input
|
| 2710 |
stream data. These extractors behave as formatted input functions (as
|
| 2711 |
-
described in [[istream.formatted.reqmts]]). After a sentry object is
|
| 2712 |
constructed, the conversion occurs as if performed by the following code
|
| 2713 |
-
fragment
|
|
|
|
| 2714 |
|
| 2715 |
``` cpp
|
| 2716 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2717 |
-
|
| 2718 |
-
use_facet<numget>(loc).get(*this, 0, *this, err, val);
|
| 2719 |
-
setstate(err);
|
| 2720 |
```
|
| 2721 |
|
| 2722 |
In the above fragment, `loc` stands for the private member of the
|
| 2723 |
`basic_ios` class.
|
| 2724 |
|
|
@@ -2729,85 +2807,123 @@ directly. — *end note*]
|
|
| 2729 |
|
| 2730 |
Class `locale` relies on this type as its interface to `istream`, so
|
| 2731 |
that it does not need to depend directly on `istream`.
|
| 2732 |
|
| 2733 |
``` cpp
|
| 2734 |
-
operator>>(short& val);
|
| 2735 |
```
|
| 2736 |
|
| 2737 |
The conversion occurs as if performed by the following code fragment
|
| 2738 |
(using the same notation as for the preceding code fragment):
|
| 2739 |
|
| 2740 |
``` cpp
|
| 2741 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2742 |
-
iostate err = ios_base::goodbit;
|
| 2743 |
long lval;
|
| 2744 |
-
use_facet<numget>(loc).get(*this, 0, *this,
|
| 2745 |
if (lval < numeric_limits<short>::min()) {
|
| 2746 |
-
|
| 2747 |
val = numeric_limits<short>::min();
|
| 2748 |
} else if (numeric_limits<short>::max() < lval) {
|
| 2749 |
-
|
| 2750 |
val = numeric_limits<short>::max();
|
| 2751 |
} else
|
| 2752 |
val = static_cast<short>(lval);
|
| 2753 |
-
setstate(err);
|
| 2754 |
```
|
| 2755 |
|
| 2756 |
``` cpp
|
| 2757 |
-
operator>>(int& val);
|
| 2758 |
```
|
| 2759 |
|
| 2760 |
The conversion occurs as if performed by the following code fragment
|
| 2761 |
(using the same notation as for the preceding code fragment):
|
| 2762 |
|
| 2763 |
``` cpp
|
| 2764 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2765 |
-
iostate err = ios_base::goodbit;
|
| 2766 |
long lval;
|
| 2767 |
-
use_facet<numget>(loc).get(*this, 0, *this,
|
| 2768 |
if (lval < numeric_limits<int>::min()) {
|
| 2769 |
-
|
| 2770 |
val = numeric_limits<int>::min();
|
| 2771 |
} else if (numeric_limits<int>::max() < lval) {
|
| 2772 |
-
|
| 2773 |
val = numeric_limits<int>::max();
|
| 2774 |
} else
|
| 2775 |
val = static_cast<int>(lval);
|
| 2776 |
-
setstate(err);
|
| 2777 |
```
|
| 2778 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2779 |
##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
|
| 2780 |
|
| 2781 |
``` cpp
|
| 2782 |
-
basic_istream
|
| 2783 |
-
operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
|
| 2784 |
```
|
| 2785 |
|
| 2786 |
*Effects:* None. This extractor does not behave as a formatted input
|
| 2787 |
function (as described in [[istream.formatted.reqmts]]).
|
| 2788 |
|
| 2789 |
-
*Returns:* `pf(*this)`.[^
|
| 2790 |
|
| 2791 |
``` cpp
|
| 2792 |
-
basic_istream<charT, traits>&
|
| 2793 |
-
operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 2794 |
```
|
| 2795 |
|
| 2796 |
*Effects:* Calls `pf(*this)`. This extractor does not behave as a
|
| 2797 |
formatted input function (as described
|
| 2798 |
in [[istream.formatted.reqmts]]).
|
| 2799 |
|
| 2800 |
*Returns:* `*this`.
|
| 2801 |
|
| 2802 |
``` cpp
|
| 2803 |
-
basic_istream
|
| 2804 |
```
|
| 2805 |
|
| 2806 |
-
*Effects:* Calls `pf(*this)`.[^
|
| 2807 |
-
|
| 2808 |
-
|
|
|
|
| 2809 |
|
| 2810 |
*Returns:* `*this`.
|
| 2811 |
|
| 2812 |
``` cpp
|
| 2813 |
template<class charT, class traits, size_t N>
|
|
@@ -2833,12 +2949,12 @@ Characters are extracted and stored until any of the following occurs:
|
|
| 2833 |
|
| 2834 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 2835 |
which may be the first position if no characters were extracted.
|
| 2836 |
`operator>>` then calls `width(0)`.
|
| 2837 |
|
| 2838 |
-
If the function extracted no characters,
|
| 2839 |
-
|
| 2840 |
|
| 2841 |
*Returns:* `in`.
|
| 2842 |
|
| 2843 |
``` cpp
|
| 2844 |
template<class charT, class traits>
|
|
@@ -2848,132 +2964,138 @@ template<class traits>
|
|
| 2848 |
template<class traits>
|
| 2849 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
|
| 2850 |
```
|
| 2851 |
|
| 2852 |
*Effects:* Behaves like a formatted input member (as described
|
| 2853 |
-
in [[istream.formatted.reqmts]]) of `in`.
|
| 2854 |
-
|
| 2855 |
-
|
|
|
|
| 2856 |
|
| 2857 |
*Returns:* `in`.
|
| 2858 |
|
| 2859 |
``` cpp
|
| 2860 |
-
basic_istream
|
| 2861 |
```
|
| 2862 |
|
| 2863 |
*Effects:* Behaves as an unformatted input
|
| 2864 |
function [[istream.unformatted]]. If `sb` is null, calls
|
| 2865 |
`setstate(failbit)`, which may throw `ios_base::failure`
|
| 2866 |
-
[[iostate.flags]]. After a sentry object is constructed, extracts
|
| 2867 |
characters from `*this` and inserts them in the output sequence
|
| 2868 |
controlled by `sb`. Characters are extracted and inserted until any of
|
| 2869 |
the following occurs:
|
| 2870 |
|
| 2871 |
- end-of-file occurs on the input sequence;
|
| 2872 |
- inserting in the output sequence fails (in which case the character to
|
| 2873 |
be inserted is not extracted);
|
| 2874 |
- an exception occurs (in which case the exception is caught).
|
| 2875 |
|
| 2876 |
-
If the function inserts no characters,
|
| 2877 |
-
|
| 2878 |
-
characters because it caught an exception thrown while extracting
|
| 2879 |
-
characters from `*this` and `failbit` is set in `exceptions()`
|
| 2880 |
-
[[iostate.flags]], then the caught exception is rethrown.
|
| 2881 |
|
| 2882 |
*Returns:* `*this`.
|
| 2883 |
|
| 2884 |
#### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
|
| 2885 |
|
| 2886 |
Each unformatted input function begins execution by constructing an
|
| 2887 |
-
object of
|
| 2888 |
-
|
| 2889 |
-
|
| 2890 |
-
|
| 2891 |
-
|
| 2892 |
-
|
| 2893 |
-
|
| 2894 |
-
|
| 2895 |
-
|
| 2896 |
-
|
| 2897 |
-
|
| 2898 |
-
|
| 2899 |
-
|
| 2900 |
-
|
| 2901 |
-
|
| 2902 |
-
|
| 2903 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2904 |
|
| 2905 |
``` cpp
|
| 2906 |
streamsize gcount() const;
|
| 2907 |
```
|
| 2908 |
|
| 2909 |
*Effects:* None. This member function does not behave as an unformatted
|
| 2910 |
input function (as described above).
|
| 2911 |
|
| 2912 |
*Returns:* The number of characters extracted by the last unformatted
|
| 2913 |
-
input member function called for the object.
|
|
|
|
| 2914 |
|
| 2915 |
``` cpp
|
| 2916 |
int_type get();
|
| 2917 |
```
|
| 2918 |
|
| 2919 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2920 |
-
above). After constructing a sentry object, extracts a character `c`,
|
| 2921 |
-
one is available. Otherwise,
|
| 2922 |
-
|
| 2923 |
|
| 2924 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 2925 |
|
| 2926 |
``` cpp
|
| 2927 |
-
basic_istream
|
| 2928 |
```
|
| 2929 |
|
| 2930 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2931 |
-
above). After constructing a sentry object, extracts a character, if
|
| 2932 |
-
is available, and assigns it to `c`.[^
|
| 2933 |
-
|
| 2934 |
-
|
|
|
|
| 2935 |
|
| 2936 |
*Returns:* `*this`.
|
| 2937 |
|
| 2938 |
``` cpp
|
| 2939 |
-
basic_istream
|
| 2940 |
```
|
| 2941 |
|
| 2942 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2943 |
-
above). After constructing a sentry object, extracts characters and
|
| 2944 |
stores them into successive locations of an array whose first element is
|
| 2945 |
-
designated by `s`.[^
|
| 2946 |
-
|
|
|
|
| 2947 |
|
| 2948 |
- `n` is less than one or `n - 1` characters are stored;
|
| 2949 |
-
- end-of-file occurs on the input sequence
|
| 2950 |
-
calls `setstate(eofbit)`);
|
| 2951 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 2952 |
which case `c` is not extracted).
|
| 2953 |
|
| 2954 |
-
If the function stores no characters,
|
| 2955 |
-
|
| 2956 |
-
`n` is greater than zero it then stores a null character into
|
| 2957 |
-
successive location of the array.
|
| 2958 |
|
| 2959 |
*Returns:* `*this`.
|
| 2960 |
|
| 2961 |
``` cpp
|
| 2962 |
-
basic_istream
|
| 2963 |
```
|
| 2964 |
|
| 2965 |
*Effects:* Calls `get(s, n, widen(’\n’))`.
|
| 2966 |
|
| 2967 |
*Returns:* Value returned by the call.
|
| 2968 |
|
| 2969 |
``` cpp
|
| 2970 |
-
basic_istream
|
| 2971 |
```
|
| 2972 |
|
| 2973 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2974 |
-
above). After constructing a sentry object, extracts characters and
|
| 2975 |
inserts them in the output sequence controlled by `sb`. Characters are
|
| 2976 |
extracted and inserted until any of the following occurs:
|
| 2977 |
|
| 2978 |
- end-of-file occurs on the input sequence;
|
| 2979 |
- inserting in the output sequence fails (in which case the character to
|
|
@@ -2981,45 +3103,45 @@ extracted and inserted until any of the following occurs:
|
|
| 2981 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 2982 |
which case `c` is not extracted);
|
| 2983 |
- an exception occurs (in which case, the exception is caught but not
|
| 2984 |
rethrown).
|
| 2985 |
|
| 2986 |
-
If the function inserts no characters,
|
| 2987 |
-
|
| 2988 |
|
| 2989 |
*Returns:* `*this`.
|
| 2990 |
|
| 2991 |
``` cpp
|
| 2992 |
-
basic_istream
|
| 2993 |
```
|
| 2994 |
|
| 2995 |
*Effects:* Calls `get(sb, widen(’\n’))`.
|
| 2996 |
|
| 2997 |
*Returns:* Value returned by the call.
|
| 2998 |
|
| 2999 |
``` cpp
|
| 3000 |
-
basic_istream
|
| 3001 |
```
|
| 3002 |
|
| 3003 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3004 |
-
above). After constructing a sentry object, extracts characters and
|
| 3005 |
stores them into successive locations of an array whose first element is
|
| 3006 |
-
designated by `s`.[^
|
| 3007 |
-
the following occurs:
|
| 3008 |
|
| 3009 |
-
|
| 3010 |
-
|
|
|
|
| 3011 |
2. `traits::eq(c, delim)` for the next available input character `c`
|
| 3012 |
(in which case the input character is extracted but not
|
| 3013 |
-
stored);[^
|
| 3014 |
3. `n` is less than one or `n - 1` characters are stored (in which case
|
| 3015 |
the function calls `setstate(failbit)`).
|
| 3016 |
|
| 3017 |
-
These conditions are tested in the order shown.[^
|
| 3018 |
|
| 3019 |
-
If the function extracts no characters,
|
| 3020 |
-
|
| 3021 |
|
| 3022 |
In any case, if `n` is greater than zero, it then stores a null
|
| 3023 |
character (using `charT()`) into the next successive location of the
|
| 3024 |
array.
|
| 3025 |
|
|
@@ -3053,21 +3175,21 @@ int main() {
|
|
| 3053 |
```
|
| 3054 |
|
| 3055 |
— *end example*]
|
| 3056 |
|
| 3057 |
``` cpp
|
| 3058 |
-
basic_istream
|
| 3059 |
```
|
| 3060 |
|
| 3061 |
*Returns:* `getline(s, n, widen(’\n’))`
|
| 3062 |
|
| 3063 |
``` cpp
|
| 3064 |
-
basic_istream
|
| 3065 |
```
|
| 3066 |
|
| 3067 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3068 |
-
above). After constructing a sentry object, extracts characters and
|
| 3069 |
discards them. Characters are extracted until any of the following
|
| 3070 |
occurs:
|
| 3071 |
|
| 3072 |
- `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
|
| 3073 |
characters have been extracted so far
|
|
@@ -3075,36 +3197,38 @@ occurs:
|
|
| 3075 |
calls `setstate(eofbit)`, which may throw `ios_base::failure`
|
| 3076 |
[[iostate.flags]]);
|
| 3077 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
| 3078 |
available input character `c` (in which case `c` is extracted).
|
| 3079 |
|
| 3080 |
-
*
|
| 3081 |
-
`traits::eq_int_type(delim, traits::eof())`.
|
| 3082 |
|
| 3083 |
*Returns:* `*this`.
|
| 3084 |
|
| 3085 |
``` cpp
|
| 3086 |
int_type peek();
|
| 3087 |
```
|
| 3088 |
|
| 3089 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3090 |
-
above). After constructing a sentry object, reads but does not extract
|
| 3091 |
the current input character.
|
| 3092 |
|
| 3093 |
*Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
|
| 3094 |
`rdbuf()->sgetc()`.
|
| 3095 |
|
| 3096 |
``` cpp
|
| 3097 |
-
basic_istream
|
| 3098 |
```
|
| 3099 |
|
| 3100 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3101 |
-
above). After constructing a sentry object, if `!good()` calls
|
| 3102 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3103 |
extracts characters and stores them into successive locations of an
|
| 3104 |
-
array whose first element is designated by `s`.[^
|
| 3105 |
-
|
|
|
|
|
|
|
| 3106 |
|
| 3107 |
- `n` characters are stored;
|
| 3108 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3109 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 3110 |
`ios_base::failure` [[iostate.flags]]).
|
|
@@ -3114,11 +3238,11 @@ extracted and stored until either of the following occurs:
|
|
| 3114 |
``` cpp
|
| 3115 |
streamsize readsome(char_type* s, streamsize n);
|
| 3116 |
```
|
| 3117 |
|
| 3118 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3119 |
-
above). After constructing a sentry object, if `!good()` calls
|
| 3120 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3121 |
extracts characters and stores them into successive locations of an
|
| 3122 |
array whose first element is designated by `s`. If
|
| 3123 |
`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
|
| 3124 |
`ios_base::failure` [[iostate.flags]]), and extracts no characters;
|
|
@@ -3127,51 +3251,51 @@ array whose first element is designated by `s`. If
|
|
| 3127 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 3128 |
|
| 3129 |
*Returns:* The number of characters extracted.
|
| 3130 |
|
| 3131 |
``` cpp
|
| 3132 |
-
basic_istream
|
| 3133 |
```
|
| 3134 |
|
| 3135 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3136 |
above), except that the function first clears `eofbit`. After
|
| 3137 |
-
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3138 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3139 |
calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
|
| 3140 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3141 |
`ios_base::failure` [[iostate.flags]]).
|
| 3142 |
|
| 3143 |
-
[*Note 1*: This function extracts no characters, so the value returned
|
| 3144 |
-
by the next call to `gcount()` is 0. — *end note*]
|
| 3145 |
-
|
| 3146 |
-
*Returns:* `*this`.
|
| 3147 |
-
|
| 3148 |
-
``` cpp
|
| 3149 |
-
basic_istream<charT, traits>& unget();
|
| 3150 |
-
```
|
| 3151 |
-
|
| 3152 |
-
*Effects:* Behaves as an unformatted input function (as described
|
| 3153 |
-
above), except that the function first clears `eofbit`. After
|
| 3154 |
-
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3155 |
-
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3156 |
-
calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
|
| 3157 |
-
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3158 |
-
`ios_base::failure` [[iostate.flags]]).
|
| 3159 |
-
|
| 3160 |
[*Note 2*: This function extracts no characters, so the value returned
|
| 3161 |
by the next call to `gcount()` is 0. — *end note*]
|
| 3162 |
|
| 3163 |
*Returns:* `*this`.
|
| 3164 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3165 |
``` cpp
|
| 3166 |
int sync();
|
| 3167 |
```
|
| 3168 |
|
| 3169 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3170 |
above), except that it does not count the number of characters extracted
|
| 3171 |
and does not affect the value returned by subsequent calls to
|
| 3172 |
-
`gcount()`. After constructing a sentry object, if `rdbuf()` is a null
|
| 3173 |
pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
|
| 3174 |
that function returns `-1` calls `setstate(badbit)` (which may throw
|
| 3175 |
`ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
|
| 3176 |
returns zero.
|
| 3177 |
|
|
@@ -3182,38 +3306,38 @@ pos_type tellg();
|
|
| 3182 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3183 |
above), except that it does not count the number of characters extracted
|
| 3184 |
and does not affect the value returned by subsequent calls to
|
| 3185 |
`gcount()`.
|
| 3186 |
|
| 3187 |
-
*Returns:* After constructing a sentry object, if `fail() != false`,
|
| 3188 |
returns `pos_type(-1)` to indicate failure. Otherwise, returns
|
| 3189 |
`rdbuf()->pubseekoff(0, cur, in)`.
|
| 3190 |
|
| 3191 |
``` cpp
|
| 3192 |
-
basic_istream
|
| 3193 |
```
|
| 3194 |
|
| 3195 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3196 |
above), except that the function first clears `eofbit`, it does not
|
| 3197 |
count the number of characters extracted, and it does not affect the
|
| 3198 |
value returned by subsequent calls to `gcount()`. After constructing a
|
| 3199 |
-
sentry object, if `fail() != true`, executes
|
| 3200 |
`rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
|
| 3201 |
function calls `setstate(failbit)` (which may throw
|
| 3202 |
`ios_base::failure`).
|
| 3203 |
|
| 3204 |
*Returns:* `*this`.
|
| 3205 |
|
| 3206 |
``` cpp
|
| 3207 |
-
basic_istream
|
| 3208 |
```
|
| 3209 |
|
| 3210 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3211 |
above), except that the function first clears `eofbit`, does not count
|
| 3212 |
the number of characters extracted, and does not affect the value
|
| 3213 |
-
returned by subsequent calls to `gcount()`. After constructing a
|
| 3214 |
-
object, if `fail() != true`, executes
|
| 3215 |
`rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
|
| 3216 |
function calls `setstate(failbit)` (which may throw
|
| 3217 |
`ios_base::failure`).
|
| 3218 |
|
| 3219 |
*Returns:* `*this`.
|
|
@@ -3229,11 +3353,11 @@ template<class charT, class traits>
|
|
| 3229 |
```
|
| 3230 |
|
| 3231 |
*Effects:* Behaves as an unformatted input
|
| 3232 |
function [[istream.unformatted]], except that it does not count the
|
| 3233 |
number of characters extracted and does not affect the value returned by
|
| 3234 |
-
subsequent calls to `is.gcount()`. After constructing a sentry object
|
| 3235 |
extracts characters as long as the next available character `c` is
|
| 3236 |
whitespace or until there are no more characters in the sequence.
|
| 3237 |
Whitespace characters are distinguished with the same criterion as used
|
| 3238 |
by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
|
| 3239 |
characters because there are no more available it sets `eofbit`, but not
|
|
@@ -3247,22 +3371,24 @@ characters because there are no more available it sets `eofbit`, but not
|
|
| 3247 |
template<class Istream, class T>
|
| 3248 |
Istream&& operator>>(Istream&& is, T&& x);
|
| 3249 |
```
|
| 3250 |
|
| 3251 |
*Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
|
| 3252 |
-
when treated as an unevaluated operand
|
| 3253 |
-
unambiguously derived from `ios_base`.
|
| 3254 |
|
| 3255 |
*Effects:* Equivalent to:
|
| 3256 |
|
| 3257 |
``` cpp
|
| 3258 |
is >> std::forward<T>(x);
|
| 3259 |
return std::move(is);
|
| 3260 |
```
|
| 3261 |
|
| 3262 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 3263 |
|
|
|
|
|
|
|
| 3264 |
``` cpp
|
| 3265 |
namespace std {
|
| 3266 |
template<class charT, class traits = char_traits<charT>>
|
| 3267 |
class basic_iostream
|
| 3268 |
: public basic_istream<charT, traits>,
|
|
@@ -3283,11 +3409,11 @@ namespace std {
|
|
| 3283 |
protected:
|
| 3284 |
// [iostream.cons], constructor
|
| 3285 |
basic_iostream(const basic_iostream&) = delete;
|
| 3286 |
basic_iostream(basic_iostream&& rhs);
|
| 3287 |
|
| 3288 |
-
// [iostream.assign],
|
| 3289 |
basic_iostream& operator=(const basic_iostream&) = delete;
|
| 3290 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3291 |
void swap(basic_iostream& rhs);
|
| 3292 |
};
|
| 3293 |
}
|
|
@@ -3312,11 +3438,11 @@ explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
|
| 3312 |
``` cpp
|
| 3313 |
basic_iostream(basic_iostream&& rhs);
|
| 3314 |
```
|
| 3315 |
|
| 3316 |
*Effects:* Move constructs from the rvalue `rhs` by constructing the
|
| 3317 |
-
`basic_istream` base class with `move(rhs)`.
|
| 3318 |
|
| 3319 |
##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
|
| 3320 |
|
| 3321 |
``` cpp
|
| 3322 |
virtual ~basic_iostream();
|
|
@@ -3338,16 +3464,24 @@ void swap(basic_iostream& rhs);
|
|
| 3338 |
|
| 3339 |
*Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
|
| 3340 |
|
| 3341 |
### Output streams <a id="output.streams">[[output.streams]]</a>
|
| 3342 |
|
| 3343 |
-
|
| 3344 |
-
|
| 3345 |
-
|
|
|
|
|
|
|
| 3346 |
|
| 3347 |
#### Class template `basic_ostream` <a id="ostream">[[ostream]]</a>
|
| 3348 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3349 |
``` cpp
|
| 3350 |
namespace std {
|
| 3351 |
template<class charT, class traits = char_traits<charT>>
|
| 3352 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 3353 |
public:
|
|
@@ -3364,51 +3498,50 @@ namespace std {
|
|
| 3364 |
|
| 3365 |
// [ostream.sentry], prefix/suffix
|
| 3366 |
class sentry;
|
| 3367 |
|
| 3368 |
// [ostream.formatted], formatted output
|
| 3369 |
-
basic_ostream<
|
| 3370 |
-
|
| 3371 |
-
basic_ostream<
|
| 3372 |
-
operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 3373 |
-
basic_ostream<charT, traits>&
|
| 3374 |
-
operator<<(ios_base& (*pf)(ios_base&));
|
| 3375 |
|
| 3376 |
-
basic_ostream
|
| 3377 |
-
basic_ostream
|
| 3378 |
-
basic_ostream
|
| 3379 |
-
basic_ostream
|
| 3380 |
-
basic_ostream
|
| 3381 |
-
basic_ostream
|
| 3382 |
-
basic_ostream
|
| 3383 |
-
basic_ostream
|
| 3384 |
-
basic_ostream
|
| 3385 |
-
basic_ostream
|
| 3386 |
-
basic_ostream
|
| 3387 |
-
basic_ostream
|
|
|
|
| 3388 |
|
| 3389 |
-
basic_ostream
|
| 3390 |
-
basic_ostream
|
| 3391 |
-
basic_ostream
|
|
|
|
| 3392 |
|
| 3393 |
// [ostream.unformatted], unformatted output
|
| 3394 |
-
basic_ostream
|
| 3395 |
-
basic_ostream
|
| 3396 |
|
| 3397 |
-
basic_ostream
|
| 3398 |
|
| 3399 |
// [ostream.seeks], seeks
|
| 3400 |
pos_type tellp();
|
| 3401 |
-
basic_ostream
|
| 3402 |
-
basic_ostream
|
| 3403 |
|
| 3404 |
protected:
|
| 3405 |
// [ostream.cons], copy/move constructor
|
| 3406 |
basic_ostream(const basic_ostream&) = delete;
|
| 3407 |
basic_ostream(basic_ostream&& rhs);
|
| 3408 |
|
| 3409 |
-
// [ostream.assign],
|
| 3410 |
basic_ostream& operator=(const basic_ostream&) = delete;
|
| 3411 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3412 |
void swap(basic_ostream& rhs);
|
| 3413 |
};
|
| 3414 |
|
|
@@ -3544,15 +3677,16 @@ void swap(basic_ostream& rhs);
|
|
| 3544 |
|
| 3545 |
##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
|
| 3546 |
|
| 3547 |
``` cpp
|
| 3548 |
namespace std {
|
| 3549 |
-
template<class charT, class traits
|
| 3550 |
class basic_ostream<charT, traits>::sentry {
|
| 3551 |
bool ok_; // exposition only
|
|
|
|
| 3552 |
public:
|
| 3553 |
-
explicit sentry(basic_ostream
|
| 3554 |
~sentry();
|
| 3555 |
explicit operator bool() const { return ok_; }
|
| 3556 |
|
| 3557 |
sentry(const sentry&) = delete;
|
| 3558 |
sentry& operator=(const sentry&) = delete;
|
|
@@ -3562,20 +3696,20 @@ namespace std {
|
|
| 3562 |
|
| 3563 |
The class `sentry` defines a class that is responsible for doing
|
| 3564 |
exception safe prefix and suffix operations.
|
| 3565 |
|
| 3566 |
``` cpp
|
| 3567 |
-
explicit sentry(basic_ostream
|
| 3568 |
```
|
| 3569 |
|
| 3570 |
If `os.good()` is nonzero, prepares for formatted or unformatted output.
|
| 3571 |
-
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^
|
| 3572 |
|
| 3573 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 3574 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 3575 |
constructor may call `setstate(failbit)` (which may throw
|
| 3576 |
-
`ios_base::failure` [[iostate.flags]]).[^
|
| 3577 |
|
| 3578 |
``` cpp
|
| 3579 |
~sentry();
|
| 3580 |
```
|
| 3581 |
|
|
@@ -3601,22 +3735,22 @@ pos_type tellp();
|
|
| 3601 |
|
| 3602 |
*Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
|
| 3603 |
failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
|
| 3604 |
|
| 3605 |
``` cpp
|
| 3606 |
-
basic_ostream
|
| 3607 |
```
|
| 3608 |
|
| 3609 |
*Effects:* If `fail() != true`, executes
|
| 3610 |
`rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
|
| 3611 |
function calls `setstate(failbit)` (which may throw
|
| 3612 |
`ios_base::failure`).
|
| 3613 |
|
| 3614 |
*Returns:* `*this`.
|
| 3615 |
|
| 3616 |
``` cpp
|
| 3617 |
-
basic_ostream
|
| 3618 |
```
|
| 3619 |
|
| 3620 |
*Effects:* If `fail() != true`, executes
|
| 3621 |
`rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
|
| 3622 |
function calls `setstate(failbit)` (which may throw
|
|
@@ -3627,20 +3761,22 @@ function calls `setstate(failbit)` (which may throw
|
|
| 3627 |
#### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
|
| 3628 |
|
| 3629 |
##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
|
| 3630 |
|
| 3631 |
Each formatted output function begins execution by constructing an
|
| 3632 |
-
object of class `sentry`. If
|
| 3633 |
to a value of type `bool`, the function endeavors to generate the
|
| 3634 |
requested output. If the generation fails, then the formatted output
|
| 3635 |
-
function does `setstate(ios_base::failbit)`, which
|
| 3636 |
exception. If an exception is thrown during output, then
|
| 3637 |
-
`ios_base::badbit` is
|
| 3638 |
-
|
| 3639 |
-
|
| 3640 |
-
|
| 3641 |
-
|
|
|
|
|
|
|
| 3642 |
|
| 3643 |
The descriptions of the individual formatted output functions describe
|
| 3644 |
how they perform output and do not mention the `sentry` object.
|
| 3645 |
|
| 3646 |
If a formatted output function of a stream `os` determines padding, it
|
|
@@ -3653,23 +3789,23 @@ the fill characters are placed after the character sequence; otherwise,
|
|
| 3653 |
they are placed before the character sequence.
|
| 3654 |
|
| 3655 |
##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
|
| 3656 |
|
| 3657 |
``` cpp
|
| 3658 |
-
operator<<(bool val);
|
| 3659 |
-
operator<<(short val);
|
| 3660 |
-
operator<<(unsigned short val);
|
| 3661 |
-
operator<<(int val);
|
| 3662 |
-
operator<<(unsigned int val);
|
| 3663 |
-
operator<<(long val);
|
| 3664 |
-
operator<<(unsigned long val);
|
| 3665 |
-
operator<<(long long val);
|
| 3666 |
-
operator<<(unsigned long long val);
|
| 3667 |
-
operator<<(float val);
|
| 3668 |
-
operator<<(double val);
|
| 3669 |
-
operator<<(long double val);
|
| 3670 |
-
operator<<(const void* val);
|
| 3671 |
```
|
| 3672 |
|
| 3673 |
*Effects:* The classes `num_get<>` and `num_put<>` handle
|
| 3674 |
locale-dependent numeric formatting and parsing. These inserter
|
| 3675 |
functions use the imbued `locale` value to perform numeric formatting.
|
|
@@ -3740,49 +3876,90 @@ It provides formatting specifications such as field width, and a locale
|
|
| 3740 |
from which to obtain other facets. If `failed` is `true` then does
|
| 3741 |
`setstate(badbit)`, which may throw an exception, and returns.
|
| 3742 |
|
| 3743 |
*Returns:* `*this`.
|
| 3744 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3745 |
##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
|
| 3746 |
|
| 3747 |
``` cpp
|
| 3748 |
-
basic_ostream<
|
| 3749 |
-
operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
|
| 3750 |
```
|
| 3751 |
|
| 3752 |
*Effects:* None. Does not behave as a formatted output function (as
|
| 3753 |
described in [[ostream.formatted.reqmts]]).
|
| 3754 |
|
| 3755 |
-
*Returns:* `pf(*this)`.[^
|
| 3756 |
|
| 3757 |
``` cpp
|
| 3758 |
-
basic_ostream<charT, traits>&
|
| 3759 |
-
operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 3760 |
```
|
| 3761 |
|
| 3762 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3763 |
formatted output function (as described
|
| 3764 |
in [[ostream.formatted.reqmts]]).
|
| 3765 |
|
| 3766 |
-
*Returns:* `*this`.[^
|
| 3767 |
|
| 3768 |
``` cpp
|
| 3769 |
-
basic_ostream
|
| 3770 |
```
|
| 3771 |
|
| 3772 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3773 |
formatted output function (as described
|
| 3774 |
in [[ostream.formatted.reqmts]]).
|
| 3775 |
|
| 3776 |
*Returns:* `*this`.
|
| 3777 |
|
| 3778 |
``` cpp
|
| 3779 |
-
basic_ostream
|
| 3780 |
```
|
| 3781 |
|
| 3782 |
*Effects:* Behaves as an unformatted output
|
| 3783 |
-
function [[ostream.unformatted]]. After the sentry object is
|
| 3784 |
constructed, if `sb` is null calls `setstate(badbit)` (which may throw
|
| 3785 |
`ios_base::failure`).
|
| 3786 |
|
| 3787 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 3788 |
read from `sb` and inserted until any of the following occurs:
|
|
@@ -3799,11 +3976,11 @@ the error state, and if `failbit` is set in `exceptions()` the caught
|
|
| 3799 |
exception is rethrown.
|
| 3800 |
|
| 3801 |
*Returns:* `*this`.
|
| 3802 |
|
| 3803 |
``` cpp
|
| 3804 |
-
basic_ostream
|
| 3805 |
```
|
| 3806 |
|
| 3807 |
*Effects:* Equivalent to:
|
| 3808 |
|
| 3809 |
``` cpp
|
|
@@ -3876,29 +4053,98 @@ Determines padding for `seq` as described
|
|
| 3876 |
in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
|
| 3877 |
`width(0)`.
|
| 3878 |
|
| 3879 |
*Returns:* `out`.
|
| 3880 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3881 |
#### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
|
| 3882 |
|
| 3883 |
Each unformatted output function begins execution by constructing an
|
| 3884 |
-
object of class `sentry`. If
|
| 3885 |
converting to a value of type `bool`, the function endeavors to generate
|
| 3886 |
the requested output. If an exception is thrown during output, then
|
| 3887 |
-
`ios_base::badbit` is
|
| 3888 |
-
|
| 3889 |
-
|
| 3890 |
-
|
| 3891 |
-
|
|
|
|
| 3892 |
|
| 3893 |
``` cpp
|
| 3894 |
-
basic_ostream
|
| 3895 |
```
|
| 3896 |
|
| 3897 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3898 |
-
above). After constructing a sentry object, inserts the character `c`,
|
| 3899 |
-
if possible.[^
|
| 3900 |
|
| 3901 |
Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 3902 |
[[iostate.flags]]).
|
| 3903 |
|
| 3904 |
*Returns:* `*this`.
|
|
@@ -3906,14 +4152,15 @@ Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
|
|
| 3906 |
``` cpp
|
| 3907 |
basic_ostream& write(const char_type* s, streamsize n);
|
| 3908 |
```
|
| 3909 |
|
| 3910 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3911 |
-
above). After constructing a sentry object, obtains characters to
|
| 3912 |
-
from successive locations of an array whose first element is
|
| 3913 |
-
by `s`.[^
|
| 3914 |
-
|
|
|
|
| 3915 |
|
| 3916 |
- `n` characters are inserted;
|
| 3917 |
- inserting in the output sequence fails (in which case the function
|
| 3918 |
calls `setstate(badbit)`, which may throw `ios_base::failure`
|
| 3919 |
[[iostate.flags]]).
|
|
@@ -3923,15 +4170,15 @@ occurs:
|
|
| 3923 |
``` cpp
|
| 3924 |
basic_ostream& flush();
|
| 3925 |
```
|
| 3926 |
|
| 3927 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3928 |
-
above). If `rdbuf()` is not a null pointer, constructs a sentry
|
| 3929 |
-
If
|
| 3930 |
-
the function calls `rdbuf()->pubsync()`. If that function returns
|
| 3931 |
-
calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 3932 |
-
[[iostate.flags]]). Otherwise, if the sentry object returns `false`,
|
| 3933 |
does nothing.
|
| 3934 |
|
| 3935 |
*Returns:* `*this`.
|
| 3936 |
|
| 3937 |
#### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
|
|
@@ -4001,11 +4248,14 @@ template<class charT, class traits>
|
|
| 4001 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 4002 |
```
|
| 4003 |
|
| 4004 |
*Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
|
| 4005 |
`basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
|
| 4006 |
-
of exposition,
|
|
|
|
|
|
|
|
|
|
| 4007 |
|
| 4008 |
*Returns:* `os`.
|
| 4009 |
|
| 4010 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 4011 |
|
|
@@ -4035,11 +4285,11 @@ unspecified resetiosflags(ios_base::fmtflags mask);
|
|
| 4035 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4036 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4037 |
`out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
|
| 4038 |
if `in` is an object of type `basic_istream<charT, traits>` then the
|
| 4039 |
expression `in >> resetiosflags(mask)` behaves as if it called
|
| 4040 |
-
`f(in, mask)`, where the function `f` is defined as:[^
|
| 4041 |
|
| 4042 |
``` cpp
|
| 4043 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 4044 |
// reset specified flags
|
| 4045 |
str.setf(ios_base::fmtflags(0), mask);
|
|
@@ -4234,25 +4484,25 @@ void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
|
|
| 4234 |
|
| 4235 |
The expression `out << put_money(mon, intl)` has type
|
| 4236 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4237 |
|
| 4238 |
``` cpp
|
| 4239 |
-
template<class charT> unspecified get_time(
|
| 4240 |
```
|
| 4241 |
|
| 4242 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 4243 |
-
type `
|
| 4244 |
-
|
| 4245 |
|
| 4246 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4247 |
of type `basic_istream<charT, traits>` then the expression
|
| 4248 |
`in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
|
| 4249 |
where the function `f` is defined as:
|
| 4250 |
|
| 4251 |
``` cpp
|
| 4252 |
template<class charT, class traits>
|
| 4253 |
-
void f(basic_ios<charT, traits>& str,
|
| 4254 |
using Iter = istreambuf_iterator<charT, traits>;
|
| 4255 |
using TimeGet = time_get<charT, Iter>;
|
| 4256 |
|
| 4257 |
ios_base::iostate err = ios_base::goodbit;
|
| 4258 |
const TimeGet& tg = use_facet<TimeGet>(str.getloc());
|
|
@@ -4267,25 +4517,25 @@ void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
|
|
| 4267 |
|
| 4268 |
The expression `in >> get_time(tmb, fmt)` has type
|
| 4269 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4270 |
|
| 4271 |
``` cpp
|
| 4272 |
-
template<class charT> unspecified put_time(const
|
| 4273 |
```
|
| 4274 |
|
| 4275 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 4276 |
-
type `
|
| 4277 |
-
|
| 4278 |
|
| 4279 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4280 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4281 |
`out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
|
| 4282 |
where the function `f` is defined as:
|
| 4283 |
|
| 4284 |
``` cpp
|
| 4285 |
template<class charT, class traits>
|
| 4286 |
-
void f(basic_ios<charT, traits>& str, const
|
| 4287 |
using Iter = ostreambuf_iterator<charT, traits>;
|
| 4288 |
using TimePut = time_put<charT, Iter>;
|
| 4289 |
|
| 4290 |
const TimePut& tp = use_facet<TimePut>(str.getloc());
|
| 4291 |
const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
|
|
@@ -4374,39 +4624,178 @@ template<class charT, class traits, class Allocator>
|
|
| 4374 |
- The expression `in >> quoted(s, delim, escape)` has type
|
| 4375 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4376 |
- The expression `out << quoted(s, delim, escape)` has type
|
| 4377 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4378 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4379 |
## String-based streams <a id="string.streams">[[string.streams]]</a>
|
| 4380 |
|
| 4381 |
### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
|
| 4382 |
|
| 4383 |
``` cpp
|
| 4384 |
namespace std {
|
| 4385 |
template<class charT, class traits = char_traits<charT>,
|
| 4386 |
class Allocator = allocator<charT>>
|
| 4387 |
class basic_stringbuf;
|
| 4388 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4389 |
using stringbuf = basic_stringbuf<char>;
|
| 4390 |
using wstringbuf = basic_stringbuf<wchar_t>;
|
| 4391 |
|
| 4392 |
template<class charT, class traits = char_traits<charT>,
|
| 4393 |
class Allocator = allocator<charT>>
|
| 4394 |
class basic_istringstream;
|
| 4395 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4396 |
using istringstream = basic_istringstream<char>;
|
| 4397 |
using wistringstream = basic_istringstream<wchar_t>;
|
| 4398 |
|
| 4399 |
template<class charT, class traits = char_traits<charT>,
|
| 4400 |
class Allocator = allocator<charT>>
|
| 4401 |
class basic_ostringstream;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4402 |
using ostringstream = basic_ostringstream<char>;
|
| 4403 |
using wostringstream = basic_ostringstream<wchar_t>;
|
| 4404 |
|
| 4405 |
template<class charT, class traits = char_traits<charT>,
|
| 4406 |
class Allocator = allocator<charT>>
|
| 4407 |
class basic_stringstream;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4408 |
using stringstream = basic_stringstream<char>;
|
| 4409 |
using wstringstream = basic_stringstream<wchar_t>;
|
| 4410 |
}
|
| 4411 |
```
|
| 4412 |
|
|
@@ -4414,10 +4803,12 @@ The header `<sstream>` defines four class templates and eight types that
|
|
| 4414 |
associate stream buffers with objects of class `basic_string`, as
|
| 4415 |
described in [[string.classes]].
|
| 4416 |
|
| 4417 |
### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
|
| 4418 |
|
|
|
|
|
|
|
| 4419 |
``` cpp
|
| 4420 |
namespace std {
|
| 4421 |
template<class charT, class traits = char_traits<charT>,
|
| 4422 |
class Allocator = allocator<charT>>
|
| 4423 |
class basic_stringbuf : public basic_streambuf<charT, traits> {
|
|
@@ -4455,11 +4846,11 @@ namespace std {
|
|
| 4455 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4456 |
basic_stringbuf(const basic_stringbuf&) = delete;
|
| 4457 |
basic_stringbuf(basic_stringbuf&& rhs);
|
| 4458 |
basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
|
| 4459 |
|
| 4460 |
-
// [stringbuf.assign],
|
| 4461 |
basic_stringbuf& operator=(const basic_stringbuf&) = delete;
|
| 4462 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4463 |
void swap(basic_stringbuf& rhs) noexcept(see below);
|
| 4464 |
|
| 4465 |
// [stringbuf.members], getters and setters
|
|
@@ -4493,14 +4884,10 @@ namespace std {
|
|
| 4493 |
private:
|
| 4494 |
ios_base::openmode mode; // exposition only
|
| 4495 |
basic_string<charT, traits, Allocator> buf; // exposition only
|
| 4496 |
void init_buf_ptrs(); // exposition only
|
| 4497 |
};
|
| 4498 |
-
|
| 4499 |
-
template<class charT, class traits, class Allocator>
|
| 4500 |
-
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4501 |
-
basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
|
| 4502 |
}
|
| 4503 |
```
|
| 4504 |
|
| 4505 |
The class `basic_stringbuf` is derived from `basic_streambuf` to
|
| 4506 |
associate possibly the input sequence and possibly the output sequence
|
|
@@ -4633,15 +5020,15 @@ would have had if it had been move constructed from `rhs`
|
|
| 4633 |
void swap(basic_stringbuf& rhs) noexcept(see below);
|
| 4634 |
```
|
| 4635 |
|
| 4636 |
*Preconditions:*
|
| 4637 |
`allocator_traits<Allocator>::propagate_on_container_swap::value` is
|
| 4638 |
-
`true` or `get_allocator() ==
|
| 4639 |
|
| 4640 |
*Effects:* Exchanges the state of `*this` and `rhs`.
|
| 4641 |
|
| 4642 |
-
*Remarks:* The
|
| 4643 |
`allocator_traits<Allocator>::propagate_on_container_swap::value ||`
|
| 4644 |
`allocator_traits<Allocator>::is_always_equal::value`.
|
| 4645 |
|
| 4646 |
``` cpp
|
| 4647 |
template<class charT, class traits, class Allocator>
|
|
@@ -4679,12 +5066,12 @@ according to `mode`.
|
|
| 4679 |
- otherwise `pptr() == pbase()` is `true`.
|
| 4680 |
- If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
|
| 4681 |
and `(gptr() == eback() && egptr() == eback() + buf.size())` is
|
| 4682 |
`true`.
|
| 4683 |
|
| 4684 |
-
[*Note 1*: For efficiency reasons, stream buffer operations
|
| 4685 |
-
|
| 4686 |
`basic_stringbuf`, e.g., by writing to characters in the range
|
| 4687 |
\[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
|
| 4688 |
operations retrieving a `basic_string` from `buf` ensure that the
|
| 4689 |
`basic_string` invariants hold on the returned value. — *end note*]
|
| 4690 |
|
|
@@ -4720,19 +5107,19 @@ return basic_string<charT, traits, SAlloc>(view(), sa);
|
|
| 4720 |
|
| 4721 |
``` cpp
|
| 4722 |
basic_string<charT, traits, Allocator> str() &&;
|
| 4723 |
```
|
| 4724 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4725 |
*Returns:* A `basic_string<charT, traits, Allocator>` object move
|
| 4726 |
constructed from the `basic_stringbuf`’s underlying character sequence
|
| 4727 |
in `buf`. This can be achieved by first adjusting `buf` to have the same
|
| 4728 |
content as `view()`.
|
| 4729 |
|
| 4730 |
-
*Ensures:* The underlying character sequence `buf` is empty and
|
| 4731 |
-
`pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
|
| 4732 |
-
initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
|
| 4733 |
-
|
| 4734 |
``` cpp
|
| 4735 |
basic_string_view<charT, traits> view() const noexcept;
|
| 4736 |
```
|
| 4737 |
|
| 4738 |
Let `sv` be `basic_string_view<charT, traits>`.
|
|
@@ -4808,11 +5195,11 @@ sequence, if possible, in one of three ways:
|
|
| 4808 |
input sequence has a putback position available, and if
|
| 4809 |
`traits::eq(to_char_type(c), gptr()[-1])` returns `true`, assigns
|
| 4810 |
`gptr() - 1` to `gptr()`. Returns: `c`.
|
| 4811 |
- If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
|
| 4812 |
input sequence has a putback position available, and if `mode` `&`
|
| 4813 |
-
`ios_base::out` is nonzero, assigns `c` to `*
|
| 4814 |
- If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
|
| 4815 |
input sequence has a putback position available, assigns `gptr() - 1`
|
| 4816 |
to `gptr()`. Returns: `traits::not_eof(c)`.
|
| 4817 |
|
| 4818 |
*Returns:* As specified above, or `traits::eof()` to indicate failure.
|
|
@@ -4833,15 +5220,15 @@ sequence, if possible, in one of two ways:
|
|
| 4833 |
function calls `sputc(c)`. Signals success by returning `c`.
|
| 4834 |
- If `traits::eq_int_type(c, traits::eof())` returns `true`, there is no
|
| 4835 |
character to append. Signals success by returning a value other than
|
| 4836 |
`traits::eof()`.
|
| 4837 |
|
|
|
|
|
|
|
| 4838 |
*Remarks:* The function can alter the number of write positions
|
| 4839 |
available as a result of any call.
|
| 4840 |
|
| 4841 |
-
*Returns:* As specified above, or `traits::eof()` to indicate failure.
|
| 4842 |
-
|
| 4843 |
The function can make a write position available only if `ios_base::out`
|
| 4844 |
is set in `mode`. To make a write position available, the function
|
| 4845 |
reallocates (or initially allocates) an array object with a sufficient
|
| 4846 |
number of elements to hold the current array object (if any), plus at
|
| 4847 |
least one additional write position. If `ios_base::in` is set in `mode`,
|
|
@@ -4902,20 +5289,22 @@ pos_type seekpos(pos_type sp,
|
|
| 4902 |
|
| 4903 |
*Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
|
| 4904 |
indicate failure.
|
| 4905 |
|
| 4906 |
``` cpp
|
| 4907 |
-
basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n);
|
| 4908 |
```
|
| 4909 |
|
| 4910 |
*Effects:* *implementation-defined*, except that `setbuf(0, 0)` has no
|
| 4911 |
effect.
|
| 4912 |
|
| 4913 |
*Returns:* `this`.
|
| 4914 |
|
| 4915 |
### Class template `basic_istringstream` <a id="istringstream">[[istringstream]]</a>
|
| 4916 |
|
|
|
|
|
|
|
| 4917 |
``` cpp
|
| 4918 |
namespace std {
|
| 4919 |
template<class charT, class traits = char_traits<charT>,
|
| 4920 |
class Allocator = allocator<charT>>
|
| 4921 |
class basic_istringstream : public basic_istream<charT, traits> {
|
|
@@ -4950,13 +5339,14 @@ namespace std {
|
|
| 4950 |
const basic_string<charT, traits, SAlloc>& s,
|
| 4951 |
ios_base::openmode which = ios_base::in);
|
| 4952 |
basic_istringstream(const basic_istringstream&) = delete;
|
| 4953 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4954 |
|
| 4955 |
-
// [istringstream.assign], assign and swap
|
| 4956 |
basic_istringstream& operator=(const basic_istringstream&) = delete;
|
| 4957 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
|
|
|
|
|
|
| 4958 |
void swap(basic_istringstream& rhs);
|
| 4959 |
|
| 4960 |
// [istringstream.members], members
|
| 4961 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4962 |
basic_string<charT, traits, Allocator> str() const &;
|
|
@@ -4971,14 +5361,10 @@ namespace std {
|
|
| 4971 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 4972 |
|
| 4973 |
private:
|
| 4974 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 4975 |
};
|
| 4976 |
-
|
| 4977 |
-
template<class charT, class traits, class Allocator>
|
| 4978 |
-
void swap(basic_istringstream<charT, traits, Allocator>& x,
|
| 4979 |
-
basic_istringstream<charT, traits, Allocator>& y);
|
| 4980 |
}
|
| 4981 |
```
|
| 4982 |
|
| 4983 |
The class `basic_istringstream<charT, traits, Allocator>` supports
|
| 4984 |
reading objects of class `basic_string<{}charT, traits, Allocator>`. It
|
|
@@ -5005,11 +5391,12 @@ explicit basic_istringstream(
|
|
| 5005 |
ios_base::openmode which = ios_base::in);
|
| 5006 |
```
|
| 5007 |
|
| 5008 |
*Effects:* Initializes the base class with
|
| 5009 |
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5010 |
-
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
|
|
|
|
| 5011 |
|
| 5012 |
``` cpp
|
| 5013 |
basic_istringstream(ios_base::openmode which, const Allocator& a);
|
| 5014 |
```
|
| 5015 |
|
|
@@ -5036,11 +5423,12 @@ template<class SAlloc>
|
|
| 5036 |
ios_base::openmode which, const Allocator& a);
|
| 5037 |
```
|
| 5038 |
|
| 5039 |
*Effects:* Initializes the base class with
|
| 5040 |
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5041 |
-
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`
|
|
|
|
| 5042 |
|
| 5043 |
``` cpp
|
| 5044 |
template<class SAlloc>
|
| 5045 |
explicit basic_istringstream(
|
| 5046 |
const basic_string<charT, traits, SAlloc>& s,
|
|
@@ -5060,11 +5448,11 @@ basic_istringstream(basic_istringstream&& rhs);
|
|
| 5060 |
by move constructing the base class, and the contained
|
| 5061 |
`basic_stringbuf`. Then calls
|
| 5062 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5063 |
contained `basic_stringbuf`.
|
| 5064 |
|
| 5065 |
-
####
|
| 5066 |
|
| 5067 |
``` cpp
|
| 5068 |
void swap(basic_istringstream& rhs);
|
| 5069 |
```
|
| 5070 |
|
|
@@ -5136,10 +5524,12 @@ void str(basic_string<charT, traits, Allocator>&& s);
|
|
| 5136 |
|
| 5137 |
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5138 |
|
| 5139 |
### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
|
| 5140 |
|
|
|
|
|
|
|
| 5141 |
``` cpp
|
| 5142 |
namespace std {
|
| 5143 |
template<class charT, class traits = char_traits<charT>,
|
| 5144 |
class Allocator = allocator<charT>>
|
| 5145 |
class basic_ostringstream : public basic_ostream<charT, traits> {
|
|
@@ -5174,13 +5564,14 @@ namespace std {
|
|
| 5174 |
const basic_string<charT, traits, SAlloc>& s,
|
| 5175 |
ios_base::openmode which = ios_base::out);
|
| 5176 |
basic_ostringstream(const basic_ostringstream&) = delete;
|
| 5177 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 5178 |
|
| 5179 |
-
// [ostringstream.assign], assign and swap
|
| 5180 |
basic_ostringstream& operator=(const basic_ostringstream&) = delete;
|
| 5181 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
|
|
|
|
|
|
| 5182 |
void swap(basic_ostringstream& rhs);
|
| 5183 |
|
| 5184 |
// [ostringstream.members], members
|
| 5185 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5186 |
|
|
@@ -5196,14 +5587,10 @@ namespace std {
|
|
| 5196 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5197 |
|
| 5198 |
private:
|
| 5199 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 5200 |
};
|
| 5201 |
-
|
| 5202 |
-
template<class charT, class traits, class Allocator>
|
| 5203 |
-
void swap(basic_ostringstream<charT, traits, Allocator>& x,
|
| 5204 |
-
basic_ostringstream<charT, traits, Allocator>& y);
|
| 5205 |
}
|
| 5206 |
```
|
| 5207 |
|
| 5208 |
The class `basic_ostringstream<charT, traits, Allocator>` supports
|
| 5209 |
writing objects of class `basic_string<{}charT, traits, Allocator>`. It
|
|
@@ -5229,19 +5616,21 @@ explicit basic_ostringstream(
|
|
| 5229 |
ios_base::openmode which = ios_base::out);
|
| 5230 |
```
|
| 5231 |
|
| 5232 |
*Effects:* Initializes the base class with
|
| 5233 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5234 |
-
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
|
|
|
|
| 5235 |
|
| 5236 |
``` cpp
|
| 5237 |
basic_ostringstream(ios_base::openmode which, const Allocator& a);
|
| 5238 |
```
|
| 5239 |
|
| 5240 |
*Effects:* Initializes the base class with
|
| 5241 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5242 |
-
`basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`
|
|
|
|
| 5243 |
|
| 5244 |
``` cpp
|
| 5245 |
explicit basic_ostringstream(
|
| 5246 |
basic_string<charT, traits, Allocator>&& s,
|
| 5247 |
ios_base::openmode which = ios_base::out);
|
|
@@ -5259,11 +5648,12 @@ template<class SAlloc>
|
|
| 5259 |
ios_base::openmode which, const Allocator& a);
|
| 5260 |
```
|
| 5261 |
|
| 5262 |
*Effects:* Initializes the base class with
|
| 5263 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5264 |
-
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`
|
|
|
|
| 5265 |
|
| 5266 |
``` cpp
|
| 5267 |
template<class SAlloc>
|
| 5268 |
explicit basic_ostringstream(
|
| 5269 |
const basic_string<charT, traits, SAlloc>& s,
|
|
@@ -5272,11 +5662,12 @@ template<class SAlloc>
|
|
| 5272 |
|
| 5273 |
*Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
|
| 5274 |
|
| 5275 |
*Effects:* Initializes the base class with
|
| 5276 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5277 |
-
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
|
|
|
|
| 5278 |
|
| 5279 |
``` cpp
|
| 5280 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 5281 |
```
|
| 5282 |
|
|
@@ -5284,11 +5675,11 @@ basic_ostringstream(basic_ostringstream&& rhs);
|
|
| 5284 |
by move constructing the base class, and the contained
|
| 5285 |
`basic_stringbuf`. Then calls
|
| 5286 |
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5287 |
contained `basic_stringbuf`.
|
| 5288 |
|
| 5289 |
-
####
|
| 5290 |
|
| 5291 |
``` cpp
|
| 5292 |
void swap(basic_ostringstream& rhs);
|
| 5293 |
```
|
| 5294 |
|
|
@@ -5360,10 +5751,12 @@ void str(basic_string<charT, traits, Allocator>&& s);
|
|
| 5360 |
|
| 5361 |
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5362 |
|
| 5363 |
### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
|
| 5364 |
|
|
|
|
|
|
|
| 5365 |
``` cpp
|
| 5366 |
namespace std {
|
| 5367 |
template<class charT, class traits = char_traits<charT>,
|
| 5368 |
class Allocator = allocator<charT>>
|
| 5369 |
class basic_stringstream : public basic_iostream<charT, traits> {
|
|
@@ -5398,13 +5791,14 @@ namespace std {
|
|
| 5398 |
const basic_string<charT, traits, SAlloc>& s,
|
| 5399 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5400 |
basic_stringstream(const basic_stringstream&) = delete;
|
| 5401 |
basic_stringstream(basic_stringstream&& rhs);
|
| 5402 |
|
| 5403 |
-
// [stringstream.assign], assign and swap
|
| 5404 |
basic_stringstream& operator=(const basic_stringstream&) = delete;
|
| 5405 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
|
|
|
|
|
|
| 5406 |
void swap(basic_stringstream& rhs);
|
| 5407 |
|
| 5408 |
// [stringstream.members], members
|
| 5409 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5410 |
|
|
@@ -5420,14 +5814,10 @@ namespace std {
|
|
| 5420 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5421 |
|
| 5422 |
private:
|
| 5423 |
basic_stringbuf<charT, traits> sb; // exposition only
|
| 5424 |
};
|
| 5425 |
-
|
| 5426 |
-
template<class charT, class traits, class Allocator>
|
| 5427 |
-
void swap(basic_stringstream<charT, traits, Allocator>& x,
|
| 5428 |
-
basic_stringstream<charT, traits, Allocator>& y);
|
| 5429 |
}
|
| 5430 |
```
|
| 5431 |
|
| 5432 |
The class template `basic_stringstream<charT, traits>` supports reading
|
| 5433 |
and writing from objects of class
|
|
@@ -5513,11 +5903,11 @@ basic_stringstream(basic_stringstream&& rhs);
|
|
| 5513 |
by move constructing the base class, and the contained
|
| 5514 |
`basic_stringbuf`. Then calls
|
| 5515 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5516 |
contained `basic_stringbuf`.
|
| 5517 |
|
| 5518 |
-
####
|
| 5519 |
|
| 5520 |
``` cpp
|
| 5521 |
void swap(basic_stringstream& rhs);
|
| 5522 |
```
|
| 5523 |
|
|
@@ -5587,33 +5977,686 @@ template<class SAlloc>
|
|
| 5587 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5588 |
```
|
| 5589 |
|
| 5590 |
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5591 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5592 |
## File-based streams <a id="file.streams">[[file.streams]]</a>
|
| 5593 |
|
| 5594 |
### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
|
| 5595 |
|
| 5596 |
``` cpp
|
| 5597 |
namespace std {
|
| 5598 |
template<class charT, class traits = char_traits<charT>>
|
| 5599 |
class basic_filebuf;
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5600 |
using filebuf = basic_filebuf<char>;
|
| 5601 |
using wfilebuf = basic_filebuf<wchar_t>;
|
| 5602 |
|
| 5603 |
template<class charT, class traits = char_traits<charT>>
|
| 5604 |
class basic_ifstream;
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5605 |
using ifstream = basic_ifstream<char>;
|
| 5606 |
using wifstream = basic_ifstream<wchar_t>;
|
| 5607 |
|
| 5608 |
template<class charT, class traits = char_traits<charT>>
|
| 5609 |
class basic_ofstream;
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5610 |
using ofstream = basic_ofstream<char>;
|
| 5611 |
using wofstream = basic_ofstream<wchar_t>;
|
| 5612 |
|
| 5613 |
template<class charT, class traits = char_traits<charT>>
|
| 5614 |
class basic_fstream;
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5615 |
using fstream = basic_fstream<char>;
|
| 5616 |
using wfstream = basic_fstream<wchar_t>;
|
| 5617 |
}
|
| 5618 |
```
|
| 5619 |
|
|
@@ -5626,18 +6669,20 @@ or sink of bytes. In an environment that uses a large character set, the
|
|
| 5626 |
file typically holds multibyte character sequences and the
|
| 5627 |
`basic_filebuf` object converts those multibyte sequences into wide
|
| 5628 |
character sequences. — *end note*]
|
| 5629 |
|
| 5630 |
In subclause [[file.streams]], member functions taking arguments of
|
| 5631 |
-
`const filesystem::path::value_type*` are only
|
| 5632 |
-
|
| 5633 |
|
| 5634 |
[*Note 2*: These functions enable class `path` support for systems with
|
| 5635 |
a wide native path character type, such as `wchar_t`. — *end note*]
|
| 5636 |
|
| 5637 |
### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
|
| 5638 |
|
|
|
|
|
|
|
| 5639 |
``` cpp
|
| 5640 |
namespace std {
|
| 5641 |
template<class charT, class traits = char_traits<charT>>
|
| 5642 |
class basic_filebuf : public basic_streambuf<charT, traits> {
|
| 5643 |
public:
|
|
@@ -5651,11 +6696,11 @@ namespace std {
|
|
| 5651 |
basic_filebuf();
|
| 5652 |
basic_filebuf(const basic_filebuf&) = delete;
|
| 5653 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5654 |
virtual ~basic_filebuf();
|
| 5655 |
|
| 5656 |
-
// [filebuf.assign],
|
| 5657 |
basic_filebuf& operator=(const basic_filebuf&) = delete;
|
| 5658 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5659 |
void swap(basic_filebuf& rhs);
|
| 5660 |
|
| 5661 |
// [filebuf.members], members
|
|
@@ -5686,14 +6731,10 @@ namespace std {
|
|
| 5686 |
ios_base::openmode which
|
| 5687 |
= ios_base::in | ios_base::out) override;
|
| 5688 |
int sync() override;
|
| 5689 |
void imbue(const locale& loc) override;
|
| 5690 |
};
|
| 5691 |
-
|
| 5692 |
-
template<class charT, class traits>
|
| 5693 |
-
void swap(basic_filebuf<charT, traits>& x,
|
| 5694 |
-
basic_filebuf<charT, traits>& y);
|
| 5695 |
}
|
| 5696 |
```
|
| 5697 |
|
| 5698 |
The class `basic_filebuf<charT, traits>` associates both the input
|
| 5699 |
sequence and the output sequence with a file.
|
|
@@ -5791,12 +6832,11 @@ void swap(basic_filebuf& rhs);
|
|
| 5791 |
|
| 5792 |
*Effects:* Exchanges the state of `*this` and `rhs`.
|
| 5793 |
|
| 5794 |
``` cpp
|
| 5795 |
template<class charT, class traits>
|
| 5796 |
-
void swap(basic_filebuf<charT, traits>& x,
|
| 5797 |
-
basic_filebuf<charT, traits>& y);
|
| 5798 |
```
|
| 5799 |
|
| 5800 |
*Effects:* Equivalent to: `x.swap(y)`.
|
| 5801 |
|
| 5802 |
#### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
|
|
@@ -5823,35 +6863,42 @@ argument determined from `mode & ~ios_base::ate` as indicated in
|
|
| 5823 |
[[filebuf.open.modes]]. If `mode` is not some combination of flags shown
|
| 5824 |
in the table then the open fails.
|
| 5825 |
|
| 5826 |
**Table: File open modes** <a id="filebuf.open.modes">[filebuf.open.modes]</a>
|
| 5827 |
|
| 5828 |
-
| `binary` | `in` | `out` | `trunc` | `app` |
|
| 5829 |
-
| -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
|
| 5830 |
-
| | | + | | | `"w"`
|
| 5831 |
-
| | | + | | +
|
| 5832 |
-
| | |
|
| 5833 |
-
| | | + | + | | `"
|
| 5834 |
-
| | +
|
| 5835 |
-
| |
|
| 5836 |
-
| | + |
|
| 5837 |
-
| | + | + | |
|
| 5838 |
-
| | + |
|
| 5839 |
-
| +
|
| 5840 |
-
| +
|
| 5841 |
-
| +
|
| 5842 |
-
| + | +
|
| 5843 |
-
| + |
|
| 5844 |
-
| + |
|
| 5845 |
-
| + | +
|
| 5846 |
-
| + | +
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5847 |
|
| 5848 |
|
| 5849 |
If the open operation succeeds and `ios_base::ate` is set in `mode`,
|
| 5850 |
positions the file to the end (as if by calling
|
| 5851 |
`fseek(file, 0, SEEK_END)`, where `file` is the pointer returned by
|
| 5852 |
-
calling `fopen`).
|
| 5853 |
|
| 5854 |
If the repositioning operation fails, calls `close()` and returns a null
|
| 5855 |
pointer to indicate failure.
|
| 5856 |
|
| 5857 |
*Returns:* `this` if successful, a null pointer otherwise.
|
|
@@ -5878,25 +6925,25 @@ or throws an exception, the function closes the file (as if by calling
|
|
| 5878 |
`fclose(file)`). If any of the calls made by the function, including
|
| 5879 |
`fclose`, fails, `close` fails by returning a null pointer. If one of
|
| 5880 |
these calls throws an exception, the exception is caught and rethrown
|
| 5881 |
after closing the file.
|
| 5882 |
|
|
|
|
|
|
|
| 5883 |
*Returns:* `this` on success, a null pointer otherwise.
|
| 5884 |
|
| 5885 |
-
*Ensures:* `is_open() == false`.
|
| 5886 |
-
|
| 5887 |
#### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
|
| 5888 |
|
| 5889 |
``` cpp
|
| 5890 |
streamsize showmanyc() override;
|
| 5891 |
```
|
| 5892 |
|
| 5893 |
*Effects:* Behaves the same as `basic_streambuf::showmanyc()`
|
| 5894 |
[[streambuf.virtuals]].
|
| 5895 |
|
| 5896 |
-
*Remarks:* An implementation
|
| 5897 |
-
|
| 5898 |
be read from the input sequence.
|
| 5899 |
|
| 5900 |
``` cpp
|
| 5901 |
int_type underflow() override;
|
| 5902 |
```
|
|
@@ -6018,10 +7065,15 @@ operation fails. Otherwise, if `way != basic_ios::cur` or `off != 0`,
|
|
| 6018 |
and if the last operation was output, then update the output sequence
|
| 6019 |
and write any unshift sequence. Next, seek to the new position: if
|
| 6020 |
`width > 0`, call `fseek(file, width * off, whence)`, otherwise call
|
| 6021 |
`fseek(file, 0, whence)`.
|
| 6022 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6023 |
*Remarks:* “The last operation was output” means either the last virtual
|
| 6024 |
operation was overflow or the put buffer is non-empty. “Write any
|
| 6025 |
unshift sequence” means, if `width` if less than zero then call
|
| 6026 |
`a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
|
| 6027 |
resulting unshift sequence. The function determines one of three values
|
|
@@ -6034,16 +7086,10 @@ for the argument `whence`, of type `int`, as indicated in
|
|
| 6034 |
| ---------------- | ------------------ |
|
| 6035 |
| `basic_ios::beg` | `SEEK_SET` |
|
| 6036 |
| `basic_ios::cur` | `SEEK_CUR` |
|
| 6037 |
| `basic_ios::end` | `SEEK_END` |
|
| 6038 |
|
| 6039 |
-
|
| 6040 |
-
*Returns:* A newly constructed `pos_type` object that stores the
|
| 6041 |
-
resultant stream position, if possible. If the positioning operation
|
| 6042 |
-
fails, or if the object cannot represent the resultant stream position,
|
| 6043 |
-
returns `pos_type(off_type(-1))`.
|
| 6044 |
-
|
| 6045 |
``` cpp
|
| 6046 |
pos_type seekpos(pos_type sp,
|
| 6047 |
ios_base::openmode which
|
| 6048 |
= ios_base::in | ios_base::out) override;
|
| 6049 |
```
|
|
@@ -6093,10 +7139,12 @@ converted according to `loc` until another call of `imbue`.
|
|
| 6093 |
characters. This in turn may require the implementation to be able to
|
| 6094 |
reconstruct the original contents of the file.
|
| 6095 |
|
| 6096 |
### Class template `basic_ifstream` <a id="ifstream">[[ifstream]]</a>
|
| 6097 |
|
|
|
|
|
|
|
| 6098 |
``` cpp
|
| 6099 |
namespace std {
|
| 6100 |
template<class charT, class traits = char_traits<charT>>
|
| 6101 |
class basic_ifstream : public basic_istream<charT, traits> {
|
| 6102 |
public:
|
|
@@ -6112,18 +7160,19 @@ namespace std {
|
|
| 6112 |
ios_base::openmode mode = ios_base::in);
|
| 6113 |
explicit basic_ifstream(const filesystem::path::value_type* s,
|
| 6114 |
ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
|
| 6115 |
explicit basic_ifstream(const string& s,
|
| 6116 |
ios_base::openmode mode = ios_base::in);
|
| 6117 |
-
|
| 6118 |
-
|
| 6119 |
basic_ifstream(const basic_ifstream&) = delete;
|
| 6120 |
basic_ifstream(basic_ifstream&& rhs);
|
| 6121 |
|
| 6122 |
-
// [ifstream.assign], assign and swap
|
| 6123 |
basic_ifstream& operator=(const basic_ifstream&) = delete;
|
| 6124 |
basic_ifstream& operator=(basic_ifstream&& rhs);
|
|
|
|
|
|
|
| 6125 |
void swap(basic_ifstream& rhs);
|
| 6126 |
|
| 6127 |
// [ifstream.members], members
|
| 6128 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6129 |
|
|
@@ -6132,17 +7181,14 @@ namespace std {
|
|
| 6132 |
void open(const filesystem::path::value_type* s,
|
| 6133 |
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 6134 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
| 6135 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
|
| 6136 |
void close();
|
|
|
|
| 6137 |
private:
|
| 6138 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 6139 |
};
|
| 6140 |
-
|
| 6141 |
-
template<class charT, class traits>
|
| 6142 |
-
void swap(basic_ifstream<charT, traits>& x,
|
| 6143 |
-
basic_ifstream<charT, traits>& y);
|
| 6144 |
}
|
| 6145 |
```
|
| 6146 |
|
| 6147 |
The class `basic_ifstream<charT, traits>` supports reading from named
|
| 6148 |
files. It uses a `basic_filebuf<{}charT, traits>` object to control the
|
|
@@ -6175,38 +7221,44 @@ with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
|
|
| 6175 |
pointer, calls `setstate(failbit)`.
|
| 6176 |
|
| 6177 |
``` cpp
|
| 6178 |
explicit basic_ifstream(const string& s,
|
| 6179 |
ios_base::openmode mode = ios_base::in);
|
| 6180 |
-
explicit basic_ifstream(const filesystem::path& s,
|
| 6181 |
-
ios_base::openmode mode = ios_base::in);
|
| 6182 |
```
|
| 6183 |
|
| 6184 |
*Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
|
| 6185 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6186 |
``` cpp
|
| 6187 |
basic_ifstream(basic_ifstream&& rhs);
|
| 6188 |
```
|
| 6189 |
|
| 6190 |
*Effects:* Move constructs the base class, and the contained
|
| 6191 |
`basic_filebuf`. Then calls
|
| 6192 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 6193 |
contained `basic_filebuf`.
|
| 6194 |
|
| 6195 |
-
####
|
| 6196 |
|
| 6197 |
``` cpp
|
| 6198 |
void swap(basic_ifstream& rhs);
|
| 6199 |
```
|
| 6200 |
|
| 6201 |
*Effects:* Exchanges the state of `*this` and `rhs` by calling
|
| 6202 |
`basic_istream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
|
| 6203 |
|
| 6204 |
``` cpp
|
| 6205 |
template<class charT, class traits>
|
| 6206 |
-
void swap(basic_ifstream<charT, traits>& x,
|
| 6207 |
-
basic_ifstream<charT, traits>& y);
|
| 6208 |
```
|
| 6209 |
|
| 6210 |
*Effects:* Equivalent to: `x.swap(y)`.
|
| 6211 |
|
| 6212 |
#### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
|
|
@@ -6249,10 +7301,12 @@ void close();
|
|
| 6249 |
pointer, calls `setstate(failbit)` (which may throw
|
| 6250 |
`ios_base::failure`) [[iostate.flags]].
|
| 6251 |
|
| 6252 |
### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
|
| 6253 |
|
|
|
|
|
|
|
| 6254 |
``` cpp
|
| 6255 |
namespace std {
|
| 6256 |
template<class charT, class traits = char_traits<charT>>
|
| 6257 |
class basic_ofstream : public basic_ostream<charT, traits> {
|
| 6258 |
public:
|
|
@@ -6268,18 +7322,19 @@ namespace std {
|
|
| 6268 |
ios_base::openmode mode = ios_base::out);
|
| 6269 |
explicit basic_ofstream(const filesystem::path::value_type* s, // wide systems only; see [fstream.syn]
|
| 6270 |
ios_base::openmode mode = ios_base::out);
|
| 6271 |
explicit basic_ofstream(const string& s,
|
| 6272 |
ios_base::openmode mode = ios_base::out);
|
| 6273 |
-
|
| 6274 |
-
|
| 6275 |
basic_ofstream(const basic_ofstream&) = delete;
|
| 6276 |
basic_ofstream(basic_ofstream&& rhs);
|
| 6277 |
|
| 6278 |
-
// [ofstream.assign], assign and swap
|
| 6279 |
basic_ofstream& operator=(const basic_ofstream&) = delete;
|
| 6280 |
basic_ofstream& operator=(basic_ofstream&& rhs);
|
|
|
|
|
|
|
| 6281 |
void swap(basic_ofstream& rhs);
|
| 6282 |
|
| 6283 |
// [ofstream.members], members
|
| 6284 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6285 |
|
|
@@ -6288,17 +7343,14 @@ namespace std {
|
|
| 6288 |
void open(const filesystem::path::value_type* s,
|
| 6289 |
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 6290 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
| 6291 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
|
| 6292 |
void close();
|
|
|
|
| 6293 |
private:
|
| 6294 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 6295 |
};
|
| 6296 |
-
|
| 6297 |
-
template<class charT, class traits>
|
| 6298 |
-
void swap(basic_ofstream<charT, traits>& x,
|
| 6299 |
-
basic_ofstream<charT, traits>& y);
|
| 6300 |
}
|
| 6301 |
```
|
| 6302 |
|
| 6303 |
The class `basic_ofstream<charT, traits>` supports writing to named
|
| 6304 |
files. It uses a `basic_filebuf<{}charT, traits>` object to control the
|
|
@@ -6331,38 +7383,44 @@ with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
|
|
| 6331 |
null pointer, calls `setstate(failbit)`.
|
| 6332 |
|
| 6333 |
``` cpp
|
| 6334 |
explicit basic_ofstream(const string& s,
|
| 6335 |
ios_base::openmode mode = ios_base::out);
|
| 6336 |
-
explicit basic_ofstream(const filesystem::path& s,
|
| 6337 |
-
ios_base::openmode mode = ios_base::out);
|
| 6338 |
```
|
| 6339 |
|
| 6340 |
*Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
|
| 6341 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6342 |
``` cpp
|
| 6343 |
basic_ofstream(basic_ofstream&& rhs);
|
| 6344 |
```
|
| 6345 |
|
| 6346 |
*Effects:* Move constructs the base class, and the contained
|
| 6347 |
`basic_filebuf`. Then calls
|
| 6348 |
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 6349 |
contained `basic_filebuf`.
|
| 6350 |
|
| 6351 |
-
####
|
| 6352 |
|
| 6353 |
``` cpp
|
| 6354 |
void swap(basic_ofstream& rhs);
|
| 6355 |
```
|
| 6356 |
|
| 6357 |
*Effects:* Exchanges the state of `*this` and `rhs` by calling
|
| 6358 |
`basic_ostream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
|
| 6359 |
|
| 6360 |
``` cpp
|
| 6361 |
template<class charT, class traits>
|
| 6362 |
-
void swap(basic_ofstream<charT, traits>& x,
|
| 6363 |
-
basic_ofstream<charT, traits>& y);
|
| 6364 |
```
|
| 6365 |
|
| 6366 |
*Effects:* Equivalent to: `x.swap(y)`.
|
| 6367 |
|
| 6368 |
#### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
|
|
@@ -6405,10 +7463,12 @@ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
|
|
| 6405 |
|
| 6406 |
*Effects:* Calls `open(s.c_str(), mode)`.
|
| 6407 |
|
| 6408 |
### Class template `basic_fstream` <a id="fstream">[[fstream]]</a>
|
| 6409 |
|
|
|
|
|
|
|
| 6410 |
``` cpp
|
| 6411 |
namespace std {
|
| 6412 |
template<class charT, class traits = char_traits<charT>>
|
| 6413 |
class basic_fstream : public basic_iostream<charT, traits> {
|
| 6414 |
public:
|
|
@@ -6427,19 +7487,19 @@ namespace std {
|
|
| 6427 |
const filesystem::path::value_type* s,
|
| 6428 |
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 6429 |
explicit basic_fstream(
|
| 6430 |
const string& s,
|
| 6431 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6432 |
-
|
| 6433 |
-
const
|
| 6434 |
-
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6435 |
basic_fstream(const basic_fstream&) = delete;
|
| 6436 |
basic_fstream(basic_fstream&& rhs);
|
| 6437 |
|
| 6438 |
-
// [fstream.assign], assign and swap
|
| 6439 |
basic_fstream& operator=(const basic_fstream&) = delete;
|
| 6440 |
basic_fstream& operator=(basic_fstream&& rhs);
|
|
|
|
|
|
|
| 6441 |
void swap(basic_fstream& rhs);
|
| 6442 |
|
| 6443 |
// [fstream.members], members
|
| 6444 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6445 |
bool is_open() const;
|
|
@@ -6458,14 +7518,10 @@ namespace std {
|
|
| 6458 |
void close();
|
| 6459 |
|
| 6460 |
private:
|
| 6461 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 6462 |
};
|
| 6463 |
-
|
| 6464 |
-
template<class charT, class traits>
|
| 6465 |
-
void swap(basic_fstream<charT, traits>& x,
|
| 6466 |
-
basic_fstream<charT, traits>& y);
|
| 6467 |
}
|
| 6468 |
```
|
| 6469 |
|
| 6470 |
The class template `basic_fstream<charT, traits>` supports reading and
|
| 6471 |
writing from named files. It uses a `basic_filebuf<charT, traits>`
|
|
@@ -6501,27 +7557,33 @@ explicit basic_fstream(
|
|
| 6501 |
|
| 6502 |
``` cpp
|
| 6503 |
explicit basic_fstream(
|
| 6504 |
const string& s,
|
| 6505 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6506 |
-
explicit basic_fstream(
|
| 6507 |
-
const filesystem::path& s,
|
| 6508 |
-
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6509 |
```
|
| 6510 |
|
| 6511 |
*Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
|
| 6512 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6513 |
``` cpp
|
| 6514 |
basic_fstream(basic_fstream&& rhs);
|
| 6515 |
```
|
| 6516 |
|
| 6517 |
*Effects:* Move constructs the base class, and the contained
|
| 6518 |
`basic_filebuf`. Then calls
|
| 6519 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 6520 |
contained `basic_filebuf`.
|
| 6521 |
|
| 6522 |
-
####
|
| 6523 |
|
| 6524 |
``` cpp
|
| 6525 |
void swap(basic_fstream& rhs);
|
| 6526 |
```
|
| 6527 |
|
|
@@ -6592,10 +7654,15 @@ pointer, calls `setstate(failbit)` (which may throw
|
|
| 6592 |
|
| 6593 |
namespace std {
|
| 6594 |
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 6595 |
class basic_syncbuf;
|
| 6596 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6597 |
using syncbuf = basic_syncbuf<char>;
|
| 6598 |
using wsyncbuf = basic_syncbuf<wchar_t>;
|
| 6599 |
|
| 6600 |
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 6601 |
class basic_osyncstream;
|
|
@@ -6651,15 +7718,10 @@ namespace std {
|
|
| 6651 |
|
| 6652 |
private:
|
| 6653 |
streambuf_type* wrapped; // exposition only
|
| 6654 |
bool emit_on_sync{}; // exposition only
|
| 6655 |
};
|
| 6656 |
-
|
| 6657 |
-
// [syncstream.syncbuf.special], specialized algorithms
|
| 6658 |
-
template<class charT, class traits, class Allocator>
|
| 6659 |
-
void swap(basic_syncbuf<charT, traits, Allocator>&,
|
| 6660 |
-
basic_syncbuf<charT, traits, Allocator>&);
|
| 6661 |
}
|
| 6662 |
```
|
| 6663 |
|
| 6664 |
Class template `basic_syncbuf` stores character data written to it,
|
| 6665 |
known as the associated output, into internal buffers allocated using
|
|
@@ -6675,28 +7737,27 @@ wrapped stream buffer object.
|
|
| 6675 |
basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
|
| 6676 |
```
|
| 6677 |
|
| 6678 |
*Effects:* Sets `wrapped` to `obuf`.
|
| 6679 |
|
| 6680 |
-
*Remarks:* A copy of `allocator` is used to allocate memory for internal
|
| 6681 |
-
buffers holding the associated output.
|
| 6682 |
-
|
| 6683 |
-
*Throws:* Nothing unless an exception is thrown by the construction of a
|
| 6684 |
-
mutex or by memory allocation.
|
| 6685 |
-
|
| 6686 |
*Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
|
| 6687 |
are `true`.
|
| 6688 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6689 |
``` cpp
|
| 6690 |
basic_syncbuf(basic_syncbuf&& other);
|
| 6691 |
```
|
| 6692 |
|
| 6693 |
*Ensures:* The value returned by `this->get_wrapped()` is the value
|
| 6694 |
returned by `other.get_wrapped()` prior to calling this constructor.
|
| 6695 |
Output stored in `other` prior to calling this constructor will be
|
| 6696 |
-
stored in `*this` afterwards.
|
| 6697 |
-
`other.rdbuf()->pbase() == other.rdbuf()->pptr()` and
|
| 6698 |
`other.get_wrapped() == nullptr` are `true`.
|
| 6699 |
|
| 6700 |
*Remarks:* This constructor disassociates `other` from its wrapped
|
| 6701 |
stream buffer, ensuring destruction of `other` produces no output.
|
| 6702 |
|
|
@@ -6710,34 +7771,34 @@ stream buffer, ensuring destruction of `other` produces no output.
|
|
| 6710 |
destructor catches and ignores that exception.
|
| 6711 |
|
| 6712 |
#### Assignment and swap <a id="syncstream.syncbuf.assign">[[syncstream.syncbuf.assign]]</a>
|
| 6713 |
|
| 6714 |
``` cpp
|
| 6715 |
-
basic_syncbuf& operator=(basic_syncbuf&& rhs)
|
| 6716 |
```
|
| 6717 |
|
| 6718 |
*Effects:* Calls `emit()` then move assigns from `rhs`. After the move
|
| 6719 |
assignment `*this` has the observable state it would have had if it had
|
| 6720 |
been move constructed from `rhs` [[syncstream.syncbuf.cons]].
|
| 6721 |
|
| 6722 |
-
*Returns:* `*this`.
|
| 6723 |
-
|
| 6724 |
*Ensures:*
|
| 6725 |
|
| 6726 |
- `rhs.get_wrapped() == nullptr` is `true`.
|
| 6727 |
- `this->get_allocator() == rhs.get_allocator()` is `true` when
|
| 6728 |
``` cpp
|
| 6729 |
allocator_traits<Allocator>::propagate_on_container_move_assignment::value
|
| 6730 |
```
|
| 6731 |
|
| 6732 |
is `true`; otherwise, the allocator is unchanged.
|
| 6733 |
|
|
|
|
|
|
|
| 6734 |
*Remarks:* This assignment operator disassociates `rhs` from its wrapped
|
| 6735 |
stream buffer, ensuring destruction of `rhs` produces no output.
|
| 6736 |
|
| 6737 |
``` cpp
|
| 6738 |
-
void swap(basic_syncbuf& other)
|
| 6739 |
```
|
| 6740 |
|
| 6741 |
*Preconditions:* Either
|
| 6742 |
`allocator_traits<Allocator>::propagate_on_container_swap::value` is
|
| 6743 |
`true` or `this->get_allocator() == other.get_allocator()` is `true`.
|
|
@@ -6754,25 +7815,25 @@ bool emit();
|
|
| 6754 |
stream buffer `*wrapped`, so that it appears in the output stream as a
|
| 6755 |
contiguous sequence of characters. `wrapped->pubsync()` is called if and
|
| 6756 |
only if a call was made to `sync()` since the most recent call to
|
| 6757 |
`emit()`, if any.
|
| 6758 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6759 |
*Returns:* `true` if all of the following conditions hold; otherwise
|
| 6760 |
`false`:
|
| 6761 |
|
| 6762 |
- `wrapped == nullptr` is `false`.
|
| 6763 |
- All of the characters in the associated output were successfully
|
| 6764 |
transferred.
|
| 6765 |
- The call to `wrapped->pubsync()` (if any) succeeded.
|
| 6766 |
|
| 6767 |
-
*Ensures:* On success, the associated output is empty.
|
| 6768 |
-
|
| 6769 |
-
*Synchronization:* All `emit()` calls transferring characters to the
|
| 6770 |
-
same stream buffer object appear to execute in a total order consistent
|
| 6771 |
-
with the “happens before” relation [[intro.races]], where each `emit()`
|
| 6772 |
-
call synchronizes with subsequent `emit()` calls in that total order.
|
| 6773 |
-
|
| 6774 |
*Remarks:* May call member functions of `wrapped` while holding a lock
|
| 6775 |
uniquely associated with `wrapped`.
|
| 6776 |
|
| 6777 |
``` cpp
|
| 6778 |
streambuf_type* get_wrapped() const noexcept;
|
|
@@ -6811,11 +7872,11 @@ otherwise `0`.
|
|
| 6811 |
#### Specialized algorithms <a id="syncstream.syncbuf.special">[[syncstream.syncbuf.special]]</a>
|
| 6812 |
|
| 6813 |
``` cpp
|
| 6814 |
template<class charT, class traits, class Allocator>
|
| 6815 |
void swap(basic_syncbuf<charT, traits, Allocator>& a,
|
| 6816 |
-
basic_syncbuf<charT, traits, Allocator>& b)
|
| 6817 |
```
|
| 6818 |
|
| 6819 |
*Effects:* Equivalent to `a.swap(b)`.
|
| 6820 |
|
| 6821 |
### Class template `basic_osyncstream` <a id="syncstream.osyncstream">[[syncstream.osyncstream]]</a>
|
|
@@ -6847,11 +7908,11 @@ namespace std {
|
|
| 6847 |
: basic_osyncstream(os, Allocator()) {}
|
| 6848 |
basic_osyncstream(basic_osyncstream&&) noexcept;
|
| 6849 |
~basic_osyncstream();
|
| 6850 |
|
| 6851 |
// assignment
|
| 6852 |
-
basic_osyncstream& operator=(basic_osyncstream&&)
|
| 6853 |
|
| 6854 |
// [syncstream.osyncstream.members], member functions
|
| 6855 |
void emit();
|
| 6856 |
streambuf_type* get_wrapped() const noexcept;
|
| 6857 |
syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); }
|
|
@@ -6860,12 +7921,12 @@ namespace std {
|
|
| 6860 |
syncbuf_type sb; // exposition only
|
| 6861 |
};
|
| 6862 |
}
|
| 6863 |
```
|
| 6864 |
|
| 6865 |
-
`Allocator` shall meet the *Cpp17Allocator* requirements
|
| 6866 |
-
[[
|
| 6867 |
|
| 6868 |
[*Example 1*:
|
| 6869 |
|
| 6870 |
A named variable can be used within a block statement for streaming.
|
| 6871 |
|
|
@@ -6900,13 +7961,13 @@ basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
|
|
| 6900 |
```
|
| 6901 |
|
| 6902 |
*Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
|
| 6903 |
base class with `basic_ostream<charT, traits>(addressof(sb))`.
|
| 6904 |
|
| 6905 |
-
[*Note 1*: The member functions of the provided stream buffer
|
| 6906 |
-
called from `emit()` while a lock is held
|
| 6907 |
-
|
| 6908 |
|
| 6909 |
*Ensures:* `get_wrapped() == buf` is `true`.
|
| 6910 |
|
| 6911 |
``` cpp
|
| 6912 |
basic_osyncstream(basic_osyncstream&& other) noexcept;
|
|
@@ -6915,20 +7976,22 @@ basic_osyncstream(basic_osyncstream&& other) noexcept;
|
|
| 6915 |
*Effects:* Move constructs the base class and `sb` from the
|
| 6916 |
corresponding subobjects of `other`, and calls
|
| 6917 |
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
|
| 6918 |
|
| 6919 |
*Ensures:* The value returned by `get_wrapped()` is the value returned
|
| 6920 |
-
by `
|
| 6921 |
`nullptr == other.get_wrapped()` is `true`.
|
| 6922 |
|
| 6923 |
#### Member functions <a id="syncstream.osyncstream.members">[[syncstream.osyncstream.members]]</a>
|
| 6924 |
|
| 6925 |
``` cpp
|
| 6926 |
void emit();
|
| 6927 |
```
|
| 6928 |
|
| 6929 |
-
*Effects:*
|
|
|
|
|
|
|
| 6930 |
`setstate(ios_base::badbit)`.
|
| 6931 |
|
| 6932 |
[*Example 1*:
|
| 6933 |
|
| 6934 |
A flush on a `basic_osyncstream` does not flush immediately:
|
|
@@ -7038,18 +8101,20 @@ can be thought of as a raw pointer to a file. If the file pointed to
|
|
| 7038 |
does not exist, the symbolic link is said to be a “dangling” symbolic
|
| 7039 |
link. — *end note*]
|
| 7040 |
|
| 7041 |
### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
|
| 7042 |
|
|
|
|
|
|
|
| 7043 |
Conformance is specified in terms of behavior. Ideal behavior is not
|
| 7044 |
always implementable, so the conformance subclauses take that into
|
| 7045 |
account.
|
| 7046 |
|
| 7047 |
#### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
|
| 7048 |
|
| 7049 |
-
Some behavior is specified by reference to POSIX
|
| 7050 |
-
|
| 7051 |
|
| 7052 |
[*Note 1*: This constitutes an “as if” rule allowing implementations to
|
| 7053 |
call native operating system or other APIs. — *end note*]
|
| 7054 |
|
| 7055 |
Implementations should provide such behavior as it is defined by POSIX.
|
|
@@ -7088,26 +8153,20 @@ system.
|
|
| 7088 |
#### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
|
| 7089 |
|
| 7090 |
A *file system race* is the condition that occurs when multiple threads,
|
| 7091 |
processes, or computers interleave access and modification of the same
|
| 7092 |
object within a file system. Behavior is undefined if calls to functions
|
| 7093 |
-
provided by subclause [[
|
| 7094 |
-
race.
|
| 7095 |
|
| 7096 |
If the possibility of a file system race would make it unreliable for a
|
| 7097 |
program to test for a precondition before calling a function described
|
| 7098 |
herein, *Preconditions:* is not specified for the function.
|
| 7099 |
|
| 7100 |
[*Note 1*: As a design practice, preconditions are not specified when
|
| 7101 |
it is unreasonable for a program to detect them prior to calling the
|
| 7102 |
function. — *end note*]
|
| 7103 |
|
| 7104 |
-
### Normative references <a id="fs.norm.ref">[[fs.norm.ref]]</a>
|
| 7105 |
-
|
| 7106 |
-
Subclause [[filesystems]] mentions commercially available operating
|
| 7107 |
-
systems for purposes of exposition.[^41]
|
| 7108 |
-
|
| 7109 |
### Requirements <a id="fs.req">[[fs.req]]</a>
|
| 7110 |
|
| 7111 |
Throughout subclause [[filesystems]], `char`, `wchar_t`, `char8_t`,
|
| 7112 |
`char16_t`, and `char32_t` are collectively called *encoded character
|
| 7113 |
types*.
|
|
@@ -7124,17 +8183,11 @@ value type that is one of the encoded character types.
|
|
| 7124 |
character set and encoding. Since `signed char` and `unsigned char` have
|
| 7125 |
no implied character set and encoding, they are not included as
|
| 7126 |
permitted types. — *end note*]
|
| 7127 |
|
| 7128 |
Template parameters named `Allocator` shall meet the *Cpp17Allocator*
|
| 7129 |
-
requirements
|
| 7130 |
-
|
| 7131 |
-
#### Namespaces and headers <a id="fs.req.namespace">[[fs.req.namespace]]</a>
|
| 7132 |
-
|
| 7133 |
-
Unless otherwise specified, references to entities described in
|
| 7134 |
-
subclause [[filesystems]] are assumed to be qualified with
|
| 7135 |
-
`::std::filesystem::`.
|
| 7136 |
|
| 7137 |
### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
|
| 7138 |
|
| 7139 |
``` cpp
|
| 7140 |
#include <compare> // see [compare.syn]
|
|
@@ -7156,18 +8209,18 @@ namespace std::filesystem {
|
|
| 7156 |
// [fs.class.directory.iterator], directory iterators
|
| 7157 |
class directory_iterator;
|
| 7158 |
|
| 7159 |
// [fs.dir.itr.nonmembers], range access for directory iterators
|
| 7160 |
directory_iterator begin(directory_iterator iter) noexcept;
|
| 7161 |
-
directory_iterator end(
|
| 7162 |
|
| 7163 |
// [fs.class.rec.dir.itr], recursive directory iterators
|
| 7164 |
class recursive_directory_iterator;
|
| 7165 |
|
| 7166 |
// [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
|
| 7167 |
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 7168 |
-
recursive_directory_iterator end(
|
| 7169 |
|
| 7170 |
// [fs.class.file.status], file status
|
| 7171 |
class file_status;
|
| 7172 |
|
| 7173 |
struct space_info {
|
|
@@ -7333,10 +8386,28 @@ namespace std::filesystem {
|
|
| 7333 |
path temp_directory_path(error_code& ec);
|
| 7334 |
|
| 7335 |
path weakly_canonical(const path& p);
|
| 7336 |
path weakly_canonical(const path& p, error_code& ec);
|
| 7337 |
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7338 |
```
|
| 7339 |
|
| 7340 |
Implementations should ensure that the resolution and range of
|
| 7341 |
`file_time_type` reflect the operating system dependent resolution and
|
| 7342 |
range of file time values.
|
|
@@ -7387,10 +8458,12 @@ follows, unless otherwise specified:
|
|
| 7387 |
appropriate for the specific operating system dependent error.
|
| 7388 |
Otherwise, `clear()` is called on the `error_code&` argument.
|
| 7389 |
|
| 7390 |
### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
|
| 7391 |
|
|
|
|
|
|
|
| 7392 |
An object of class `path` represents a path and contains a pathname.
|
| 7393 |
Such an object is concerned only with the lexical and syntactic aspects
|
| 7394 |
of a path. The path does not necessarily exist in external storage, and
|
| 7395 |
the pathname is not necessarily valid for the current operating system
|
| 7396 |
or for a particular file system.
|
|
@@ -7412,22 +8485,22 @@ elements of a path that determine if it is absolute are operating system
|
|
| 7412 |
dependent. A *relative path* is a path that is not absolute, and as
|
| 7413 |
such, only unambiguously identifies the location of a file when resolved
|
| 7414 |
relative to an implied starting location. The elements of a path that
|
| 7415 |
determine if it is relative are operating system dependent.
|
| 7416 |
|
| 7417 |
-
[*Note 2*: Pathnames “.”
|
| 7418 |
|
| 7419 |
A *pathname* is a character string that represents the name of a path.
|
| 7420 |
Pathnames are formatted according to the generic pathname format grammar
|
| 7421 |
[[fs.path.generic]] or according to an operating system dependent
|
| 7422 |
*native pathname format* accepted by the host operating system.
|
| 7423 |
|
| 7424 |
*Pathname resolution* is the operating system dependent mechanism for
|
| 7425 |
resolving a pathname to a particular file in a file hierarchy. There may
|
| 7426 |
be multiple pathnames that resolve to the same file.
|
| 7427 |
|
| 7428 |
-
[*Example 1*: POSIX specifies the mechanism in section 4.
|
| 7429 |
resolution. — *end example*]
|
| 7430 |
|
| 7431 |
``` cpp
|
| 7432 |
namespace std::filesystem {
|
| 7433 |
class path {
|
|
@@ -7645,13 +8718,13 @@ consisting solely of one and two period characters respectively, have
|
|
| 7645 |
special meaning. The following characteristics of filenames are
|
| 7646 |
operating system dependent:
|
| 7647 |
|
| 7648 |
- The permitted characters. \[*Example 1*: Some operating systems
|
| 7649 |
prohibit the ASCII control characters (0x00 – 0x1F) in
|
| 7650 |
-
filenames. — *end example*] \[*Note 1*:
|
| 7651 |
-
|
| 7652 |
-
Character Set:
|
| 7653 |
`A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
|
| 7654 |
`a b c d e f g h i j k l m n o p q r s t u v w x y z`
|
| 7655 |
`0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
|
| 7656 |
- The maximum permitted length.
|
| 7657 |
- Filenames that are not permitted.
|
|
@@ -7676,11 +8749,11 @@ A *root-name* identifies the starting location for pathname resolution
|
|
| 7676 |
required.
|
| 7677 |
|
| 7678 |
[*Note 2*: Many operating systems define a name beginning with two
|
| 7679 |
*directory-separator* characters as a *root-name* that identifies
|
| 7680 |
network or other resource locations. Some operating systems define a
|
| 7681 |
-
single letter followed by a colon as a drive specifier
|
| 7682 |
identifying a specific device such as a disk drive. — *end note*]
|
| 7683 |
|
| 7684 |
If a *root-name* is otherwise ambiguous, the possibility with the
|
| 7685 |
longest sequence of characters is chosen.
|
| 7686 |
|
|
@@ -7692,11 +8765,11 @@ longest sequence of characters is chosen.
|
|
| 7692 |
|
| 7693 |
1. If the path is empty, stop.
|
| 7694 |
2. Replace each slash character in the *root-name* with a
|
| 7695 |
*preferred-separator*.
|
| 7696 |
3. Replace each *directory-separator* with a *preferred-separator*.
|
| 7697 |
-
\[*Note 4*: The generic pathname grammar
|
| 7698 |
*directory-separator* as one or more slashes and
|
| 7699 |
*preferred-separator*s. — *end note*]
|
| 7700 |
4. Remove each dot filename and any immediately following
|
| 7701 |
*directory-separator*.
|
| 7702 |
5. As long as any appear, remove a non-dot-dot filename immediately
|
|
@@ -7736,11 +8809,11 @@ path using either a pathname in the generic format [[fs.path.generic]]
|
|
| 7736 |
or a pathname in the native format [[fs.class.path]]. Such an argument
|
| 7737 |
is taken to be in the generic format if and only if it matches the
|
| 7738 |
generic format and is not acceptable to the operating system as a native
|
| 7739 |
path.
|
| 7740 |
|
| 7741 |
-
[*Note 2*: Some operating systems
|
| 7742 |
distinguish between native format and generic format arguments. This is
|
| 7743 |
by design as it simplifies use for operating systems that do not require
|
| 7744 |
disambiguation. An implementation for an operating system where
|
| 7745 |
disambiguation is required is permitted to distinguish between the
|
| 7746 |
formats. — *end note*]
|
|
@@ -7759,11 +8832,11 @@ differently from paths for directories, the path shall be treated as a
|
|
| 7759 |
directory path if its last element is a *directory-separator*, otherwise
|
| 7760 |
it shall be treated as a path to a regular file.
|
| 7761 |
|
| 7762 |
[*Note 4*: A path stores a native format pathname
|
| 7763 |
[[fs.path.native.obs]] and acts as if it also stores a generic format
|
| 7764 |
-
pathname, related as given below. The implementation
|
| 7765 |
generic format pathname based on the native format pathname (and
|
| 7766 |
possibly other information) when requested. — *end note*]
|
| 7767 |
|
| 7768 |
When a path is constructed from or is assigned a single representation
|
| 7769 |
separate from any path, the other representation is selected by the
|
|
@@ -7781,11 +8854,11 @@ the result of converting *p*. — *end note*]
|
|
| 7781 |
|
| 7782 |
The *native encoding* of an ordinary character string is the operating
|
| 7783 |
system dependent current encoding for pathnames [[fs.class.path]]. The
|
| 7784 |
*native encoding* for wide character strings is the
|
| 7785 |
implementation-defined execution wide-character set encoding
|
| 7786 |
-
[[
|
| 7787 |
|
| 7788 |
For member function arguments that take character sequences representing
|
| 7789 |
paths and for member functions returning strings, value type and
|
| 7790 |
encoding conversion is performed if the value type of the argument or
|
| 7791 |
return value differs from `path::value_type`. For the argument or return
|
|
@@ -7799,12 +8872,12 @@ determined by its value type:
|
|
| 7799 |
return values is performed. For Windows-based operating systems, the
|
| 7800 |
native ordinary encoding is determined by calling a Windows API
|
| 7801 |
function. — *end note*] \[*Note 7*: This results in behavior
|
| 7802 |
identical to other C and C++ standard library functions that perform
|
| 7803 |
file operations using ordinary character strings to identify paths.
|
| 7804 |
-
Changing this behavior would be surprising and
|
| 7805 |
-
prone. — *end note*]
|
| 7806 |
- `wchar_t`: The encoding is the native wide encoding. The method of
|
| 7807 |
conversion is unspecified. \[*Note 8*: For Windows-based operating
|
| 7808 |
systems `path::value_type` is `wchar_t` so no conversion from
|
| 7809 |
`wchar_t` value type arguments or to `wchar_t` value type return
|
| 7810 |
values is performed. — *end note*]
|
|
@@ -7848,11 +8921,11 @@ participate in overload resolution unless `Source` denotes a type other
|
|
| 7848 |
than `path`, and either
|
| 7849 |
|
| 7850 |
- `Source` is a specialization of `basic_string` or `basic_string_view`,
|
| 7851 |
or
|
| 7852 |
- the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
|
| 7853 |
-
valid and denotes a possibly
|
| 7854 |
[[temp.deduct]].
|
| 7855 |
|
| 7856 |
[*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
|
| 7857 |
above and their encodings convert to `path::value_type` and its
|
| 7858 |
encoding. — *end note*]
|
|
@@ -8087,12 +9160,12 @@ template<class Source>
|
|
| 8087 |
```
|
| 8088 |
|
| 8089 |
*Effects:* Appends `path(x).native()` to the pathname in the native
|
| 8090 |
format.
|
| 8091 |
|
| 8092 |
-
[*Note 2*: This directly manipulates the value of `native()`
|
| 8093 |
-
not
|
| 8094 |
|
| 8095 |
*Returns:* `*this`.
|
| 8096 |
|
| 8097 |
``` cpp
|
| 8098 |
path& operator+=(value_type x);
|
|
@@ -8241,14 +9314,10 @@ const value_type* c_str() const noexcept;
|
|
| 8241 |
operator string_type() const;
|
| 8242 |
```
|
| 8243 |
|
| 8244 |
*Returns:* `native()`.
|
| 8245 |
|
| 8246 |
-
[*Note 3*: Conversion to `string_type` is provided so that an object of
|
| 8247 |
-
class `path` can be given as an argument to existing standard library
|
| 8248 |
-
file stream constructors and open functions. — *end note*]
|
| 8249 |
-
|
| 8250 |
``` cpp
|
| 8251 |
template<class EcharT, class traits = char_traits<EcharT>,
|
| 8252 |
class Allocator = allocator<EcharT>>
|
| 8253 |
basic_string<EcharT, traits, Allocator>
|
| 8254 |
string(const Allocator& a = Allocator()) const;
|
|
@@ -8448,17 +9517,17 @@ path(".bar").extension(); // yields "" and stem() is ".bar"
|
|
| 8448 |
path("..bar").extension(); // yields ".bar" and stem() is "."
|
| 8449 |
```
|
| 8450 |
|
| 8451 |
— *end example*]
|
| 8452 |
|
| 8453 |
-
[*Note
|
| 8454 |
possible to distinguish between no extension and an empty
|
| 8455 |
extension. — *end note*]
|
| 8456 |
|
| 8457 |
-
[*Note
|
| 8458 |
-
|
| 8459 |
-
the generic format pathnames are the same. — *end note*]
|
| 8460 |
|
| 8461 |
##### Query <a id="fs.path.query">[[fs.path.query]]</a>
|
| 8462 |
|
| 8463 |
``` cpp
|
| 8464 |
[[nodiscard]] bool empty() const noexcept;
|
|
@@ -8557,25 +9626,21 @@ slashes, but that does not affect `path` equality.
|
|
| 8557 |
|
| 8558 |
``` cpp
|
| 8559 |
path lexically_relative(const path& base) const;
|
| 8560 |
```
|
| 8561 |
|
| 8562 |
-
*Returns:* `*this` made relative to `base`. Does not
|
| 8563 |
-
resolve [[fs.class.path]] symlinks. Does not first
|
| 8564 |
-
normalize [[fs.path.generic]] `*this` or `base`.
|
| 8565 |
-
|
| 8566 |
*Effects:* If:
|
| 8567 |
|
| 8568 |
- `root_name() != base.root_name()` is `true`, or
|
| 8569 |
- `is_absolute() != base.is_absolute()` is `true`, or
|
| 8570 |
- `!has_root_directory() && base.has_root_directory()` is `true`, or
|
| 8571 |
- any *filename* in `relative_path()` or `base.relative_path()` can be
|
| 8572 |
interpreted as a *root-name*,
|
| 8573 |
|
| 8574 |
returns `path()`.
|
| 8575 |
|
| 8576 |
-
[*Note
|
| 8577 |
*relative-path* is acceptable as a *root-name*. — *end note*]
|
| 8578 |
|
| 8579 |
Determines the first mismatched element of `*this` and `base` as if by:
|
| 8580 |
|
| 8581 |
``` cpp
|
|
@@ -8593,10 +9658,14 @@ Then,
|
|
| 8593 |
- returns an object of class `path` that is default-constructed,
|
| 8594 |
followed by
|
| 8595 |
- application of `operator/=(path(".."))` `n` times, and then
|
| 8596 |
- application of `operator/=` for each element in \[`a`, `end()`).
|
| 8597 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8598 |
[*Example 11*:
|
| 8599 |
|
| 8600 |
``` cpp
|
| 8601 |
assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
|
| 8602 |
assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
|
|
@@ -8610,28 +9679,28 @@ The above assertions will succeed. On Windows, the returned path’s
|
|
| 8610 |
*directory-separator* characters will be backslashes rather than
|
| 8611 |
slashes, but that does not affect `path` equality.
|
| 8612 |
|
| 8613 |
— *end example*]
|
| 8614 |
|
| 8615 |
-
[*Note
|
| 8616 |
operational function `relative()`. — *end note*]
|
| 8617 |
|
| 8618 |
-
[*Note
|
| 8619 |
consistent matching of elements, apply `lexically_normal()` to `*this`,
|
| 8620 |
`base`, or both. — *end note*]
|
| 8621 |
|
| 8622 |
``` cpp
|
| 8623 |
path lexically_proximate(const path& base) const;
|
| 8624 |
```
|
| 8625 |
|
| 8626 |
*Returns:* If the value of `lexically_relative(base)` is not an empty
|
| 8627 |
path, return it. Otherwise return `*this`.
|
| 8628 |
|
| 8629 |
-
[*Note
|
| 8630 |
operational function `proximate()`. — *end note*]
|
| 8631 |
|
| 8632 |
-
[*Note
|
| 8633 |
consistent matching of elements, apply `lexically_normal()` to `*this`,
|
| 8634 |
`base`, or both. — *end note*]
|
| 8635 |
|
| 8636 |
#### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
|
| 8637 |
|
|
@@ -8736,14 +9805,10 @@ Path equality and path equivalence have different semantics.
|
|
| 8736 |
- Equivalence is determined by the `equivalent()` non-member function,
|
| 8737 |
which determines if two paths resolve [[fs.class.path]] to the same
|
| 8738 |
file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
|
| 8739 |
`true` when both paths resolve to the same file. — *end example*]
|
| 8740 |
|
| 8741 |
-
Programmers wishing to determine if two paths are “the same” must decide
|
| 8742 |
-
if “the same” means “the same representation” or “resolve to the same
|
| 8743 |
-
actual file”, and choose the appropriate function accordingly.
|
| 8744 |
-
|
| 8745 |
— *end note*]
|
| 8746 |
|
| 8747 |
``` cpp
|
| 8748 |
friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
|
| 8749 |
```
|
|
@@ -8754,12 +9819,24 @@ friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
|
|
| 8754 |
friend path operator/(const path& lhs, const path& rhs);
|
| 8755 |
```
|
| 8756 |
|
| 8757 |
*Effects:* Equivalent to: `return path(lhs) /= rhs;`
|
| 8758 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8759 |
### Class `filesystem_error` <a id="fs.class.filesystem.error">[[fs.class.filesystem.error]]</a>
|
| 8760 |
|
|
|
|
|
|
|
| 8761 |
``` cpp
|
| 8762 |
namespace std::filesystem {
|
| 8763 |
class filesystem_error : public system_error {
|
| 8764 |
public:
|
| 8765 |
filesystem_error(const string& what_arg, error_code ec);
|
|
@@ -8845,22 +9922,41 @@ and `path2` in the native format in the returned string.
|
|
| 8845 |
#### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
|
| 8846 |
|
| 8847 |
This enum specifies constants used to identify the format of the
|
| 8848 |
character sequence, with the meanings listed in [[fs.enum.path.format]].
|
| 8849 |
|
| 8850 |
-
|
| 8851 |
-
|
| 8852 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8853 |
|
| 8854 |
#### Enum class `file_type` <a id="fs.enum.file.type">[[fs.enum.file.type]]</a>
|
| 8855 |
|
| 8856 |
This enum class specifies constants used to identify file types, with
|
| 8857 |
the meanings listed in [[fs.enum.file.type]]. The values of the
|
| 8858 |
constants are distinct.
|
| 8859 |
|
| 8860 |
-
|
| 8861 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8862 |
|
| 8863 |
#### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
|
| 8864 |
|
| 8865 |
The `enum class` type `copy_options` is a bitmask type [[bitmask.types]]
|
| 8866 |
that specifies bitmask constants used to control the semantics of copy
|
|
@@ -8871,16 +9967,16 @@ exposition; implementations shall provide only a single definition.
|
|
| 8871 |
Every other constant in the table represents a distinct bitmask element.
|
| 8872 |
|
| 8873 |
**Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
|
| 8874 |
|
| 8875 |
| Constant | Meaning |
|
| 8876 |
-
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------
|
| 8877 |
| `none` | (Default) Error; file already exists. |
|
| 8878 |
| `skip_existing` | Do not overwrite existing file, do not report an error. |
|
| 8879 |
| `overwrite_existing` | Overwrite the existing file. |
|
| 8880 |
-
| `update_existing` | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for
|
| 8881 |
-
| `recursive` | Recursively copy
|
| 8882 |
| `copy_symlinks` | Copy symbolic links as symbolic links rather than copying the files that they point to. |
|
| 8883 |
| `skip_symlinks` | Ignore symbolic links. \ohdrx{2}{Option group controlling `copy` function effects for choosing the form of copying} |
|
| 8884 |
| `directories_only` | Copy directory structure only, do not copy non-directory files. |
|
| 8885 |
| `create_symlinks` | Make symbolic links instead of copies of files. The source path shall be an absolute path unless the destination path is in the current directory. |
|
| 8886 |
| `create_hard_links` | Make hard links instead of copies of files. |
|
|
@@ -8929,12 +10025,12 @@ permissions operations, with the meanings listed in
|
|
| 8929 |
**Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
|
| 8930 |
|
| 8931 |
| Name | Meaning |
|
| 8932 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 8933 |
| `replace` | `permissions` shall replace the file's permission bits with `perm` |
|
| 8934 |
-
| `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{
|
| 8935 |
-
| `remove` | `permissions` shall replace the file's permission bits with the bitwise \logop{
|
| 8936 |
| `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
|
| 8937 |
|
| 8938 |
|
| 8939 |
#### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
|
| 8940 |
|
|
@@ -8953,10 +10049,12 @@ every other constant in the table represents a distinct bitmask element.
|
|
| 8953 |
| `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
|
| 8954 |
|
| 8955 |
|
| 8956 |
### Class `file_status` <a id="fs.class.file.status">[[fs.class.file.status]]</a>
|
| 8957 |
|
|
|
|
|
|
|
| 8958 |
``` cpp
|
| 8959 |
namespace std::filesystem {
|
| 8960 |
class file_status {
|
| 8961 |
public:
|
| 8962 |
// [fs.file.status.cons], constructors and destructor
|
|
@@ -9025,10 +10123,12 @@ void permissions(perms prms) noexcept;
|
|
| 9025 |
|
| 9026 |
*Ensures:* `permissions() == prms`.
|
| 9027 |
|
| 9028 |
### Class `directory_entry` <a id="fs.class.directory.entry">[[fs.class.directory.entry]]</a>
|
| 9029 |
|
|
|
|
|
|
|
| 9030 |
``` cpp
|
| 9031 |
namespace std::filesystem {
|
| 9032 |
class directory_entry {
|
| 9033 |
public:
|
| 9034 |
// [fs.dir.entry.cons], constructors and destructor
|
|
@@ -9084,10 +10184,15 @@ namespace std::filesystem {
|
|
| 9084 |
file_status symlink_status(error_code& ec) const noexcept;
|
| 9085 |
|
| 9086 |
bool operator==(const directory_entry& rhs) const noexcept;
|
| 9087 |
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
|
| 9088 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9089 |
private:
|
| 9090 |
filesystem::path pathobject; // exposition only
|
| 9091 |
friend class directory_iterator; // exposition only
|
| 9092 |
};
|
| 9093 |
}
|
|
@@ -9190,13 +10295,12 @@ unspecified.
|
|
| 9190 |
|
| 9191 |
*Throws:* As specified in [[fs.err.report]].
|
| 9192 |
|
| 9193 |
[*Note 1*: Implementations of `directory_iterator`
|
| 9194 |
[[fs.class.directory.iterator]] are prohibited from directly or
|
| 9195 |
-
indirectly calling the `refresh` function
|
| 9196 |
-
|
| 9197 |
-
unnecessary file system accesses. — *end note*]
|
| 9198 |
|
| 9199 |
#### Observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
|
| 9200 |
|
| 9201 |
Unqualified function names in the *Returns:* elements of the
|
| 9202 |
`directory_entry` observers described below refer to members of the
|
|
@@ -9361,18 +10465,30 @@ bool operator==(const directory_entry& rhs) const noexcept;
|
|
| 9361 |
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
|
| 9362 |
```
|
| 9363 |
|
| 9364 |
*Returns:* `pathobject <=> rhs.pathobject`.
|
| 9365 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9366 |
### Class `directory_iterator` <a id="fs.class.directory.iterator">[[fs.class.directory.iterator]]</a>
|
| 9367 |
|
|
|
|
|
|
|
| 9368 |
An object of type `directory_iterator` provides an iterator for a
|
| 9369 |
sequence of `directory_entry` elements representing the path and any
|
| 9370 |
cached attribute values [[fs.class.directory.entry]] for each file in a
|
| 9371 |
directory or in an *implementation-defined* directory-like file type.
|
| 9372 |
|
| 9373 |
-
[*Note 1*: For iteration into
|
| 9374 |
`recursive_directory_iterator` [[fs.class.rec.dir.itr]]. — *end note*]
|
| 9375 |
|
| 9376 |
``` cpp
|
| 9377 |
namespace std::filesystem {
|
| 9378 |
class directory_iterator {
|
|
@@ -9400,10 +10516,14 @@ namespace std::filesystem {
|
|
| 9400 |
const directory_entry& operator*() const;
|
| 9401 |
const directory_entry* operator->() const;
|
| 9402 |
directory_iterator& operator++();
|
| 9403 |
directory_iterator& increment(error_code& ec);
|
| 9404 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9405 |
// other members as required by [input.iterators], input iterators
|
| 9406 |
};
|
| 9407 |
}
|
| 9408 |
```
|
| 9409 |
|
|
@@ -9422,12 +10542,12 @@ Two end iterators are always equal. An end iterator shall not be equal
|
|
| 9422 |
to a non-end iterator.
|
| 9423 |
|
| 9424 |
The result of calling the `path()` member of the `directory_entry`
|
| 9425 |
object obtained by dereferencing a `directory_iterator` is a reference
|
| 9426 |
to a `path` object composed of the directory argument from which the
|
| 9427 |
-
iterator was constructed with filename of the directory entry
|
| 9428 |
-
as if by `operator/=`.
|
| 9429 |
|
| 9430 |
Directory iteration shall not yield directory entries for the current
|
| 9431 |
(dot) and parent (dot-dot) directories.
|
| 9432 |
|
| 9433 |
The order of directory entries obtained by dereferencing successive
|
|
@@ -9442,21 +10562,21 @@ call any `directory_entry` `refresh` function.
|
|
| 9442 |
[*Note 2*: The exact mechanism for storing cached attribute values is
|
| 9443 |
not exposed to users. For exposition, class `directory_iterator` is
|
| 9444 |
shown in [[fs.class.directory.entry]] as a friend of class
|
| 9445 |
`directory_entry`. — *end note*]
|
| 9446 |
|
| 9447 |
-
[*Note 3*:
|
| 9448 |
-
|
| 9449 |
-
|
| 9450 |
-
|
| 9451 |
-
|
| 9452 |
|
| 9453 |
[*Note 4*: If a file is removed from or added to a directory after the
|
| 9454 |
construction of a `directory_iterator` for the directory, it is
|
| 9455 |
unspecified whether or not subsequently incrementing the iterator will
|
| 9456 |
ever result in an iterator referencing the removed or added directory
|
| 9457 |
-
entry. See POSIX `
|
| 9458 |
|
| 9459 |
#### Members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
|
| 9460 |
|
| 9461 |
``` cpp
|
| 9462 |
directory_iterator() noexcept;
|
|
@@ -9530,21 +10650,23 @@ directory_iterator begin(directory_iterator iter) noexcept;
|
|
| 9530 |
```
|
| 9531 |
|
| 9532 |
*Returns:* `iter`.
|
| 9533 |
|
| 9534 |
``` cpp
|
| 9535 |
-
directory_iterator end(
|
| 9536 |
```
|
| 9537 |
|
| 9538 |
*Returns:* `directory_iterator()`.
|
| 9539 |
|
| 9540 |
### Class `recursive_directory_iterator` <a id="fs.class.rec.dir.itr">[[fs.class.rec.dir.itr]]</a>
|
| 9541 |
|
|
|
|
|
|
|
| 9542 |
An object of type `recursive_directory_iterator` provides an iterator
|
| 9543 |
for a sequence of `directory_entry` elements representing the files in a
|
| 9544 |
directory or in an *implementation-defined* directory-like file type,
|
| 9545 |
-
and its
|
| 9546 |
|
| 9547 |
``` cpp
|
| 9548 |
namespace std::filesystem {
|
| 9549 |
class recursive_directory_iterator {
|
| 9550 |
public:
|
|
@@ -9584,10 +10706,14 @@ namespace std::filesystem {
|
|
| 9584 |
|
| 9585 |
void pop();
|
| 9586 |
void pop(error_code& ec);
|
| 9587 |
void disable_recursion_pending();
|
| 9588 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9589 |
// other members as required by [input.iterators], input iterators
|
| 9590 |
};
|
| 9591 |
}
|
| 9592 |
```
|
| 9593 |
|
|
@@ -9597,11 +10723,12 @@ results in undefined behavior.
|
|
| 9597 |
|
| 9598 |
The behavior of a `recursive_directory_iterator` is the same as a
|
| 9599 |
`directory_iterator` unless otherwise specified.
|
| 9600 |
|
| 9601 |
[*Note 1*: If the directory structure being iterated over contains
|
| 9602 |
-
cycles then
|
|
|
|
| 9603 |
|
| 9604 |
#### Members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
|
| 9605 |
|
| 9606 |
``` cpp
|
| 9607 |
recursive_directory_iterator() noexcept;
|
|
@@ -9632,13 +10759,13 @@ error.
|
|
| 9632 |
`directory_options` argument, otherwise
|
| 9633 |
`options() == directory_options::none`.
|
| 9634 |
|
| 9635 |
*Throws:* As specified in [[fs.err.report]].
|
| 9636 |
|
| 9637 |
-
[*Note 1*:
|
| 9638 |
-
`recursive_directory_iterator("
|
| 9639 |
-
|
| 9640 |
|
| 9641 |
[*Note 2*: By default, `recursive_directory_iterator` does not follow
|
| 9642 |
directory symlinks. To follow directory symlinks, specify `options` as
|
| 9643 |
`directory_options::follow_directory_symlink`. — *end note*]
|
| 9644 |
|
|
@@ -9775,40 +10902,42 @@ void disable_recursion_pending();
|
|
| 9775 |
recursion into a directory. — *end note*]
|
| 9776 |
|
| 9777 |
#### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
|
| 9778 |
|
| 9779 |
These functions enable use of `recursive_directory_iterator` with
|
| 9780 |
-
range-based for statements.
|
| 9781 |
|
| 9782 |
``` cpp
|
| 9783 |
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 9784 |
```
|
| 9785 |
|
| 9786 |
*Returns:* `iter`.
|
| 9787 |
|
| 9788 |
``` cpp
|
| 9789 |
-
recursive_directory_iterator end(
|
| 9790 |
```
|
| 9791 |
|
| 9792 |
*Returns:* `recursive_directory_iterator()`.
|
| 9793 |
|
| 9794 |
### Filesystem operation functions <a id="fs.op.funcs">[[fs.op.funcs]]</a>
|
| 9795 |
|
|
|
|
|
|
|
| 9796 |
Filesystem operation functions query or modify files, including
|
| 9797 |
directories, in external storage.
|
| 9798 |
|
| 9799 |
[*Note 1*: Because hardware failures, network failures, file system
|
| 9800 |
races [[fs.race.behavior]], and many other kinds of errors occur
|
| 9801 |
-
frequently in file system operations,
|
| 9802 |
-
|
| 9803 |
-
|
| 9804 |
|
| 9805 |
#### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
|
| 9806 |
|
| 9807 |
``` cpp
|
| 9808 |
-
path absolute(const path& p);
|
| 9809 |
-
path absolute(const path& p, error_code& ec);
|
| 9810 |
```
|
| 9811 |
|
| 9812 |
*Effects:* Composes an absolute path referencing the same file system
|
| 9813 |
location as `p` according to the operating system [[fs.conform.os]].
|
| 9814 |
|
|
@@ -9818,12 +10947,12 @@ location as `p` according to the operating system [[fs.conform.os]].
|
|
| 9818 |
[*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
|
| 9819 |
unless an error occurs. — *end note*]
|
| 9820 |
|
| 9821 |
*Throws:* As specified in [[fs.err.report]].
|
| 9822 |
|
| 9823 |
-
[*Note 2*: To resolve symlinks
|
| 9824 |
-
|
| 9825 |
`canonical` [[fs.op.canonical]]. — *end note*]
|
| 9826 |
|
| 9827 |
[*Note 3*: Implementations are strongly encouraged to not query
|
| 9828 |
secondary storage, and not consider `!exists(p)` an
|
| 9829 |
error. — *end note*]
|
|
@@ -9834,12 +10963,12 @@ simply `current_path()/p`. For Windows-based operating systems,
|
|
| 9834 |
`GetFullPathNameW`. — *end example*]
|
| 9835 |
|
| 9836 |
#### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
|
| 9837 |
|
| 9838 |
``` cpp
|
| 9839 |
-
path canonical(const path& p);
|
| 9840 |
-
path canonical(const path& p, error_code& ec);
|
| 9841 |
```
|
| 9842 |
|
| 9843 |
*Effects:* Converts `p` to an absolute path that has no symbolic link,
|
| 9844 |
dot, or dot-dot elements in its pathname in the generic format.
|
| 9845 |
|
|
@@ -9852,24 +10981,24 @@ error occurs.
|
|
| 9852 |
*Remarks:* `!exists(p)` is an error.
|
| 9853 |
|
| 9854 |
#### Copy <a id="fs.op.copy">[[fs.op.copy]]</a>
|
| 9855 |
|
| 9856 |
``` cpp
|
| 9857 |
-
void copy(const path& from, const path& to);
|
| 9858 |
```
|
| 9859 |
|
| 9860 |
*Effects:* Equivalent to `copy(from, to, copy_options::none)`.
|
| 9861 |
|
| 9862 |
``` cpp
|
| 9863 |
-
void copy(const path& from, const path& to, error_code& ec);
|
| 9864 |
```
|
| 9865 |
|
| 9866 |
*Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
|
| 9867 |
|
| 9868 |
``` cpp
|
| 9869 |
-
void copy(const path& from, const path& to, copy_options options);
|
| 9870 |
-
void copy(const path& from, const path& to, copy_options options,
|
| 9871 |
error_code& ec);
|
| 9872 |
```
|
| 9873 |
|
| 9874 |
*Preconditions:* At most one element from each option
|
| 9875 |
group [[fs.enum.copy.opts]] is set in `options`.
|
|
@@ -10006,22 +11135,22 @@ would result in:
|
|
| 10006 |
— *end example*]
|
| 10007 |
|
| 10008 |
#### Copy file <a id="fs.op.copy.file">[[fs.op.copy.file]]</a>
|
| 10009 |
|
| 10010 |
``` cpp
|
| 10011 |
-
bool copy_file(const path& from, const path& to);
|
| 10012 |
-
bool copy_file(const path& from, const path& to, error_code& ec);
|
| 10013 |
```
|
| 10014 |
|
| 10015 |
*Returns:* `copy_file(from, to, copy_options::none)` or
|
| 10016 |
`copy_file(from, to, copy_options::none, ec)`, respectively.
|
| 10017 |
|
| 10018 |
*Throws:* As specified in [[fs.err.report]].
|
| 10019 |
|
| 10020 |
``` cpp
|
| 10021 |
-
bool copy_file(const path& from, const path& to, copy_options options);
|
| 10022 |
-
bool copy_file(const path& from, const path& to, copy_options options,
|
| 10023 |
error_code& ec);
|
| 10024 |
```
|
| 10025 |
|
| 10026 |
*Preconditions:* At most one element from each option
|
| 10027 |
group [[fs.enum.copy.opts]] is set in `options`.
|
|
@@ -10056,12 +11185,12 @@ signature with argument `ec` returns `false` if an error occurs.
|
|
| 10056 |
*Complexity:* At most one direct or indirect invocation of `status(to)`.
|
| 10057 |
|
| 10058 |
#### Copy symlink <a id="fs.op.copy.symlink">[[fs.op.copy.symlink]]</a>
|
| 10059 |
|
| 10060 |
``` cpp
|
| 10061 |
-
void copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 10062 |
-
void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 10063 |
error_code& ec) noexcept;
|
| 10064 |
```
|
| 10065 |
|
| 10066 |
*Effects:* Equivalent to
|
| 10067 |
*`function`*`(read_symlink(existing_symlink), new_symlink)` or
|
|
@@ -10072,12 +11201,12 @@ respectively, where in each case *`function`* is `create_symlink` or
|
|
| 10072 |
*Throws:* As specified in [[fs.err.report]].
|
| 10073 |
|
| 10074 |
#### Create directories <a id="fs.op.create.directories">[[fs.op.create.directories]]</a>
|
| 10075 |
|
| 10076 |
``` cpp
|
| 10077 |
-
bool create_directories(const path& p);
|
| 10078 |
-
bool create_directories(const path& p, error_code& ec);
|
| 10079 |
```
|
| 10080 |
|
| 10081 |
*Effects:* Calls `create_directory()` for each element of `p` that does
|
| 10082 |
not exist.
|
| 10083 |
|
|
@@ -10089,12 +11218,12 @@ resolves to, otherwise `false`.
|
|
| 10089 |
*Complexity:* 𝑂(n) where *n* is the number of elements of `p`.
|
| 10090 |
|
| 10091 |
#### Create directory <a id="fs.op.create.directory">[[fs.op.create.directory]]</a>
|
| 10092 |
|
| 10093 |
``` cpp
|
| 10094 |
-
bool create_directory(const path& p);
|
| 10095 |
-
bool create_directory(const path& p, error_code& ec) noexcept;
|
| 10096 |
```
|
| 10097 |
|
| 10098 |
*Effects:* Creates the directory `p` resolves to, as if by POSIX `mkdir`
|
| 10099 |
with a second argument of `static_cast<int>(perms::all)`. If `mkdir`
|
| 10100 |
fails because `p` resolves to an existing directory, no error is
|
|
@@ -10103,12 +11232,12 @@ reported. Otherwise on failure an error is reported.
|
|
| 10103 |
*Returns:* `true` if a new directory was created, otherwise `false`.
|
| 10104 |
|
| 10105 |
*Throws:* As specified in [[fs.err.report]].
|
| 10106 |
|
| 10107 |
``` cpp
|
| 10108 |
-
bool create_directory(const path& p, const path& existing_p);
|
| 10109 |
-
bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
|
| 10110 |
```
|
| 10111 |
|
| 10112 |
*Effects:* Creates the directory `p` resolves to, with attributes copied
|
| 10113 |
from directory `existing_p`. The set of attributes copied is operating
|
| 10114 |
system dependent. If `mkdir` fails because `p` resolves to an existing
|
|
@@ -10128,12 +11257,12 @@ from directory `existing_p`, otherwise `false`.
|
|
| 10128 |
*Throws:* As specified in [[fs.err.report]].
|
| 10129 |
|
| 10130 |
#### Create directory symlink <a id="fs.op.create.dir.symlk">[[fs.op.create.dir.symlk]]</a>
|
| 10131 |
|
| 10132 |
``` cpp
|
| 10133 |
-
void create_directory_symlink(const path& to, const path& new_symlink);
|
| 10134 |
-
void create_directory_symlink(const path& to, const path& new_symlink,
|
| 10135 |
error_code& ec) noexcept;
|
| 10136 |
```
|
| 10137 |
|
| 10138 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 10139 |
|
|
@@ -10141,24 +11270,24 @@ void create_directory_symlink(const path& to, const path& new_symlink,
|
|
| 10141 |
an unspecified representation of `to`.
|
| 10142 |
|
| 10143 |
*Throws:* As specified in [[fs.err.report]].
|
| 10144 |
|
| 10145 |
[*Note 1*: Some operating systems require symlink creation to identify
|
| 10146 |
-
that the link is to a directory.
|
| 10147 |
-
`create_directory_symlink()`
|
| 10148 |
-
|
| 10149 |
|
| 10150 |
[*Note 2*: Some operating systems do not support symbolic links at all
|
| 10151 |
or support them only for regular files. Some file systems (such as the
|
| 10152 |
FAT file system) do not support symbolic links regardless of the
|
| 10153 |
operating system. — *end note*]
|
| 10154 |
|
| 10155 |
#### Create hard link <a id="fs.op.create.hard.lk">[[fs.op.create.hard.lk]]</a>
|
| 10156 |
|
| 10157 |
``` cpp
|
| 10158 |
-
void create_hard_link(const path& to, const path& new_hard_link);
|
| 10159 |
-
void create_hard_link(const path& to, const path& new_hard_link,
|
| 10160 |
error_code& ec) noexcept;
|
| 10161 |
```
|
| 10162 |
|
| 10163 |
*Effects:* Establishes the postcondition, as if by POSIX `link()`.
|
| 10164 |
|
|
@@ -10176,12 +11305,12 @@ system. Some file systems limit the number of links per
|
|
| 10176 |
file. — *end note*]
|
| 10177 |
|
| 10178 |
#### Create symlink <a id="fs.op.create.symlink">[[fs.op.create.symlink]]</a>
|
| 10179 |
|
| 10180 |
``` cpp
|
| 10181 |
-
void create_symlink(const path& to, const path& new_symlink);
|
| 10182 |
-
void create_symlink(const path& to, const path& new_symlink,
|
| 10183 |
error_code& ec) noexcept;
|
| 10184 |
```
|
| 10185 |
|
| 10186 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 10187 |
|
|
@@ -10196,12 +11325,12 @@ FAT file system) do not support symbolic links regardless of the
|
|
| 10196 |
operating system. — *end note*]
|
| 10197 |
|
| 10198 |
#### Current path <a id="fs.op.current.path">[[fs.op.current.path]]</a>
|
| 10199 |
|
| 10200 |
``` cpp
|
| 10201 |
-
path current_path();
|
| 10202 |
-
path current_path(error_code& ec);
|
| 10203 |
```
|
| 10204 |
|
| 10205 |
*Returns:* The absolute path of the current working directory, whose
|
| 10206 |
pathname in the native format is obtained as if by POSIX `getcwd()`. The
|
| 10207 |
signature with argument `ec` returns `path()` if an error occurs.
|
|
@@ -10215,61 +11344,61 @@ resolution for relative paths.
|
|
| 10215 |
[*Note 1*: The `current_path()` name was chosen to emphasize that the
|
| 10216 |
returned value is a path, not just a single directory
|
| 10217 |
name. — *end note*]
|
| 10218 |
|
| 10219 |
[*Note 2*: The current path as returned by many operating systems is a
|
| 10220 |
-
dangerous global variable
|
| 10221 |
or system library functions, or by another thread. — *end note*]
|
| 10222 |
|
| 10223 |
``` cpp
|
| 10224 |
-
void current_path(const path& p);
|
| 10225 |
-
void current_path(const path& p, error_code& ec) noexcept;
|
| 10226 |
```
|
| 10227 |
|
| 10228 |
*Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
|
| 10229 |
|
| 10230 |
*Ensures:* `equivalent(p, current_path())`.
|
| 10231 |
|
| 10232 |
*Throws:* As specified in [[fs.err.report]].
|
| 10233 |
|
| 10234 |
[*Note 3*: The current path for many operating systems is a dangerous
|
| 10235 |
-
global state
|
| 10236 |
library functions, or by another thread. — *end note*]
|
| 10237 |
|
| 10238 |
#### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
|
| 10239 |
|
| 10240 |
``` cpp
|
| 10241 |
-
bool equivalent(const path& p1, const path& p2);
|
| 10242 |
-
bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 10243 |
```
|
| 10244 |
|
| 10245 |
-
*Returns:* `true`, if `p1` and `p2` resolve to the same file system
|
| 10246 |
-
entity, otherwise `false`. The signature with argument `ec` returns
|
| 10247 |
-
`false` if an error occurs.
|
| 10248 |
-
|
| 10249 |
Two paths are considered to resolve to the same file system entity if
|
| 10250 |
two candidate entities reside on the same device at the same location.
|
| 10251 |
|
| 10252 |
[*Note 1*: On POSIX platforms, this is determined as if by the values
|
| 10253 |
of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
|
| 10254 |
having equal `st_dev` values and equal `st_ino` values. — *end note*]
|
| 10255 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 10256 |
*Remarks:* `!exists(p1) || !exists(p2)` is an error.
|
| 10257 |
|
| 10258 |
-
*Throws:* As specified in [[fs.err.report]].
|
| 10259 |
-
|
| 10260 |
#### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
|
| 10261 |
|
| 10262 |
``` cpp
|
| 10263 |
-
bool exists(file_status s) noexcept;
|
| 10264 |
```
|
| 10265 |
|
| 10266 |
*Returns:* `status_known(s) && s.type() != file_type::not_found`.
|
| 10267 |
|
| 10268 |
``` cpp
|
| 10269 |
-
bool exists(const path& p);
|
| 10270 |
-
bool exists(const path& p, error_code& ec) noexcept;
|
| 10271 |
```
|
| 10272 |
|
| 10273 |
Let `s` be a `file_status`, determined as if by `status(p)` or
|
| 10274 |
`status(p, ec)`, respectively.
|
| 10275 |
|
|
@@ -10281,12 +11410,12 @@ Let `s` be a `file_status`, determined as if by `status(p)` or
|
|
| 10281 |
*Throws:* As specified in [[fs.err.report]].
|
| 10282 |
|
| 10283 |
#### File size <a id="fs.op.file.size">[[fs.op.file.size]]</a>
|
| 10284 |
|
| 10285 |
``` cpp
|
| 10286 |
-
uintmax_t file_size(const path& p);
|
| 10287 |
-
uintmax_t file_size(const path& p, error_code& ec) noexcept;
|
| 10288 |
```
|
| 10289 |
|
| 10290 |
*Effects:* If `exists(p)` is `false`, an error is
|
| 10291 |
reported [[fs.err.report]].
|
| 10292 |
|
|
@@ -10303,30 +11432,30 @@ an error occurs.
|
|
| 10303 |
*Throws:* As specified in [[fs.err.report]].
|
| 10304 |
|
| 10305 |
#### Hard link count <a id="fs.op.hard.lk.ct">[[fs.op.hard.lk.ct]]</a>
|
| 10306 |
|
| 10307 |
``` cpp
|
| 10308 |
-
uintmax_t hard_link_count(const path& p);
|
| 10309 |
-
uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
| 10310 |
```
|
| 10311 |
|
| 10312 |
*Returns:* The number of hard links for `p`. The signature with argument
|
| 10313 |
`ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
|
| 10314 |
|
| 10315 |
*Throws:* As specified in [[fs.err.report]].
|
| 10316 |
|
| 10317 |
#### Is block file <a id="fs.op.is.block.file">[[fs.op.is.block.file]]</a>
|
| 10318 |
|
| 10319 |
``` cpp
|
| 10320 |
-
bool is_block_file(file_status s) noexcept;
|
| 10321 |
```
|
| 10322 |
|
| 10323 |
*Returns:* `s.type() == file_type::block`.
|
| 10324 |
|
| 10325 |
``` cpp
|
| 10326 |
-
bool is_block_file(const path& p);
|
| 10327 |
-
bool is_block_file(const path& p, error_code& ec) noexcept;
|
| 10328 |
```
|
| 10329 |
|
| 10330 |
*Returns:* `is_block_file(status(p))` or `is_block_file(status(p, ec))`,
|
| 10331 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10332 |
error occurs.
|
|
@@ -10334,18 +11463,18 @@ error occurs.
|
|
| 10334 |
*Throws:* As specified in [[fs.err.report]].
|
| 10335 |
|
| 10336 |
#### Is character file <a id="fs.op.is.char.file">[[fs.op.is.char.file]]</a>
|
| 10337 |
|
| 10338 |
``` cpp
|
| 10339 |
-
bool is_character_file(file_status s) noexcept;
|
| 10340 |
```
|
| 10341 |
|
| 10342 |
*Returns:* `s.type() == file_type::character`.
|
| 10343 |
|
| 10344 |
``` cpp
|
| 10345 |
-
bool is_character_file(const path& p);
|
| 10346 |
-
bool is_character_file(const path& p, error_code& ec) noexcept;
|
| 10347 |
```
|
| 10348 |
|
| 10349 |
*Returns:* `is_character_file(status(p))` or
|
| 10350 |
`is_character_file(status(p, ec))`, respectively.
|
| 10351 |
The signature with argument `ec` returns `false` if an error occurs.
|
|
@@ -10353,18 +11482,18 @@ The signature with argument `ec` returns `false` if an error occurs.
|
|
| 10353 |
*Throws:* As specified in [[fs.err.report]].
|
| 10354 |
|
| 10355 |
#### Is directory <a id="fs.op.is.directory">[[fs.op.is.directory]]</a>
|
| 10356 |
|
| 10357 |
``` cpp
|
| 10358 |
-
bool is_directory(file_status s) noexcept;
|
| 10359 |
```
|
| 10360 |
|
| 10361 |
*Returns:* `s.type() == file_type::directory`.
|
| 10362 |
|
| 10363 |
``` cpp
|
| 10364 |
-
bool is_directory(const path& p);
|
| 10365 |
-
bool is_directory(const path& p, error_code& ec) noexcept;
|
| 10366 |
```
|
| 10367 |
|
| 10368 |
*Returns:* `is_directory(status(p))` or `is_directory(status(p, ec))`,
|
| 10369 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10370 |
error occurs.
|
|
@@ -10372,12 +11501,12 @@ error occurs.
|
|
| 10372 |
*Throws:* As specified in [[fs.err.report]].
|
| 10373 |
|
| 10374 |
#### Is empty <a id="fs.op.is.empty">[[fs.op.is.empty]]</a>
|
| 10375 |
|
| 10376 |
``` cpp
|
| 10377 |
-
bool is_empty(const path& p);
|
| 10378 |
-
bool is_empty(const path& p, error_code& ec);
|
| 10379 |
```
|
| 10380 |
|
| 10381 |
*Effects:*
|
| 10382 |
|
| 10383 |
- Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
|
|
@@ -10400,18 +11529,18 @@ bool is_empty(const path& p, error_code& ec);
|
|
| 10400 |
*Throws:* As specified in [[fs.err.report]].
|
| 10401 |
|
| 10402 |
#### Is fifo <a id="fs.op.is.fifo">[[fs.op.is.fifo]]</a>
|
| 10403 |
|
| 10404 |
``` cpp
|
| 10405 |
-
bool is_fifo(file_status s) noexcept;
|
| 10406 |
```
|
| 10407 |
|
| 10408 |
*Returns:* `s.type() == file_type::fifo`.
|
| 10409 |
|
| 10410 |
``` cpp
|
| 10411 |
-
bool is_fifo(const path& p);
|
| 10412 |
-
bool is_fifo(const path& p, error_code& ec) noexcept;
|
| 10413 |
```
|
| 10414 |
|
| 10415 |
*Returns:* `is_fifo(status(p))` or `is_fifo(status(p, ec))`,
|
| 10416 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10417 |
error occurs.
|
|
@@ -10419,19 +11548,19 @@ error occurs.
|
|
| 10419 |
*Throws:* As specified in [[fs.err.report]].
|
| 10420 |
|
| 10421 |
#### Is other <a id="fs.op.is.other">[[fs.op.is.other]]</a>
|
| 10422 |
|
| 10423 |
``` cpp
|
| 10424 |
-
bool is_other(file_status s) noexcept;
|
| 10425 |
```
|
| 10426 |
|
| 10427 |
*Returns:*
|
| 10428 |
`exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)`.
|
| 10429 |
|
| 10430 |
``` cpp
|
| 10431 |
-
bool is_other(const path& p);
|
| 10432 |
-
bool is_other(const path& p, error_code& ec) noexcept;
|
| 10433 |
```
|
| 10434 |
|
| 10435 |
*Returns:* `is_other(status(p))` or `is_other(status(p, ec))`,
|
| 10436 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10437 |
error occurs.
|
|
@@ -10439,26 +11568,26 @@ error occurs.
|
|
| 10439 |
*Throws:* As specified in [[fs.err.report]].
|
| 10440 |
|
| 10441 |
#### Is regular file <a id="fs.op.is.regular.file">[[fs.op.is.regular.file]]</a>
|
| 10442 |
|
| 10443 |
``` cpp
|
| 10444 |
-
bool is_regular_file(file_status s) noexcept;
|
| 10445 |
```
|
| 10446 |
|
| 10447 |
*Returns:* `s.type() == file_type::regular`.
|
| 10448 |
|
| 10449 |
``` cpp
|
| 10450 |
-
bool is_regular_file(const path& p);
|
| 10451 |
```
|
| 10452 |
|
| 10453 |
*Returns:* `is_regular_file(status(p))`.
|
| 10454 |
|
| 10455 |
*Throws:* `filesystem_error` if `status(p)` would throw
|
| 10456 |
`filesystem_error`.
|
| 10457 |
|
| 10458 |
``` cpp
|
| 10459 |
-
bool is_regular_file(const path& p, error_code& ec) noexcept;
|
| 10460 |
```
|
| 10461 |
|
| 10462 |
*Effects:* Sets `ec` as if by `status(p, ec)`.
|
| 10463 |
|
| 10464 |
[*Note 1*: `file_type::none`, `file_type::not_found` and
|
|
@@ -10469,18 +11598,18 @@ between cases, call the `status` function directly. — *end note*]
|
|
| 10469 |
occurs.
|
| 10470 |
|
| 10471 |
#### Is socket <a id="fs.op.is.socket">[[fs.op.is.socket]]</a>
|
| 10472 |
|
| 10473 |
``` cpp
|
| 10474 |
-
bool is_socket(file_status s) noexcept;
|
| 10475 |
```
|
| 10476 |
|
| 10477 |
*Returns:* `s.type() == file_type::socket`.
|
| 10478 |
|
| 10479 |
``` cpp
|
| 10480 |
-
bool is_socket(const path& p);
|
| 10481 |
-
bool is_socket(const path& p, error_code& ec) noexcept;
|
| 10482 |
```
|
| 10483 |
|
| 10484 |
*Returns:* `is_socket(status(p))` or `is_socket(status(p, ec))`,
|
| 10485 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10486 |
error occurs.
|
|
@@ -10488,18 +11617,18 @@ error occurs.
|
|
| 10488 |
*Throws:* As specified in [[fs.err.report]].
|
| 10489 |
|
| 10490 |
#### Is symlink <a id="fs.op.is.symlink">[[fs.op.is.symlink]]</a>
|
| 10491 |
|
| 10492 |
``` cpp
|
| 10493 |
-
bool is_symlink(file_status s) noexcept;
|
| 10494 |
```
|
| 10495 |
|
| 10496 |
*Returns:* `s.type() == file_type::symlink`.
|
| 10497 |
|
| 10498 |
``` cpp
|
| 10499 |
-
bool is_symlink(const path& p);
|
| 10500 |
-
bool is_symlink(const path& p, error_code& ec) noexcept;
|
| 10501 |
```
|
| 10502 |
|
| 10503 |
*Returns:* `is_symlink(symlink_status(p))` or
|
| 10504 |
`is_symlink(symlink_status(p, ec))`, respectively. The signature with
|
| 10505 |
argument `ec` returns `false` if an error occurs.
|
|
@@ -10507,74 +11636,74 @@ argument `ec` returns `false` if an error occurs.
|
|
| 10507 |
*Throws:* As specified in [[fs.err.report]].
|
| 10508 |
|
| 10509 |
#### Last write time <a id="fs.op.last.write.time">[[fs.op.last.write.time]]</a>
|
| 10510 |
|
| 10511 |
``` cpp
|
| 10512 |
-
file_time_type last_write_time(const path& p);
|
| 10513 |
-
file_time_type last_write_time(const path& p, error_code& ec) noexcept;
|
| 10514 |
```
|
| 10515 |
|
| 10516 |
*Returns:* The time of last data modification of `p`, determined as if
|
| 10517 |
by the value of the POSIX `stat` class member `st_mtime` obtained as if
|
| 10518 |
by POSIX `stat()`. The signature with argument `ec` returns
|
| 10519 |
`file_time_type::min()` if an error occurs.
|
| 10520 |
|
| 10521 |
*Throws:* As specified in [[fs.err.report]].
|
| 10522 |
|
| 10523 |
``` cpp
|
| 10524 |
-
void last_write_time(const path& p, file_time_type new_time);
|
| 10525 |
-
void last_write_time(const path& p, file_time_type new_time,
|
| 10526 |
error_code& ec) noexcept;
|
| 10527 |
```
|
| 10528 |
|
| 10529 |
*Effects:* Sets the time of last data modification of the file resolved
|
| 10530 |
to by `p` to `new_time`, as if by POSIX `futimens()`.
|
| 10531 |
|
| 10532 |
*Throws:* As specified in [[fs.err.report]].
|
| 10533 |
|
| 10534 |
[*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
|
| 10535 |
-
specified
|
| 10536 |
-
granularity. — *end note*]
|
| 10537 |
|
| 10538 |
#### Permissions <a id="fs.op.permissions">[[fs.op.permissions]]</a>
|
| 10539 |
|
| 10540 |
``` cpp
|
| 10541 |
-
void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
|
| 10542 |
-
void permissions(const path& p, perms prms, error_code& ec) noexcept;
|
| 10543 |
-
void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
|
| 10544 |
```
|
| 10545 |
|
| 10546 |
*Preconditions:* Exactly one of the `perm_options` constants `replace`,
|
| 10547 |
`add`, or `remove` is present in `opts`.
|
| 10548 |
|
| 10549 |
-
*Remarks:* The second signature behaves as if it had an additional
|
| 10550 |
-
parameter `perm_options` `opts` with an argument of
|
| 10551 |
-
`perm_options::replace`.
|
| 10552 |
-
|
| 10553 |
*Effects:* Applies the action specified by `opts` to the file `p`
|
| 10554 |
resolves to, or to file `p` itself if `p` is a symbolic link and
|
| 10555 |
`perm_options::nofollow` is set in `opts`. The action is applied as if
|
| 10556 |
by POSIX `fchmodat()`.
|
| 10557 |
|
| 10558 |
[*Note 1*: Conceptually permissions are viewed as bits, but the actual
|
| 10559 |
-
implementation
|
| 10560 |
|
| 10561 |
*Throws:* As specified in [[fs.err.report]].
|
| 10562 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 10563 |
#### Proximate <a id="fs.op.proximate">[[fs.op.proximate]]</a>
|
| 10564 |
|
| 10565 |
``` cpp
|
| 10566 |
-
path proximate(const path& p, error_code& ec);
|
| 10567 |
```
|
| 10568 |
|
| 10569 |
*Returns:* `proximate(p, current_path(), ec)`.
|
| 10570 |
|
| 10571 |
*Throws:* As specified in [[fs.err.report]].
|
| 10572 |
|
| 10573 |
``` cpp
|
| 10574 |
-
path proximate(const path& p, const path& base = current_path());
|
| 10575 |
-
path proximate(const path& p, const path& base, error_code& ec);
|
| 10576 |
```
|
| 10577 |
|
| 10578 |
*Returns:* For the first form:
|
| 10579 |
|
| 10580 |
``` cpp
|
|
@@ -10592,12 +11721,12 @@ or `path()` at the first error occurrence, if any.
|
|
| 10592 |
*Throws:* As specified in [[fs.err.report]].
|
| 10593 |
|
| 10594 |
#### Read symlink <a id="fs.op.read.symlink">[[fs.op.read.symlink]]</a>
|
| 10595 |
|
| 10596 |
``` cpp
|
| 10597 |
-
path read_symlink(const path& p);
|
| 10598 |
-
path read_symlink(const path& p, error_code& ec);
|
| 10599 |
```
|
| 10600 |
|
| 10601 |
*Returns:* If `p` resolves to a symbolic link, a `path` object
|
| 10602 |
containing the contents of that symbolic link. The signature with
|
| 10603 |
argument `ec` returns `path()` if an error occurs.
|
|
@@ -10608,20 +11737,20 @@ argument `ec` returns `path()` if an error occurs.
|
|
| 10608 |
link. — *end note*]
|
| 10609 |
|
| 10610 |
#### Relative <a id="fs.op.relative">[[fs.op.relative]]</a>
|
| 10611 |
|
| 10612 |
``` cpp
|
| 10613 |
-
path relative(const path& p, error_code& ec);
|
| 10614 |
```
|
| 10615 |
|
| 10616 |
*Returns:* `relative(p, current_path(), ec)`.
|
| 10617 |
|
| 10618 |
*Throws:* As specified in [[fs.err.report]].
|
| 10619 |
|
| 10620 |
``` cpp
|
| 10621 |
-
path relative(const path& p, const path& base = current_path());
|
| 10622 |
-
path relative(const path& p, const path& base, error_code& ec);
|
| 10623 |
```
|
| 10624 |
|
| 10625 |
*Returns:* For the first form:
|
| 10626 |
|
| 10627 |
``` cpp
|
|
@@ -10639,12 +11768,12 @@ or `path()` at the first error occurrence, if any.
|
|
| 10639 |
*Throws:* As specified in [[fs.err.report]].
|
| 10640 |
|
| 10641 |
#### Remove <a id="fs.op.remove">[[fs.op.remove]]</a>
|
| 10642 |
|
| 10643 |
``` cpp
|
| 10644 |
-
bool remove(const path& p);
|
| 10645 |
-
bool remove(const path& p, error_code& ec) noexcept;
|
| 10646 |
```
|
| 10647 |
|
| 10648 |
*Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
|
| 10649 |
as if by POSIX `remove()`.
|
| 10650 |
|
|
@@ -10659,12 +11788,12 @@ with argument `ec` returns `false` if an error occurs.
|
|
| 10659 |
*Throws:* As specified in [[fs.err.report]].
|
| 10660 |
|
| 10661 |
#### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
|
| 10662 |
|
| 10663 |
``` cpp
|
| 10664 |
-
uintmax_t remove_all(const path& p);
|
| 10665 |
-
uintmax_t remove_all(const path& p, error_code& ec);
|
| 10666 |
```
|
| 10667 |
|
| 10668 |
*Effects:* Recursively deletes the contents of `p` if it exists, then
|
| 10669 |
deletes file `p` itself, as if by POSIX `remove()`.
|
| 10670 |
|
|
@@ -10679,25 +11808,25 @@ returns `static_cast< uintmax_t>(-1)` if an error occurs.
|
|
| 10679 |
*Throws:* As specified in [[fs.err.report]].
|
| 10680 |
|
| 10681 |
#### Rename <a id="fs.op.rename">[[fs.op.rename]]</a>
|
| 10682 |
|
| 10683 |
``` cpp
|
| 10684 |
-
void rename(const path& old_p, const path& new_p);
|
| 10685 |
-
void rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
|
| 10686 |
```
|
| 10687 |
|
| 10688 |
*Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
|
| 10689 |
|
| 10690 |
[*Note 1*:
|
| 10691 |
|
| 10692 |
- If `old_p` and `new_p` resolve to the same existing file, no action is
|
| 10693 |
taken.
|
| 10694 |
-
- Otherwise, the rename
|
| 10695 |
- if `new_p` resolves to an existing non-directory file, `new_p` is
|
| 10696 |
removed; otherwise,
|
| 10697 |
- if `new_p` resolves to an existing directory, `new_p` is removed if
|
| 10698 |
-
empty on POSIX compliant operating systems but
|
| 10699 |
other operating systems.
|
| 10700 |
|
| 10701 |
A symbolic link is itself renamed, rather than the file it resolves to.
|
| 10702 |
|
| 10703 |
— *end note*]
|
|
@@ -10705,24 +11834,24 @@ A symbolic link is itself renamed, rather than the file it resolves to.
|
|
| 10705 |
*Throws:* As specified in [[fs.err.report]].
|
| 10706 |
|
| 10707 |
#### Resize file <a id="fs.op.resize.file">[[fs.op.resize.file]]</a>
|
| 10708 |
|
| 10709 |
``` cpp
|
| 10710 |
-
void resize_file(const path& p, uintmax_t new_size);
|
| 10711 |
-
void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
|
| 10712 |
```
|
| 10713 |
|
| 10714 |
*Effects:* Causes the size that would be returned by `file_size(p)` to
|
| 10715 |
be equal to `new_size`, as if by POSIX `truncate()`.
|
| 10716 |
|
| 10717 |
*Throws:* As specified in [[fs.err.report]].
|
| 10718 |
|
| 10719 |
#### Space <a id="fs.op.space">[[fs.op.space]]</a>
|
| 10720 |
|
| 10721 |
``` cpp
|
| 10722 |
-
space_info space(const path& p);
|
| 10723 |
-
space_info space(const path& p, error_code& ec) noexcept;
|
| 10724 |
```
|
| 10725 |
|
| 10726 |
*Returns:* An object of type `space_info`. The value of the `space_info`
|
| 10727 |
object is determined as if by using POSIX `statvfs` to obtain a POSIX
|
| 10728 |
`struct statvfs`, and then multiplying its `f_blocks`, `f_bfree`, and
|
|
@@ -10735,16 +11864,16 @@ members are set to `static_cast<uintmax_t>(-1)` if an error occurs.
|
|
| 10735 |
*Throws:* As specified in [[fs.err.report]].
|
| 10736 |
|
| 10737 |
*Remarks:* The value of member `space_info::available` is operating
|
| 10738 |
system dependent.
|
| 10739 |
|
| 10740 |
-
[*Note 1*: `available`
|
| 10741 |
|
| 10742 |
#### Status <a id="fs.op.status">[[fs.op.status]]</a>
|
| 10743 |
|
| 10744 |
``` cpp
|
| 10745 |
-
file_status status(const path& p);
|
| 10746 |
```
|
| 10747 |
|
| 10748 |
*Effects:* As if:
|
| 10749 |
|
| 10750 |
``` cpp
|
|
@@ -10762,11 +11891,11 @@ return result;
|
|
| 10762 |
[*Note 1*: `result` values of `file_status(file_type::not_found)` and
|
| 10763 |
`file_status(file_type::unknown)` are not considered failures and do not
|
| 10764 |
cause an exception to be thrown. — *end note*]
|
| 10765 |
|
| 10766 |
``` cpp
|
| 10767 |
-
file_status status(const path& p, error_code& ec) noexcept;
|
| 10768 |
```
|
| 10769 |
|
| 10770 |
*Effects:* If possible, determines the attributes of the file `p`
|
| 10771 |
resolves to, as if by using POSIX `stat()` to obtain a POSIX
|
| 10772 |
`struct stat`. If, during attribute determination, the underlying file
|
|
@@ -10827,20 +11956,20 @@ determined as if by converting the `st_mode` member of the obtained
|
|
| 10827 |
pathname resolution continues using the contents of the symbolic link.
|
| 10828 |
|
| 10829 |
#### Status known <a id="fs.op.status.known">[[fs.op.status.known]]</a>
|
| 10830 |
|
| 10831 |
``` cpp
|
| 10832 |
-
bool status_known(file_status s) noexcept;
|
| 10833 |
```
|
| 10834 |
|
| 10835 |
*Returns:* `s.type() != file_type::none`.
|
| 10836 |
|
| 10837 |
#### Symlink status <a id="fs.op.symlink.status">[[fs.op.symlink.status]]</a>
|
| 10838 |
|
| 10839 |
``` cpp
|
| 10840 |
-
file_status symlink_status(const path& p);
|
| 10841 |
-
file_status symlink_status(const path& p, error_code& ec) noexcept;
|
| 10842 |
```
|
| 10843 |
|
| 10844 |
*Effects:* Same as `status()`, above, except that the attributes of `p`
|
| 10845 |
are determined as if by using POSIX `lstat()` to obtain a POSIX
|
| 10846 |
`struct stat`.
|
|
@@ -10852,19 +11981,19 @@ determined as if by converting the `st_mode` member of the obtained
|
|
| 10852 |
*Returns:* Same as `status()`, above, except that if the attributes
|
| 10853 |
indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
|
| 10854 |
`file_status(file_type::symlink, prms)`. The signature with argument
|
| 10855 |
`ec` returns `file_status(file_type::none)` if an error occurs.
|
| 10856 |
|
|
|
|
|
|
|
| 10857 |
*Remarks:* Pathname resolution terminates if `p` names a symbolic link.
|
| 10858 |
|
| 10859 |
-
*Throws:* As specified in [[fs.err.report]].
|
| 10860 |
-
|
| 10861 |
#### Temporary directory path <a id="fs.op.temp.dir.path">[[fs.op.temp.dir.path]]</a>
|
| 10862 |
|
| 10863 |
``` cpp
|
| 10864 |
-
path temp_directory_path();
|
| 10865 |
-
path temp_directory_path(error_code& ec);
|
| 10866 |
```
|
| 10867 |
|
| 10868 |
Let `p` be an unspecified directory path suitable for temporary files.
|
| 10869 |
|
| 10870 |
*Effects:* If `exists(p)` is `false` or `is_directory(p)` is `false`, an
|
|
@@ -10883,17 +12012,14 @@ return the path reported by the Windows `GetTempPath` API
|
|
| 10883 |
function. — *end example*]
|
| 10884 |
|
| 10885 |
#### Weakly canonical <a id="fs.op.weakly.canonical">[[fs.op.weakly.canonical]]</a>
|
| 10886 |
|
| 10887 |
``` cpp
|
| 10888 |
-
path weakly_canonical(const path& p);
|
| 10889 |
-
path weakly_canonical(const path& p, error_code& ec);
|
| 10890 |
```
|
| 10891 |
|
| 10892 |
-
*Returns:* `p` with symlinks resolved and the result
|
| 10893 |
-
normalized [[fs.path.generic]].
|
| 10894 |
-
|
| 10895 |
*Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
|
| 10896 |
determine existence, return a path composed by `operator/=` from the
|
| 10897 |
result of calling `canonical()` with a path argument composed of the
|
| 10898 |
leading elements of `p` that exist, if any, followed by the elements of
|
| 10899 |
`p` that do not exist, if any. For the first form, `canonical()` is
|
|
@@ -10901,12 +12027,12 @@ called without an `error_code` argument. For the second form,
|
|
| 10901 |
`canonical()` is called with `ec` as an `error_code` argument, and
|
| 10902 |
`path()` is returned at the first error occurrence, if any.
|
| 10903 |
|
| 10904 |
*Ensures:* The returned path is in normal form [[fs.path.generic]].
|
| 10905 |
|
| 10906 |
-
*
|
| 10907 |
-
|
| 10908 |
|
| 10909 |
*Throws:* As specified in [[fs.err.report]].
|
| 10910 |
|
| 10911 |
## C library files <a id="c.files">[[c.files]]</a>
|
| 10912 |
|
|
@@ -11000,19 +12126,19 @@ See also: ISO C 7.21
|
|
| 11000 |
#include <cstdint> // see [cstdint.syn]
|
| 11001 |
|
| 11002 |
namespace std {
|
| 11003 |
using imaxdiv_t = see below;
|
| 11004 |
|
| 11005 |
-
intmax_t imaxabs(intmax_t j);
|
| 11006 |
-
imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
|
| 11007 |
intmax_t strtoimax(const char* nptr, char** endptr, int base);
|
| 11008 |
uintmax_t strtoumax(const char* nptr, char** endptr, int base);
|
| 11009 |
intmax_t wcstoimax(const wchar_t* nptr, wchar_t** endptr, int base);
|
| 11010 |
uintmax_t wcstoumax(const wchar_t* nptr, wchar_t** endptr, int base);
|
| 11011 |
|
| 11012 |
-
intmax_t abs(intmax_t);
|
| 11013 |
-
imaxdiv_t div(intmax_t, intmax_t);
|
| 11014 |
}
|
| 11015 |
|
| 11016 |
#define PRIdN see below
|
| 11017 |
#define PRIiN see below
|
| 11018 |
#define PRIoN see below
|
|
@@ -11073,73 +12199,97 @@ namespace std {
|
|
| 11073 |
The contents and meaning of the header `<cinttypes>` are the same as the
|
| 11074 |
C standard library header `<inttypes.h>`, with the following changes:
|
| 11075 |
|
| 11076 |
- The header `<cinttypes>` includes the header `<cstdint>` instead of
|
| 11077 |
`<stdint.h>`, and
|
|
|
|
|
|
|
|
|
|
| 11078 |
- if and only if the type `intmax_t` designates an extended integer type
|
| 11079 |
[[basic.fundamental]], the following function signatures are added:
|
| 11080 |
``` cpp
|
| 11081 |
-
intmax_t abs(intmax_t);
|
| 11082 |
-
imaxdiv_t div(intmax_t, intmax_t);
|
| 11083 |
```
|
| 11084 |
|
| 11085 |
which shall have the same semantics as the function signatures
|
| 11086 |
-
`intmax_t imaxabs(intmax_t)` and
|
| 11087 |
-
`imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
|
| 11088 |
|
| 11089 |
See also: ISO C 7.8
|
| 11090 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11091 |
<!-- Link reference definitions -->
|
| 11092 |
[adjustfield.manip]: #adjustfield.manip
|
|
|
|
| 11093 |
[basefield.manip]: #basefield.manip
|
| 11094 |
[basic.fundamental]: basic.md#basic.fundamental
|
| 11095 |
[basic.ios.cons]: #basic.ios.cons
|
| 11096 |
[basic.ios.copyfmt]: #basic.ios.copyfmt
|
| 11097 |
[basic.ios.members]: #basic.ios.members
|
|
|
|
| 11098 |
[basic.start.main]: basic.md#basic.start.main
|
| 11099 |
[bidirectional.iterators]: iterators.md#bidirectional.iterators
|
| 11100 |
[bitmask.types]: library.md#bitmask.types
|
| 11101 |
[c.files]: #c.files
|
| 11102 |
[char.traits]: strings.md#char.traits
|
|
|
|
|
|
|
| 11103 |
[cinttypes.syn]: #cinttypes.syn
|
| 11104 |
[container.requirements.general]: containers.md#container.requirements.general
|
| 11105 |
-
[cpp17.allocator]: #cpp17.allocator
|
| 11106 |
[cpp17.copyassignable]: #cpp17.copyassignable
|
| 11107 |
[cpp17.copyconstructible]: #cpp17.copyconstructible
|
| 11108 |
[cpp17.defaultconstructible]: #cpp17.defaultconstructible
|
| 11109 |
[cpp17.destructible]: #cpp17.destructible
|
| 11110 |
[cpp17.equalitycomparable]: #cpp17.equalitycomparable
|
|
|
|
| 11111 |
[cstdio.syn]: #cstdio.syn
|
| 11112 |
-
[defns.ntcts]:
|
| 11113 |
[enumerated.types]: library.md#enumerated.types
|
| 11114 |
[error.reporting]: #error.reporting
|
| 11115 |
[ext.manip]: #ext.manip
|
| 11116 |
[file.streams]: #file.streams
|
| 11117 |
[filebuf]: #filebuf
|
| 11118 |
[filebuf.assign]: #filebuf.assign
|
| 11119 |
[filebuf.cons]: #filebuf.cons
|
|
|
|
| 11120 |
[filebuf.members]: #filebuf.members
|
| 11121 |
[filebuf.open.modes]: #filebuf.open.modes
|
| 11122 |
[filebuf.seekoff]: #filebuf.seekoff
|
| 11123 |
[filebuf.virtuals]: #filebuf.virtuals
|
| 11124 |
[filesystems]: #filesystems
|
| 11125 |
[floatfield.manip]: #floatfield.manip
|
| 11126 |
[fmtflags.manip]: #fmtflags.manip
|
| 11127 |
[fmtflags.state]: #fmtflags.state
|
|
|
|
| 11128 |
[fpos]: #fpos
|
| 11129 |
[fpos.members]: #fpos.members
|
| 11130 |
[fpos.operations]: #fpos.operations
|
| 11131 |
[fs.class.directory.entry]: #fs.class.directory.entry
|
|
|
|
| 11132 |
[fs.class.directory.iterator]: #fs.class.directory.iterator
|
|
|
|
| 11133 |
[fs.class.file.status]: #fs.class.file.status
|
|
|
|
| 11134 |
[fs.class.filesystem.error]: #fs.class.filesystem.error
|
|
|
|
| 11135 |
[fs.class.path]: #fs.class.path
|
|
|
|
| 11136 |
[fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
|
|
|
|
| 11137 |
[fs.conform.9945]: #fs.conform.9945
|
| 11138 |
[fs.conform.os]: #fs.conform.os
|
| 11139 |
[fs.conformance]: #fs.conformance
|
|
|
|
| 11140 |
[fs.dir.entry.cons]: #fs.dir.entry.cons
|
|
|
|
| 11141 |
[fs.dir.entry.mods]: #fs.dir.entry.mods
|
| 11142 |
[fs.dir.entry.obs]: #fs.dir.entry.obs
|
| 11143 |
[fs.dir.itr.members]: #fs.dir.itr.members
|
| 11144 |
[fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
|
| 11145 |
[fs.enum]: #fs.enum
|
|
@@ -11154,11 +12304,10 @@ See also: ISO C 7.8
|
|
| 11154 |
[fs.file.status.mods]: #fs.file.status.mods
|
| 11155 |
[fs.file.status.obs]: #fs.file.status.obs
|
| 11156 |
[fs.filesystem.error.members]: #fs.filesystem.error.members
|
| 11157 |
[fs.filesystem.syn]: #fs.filesystem.syn
|
| 11158 |
[fs.general]: #fs.general
|
| 11159 |
-
[fs.norm.ref]: #fs.norm.ref
|
| 11160 |
[fs.op.absolute]: #fs.op.absolute
|
| 11161 |
[fs.op.canonical]: #fs.op.canonical
|
| 11162 |
[fs.op.copy]: #fs.op.copy
|
| 11163 |
[fs.op.copy.file]: #fs.op.copy.file
|
| 11164 |
[fs.op.copy.symlink]: #fs.op.copy.symlink
|
|
@@ -11170,10 +12319,11 @@ See also: ISO C 7.8
|
|
| 11170 |
[fs.op.current.path]: #fs.op.current.path
|
| 11171 |
[fs.op.equivalent]: #fs.op.equivalent
|
| 11172 |
[fs.op.exists]: #fs.op.exists
|
| 11173 |
[fs.op.file.size]: #fs.op.file.size
|
| 11174 |
[fs.op.funcs]: #fs.op.funcs
|
|
|
|
| 11175 |
[fs.op.hard.lk.ct]: #fs.op.hard.lk.ct
|
| 11176 |
[fs.op.is.block.file]: #fs.op.is.block.file
|
| 11177 |
[fs.op.is.char.file]: #fs.op.is.char.file
|
| 11178 |
[fs.op.is.directory]: #fs.op.is.directory
|
| 11179 |
[fs.op.is.empty]: #fs.op.is.empty
|
|
@@ -11206,10 +12356,11 @@ See also: ISO C 7.8
|
|
| 11206 |
[fs.path.decompose]: #fs.path.decompose
|
| 11207 |
[fs.path.fmt.cvt]: #fs.path.fmt.cvt
|
| 11208 |
[fs.path.gen]: #fs.path.gen
|
| 11209 |
[fs.path.generic]: #fs.path.generic
|
| 11210 |
[fs.path.generic.obs]: #fs.path.generic.obs
|
|
|
|
| 11211 |
[fs.path.io]: #fs.path.io
|
| 11212 |
[fs.path.itr]: #fs.path.itr
|
| 11213 |
[fs.path.member]: #fs.path.member
|
| 11214 |
[fs.path.modifiers]: #fs.path.modifiers
|
| 11215 |
[fs.path.native.obs]: #fs.path.native.obs
|
|
@@ -11219,31 +12370,34 @@ See also: ISO C 7.8
|
|
| 11219 |
[fs.path.type.cvt]: #fs.path.type.cvt
|
| 11220 |
[fs.race.behavior]: #fs.race.behavior
|
| 11221 |
[fs.rec.dir.itr.members]: #fs.rec.dir.itr.members
|
| 11222 |
[fs.rec.dir.itr.nonmembers]: #fs.rec.dir.itr.nonmembers
|
| 11223 |
[fs.req]: #fs.req
|
| 11224 |
-
[fs.req.namespace]: #fs.req.namespace
|
| 11225 |
[fstream]: #fstream
|
| 11226 |
-
[fstream.assign]: #fstream.assign
|
| 11227 |
[fstream.cons]: #fstream.cons
|
|
|
|
| 11228 |
[fstream.members]: #fstream.members
|
|
|
|
| 11229 |
[fstream.syn]: #fstream.syn
|
| 11230 |
[ifstream]: #ifstream
|
| 11231 |
-
[ifstream.assign]: #ifstream.assign
|
| 11232 |
[ifstream.cons]: #ifstream.cons
|
|
|
|
| 11233 |
[ifstream.members]: #ifstream.members
|
|
|
|
| 11234 |
[input.iterators]: iterators.md#input.iterators
|
| 11235 |
[input.output]: #input.output
|
| 11236 |
[input.output.general]: #input.output.general
|
| 11237 |
[input.streams]: #input.streams
|
|
|
|
| 11238 |
[intro.multithread]: basic.md#intro.multithread
|
| 11239 |
[intro.races]: basic.md#intro.races
|
| 11240 |
[iomanip.syn]: #iomanip.syn
|
| 11241 |
[ios]: #ios
|
| 11242 |
[ios.base]: #ios.base
|
| 11243 |
[ios.base.callback]: #ios.base.callback
|
| 11244 |
[ios.base.cons]: #ios.base.cons
|
|
|
|
| 11245 |
[ios.base.locales]: #ios.base.locales
|
| 11246 |
[ios.base.storage]: #ios.base.storage
|
| 11247 |
[ios.failure]: #ios.failure
|
| 11248 |
[ios.fmtflags]: #ios.fmtflags
|
| 11249 |
[ios.fmtflags.const]: #ios.fmtflags.const
|
|
@@ -11266,72 +12420,108 @@ See also: ISO C 7.8
|
|
| 11266 |
[iostream.limits.imbue]: #iostream.limits.imbue
|
| 11267 |
[iostream.objects]: #iostream.objects
|
| 11268 |
[iostream.objects.overview]: #iostream.objects.overview
|
| 11269 |
[iostream.syn]: #iostream.syn
|
| 11270 |
[iostreamclass]: #iostreamclass
|
|
|
|
| 11271 |
[iostreams.base]: #iostreams.base
|
| 11272 |
[iostreams.limits.pos]: #iostreams.limits.pos
|
| 11273 |
[iostreams.requirements]: #iostreams.requirements
|
| 11274 |
[iostreams.summary]: #iostreams.summary
|
| 11275 |
[iostreams.threadsafety]: #iostreams.threadsafety
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11276 |
[istream]: #istream
|
| 11277 |
[istream.assign]: #istream.assign
|
| 11278 |
[istream.cons]: #istream.cons
|
| 11279 |
[istream.extractors]: #istream.extractors
|
| 11280 |
[istream.formatted]: #istream.formatted
|
| 11281 |
[istream.formatted.arithmetic]: #istream.formatted.arithmetic
|
| 11282 |
[istream.formatted.reqmts]: #istream.formatted.reqmts
|
|
|
|
| 11283 |
[istream.manip]: #istream.manip
|
| 11284 |
[istream.rvalue]: #istream.rvalue
|
| 11285 |
[istream.sentry]: #istream.sentry
|
| 11286 |
[istream.syn]: #istream.syn
|
| 11287 |
[istream.unformatted]: #istream.unformatted
|
| 11288 |
[istringstream]: #istringstream
|
| 11289 |
-
[istringstream.assign]: #istringstream.assign
|
| 11290 |
[istringstream.cons]: #istringstream.cons
|
|
|
|
| 11291 |
[istringstream.members]: #istringstream.members
|
|
|
|
| 11292 |
[lex.charset]: lex.md#lex.charset
|
| 11293 |
[locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
|
| 11294 |
[locale.num.get]: localization.md#locale.num.get
|
| 11295 |
[namespace.std]: library.md#namespace.std
|
| 11296 |
[narrow.stream.objects]: #narrow.stream.objects
|
| 11297 |
[numeric.limits]: support.md#numeric.limits
|
| 11298 |
[ofstream]: #ofstream
|
| 11299 |
-
[ofstream.assign]: #ofstream.assign
|
| 11300 |
[ofstream.cons]: #ofstream.cons
|
|
|
|
| 11301 |
[ofstream.members]: #ofstream.members
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11302 |
[ostream]: #ostream
|
| 11303 |
[ostream.assign]: #ostream.assign
|
| 11304 |
[ostream.cons]: #ostream.cons
|
| 11305 |
[ostream.formatted]: #ostream.formatted
|
|
|
|
| 11306 |
[ostream.formatted.reqmts]: #ostream.formatted.reqmts
|
|
|
|
| 11307 |
[ostream.inserters]: #ostream.inserters
|
| 11308 |
[ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
|
| 11309 |
[ostream.inserters.character]: #ostream.inserters.character
|
| 11310 |
[ostream.manip]: #ostream.manip
|
| 11311 |
[ostream.rvalue]: #ostream.rvalue
|
| 11312 |
[ostream.seeks]: #ostream.seeks
|
| 11313 |
[ostream.sentry]: #ostream.sentry
|
| 11314 |
[ostream.syn]: #ostream.syn
|
| 11315 |
[ostream.unformatted]: #ostream.unformatted
|
| 11316 |
[ostringstream]: #ostringstream
|
| 11317 |
-
[ostringstream.assign]: #ostringstream.assign
|
| 11318 |
[ostringstream.cons]: #ostringstream.cons
|
|
|
|
| 11319 |
[ostringstream.members]: #ostringstream.members
|
|
|
|
| 11320 |
[output.streams]: #output.streams
|
|
|
|
|
|
|
|
|
|
| 11321 |
[quoted.manip]: #quoted.manip
|
| 11322 |
[res.on.data.races]: library.md#res.on.data.races
|
| 11323 |
[res.on.exception.handling]: library.md#res.on.exception.handling
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11324 |
[sstream.syn]: #sstream.syn
|
| 11325 |
[std.ios.manip]: #std.ios.manip
|
| 11326 |
[std.manip]: #std.manip
|
|
|
|
| 11327 |
[stream.buffers]: #stream.buffers
|
| 11328 |
[stream.types]: #stream.types
|
| 11329 |
[streambuf]: #streambuf
|
| 11330 |
[streambuf.assign]: #streambuf.assign
|
| 11331 |
[streambuf.buffer]: #streambuf.buffer
|
| 11332 |
[streambuf.cons]: #streambuf.cons
|
|
|
|
| 11333 |
[streambuf.get.area]: #streambuf.get.area
|
| 11334 |
[streambuf.locales]: #streambuf.locales
|
| 11335 |
[streambuf.members]: #streambuf.members
|
| 11336 |
[streambuf.protected]: #streambuf.protected
|
| 11337 |
[streambuf.pub.get]: #streambuf.pub.get
|
|
@@ -11349,19 +12539,21 @@ See also: ISO C 7.8
|
|
| 11349 |
[string.classes]: strings.md#string.classes
|
| 11350 |
[string.streams]: #string.streams
|
| 11351 |
[stringbuf]: #stringbuf
|
| 11352 |
[stringbuf.assign]: #stringbuf.assign
|
| 11353 |
[stringbuf.cons]: #stringbuf.cons
|
|
|
|
| 11354 |
[stringbuf.members]: #stringbuf.members
|
| 11355 |
[stringbuf.seekoff.newoff]: #stringbuf.seekoff.newoff
|
| 11356 |
[stringbuf.seekoff.pos]: #stringbuf.seekoff.pos
|
| 11357 |
[stringbuf.virtuals]: #stringbuf.virtuals
|
| 11358 |
[strings]: strings.md#strings
|
| 11359 |
[stringstream]: #stringstream
|
| 11360 |
-
[stringstream.assign]: #stringstream.assign
|
| 11361 |
[stringstream.cons]: #stringstream.cons
|
|
|
|
| 11362 |
[stringstream.members]: #stringstream.members
|
|
|
|
| 11363 |
[syncstream]: #syncstream
|
| 11364 |
[syncstream.osyncstream]: #syncstream.osyncstream
|
| 11365 |
[syncstream.osyncstream.cons]: #syncstream.osyncstream.cons
|
| 11366 |
[syncstream.osyncstream.members]: #syncstream.osyncstream.members
|
| 11367 |
[syncstream.osyncstream.overview]: #syncstream.osyncstream.overview
|
|
@@ -11372,71 +12564,73 @@ See also: ISO C 7.8
|
|
| 11372 |
[syncstream.syncbuf.members]: #syncstream.syncbuf.members
|
| 11373 |
[syncstream.syncbuf.overview]: #syncstream.syncbuf.overview
|
| 11374 |
[syncstream.syncbuf.special]: #syncstream.syncbuf.special
|
| 11375 |
[syncstream.syncbuf.virtuals]: #syncstream.syncbuf.virtuals
|
| 11376 |
[temp.deduct]: temp.md#temp.deduct
|
|
|
|
|
|
|
| 11377 |
[wide.stream.objects]: #wide.stream.objects
|
| 11378 |
|
| 11379 |
-
[^1]:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11380 |
that including `<iosfwd>` and other headers does not violate the
|
| 11381 |
rules about multiple occurrences of default arguments.
|
| 11382 |
|
| 11383 |
-
[^
|
| 11384 |
-
initialize the objects earlier than required.
|
| 11385 |
-
|
| 11386 |
-
[^3]: Constructors and destructors for objects with static storage
|
| 11387 |
duration can access these objects to read input from `stdin` or
|
| 11388 |
write output to `stdout` or `stderr`.
|
| 11389 |
|
| 11390 |
-
[^
|
| 11391 |
-
|
| 11392 |
-
[^5]: `streamsize` is used in most places where ISO C would use
|
| 11393 |
-
`size_t`.
|
| 11394 |
-
|
| 11395 |
-
[^6]: This implies that operations on a standard iostream object can be
|
| 11396 |
mixed arbitrarily with operations on the corresponding stdio stream.
|
| 11397 |
In practical terms, synchronization usually means that a standard
|
| 11398 |
iostream object and a standard stdio object share a buffer.
|
| 11399 |
|
| 11400 |
-
[^
|
| 11401 |
pointed at by `iarray` and the pointer array pointed at by `parray`
|
| 11402 |
as sparse data structures, possibly with a one-element cache for
|
| 11403 |
each.
|
| 11404 |
|
|
|
|
|
|
|
| 11405 |
[^8]: For example, because it cannot allocate space.
|
| 11406 |
|
| 11407 |
-
[^9]:
|
| 11408 |
-
|
| 11409 |
-
[^10]: This suggests an infinite amount of copying, but the
|
| 11410 |
implementation can keep track of the maximum element of the arrays
|
| 11411 |
that is nonzero.
|
| 11412 |
|
| 11413 |
-
[^
|
| 11414 |
|
| 11415 |
-
[^
|
| 11416 |
function signature
|
| 11417 |
`basic_ostream& stream::operator<<(ios_base& (*)(ios_base&))` to
|
| 11418 |
permit expressions of the form `cout << dec` to change the format
|
| 11419 |
flags stored in `cout`.
|
| 11420 |
|
| 11421 |
-
[^
|
| 11422 |
-
to assure that only objects for classes derived from this class
|
| 11423 |
be constructed.
|
| 11424 |
|
| 11425 |
-
[^
|
|
|
|
|
|
|
|
|
|
| 11426 |
prematurely. The intention is not only that the calls will not
|
| 11427 |
return `eof()` but that they will return “immediately”.
|
| 11428 |
|
| 11429 |
[^15]: Classes derived from `basic_streambuf` can provide more efficient
|
| 11430 |
ways to implement `xsgetn()` and `xsputn()` by overriding these
|
| 11431 |
definitions from the base class.
|
| 11432 |
|
| 11433 |
-
[^16]: That is, for each class derived from
|
| 11434 |
-
`basic_streambuf` in this Clause
|
| 11435 |
-
|
| 11436 |
-
|
| 11437 |
-
|
| 11438 |
|
| 11439 |
[^17]: Typically, `overflow` returns `c` to indicate success, except
|
| 11440 |
when `traits::eq_int_type(c, traits::eof())` returns `true`, in
|
| 11441 |
which case it returns `traits::not_eof(c)`.
|
| 11442 |
|
|
@@ -11445,76 +12639,67 @@ See also: ISO C 7.8
|
|
| 11445 |
specified.
|
| 11446 |
|
| 11447 |
[^19]: The `sentry` constructor and destructor can also perform
|
| 11448 |
additional implementation-dependent operations.
|
| 11449 |
|
| 11450 |
-
[^20]:
|
| 11451 |
-
|
| 11452 |
-
[^21]: See, for example, the function signature
|
| 11453 |
`ws(basic_istream&)`[[istream.manip]].
|
| 11454 |
|
| 11455 |
-
[^
|
| 11456 |
`dec(ios_base&)`[[basefield.manip]].
|
| 11457 |
|
| 11458 |
-
[^
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11459 |
|
| 11460 |
[^24]: Note that this function is not overloaded on types `signed char`
|
| 11461 |
and `unsigned char`.
|
| 11462 |
|
| 11463 |
-
[^25]:
|
| 11464 |
-
and `unsigned char`.
|
| 11465 |
-
|
| 11466 |
-
[^26]: Note that this function is not overloaded on types `signed char`
|
| 11467 |
-
and `unsigned char`.
|
| 11468 |
-
|
| 11469 |
-
[^27]: Since the final input character is “extracted”, it is counted in
|
| 11470 |
the `gcount()`, even though it is not stored.
|
| 11471 |
|
| 11472 |
-
[^
|
| 11473 |
setting `failbit`. This is different behavior than the historical
|
| 11474 |
AT&T implementation.
|
| 11475 |
|
| 11476 |
-
[^
|
| 11477 |
set.
|
| 11478 |
|
| 11479 |
-
[^
|
| 11480 |
and `unsigned char`.
|
| 11481 |
|
| 11482 |
-
[^
|
| 11483 |
function can determine that no synchronization is necessary.
|
| 11484 |
|
| 11485 |
-
[^
|
| 11486 |
additional implementation-dependent operations.
|
| 11487 |
|
| 11488 |
-
[^
|
| 11489 |
|
| 11490 |
-
[^
|
| 11491 |
`endl(basic_ostream&)`[[ostream.manip]].
|
| 11492 |
|
| 11493 |
-
[^
|
| 11494 |
`dec(ios_base&)`[[basefield.manip]].
|
| 11495 |
|
| 11496 |
-
[^
|
| 11497 |
|
| 11498 |
-
[^
|
| 11499 |
and `unsigned char`.
|
| 11500 |
|
| 11501 |
-
[^
|
| 11502 |
and `unsigned char`.
|
| 11503 |
|
| 11504 |
-
[^
|
| 11505 |
`ios_base::skipws` in the format flags stored in the
|
| 11506 |
`basic_istream<charT, traits>` object `cin` (the same as
|
| 11507 |
`cin >> noskipws`), and the expression
|
| 11508 |
`cout << resetiosflags(ios_base::showbase)` clears
|
| 11509 |
`ios_base::showbase` in the format flags stored in the
|
| 11510 |
`basic_ostream<charT, traits>` object `cout` (the same as
|
| 11511 |
`cout << noshowbase`).
|
| 11512 |
|
| 11513 |
-
[^
|
| 11514 |
`fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
|
| 11515 |
declared, in `<cstdio>`.
|
| 11516 |
-
|
| 11517 |
-
[^41]: POSIX® is a registered trademark of The IEEE. Windows® is a
|
| 11518 |
-
registered trademark of Microsoft Corporation. This information is
|
| 11519 |
-
given for the convenience of users of this document and does not
|
| 11520 |
-
constitute an endorsement by ISO or IEC of these products.
|
|
|
|
| 12 |
summarized in [[iostreams.summary]].
|
| 13 |
|
| 14 |
**Table: Input/output library summary** <a id="iostreams.summary">[iostreams.summary]</a>
|
| 15 |
|
| 16 |
| Subclause | | Header |
|
| 17 |
+
| -------------------------- | --------------------------- | ------------------------------------------------ |
|
| 18 |
| [[iostreams.requirements]] | Requirements | |
|
| 19 |
| [[iostream.forward]] | Forward declarations | `<iosfwd>` |
|
| 20 |
| [[iostream.objects]] | Standard iostream objects | `<iostream>` |
|
| 21 |
| [[iostreams.base]] | Iostreams base classes | `<ios>` |
|
| 22 |
| [[stream.buffers]] | Stream buffers | `<streambuf>` |
|
| 23 |
+
| [[iostream.format]] | Formatting and manipulators | `<istream>`, `<ostream>`, `<iomanip>`, `<print>` |
|
| 24 |
| [[string.streams]] | String streams | `<sstream>` |
|
| 25 |
+
| [[span.streams]] | Span-based streams | `<spanstream>` |
|
| 26 |
| [[file.streams]] | File streams | `<fstream>` |
|
| 27 |
| [[syncstream]] | Synchronized output streams | `<syncstream>` |
|
| 28 |
| [[filesystems]] | File systems | `<filesystem>` |
|
| 29 |
| [[c.files]] | C library files | `<cstdio>`, `<cinttypes>` |
|
| 30 |
|
| 31 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 32 |
## Iostreams requirements <a id="iostreams.requirements">[[iostreams.requirements]]</a>
|
| 33 |
|
| 34 |
### Imbue limitations <a id="iostream.limits.imbue">[[iostream.limits.imbue]]</a>
|
| 35 |
|
| 36 |
No function described in [[input.output]] except for `ios_base::imbue`
|
|
|
|
| 38 |
or `basic_streambuf::imbue` to be called. If any user function called
|
| 39 |
from a function declared in [[input.output]] or as an overriding virtual
|
| 40 |
function of any class declared in [[input.output]] calls `imbue`, the
|
| 41 |
behavior is undefined.
|
| 42 |
|
| 43 |
+
### Types <a id="stream.types">[[stream.types]]</a>
|
| 44 |
+
|
| 45 |
+
``` cpp
|
| 46 |
+
using streamoff = implementation-defined // type of streamoff;
|
| 47 |
+
```
|
| 48 |
+
|
| 49 |
+
The type `streamoff` is a synonym for one of the signed basic integral
|
| 50 |
+
types of sufficient size to represent the maximum possible file size for
|
| 51 |
+
the operating system.[^1]
|
| 52 |
+
|
| 53 |
+
``` cpp
|
| 54 |
+
using streamsize = implementation-defined;
|
| 55 |
+
```
|
| 56 |
+
|
| 57 |
+
The type `streamsize` is a synonym for one of the signed basic integral
|
| 58 |
+
types. It is used to represent the number of characters transferred in
|
| 59 |
+
an I/O operation, or the size of I/O buffers.[^2]
|
| 60 |
+
|
| 61 |
### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
|
| 62 |
|
| 63 |
The classes of [[input.output]] with template arguments `charT` and
|
| 64 |
`traits` behave as described if `traits::pos_type` and
|
| 65 |
`traits::off_type` are `streampos` and `streamoff` respectively. Except
|
| 66 |
as noted explicitly below, their behavior when `traits::pos_type` and
|
| 67 |
`traits::off_type` are other types is *implementation-defined*.
|
| 68 |
|
| 69 |
+
[*Note 1*: For each of the specializations of `char_traits` defined in
|
| 70 |
+
[[char.traits.specializations]], `state_type` denotes `mbstate_t`,
|
| 71 |
+
`pos_type` denotes `fpos<mbstate_t>`, and `off_type` denotes
|
| 72 |
+
`streamoff`. — *end note*]
|
| 73 |
+
|
| 74 |
In the classes of [[input.output]], a template parameter with name
|
| 75 |
`charT` represents a member of the set of types containing `char`,
|
| 76 |
`wchar_t`, and any other *implementation-defined* character types that
|
| 77 |
meet the requirements for a character on which any of the iostream
|
| 78 |
components can be instantiated.
|
| 79 |
|
| 80 |
### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
|
| 81 |
|
| 82 |
+
Concurrent access to a stream object
|
| 83 |
+
[[string.streams]], [[file.streams]], stream buffer object
|
| 84 |
+
[[stream.buffers]], or C Library stream [[c.files]] by multiple threads
|
| 85 |
+
may result in a data race [[intro.multithread]] unless otherwise
|
| 86 |
+
specified [[iostream.objects]].
|
| 87 |
|
| 88 |
[*Note 1*: Data races result in undefined behavior
|
| 89 |
[[intro.multithread]]. — *end note*]
|
| 90 |
|
| 91 |
If one thread makes a library call *a* that writes a value to a stream
|
|
|
|
| 130 |
class basic_ostringstream;
|
| 131 |
template<class charT, class traits = char_traits<charT>,
|
| 132 |
class Allocator = allocator<charT>>
|
| 133 |
class basic_stringstream;
|
| 134 |
|
| 135 |
+
template<class charT, class traits = char_traits<charT>>
|
| 136 |
+
class basic_spanbuf;
|
| 137 |
+
template<class charT, class traits = char_traits<charT>>
|
| 138 |
+
class basic_ispanstream;
|
| 139 |
+
template<class charT, class traits = char_traits<charT>>
|
| 140 |
+
class basic_ospanstream;
|
| 141 |
+
template<class charT, class traits = char_traits<charT>>
|
| 142 |
+
class basic_spanstream;
|
| 143 |
+
|
| 144 |
template<class charT, class traits = char_traits<charT>>
|
| 145 |
class basic_filebuf;
|
| 146 |
template<class charT, class traits = char_traits<charT>>
|
| 147 |
class basic_ifstream;
|
| 148 |
template<class charT, class traits = char_traits<charT>>
|
|
|
|
| 173 |
using stringbuf = basic_stringbuf<char>;
|
| 174 |
using istringstream = basic_istringstream<char>;
|
| 175 |
using ostringstream = basic_ostringstream<char>;
|
| 176 |
using stringstream = basic_stringstream<char>;
|
| 177 |
|
| 178 |
+
using spanbuf = basic_spanbuf<char>;
|
| 179 |
+
using ispanstream = basic_ispanstream<char>;
|
| 180 |
+
using ospanstream = basic_ospanstream<char>;
|
| 181 |
+
using spanstream = basic_spanstream<char>;
|
| 182 |
+
|
| 183 |
using filebuf = basic_filebuf<char>;
|
| 184 |
using ifstream = basic_ifstream<char>;
|
| 185 |
using ofstream = basic_ofstream<char>;
|
| 186 |
using fstream = basic_fstream<char>;
|
| 187 |
|
|
|
|
| 196 |
using wstringbuf = basic_stringbuf<wchar_t>;
|
| 197 |
using wistringstream = basic_istringstream<wchar_t>;
|
| 198 |
using wostringstream = basic_ostringstream<wchar_t>;
|
| 199 |
using wstringstream = basic_stringstream<wchar_t>;
|
| 200 |
|
| 201 |
+
using wspanbuf = basic_spanbuf<wchar_t>;
|
| 202 |
+
using wispanstream = basic_ispanstream<wchar_t>;
|
| 203 |
+
using wospanstream = basic_ospanstream<wchar_t>;
|
| 204 |
+
using wspanstream = basic_spanstream<wchar_t>;
|
| 205 |
+
|
| 206 |
using wfilebuf = basic_filebuf<wchar_t>;
|
| 207 |
using wifstream = basic_ifstream<wchar_t>;
|
| 208 |
using wofstream = basic_ofstream<wchar_t>;
|
| 209 |
using wfstream = basic_fstream<wchar_t>;
|
| 210 |
|
|
|
|
| 220 |
}
|
| 221 |
```
|
| 222 |
|
| 223 |
Default template arguments are described as appearing both in `<iosfwd>`
|
| 224 |
and in the synopsis of other headers but it is well-formed to include
|
| 225 |
+
both `<iosfwd>` and one or more of the other headers.[^3]
|
| 226 |
|
| 227 |
### Overview <a id="iostream.forward.overview">[[iostream.forward.overview]]</a>
|
| 228 |
|
| 229 |
The class template specialization `basic_ios<charT, traits>` serves as a
|
| 230 |
virtual base class for the class templates `basic_istream`,
|
|
|
|
| 299 |
and includes all the headers necessary to use these objects.
|
| 300 |
|
| 301 |
The objects are constructed and the associations are established at some
|
| 302 |
time prior to or during the first time an object of class
|
| 303 |
`ios_base::Init` is constructed, and in any case before the body of
|
| 304 |
+
`main` [[basic.start.main]] begins execution. The objects are not
|
| 305 |
+
destroyed during program execution.[^4]
|
| 306 |
+
|
| 307 |
+
*Recommended practice:* If it is possible for them to do so,
|
| 308 |
+
implementations should initialize the objects earlier than required.
|
| 309 |
+
|
| 310 |
+
The results of including `<iostream>` in a translation unit shall be as
|
| 311 |
+
if `<iostream>` defined an instance of `ios_base::Init` with static
|
| 312 |
+
storage duration. Each C++ library module [[std.modules]] in a hosted
|
| 313 |
+
implementation shall behave as if it contains an interface unit that
|
| 314 |
+
defines an unexported `ios_base::Init` variable with ordered
|
| 315 |
+
initialization [[basic.start.dynamic]].
|
| 316 |
+
|
| 317 |
+
[*Note 1*: As a result, the definition of that variable is
|
| 318 |
+
appearance-ordered before any declaration following the point of
|
| 319 |
+
importation of a C++ library module. Whether such a definition exists is
|
| 320 |
+
unobservable by a program that does not reference any of the standard
|
| 321 |
+
iostream objects. — *end note*]
|
| 322 |
|
| 323 |
Mixing operations on corresponding wide- and narrow-character streams
|
| 324 |
follows the same semantics as mixing such operations on `FILE`s, as
|
| 325 |
specified in the C standard library.
|
| 326 |
|
| 327 |
Concurrent access to a synchronized [[ios.members.static]] standard
|
| 328 |
iostream object’s formatted and unformatted input [[istream]] and output
|
| 329 |
[[ostream]] functions or a standard C stream by multiple threads does
|
| 330 |
not result in a data race [[intro.multithread]].
|
| 331 |
|
| 332 |
+
[*Note 2*: Unsynchronized concurrent use of these objects and streams
|
| 333 |
+
by multiple threads can result in interleaved characters. — *end note*]
|
|
|
|
| 334 |
|
| 335 |
See also: ISO C 7.21.2
|
| 336 |
|
| 337 |
### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
|
| 338 |
|
|
|
|
| 474 |
error_condition make_error_condition(io_errc e) noexcept;
|
| 475 |
const error_category& iostream_category() noexcept;
|
| 476 |
}
|
| 477 |
```
|
| 478 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 479 |
### Class `ios_base` <a id="ios.base">[[ios.base]]</a>
|
| 480 |
|
| 481 |
+
#### General <a id="ios.base.general">[[ios.base.general]]</a>
|
| 482 |
+
|
| 483 |
``` cpp
|
| 484 |
namespace std {
|
| 485 |
class ios_base {
|
| 486 |
public:
|
| 487 |
class failure; // see below
|
|
|
|
| 518 |
using openmode = T3;
|
| 519 |
static constexpr openmode app = unspecified;
|
| 520 |
static constexpr openmode ate = unspecified;
|
| 521 |
static constexpr openmode binary = unspecified;
|
| 522 |
static constexpr openmode in = unspecified;
|
| 523 |
+
static constexpr openmode noreplace = unspecified;
|
| 524 |
static constexpr openmode out = unspecified;
|
| 525 |
static constexpr openmode trunc = unspecified;
|
| 526 |
|
| 527 |
// [ios.seekdir], seekdir
|
| 528 |
using seekdir = T4;
|
|
|
|
| 732 |
elements indicated in [[ios.openmode]].
|
| 733 |
|
| 734 |
**Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
|
| 735 |
|
| 736 |
| Element | Effect(s) if set |
|
| 737 |
+
| ----------- | ----------------------------------------------------------------- |
|
| 738 |
| `app` | seek to end before each write |
|
| 739 |
| `ate` | open and seek to end immediately after opening |
|
| 740 |
| `binary` | perform input and output in binary mode (as opposed to text mode) |
|
| 741 |
| `in` | open for input |
|
| 742 |
+
| `noreplace` | open in exclusive mode |
|
| 743 |
| `out` | open for output |
|
| 744 |
| `trunc` | truncate an existing stream when opening |
|
| 745 |
|
| 746 |
|
| 747 |
##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
|
|
|
|
| 770 |
public:
|
| 771 |
Init();
|
| 772 |
Init(const Init&) = default;
|
| 773 |
~Init();
|
| 774 |
Init& operator=(const Init&) = default;
|
| 775 |
+
|
| 776 |
private:
|
| 777 |
static int init_cnt; // exposition only
|
| 778 |
};
|
| 779 |
}
|
| 780 |
```
|
|
|
|
| 900 |
|
| 901 |
``` cpp
|
| 902 |
static bool sync_with_stdio(bool sync = true);
|
| 903 |
```
|
| 904 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 905 |
*Effects:* If any input or output operation has occurred using the
|
| 906 |
standard streams prior to the call, the effect is
|
| 907 |
*implementation-defined*. Otherwise, called with a `false` argument, it
|
| 908 |
allows the standard streams to operate independently of the standard C
|
| 909 |
streams.
|
| 910 |
|
| 911 |
+
*Returns:* `true` if the previous state of the standard iostream
|
| 912 |
+
objects [[iostream.objects]] was synchronized and otherwise returns
|
| 913 |
+
`false`. The first time it is called, the function returns `true`.
|
| 914 |
+
|
| 915 |
+
*Remarks:* When a standard iostream object `str` is *synchronized* with
|
| 916 |
+
a standard stdio stream `f`, the effect of inserting a character `c` by
|
| 917 |
|
| 918 |
``` cpp
|
| 919 |
fputc(f, c);
|
| 920 |
```
|
| 921 |
|
|
|
|
| 949 |
|
| 950 |
``` cpp
|
| 951 |
str.rdbuf()->sputbackc(c);
|
| 952 |
```
|
| 953 |
|
| 954 |
+
for any sequence of characters.[^5]
|
| 955 |
|
| 956 |
#### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
|
| 957 |
|
| 958 |
``` cpp
|
| 959 |
static int xalloc();
|
|
|
|
| 973 |
*Effects:* If `iarray` is a null pointer, allocates an array of `long`
|
| 974 |
of unspecified size and stores a pointer to its first element in
|
| 975 |
`iarray`. The function then extends the array pointed at by `iarray` as
|
| 976 |
necessary to include the element `iarray[idx]`. Each newly allocated
|
| 977 |
element of the array is initialized to zero. The reference returned is
|
| 978 |
+
invalid after any other operation on the object.[^6]
|
| 979 |
+
|
| 980 |
+
However, the value of the storage referred to is retained, so that until
|
| 981 |
+
the next call to `copyfmt`, calling `iword` with the same index yields
|
| 982 |
+
another reference to the same value. If the function fails[^7]
|
| 983 |
+
|
| 984 |
+
and `*this` is a base class subobject of a `basic_ios<>` object or
|
| 985 |
+
subobject, the effect is equivalent to calling
|
| 986 |
+
`basic_ios<>::setstate(badbit)` on the derived object (which may throw
|
| 987 |
+
`failure`).
|
| 988 |
|
| 989 |
*Returns:* On success `iarray[idx]`. On failure, a valid `long&`
|
| 990 |
initialized to 0.
|
| 991 |
|
| 992 |
``` cpp
|
|
|
|
| 998 |
*Effects:* If `parray` is a null pointer, allocates an array of pointers
|
| 999 |
to `void` of unspecified size and stores a pointer to its first element
|
| 1000 |
in `parray`. The function then extends the array pointed at by `parray`
|
| 1001 |
as necessary to include the element `parray[idx]`. Each newly allocated
|
| 1002 |
element of the array is initialized to a null pointer. The reference
|
| 1003 |
+
returned is invalid after any other operation on the object. However,
|
| 1004 |
the value of the storage referred to is retained, so that until the next
|
| 1005 |
call to `copyfmt`, calling `pword` with the same index yields another
|
| 1006 |
+
reference to the same value. If the function fails[^8]
|
| 1007 |
+
|
| 1008 |
+
and `*this` is a base class subobject of a `basic_ios<>` object or
|
| 1009 |
+
subobject, the effect is equivalent to calling
|
| 1010 |
+
`basic_ios<>::setstate(badbit)` on the derived object (which may throw
|
| 1011 |
+
`failure`).
|
| 1012 |
|
| 1013 |
*Returns:* On success `parray[idx]`. On failure a valid `void*&`
|
| 1014 |
initialized to 0.
|
| 1015 |
|
| 1016 |
*Remarks:* After a subsequent call to `pword(int)` for the same object,
|
|
|
|
| 1050 |
```
|
| 1051 |
|
| 1052 |
*Effects:* Calls each registered callback pair `(fn, idx)`
|
| 1053 |
[[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
|
| 1054 |
that any `ios_base` member function called from within `fn` has
|
| 1055 |
+
well-defined results. Then, any memory obtained is deallocated.
|
| 1056 |
|
| 1057 |
### Class template `fpos` <a id="fpos">[[fpos]]</a>
|
| 1058 |
|
| 1059 |
``` cpp
|
| 1060 |
namespace std {
|
| 1061 |
template<class stateT> class fpos {
|
| 1062 |
public:
|
| 1063 |
// [fpos.members], members
|
| 1064 |
stateT state() const;
|
| 1065 |
void state(stateT);
|
| 1066 |
+
|
| 1067 |
+
private:
|
| 1068 |
stateT st; // exposition only
|
| 1069 |
};
|
| 1070 |
}
|
| 1071 |
```
|
| 1072 |
|
|
|
|
| 1093 |
[[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
|
| 1094 |
[[cpp17.copyassignable]]), and *Cpp17Destructible* (
|
| 1095 |
[[cpp17.destructible]]) requirements. If
|
| 1096 |
`is_trivially_copy_constructible_v<stateT>` is `true`, then
|
| 1097 |
`fpos<stateT>` has a trivial copy constructor. If
|
| 1098 |
+
`is_trivially_copy_assignable_v<stateT>` is `true`, then `fpos<stateT>`
|
| 1099 |
has a trivial copy assignment operator. If
|
| 1100 |
`is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
|
| 1101 |
a trivial destructor. All specializations of `fpos` meet the
|
| 1102 |
*Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
|
| 1103 |
*Cpp17CopyAssignable*, *Cpp17Destructible*, and
|
| 1104 |
*Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
|
| 1105 |
In addition, the expressions shown in [[fpos.operations]] are valid and
|
| 1106 |
have the indicated semantics. In that table,
|
| 1107 |
|
| 1108 |
+
- `P` refers to a specialization of `fpos`,
|
| 1109 |
- `p` and `q` refer to values of type `P` or `const P`,
|
| 1110 |
- `pl` and `ql` refer to modifiable lvalues of type `P`,
|
| 1111 |
- `O` refers to type `streamoff`, and
|
| 1112 |
+
- `o` and `o2` refer to values of type `streamoff` or `const streamoff`.
|
| 1113 |
|
| 1114 |
Stream operations that return a value of type `traits::pos_type` return
|
| 1115 |
`P(O(-1))` as an invalid value to signal an error. If this value is used
|
| 1116 |
as an argument to any `istream`, `ostream`, or `streambuf` member that
|
| 1117 |
accepts a value of type `traits::pos_type` then the behavior of that
|
|
|
|
| 1175 |
void init(basic_streambuf<charT, traits>* sb);
|
| 1176 |
void move(basic_ios& rhs);
|
| 1177 |
void move(basic_ios&& rhs);
|
| 1178 |
void swap(basic_ios& rhs) noexcept;
|
| 1179 |
void set_rdbuf(basic_streambuf<charT, traits>* sb);
|
|
|
|
| 1180 |
};
|
| 1181 |
}
|
| 1182 |
```
|
| 1183 |
|
| 1184 |
#### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
|
|
|
|
| 1314 |
`(*fn)(erase_event, *this, idx)`;
|
| 1315 |
- then, assigns to the member objects of `*this` the corresponding
|
| 1316 |
member objects of `rhs`, except that
|
| 1317 |
- `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
|
| 1318 |
- the contents of arrays pointed at by `pword` and `iword` are copied,
|
| 1319 |
+
not the pointers themselves;[^9] and
|
| 1320 |
- if any newly stored pointer values in `*this` point at objects
|
| 1321 |
stored outside the object `rhs` and those objects are destroyed when
|
| 1322 |
`rhs` is destroyed, the newly stored pointer values are altered to
|
| 1323 |
point at newly constructed copies of the objects;
|
| 1324 |
- then, calls each callback pair that was copied from `rhs` as
|
|
|
|
| 1403 |
|
| 1404 |
``` cpp
|
| 1405 |
void clear(iostate state = goodbit);
|
| 1406 |
```
|
| 1407 |
|
|
|
|
|
|
|
|
|
|
| 1408 |
*Effects:* If
|
| 1409 |
`((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
|
| 1410 |
Otherwise, the function throws an object of class `ios_base::failure`
|
| 1411 |
[[ios.failure]], constructed with *implementation-defined* argument
|
| 1412 |
values.
|
| 1413 |
|
| 1414 |
+
*Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
|
| 1415 |
+
`rdstate() == (state | ios_base::badbit)`.
|
| 1416 |
+
|
| 1417 |
``` cpp
|
| 1418 |
void setstate(iostate state);
|
| 1419 |
```
|
| 1420 |
|
| 1421 |
*Effects:* Calls `clear(rdstate() | state)` (which may throw
|
|
|
|
| 1435 |
|
| 1436 |
``` cpp
|
| 1437 |
bool fail() const;
|
| 1438 |
```
|
| 1439 |
|
| 1440 |
+
*Returns:* `true` if `failbit` or `badbit` is set in `rdstate()`.[^10]
|
| 1441 |
|
| 1442 |
``` cpp
|
| 1443 |
bool bad() const;
|
| 1444 |
```
|
| 1445 |
|
|
|
|
| 1454 |
|
| 1455 |
``` cpp
|
| 1456 |
void exceptions(iostate except);
|
| 1457 |
```
|
| 1458 |
|
|
|
|
|
|
|
| 1459 |
*Effects:* Calls `clear(rdstate())`.
|
| 1460 |
|
| 1461 |
+
*Ensures:* `except == exceptions()`.
|
| 1462 |
+
|
| 1463 |
### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
|
| 1464 |
|
| 1465 |
#### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
|
| 1466 |
|
| 1467 |
Each function specified in this subclause is a designated addressable
|
|
|
|
| 1617 |
ios_base& dec(ios_base& str);
|
| 1618 |
```
|
| 1619 |
|
| 1620 |
*Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
|
| 1621 |
|
| 1622 |
+
*Returns:* `str`.[^11]
|
| 1623 |
|
| 1624 |
``` cpp
|
| 1625 |
ios_base& hex(ios_base& str);
|
| 1626 |
```
|
| 1627 |
|
|
|
|
| 1665 |
*Effects:* Calls
|
| 1666 |
`str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
|
| 1667 |
|
| 1668 |
*Returns:* `str`.
|
| 1669 |
|
| 1670 |
+
[*Note 1*: `ios_base::hex` cannot be used to specify a hexadecimal
|
| 1671 |
+
floating-point format, because it is not part of `ios_base::floatfield`
|
| 1672 |
+
([[ios.fmtflags.const]]). — *end note*]
|
|
|
|
| 1673 |
|
| 1674 |
``` cpp
|
| 1675 |
ios_base& defaultfloat(ios_base& str);
|
| 1676 |
```
|
| 1677 |
|
|
|
|
| 1772 |
shall have a defined value and is the next element to read (to get, or
|
| 1773 |
to obtain a character value, from the sequence).
|
| 1774 |
|
| 1775 |
### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
|
| 1776 |
|
| 1777 |
+
#### General <a id="streambuf.general">[[streambuf.general]]</a>
|
| 1778 |
+
|
| 1779 |
``` cpp
|
| 1780 |
namespace std {
|
| 1781 |
template<class charT, class traits = char_traits<charT>>
|
| 1782 |
class basic_streambuf {
|
| 1783 |
public:
|
|
|
|
| 1881 |
|
| 1882 |
``` cpp
|
| 1883 |
basic_streambuf();
|
| 1884 |
```
|
| 1885 |
|
| 1886 |
+
*Effects:* Initializes:[^12]
|
| 1887 |
|
| 1888 |
- all pointer member objects to null pointers,
|
| 1889 |
+
- the `getloc()` member to a copy of the global locale, `locale()`, at
|
| 1890 |
+
the time of construction.
|
| 1891 |
|
| 1892 |
*Remarks:* Once the `getloc()` member is initialized, results of calling
|
| 1893 |
locale member functions, and of members of facets so obtained, can
|
| 1894 |
safely be cached until the next time the member `imbue` is called.
|
| 1895 |
|
|
|
|
| 2158 |
basic_streambuf* setbuf(char_type* s, streamsize n);
|
| 2159 |
```
|
| 2160 |
|
| 2161 |
*Effects:* Influences stream buffering in a way that is defined
|
| 2162 |
separately for each class derived from `basic_streambuf` in this
|
| 2163 |
+
Clause [[stringbuf.virtuals]], [[filebuf.virtuals]].
|
| 2164 |
|
| 2165 |
*Default behavior:* Does nothing. Returns `this`.
|
| 2166 |
|
| 2167 |
``` cpp
|
| 2168 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
|
|
|
| 2170 |
= ios_base::in | ios_base::out);
|
| 2171 |
```
|
| 2172 |
|
| 2173 |
*Effects:* Alters the stream positions within one or more of the
|
| 2174 |
controlled sequences in a way that is defined separately for each class
|
| 2175 |
+
derived from `basic_streambuf` in this
|
| 2176 |
+
Clause [[stringbuf.virtuals]], [[filebuf.virtuals]].
|
| 2177 |
|
| 2178 |
*Default behavior:* Returns `pos_type(off_type(-1))`.
|
| 2179 |
|
| 2180 |
``` cpp
|
| 2181 |
pos_type seekpos(pos_type sp,
|
|
|
|
| 2183 |
= ios_base::in | ios_base::out);
|
| 2184 |
```
|
| 2185 |
|
| 2186 |
*Effects:* Alters the stream positions within one or more of the
|
| 2187 |
controlled sequences in a way that is defined separately for each class
|
| 2188 |
+
derived from `basic_streambuf` in this
|
| 2189 |
+
Clause [[stringbuf]], [[filebuf]].
|
| 2190 |
|
| 2191 |
*Default behavior:* Returns `pos_type(off_type(-1))`.
|
| 2192 |
|
| 2193 |
``` cpp
|
| 2194 |
int sync();
|
|
|
|
| 2205 |
*Default behavior:* Returns zero.
|
| 2206 |
|
| 2207 |
##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
|
| 2208 |
|
| 2209 |
``` cpp
|
| 2210 |
+
streamsize showmanyc();
|
|
|
|
| 2211 |
```
|
| 2212 |
|
| 2213 |
+
[^13]
|
| 2214 |
+
|
| 2215 |
*Returns:* An estimate of the number of characters available in the
|
| 2216 |
sequence, or -1. If it returns a positive value, then successive calls
|
| 2217 |
to `underflow()` will not return `traits::eof()` until at least that
|
| 2218 |
number of characters have been extracted from the stream. If
|
| 2219 |
`showmanyc()` returns -1, then calls to `underflow()` or `uflow()` will
|
|
|
|
| 2239 |
|
| 2240 |
``` cpp
|
| 2241 |
int_type underflow();
|
| 2242 |
```
|
| 2243 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2244 |
The *pending sequence* of characters is defined as the concatenation of
|
| 2245 |
|
| 2246 |
- the empty sequence if `gptr()` is null, otherwise the characters in
|
| 2247 |
\[`gptr()`, `egptr()`), followed by
|
| 2248 |
- some (possibly empty) sequence of characters read from the input
|
|
|
|
| 2268 |
in which case the characters in \[`eback()`, `gptr()`) agree with the
|
| 2269 |
last `gptr() - eback()` characters of the backup sequence, or
|
| 2270 |
- the characters in \[`gptr() - n`, `gptr()`) agree with the backup
|
| 2271 |
sequence (where `n` is the length of the backup sequence).
|
| 2272 |
|
| 2273 |
+
*Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
|
| 2274 |
+
of the *pending sequence*, without moving the input sequence position
|
| 2275 |
+
past it. If the pending sequence is null then the function returns
|
| 2276 |
+
`traits::eof()` to indicate failure.
|
| 2277 |
+
|
| 2278 |
*Default behavior:* Returns `traits::eof()`.
|
| 2279 |
|
| 2280 |
+
*Remarks:* The public members of `basic_streambuf` call this virtual
|
| 2281 |
+
function only if `gptr()` is null or `gptr() >= egptr()`.
|
| 2282 |
+
|
| 2283 |
``` cpp
|
| 2284 |
int_type uflow();
|
| 2285 |
```
|
| 2286 |
|
| 2287 |
*Preconditions:* The constraints are the same as for `underflow()`,
|
|
|
|
| 2289 |
sequence to the backup sequence, and the pending sequence is not empty
|
| 2290 |
before the transfer.
|
| 2291 |
|
| 2292 |
*Default behavior:* Calls `underflow()`. If `underflow()` returns
|
| 2293 |
`traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
|
| 2294 |
+
of `traits::to_int_type(*gptr())` and increments the value of the next
|
| 2295 |
pointer for the input sequence.
|
| 2296 |
|
| 2297 |
*Returns:* `traits::eof()` to indicate failure.
|
| 2298 |
|
| 2299 |
##### Putback <a id="streambuf.virt.pback">[[streambuf.virt.pback]]</a>
|
| 2300 |
|
| 2301 |
``` cpp
|
| 2302 |
int_type pbackfail(int_type c = traits::eof());
|
| 2303 |
```
|
| 2304 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2305 |
The *pending sequence* is defined as for `underflow()`, with the
|
| 2306 |
modifications that
|
| 2307 |
|
| 2308 |
- If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
|
| 2309 |
input sequence is backed up one character before the pending sequence
|
|
|
|
| 2315 |
*Ensures:* On return, the constraints of `gptr()`, `eback()`, and
|
| 2316 |
`pptr()` are the same as for `underflow()`.
|
| 2317 |
|
| 2318 |
*Returns:* `traits::eof()` to indicate failure. Failure may occur
|
| 2319 |
because the input sequence could not be backed up, or if for some other
|
| 2320 |
+
reason the pointers cannot be set consistent with the constraints.
|
| 2321 |
`pbackfail()` is called only when put back has really failed.
|
| 2322 |
|
| 2323 |
Returns some value other than `traits::eof()` to indicate success.
|
| 2324 |
|
| 2325 |
*Default behavior:* Returns `traits::eof()`.
|
| 2326 |
|
| 2327 |
+
*Remarks:* The public functions of `basic_streambuf` call this virtual
|
| 2328 |
+
function only when `gptr()` is null, `gptr() == eback()`, or
|
| 2329 |
+
`traits::eq(traits::to_char_type(c), gptr()[-1])` returns `false`. Other
|
| 2330 |
+
calls shall also satisfy that constraint.
|
| 2331 |
+
|
| 2332 |
##### Put area <a id="streambuf.virt.put">[[streambuf.virt.put]]</a>
|
| 2333 |
|
| 2334 |
``` cpp
|
| 2335 |
streamsize xsputn(const char_type* s, streamsize n);
|
| 2336 |
```
|
|
|
|
| 2356 |
- the empty sequence if `pbase()` is null, otherwise the
|
| 2357 |
`pptr() - pbase()` characters beginning at `pbase()`, followed by
|
| 2358 |
- the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
|
| 2359 |
`true`, otherwise the sequence consisting of `c`.
|
| 2360 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2361 |
*Preconditions:* Every overriding definition of this virtual function
|
| 2362 |
obeys the following constraints:
|
| 2363 |
|
| 2364 |
- The effect of consuming a character on the associated output sequence
|
| 2365 |
is specified.[^16]
|
|
|
|
| 2379 |
Otherwise, returns some value other than `traits::eof()` to indicate
|
| 2380 |
success.[^17]
|
| 2381 |
|
| 2382 |
*Default behavior:* Returns `traits::eof()`.
|
| 2383 |
|
| 2384 |
+
*Remarks:* The member functions `sputc()` and `sputn()` call this
|
| 2385 |
+
function in case that no room can be found in the put buffer enough to
|
| 2386 |
+
accommodate the argument character sequence.
|
| 2387 |
+
|
| 2388 |
## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
|
| 2389 |
|
| 2390 |
### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
|
| 2391 |
|
| 2392 |
``` cpp
|
|
|
|
| 2404 |
using wiostream = basic_iostream<wchar_t>;
|
| 2405 |
|
| 2406 |
template<class charT, class traits>
|
| 2407 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 2408 |
|
| 2409 |
+
template<class Istream, class T>
|
| 2410 |
+
Istream&& operator>>(Istream&& is, T&& x);
|
| 2411 |
}
|
| 2412 |
```
|
| 2413 |
|
| 2414 |
### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
|
| 2415 |
|
|
|
|
| 2433 |
template<class charT, class traits>
|
| 2434 |
basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
|
| 2435 |
template<class charT, class traits>
|
| 2436 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 2437 |
|
| 2438 |
+
template<class Ostream, class T>
|
| 2439 |
+
Ostream&& operator<<(Ostream&& os, const T& x);
|
| 2440 |
+
|
| 2441 |
+
// [ostream.formatted.print], print functions
|
| 2442 |
+
template<class... Args>
|
| 2443 |
+
void print(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 2444 |
+
template<class... Args>
|
| 2445 |
+
void println(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 2446 |
+
|
| 2447 |
+
void vprint_unicode(ostream& os, string_view fmt, format_args args);
|
| 2448 |
+
void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
|
| 2449 |
}
|
| 2450 |
```
|
| 2451 |
|
| 2452 |
### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
|
| 2453 |
|
| 2454 |
``` cpp
|
| 2455 |
namespace std {
|
| 2456 |
+
unspecified resetiosflags(ios_base::fmtflags mask);
|
| 2457 |
+
unspecified setiosflags (ios_base::fmtflags mask);
|
| 2458 |
+
unspecified setbase(int base);
|
| 2459 |
+
template<class charT> unspecified setfill(charT c);
|
| 2460 |
+
unspecified setprecision(int n);
|
| 2461 |
+
unspecified setw(int n);
|
| 2462 |
+
template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
|
| 2463 |
+
template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
|
| 2464 |
+
template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
|
| 2465 |
+
template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
|
|
|
|
| 2466 |
|
| 2467 |
template<class charT>
|
| 2468 |
+
unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
|
| 2469 |
|
| 2470 |
template<class charT, class traits, class Allocator>
|
| 2471 |
+
unspecified quoted(const basic_string<charT, traits, Allocator>& s,
|
| 2472 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2473 |
|
| 2474 |
template<class charT, class traits, class Allocator>
|
| 2475 |
+
unspecified quoted(basic_string<charT, traits, Allocator>& s,
|
| 2476 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2477 |
|
| 2478 |
template<class charT, class traits>
|
| 2479 |
+
unspecified quoted(basic_string_view<charT, traits> s,
|
| 2480 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2481 |
}
|
| 2482 |
```
|
| 2483 |
|
| 2484 |
+
### Header `<print>` synopsis <a id="print.syn">[[print.syn]]</a>
|
| 2485 |
+
|
| 2486 |
+
``` cpp
|
| 2487 |
+
namespace std {
|
| 2488 |
+
// [print.fun], print functions
|
| 2489 |
+
template<class... Args>
|
| 2490 |
+
void print(format_string<Args...> fmt, Args&&... args);
|
| 2491 |
+
template<class... Args>
|
| 2492 |
+
void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 2493 |
+
|
| 2494 |
+
template<class... Args>
|
| 2495 |
+
void println(format_string<Args...> fmt, Args&&... args);
|
| 2496 |
+
template<class... Args>
|
| 2497 |
+
void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 2498 |
+
|
| 2499 |
+
void vprint_unicode(string_view fmt, format_args args);
|
| 2500 |
+
void vprint_unicode(FILE* stream, string_view fmt, format_args args);
|
| 2501 |
+
|
| 2502 |
+
void vprint_nonunicode(string_view fmt, format_args args);
|
| 2503 |
+
void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
|
| 2504 |
+
}
|
| 2505 |
+
```
|
| 2506 |
+
|
| 2507 |
### Input streams <a id="input.streams">[[input.streams]]</a>
|
| 2508 |
|
| 2509 |
+
#### General <a id="input.streams.general">[[input.streams.general]]</a>
|
| 2510 |
+
|
| 2511 |
+
The header `<istream>` defines two class templates and a function
|
| 2512 |
+
template that control input from a stream buffer, along with a function
|
| 2513 |
+
template that extracts from stream rvalues.
|
| 2514 |
|
| 2515 |
#### Class template `basic_istream` <a id="istream">[[istream]]</a>
|
| 2516 |
|
| 2517 |
+
##### General <a id="istream.general">[[istream.general]]</a>
|
| 2518 |
+
|
| 2519 |
+
When a function is specified with a type placeholder of
|
| 2520 |
+
`extended-floating-point-type`, the implementation provides overloads
|
| 2521 |
+
for all cv-unqualified extended floating-point types
|
| 2522 |
+
[[basic.fundamental]] in lieu of `extended-floating-{point-type}`.
|
| 2523 |
+
|
| 2524 |
``` cpp
|
| 2525 |
namespace std {
|
| 2526 |
template<class charT, class traits = char_traits<charT>>
|
| 2527 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 2528 |
public:
|
|
|
|
| 2539 |
|
| 2540 |
// [istream.sentry], prefix/suffix
|
| 2541 |
class sentry;
|
| 2542 |
|
| 2543 |
// [istream.formatted], formatted input
|
| 2544 |
+
basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
|
| 2545 |
+
basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 2546 |
+
basic_istream& operator>>(ios_base& (*pf)(ios_base&));
|
|
|
|
|
|
|
|
|
|
| 2547 |
|
| 2548 |
+
basic_istream& operator>>(bool& n);
|
| 2549 |
+
basic_istream& operator>>(short& n);
|
| 2550 |
+
basic_istream& operator>>(unsigned short& n);
|
| 2551 |
+
basic_istream& operator>>(int& n);
|
| 2552 |
+
basic_istream& operator>>(unsigned int& n);
|
| 2553 |
+
basic_istream& operator>>(long& n);
|
| 2554 |
+
basic_istream& operator>>(unsigned long& n);
|
| 2555 |
+
basic_istream& operator>>(long long& n);
|
| 2556 |
+
basic_istream& operator>>(unsigned long long& n);
|
| 2557 |
+
basic_istream& operator>>(float& f);
|
| 2558 |
+
basic_istream& operator>>(double& f);
|
| 2559 |
+
basic_istream& operator>>(long double& f);
|
| 2560 |
+
basic_istream& operator>>(extended-floating-point-type& f);
|
| 2561 |
|
| 2562 |
+
basic_istream& operator>>(void*& p);
|
| 2563 |
+
basic_istream& operator>>(basic_streambuf<char_type, traits>* sb);
|
| 2564 |
|
| 2565 |
// [istream.unformatted], unformatted input
|
| 2566 |
streamsize gcount() const;
|
| 2567 |
int_type get();
|
| 2568 |
+
basic_istream& get(char_type& c);
|
| 2569 |
+
basic_istream& get(char_type* s, streamsize n);
|
| 2570 |
+
basic_istream& get(char_type* s, streamsize n, char_type delim);
|
| 2571 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb);
|
| 2572 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb, char_type delim);
|
| 2573 |
|
| 2574 |
+
basic_istream& getline(char_type* s, streamsize n);
|
| 2575 |
+
basic_istream& getline(char_type* s, streamsize n, char_type delim);
|
| 2576 |
|
| 2577 |
+
basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
|
| 2578 |
int_type peek();
|
| 2579 |
+
basic_istream& read (char_type* s, streamsize n);
|
| 2580 |
streamsize readsome(char_type* s, streamsize n);
|
| 2581 |
|
| 2582 |
+
basic_istream& putback(char_type c);
|
| 2583 |
+
basic_istream& unget();
|
| 2584 |
int sync();
|
| 2585 |
|
| 2586 |
pos_type tellg();
|
| 2587 |
+
basic_istream& seekg(pos_type);
|
| 2588 |
+
basic_istream& seekg(off_type, ios_base::seekdir);
|
| 2589 |
|
| 2590 |
protected:
|
| 2591 |
// [istream.cons], copy/move constructor
|
| 2592 |
basic_istream(const basic_istream&) = delete;
|
| 2593 |
basic_istream(basic_istream&& rhs);
|
| 2594 |
|
| 2595 |
+
// [istream.assign], assignment and swap
|
| 2596 |
basic_istream& operator=(const basic_istream&) = delete;
|
| 2597 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2598 |
void swap(basic_istream& rhs);
|
| 2599 |
};
|
| 2600 |
|
|
|
|
| 2623 |
*formatted input functions* (or *extractors*) and the *unformatted input
|
| 2624 |
functions.* Both groups of input functions are described as if they
|
| 2625 |
obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
|
| 2626 |
or `rdbuf()->sgetc()`. They may use other public members of `istream`.
|
| 2627 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2628 |
##### Constructors <a id="istream.cons">[[istream.cons]]</a>
|
| 2629 |
|
| 2630 |
``` cpp
|
| 2631 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2632 |
```
|
|
|
|
| 2669 |
|
| 2670 |
##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
|
| 2671 |
|
| 2672 |
``` cpp
|
| 2673 |
namespace std {
|
| 2674 |
+
template<class charT, class traits>
|
| 2675 |
class basic_istream<charT, traits>::sentry {
|
| 2676 |
bool ok_; // exposition only
|
| 2677 |
+
|
| 2678 |
public:
|
| 2679 |
+
explicit sentry(basic_istream& is, bool noskipws = false);
|
| 2680 |
~sentry();
|
| 2681 |
explicit operator bool() const { return ok_; }
|
| 2682 |
sentry(const sentry&) = delete;
|
| 2683 |
sentry& operator=(const sentry&) = delete;
|
| 2684 |
};
|
|
|
|
| 2687 |
|
| 2688 |
The class `sentry` defines a class that is responsible for doing
|
| 2689 |
exception safe prefix and suffix operations.
|
| 2690 |
|
| 2691 |
``` cpp
|
| 2692 |
+
explicit sentry(basic_istream& is, bool noskipws = false);
|
| 2693 |
```
|
| 2694 |
|
| 2695 |
*Effects:* If `is.good()` is `false`, calls `is.setstate(failbit)`.
|
| 2696 |
Otherwise, prepares for formatted or unformatted input. First, if
|
| 2697 |
`is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
|
| 2698 |
to synchronize the output sequence with any associated external C
|
| 2699 |
stream. Except that this call can be suppressed if the put area of
|
| 2700 |
`is.tie()` is empty. Further an implementation is allowed to defer the
|
| 2701 |
call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
|
| 2702 |
such call occurs before the `sentry` object is destroyed, the call to
|
| 2703 |
+
`flush` may be eliminated entirely.[^18]
|
| 2704 |
+
|
| 2705 |
+
If `noskipws` is zero and `is.flags() & ios_base::skipws` is nonzero,
|
| 2706 |
+
the function extracts and discards each character as long as the next
|
| 2707 |
+
available input character `c` is a whitespace character. If
|
| 2708 |
+
`is.rdbuf()->sbumpc()` or `is.rdbuf()->sgetc()` returns `traits::eof()`,
|
| 2709 |
+
the function calls `setstate(failbit | eofbit)` (which may throw
|
| 2710 |
+
`ios_base::failure`).
|
| 2711 |
|
| 2712 |
*Remarks:* The constructor
|
| 2713 |
|
| 2714 |
``` cpp
|
| 2715 |
+
explicit sentry(basic_istream& is, bool noskipws = false)
|
| 2716 |
```
|
| 2717 |
|
| 2718 |
uses the currently imbued locale in `is`, to determine whether the next
|
| 2719 |
input character is whitespace or not.
|
| 2720 |
|
|
|
|
| 2747 |
#### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
|
| 2748 |
|
| 2749 |
##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
|
| 2750 |
|
| 2751 |
Each formatted input function begins execution by constructing an object
|
| 2752 |
+
of type `ios_base::iostate`, termed the local error state, and
|
| 2753 |
+
initializing it to `ios_base::goodbit`. It then creates an object of
|
| 2754 |
+
class `sentry` with the `noskipws` (second) argument `false`. If the
|
| 2755 |
`sentry` object returns `true`, when converted to a value of type
|
| 2756 |
+
`bool`, the function endeavors to obtain the requested input. Otherwise,
|
| 2757 |
+
if the `sentry` constructor exits by throwing an exception or if the
|
| 2758 |
+
`sentry` object produces `false` when converted to a value of type
|
| 2759 |
+
`bool`, the function returns without attempting to obtain any input. If
|
| 2760 |
+
`rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`, then
|
| 2761 |
+
`ios_base::eofbit` is set in the local error state and the input
|
| 2762 |
+
function stops trying to obtain the requested input. If an exception is
|
| 2763 |
+
thrown during input then `ios_base::badbit` is set in the local error
|
| 2764 |
+
state, `*this`’s error state is set to the local error state, and the
|
| 2765 |
+
exception is rethrown if `(exceptions() & badbit) != 0`. After
|
| 2766 |
+
extraction is done, the input function calls `setstate`, which sets
|
| 2767 |
+
`*this`’s error state to the local error state, and may throw an
|
| 2768 |
+
exception. In any case, the formatted input function destroys the
|
| 2769 |
+
`sentry` object. If no exception has been thrown, it returns `*this`.
|
| 2770 |
|
| 2771 |
##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
|
| 2772 |
|
| 2773 |
``` cpp
|
| 2774 |
+
basic_istream& operator>>(unsigned short& val);
|
| 2775 |
+
basic_istream& operator>>(unsigned int& val);
|
| 2776 |
+
basic_istream& operator>>(long& val);
|
| 2777 |
+
basic_istream& operator>>(unsigned long& val);
|
| 2778 |
+
basic_istream& operator>>(long long& val);
|
| 2779 |
+
basic_istream& operator>>(unsigned long long& val);
|
| 2780 |
+
basic_istream& operator>>(float& val);
|
| 2781 |
+
basic_istream& operator>>(double& val);
|
| 2782 |
+
basic_istream& operator>>(long double& val);
|
| 2783 |
+
basic_istream& operator>>(bool& val);
|
| 2784 |
+
basic_istream& operator>>(void*& val);
|
| 2785 |
```
|
| 2786 |
|
| 2787 |
As in the case of the inserters, these extractors depend on the locale’s
|
| 2788 |
`num_get<>` [[locale.num.get]] object to perform parsing the input
|
| 2789 |
stream data. These extractors behave as formatted input functions (as
|
| 2790 |
+
described in [[istream.formatted.reqmts]]). After a `sentry` object is
|
| 2791 |
constructed, the conversion occurs as if performed by the following code
|
| 2792 |
+
fragment, where `state` represents the input function’s local error
|
| 2793 |
+
state:
|
| 2794 |
|
| 2795 |
``` cpp
|
| 2796 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2797 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, val);
|
|
|
|
|
|
|
| 2798 |
```
|
| 2799 |
|
| 2800 |
In the above fragment, `loc` stands for the private member of the
|
| 2801 |
`basic_ios` class.
|
| 2802 |
|
|
|
|
| 2807 |
|
| 2808 |
Class `locale` relies on this type as its interface to `istream`, so
|
| 2809 |
that it does not need to depend directly on `istream`.
|
| 2810 |
|
| 2811 |
``` cpp
|
| 2812 |
+
basic_istream& operator>>(short& val);
|
| 2813 |
```
|
| 2814 |
|
| 2815 |
The conversion occurs as if performed by the following code fragment
|
| 2816 |
(using the same notation as for the preceding code fragment):
|
| 2817 |
|
| 2818 |
``` cpp
|
| 2819 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
|
|
|
| 2820 |
long lval;
|
| 2821 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, lval);
|
| 2822 |
if (lval < numeric_limits<short>::min()) {
|
| 2823 |
+
state |= ios_base::failbit;
|
| 2824 |
val = numeric_limits<short>::min();
|
| 2825 |
} else if (numeric_limits<short>::max() < lval) {
|
| 2826 |
+
state |= ios_base::failbit;
|
| 2827 |
val = numeric_limits<short>::max();
|
| 2828 |
} else
|
| 2829 |
val = static_cast<short>(lval);
|
|
|
|
| 2830 |
```
|
| 2831 |
|
| 2832 |
``` cpp
|
| 2833 |
+
basic_istream& operator>>(int& val);
|
| 2834 |
```
|
| 2835 |
|
| 2836 |
The conversion occurs as if performed by the following code fragment
|
| 2837 |
(using the same notation as for the preceding code fragment):
|
| 2838 |
|
| 2839 |
``` cpp
|
| 2840 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
|
|
|
| 2841 |
long lval;
|
| 2842 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, lval);
|
| 2843 |
if (lval < numeric_limits<int>::min()) {
|
| 2844 |
+
state |= ios_base::failbit;
|
| 2845 |
val = numeric_limits<int>::min();
|
| 2846 |
} else if (numeric_limits<int>::max() < lval) {
|
| 2847 |
+
state |= ios_base::failbit;
|
| 2848 |
val = numeric_limits<int>::max();
|
| 2849 |
} else
|
| 2850 |
val = static_cast<int>(lval);
|
|
|
|
| 2851 |
```
|
| 2852 |
|
| 2853 |
+
``` cpp
|
| 2854 |
+
basic_istream& operator>>(extended-floating-point-type& val);
|
| 2855 |
+
```
|
| 2856 |
+
|
| 2857 |
+
If the floating-point conversion rank of
|
| 2858 |
+
*`extended-floating-point-type`* is not less than or equal to that of
|
| 2859 |
+
`long double`, then an invocation of the operator function is
|
| 2860 |
+
conditionally supported with *implementation-defined* semantics.
|
| 2861 |
+
|
| 2862 |
+
Otherwise, let `FP` be a standard floating-point type:
|
| 2863 |
+
|
| 2864 |
+
- if the floating-point conversion rank of
|
| 2865 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 2866 |
+
`float`, then `FP` is `float`,
|
| 2867 |
+
- otherwise, if the floating-point conversion rank of
|
| 2868 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 2869 |
+
`double`, then `FP` is `double`,
|
| 2870 |
+
- otherwise, `FP` is `long double`.
|
| 2871 |
+
|
| 2872 |
+
The conversion occurs as if performed by the following code fragment
|
| 2873 |
+
(using the same notation as for the preceding code fragment):
|
| 2874 |
+
|
| 2875 |
+
``` cpp
|
| 2876 |
+
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2877 |
+
FP fval;
|
| 2878 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, fval);
|
| 2879 |
+
if (fval < -numeric_limits<extended-floating-point-type>::max()) {
|
| 2880 |
+
state |= ios_base::failbit;
|
| 2881 |
+
val = -numeric_limits<extended-floating-point-type>::max();
|
| 2882 |
+
} else if (numeric_limits<extended-floating-point-type>::max() < fval) {
|
| 2883 |
+
state |= ios_base::failbit;
|
| 2884 |
+
val = numeric_limits<extended-floating-point-type>::max();
|
| 2885 |
+
} else {
|
| 2886 |
+
val = static_cast<extended-floating-point-type>(fval);
|
| 2887 |
+
}
|
| 2888 |
+
```
|
| 2889 |
+
|
| 2890 |
+
[*Note 2*: When the extended floating-point type has a floating-point
|
| 2891 |
+
conversion rank that is not equal to the rank of any standard
|
| 2892 |
+
floating-point type, then double rounding during the conversion can
|
| 2893 |
+
result in inaccurate results. `from_chars` can be used in situations
|
| 2894 |
+
where maximum accuracy is important. — *end note*]
|
| 2895 |
+
|
| 2896 |
##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
|
| 2897 |
|
| 2898 |
``` cpp
|
| 2899 |
+
basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
|
|
|
|
| 2900 |
```
|
| 2901 |
|
| 2902 |
*Effects:* None. This extractor does not behave as a formatted input
|
| 2903 |
function (as described in [[istream.formatted.reqmts]]).
|
| 2904 |
|
| 2905 |
+
*Returns:* `pf(*this)`. [^20]
|
| 2906 |
|
| 2907 |
``` cpp
|
| 2908 |
+
basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
|
|
|
| 2909 |
```
|
| 2910 |
|
| 2911 |
*Effects:* Calls `pf(*this)`. This extractor does not behave as a
|
| 2912 |
formatted input function (as described
|
| 2913 |
in [[istream.formatted.reqmts]]).
|
| 2914 |
|
| 2915 |
*Returns:* `*this`.
|
| 2916 |
|
| 2917 |
``` cpp
|
| 2918 |
+
basic_istream& operator>>(ios_base& (*pf)(ios_base&));
|
| 2919 |
```
|
| 2920 |
|
| 2921 |
+
*Effects:* Calls `pf(*this)`.[^21]
|
| 2922 |
+
|
| 2923 |
+
This extractor does not behave as a formatted input function (as
|
| 2924 |
+
described in [[istream.formatted.reqmts]]).
|
| 2925 |
|
| 2926 |
*Returns:* `*this`.
|
| 2927 |
|
| 2928 |
``` cpp
|
| 2929 |
template<class charT, class traits, size_t N>
|
|
|
|
| 2949 |
|
| 2950 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 2951 |
which may be the first position if no characters were extracted.
|
| 2952 |
`operator>>` then calls `width(0)`.
|
| 2953 |
|
| 2954 |
+
If the function extracted no characters, `ios_base::failbit` is set in
|
| 2955 |
+
the input function’s local error state before `setstate` is called.
|
| 2956 |
|
| 2957 |
*Returns:* `in`.
|
| 2958 |
|
| 2959 |
``` cpp
|
| 2960 |
template<class charT, class traits>
|
|
|
|
| 2964 |
template<class traits>
|
| 2965 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
|
| 2966 |
```
|
| 2967 |
|
| 2968 |
*Effects:* Behaves like a formatted input member (as described
|
| 2969 |
+
in [[istream.formatted.reqmts]]) of `in`. A character is extracted from
|
| 2970 |
+
`in`, if one is available, and stored in `c`. Otherwise,
|
| 2971 |
+
`ios_base::failbit` is set in the input function’s local error state
|
| 2972 |
+
before `setstate` is called.
|
| 2973 |
|
| 2974 |
*Returns:* `in`.
|
| 2975 |
|
| 2976 |
``` cpp
|
| 2977 |
+
basic_istream& operator>>(basic_streambuf<charT, traits>* sb);
|
| 2978 |
```
|
| 2979 |
|
| 2980 |
*Effects:* Behaves as an unformatted input
|
| 2981 |
function [[istream.unformatted]]. If `sb` is null, calls
|
| 2982 |
`setstate(failbit)`, which may throw `ios_base::failure`
|
| 2983 |
+
[[iostate.flags]]. After a `sentry` object is constructed, extracts
|
| 2984 |
characters from `*this` and inserts them in the output sequence
|
| 2985 |
controlled by `sb`. Characters are extracted and inserted until any of
|
| 2986 |
the following occurs:
|
| 2987 |
|
| 2988 |
- end-of-file occurs on the input sequence;
|
| 2989 |
- inserting in the output sequence fails (in which case the character to
|
| 2990 |
be inserted is not extracted);
|
| 2991 |
- an exception occurs (in which case the exception is caught).
|
| 2992 |
|
| 2993 |
+
If the function inserts no characters, `ios_base::failbit` is set in the
|
| 2994 |
+
input function’s local error state before `setstate` is called.
|
|
|
|
|
|
|
|
|
|
| 2995 |
|
| 2996 |
*Returns:* `*this`.
|
| 2997 |
|
| 2998 |
#### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
|
| 2999 |
|
| 3000 |
Each unformatted input function begins execution by constructing an
|
| 3001 |
+
object of type `ios_base::iostate`, termed the local error state, and
|
| 3002 |
+
initializing it to `ios_base::goodbit`. It then creates an object of
|
| 3003 |
+
class `sentry` with the default argument `noskipws` (second) argument
|
| 3004 |
+
`true`. If the `sentry` object returns `true`, when converted to a value
|
| 3005 |
+
of type `bool`, the function endeavors to obtain the requested input.
|
| 3006 |
+
Otherwise, if the `sentry` constructor exits by throwing an exception or
|
| 3007 |
+
if the `sentry` object produces `false`, when converted to a value of
|
| 3008 |
+
type `bool`, the function returns without attempting to obtain any
|
| 3009 |
+
input. In either case the number of extracted characters is set to 0;
|
| 3010 |
+
unformatted input functions taking a character array of nonzero size as
|
| 3011 |
+
an argument shall also store a null character (using `charT()`) in the
|
| 3012 |
+
first location of the array. If `rdbuf()->sbumpc()` or
|
| 3013 |
+
`rdbuf()->sgetc()` returns `traits::eof()`, then `ios_base::eofbit` is
|
| 3014 |
+
set in the local error state and the input function stops trying to
|
| 3015 |
+
obtain the requested input. If an exception is thrown during input then
|
| 3016 |
+
`ios_base::badbit` is set in the local error state, `*this`’s error
|
| 3017 |
+
state is set to the local error state, and the exception is rethrown if
|
| 3018 |
+
`(exceptions() & badbit) != 0`. If no exception has been thrown it
|
| 3019 |
+
stores the number of characters extracted in a member object. After
|
| 3020 |
+
extraction is done, the input function calls `setstate`, which sets
|
| 3021 |
+
`*this`’s error state to the local error state, and may throw an
|
| 3022 |
+
exception. In any event the `sentry` object is destroyed before leaving
|
| 3023 |
+
the unformatted input function.
|
| 3024 |
|
| 3025 |
``` cpp
|
| 3026 |
streamsize gcount() const;
|
| 3027 |
```
|
| 3028 |
|
| 3029 |
*Effects:* None. This member function does not behave as an unformatted
|
| 3030 |
input function (as described above).
|
| 3031 |
|
| 3032 |
*Returns:* The number of characters extracted by the last unformatted
|
| 3033 |
+
input member function called for the object. If the number cannot be
|
| 3034 |
+
represented, returns `numeric_limits<streamsize>::max()`.
|
| 3035 |
|
| 3036 |
``` cpp
|
| 3037 |
int_type get();
|
| 3038 |
```
|
| 3039 |
|
| 3040 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3041 |
+
above). After constructing a `sentry` object, extracts a character `c`,
|
| 3042 |
+
if one is available. Otherwise, `ios_base::failbit` is set in the input
|
| 3043 |
+
function’s local error state before `setstate` is called.
|
| 3044 |
|
| 3045 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 3046 |
|
| 3047 |
``` cpp
|
| 3048 |
+
basic_istream& get(char_type& c);
|
| 3049 |
```
|
| 3050 |
|
| 3051 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3052 |
+
above). After constructing a `sentry` object, extracts a character, if
|
| 3053 |
+
one is available, and assigns it to `c`.[^22]
|
| 3054 |
+
|
| 3055 |
+
Otherwise, `ios_base::failbit` is set in the input function’s local
|
| 3056 |
+
error state before `setstate` is called.
|
| 3057 |
|
| 3058 |
*Returns:* `*this`.
|
| 3059 |
|
| 3060 |
``` cpp
|
| 3061 |
+
basic_istream& get(char_type* s, streamsize n, char_type delim);
|
| 3062 |
```
|
| 3063 |
|
| 3064 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3065 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 3066 |
stores them into successive locations of an array whose first element is
|
| 3067 |
+
designated by `s`.[^23]
|
| 3068 |
+
|
| 3069 |
+
Characters are extracted and stored until any of the following occurs:
|
| 3070 |
|
| 3071 |
- `n` is less than one or `n - 1` characters are stored;
|
| 3072 |
+
- end-of-file occurs on the input sequence;
|
|
|
|
| 3073 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 3074 |
which case `c` is not extracted).
|
| 3075 |
|
| 3076 |
+
If the function stores no characters, `ios_base::failbit` is set in the
|
| 3077 |
+
input function’s local error state before `setstate` is called. In any
|
| 3078 |
+
case, if `n` is greater than zero it then stores a null character into
|
| 3079 |
+
the next successive location of the array.
|
| 3080 |
|
| 3081 |
*Returns:* `*this`.
|
| 3082 |
|
| 3083 |
``` cpp
|
| 3084 |
+
basic_istream& get(char_type* s, streamsize n);
|
| 3085 |
```
|
| 3086 |
|
| 3087 |
*Effects:* Calls `get(s, n, widen(’\n’))`.
|
| 3088 |
|
| 3089 |
*Returns:* Value returned by the call.
|
| 3090 |
|
| 3091 |
``` cpp
|
| 3092 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb, char_type delim);
|
| 3093 |
```
|
| 3094 |
|
| 3095 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3096 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 3097 |
inserts them in the output sequence controlled by `sb`. Characters are
|
| 3098 |
extracted and inserted until any of the following occurs:
|
| 3099 |
|
| 3100 |
- end-of-file occurs on the input sequence;
|
| 3101 |
- inserting in the output sequence fails (in which case the character to
|
|
|
|
| 3103 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 3104 |
which case `c` is not extracted);
|
| 3105 |
- an exception occurs (in which case, the exception is caught but not
|
| 3106 |
rethrown).
|
| 3107 |
|
| 3108 |
+
If the function inserts no characters, `ios_base::failbit` is set in the
|
| 3109 |
+
input function’s local error state before `setstate` is called.
|
| 3110 |
|
| 3111 |
*Returns:* `*this`.
|
| 3112 |
|
| 3113 |
``` cpp
|
| 3114 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb);
|
| 3115 |
```
|
| 3116 |
|
| 3117 |
*Effects:* Calls `get(sb, widen(’\n’))`.
|
| 3118 |
|
| 3119 |
*Returns:* Value returned by the call.
|
| 3120 |
|
| 3121 |
``` cpp
|
| 3122 |
+
basic_istream& getline(char_type* s, streamsize n, char_type delim);
|
| 3123 |
```
|
| 3124 |
|
| 3125 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3126 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 3127 |
stores them into successive locations of an array whose first element is
|
| 3128 |
+
designated by `s`.[^24]
|
|
|
|
| 3129 |
|
| 3130 |
+
Characters are extracted and stored until one of the following occurs:
|
| 3131 |
+
|
| 3132 |
+
1. end-of-file occurs on the input sequence;
|
| 3133 |
2. `traits::eq(c, delim)` for the next available input character `c`
|
| 3134 |
(in which case the input character is extracted but not
|
| 3135 |
+
stored);[^25]
|
| 3136 |
3. `n` is less than one or `n - 1` characters are stored (in which case
|
| 3137 |
the function calls `setstate(failbit)`).
|
| 3138 |
|
| 3139 |
+
These conditions are tested in the order shown.[^26]
|
| 3140 |
|
| 3141 |
+
If the function extracts no characters, `ios_base::failbit` is set in
|
| 3142 |
+
the input function’s local error state before `setstate` is called.[^27]
|
| 3143 |
|
| 3144 |
In any case, if `n` is greater than zero, it then stores a null
|
| 3145 |
character (using `charT()`) into the next successive location of the
|
| 3146 |
array.
|
| 3147 |
|
|
|
|
| 3175 |
```
|
| 3176 |
|
| 3177 |
— *end example*]
|
| 3178 |
|
| 3179 |
``` cpp
|
| 3180 |
+
basic_istream& getline(char_type* s, streamsize n);
|
| 3181 |
```
|
| 3182 |
|
| 3183 |
*Returns:* `getline(s, n, widen(’\n’))`
|
| 3184 |
|
| 3185 |
``` cpp
|
| 3186 |
+
basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
|
| 3187 |
```
|
| 3188 |
|
| 3189 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3190 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 3191 |
discards them. Characters are extracted until any of the following
|
| 3192 |
occurs:
|
| 3193 |
|
| 3194 |
- `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
|
| 3195 |
characters have been extracted so far
|
|
|
|
| 3197 |
calls `setstate(eofbit)`, which may throw `ios_base::failure`
|
| 3198 |
[[iostate.flags]]);
|
| 3199 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
| 3200 |
available input character `c` (in which case `c` is extracted).
|
| 3201 |
|
| 3202 |
+
[*Note 1*: The last condition will never occur if
|
| 3203 |
+
`traits::eq_int_type(delim, traits::eof())`. — *end note*]
|
| 3204 |
|
| 3205 |
*Returns:* `*this`.
|
| 3206 |
|
| 3207 |
``` cpp
|
| 3208 |
int_type peek();
|
| 3209 |
```
|
| 3210 |
|
| 3211 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3212 |
+
above). After constructing a `sentry` object, reads but does not extract
|
| 3213 |
the current input character.
|
| 3214 |
|
| 3215 |
*Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
|
| 3216 |
`rdbuf()->sgetc()`.
|
| 3217 |
|
| 3218 |
``` cpp
|
| 3219 |
+
basic_istream& read(char_type* s, streamsize n);
|
| 3220 |
```
|
| 3221 |
|
| 3222 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3223 |
+
above). After constructing a `sentry` object, if `!good()` calls
|
| 3224 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3225 |
extracts characters and stores them into successive locations of an
|
| 3226 |
+
array whose first element is designated by `s`.[^28]
|
| 3227 |
+
|
| 3228 |
+
Characters are extracted and stored until either of the following
|
| 3229 |
+
occurs:
|
| 3230 |
|
| 3231 |
- `n` characters are stored;
|
| 3232 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3233 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 3234 |
`ios_base::failure` [[iostate.flags]]).
|
|
|
|
| 3238 |
``` cpp
|
| 3239 |
streamsize readsome(char_type* s, streamsize n);
|
| 3240 |
```
|
| 3241 |
|
| 3242 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3243 |
+
above). After constructing a `sentry` object, if `!good()` calls
|
| 3244 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3245 |
extracts characters and stores them into successive locations of an
|
| 3246 |
array whose first element is designated by `s`. If
|
| 3247 |
`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
|
| 3248 |
`ios_base::failure` [[iostate.flags]]), and extracts no characters;
|
|
|
|
| 3251 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 3252 |
|
| 3253 |
*Returns:* The number of characters extracted.
|
| 3254 |
|
| 3255 |
``` cpp
|
| 3256 |
+
basic_istream& putback(char_type c);
|
| 3257 |
```
|
| 3258 |
|
| 3259 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3260 |
above), except that the function first clears `eofbit`. After
|
| 3261 |
+
constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
|
| 3262 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3263 |
calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
|
| 3264 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3265 |
`ios_base::failure` [[iostate.flags]]).
|
| 3266 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3267 |
[*Note 2*: This function extracts no characters, so the value returned
|
| 3268 |
by the next call to `gcount()` is 0. — *end note*]
|
| 3269 |
|
| 3270 |
*Returns:* `*this`.
|
| 3271 |
|
| 3272 |
+
``` cpp
|
| 3273 |
+
basic_istream& unget();
|
| 3274 |
+
```
|
| 3275 |
+
|
| 3276 |
+
*Effects:* Behaves as an unformatted input function (as described
|
| 3277 |
+
above), except that the function first clears `eofbit`. After
|
| 3278 |
+
constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
|
| 3279 |
+
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3280 |
+
calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
|
| 3281 |
+
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3282 |
+
`ios_base::failure` [[iostate.flags]]).
|
| 3283 |
+
|
| 3284 |
+
[*Note 3*: This function extracts no characters, so the value returned
|
| 3285 |
+
by the next call to `gcount()` is 0. — *end note*]
|
| 3286 |
+
|
| 3287 |
+
*Returns:* `*this`.
|
| 3288 |
+
|
| 3289 |
``` cpp
|
| 3290 |
int sync();
|
| 3291 |
```
|
| 3292 |
|
| 3293 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3294 |
above), except that it does not count the number of characters extracted
|
| 3295 |
and does not affect the value returned by subsequent calls to
|
| 3296 |
+
`gcount()`. After constructing a `sentry` object, if `rdbuf()` is a null
|
| 3297 |
pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
|
| 3298 |
that function returns `-1` calls `setstate(badbit)` (which may throw
|
| 3299 |
`ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
|
| 3300 |
returns zero.
|
| 3301 |
|
|
|
|
| 3306 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3307 |
above), except that it does not count the number of characters extracted
|
| 3308 |
and does not affect the value returned by subsequent calls to
|
| 3309 |
`gcount()`.
|
| 3310 |
|
| 3311 |
+
*Returns:* After constructing a `sentry` object, if `fail() != false`,
|
| 3312 |
returns `pos_type(-1)` to indicate failure. Otherwise, returns
|
| 3313 |
`rdbuf()->pubseekoff(0, cur, in)`.
|
| 3314 |
|
| 3315 |
``` cpp
|
| 3316 |
+
basic_istream& seekg(pos_type pos);
|
| 3317 |
```
|
| 3318 |
|
| 3319 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3320 |
above), except that the function first clears `eofbit`, it does not
|
| 3321 |
count the number of characters extracted, and it does not affect the
|
| 3322 |
value returned by subsequent calls to `gcount()`. After constructing a
|
| 3323 |
+
`sentry` object, if `fail() != true`, executes
|
| 3324 |
`rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
|
| 3325 |
function calls `setstate(failbit)` (which may throw
|
| 3326 |
`ios_base::failure`).
|
| 3327 |
|
| 3328 |
*Returns:* `*this`.
|
| 3329 |
|
| 3330 |
``` cpp
|
| 3331 |
+
basic_istream& seekg(off_type off, ios_base::seekdir dir);
|
| 3332 |
```
|
| 3333 |
|
| 3334 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3335 |
above), except that the function first clears `eofbit`, does not count
|
| 3336 |
the number of characters extracted, and does not affect the value
|
| 3337 |
+
returned by subsequent calls to `gcount()`. After constructing a
|
| 3338 |
+
`sentry` object, if `fail() != true`, executes
|
| 3339 |
`rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
|
| 3340 |
function calls `setstate(failbit)` (which may throw
|
| 3341 |
`ios_base::failure`).
|
| 3342 |
|
| 3343 |
*Returns:* `*this`.
|
|
|
|
| 3353 |
```
|
| 3354 |
|
| 3355 |
*Effects:* Behaves as an unformatted input
|
| 3356 |
function [[istream.unformatted]], except that it does not count the
|
| 3357 |
number of characters extracted and does not affect the value returned by
|
| 3358 |
+
subsequent calls to `is.gcount()`. After constructing a `sentry` object
|
| 3359 |
extracts characters as long as the next available character `c` is
|
| 3360 |
whitespace or until there are no more characters in the sequence.
|
| 3361 |
Whitespace characters are distinguished with the same criterion as used
|
| 3362 |
by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
|
| 3363 |
characters because there are no more available it sets `eofbit`, but not
|
|
|
|
| 3371 |
template<class Istream, class T>
|
| 3372 |
Istream&& operator>>(Istream&& is, T&& x);
|
| 3373 |
```
|
| 3374 |
|
| 3375 |
*Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
|
| 3376 |
+
when treated as an unevaluated operand [[term.unevaluated.operand]] and
|
| 3377 |
+
`Istream` is publicly and unambiguously derived from `ios_base`.
|
| 3378 |
|
| 3379 |
*Effects:* Equivalent to:
|
| 3380 |
|
| 3381 |
``` cpp
|
| 3382 |
is >> std::forward<T>(x);
|
| 3383 |
return std::move(is);
|
| 3384 |
```
|
| 3385 |
|
| 3386 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 3387 |
|
| 3388 |
+
##### General <a id="iostreamclass.general">[[iostreamclass.general]]</a>
|
| 3389 |
+
|
| 3390 |
``` cpp
|
| 3391 |
namespace std {
|
| 3392 |
template<class charT, class traits = char_traits<charT>>
|
| 3393 |
class basic_iostream
|
| 3394 |
: public basic_istream<charT, traits>,
|
|
|
|
| 3409 |
protected:
|
| 3410 |
// [iostream.cons], constructor
|
| 3411 |
basic_iostream(const basic_iostream&) = delete;
|
| 3412 |
basic_iostream(basic_iostream&& rhs);
|
| 3413 |
|
| 3414 |
+
// [iostream.assign], assignment and swap
|
| 3415 |
basic_iostream& operator=(const basic_iostream&) = delete;
|
| 3416 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3417 |
void swap(basic_iostream& rhs);
|
| 3418 |
};
|
| 3419 |
}
|
|
|
|
| 3438 |
``` cpp
|
| 3439 |
basic_iostream(basic_iostream&& rhs);
|
| 3440 |
```
|
| 3441 |
|
| 3442 |
*Effects:* Move constructs from the rvalue `rhs` by constructing the
|
| 3443 |
+
`basic_istream` base class with `std::move(rhs)`.
|
| 3444 |
|
| 3445 |
##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
|
| 3446 |
|
| 3447 |
``` cpp
|
| 3448 |
virtual ~basic_iostream();
|
|
|
|
| 3464 |
|
| 3465 |
*Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
|
| 3466 |
|
| 3467 |
### Output streams <a id="output.streams">[[output.streams]]</a>
|
| 3468 |
|
| 3469 |
+
#### General <a id="output.streams.general">[[output.streams.general]]</a>
|
| 3470 |
+
|
| 3471 |
+
The header `<ostream>` defines a class template and several function
|
| 3472 |
+
templates that control output to a stream buffer, along with a function
|
| 3473 |
+
template that inserts into stream rvalues.
|
| 3474 |
|
| 3475 |
#### Class template `basic_ostream` <a id="ostream">[[ostream]]</a>
|
| 3476 |
|
| 3477 |
+
##### General <a id="ostream.general">[[ostream.general]]</a>
|
| 3478 |
+
|
| 3479 |
+
When a function has a parameter type `extended-floating-point-type`, the
|
| 3480 |
+
implementation provides overloads for all cv-unqualified extended
|
| 3481 |
+
floating-point types [[basic.fundamental]].
|
| 3482 |
+
|
| 3483 |
``` cpp
|
| 3484 |
namespace std {
|
| 3485 |
template<class charT, class traits = char_traits<charT>>
|
| 3486 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 3487 |
public:
|
|
|
|
| 3498 |
|
| 3499 |
// [ostream.sentry], prefix/suffix
|
| 3500 |
class sentry;
|
| 3501 |
|
| 3502 |
// [ostream.formatted], formatted output
|
| 3503 |
+
basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&));
|
| 3504 |
+
basic_ostream& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 3505 |
+
basic_ostream& operator<<(ios_base& (*pf)(ios_base&));
|
|
|
|
|
|
|
|
|
|
| 3506 |
|
| 3507 |
+
basic_ostream& operator<<(bool n);
|
| 3508 |
+
basic_ostream& operator<<(short n);
|
| 3509 |
+
basic_ostream& operator<<(unsigned short n);
|
| 3510 |
+
basic_ostream& operator<<(int n);
|
| 3511 |
+
basic_ostream& operator<<(unsigned int n);
|
| 3512 |
+
basic_ostream& operator<<(long n);
|
| 3513 |
+
basic_ostream& operator<<(unsigned long n);
|
| 3514 |
+
basic_ostream& operator<<(long long n);
|
| 3515 |
+
basic_ostream& operator<<(unsigned long long n);
|
| 3516 |
+
basic_ostream& operator<<(float f);
|
| 3517 |
+
basic_ostream& operator<<(double f);
|
| 3518 |
+
basic_ostream& operator<<(long double f);
|
| 3519 |
+
basic_ostream& operator<<(extended-floating-point-type f);
|
| 3520 |
|
| 3521 |
+
basic_ostream& operator<<(const void* p);
|
| 3522 |
+
basic_ostream& operator<<(const volatile void* p);
|
| 3523 |
+
basic_ostream& operator<<(nullptr_t);
|
| 3524 |
+
basic_ostream& operator<<(basic_streambuf<char_type, traits>* sb);
|
| 3525 |
|
| 3526 |
// [ostream.unformatted], unformatted output
|
| 3527 |
+
basic_ostream& put(char_type c);
|
| 3528 |
+
basic_ostream& write(const char_type* s, streamsize n);
|
| 3529 |
|
| 3530 |
+
basic_ostream& flush();
|
| 3531 |
|
| 3532 |
// [ostream.seeks], seeks
|
| 3533 |
pos_type tellp();
|
| 3534 |
+
basic_ostream& seekp(pos_type);
|
| 3535 |
+
basic_ostream& seekp(off_type, ios_base::seekdir);
|
| 3536 |
|
| 3537 |
protected:
|
| 3538 |
// [ostream.cons], copy/move constructor
|
| 3539 |
basic_ostream(const basic_ostream&) = delete;
|
| 3540 |
basic_ostream(basic_ostream&& rhs);
|
| 3541 |
|
| 3542 |
+
// [ostream.assign], assignment and swap
|
| 3543 |
basic_ostream& operator=(const basic_ostream&) = delete;
|
| 3544 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3545 |
void swap(basic_ostream& rhs);
|
| 3546 |
};
|
| 3547 |
|
|
|
|
| 3677 |
|
| 3678 |
##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
|
| 3679 |
|
| 3680 |
``` cpp
|
| 3681 |
namespace std {
|
| 3682 |
+
template<class charT, class traits>
|
| 3683 |
class basic_ostream<charT, traits>::sentry {
|
| 3684 |
bool ok_; // exposition only
|
| 3685 |
+
|
| 3686 |
public:
|
| 3687 |
+
explicit sentry(basic_ostream& os);
|
| 3688 |
~sentry();
|
| 3689 |
explicit operator bool() const { return ok_; }
|
| 3690 |
|
| 3691 |
sentry(const sentry&) = delete;
|
| 3692 |
sentry& operator=(const sentry&) = delete;
|
|
|
|
| 3696 |
|
| 3697 |
The class `sentry` defines a class that is responsible for doing
|
| 3698 |
exception safe prefix and suffix operations.
|
| 3699 |
|
| 3700 |
``` cpp
|
| 3701 |
+
explicit sentry(basic_ostream& os);
|
| 3702 |
```
|
| 3703 |
|
| 3704 |
If `os.good()` is nonzero, prepares for formatted or unformatted output.
|
| 3705 |
+
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
|
| 3706 |
|
| 3707 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 3708 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 3709 |
constructor may call `setstate(failbit)` (which may throw
|
| 3710 |
+
`ios_base::failure` [[iostate.flags]]).[^30]
|
| 3711 |
|
| 3712 |
``` cpp
|
| 3713 |
~sentry();
|
| 3714 |
```
|
| 3715 |
|
|
|
|
| 3735 |
|
| 3736 |
*Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
|
| 3737 |
failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
|
| 3738 |
|
| 3739 |
``` cpp
|
| 3740 |
+
basic_ostream& seekp(pos_type pos);
|
| 3741 |
```
|
| 3742 |
|
| 3743 |
*Effects:* If `fail() != true`, executes
|
| 3744 |
`rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
|
| 3745 |
function calls `setstate(failbit)` (which may throw
|
| 3746 |
`ios_base::failure`).
|
| 3747 |
|
| 3748 |
*Returns:* `*this`.
|
| 3749 |
|
| 3750 |
``` cpp
|
| 3751 |
+
basic_ostream& seekp(off_type off, ios_base::seekdir dir);
|
| 3752 |
```
|
| 3753 |
|
| 3754 |
*Effects:* If `fail() != true`, executes
|
| 3755 |
`rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
|
| 3756 |
function calls `setstate(failbit)` (which may throw
|
|
|
|
| 3761 |
#### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
|
| 3762 |
|
| 3763 |
##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
|
| 3764 |
|
| 3765 |
Each formatted output function begins execution by constructing an
|
| 3766 |
+
object of class `sentry`. If that object returns `true` when converted
|
| 3767 |
to a value of type `bool`, the function endeavors to generate the
|
| 3768 |
requested output. If the generation fails, then the formatted output
|
| 3769 |
+
function does `setstate(ios_base::failbit)`, which can throw an
|
| 3770 |
exception. If an exception is thrown during output, then
|
| 3771 |
+
`ios_base::badbit` is set[^31]
|
| 3772 |
+
|
| 3773 |
+
in `*this`’s error state. If `(exceptions()&badbit) != 0` then the
|
| 3774 |
+
exception is rethrown. Whether or not an exception is thrown, the
|
| 3775 |
+
`sentry` object is destroyed before leaving the formatted output
|
| 3776 |
+
function. If no exception is thrown, the result of the formatted output
|
| 3777 |
+
function is `*this`.
|
| 3778 |
|
| 3779 |
The descriptions of the individual formatted output functions describe
|
| 3780 |
how they perform output and do not mention the `sentry` object.
|
| 3781 |
|
| 3782 |
If a formatted output function of a stream `os` determines padding, it
|
|
|
|
| 3789 |
they are placed before the character sequence.
|
| 3790 |
|
| 3791 |
##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
|
| 3792 |
|
| 3793 |
``` cpp
|
| 3794 |
+
basic_ostream& operator<<(bool val);
|
| 3795 |
+
basic_ostream& operator<<(short val);
|
| 3796 |
+
basic_ostream& operator<<(unsigned short val);
|
| 3797 |
+
basic_ostream& operator<<(int val);
|
| 3798 |
+
basic_ostream& operator<<(unsigned int val);
|
| 3799 |
+
basic_ostream& operator<<(long val);
|
| 3800 |
+
basic_ostream& operator<<(unsigned long val);
|
| 3801 |
+
basic_ostream& operator<<(long long val);
|
| 3802 |
+
basic_ostream& operator<<(unsigned long long val);
|
| 3803 |
+
basic_ostream& operator<<(float val);
|
| 3804 |
+
basic_ostream& operator<<(double val);
|
| 3805 |
+
basic_ostream& operator<<(long double val);
|
| 3806 |
+
basic_ostream& operator<<(const void* val);
|
| 3807 |
```
|
| 3808 |
|
| 3809 |
*Effects:* The classes `num_get<>` and `num_put<>` handle
|
| 3810 |
locale-dependent numeric formatting and parsing. These inserter
|
| 3811 |
functions use the imbued `locale` value to perform numeric formatting.
|
|
|
|
| 3876 |
from which to obtain other facets. If `failed` is `true` then does
|
| 3877 |
`setstate(badbit)`, which may throw an exception, and returns.
|
| 3878 |
|
| 3879 |
*Returns:* `*this`.
|
| 3880 |
|
| 3881 |
+
``` cpp
|
| 3882 |
+
basic_ostream& operator<<(const volatile void* p);
|
| 3883 |
+
```
|
| 3884 |
+
|
| 3885 |
+
*Effects:* Equivalent to:
|
| 3886 |
+
`return operator<<(const_cast<const void*>(p));`
|
| 3887 |
+
|
| 3888 |
+
``` cpp
|
| 3889 |
+
basic_ostream& operator<<(extended-floating-point-type val);
|
| 3890 |
+
```
|
| 3891 |
+
|
| 3892 |
+
*Effects:* If the floating-point conversion rank of
|
| 3893 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 3894 |
+
`double`, the formatting conversion occurs as if it performed the
|
| 3895 |
+
following code fragment:
|
| 3896 |
+
|
| 3897 |
+
``` cpp
|
| 3898 |
+
bool failed = use_facet<
|
| 3899 |
+
num_put<charT, ostreambuf_iterator<charT, traits>>
|
| 3900 |
+
>(getloc()).put(*this, *this, fill(),
|
| 3901 |
+
static_cast<double>(val)).failed();
|
| 3902 |
+
```
|
| 3903 |
+
|
| 3904 |
+
Otherwise, if the floating-point conversion rank of
|
| 3905 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 3906 |
+
`long double`, the formatting conversion occurs as if it performed the
|
| 3907 |
+
following code fragment:
|
| 3908 |
+
|
| 3909 |
+
``` cpp
|
| 3910 |
+
bool failed = use_facet<
|
| 3911 |
+
num_put<charT, ostreambuf_iterator<charT, traits>>
|
| 3912 |
+
>(getloc()).put(*this, *this, fill(),
|
| 3913 |
+
static_cast<long double>(val)).failed();
|
| 3914 |
+
```
|
| 3915 |
+
|
| 3916 |
+
Otherwise, an invocation of the operator function is conditionally
|
| 3917 |
+
supported with *implementation-defined* semantics.
|
| 3918 |
+
|
| 3919 |
+
If `failed` is `true` then does `setstate(badbit)`, which may throw an
|
| 3920 |
+
exception, and returns.
|
| 3921 |
+
|
| 3922 |
+
*Returns:* `*this`.
|
| 3923 |
+
|
| 3924 |
##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
|
| 3925 |
|
| 3926 |
``` cpp
|
| 3927 |
+
basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&));
|
|
|
|
| 3928 |
```
|
| 3929 |
|
| 3930 |
*Effects:* None. Does not behave as a formatted output function (as
|
| 3931 |
described in [[ostream.formatted.reqmts]]).
|
| 3932 |
|
| 3933 |
+
*Returns:* `pf(*this)`.[^32]
|
| 3934 |
|
| 3935 |
``` cpp
|
| 3936 |
+
basic_ostream& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
|
|
|
| 3937 |
```
|
| 3938 |
|
| 3939 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3940 |
formatted output function (as described
|
| 3941 |
in [[ostream.formatted.reqmts]]).
|
| 3942 |
|
| 3943 |
+
*Returns:* `*this`.[^33]
|
| 3944 |
|
| 3945 |
``` cpp
|
| 3946 |
+
basic_ostream& operator<<(ios_base& (*pf)(ios_base&));
|
| 3947 |
```
|
| 3948 |
|
| 3949 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3950 |
formatted output function (as described
|
| 3951 |
in [[ostream.formatted.reqmts]]).
|
| 3952 |
|
| 3953 |
*Returns:* `*this`.
|
| 3954 |
|
| 3955 |
``` cpp
|
| 3956 |
+
basic_ostream& operator<<(basic_streambuf<charT, traits>* sb);
|
| 3957 |
```
|
| 3958 |
|
| 3959 |
*Effects:* Behaves as an unformatted output
|
| 3960 |
+
function [[ostream.unformatted]]. After the `sentry` object is
|
| 3961 |
constructed, if `sb` is null calls `setstate(badbit)` (which may throw
|
| 3962 |
`ios_base::failure`).
|
| 3963 |
|
| 3964 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 3965 |
read from `sb` and inserted until any of the following occurs:
|
|
|
|
| 3976 |
exception is rethrown.
|
| 3977 |
|
| 3978 |
*Returns:* `*this`.
|
| 3979 |
|
| 3980 |
``` cpp
|
| 3981 |
+
basic_ostream& operator<<(nullptr_t);
|
| 3982 |
```
|
| 3983 |
|
| 3984 |
*Effects:* Equivalent to:
|
| 3985 |
|
| 3986 |
``` cpp
|
|
|
|
| 4053 |
in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
|
| 4054 |
`width(0)`.
|
| 4055 |
|
| 4056 |
*Returns:* `out`.
|
| 4057 |
|
| 4058 |
+
##### Print <a id="ostream.formatted.print">[[ostream.formatted.print]]</a>
|
| 4059 |
+
|
| 4060 |
+
``` cpp
|
| 4061 |
+
template<class... Args>
|
| 4062 |
+
void print(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 4063 |
+
```
|
| 4064 |
+
|
| 4065 |
+
*Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
|
| 4066 |
+
equivalent to:
|
| 4067 |
+
|
| 4068 |
+
``` cpp
|
| 4069 |
+
vprint_unicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 4070 |
+
```
|
| 4071 |
+
|
| 4072 |
+
Otherwise, equivalent to:
|
| 4073 |
+
|
| 4074 |
+
``` cpp
|
| 4075 |
+
vprint_nonunicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 4076 |
+
```
|
| 4077 |
+
|
| 4078 |
+
``` cpp
|
| 4079 |
+
template<class... Args>
|
| 4080 |
+
void println(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 4081 |
+
```
|
| 4082 |
+
|
| 4083 |
+
*Effects:* Equivalent to:
|
| 4084 |
+
|
| 4085 |
+
``` cpp
|
| 4086 |
+
print(os, "{}\n", format(fmt, std::forward<Args>(args)...));
|
| 4087 |
+
```
|
| 4088 |
+
|
| 4089 |
+
``` cpp
|
| 4090 |
+
void vprint_unicode(ostream& os, string_view fmt, format_args args);
|
| 4091 |
+
void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
|
| 4092 |
+
```
|
| 4093 |
+
|
| 4094 |
+
*Effects:* Behaves as a formatted output
|
| 4095 |
+
function [[ostream.formatted.reqmts]] of `os`, except that:
|
| 4096 |
+
|
| 4097 |
+
- failure to generate output is reported as specified below, and
|
| 4098 |
+
- any exception thrown by the call to `vformat` is propagated without
|
| 4099 |
+
regard to the value of `os.exceptions()` and without turning on
|
| 4100 |
+
`ios_base::badbit` in the error state of `os`.
|
| 4101 |
+
|
| 4102 |
+
After constructing a `sentry` object, the function initializes an
|
| 4103 |
+
automatic variable via
|
| 4104 |
+
|
| 4105 |
+
``` cpp
|
| 4106 |
+
string out = vformat(os.getloc(), fmt, args);
|
| 4107 |
+
```
|
| 4108 |
+
|
| 4109 |
+
If the function is `vprint_unicode` and `os` is a stream that refers to
|
| 4110 |
+
a terminal capable of displaying Unicode which is determined in an
|
| 4111 |
+
implementation-defined manner, writes `out` to the terminal using the
|
| 4112 |
+
native Unicode API; if `out` contains invalid code units, the behavior
|
| 4113 |
+
is undefined and implementations are encouraged to diagnose it. If the
|
| 4114 |
+
native Unicode API is used, the function flushes `os` before writing
|
| 4115 |
+
`out`. Otherwise (if `os` is not such a stream or the function is
|
| 4116 |
+
`vprint_nonunicode`), inserts the character sequence \[`out.begin()`,
|
| 4117 |
+
`out.end()`) into `os`. If writing to the terminal or inserting into
|
| 4118 |
+
`os` fails, calls `os.setstate(ios_base::badbit)` (which may throw
|
| 4119 |
+
`ios_base::failure`).
|
| 4120 |
+
|
| 4121 |
+
*Recommended practice:* For `vprint_unicode`, if invoking the native
|
| 4122 |
+
Unicode API requires transcoding, implementations should substitute
|
| 4123 |
+
invalid code units with U+fffd (replacement character) per the Unicode
|
| 4124 |
+
Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
|
| 4125 |
+
|
| 4126 |
#### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
|
| 4127 |
|
| 4128 |
Each unformatted output function begins execution by constructing an
|
| 4129 |
+
object of class `sentry`. If that object returns `true`, while
|
| 4130 |
converting to a value of type `bool`, the function endeavors to generate
|
| 4131 |
the requested output. If an exception is thrown during output, then
|
| 4132 |
+
`ios_base::badbit` is set[^34]
|
| 4133 |
+
|
| 4134 |
+
in `*this`’s error state. If `(exceptions() & badbit) != 0` then the
|
| 4135 |
+
exception is rethrown. In any case, the unformatted output function ends
|
| 4136 |
+
by destroying the `sentry` object, then, if no exception was thrown,
|
| 4137 |
+
returning the value specified for the unformatted output function.
|
| 4138 |
|
| 4139 |
``` cpp
|
| 4140 |
+
basic_ostream& put(char_type c);
|
| 4141 |
```
|
| 4142 |
|
| 4143 |
*Effects:* Behaves as an unformatted output function (as described
|
| 4144 |
+
above). After constructing a `sentry` object, inserts the character `c`,
|
| 4145 |
+
if possible.[^35]
|
| 4146 |
|
| 4147 |
Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 4148 |
[[iostate.flags]]).
|
| 4149 |
|
| 4150 |
*Returns:* `*this`.
|
|
|
|
| 4152 |
``` cpp
|
| 4153 |
basic_ostream& write(const char_type* s, streamsize n);
|
| 4154 |
```
|
| 4155 |
|
| 4156 |
*Effects:* Behaves as an unformatted output function (as described
|
| 4157 |
+
above). After constructing a `sentry` object, obtains characters to
|
| 4158 |
+
insert from successive locations of an array whose first element is
|
| 4159 |
+
designated by `s`.[^36]
|
| 4160 |
+
|
| 4161 |
+
Characters are inserted until either of the following occurs:
|
| 4162 |
|
| 4163 |
- `n` characters are inserted;
|
| 4164 |
- inserting in the output sequence fails (in which case the function
|
| 4165 |
calls `setstate(badbit)`, which may throw `ios_base::failure`
|
| 4166 |
[[iostate.flags]]).
|
|
|
|
| 4170 |
``` cpp
|
| 4171 |
basic_ostream& flush();
|
| 4172 |
```
|
| 4173 |
|
| 4174 |
*Effects:* Behaves as an unformatted output function (as described
|
| 4175 |
+
above). If `rdbuf()` is not a null pointer, constructs a `sentry`
|
| 4176 |
+
object. If that object returns `true` when converted to a value of type
|
| 4177 |
+
`bool` the function calls `rdbuf()->pubsync()`. If that function returns
|
| 4178 |
+
-1 calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 4179 |
+
[[iostate.flags]]). Otherwise, if the `sentry` object returns `false`,
|
| 4180 |
does nothing.
|
| 4181 |
|
| 4182 |
*Returns:* `*this`.
|
| 4183 |
|
| 4184 |
#### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
|
|
|
|
| 4248 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 4249 |
```
|
| 4250 |
|
| 4251 |
*Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
|
| 4252 |
`basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
|
| 4253 |
+
of exposition, behaves as an unformatted output
|
| 4254 |
+
function [[ostream.unformatted]] of `os`. After constructing a `sentry`
|
| 4255 |
+
object, calls `buf->emit()`. If that call returns `false`, calls
|
| 4256 |
+
`os.setstate(ios_base::badbit)`.
|
| 4257 |
|
| 4258 |
*Returns:* `os`.
|
| 4259 |
|
| 4260 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 4261 |
|
|
|
|
| 4285 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4286 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4287 |
`out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
|
| 4288 |
if `in` is an object of type `basic_istream<charT, traits>` then the
|
| 4289 |
expression `in >> resetiosflags(mask)` behaves as if it called
|
| 4290 |
+
`f(in, mask)`, where the function `f` is defined as:[^37]
|
| 4291 |
|
| 4292 |
``` cpp
|
| 4293 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 4294 |
// reset specified flags
|
| 4295 |
str.setf(ios_base::fmtflags(0), mask);
|
|
|
|
| 4484 |
|
| 4485 |
The expression `out << put_money(mon, intl)` has type
|
| 4486 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4487 |
|
| 4488 |
``` cpp
|
| 4489 |
+
template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
|
| 4490 |
```
|
| 4491 |
|
| 4492 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 4493 |
+
type `tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`) is a
|
| 4494 |
+
valid range.
|
| 4495 |
|
| 4496 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4497 |
of type `basic_istream<charT, traits>` then the expression
|
| 4498 |
`in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
|
| 4499 |
where the function `f` is defined as:
|
| 4500 |
|
| 4501 |
``` cpp
|
| 4502 |
template<class charT, class traits>
|
| 4503 |
+
void f(basic_ios<charT, traits>& str, tm* tmb, const charT* fmt) {
|
| 4504 |
using Iter = istreambuf_iterator<charT, traits>;
|
| 4505 |
using TimeGet = time_get<charT, Iter>;
|
| 4506 |
|
| 4507 |
ios_base::iostate err = ios_base::goodbit;
|
| 4508 |
const TimeGet& tg = use_facet<TimeGet>(str.getloc());
|
|
|
|
| 4517 |
|
| 4518 |
The expression `in >> get_time(tmb, fmt)` has type
|
| 4519 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4520 |
|
| 4521 |
``` cpp
|
| 4522 |
+
template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
|
| 4523 |
```
|
| 4524 |
|
| 4525 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 4526 |
+
type `tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`) is a
|
| 4527 |
+
valid range.
|
| 4528 |
|
| 4529 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4530 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4531 |
`out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
|
| 4532 |
where the function `f` is defined as:
|
| 4533 |
|
| 4534 |
``` cpp
|
| 4535 |
template<class charT, class traits>
|
| 4536 |
+
void f(basic_ios<charT, traits>& str, const tm* tmb, const charT* fmt) {
|
| 4537 |
using Iter = ostreambuf_iterator<charT, traits>;
|
| 4538 |
using TimePut = time_put<charT, Iter>;
|
| 4539 |
|
| 4540 |
const TimePut& tp = use_facet<TimePut>(str.getloc());
|
| 4541 |
const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
|
|
|
|
| 4624 |
- The expression `in >> quoted(s, delim, escape)` has type
|
| 4625 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4626 |
- The expression `out << quoted(s, delim, escape)` has type
|
| 4627 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4628 |
|
| 4629 |
+
### Print functions <a id="print.fun">[[print.fun]]</a>
|
| 4630 |
+
|
| 4631 |
+
``` cpp
|
| 4632 |
+
template<class... Args>
|
| 4633 |
+
void print(format_string<Args...> fmt, Args&&... args);
|
| 4634 |
+
```
|
| 4635 |
+
|
| 4636 |
+
*Effects:* Equivalent to:
|
| 4637 |
+
|
| 4638 |
+
``` cpp
|
| 4639 |
+
print(stdout, fmt, std::forward<Args>(args)...);
|
| 4640 |
+
```
|
| 4641 |
+
|
| 4642 |
+
``` cpp
|
| 4643 |
+
template<class... Args>
|
| 4644 |
+
void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 4645 |
+
```
|
| 4646 |
+
|
| 4647 |
+
*Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
|
| 4648 |
+
equivalent to:
|
| 4649 |
+
|
| 4650 |
+
``` cpp
|
| 4651 |
+
vprint_unicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 4652 |
+
```
|
| 4653 |
+
|
| 4654 |
+
Otherwise, equivalent to:
|
| 4655 |
+
|
| 4656 |
+
``` cpp
|
| 4657 |
+
vprint_nonunicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 4658 |
+
```
|
| 4659 |
+
|
| 4660 |
+
``` cpp
|
| 4661 |
+
template<class... Args>
|
| 4662 |
+
void println(format_string<Args...> fmt, Args&&... args);
|
| 4663 |
+
```
|
| 4664 |
+
|
| 4665 |
+
*Effects:* Equivalent to:
|
| 4666 |
+
|
| 4667 |
+
``` cpp
|
| 4668 |
+
println(stdout, fmt, std::forward<Args>(args)...);
|
| 4669 |
+
```
|
| 4670 |
+
|
| 4671 |
+
``` cpp
|
| 4672 |
+
template<class... Args>
|
| 4673 |
+
void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 4674 |
+
```
|
| 4675 |
+
|
| 4676 |
+
*Effects:* Equivalent to:
|
| 4677 |
+
|
| 4678 |
+
``` cpp
|
| 4679 |
+
print(stream, "{}\n", format(fmt, std::forward<Args>(args)...));
|
| 4680 |
+
```
|
| 4681 |
+
|
| 4682 |
+
``` cpp
|
| 4683 |
+
void vprint_unicode(string_view fmt, format_args args);
|
| 4684 |
+
```
|
| 4685 |
+
|
| 4686 |
+
*Effects:* Equivalent to:
|
| 4687 |
+
|
| 4688 |
+
``` cpp
|
| 4689 |
+
vprint_unicode(stdout, fmt, args);
|
| 4690 |
+
```
|
| 4691 |
+
|
| 4692 |
+
``` cpp
|
| 4693 |
+
void vprint_unicode(FILE* stream, string_view fmt, format_args args);
|
| 4694 |
+
```
|
| 4695 |
+
|
| 4696 |
+
*Preconditions:* `stream` is a valid pointer to an output C stream.
|
| 4697 |
+
|
| 4698 |
+
*Effects:* The function initializes an automatic variable via
|
| 4699 |
+
|
| 4700 |
+
``` cpp
|
| 4701 |
+
string out = vformat(fmt, args);
|
| 4702 |
+
```
|
| 4703 |
+
|
| 4704 |
+
If `stream` refers to a terminal capable of displaying Unicode, writes
|
| 4705 |
+
`out` to the terminal using the native Unicode API; if `out` contains
|
| 4706 |
+
invalid code units, the behavior is undefined and implementations are
|
| 4707 |
+
encouraged to diagnose it. Otherwise writes `out` to `stream` unchanged.
|
| 4708 |
+
If the native Unicode API is used, the function flushes `stream` before
|
| 4709 |
+
writing `out`.
|
| 4710 |
+
|
| 4711 |
+
[*Note 1*: On POSIX and Windows, `stream` referring to a terminal means
|
| 4712 |
+
that, respectively, `isatty(fileno(stream))` and
|
| 4713 |
+
`GetConsoleMode(_get_osfhandle(_fileno(stream)), ...)` return
|
| 4714 |
+
nonzero. — *end note*]
|
| 4715 |
+
|
| 4716 |
+
[*Note 2*: On Windows, the native Unicode API is
|
| 4717 |
+
`WriteConsoleW`. — *end note*]
|
| 4718 |
+
|
| 4719 |
+
*Throws:* Any exception thrown by the call to `vformat`
|
| 4720 |
+
[[format.err.report]]. `system_error` if writing to the terminal or
|
| 4721 |
+
`stream` fails. May throw `bad_alloc`.
|
| 4722 |
+
|
| 4723 |
+
*Recommended practice:* If invoking the native Unicode API requires
|
| 4724 |
+
transcoding, implementations should substitute invalid code units with
|
| 4725 |
+
U+fffd (replacement character) per the Unicode Standard, Chapter 3.9
|
| 4726 |
+
‘U+fffd‘ Substitution in Conversion.
|
| 4727 |
+
|
| 4728 |
+
``` cpp
|
| 4729 |
+
void vprint_nonunicode(string_view fmt, format_args args);
|
| 4730 |
+
```
|
| 4731 |
+
|
| 4732 |
+
*Effects:* Equivalent to:
|
| 4733 |
+
|
| 4734 |
+
``` cpp
|
| 4735 |
+
vprint_nonunicode(stdout, fmt, args);
|
| 4736 |
+
```
|
| 4737 |
+
|
| 4738 |
+
``` cpp
|
| 4739 |
+
void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
|
| 4740 |
+
```
|
| 4741 |
+
|
| 4742 |
+
*Preconditions:* `stream` is a valid pointer to an output C stream.
|
| 4743 |
+
|
| 4744 |
+
*Effects:* Writes the result of `vformat(fmt, args)` to `stream`.
|
| 4745 |
+
|
| 4746 |
+
*Throws:* Any exception thrown by the call to `vformat`
|
| 4747 |
+
[[format.err.report]]. `system_error` if writing to `stream` fails. May
|
| 4748 |
+
throw `bad_alloc`.
|
| 4749 |
+
|
| 4750 |
## String-based streams <a id="string.streams">[[string.streams]]</a>
|
| 4751 |
|
| 4752 |
### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
|
| 4753 |
|
| 4754 |
``` cpp
|
| 4755 |
namespace std {
|
| 4756 |
template<class charT, class traits = char_traits<charT>,
|
| 4757 |
class Allocator = allocator<charT>>
|
| 4758 |
class basic_stringbuf;
|
| 4759 |
|
| 4760 |
+
template<class charT, class traits, class Allocator>
|
| 4761 |
+
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4762 |
+
basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
|
| 4763 |
+
|
| 4764 |
using stringbuf = basic_stringbuf<char>;
|
| 4765 |
using wstringbuf = basic_stringbuf<wchar_t>;
|
| 4766 |
|
| 4767 |
template<class charT, class traits = char_traits<charT>,
|
| 4768 |
class Allocator = allocator<charT>>
|
| 4769 |
class basic_istringstream;
|
| 4770 |
|
| 4771 |
+
template<class charT, class traits, class Allocator>
|
| 4772 |
+
void swap(basic_istringstream<charT, traits, Allocator>& x,
|
| 4773 |
+
basic_istringstream<charT, traits, Allocator>& y);
|
| 4774 |
+
|
| 4775 |
using istringstream = basic_istringstream<char>;
|
| 4776 |
using wistringstream = basic_istringstream<wchar_t>;
|
| 4777 |
|
| 4778 |
template<class charT, class traits = char_traits<charT>,
|
| 4779 |
class Allocator = allocator<charT>>
|
| 4780 |
class basic_ostringstream;
|
| 4781 |
+
|
| 4782 |
+
template<class charT, class traits, class Allocator>
|
| 4783 |
+
void swap(basic_ostringstream<charT, traits, Allocator>& x,
|
| 4784 |
+
basic_ostringstream<charT, traits, Allocator>& y);
|
| 4785 |
+
|
| 4786 |
using ostringstream = basic_ostringstream<char>;
|
| 4787 |
using wostringstream = basic_ostringstream<wchar_t>;
|
| 4788 |
|
| 4789 |
template<class charT, class traits = char_traits<charT>,
|
| 4790 |
class Allocator = allocator<charT>>
|
| 4791 |
class basic_stringstream;
|
| 4792 |
+
|
| 4793 |
+
template<class charT, class traits, class Allocator>
|
| 4794 |
+
void swap(basic_stringstream<charT, traits, Allocator>& x,
|
| 4795 |
+
basic_stringstream<charT, traits, Allocator>& y);
|
| 4796 |
+
|
| 4797 |
using stringstream = basic_stringstream<char>;
|
| 4798 |
using wstringstream = basic_stringstream<wchar_t>;
|
| 4799 |
}
|
| 4800 |
```
|
| 4801 |
|
|
|
|
| 4803 |
associate stream buffers with objects of class `basic_string`, as
|
| 4804 |
described in [[string.classes]].
|
| 4805 |
|
| 4806 |
### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
|
| 4807 |
|
| 4808 |
+
#### General <a id="stringbuf.general">[[stringbuf.general]]</a>
|
| 4809 |
+
|
| 4810 |
``` cpp
|
| 4811 |
namespace std {
|
| 4812 |
template<class charT, class traits = char_traits<charT>,
|
| 4813 |
class Allocator = allocator<charT>>
|
| 4814 |
class basic_stringbuf : public basic_streambuf<charT, traits> {
|
|
|
|
| 4846 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4847 |
basic_stringbuf(const basic_stringbuf&) = delete;
|
| 4848 |
basic_stringbuf(basic_stringbuf&& rhs);
|
| 4849 |
basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
|
| 4850 |
|
| 4851 |
+
// [stringbuf.assign], assignment and swap
|
| 4852 |
basic_stringbuf& operator=(const basic_stringbuf&) = delete;
|
| 4853 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4854 |
void swap(basic_stringbuf& rhs) noexcept(see below);
|
| 4855 |
|
| 4856 |
// [stringbuf.members], getters and setters
|
|
|
|
| 4884 |
private:
|
| 4885 |
ios_base::openmode mode; // exposition only
|
| 4886 |
basic_string<charT, traits, Allocator> buf; // exposition only
|
| 4887 |
void init_buf_ptrs(); // exposition only
|
| 4888 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4889 |
}
|
| 4890 |
```
|
| 4891 |
|
| 4892 |
The class `basic_stringbuf` is derived from `basic_streambuf` to
|
| 4893 |
associate possibly the input sequence and possibly the output sequence
|
|
|
|
| 5020 |
void swap(basic_stringbuf& rhs) noexcept(see below);
|
| 5021 |
```
|
| 5022 |
|
| 5023 |
*Preconditions:*
|
| 5024 |
`allocator_traits<Allocator>::propagate_on_container_swap::value` is
|
| 5025 |
+
`true` or `get_allocator() == rhs.get_allocator()` is `true`.
|
| 5026 |
|
| 5027 |
*Effects:* Exchanges the state of `*this` and `rhs`.
|
| 5028 |
|
| 5029 |
+
*Remarks:* The exception specification is equivalent to:
|
| 5030 |
`allocator_traits<Allocator>::propagate_on_container_swap::value ||`
|
| 5031 |
`allocator_traits<Allocator>::is_always_equal::value`.
|
| 5032 |
|
| 5033 |
``` cpp
|
| 5034 |
template<class charT, class traits, class Allocator>
|
|
|
|
| 5066 |
- otherwise `pptr() == pbase()` is `true`.
|
| 5067 |
- If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
|
| 5068 |
and `(gptr() == eback() && egptr() == eback() + buf.size())` is
|
| 5069 |
`true`.
|
| 5070 |
|
| 5071 |
+
[*Note 1*: For efficiency reasons, stream buffer operations can violate
|
| 5072 |
+
invariants of `buf` while it is held encapsulated in the
|
| 5073 |
`basic_stringbuf`, e.g., by writing to characters in the range
|
| 5074 |
\[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
|
| 5075 |
operations retrieving a `basic_string` from `buf` ensure that the
|
| 5076 |
`basic_string` invariants hold on the returned value. — *end note*]
|
| 5077 |
|
|
|
|
| 5107 |
|
| 5108 |
``` cpp
|
| 5109 |
basic_string<charT, traits, Allocator> str() &&;
|
| 5110 |
```
|
| 5111 |
|
| 5112 |
+
*Ensures:* The underlying character sequence `buf` is empty and
|
| 5113 |
+
`pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
|
| 5114 |
+
initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
|
| 5115 |
+
|
| 5116 |
*Returns:* A `basic_string<charT, traits, Allocator>` object move
|
| 5117 |
constructed from the `basic_stringbuf`’s underlying character sequence
|
| 5118 |
in `buf`. This can be achieved by first adjusting `buf` to have the same
|
| 5119 |
content as `view()`.
|
| 5120 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5121 |
``` cpp
|
| 5122 |
basic_string_view<charT, traits> view() const noexcept;
|
| 5123 |
```
|
| 5124 |
|
| 5125 |
Let `sv` be `basic_string_view<charT, traits>`.
|
|
|
|
| 5195 |
input sequence has a putback position available, and if
|
| 5196 |
`traits::eq(to_char_type(c), gptr()[-1])` returns `true`, assigns
|
| 5197 |
`gptr() - 1` to `gptr()`. Returns: `c`.
|
| 5198 |
- If `traits::eq_int_type(c, traits::eof())` returns `false` and if the
|
| 5199 |
input sequence has a putback position available, and if `mode` `&`
|
| 5200 |
+
`ios_base::out` is nonzero, assigns `c` to `*–gptr()`. Returns: `c`.
|
| 5201 |
- If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
|
| 5202 |
input sequence has a putback position available, assigns `gptr() - 1`
|
| 5203 |
to `gptr()`. Returns: `traits::not_eof(c)`.
|
| 5204 |
|
| 5205 |
*Returns:* As specified above, or `traits::eof()` to indicate failure.
|
|
|
|
| 5220 |
function calls `sputc(c)`. Signals success by returning `c`.
|
| 5221 |
- If `traits::eq_int_type(c, traits::eof())` returns `true`, there is no
|
| 5222 |
character to append. Signals success by returning a value other than
|
| 5223 |
`traits::eof()`.
|
| 5224 |
|
| 5225 |
+
*Returns:* As specified above, or `traits::eof()` to indicate failure.
|
| 5226 |
+
|
| 5227 |
*Remarks:* The function can alter the number of write positions
|
| 5228 |
available as a result of any call.
|
| 5229 |
|
|
|
|
|
|
|
| 5230 |
The function can make a write position available only if `ios_base::out`
|
| 5231 |
is set in `mode`. To make a write position available, the function
|
| 5232 |
reallocates (or initially allocates) an array object with a sufficient
|
| 5233 |
number of elements to hold the current array object (if any), plus at
|
| 5234 |
least one additional write position. If `ios_base::in` is set in `mode`,
|
|
|
|
| 5289 |
|
| 5290 |
*Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
|
| 5291 |
indicate failure.
|
| 5292 |
|
| 5293 |
``` cpp
|
| 5294 |
+
basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n) override;
|
| 5295 |
```
|
| 5296 |
|
| 5297 |
*Effects:* *implementation-defined*, except that `setbuf(0, 0)` has no
|
| 5298 |
effect.
|
| 5299 |
|
| 5300 |
*Returns:* `this`.
|
| 5301 |
|
| 5302 |
### Class template `basic_istringstream` <a id="istringstream">[[istringstream]]</a>
|
| 5303 |
|
| 5304 |
+
#### General <a id="istringstream.general">[[istringstream.general]]</a>
|
| 5305 |
+
|
| 5306 |
``` cpp
|
| 5307 |
namespace std {
|
| 5308 |
template<class charT, class traits = char_traits<charT>,
|
| 5309 |
class Allocator = allocator<charT>>
|
| 5310 |
class basic_istringstream : public basic_istream<charT, traits> {
|
|
|
|
| 5339 |
const basic_string<charT, traits, SAlloc>& s,
|
| 5340 |
ios_base::openmode which = ios_base::in);
|
| 5341 |
basic_istringstream(const basic_istringstream&) = delete;
|
| 5342 |
basic_istringstream(basic_istringstream&& rhs);
|
| 5343 |
|
|
|
|
| 5344 |
basic_istringstream& operator=(const basic_istringstream&) = delete;
|
| 5345 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
| 5346 |
+
|
| 5347 |
+
// [istringstream.swap], swap
|
| 5348 |
void swap(basic_istringstream& rhs);
|
| 5349 |
|
| 5350 |
// [istringstream.members], members
|
| 5351 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5352 |
basic_string<charT, traits, Allocator> str() const &;
|
|
|
|
| 5361 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5362 |
|
| 5363 |
private:
|
| 5364 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 5365 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5366 |
}
|
| 5367 |
```
|
| 5368 |
|
| 5369 |
The class `basic_istringstream<charT, traits, Allocator>` supports
|
| 5370 |
reading objects of class `basic_string<{}charT, traits, Allocator>`. It
|
|
|
|
| 5391 |
ios_base::openmode which = ios_base::in);
|
| 5392 |
```
|
| 5393 |
|
| 5394 |
*Effects:* Initializes the base class with
|
| 5395 |
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5396 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
|
| 5397 |
+
[[stringbuf.cons]].
|
| 5398 |
|
| 5399 |
``` cpp
|
| 5400 |
basic_istringstream(ios_base::openmode which, const Allocator& a);
|
| 5401 |
```
|
| 5402 |
|
|
|
|
| 5423 |
ios_base::openmode which, const Allocator& a);
|
| 5424 |
```
|
| 5425 |
|
| 5426 |
*Effects:* Initializes the base class with
|
| 5427 |
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5428 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`
|
| 5429 |
+
[[stringbuf.cons]].
|
| 5430 |
|
| 5431 |
``` cpp
|
| 5432 |
template<class SAlloc>
|
| 5433 |
explicit basic_istringstream(
|
| 5434 |
const basic_string<charT, traits, SAlloc>& s,
|
|
|
|
| 5448 |
by move constructing the base class, and the contained
|
| 5449 |
`basic_stringbuf`. Then calls
|
| 5450 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5451 |
contained `basic_stringbuf`.
|
| 5452 |
|
| 5453 |
+
#### Swap <a id="istringstream.swap">[[istringstream.swap]]</a>
|
| 5454 |
|
| 5455 |
``` cpp
|
| 5456 |
void swap(basic_istringstream& rhs);
|
| 5457 |
```
|
| 5458 |
|
|
|
|
| 5524 |
|
| 5525 |
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5526 |
|
| 5527 |
### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
|
| 5528 |
|
| 5529 |
+
#### General <a id="ostringstream.general">[[ostringstream.general]]</a>
|
| 5530 |
+
|
| 5531 |
``` cpp
|
| 5532 |
namespace std {
|
| 5533 |
template<class charT, class traits = char_traits<charT>,
|
| 5534 |
class Allocator = allocator<charT>>
|
| 5535 |
class basic_ostringstream : public basic_ostream<charT, traits> {
|
|
|
|
| 5564 |
const basic_string<charT, traits, SAlloc>& s,
|
| 5565 |
ios_base::openmode which = ios_base::out);
|
| 5566 |
basic_ostringstream(const basic_ostringstream&) = delete;
|
| 5567 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 5568 |
|
|
|
|
| 5569 |
basic_ostringstream& operator=(const basic_ostringstream&) = delete;
|
| 5570 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
| 5571 |
+
|
| 5572 |
+
// [ostringstream.swap], swap
|
| 5573 |
void swap(basic_ostringstream& rhs);
|
| 5574 |
|
| 5575 |
// [ostringstream.members], members
|
| 5576 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5577 |
|
|
|
|
| 5587 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5588 |
|
| 5589 |
private:
|
| 5590 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 5591 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5592 |
}
|
| 5593 |
```
|
| 5594 |
|
| 5595 |
The class `basic_ostringstream<charT, traits, Allocator>` supports
|
| 5596 |
writing objects of class `basic_string<{}charT, traits, Allocator>`. It
|
|
|
|
| 5616 |
ios_base::openmode which = ios_base::out);
|
| 5617 |
```
|
| 5618 |
|
| 5619 |
*Effects:* Initializes the base class with
|
| 5620 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5621 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
|
| 5622 |
+
[[stringbuf.cons]].
|
| 5623 |
|
| 5624 |
``` cpp
|
| 5625 |
basic_ostringstream(ios_base::openmode which, const Allocator& a);
|
| 5626 |
```
|
| 5627 |
|
| 5628 |
*Effects:* Initializes the base class with
|
| 5629 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5630 |
+
`basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`
|
| 5631 |
+
[[stringbuf.cons]].
|
| 5632 |
|
| 5633 |
``` cpp
|
| 5634 |
explicit basic_ostringstream(
|
| 5635 |
basic_string<charT, traits, Allocator>&& s,
|
| 5636 |
ios_base::openmode which = ios_base::out);
|
|
|
|
| 5648 |
ios_base::openmode which, const Allocator& a);
|
| 5649 |
```
|
| 5650 |
|
| 5651 |
*Effects:* Initializes the base class with
|
| 5652 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5653 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`
|
| 5654 |
+
[[stringbuf.cons]].
|
| 5655 |
|
| 5656 |
``` cpp
|
| 5657 |
template<class SAlloc>
|
| 5658 |
explicit basic_ostringstream(
|
| 5659 |
const basic_string<charT, traits, SAlloc>& s,
|
|
|
|
| 5662 |
|
| 5663 |
*Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
|
| 5664 |
|
| 5665 |
*Effects:* Initializes the base class with
|
| 5666 |
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5667 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`
|
| 5668 |
+
[[stringbuf.cons]].
|
| 5669 |
|
| 5670 |
``` cpp
|
| 5671 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 5672 |
```
|
| 5673 |
|
|
|
|
| 5675 |
by move constructing the base class, and the contained
|
| 5676 |
`basic_stringbuf`. Then calls
|
| 5677 |
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5678 |
contained `basic_stringbuf`.
|
| 5679 |
|
| 5680 |
+
#### Swap <a id="ostringstream.swap">[[ostringstream.swap]]</a>
|
| 5681 |
|
| 5682 |
``` cpp
|
| 5683 |
void swap(basic_ostringstream& rhs);
|
| 5684 |
```
|
| 5685 |
|
|
|
|
| 5751 |
|
| 5752 |
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5753 |
|
| 5754 |
### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
|
| 5755 |
|
| 5756 |
+
#### General <a id="stringstream.general">[[stringstream.general]]</a>
|
| 5757 |
+
|
| 5758 |
``` cpp
|
| 5759 |
namespace std {
|
| 5760 |
template<class charT, class traits = char_traits<charT>,
|
| 5761 |
class Allocator = allocator<charT>>
|
| 5762 |
class basic_stringstream : public basic_iostream<charT, traits> {
|
|
|
|
| 5791 |
const basic_string<charT, traits, SAlloc>& s,
|
| 5792 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5793 |
basic_stringstream(const basic_stringstream&) = delete;
|
| 5794 |
basic_stringstream(basic_stringstream&& rhs);
|
| 5795 |
|
|
|
|
| 5796 |
basic_stringstream& operator=(const basic_stringstream&) = delete;
|
| 5797 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
| 5798 |
+
|
| 5799 |
+
// [stringstream.swap], swap
|
| 5800 |
void swap(basic_stringstream& rhs);
|
| 5801 |
|
| 5802 |
// [stringstream.members], members
|
| 5803 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5804 |
|
|
|
|
| 5814 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5815 |
|
| 5816 |
private:
|
| 5817 |
basic_stringbuf<charT, traits> sb; // exposition only
|
| 5818 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5819 |
}
|
| 5820 |
```
|
| 5821 |
|
| 5822 |
The class template `basic_stringstream<charT, traits>` supports reading
|
| 5823 |
and writing from objects of class
|
|
|
|
| 5903 |
by move constructing the base class, and the contained
|
| 5904 |
`basic_stringbuf`. Then calls
|
| 5905 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5906 |
contained `basic_stringbuf`.
|
| 5907 |
|
| 5908 |
+
#### Swap <a id="stringstream.swap">[[stringstream.swap]]</a>
|
| 5909 |
|
| 5910 |
``` cpp
|
| 5911 |
void swap(basic_stringstream& rhs);
|
| 5912 |
```
|
| 5913 |
|
|
|
|
| 5977 |
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5978 |
```
|
| 5979 |
|
| 5980 |
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5981 |
|
| 5982 |
+
## Span-based streams <a id="span.streams">[[span.streams]]</a>
|
| 5983 |
+
|
| 5984 |
+
### Overview <a id="span.streams.overview">[[span.streams.overview]]</a>
|
| 5985 |
+
|
| 5986 |
+
The header `<spanstream>` defines class templates and types that
|
| 5987 |
+
associate stream buffers with objects whose types are specializations of
|
| 5988 |
+
`span` as described in [[views.span]].
|
| 5989 |
+
|
| 5990 |
+
[*Note 1*: A user of these classes is responsible for ensuring that the
|
| 5991 |
+
character sequence represented by the given `span` outlives the use of
|
| 5992 |
+
the sequence by objects of the classes in subclause [[span.streams]].
|
| 5993 |
+
Using multiple `basic_spanbuf` objects referring to overlapping
|
| 5994 |
+
underlying sequences from different threads, where at least one
|
| 5995 |
+
`basic_spanbuf` object is used for writing to the sequence, results in a
|
| 5996 |
+
data race. — *end note*]
|
| 5997 |
+
|
| 5998 |
+
### Header `<spanstream>` synopsis <a id="spanstream.syn">[[spanstream.syn]]</a>
|
| 5999 |
+
|
| 6000 |
+
``` cpp
|
| 6001 |
+
namespace std {
|
| 6002 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6003 |
+
class basic_spanbuf;
|
| 6004 |
+
|
| 6005 |
+
template<class charT, class traits>
|
| 6006 |
+
void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
|
| 6007 |
+
|
| 6008 |
+
using spanbuf = basic_spanbuf<char>;
|
| 6009 |
+
using wspanbuf = basic_spanbuf<wchar_t>;
|
| 6010 |
+
|
| 6011 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6012 |
+
class basic_ispanstream;
|
| 6013 |
+
|
| 6014 |
+
template<class charT, class traits>
|
| 6015 |
+
void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
|
| 6016 |
+
|
| 6017 |
+
using ispanstream = basic_ispanstream<char>;
|
| 6018 |
+
using wispanstream = basic_ispanstream<wchar_t>;
|
| 6019 |
+
|
| 6020 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6021 |
+
class basic_ospanstream;
|
| 6022 |
+
|
| 6023 |
+
template<class charT, class traits>
|
| 6024 |
+
void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
|
| 6025 |
+
|
| 6026 |
+
using ospanstream = basic_ospanstream<char>;
|
| 6027 |
+
using wospanstream = basic_ospanstream<wchar_t>;
|
| 6028 |
+
|
| 6029 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6030 |
+
class basic_spanstream;
|
| 6031 |
+
|
| 6032 |
+
template<class charT, class traits>
|
| 6033 |
+
void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
|
| 6034 |
+
|
| 6035 |
+
using spanstream = basic_spanstream<char>;
|
| 6036 |
+
using wspanstream = basic_spanstream<wchar_t>;
|
| 6037 |
+
}
|
| 6038 |
+
```
|
| 6039 |
+
|
| 6040 |
+
### Class template `basic_spanbuf` <a id="spanbuf">[[spanbuf]]</a>
|
| 6041 |
+
|
| 6042 |
+
#### General <a id="spanbuf.general">[[spanbuf.general]]</a>
|
| 6043 |
+
|
| 6044 |
+
``` cpp
|
| 6045 |
+
namespace std {
|
| 6046 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6047 |
+
class basic_spanbuf
|
| 6048 |
+
: public basic_streambuf<charT, traits> {
|
| 6049 |
+
public:
|
| 6050 |
+
using char_type = charT;
|
| 6051 |
+
using int_type = typename traits::int_type;
|
| 6052 |
+
using pos_type = typename traits::pos_type;
|
| 6053 |
+
using off_type = typename traits::off_type;
|
| 6054 |
+
using traits_type = traits;
|
| 6055 |
+
|
| 6056 |
+
// [spanbuf.cons], constructors
|
| 6057 |
+
basic_spanbuf() : basic_spanbuf(ios_base::in | ios_base::out) {}
|
| 6058 |
+
explicit basic_spanbuf(ios_base::openmode which)
|
| 6059 |
+
: basic_spanbuf(std::span<charT>(), which) {}
|
| 6060 |
+
explicit basic_spanbuf(std::span<charT> s,
|
| 6061 |
+
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 6062 |
+
basic_spanbuf(const basic_spanbuf&) = delete;
|
| 6063 |
+
basic_spanbuf(basic_spanbuf&& rhs);
|
| 6064 |
+
|
| 6065 |
+
// [spanbuf.assign], assignment and swap
|
| 6066 |
+
basic_spanbuf& operator=(const basic_spanbuf&) = delete;
|
| 6067 |
+
basic_spanbuf& operator=(basic_spanbuf&& rhs);
|
| 6068 |
+
void swap(basic_spanbuf& rhs);
|
| 6069 |
+
|
| 6070 |
+
// [spanbuf.members], member functions
|
| 6071 |
+
std::span<charT> span() const noexcept;
|
| 6072 |
+
void span(std::span<charT> s) noexcept;
|
| 6073 |
+
|
| 6074 |
+
protected:
|
| 6075 |
+
// [spanbuf.virtuals], overridden virtual functions
|
| 6076 |
+
basic_streambuf<charT, traits>* setbuf(charT*, streamsize) override;
|
| 6077 |
+
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 6078 |
+
ios_base::openmode which = ios_base::in | ios_base::out) override;
|
| 6079 |
+
pos_type seekpos(pos_type sp,
|
| 6080 |
+
ios_base::openmode which = ios_base::in | ios_base::out) override;
|
| 6081 |
+
|
| 6082 |
+
private:
|
| 6083 |
+
ios_base::openmode mode; // exposition only
|
| 6084 |
+
std::span<charT> buf; // exposition only
|
| 6085 |
+
};
|
| 6086 |
+
}
|
| 6087 |
+
```
|
| 6088 |
+
|
| 6089 |
+
The class template `basic_spanbuf` is derived from `basic_streambuf` to
|
| 6090 |
+
associate possibly the input sequence and possibly the output sequence
|
| 6091 |
+
with a sequence of arbitrary characters. The sequence is provided by an
|
| 6092 |
+
object of class `span<charT>`.
|
| 6093 |
+
|
| 6094 |
+
For the sake of exposition, the maintained data is presented here as:
|
| 6095 |
+
|
| 6096 |
+
- `ios_base::openmode mode`, has `in` set if the input sequence can be
|
| 6097 |
+
read, and `out` set if the output sequence can be written.
|
| 6098 |
+
- `std::span<charT> buf` is the view to the underlying character
|
| 6099 |
+
sequence.
|
| 6100 |
+
|
| 6101 |
+
#### Constructors <a id="spanbuf.cons">[[spanbuf.cons]]</a>
|
| 6102 |
+
|
| 6103 |
+
``` cpp
|
| 6104 |
+
explicit basic_spanbuf(std::span<charT> s,
|
| 6105 |
+
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 6106 |
+
```
|
| 6107 |
+
|
| 6108 |
+
*Effects:* Initializes the base class with `basic_streambuf()`
|
| 6109 |
+
[[streambuf.cons]], and *mode* with `which`. Initializes the internal
|
| 6110 |
+
pointers as if calling `span(s)`.
|
| 6111 |
+
|
| 6112 |
+
``` cpp
|
| 6113 |
+
basic_spanbuf(basic_spanbuf&& rhs);
|
| 6114 |
+
```
|
| 6115 |
+
|
| 6116 |
+
*Effects:* Initializes the base class with `std::move(rhs)` and *mode*
|
| 6117 |
+
with `std::move(rhs.`*`mode`*`)` and *buf* with
|
| 6118 |
+
`std::move(rhs.`*`buf`*`)`. The sequence pointers in `*this` (`eback()`,
|
| 6119 |
+
`gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) obtain the values
|
| 6120 |
+
which `rhs` had. It is *implementation-defined* whether
|
| 6121 |
+
`rhs.`*`buf`*`.empty()` returns `true` after the move.
|
| 6122 |
+
|
| 6123 |
+
*Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
|
| 6124 |
+
construction.
|
| 6125 |
+
|
| 6126 |
+
- `span().data() == rhs_p.span().data()`
|
| 6127 |
+
- `span().size() == rhs_p.span().size()`
|
| 6128 |
+
- `eback() == rhs_p.eback()`
|
| 6129 |
+
- `gptr() == rhs_p.gptr()`
|
| 6130 |
+
- `egptr() == rhs_p.egptr()`
|
| 6131 |
+
- `pbase() == rhs_p.pbase()`
|
| 6132 |
+
- `pptr() == rhs_p.pptr()`
|
| 6133 |
+
- `epptr() == rhs_p.epptr()`
|
| 6134 |
+
- `getloc() == rhs_p.getloc()`
|
| 6135 |
+
|
| 6136 |
+
#### Assignment and swap <a id="spanbuf.assign">[[spanbuf.assign]]</a>
|
| 6137 |
+
|
| 6138 |
+
``` cpp
|
| 6139 |
+
basic_spanbuf& operator=(basic_spanbuf&& rhs);
|
| 6140 |
+
```
|
| 6141 |
+
|
| 6142 |
+
*Effects:* Equivalent to:
|
| 6143 |
+
|
| 6144 |
+
``` cpp
|
| 6145 |
+
basic_spanbuf tmp{std::move(rhs)};
|
| 6146 |
+
this->swap(tmp);
|
| 6147 |
+
return *this;
|
| 6148 |
+
```
|
| 6149 |
+
|
| 6150 |
+
``` cpp
|
| 6151 |
+
void swap(basic_spanbuf& rhs);
|
| 6152 |
+
```
|
| 6153 |
+
|
| 6154 |
+
*Effects:* Equivalent to:
|
| 6155 |
+
|
| 6156 |
+
``` cpp
|
| 6157 |
+
basic_streambuf<charT, traits>::swap(rhs);
|
| 6158 |
+
std::swap(mode, rhs.mode);
|
| 6159 |
+
std::swap(buf, rhs.buf);
|
| 6160 |
+
```
|
| 6161 |
+
|
| 6162 |
+
``` cpp
|
| 6163 |
+
template<class charT, class traits>
|
| 6164 |
+
void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
|
| 6165 |
+
```
|
| 6166 |
+
|
| 6167 |
+
*Effects:* Equivalent to `x.swap(y)`.
|
| 6168 |
+
|
| 6169 |
+
#### Member functions <a id="spanbuf.members">[[spanbuf.members]]</a>
|
| 6170 |
+
|
| 6171 |
+
``` cpp
|
| 6172 |
+
std::span<charT> span() const noexcept;
|
| 6173 |
+
```
|
| 6174 |
+
|
| 6175 |
+
*Returns:* If `ios_base::out` is set in *mode*, returns
|
| 6176 |
+
`std::span<charT>(pbase(), pptr())`, otherwise returns *buf*.
|
| 6177 |
+
|
| 6178 |
+
[*Note 1*: In contrast to `basic_stringbuf`, the underlying sequence
|
| 6179 |
+
never grows and is not owned. An owning copy can be obtained by
|
| 6180 |
+
converting the result to `basic_string<charT>`. — *end note*]
|
| 6181 |
+
|
| 6182 |
+
``` cpp
|
| 6183 |
+
void span(std::span<charT> s) noexcept;
|
| 6184 |
+
```
|
| 6185 |
+
|
| 6186 |
+
*Effects:* *`buf`*` = s`. Initializes the input and output sequences
|
| 6187 |
+
according to *mode*.
|
| 6188 |
+
|
| 6189 |
+
*Ensures:*
|
| 6190 |
+
|
| 6191 |
+
- If `ios_base::out` is set in *mode*,
|
| 6192 |
+
`pbase() == s.data() && epptr() == pbase() + s.size()` is `true`;
|
| 6193 |
+
- in addition, if `ios_base::ate` is set in *mode*,
|
| 6194 |
+
`pptr() == pbase() + s.size()` is `true`,
|
| 6195 |
+
- otherwise `pptr() == pbase()` is `true`.
|
| 6196 |
+
- If `ios_base::in` is set in *mode*,
|
| 6197 |
+
`eback() == s.data() && gptr() == eback() && egptr() == eback() + s.size()`
|
| 6198 |
+
is `true`.
|
| 6199 |
+
|
| 6200 |
+
#### Overridden virtual functions <a id="spanbuf.virtuals">[[spanbuf.virtuals]]</a>
|
| 6201 |
+
|
| 6202 |
+
[*Note 1*: Because the underlying buffer is of fixed size, neither
|
| 6203 |
+
`overflow`, `underflow`, nor `pbackfail` can provide useful
|
| 6204 |
+
behavior. — *end note*]
|
| 6205 |
+
|
| 6206 |
+
``` cpp
|
| 6207 |
+
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 6208 |
+
ios_base::openmode which = ios_base::in | ios_base::out) override;
|
| 6209 |
+
```
|
| 6210 |
+
|
| 6211 |
+
*Effects:* Alters the stream position within one or both of the
|
| 6212 |
+
controlled sequences, if possible, as follows:
|
| 6213 |
+
|
| 6214 |
+
- If `ios_base::in` is set in `which`, positions the input sequence;
|
| 6215 |
+
`xnext` is `gptr()`, `xbeg` is `eback()`.
|
| 6216 |
+
- If `ios_base::out` is set in `which`, positions the output sequence;
|
| 6217 |
+
`xnext` is `pptr()`, `xbeg` is `pbase()`.
|
| 6218 |
+
|
| 6219 |
+
If both `ios_base::in` and `ios_base::out` are set in `which` and `way`
|
| 6220 |
+
is `ios_base::cur`, the positioning operation fails.
|
| 6221 |
+
|
| 6222 |
+
For a sequence to be positioned, if its next pointer `xnext` (either
|
| 6223 |
+
`gptr()` or `pptr()`) is a null pointer and the new offset `newoff` as
|
| 6224 |
+
computed below is nonzero, the positioning operation fails. Otherwise,
|
| 6225 |
+
the function determines `baseoff` as a value of type `off_type` as
|
| 6226 |
+
follows:
|
| 6227 |
+
|
| 6228 |
+
- `0` when `way` is `ios_base::beg`;
|
| 6229 |
+
- `(pptr() - pbase())` for the output sequence, or `(gptr() - eback())`
|
| 6230 |
+
for the input sequence when `way` is `ios_base::cur`;
|
| 6231 |
+
- when `way` is `ios_base::end` :
|
| 6232 |
+
- `(pptr() - pbase())` if `ios_base::out` is set in *mode* and
|
| 6233 |
+
`ios_base::in` is not set in *mode*,
|
| 6234 |
+
- `buf.size()` otherwise.
|
| 6235 |
+
|
| 6236 |
+
If `baseoff` + `off` would overflow, or if `baseoff` + `off` is less
|
| 6237 |
+
than zero, or if `baseoff` + `off` is greater than *`buf`*`.size()`, the
|
| 6238 |
+
positioning operation fails. Otherwise, the function computes
|
| 6239 |
+
|
| 6240 |
+
``` cpp
|
| 6241 |
+
off_type newoff = baseoff + off;
|
| 6242 |
+
```
|
| 6243 |
+
|
| 6244 |
+
and assigns `xbeg + newoff` to the next pointer `xnext`.
|
| 6245 |
+
|
| 6246 |
+
*Returns:* `pos_type(off_type(-1))` if the positioning operation fails;
|
| 6247 |
+
`pos_type(newoff)` otherwise.
|
| 6248 |
+
|
| 6249 |
+
``` cpp
|
| 6250 |
+
pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override;
|
| 6251 |
+
```
|
| 6252 |
+
|
| 6253 |
+
*Effects:* Equivalent to:
|
| 6254 |
+
|
| 6255 |
+
``` cpp
|
| 6256 |
+
return seekoff(off_type(sp), ios_base::beg, which);
|
| 6257 |
+
```
|
| 6258 |
+
|
| 6259 |
+
``` cpp
|
| 6260 |
+
basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n) override;
|
| 6261 |
+
```
|
| 6262 |
+
|
| 6263 |
+
*Effects:* Equivalent to:
|
| 6264 |
+
|
| 6265 |
+
``` cpp
|
| 6266 |
+
this->span(std::span<charT>(s, n));
|
| 6267 |
+
return this;
|
| 6268 |
+
```
|
| 6269 |
+
|
| 6270 |
+
### Class template `basic_ispanstream` <a id="ispanstream">[[ispanstream]]</a>
|
| 6271 |
+
|
| 6272 |
+
#### General <a id="ispanstream.general">[[ispanstream.general]]</a>
|
| 6273 |
+
|
| 6274 |
+
``` cpp
|
| 6275 |
+
namespace std {
|
| 6276 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6277 |
+
class basic_ispanstream
|
| 6278 |
+
: public basic_istream<charT, traits> {
|
| 6279 |
+
public:
|
| 6280 |
+
using char_type = charT;
|
| 6281 |
+
using int_type = typename traits::int_type;
|
| 6282 |
+
using pos_type = typename traits::pos_type;
|
| 6283 |
+
using off_type = typename traits::off_type;
|
| 6284 |
+
using traits_type = traits;
|
| 6285 |
+
|
| 6286 |
+
// [ispanstream.cons], constructors
|
| 6287 |
+
explicit basic_ispanstream(std::span<charT> s,
|
| 6288 |
+
ios_base::openmode which = ios_base::in);
|
| 6289 |
+
basic_ispanstream(const basic_ispanstream&) = delete;
|
| 6290 |
+
basic_ispanstream(basic_ispanstream&& rhs);
|
| 6291 |
+
template<class ROS> explicit basic_ispanstream(ROS&& s);
|
| 6292 |
+
|
| 6293 |
+
basic_ispanstream& operator=(const basic_ispanstream&) = delete;
|
| 6294 |
+
basic_ispanstream& operator=(basic_ispanstream&& rhs);
|
| 6295 |
+
|
| 6296 |
+
// [ispanstream.swap], swap
|
| 6297 |
+
void swap(basic_ispanstream& rhs);
|
| 6298 |
+
|
| 6299 |
+
// [ispanstream.members], member functions
|
| 6300 |
+
basic_spanbuf<charT, traits>* rdbuf() const noexcept;
|
| 6301 |
+
|
| 6302 |
+
std::span<const charT> span() const noexcept;
|
| 6303 |
+
void span(std::span<charT> s) noexcept;
|
| 6304 |
+
template<class ROS> void span(ROS&& s) noexcept;
|
| 6305 |
+
|
| 6306 |
+
private:
|
| 6307 |
+
basic_spanbuf<charT, traits> sb; // exposition only
|
| 6308 |
+
};
|
| 6309 |
+
}
|
| 6310 |
+
```
|
| 6311 |
+
|
| 6312 |
+
[*Note 1*: Constructing an `ispanstream` from a *string-literal*
|
| 6313 |
+
includes the termination character `'\0'` in the underlying
|
| 6314 |
+
`spanbuf`. — *end note*]
|
| 6315 |
+
|
| 6316 |
+
#### Constructors <a id="ispanstream.cons">[[ispanstream.cons]]</a>
|
| 6317 |
+
|
| 6318 |
+
``` cpp
|
| 6319 |
+
explicit basic_ispanstream(std::span<charT> s, ios_base::openmode which = ios_base::in);
|
| 6320 |
+
```
|
| 6321 |
+
|
| 6322 |
+
*Effects:* Initializes the base class with
|
| 6323 |
+
`basic_istream<charT, traits>(addressof(sb))` and `sb` with
|
| 6324 |
+
`basic_spanbuf<charT, traits>(s, which | ios_base::in)`
|
| 6325 |
+
[[spanbuf.cons]].
|
| 6326 |
+
|
| 6327 |
+
``` cpp
|
| 6328 |
+
basic_ispanstream(basic_ispanstream&& rhs);
|
| 6329 |
+
```
|
| 6330 |
+
|
| 6331 |
+
*Effects:* Initializes the base class with `std::move(rhs)` and `sb`
|
| 6332 |
+
with `std::move(rhs.sb)`. Next,
|
| 6333 |
+
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` is called to
|
| 6334 |
+
install the contained `basic_spanbuf`.
|
| 6335 |
+
|
| 6336 |
+
``` cpp
|
| 6337 |
+
template<class ROS> explicit basic_ispanstream(ROS&& s)
|
| 6338 |
+
```
|
| 6339 |
+
|
| 6340 |
+
*Constraints:* `ROS` models `ranges::borrowed_range`.
|
| 6341 |
+
`!convertible_to<ROS, std::span<charT>> && convertible_to<ROS, std::span<charT const>>`
|
| 6342 |
+
is `true`.
|
| 6343 |
+
|
| 6344 |
+
*Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
|
| 6345 |
+
Equivalent to
|
| 6346 |
+
|
| 6347 |
+
``` cpp
|
| 6348 |
+
basic_ispanstream(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
|
| 6349 |
+
```
|
| 6350 |
+
|
| 6351 |
+
#### Swap <a id="ispanstream.swap">[[ispanstream.swap]]</a>
|
| 6352 |
+
|
| 6353 |
+
``` cpp
|
| 6354 |
+
void swap(basic_ispanstream& rhs);
|
| 6355 |
+
```
|
| 6356 |
+
|
| 6357 |
+
*Effects:* Equivalent to:
|
| 6358 |
+
|
| 6359 |
+
``` cpp
|
| 6360 |
+
basic_istream<charT, traits>::swap(rhs);
|
| 6361 |
+
sb.swap(rhs.sb);
|
| 6362 |
+
```
|
| 6363 |
+
|
| 6364 |
+
``` cpp
|
| 6365 |
+
template<class charT, class traits>
|
| 6366 |
+
void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
|
| 6367 |
+
```
|
| 6368 |
+
|
| 6369 |
+
*Effects:* Equivalent to `x.swap(y)`.
|
| 6370 |
+
|
| 6371 |
+
#### Member functions <a id="ispanstream.members">[[ispanstream.members]]</a>
|
| 6372 |
+
|
| 6373 |
+
``` cpp
|
| 6374 |
+
basic_spanbuf<charT, traits>* rdbuf() const noexcept;
|
| 6375 |
+
```
|
| 6376 |
+
|
| 6377 |
+
*Effects:* Equivalent to:
|
| 6378 |
+
|
| 6379 |
+
``` cpp
|
| 6380 |
+
return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
|
| 6381 |
+
```
|
| 6382 |
+
|
| 6383 |
+
``` cpp
|
| 6384 |
+
std::span<const charT> span() const noexcept;
|
| 6385 |
+
```
|
| 6386 |
+
|
| 6387 |
+
*Effects:* Equivalent to: `return rdbuf()->span();`
|
| 6388 |
+
|
| 6389 |
+
``` cpp
|
| 6390 |
+
void span(std::span<charT> s) noexcept;
|
| 6391 |
+
```
|
| 6392 |
+
|
| 6393 |
+
*Effects:* Equivalent to `rdbuf()->span(s)`.
|
| 6394 |
+
|
| 6395 |
+
``` cpp
|
| 6396 |
+
template<class ROS> void span(ROS&& s) noexcept;
|
| 6397 |
+
```
|
| 6398 |
+
|
| 6399 |
+
*Constraints:* `ROS` models `ranges::borrowed_range`.
|
| 6400 |
+
`(!convertible_to<ROS, std::span<charT>>) && convertible_to<ROS, std::span<const charT>>`
|
| 6401 |
+
is `true`.
|
| 6402 |
+
|
| 6403 |
+
*Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
|
| 6404 |
+
Equivalent to:
|
| 6405 |
+
|
| 6406 |
+
``` cpp
|
| 6407 |
+
this->span(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
|
| 6408 |
+
```
|
| 6409 |
+
|
| 6410 |
+
### Class template `basic_ospanstream` <a id="ospanstream">[[ospanstream]]</a>
|
| 6411 |
+
|
| 6412 |
+
#### General <a id="ospanstream.general">[[ospanstream.general]]</a>
|
| 6413 |
+
|
| 6414 |
+
``` cpp
|
| 6415 |
+
namespace std {
|
| 6416 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6417 |
+
class basic_ospanstream
|
| 6418 |
+
: public basic_ostream<charT, traits> {
|
| 6419 |
+
public:
|
| 6420 |
+
using char_type = charT;
|
| 6421 |
+
using int_type = typename traits::int_type;
|
| 6422 |
+
using pos_type = typename traits::pos_type;
|
| 6423 |
+
using off_type = typename traits::off_type;
|
| 6424 |
+
using traits_type = traits;
|
| 6425 |
+
|
| 6426 |
+
// [ospanstream.cons], constructors
|
| 6427 |
+
explicit basic_ospanstream(std::span<charT> s,
|
| 6428 |
+
ios_base::openmode which = ios_base::out);
|
| 6429 |
+
basic_ospanstream(const basic_ospanstream&) = delete;
|
| 6430 |
+
basic_ospanstream(basic_ospanstream&& rhs);
|
| 6431 |
+
|
| 6432 |
+
basic_ospanstream& operator=(const basic_ospanstream&) = delete;
|
| 6433 |
+
basic_ospanstream& operator=(basic_ospanstream&& rhs);
|
| 6434 |
+
|
| 6435 |
+
// [ospanstream.swap], swap
|
| 6436 |
+
void swap(basic_ospanstream& rhs);
|
| 6437 |
+
|
| 6438 |
+
// [ospanstream.members], member functions
|
| 6439 |
+
basic_spanbuf<charT, traits>* rdbuf() const noexcept;
|
| 6440 |
+
|
| 6441 |
+
std::span<charT> span() const noexcept;
|
| 6442 |
+
void span(std::span<charT> s) noexcept;
|
| 6443 |
+
|
| 6444 |
+
private:
|
| 6445 |
+
basic_spanbuf<charT, traits> sb; // exposition only
|
| 6446 |
+
};
|
| 6447 |
+
}
|
| 6448 |
+
```
|
| 6449 |
+
|
| 6450 |
+
#### Constructors <a id="ospanstream.cons">[[ospanstream.cons]]</a>
|
| 6451 |
+
|
| 6452 |
+
``` cpp
|
| 6453 |
+
explicit basic_ospanstream(std::span<charT> s,
|
| 6454 |
+
ios_base::openmode which = ios_base::out);
|
| 6455 |
+
```
|
| 6456 |
+
|
| 6457 |
+
*Effects:* Initializes the base class with
|
| 6458 |
+
`basic_ostream<charT, traits>(addressof(sb))` and `sb` with
|
| 6459 |
+
`basic_spanbuf<charT, traits>(s, which | ios_base::out)`
|
| 6460 |
+
[[spanbuf.cons]].
|
| 6461 |
+
|
| 6462 |
+
``` cpp
|
| 6463 |
+
basic_ospanstream(basic_ospanstream&& rhs) noexcept;
|
| 6464 |
+
```
|
| 6465 |
+
|
| 6466 |
+
*Effects:* Initializes the base class with `std::move(rhs)` and `sb`
|
| 6467 |
+
with `std::move(rhs.sb)`. Next,
|
| 6468 |
+
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` is called to
|
| 6469 |
+
install the contained `basic_spanbuf`.
|
| 6470 |
+
|
| 6471 |
+
#### Swap <a id="ospanstream.swap">[[ospanstream.swap]]</a>
|
| 6472 |
+
|
| 6473 |
+
``` cpp
|
| 6474 |
+
void swap(basic_ospanstream& rhs);
|
| 6475 |
+
```
|
| 6476 |
+
|
| 6477 |
+
*Effects:* Equivalent to:
|
| 6478 |
+
|
| 6479 |
+
``` cpp
|
| 6480 |
+
basic_ostream<charT, traits>::swap(rhs);
|
| 6481 |
+
sb.swap(rhs.sb);
|
| 6482 |
+
```
|
| 6483 |
+
|
| 6484 |
+
``` cpp
|
| 6485 |
+
template<class charT, class traits>
|
| 6486 |
+
void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
|
| 6487 |
+
```
|
| 6488 |
+
|
| 6489 |
+
*Effects:* Equivalent to `x.swap(y)`.
|
| 6490 |
+
|
| 6491 |
+
#### Member functions <a id="ospanstream.members">[[ospanstream.members]]</a>
|
| 6492 |
+
|
| 6493 |
+
``` cpp
|
| 6494 |
+
basic_spanbuf<charT, traits>* rdbuf() const noexcept;
|
| 6495 |
+
```
|
| 6496 |
+
|
| 6497 |
+
*Effects:* Equivalent to:
|
| 6498 |
+
|
| 6499 |
+
``` cpp
|
| 6500 |
+
return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
|
| 6501 |
+
```
|
| 6502 |
+
|
| 6503 |
+
``` cpp
|
| 6504 |
+
std::span<charT> span() const noexcept;
|
| 6505 |
+
```
|
| 6506 |
+
|
| 6507 |
+
*Effects:* Equivalent to: `return rdbuf()->span();`
|
| 6508 |
+
|
| 6509 |
+
``` cpp
|
| 6510 |
+
void span(std::span<charT> s) noexcept;
|
| 6511 |
+
```
|
| 6512 |
+
|
| 6513 |
+
*Effects:* Equivalent to `rdbuf()->span(s)`.
|
| 6514 |
+
|
| 6515 |
+
### Class template `basic_spanstream` <a id="spanstream">[[spanstream]]</a>
|
| 6516 |
+
|
| 6517 |
+
#### General <a id="spanstream.general">[[spanstream.general]]</a>
|
| 6518 |
+
|
| 6519 |
+
``` cpp
|
| 6520 |
+
namespace std {
|
| 6521 |
+
template<class charT, class traits = char_traits<charT>>
|
| 6522 |
+
class basic_spanstream
|
| 6523 |
+
: public basic_iostream<charT, traits> {
|
| 6524 |
+
public:
|
| 6525 |
+
using char_type = charT;
|
| 6526 |
+
using int_type = typename traits::int_type;
|
| 6527 |
+
using pos_type = typename traits::pos_type;
|
| 6528 |
+
using off_type = typename traits::off_type;
|
| 6529 |
+
using traits_type = traits;
|
| 6530 |
+
|
| 6531 |
+
// [spanstream.cons], constructors
|
| 6532 |
+
explicit basic_spanstream(std::span<charT> s,
|
| 6533 |
+
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 6534 |
+
basic_spanstream(const basic_spanstream&) = delete;
|
| 6535 |
+
basic_spanstream(basic_spanstream&& rhs);
|
| 6536 |
+
|
| 6537 |
+
basic_spanstream& operator=(const basic_spanstream&) = delete;
|
| 6538 |
+
basic_spanstream& operator=(basic_spanstream&& rhs);
|
| 6539 |
+
|
| 6540 |
+
// [spanstream.swap], swap
|
| 6541 |
+
void swap(basic_spanstream& rhs);
|
| 6542 |
+
|
| 6543 |
+
// [spanstream.members], members
|
| 6544 |
+
basic_spanbuf<charT, traits>* rdbuf() const noexcept;
|
| 6545 |
+
|
| 6546 |
+
std::span<charT> span() const noexcept;
|
| 6547 |
+
void span(std::span<charT> s) noexcept;
|
| 6548 |
+
|
| 6549 |
+
private:
|
| 6550 |
+
basic_spanbuf<charT, traits> sb; // exposition only
|
| 6551 |
+
};
|
| 6552 |
+
}
|
| 6553 |
+
```
|
| 6554 |
+
|
| 6555 |
+
#### Constructors <a id="spanstream.cons">[[spanstream.cons]]</a>
|
| 6556 |
+
|
| 6557 |
+
``` cpp
|
| 6558 |
+
explicit basic_spanstream(std::span<charT> s,
|
| 6559 |
+
ios_base::openmode which = ios_base::out | ios_bas::in);
|
| 6560 |
+
```
|
| 6561 |
+
|
| 6562 |
+
*Effects:* Initializes the base class with
|
| 6563 |
+
`basic_iostream<charT, traits>(addressof(sb))` and `sb` with
|
| 6564 |
+
`basic_spanbuf<charT, traits>(s, which)` [[spanbuf.cons]].
|
| 6565 |
+
|
| 6566 |
+
``` cpp
|
| 6567 |
+
basic_spanstream(basic_spanstream&& rhs);
|
| 6568 |
+
```
|
| 6569 |
+
|
| 6570 |
+
*Effects:* Initializes the base class with `std::move(rhs)` and `sb`
|
| 6571 |
+
with `std::move(rhs.sb)`. Next,
|
| 6572 |
+
`basic_iostream<charT, traits>::set_rdbuf(addressof(sb))` is called to
|
| 6573 |
+
install the contained `basic_spanbuf`.
|
| 6574 |
+
|
| 6575 |
+
#### Swap <a id="spanstream.swap">[[spanstream.swap]]</a>
|
| 6576 |
+
|
| 6577 |
+
``` cpp
|
| 6578 |
+
void swap(basic_spanstream& rhs);
|
| 6579 |
+
```
|
| 6580 |
+
|
| 6581 |
+
*Effects:* Equivalent to:
|
| 6582 |
+
|
| 6583 |
+
``` cpp
|
| 6584 |
+
basic_iostream<charT, traits>::swap(rhs);
|
| 6585 |
+
sb.swap(rhs.sb);
|
| 6586 |
+
```
|
| 6587 |
+
|
| 6588 |
+
``` cpp
|
| 6589 |
+
template<class charT, class traits>
|
| 6590 |
+
void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
|
| 6591 |
+
```
|
| 6592 |
+
|
| 6593 |
+
*Effects:* Equivalent to `x.swap(y)`.
|
| 6594 |
+
|
| 6595 |
+
#### Member functions <a id="spanstream.members">[[spanstream.members]]</a>
|
| 6596 |
+
|
| 6597 |
+
``` cpp
|
| 6598 |
+
basic_spanbuf<charT, traits>* rdbuf() const noexcept;
|
| 6599 |
+
```
|
| 6600 |
+
|
| 6601 |
+
*Effects:* Equivalent to:
|
| 6602 |
+
|
| 6603 |
+
``` cpp
|
| 6604 |
+
return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
|
| 6605 |
+
```
|
| 6606 |
+
|
| 6607 |
+
``` cpp
|
| 6608 |
+
std::span<charT> span() const noexcept;
|
| 6609 |
+
```
|
| 6610 |
+
|
| 6611 |
+
*Effects:* Equivalent to: `return rdbuf()->span();`
|
| 6612 |
+
|
| 6613 |
+
``` cpp
|
| 6614 |
+
void span(std::span<charT> s) noexcept;
|
| 6615 |
+
```
|
| 6616 |
+
|
| 6617 |
+
*Effects:* Equivalent to `rdbuf()->span(s)`.
|
| 6618 |
+
|
| 6619 |
## File-based streams <a id="file.streams">[[file.streams]]</a>
|
| 6620 |
|
| 6621 |
### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
|
| 6622 |
|
| 6623 |
``` cpp
|
| 6624 |
namespace std {
|
| 6625 |
template<class charT, class traits = char_traits<charT>>
|
| 6626 |
class basic_filebuf;
|
| 6627 |
+
|
| 6628 |
+
template<class charT, class traits>
|
| 6629 |
+
void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
|
| 6630 |
+
|
| 6631 |
using filebuf = basic_filebuf<char>;
|
| 6632 |
using wfilebuf = basic_filebuf<wchar_t>;
|
| 6633 |
|
| 6634 |
template<class charT, class traits = char_traits<charT>>
|
| 6635 |
class basic_ifstream;
|
| 6636 |
+
|
| 6637 |
+
template<class charT, class traits>
|
| 6638 |
+
void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
|
| 6639 |
+
|
| 6640 |
using ifstream = basic_ifstream<char>;
|
| 6641 |
using wifstream = basic_ifstream<wchar_t>;
|
| 6642 |
|
| 6643 |
template<class charT, class traits = char_traits<charT>>
|
| 6644 |
class basic_ofstream;
|
| 6645 |
+
|
| 6646 |
+
template<class charT, class traits>
|
| 6647 |
+
void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
|
| 6648 |
+
|
| 6649 |
using ofstream = basic_ofstream<char>;
|
| 6650 |
using wofstream = basic_ofstream<wchar_t>;
|
| 6651 |
|
| 6652 |
template<class charT, class traits = char_traits<charT>>
|
| 6653 |
class basic_fstream;
|
| 6654 |
+
|
| 6655 |
+
template<class charT, class traits>
|
| 6656 |
+
void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);
|
| 6657 |
+
|
| 6658 |
using fstream = basic_fstream<char>;
|
| 6659 |
using wfstream = basic_fstream<wchar_t>;
|
| 6660 |
}
|
| 6661 |
```
|
| 6662 |
|
|
|
|
| 6669 |
file typically holds multibyte character sequences and the
|
| 6670 |
`basic_filebuf` object converts those multibyte sequences into wide
|
| 6671 |
character sequences. — *end note*]
|
| 6672 |
|
| 6673 |
In subclause [[file.streams]], member functions taking arguments of
|
| 6674 |
+
`const filesystem::path::value_type*` are only provided on systems where
|
| 6675 |
+
`filesystem::path::value_type` [[fs.class.path]] is not `char`.
|
| 6676 |
|
| 6677 |
[*Note 2*: These functions enable class `path` support for systems with
|
| 6678 |
a wide native path character type, such as `wchar_t`. — *end note*]
|
| 6679 |
|
| 6680 |
### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
|
| 6681 |
|
| 6682 |
+
#### General <a id="filebuf.general">[[filebuf.general]]</a>
|
| 6683 |
+
|
| 6684 |
``` cpp
|
| 6685 |
namespace std {
|
| 6686 |
template<class charT, class traits = char_traits<charT>>
|
| 6687 |
class basic_filebuf : public basic_streambuf<charT, traits> {
|
| 6688 |
public:
|
|
|
|
| 6696 |
basic_filebuf();
|
| 6697 |
basic_filebuf(const basic_filebuf&) = delete;
|
| 6698 |
basic_filebuf(basic_filebuf&& rhs);
|
| 6699 |
virtual ~basic_filebuf();
|
| 6700 |
|
| 6701 |
+
// [filebuf.assign], assignment and swap
|
| 6702 |
basic_filebuf& operator=(const basic_filebuf&) = delete;
|
| 6703 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 6704 |
void swap(basic_filebuf& rhs);
|
| 6705 |
|
| 6706 |
// [filebuf.members], members
|
|
|
|
| 6731 |
ios_base::openmode which
|
| 6732 |
= ios_base::in | ios_base::out) override;
|
| 6733 |
int sync() override;
|
| 6734 |
void imbue(const locale& loc) override;
|
| 6735 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6736 |
}
|
| 6737 |
```
|
| 6738 |
|
| 6739 |
The class `basic_filebuf<charT, traits>` associates both the input
|
| 6740 |
sequence and the output sequence with a file.
|
|
|
|
| 6832 |
|
| 6833 |
*Effects:* Exchanges the state of `*this` and `rhs`.
|
| 6834 |
|
| 6835 |
``` cpp
|
| 6836 |
template<class charT, class traits>
|
| 6837 |
+
void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
|
|
|
|
| 6838 |
```
|
| 6839 |
|
| 6840 |
*Effects:* Equivalent to: `x.swap(y)`.
|
| 6841 |
|
| 6842 |
#### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
|
|
|
|
| 6863 |
[[filebuf.open.modes]]. If `mode` is not some combination of flags shown
|
| 6864 |
in the table then the open fails.
|
| 6865 |
|
| 6866 |
**Table: File open modes** <a id="filebuf.open.modes">[filebuf.open.modes]</a>
|
| 6867 |
|
| 6868 |
+
| `binary` | `in` | `out` | `trunc` | `app` | `noreplace` | `stdio` equivalent |
|
| 6869 |
+
| -------- | ---- | ----- | ------- | ----- | ----------- | ------------------ |
|
| 6870 |
+
| | | + | | | | `"w"` |
|
| 6871 |
+
| | | + | | | + | `"wx"` |
|
| 6872 |
+
| | | + | + | | | `"w"` |
|
| 6873 |
+
| | | + | + | | + | `"wx"` |
|
| 6874 |
+
| | | + | | + | | `"a"` |
|
| 6875 |
+
| | | | | + | | `"a"` |
|
| 6876 |
+
| | + | | | | | `"r"` |
|
| 6877 |
+
| | + | + | | | | `"r+"` |
|
| 6878 |
+
| | + | + | + | | | `"w+"` |
|
| 6879 |
+
| | + | + | + | | + | `"w+x"` |
|
| 6880 |
+
| | + | + | | + | | `"a+"` |
|
| 6881 |
+
| | + | | | + | | `"a+"` |
|
| 6882 |
+
| + | | + | | | | `"wb"` |
|
| 6883 |
+
| + | | + | | | + | `"wbx"` |
|
| 6884 |
+
| + | | + | + | | | `"wb"` |
|
| 6885 |
+
| + | | + | + | | + | `"wbx"` |
|
| 6886 |
+
| + | | + | | + | | `"ab"` |
|
| 6887 |
+
| + | | | | + | | `"ab"` |
|
| 6888 |
+
| + | + | | | | | `"rb"` |
|
| 6889 |
+
| + | + | + | | | | `"r+b"` |
|
| 6890 |
+
| + | + | + | + | | | `"w+b"` |
|
| 6891 |
+
| + | + | + | + | | + | `"w+bx"` |
|
| 6892 |
+
| + | + | + | | + | | `"a+b"` |
|
| 6893 |
+
| + | + | | | + | | `"a+b"` |
|
| 6894 |
|
| 6895 |
|
| 6896 |
If the open operation succeeds and `ios_base::ate` is set in `mode`,
|
| 6897 |
positions the file to the end (as if by calling
|
| 6898 |
`fseek(file, 0, SEEK_END)`, where `file` is the pointer returned by
|
| 6899 |
+
calling `fopen`).[^38]
|
| 6900 |
|
| 6901 |
If the repositioning operation fails, calls `close()` and returns a null
|
| 6902 |
pointer to indicate failure.
|
| 6903 |
|
| 6904 |
*Returns:* `this` if successful, a null pointer otherwise.
|
|
|
|
| 6925 |
`fclose(file)`). If any of the calls made by the function, including
|
| 6926 |
`fclose`, fails, `close` fails by returning a null pointer. If one of
|
| 6927 |
these calls throws an exception, the exception is caught and rethrown
|
| 6928 |
after closing the file.
|
| 6929 |
|
| 6930 |
+
*Ensures:* `is_open() == false`.
|
| 6931 |
+
|
| 6932 |
*Returns:* `this` on success, a null pointer otherwise.
|
| 6933 |
|
|
|
|
|
|
|
| 6934 |
#### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
|
| 6935 |
|
| 6936 |
``` cpp
|
| 6937 |
streamsize showmanyc() override;
|
| 6938 |
```
|
| 6939 |
|
| 6940 |
*Effects:* Behaves the same as `basic_streambuf::showmanyc()`
|
| 6941 |
[[streambuf.virtuals]].
|
| 6942 |
|
| 6943 |
+
*Remarks:* An implementation may provide an overriding definition for
|
| 6944 |
+
this function signature if it can determine whether more characters can
|
| 6945 |
be read from the input sequence.
|
| 6946 |
|
| 6947 |
``` cpp
|
| 6948 |
int_type underflow() override;
|
| 6949 |
```
|
|
|
|
| 7065 |
and if the last operation was output, then update the output sequence
|
| 7066 |
and write any unshift sequence. Next, seek to the new position: if
|
| 7067 |
`width > 0`, call `fseek(file, width * off, whence)`, otherwise call
|
| 7068 |
`fseek(file, 0, whence)`.
|
| 7069 |
|
| 7070 |
+
*Returns:* A newly constructed `pos_type` object that stores the
|
| 7071 |
+
resultant stream position, if possible. If the positioning operation
|
| 7072 |
+
fails, or if the object cannot represent the resultant stream position,
|
| 7073 |
+
returns `pos_type(off_type(-1))`.
|
| 7074 |
+
|
| 7075 |
*Remarks:* “The last operation was output” means either the last virtual
|
| 7076 |
operation was overflow or the put buffer is non-empty. “Write any
|
| 7077 |
unshift sequence” means, if `width` if less than zero then call
|
| 7078 |
`a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
|
| 7079 |
resulting unshift sequence. The function determines one of three values
|
|
|
|
| 7086 |
| ---------------- | ------------------ |
|
| 7087 |
| `basic_ios::beg` | `SEEK_SET` |
|
| 7088 |
| `basic_ios::cur` | `SEEK_CUR` |
|
| 7089 |
| `basic_ios::end` | `SEEK_END` |
|
| 7090 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7091 |
``` cpp
|
| 7092 |
pos_type seekpos(pos_type sp,
|
| 7093 |
ios_base::openmode which
|
| 7094 |
= ios_base::in | ios_base::out) override;
|
| 7095 |
```
|
|
|
|
| 7139 |
characters. This in turn may require the implementation to be able to
|
| 7140 |
reconstruct the original contents of the file.
|
| 7141 |
|
| 7142 |
### Class template `basic_ifstream` <a id="ifstream">[[ifstream]]</a>
|
| 7143 |
|
| 7144 |
+
#### General <a id="ifstream.general">[[ifstream.general]]</a>
|
| 7145 |
+
|
| 7146 |
``` cpp
|
| 7147 |
namespace std {
|
| 7148 |
template<class charT, class traits = char_traits<charT>>
|
| 7149 |
class basic_ifstream : public basic_istream<charT, traits> {
|
| 7150 |
public:
|
|
|
|
| 7160 |
ios_base::openmode mode = ios_base::in);
|
| 7161 |
explicit basic_ifstream(const filesystem::path::value_type* s,
|
| 7162 |
ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
|
| 7163 |
explicit basic_ifstream(const string& s,
|
| 7164 |
ios_base::openmode mode = ios_base::in);
|
| 7165 |
+
template<class T>
|
| 7166 |
+
explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
|
| 7167 |
basic_ifstream(const basic_ifstream&) = delete;
|
| 7168 |
basic_ifstream(basic_ifstream&& rhs);
|
| 7169 |
|
|
|
|
| 7170 |
basic_ifstream& operator=(const basic_ifstream&) = delete;
|
| 7171 |
basic_ifstream& operator=(basic_ifstream&& rhs);
|
| 7172 |
+
|
| 7173 |
+
// [ifstream.swap], swap
|
| 7174 |
void swap(basic_ifstream& rhs);
|
| 7175 |
|
| 7176 |
// [ifstream.members], members
|
| 7177 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 7178 |
|
|
|
|
| 7181 |
void open(const filesystem::path::value_type* s,
|
| 7182 |
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 7183 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
| 7184 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
|
| 7185 |
void close();
|
| 7186 |
+
|
| 7187 |
private:
|
| 7188 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 7189 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7190 |
}
|
| 7191 |
```
|
| 7192 |
|
| 7193 |
The class `basic_ifstream<charT, traits>` supports reading from named
|
| 7194 |
files. It uses a `basic_filebuf<{}charT, traits>` object to control the
|
|
|
|
| 7221 |
pointer, calls `setstate(failbit)`.
|
| 7222 |
|
| 7223 |
``` cpp
|
| 7224 |
explicit basic_ifstream(const string& s,
|
| 7225 |
ios_base::openmode mode = ios_base::in);
|
|
|
|
|
|
|
| 7226 |
```
|
| 7227 |
|
| 7228 |
*Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
|
| 7229 |
|
| 7230 |
+
``` cpp
|
| 7231 |
+
template<class T>
|
| 7232 |
+
explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
|
| 7233 |
+
```
|
| 7234 |
+
|
| 7235 |
+
*Constraints:* `is_same_v<T, filesystem::path>` is `true`.
|
| 7236 |
+
|
| 7237 |
+
*Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
|
| 7238 |
+
|
| 7239 |
``` cpp
|
| 7240 |
basic_ifstream(basic_ifstream&& rhs);
|
| 7241 |
```
|
| 7242 |
|
| 7243 |
*Effects:* Move constructs the base class, and the contained
|
| 7244 |
`basic_filebuf`. Then calls
|
| 7245 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 7246 |
contained `basic_filebuf`.
|
| 7247 |
|
| 7248 |
+
#### Swap <a id="ifstream.swap">[[ifstream.swap]]</a>
|
| 7249 |
|
| 7250 |
``` cpp
|
| 7251 |
void swap(basic_ifstream& rhs);
|
| 7252 |
```
|
| 7253 |
|
| 7254 |
*Effects:* Exchanges the state of `*this` and `rhs` by calling
|
| 7255 |
`basic_istream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
|
| 7256 |
|
| 7257 |
``` cpp
|
| 7258 |
template<class charT, class traits>
|
| 7259 |
+
void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
|
|
|
|
| 7260 |
```
|
| 7261 |
|
| 7262 |
*Effects:* Equivalent to: `x.swap(y)`.
|
| 7263 |
|
| 7264 |
#### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
|
|
|
|
| 7301 |
pointer, calls `setstate(failbit)` (which may throw
|
| 7302 |
`ios_base::failure`) [[iostate.flags]].
|
| 7303 |
|
| 7304 |
### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
|
| 7305 |
|
| 7306 |
+
#### General <a id="ofstream.general">[[ofstream.general]]</a>
|
| 7307 |
+
|
| 7308 |
``` cpp
|
| 7309 |
namespace std {
|
| 7310 |
template<class charT, class traits = char_traits<charT>>
|
| 7311 |
class basic_ofstream : public basic_ostream<charT, traits> {
|
| 7312 |
public:
|
|
|
|
| 7322 |
ios_base::openmode mode = ios_base::out);
|
| 7323 |
explicit basic_ofstream(const filesystem::path::value_type* s, // wide systems only; see [fstream.syn]
|
| 7324 |
ios_base::openmode mode = ios_base::out);
|
| 7325 |
explicit basic_ofstream(const string& s,
|
| 7326 |
ios_base::openmode mode = ios_base::out);
|
| 7327 |
+
template<class T>
|
| 7328 |
+
explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
|
| 7329 |
basic_ofstream(const basic_ofstream&) = delete;
|
| 7330 |
basic_ofstream(basic_ofstream&& rhs);
|
| 7331 |
|
|
|
|
| 7332 |
basic_ofstream& operator=(const basic_ofstream&) = delete;
|
| 7333 |
basic_ofstream& operator=(basic_ofstream&& rhs);
|
| 7334 |
+
|
| 7335 |
+
// [ofstream.swap], swap
|
| 7336 |
void swap(basic_ofstream& rhs);
|
| 7337 |
|
| 7338 |
// [ofstream.members], members
|
| 7339 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 7340 |
|
|
|
|
| 7343 |
void open(const filesystem::path::value_type* s,
|
| 7344 |
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 7345 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
| 7346 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
|
| 7347 |
void close();
|
| 7348 |
+
|
| 7349 |
private:
|
| 7350 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 7351 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7352 |
}
|
| 7353 |
```
|
| 7354 |
|
| 7355 |
The class `basic_ofstream<charT, traits>` supports writing to named
|
| 7356 |
files. It uses a `basic_filebuf<{}charT, traits>` object to control the
|
|
|
|
| 7383 |
null pointer, calls `setstate(failbit)`.
|
| 7384 |
|
| 7385 |
``` cpp
|
| 7386 |
explicit basic_ofstream(const string& s,
|
| 7387 |
ios_base::openmode mode = ios_base::out);
|
|
|
|
|
|
|
| 7388 |
```
|
| 7389 |
|
| 7390 |
*Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
|
| 7391 |
|
| 7392 |
+
``` cpp
|
| 7393 |
+
template<class T>
|
| 7394 |
+
explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
|
| 7395 |
+
```
|
| 7396 |
+
|
| 7397 |
+
*Constraints:* `is_same_v<T, filesystem::path>` is `true`.
|
| 7398 |
+
|
| 7399 |
+
*Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
|
| 7400 |
+
|
| 7401 |
``` cpp
|
| 7402 |
basic_ofstream(basic_ofstream&& rhs);
|
| 7403 |
```
|
| 7404 |
|
| 7405 |
*Effects:* Move constructs the base class, and the contained
|
| 7406 |
`basic_filebuf`. Then calls
|
| 7407 |
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 7408 |
contained `basic_filebuf`.
|
| 7409 |
|
| 7410 |
+
#### Swap <a id="ofstream.swap">[[ofstream.swap]]</a>
|
| 7411 |
|
| 7412 |
``` cpp
|
| 7413 |
void swap(basic_ofstream& rhs);
|
| 7414 |
```
|
| 7415 |
|
| 7416 |
*Effects:* Exchanges the state of `*this` and `rhs` by calling
|
| 7417 |
`basic_ostream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
|
| 7418 |
|
| 7419 |
``` cpp
|
| 7420 |
template<class charT, class traits>
|
| 7421 |
+
void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
|
|
|
|
| 7422 |
```
|
| 7423 |
|
| 7424 |
*Effects:* Equivalent to: `x.swap(y)`.
|
| 7425 |
|
| 7426 |
#### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
|
|
|
|
| 7463 |
|
| 7464 |
*Effects:* Calls `open(s.c_str(), mode)`.
|
| 7465 |
|
| 7466 |
### Class template `basic_fstream` <a id="fstream">[[fstream]]</a>
|
| 7467 |
|
| 7468 |
+
#### General <a id="fstream.general">[[fstream.general]]</a>
|
| 7469 |
+
|
| 7470 |
``` cpp
|
| 7471 |
namespace std {
|
| 7472 |
template<class charT, class traits = char_traits<charT>>
|
| 7473 |
class basic_fstream : public basic_iostream<charT, traits> {
|
| 7474 |
public:
|
|
|
|
| 7487 |
const filesystem::path::value_type* s,
|
| 7488 |
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 7489 |
explicit basic_fstream(
|
| 7490 |
const string& s,
|
| 7491 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 7492 |
+
template<class T>
|
| 7493 |
+
explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
|
|
|
|
| 7494 |
basic_fstream(const basic_fstream&) = delete;
|
| 7495 |
basic_fstream(basic_fstream&& rhs);
|
| 7496 |
|
|
|
|
| 7497 |
basic_fstream& operator=(const basic_fstream&) = delete;
|
| 7498 |
basic_fstream& operator=(basic_fstream&& rhs);
|
| 7499 |
+
|
| 7500 |
+
// [fstream.swap], swap
|
| 7501 |
void swap(basic_fstream& rhs);
|
| 7502 |
|
| 7503 |
// [fstream.members], members
|
| 7504 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 7505 |
bool is_open() const;
|
|
|
|
| 7518 |
void close();
|
| 7519 |
|
| 7520 |
private:
|
| 7521 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 7522 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7523 |
}
|
| 7524 |
```
|
| 7525 |
|
| 7526 |
The class template `basic_fstream<charT, traits>` supports reading and
|
| 7527 |
writing from named files. It uses a `basic_filebuf<charT, traits>`
|
|
|
|
| 7557 |
|
| 7558 |
``` cpp
|
| 7559 |
explicit basic_fstream(
|
| 7560 |
const string& s,
|
| 7561 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
|
|
|
|
|
|
|
|
|
| 7562 |
```
|
| 7563 |
|
| 7564 |
*Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
|
| 7565 |
|
| 7566 |
+
``` cpp
|
| 7567 |
+
template<class T>
|
| 7568 |
+
explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 7569 |
+
```
|
| 7570 |
+
|
| 7571 |
+
*Constraints:* `is_same_v<T, filesystem::path>` is `true`.
|
| 7572 |
+
|
| 7573 |
+
*Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
|
| 7574 |
+
|
| 7575 |
``` cpp
|
| 7576 |
basic_fstream(basic_fstream&& rhs);
|
| 7577 |
```
|
| 7578 |
|
| 7579 |
*Effects:* Move constructs the base class, and the contained
|
| 7580 |
`basic_filebuf`. Then calls
|
| 7581 |
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 7582 |
contained `basic_filebuf`.
|
| 7583 |
|
| 7584 |
+
#### Swap <a id="fstream.swap">[[fstream.swap]]</a>
|
| 7585 |
|
| 7586 |
``` cpp
|
| 7587 |
void swap(basic_fstream& rhs);
|
| 7588 |
```
|
| 7589 |
|
|
|
|
| 7654 |
|
| 7655 |
namespace std {
|
| 7656 |
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 7657 |
class basic_syncbuf;
|
| 7658 |
|
| 7659 |
+
// [syncstream.syncbuf.special], specialized algorithms
|
| 7660 |
+
template<class charT, class traits, class Allocator>
|
| 7661 |
+
void swap(basic_syncbuf<charT, traits, Allocator>&,
|
| 7662 |
+
basic_syncbuf<charT, traits, Allocator>&);
|
| 7663 |
+
|
| 7664 |
using syncbuf = basic_syncbuf<char>;
|
| 7665 |
using wsyncbuf = basic_syncbuf<wchar_t>;
|
| 7666 |
|
| 7667 |
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 7668 |
class basic_osyncstream;
|
|
|
|
| 7718 |
|
| 7719 |
private:
|
| 7720 |
streambuf_type* wrapped; // exposition only
|
| 7721 |
bool emit_on_sync{}; // exposition only
|
| 7722 |
};
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7723 |
}
|
| 7724 |
```
|
| 7725 |
|
| 7726 |
Class template `basic_syncbuf` stores character data written to it,
|
| 7727 |
known as the associated output, into internal buffers allocated using
|
|
|
|
| 7737 |
basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
|
| 7738 |
```
|
| 7739 |
|
| 7740 |
*Effects:* Sets `wrapped` to `obuf`.
|
| 7741 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7742 |
*Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
|
| 7743 |
are `true`.
|
| 7744 |
|
| 7745 |
+
*Throws:* Nothing unless an exception is thrown by the construction of a
|
| 7746 |
+
mutex or by memory allocation.
|
| 7747 |
+
|
| 7748 |
+
*Remarks:* A copy of `allocator` is used to allocate memory for internal
|
| 7749 |
+
buffers holding the associated output.
|
| 7750 |
+
|
| 7751 |
``` cpp
|
| 7752 |
basic_syncbuf(basic_syncbuf&& other);
|
| 7753 |
```
|
| 7754 |
|
| 7755 |
*Ensures:* The value returned by `this->get_wrapped()` is the value
|
| 7756 |
returned by `other.get_wrapped()` prior to calling this constructor.
|
| 7757 |
Output stored in `other` prior to calling this constructor will be
|
| 7758 |
+
stored in `*this` afterwards. `other.pbase() == other.pptr()` and
|
|
|
|
| 7759 |
`other.get_wrapped() == nullptr` are `true`.
|
| 7760 |
|
| 7761 |
*Remarks:* This constructor disassociates `other` from its wrapped
|
| 7762 |
stream buffer, ensuring destruction of `other` produces no output.
|
| 7763 |
|
|
|
|
| 7771 |
destructor catches and ignores that exception.
|
| 7772 |
|
| 7773 |
#### Assignment and swap <a id="syncstream.syncbuf.assign">[[syncstream.syncbuf.assign]]</a>
|
| 7774 |
|
| 7775 |
``` cpp
|
| 7776 |
+
basic_syncbuf& operator=(basic_syncbuf&& rhs);
|
| 7777 |
```
|
| 7778 |
|
| 7779 |
*Effects:* Calls `emit()` then move assigns from `rhs`. After the move
|
| 7780 |
assignment `*this` has the observable state it would have had if it had
|
| 7781 |
been move constructed from `rhs` [[syncstream.syncbuf.cons]].
|
| 7782 |
|
|
|
|
|
|
|
| 7783 |
*Ensures:*
|
| 7784 |
|
| 7785 |
- `rhs.get_wrapped() == nullptr` is `true`.
|
| 7786 |
- `this->get_allocator() == rhs.get_allocator()` is `true` when
|
| 7787 |
``` cpp
|
| 7788 |
allocator_traits<Allocator>::propagate_on_container_move_assignment::value
|
| 7789 |
```
|
| 7790 |
|
| 7791 |
is `true`; otherwise, the allocator is unchanged.
|
| 7792 |
|
| 7793 |
+
*Returns:* `*this`.
|
| 7794 |
+
|
| 7795 |
*Remarks:* This assignment operator disassociates `rhs` from its wrapped
|
| 7796 |
stream buffer, ensuring destruction of `rhs` produces no output.
|
| 7797 |
|
| 7798 |
``` cpp
|
| 7799 |
+
void swap(basic_syncbuf& other);
|
| 7800 |
```
|
| 7801 |
|
| 7802 |
*Preconditions:* Either
|
| 7803 |
`allocator_traits<Allocator>::propagate_on_container_swap::value` is
|
| 7804 |
`true` or `this->get_allocator() == other.get_allocator()` is `true`.
|
|
|
|
| 7815 |
stream buffer `*wrapped`, so that it appears in the output stream as a
|
| 7816 |
contiguous sequence of characters. `wrapped->pubsync()` is called if and
|
| 7817 |
only if a call was made to `sync()` since the most recent call to
|
| 7818 |
`emit()`, if any.
|
| 7819 |
|
| 7820 |
+
*Synchronization:* All `emit()` calls transferring characters to the
|
| 7821 |
+
same stream buffer object appear to execute in a total order consistent
|
| 7822 |
+
with the “happens before” relation [[intro.races]], where each `emit()`
|
| 7823 |
+
call synchronizes with subsequent `emit()` calls in that total order.
|
| 7824 |
+
|
| 7825 |
+
*Ensures:* On success, the associated output is empty.
|
| 7826 |
+
|
| 7827 |
*Returns:* `true` if all of the following conditions hold; otherwise
|
| 7828 |
`false`:
|
| 7829 |
|
| 7830 |
- `wrapped == nullptr` is `false`.
|
| 7831 |
- All of the characters in the associated output were successfully
|
| 7832 |
transferred.
|
| 7833 |
- The call to `wrapped->pubsync()` (if any) succeeded.
|
| 7834 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7835 |
*Remarks:* May call member functions of `wrapped` while holding a lock
|
| 7836 |
uniquely associated with `wrapped`.
|
| 7837 |
|
| 7838 |
``` cpp
|
| 7839 |
streambuf_type* get_wrapped() const noexcept;
|
|
|
|
| 7872 |
#### Specialized algorithms <a id="syncstream.syncbuf.special">[[syncstream.syncbuf.special]]</a>
|
| 7873 |
|
| 7874 |
``` cpp
|
| 7875 |
template<class charT, class traits, class Allocator>
|
| 7876 |
void swap(basic_syncbuf<charT, traits, Allocator>& a,
|
| 7877 |
+
basic_syncbuf<charT, traits, Allocator>& b);
|
| 7878 |
```
|
| 7879 |
|
| 7880 |
*Effects:* Equivalent to `a.swap(b)`.
|
| 7881 |
|
| 7882 |
### Class template `basic_osyncstream` <a id="syncstream.osyncstream">[[syncstream.osyncstream]]</a>
|
|
|
|
| 7908 |
: basic_osyncstream(os, Allocator()) {}
|
| 7909 |
basic_osyncstream(basic_osyncstream&&) noexcept;
|
| 7910 |
~basic_osyncstream();
|
| 7911 |
|
| 7912 |
// assignment
|
| 7913 |
+
basic_osyncstream& operator=(basic_osyncstream&&);
|
| 7914 |
|
| 7915 |
// [syncstream.osyncstream.members], member functions
|
| 7916 |
void emit();
|
| 7917 |
streambuf_type* get_wrapped() const noexcept;
|
| 7918 |
syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); }
|
|
|
|
| 7921 |
syncbuf_type sb; // exposition only
|
| 7922 |
};
|
| 7923 |
}
|
| 7924 |
```
|
| 7925 |
|
| 7926 |
+
`Allocator` shall meet the *Cpp17Allocator* requirements
|
| 7927 |
+
[[allocator.requirements.general]].
|
| 7928 |
|
| 7929 |
[*Example 1*:
|
| 7930 |
|
| 7931 |
A named variable can be used within a block statement for streaming.
|
| 7932 |
|
|
|
|
| 7961 |
```
|
| 7962 |
|
| 7963 |
*Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
|
| 7964 |
base class with `basic_ostream<charT, traits>(addressof(sb))`.
|
| 7965 |
|
| 7966 |
+
[*Note 1*: The member functions of the provided stream buffer can be
|
| 7967 |
+
called from `emit()` while a lock is held, which might result in a
|
| 7968 |
+
deadlock if used incautiously. — *end note*]
|
| 7969 |
|
| 7970 |
*Ensures:* `get_wrapped() == buf` is `true`.
|
| 7971 |
|
| 7972 |
``` cpp
|
| 7973 |
basic_osyncstream(basic_osyncstream&& other) noexcept;
|
|
|
|
| 7976 |
*Effects:* Move constructs the base class and `sb` from the
|
| 7977 |
corresponding subobjects of `other`, and calls
|
| 7978 |
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
|
| 7979 |
|
| 7980 |
*Ensures:* The value returned by `get_wrapped()` is the value returned
|
| 7981 |
+
by `other.get_wrapped()` prior to calling this constructor.
|
| 7982 |
`nullptr == other.get_wrapped()` is `true`.
|
| 7983 |
|
| 7984 |
#### Member functions <a id="syncstream.osyncstream.members">[[syncstream.osyncstream.members]]</a>
|
| 7985 |
|
| 7986 |
``` cpp
|
| 7987 |
void emit();
|
| 7988 |
```
|
| 7989 |
|
| 7990 |
+
*Effects:* Behaves as an unformatted output
|
| 7991 |
+
function [[ostream.unformatted]]. After constructing a `sentry` object,
|
| 7992 |
+
calls `sb.emit()`. If that call returns `false`, calls
|
| 7993 |
`setstate(ios_base::badbit)`.
|
| 7994 |
|
| 7995 |
[*Example 1*:
|
| 7996 |
|
| 7997 |
A flush on a `basic_osyncstream` does not flush immediately:
|
|
|
|
| 8101 |
does not exist, the symbolic link is said to be a “dangling” symbolic
|
| 8102 |
link. — *end note*]
|
| 8103 |
|
| 8104 |
### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
|
| 8105 |
|
| 8106 |
+
#### General <a id="fs.conformance.general">[[fs.conformance.general]]</a>
|
| 8107 |
+
|
| 8108 |
Conformance is specified in terms of behavior. Ideal behavior is not
|
| 8109 |
always implementable, so the conformance subclauses take that into
|
| 8110 |
account.
|
| 8111 |
|
| 8112 |
#### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
|
| 8113 |
|
| 8114 |
+
Some behavior is specified by reference to POSIX. How such behavior is
|
| 8115 |
+
actually implemented is unspecified.
|
| 8116 |
|
| 8117 |
[*Note 1*: This constitutes an “as if” rule allowing implementations to
|
| 8118 |
call native operating system or other APIs. — *end note*]
|
| 8119 |
|
| 8120 |
Implementations should provide such behavior as it is defined by POSIX.
|
|
|
|
| 8153 |
#### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
|
| 8154 |
|
| 8155 |
A *file system race* is the condition that occurs when multiple threads,
|
| 8156 |
processes, or computers interleave access and modification of the same
|
| 8157 |
object within a file system. Behavior is undefined if calls to functions
|
| 8158 |
+
provided by subclause [[filesystems]] introduce a file system race.
|
|
|
|
| 8159 |
|
| 8160 |
If the possibility of a file system race would make it unreliable for a
|
| 8161 |
program to test for a precondition before calling a function described
|
| 8162 |
herein, *Preconditions:* is not specified for the function.
|
| 8163 |
|
| 8164 |
[*Note 1*: As a design practice, preconditions are not specified when
|
| 8165 |
it is unreasonable for a program to detect them prior to calling the
|
| 8166 |
function. — *end note*]
|
| 8167 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8168 |
### Requirements <a id="fs.req">[[fs.req]]</a>
|
| 8169 |
|
| 8170 |
Throughout subclause [[filesystems]], `char`, `wchar_t`, `char8_t`,
|
| 8171 |
`char16_t`, and `char32_t` are collectively called *encoded character
|
| 8172 |
types*.
|
|
|
|
| 8183 |
character set and encoding. Since `signed char` and `unsigned char` have
|
| 8184 |
no implied character set and encoding, they are not included as
|
| 8185 |
permitted types. — *end note*]
|
| 8186 |
|
| 8187 |
Template parameters named `Allocator` shall meet the *Cpp17Allocator*
|
| 8188 |
+
requirements [[allocator.requirements.general]].
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8189 |
|
| 8190 |
### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
|
| 8191 |
|
| 8192 |
``` cpp
|
| 8193 |
#include <compare> // see [compare.syn]
|
|
|
|
| 8209 |
// [fs.class.directory.iterator], directory iterators
|
| 8210 |
class directory_iterator;
|
| 8211 |
|
| 8212 |
// [fs.dir.itr.nonmembers], range access for directory iterators
|
| 8213 |
directory_iterator begin(directory_iterator iter) noexcept;
|
| 8214 |
+
directory_iterator end(directory_iterator) noexcept;
|
| 8215 |
|
| 8216 |
// [fs.class.rec.dir.itr], recursive directory iterators
|
| 8217 |
class recursive_directory_iterator;
|
| 8218 |
|
| 8219 |
// [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
|
| 8220 |
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 8221 |
+
recursive_directory_iterator end(recursive_directory_iterator) noexcept;
|
| 8222 |
|
| 8223 |
// [fs.class.file.status], file status
|
| 8224 |
class file_status;
|
| 8225 |
|
| 8226 |
struct space_info {
|
|
|
|
| 8386 |
path temp_directory_path(error_code& ec);
|
| 8387 |
|
| 8388 |
path weakly_canonical(const path& p);
|
| 8389 |
path weakly_canonical(const path& p, error_code& ec);
|
| 8390 |
}
|
| 8391 |
+
|
| 8392 |
+
// [fs.path.hash], hash support
|
| 8393 |
+
namespace std {
|
| 8394 |
+
template<class T> struct hash;
|
| 8395 |
+
template<> struct hash<filesystem::path>;
|
| 8396 |
+
}
|
| 8397 |
+
|
| 8398 |
+
namespace std::ranges {
|
| 8399 |
+
template<>
|
| 8400 |
+
inline constexpr bool enable_borrowed_range<filesystem::directory_iterator> = true;
|
| 8401 |
+
template<>
|
| 8402 |
+
inline constexpr bool enable_borrowed_range<filesystem::recursive_directory_iterator> = true;
|
| 8403 |
+
|
| 8404 |
+
template<>
|
| 8405 |
+
inline constexpr bool enable_view<filesystem::directory_iterator> = true;
|
| 8406 |
+
template<>
|
| 8407 |
+
inline constexpr bool enable_view<filesystem::recursive_directory_iterator> = true;
|
| 8408 |
+
}
|
| 8409 |
```
|
| 8410 |
|
| 8411 |
Implementations should ensure that the resolution and range of
|
| 8412 |
`file_time_type` reflect the operating system dependent resolution and
|
| 8413 |
range of file time values.
|
|
|
|
| 8458 |
appropriate for the specific operating system dependent error.
|
| 8459 |
Otherwise, `clear()` is called on the `error_code&` argument.
|
| 8460 |
|
| 8461 |
### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
|
| 8462 |
|
| 8463 |
+
#### General <a id="fs.class.path.general">[[fs.class.path.general]]</a>
|
| 8464 |
+
|
| 8465 |
An object of class `path` represents a path and contains a pathname.
|
| 8466 |
Such an object is concerned only with the lexical and syntactic aspects
|
| 8467 |
of a path. The path does not necessarily exist in external storage, and
|
| 8468 |
the pathname is not necessarily valid for the current operating system
|
| 8469 |
or for a particular file system.
|
|
|
|
| 8485 |
dependent. A *relative path* is a path that is not absolute, and as
|
| 8486 |
such, only unambiguously identifies the location of a file when resolved
|
| 8487 |
relative to an implied starting location. The elements of a path that
|
| 8488 |
determine if it is relative are operating system dependent.
|
| 8489 |
|
| 8490 |
+
[*Note 2*: Pathnames “.” and “..” are relative paths. — *end note*]
|
| 8491 |
|
| 8492 |
A *pathname* is a character string that represents the name of a path.
|
| 8493 |
Pathnames are formatted according to the generic pathname format grammar
|
| 8494 |
[[fs.path.generic]] or according to an operating system dependent
|
| 8495 |
*native pathname format* accepted by the host operating system.
|
| 8496 |
|
| 8497 |
*Pathname resolution* is the operating system dependent mechanism for
|
| 8498 |
resolving a pathname to a particular file in a file hierarchy. There may
|
| 8499 |
be multiple pathnames that resolve to the same file.
|
| 8500 |
|
| 8501 |
+
[*Example 1*: POSIX specifies the mechanism in section 4.12, Pathname
|
| 8502 |
resolution. — *end example*]
|
| 8503 |
|
| 8504 |
``` cpp
|
| 8505 |
namespace std::filesystem {
|
| 8506 |
class path {
|
|
|
|
| 8718 |
special meaning. The following characteristics of filenames are
|
| 8719 |
operating system dependent:
|
| 8720 |
|
| 8721 |
- The permitted characters. \[*Example 1*: Some operating systems
|
| 8722 |
prohibit the ASCII control characters (0x00 – 0x1F) in
|
| 8723 |
+
filenames. — *end example*] \[*Note 1*: Wider portability can be
|
| 8724 |
+
achieved by limiting *filename* characters to the POSIX Portable
|
| 8725 |
+
Filename Character Set:
|
| 8726 |
`A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
|
| 8727 |
`a b c d e f g h i j k l m n o p q r s t u v w x y z`
|
| 8728 |
`0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
|
| 8729 |
- The maximum permitted length.
|
| 8730 |
- Filenames that are not permitted.
|
|
|
|
| 8749 |
required.
|
| 8750 |
|
| 8751 |
[*Note 2*: Many operating systems define a name beginning with two
|
| 8752 |
*directory-separator* characters as a *root-name* that identifies
|
| 8753 |
network or other resource locations. Some operating systems define a
|
| 8754 |
+
single letter followed by a colon as a drive specifier — a *root-name*
|
| 8755 |
identifying a specific device such as a disk drive. — *end note*]
|
| 8756 |
|
| 8757 |
If a *root-name* is otherwise ambiguous, the possibility with the
|
| 8758 |
longest sequence of characters is chosen.
|
| 8759 |
|
|
|
|
| 8765 |
|
| 8766 |
1. If the path is empty, stop.
|
| 8767 |
2. Replace each slash character in the *root-name* with a
|
| 8768 |
*preferred-separator*.
|
| 8769 |
3. Replace each *directory-separator* with a *preferred-separator*.
|
| 8770 |
+
\[*Note 4*: The generic pathname grammar defines
|
| 8771 |
*directory-separator* as one or more slashes and
|
| 8772 |
*preferred-separator*s. — *end note*]
|
| 8773 |
4. Remove each dot filename and any immediately following
|
| 8774 |
*directory-separator*.
|
| 8775 |
5. As long as any appear, remove a non-dot-dot filename immediately
|
|
|
|
| 8809 |
or a pathname in the native format [[fs.class.path]]. Such an argument
|
| 8810 |
is taken to be in the generic format if and only if it matches the
|
| 8811 |
generic format and is not acceptable to the operating system as a native
|
| 8812 |
path.
|
| 8813 |
|
| 8814 |
+
[*Note 2*: Some operating systems have no unambiguous way to
|
| 8815 |
distinguish between native format and generic format arguments. This is
|
| 8816 |
by design as it simplifies use for operating systems that do not require
|
| 8817 |
disambiguation. An implementation for an operating system where
|
| 8818 |
disambiguation is required is permitted to distinguish between the
|
| 8819 |
formats. — *end note*]
|
|
|
|
| 8832 |
directory path if its last element is a *directory-separator*, otherwise
|
| 8833 |
it shall be treated as a path to a regular file.
|
| 8834 |
|
| 8835 |
[*Note 4*: A path stores a native format pathname
|
| 8836 |
[[fs.path.native.obs]] and acts as if it also stores a generic format
|
| 8837 |
+
pathname, related as given below. The implementation can generate the
|
| 8838 |
generic format pathname based on the native format pathname (and
|
| 8839 |
possibly other information) when requested. — *end note*]
|
| 8840 |
|
| 8841 |
When a path is constructed from or is assigned a single representation
|
| 8842 |
separate from any path, the other representation is selected by the
|
|
|
|
| 8854 |
|
| 8855 |
The *native encoding* of an ordinary character string is the operating
|
| 8856 |
system dependent current encoding for pathnames [[fs.class.path]]. The
|
| 8857 |
*native encoding* for wide character strings is the
|
| 8858 |
implementation-defined execution wide-character set encoding
|
| 8859 |
+
[[character.seq]].
|
| 8860 |
|
| 8861 |
For member function arguments that take character sequences representing
|
| 8862 |
paths and for member functions returning strings, value type and
|
| 8863 |
encoding conversion is performed if the value type of the argument or
|
| 8864 |
return value differs from `path::value_type`. For the argument or return
|
|
|
|
| 8872 |
return values is performed. For Windows-based operating systems, the
|
| 8873 |
native ordinary encoding is determined by calling a Windows API
|
| 8874 |
function. — *end note*] \[*Note 7*: This results in behavior
|
| 8875 |
identical to other C and C++ standard library functions that perform
|
| 8876 |
file operations using ordinary character strings to identify paths.
|
| 8877 |
+
Changing this behavior would be surprising and
|
| 8878 |
+
error-prone. — *end note*]
|
| 8879 |
- `wchar_t`: The encoding is the native wide encoding. The method of
|
| 8880 |
conversion is unspecified. \[*Note 8*: For Windows-based operating
|
| 8881 |
systems `path::value_type` is `wchar_t` so no conversion from
|
| 8882 |
`wchar_t` value type arguments or to `wchar_t` value type return
|
| 8883 |
values is performed. — *end note*]
|
|
|
|
| 8921 |
than `path`, and either
|
| 8922 |
|
| 8923 |
- `Source` is a specialization of `basic_string` or `basic_string_view`,
|
| 8924 |
or
|
| 8925 |
- the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
|
| 8926 |
+
valid and denotes a possibly const encoded character type
|
| 8927 |
[[temp.deduct]].
|
| 8928 |
|
| 8929 |
[*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
|
| 8930 |
above and their encodings convert to `path::value_type` and its
|
| 8931 |
encoding. — *end note*]
|
|
|
|
| 9160 |
```
|
| 9161 |
|
| 9162 |
*Effects:* Appends `path(x).native()` to the pathname in the native
|
| 9163 |
format.
|
| 9164 |
|
| 9165 |
+
[*Note 2*: This directly manipulates the value of `native()`, which is
|
| 9166 |
+
not necessarily portable between operating systems. — *end note*]
|
| 9167 |
|
| 9168 |
*Returns:* `*this`.
|
| 9169 |
|
| 9170 |
``` cpp
|
| 9171 |
path& operator+=(value_type x);
|
|
|
|
| 9314 |
operator string_type() const;
|
| 9315 |
```
|
| 9316 |
|
| 9317 |
*Returns:* `native()`.
|
| 9318 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9319 |
``` cpp
|
| 9320 |
template<class EcharT, class traits = char_traits<EcharT>,
|
| 9321 |
class Allocator = allocator<EcharT>>
|
| 9322 |
basic_string<EcharT, traits, Allocator>
|
| 9323 |
string(const Allocator& a = Allocator()) const;
|
|
|
|
| 9517 |
path("..bar").extension(); // yields ".bar" and stem() is "."
|
| 9518 |
```
|
| 9519 |
|
| 9520 |
— *end example*]
|
| 9521 |
|
| 9522 |
+
[*Note 3*: The period is included in the return value so that it is
|
| 9523 |
possible to distinguish between no extension and an empty
|
| 9524 |
extension. — *end note*]
|
| 9525 |
|
| 9526 |
+
[*Note 4*: On non-POSIX operating systems, for a path `p`, it is
|
| 9527 |
+
possible that `p.stem() + p.extension() == p.filename()` is `false`,
|
| 9528 |
+
even though the generic format pathnames are the same. — *end note*]
|
| 9529 |
|
| 9530 |
##### Query <a id="fs.path.query">[[fs.path.query]]</a>
|
| 9531 |
|
| 9532 |
``` cpp
|
| 9533 |
[[nodiscard]] bool empty() const noexcept;
|
|
|
|
| 9626 |
|
| 9627 |
``` cpp
|
| 9628 |
path lexically_relative(const path& base) const;
|
| 9629 |
```
|
| 9630 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9631 |
*Effects:* If:
|
| 9632 |
|
| 9633 |
- `root_name() != base.root_name()` is `true`, or
|
| 9634 |
- `is_absolute() != base.is_absolute()` is `true`, or
|
| 9635 |
- `!has_root_directory() && base.has_root_directory()` is `true`, or
|
| 9636 |
- any *filename* in `relative_path()` or `base.relative_path()` can be
|
| 9637 |
interpreted as a *root-name*,
|
| 9638 |
|
| 9639 |
returns `path()`.
|
| 9640 |
|
| 9641 |
+
[*Note 5*: On a POSIX implementation, no *filename* in a
|
| 9642 |
*relative-path* is acceptable as a *root-name*. — *end note*]
|
| 9643 |
|
| 9644 |
Determines the first mismatched element of `*this` and `base` as if by:
|
| 9645 |
|
| 9646 |
``` cpp
|
|
|
|
| 9658 |
- returns an object of class `path` that is default-constructed,
|
| 9659 |
followed by
|
| 9660 |
- application of `operator/=(path(".."))` `n` times, and then
|
| 9661 |
- application of `operator/=` for each element in \[`a`, `end()`).
|
| 9662 |
|
| 9663 |
+
*Returns:* `*this` made relative to `base`. Does not
|
| 9664 |
+
resolve [[fs.class.path]] symlinks. Does not first
|
| 9665 |
+
normalize [[fs.path.generic]] `*this` or `base`.
|
| 9666 |
+
|
| 9667 |
[*Example 11*:
|
| 9668 |
|
| 9669 |
``` cpp
|
| 9670 |
assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
|
| 9671 |
assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
|
|
|
|
| 9679 |
*directory-separator* characters will be backslashes rather than
|
| 9680 |
slashes, but that does not affect `path` equality.
|
| 9681 |
|
| 9682 |
— *end example*]
|
| 9683 |
|
| 9684 |
+
[*Note 6*: If symlink following semantics are desired, use the
|
| 9685 |
operational function `relative()`. — *end note*]
|
| 9686 |
|
| 9687 |
+
[*Note 7*: If normalization [[fs.path.generic]] is needed to ensure
|
| 9688 |
consistent matching of elements, apply `lexically_normal()` to `*this`,
|
| 9689 |
`base`, or both. — *end note*]
|
| 9690 |
|
| 9691 |
``` cpp
|
| 9692 |
path lexically_proximate(const path& base) const;
|
| 9693 |
```
|
| 9694 |
|
| 9695 |
*Returns:* If the value of `lexically_relative(base)` is not an empty
|
| 9696 |
path, return it. Otherwise return `*this`.
|
| 9697 |
|
| 9698 |
+
[*Note 8*: If symlink following semantics are desired, use the
|
| 9699 |
operational function `proximate()`. — *end note*]
|
| 9700 |
|
| 9701 |
+
[*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
|
| 9702 |
consistent matching of elements, apply `lexically_normal()` to `*this`,
|
| 9703 |
`base`, or both. — *end note*]
|
| 9704 |
|
| 9705 |
#### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
|
| 9706 |
|
|
|
|
| 9805 |
- Equivalence is determined by the `equivalent()` non-member function,
|
| 9806 |
which determines if two paths resolve [[fs.class.path]] to the same
|
| 9807 |
file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
|
| 9808 |
`true` when both paths resolve to the same file. — *end example*]
|
| 9809 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9810 |
— *end note*]
|
| 9811 |
|
| 9812 |
``` cpp
|
| 9813 |
friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
|
| 9814 |
```
|
|
|
|
| 9819 |
friend path operator/(const path& lhs, const path& rhs);
|
| 9820 |
```
|
| 9821 |
|
| 9822 |
*Effects:* Equivalent to: `return path(lhs) /= rhs;`
|
| 9823 |
|
| 9824 |
+
#### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
|
| 9825 |
+
|
| 9826 |
+
``` cpp
|
| 9827 |
+
template<> struct hash<filesystem::path>;
|
| 9828 |
+
```
|
| 9829 |
+
|
| 9830 |
+
For an object `p` of type `filesystem::path`,
|
| 9831 |
+
`hash<filesystem::path>()(p)` evaluates to the same result as
|
| 9832 |
+
`filesystem::hash_value(p)`.
|
| 9833 |
+
|
| 9834 |
### Class `filesystem_error` <a id="fs.class.filesystem.error">[[fs.class.filesystem.error]]</a>
|
| 9835 |
|
| 9836 |
+
#### General <a id="fs.class.filesystem.error.general">[[fs.class.filesystem.error.general]]</a>
|
| 9837 |
+
|
| 9838 |
``` cpp
|
| 9839 |
namespace std::filesystem {
|
| 9840 |
class filesystem_error : public system_error {
|
| 9841 |
public:
|
| 9842 |
filesystem_error(const string& what_arg, error_code ec);
|
|
|
|
| 9922 |
#### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
|
| 9923 |
|
| 9924 |
This enum specifies constants used to identify the format of the
|
| 9925 |
character sequence, with the meanings listed in [[fs.enum.path.format]].
|
| 9926 |
|
| 9927 |
+
**Table: Enum `path::format`** <a id="fs.enum.path.format">[fs.enum.path.format]</a>
|
| 9928 |
+
|
| 9929 |
+
| Name | Meaning |
|
| 9930 |
+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 9931 |
+
| `native_format` | The native pathname format. |
|
| 9932 |
+
| `generic_format` | The generic pathname format. |
|
| 9933 |
+
| `auto_format` | The interpretation of the format of the character sequence is implementation-defined. The implementation may inspect the content of the character sequence to determine the format. Recommended practice: For POSIX-based systems, native and generic formats are equivalent and the character sequence should always be interpreted in the same way. |
|
| 9934 |
+
|
| 9935 |
|
| 9936 |
#### Enum class `file_type` <a id="fs.enum.file.type">[[fs.enum.file.type]]</a>
|
| 9937 |
|
| 9938 |
This enum class specifies constants used to identify file types, with
|
| 9939 |
the meanings listed in [[fs.enum.file.type]]. The values of the
|
| 9940 |
constants are distinct.
|
| 9941 |
|
| 9942 |
+
**Table: Enum class `file_type`** <a id="fs.enum.file.type">[fs.enum.file.type]</a>
|
| 9943 |
+
|
| 9944 |
+
| Constant | Meaning |
|
| 9945 |
+
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 9946 |
+
| `none` | The type of the file has not been determined or an error occurred while trying to determine the type. |
|
| 9947 |
+
| `not_found` | Pseudo-type indicating the file was not found. *The file not being found is not considered an error while determining the type of a file.* |
|
| 9948 |
+
| `regular` | Regular file |
|
| 9949 |
+
| `directory` | Directory file |
|
| 9950 |
+
| `symlink` | Symbolic link file |
|
| 9951 |
+
| `block` | Block special file |
|
| 9952 |
+
| `character` | Character special file |
|
| 9953 |
+
| `fifo` | FIFO or pipe file |
|
| 9954 |
+
| `socket` | Socket file |
|
| 9955 |
+
| `implementation-defined` | Implementations that support file systems having file types in addition to the above `file_type` types shall supply implementation-defined `file_type` constants to separately identify each of those additional file types |
|
| 9956 |
+
| `unknown` | The file exists but the type cannot be determined |
|
| 9957 |
+
|
| 9958 |
|
| 9959 |
#### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
|
| 9960 |
|
| 9961 |
The `enum class` type `copy_options` is a bitmask type [[bitmask.types]]
|
| 9962 |
that specifies bitmask constants used to control the semantics of copy
|
|
|
|
| 9967 |
Every other constant in the table represents a distinct bitmask element.
|
| 9968 |
|
| 9969 |
**Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
|
| 9970 |
|
| 9971 |
| Constant | Meaning |
|
| 9972 |
+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 9973 |
| `none` | (Default) Error; file already exists. |
|
| 9974 |
| `skip_existing` | Do not overwrite existing file, do not report an error. |
|
| 9975 |
| `overwrite_existing` | Overwrite the existing file. |
|
| 9976 |
+
| `update_existing` | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for subdirectories} |
|
| 9977 |
+
| `recursive` | Recursively copy subdirectories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links} |
|
| 9978 |
| `copy_symlinks` | Copy symbolic links as symbolic links rather than copying the files that they point to. |
|
| 9979 |
| `skip_symlinks` | Ignore symbolic links. \ohdrx{2}{Option group controlling `copy` function effects for choosing the form of copying} |
|
| 9980 |
| `directories_only` | Copy directory structure only, do not copy non-directory files. |
|
| 9981 |
| `create_symlinks` | Make symbolic links instead of copies of files. The source path shall be an absolute path unless the destination path is in the current directory. |
|
| 9982 |
| `create_hard_links` | Make hard links instead of copies of files. |
|
|
|
|
| 10025 |
**Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
|
| 10026 |
|
| 10027 |
| Name | Meaning |
|
| 10028 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 10029 |
| `replace` | `permissions` shall replace the file's permission bits with `perm` |
|
| 10030 |
+
| `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{or} of `perm` and the file's current permission bits. |
|
| 10031 |
+
| `remove` | `permissions` shall replace the file's permission bits with the bitwise \logop{and} of the complement of `perm` and the file's current permission bits. |
|
| 10032 |
| `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
|
| 10033 |
|
| 10034 |
|
| 10035 |
#### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
|
| 10036 |
|
|
|
|
| 10049 |
| `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
|
| 10050 |
|
| 10051 |
|
| 10052 |
### Class `file_status` <a id="fs.class.file.status">[[fs.class.file.status]]</a>
|
| 10053 |
|
| 10054 |
+
#### General <a id="fs.class.file.status.general">[[fs.class.file.status.general]]</a>
|
| 10055 |
+
|
| 10056 |
``` cpp
|
| 10057 |
namespace std::filesystem {
|
| 10058 |
class file_status {
|
| 10059 |
public:
|
| 10060 |
// [fs.file.status.cons], constructors and destructor
|
|
|
|
| 10123 |
|
| 10124 |
*Ensures:* `permissions() == prms`.
|
| 10125 |
|
| 10126 |
### Class `directory_entry` <a id="fs.class.directory.entry">[[fs.class.directory.entry]]</a>
|
| 10127 |
|
| 10128 |
+
#### General <a id="fs.class.directory.entry.general">[[fs.class.directory.entry.general]]</a>
|
| 10129 |
+
|
| 10130 |
``` cpp
|
| 10131 |
namespace std::filesystem {
|
| 10132 |
class directory_entry {
|
| 10133 |
public:
|
| 10134 |
// [fs.dir.entry.cons], constructors and destructor
|
|
|
|
| 10184 |
file_status symlink_status(error_code& ec) const noexcept;
|
| 10185 |
|
| 10186 |
bool operator==(const directory_entry& rhs) const noexcept;
|
| 10187 |
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
|
| 10188 |
|
| 10189 |
+
// [fs.dir.entry.io], inserter
|
| 10190 |
+
template<class charT, class traits>
|
| 10191 |
+
friend basic_ostream<charT, traits>&
|
| 10192 |
+
operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
|
| 10193 |
+
|
| 10194 |
private:
|
| 10195 |
filesystem::path pathobject; // exposition only
|
| 10196 |
friend class directory_iterator; // exposition only
|
| 10197 |
};
|
| 10198 |
}
|
|
|
|
| 10295 |
|
| 10296 |
*Throws:* As specified in [[fs.err.report]].
|
| 10297 |
|
| 10298 |
[*Note 1*: Implementations of `directory_iterator`
|
| 10299 |
[[fs.class.directory.iterator]] are prohibited from directly or
|
| 10300 |
+
indirectly calling the `refresh` function as described in
|
| 10301 |
+
[[fs.class.directory.iterator.general]]. — *end note*]
|
|
|
|
| 10302 |
|
| 10303 |
#### Observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
|
| 10304 |
|
| 10305 |
Unqualified function names in the *Returns:* elements of the
|
| 10306 |
`directory_entry` observers described below refer to members of the
|
|
|
|
| 10465 |
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
|
| 10466 |
```
|
| 10467 |
|
| 10468 |
*Returns:* `pathobject <=> rhs.pathobject`.
|
| 10469 |
|
| 10470 |
+
#### Inserter <a id="fs.dir.entry.io">[[fs.dir.entry.io]]</a>
|
| 10471 |
+
|
| 10472 |
+
``` cpp
|
| 10473 |
+
template<class charT, class traits>
|
| 10474 |
+
friend basic_ostream<charT, traits>&
|
| 10475 |
+
operator<<(basic_ostream<charT, traits>& os, const directory_entry& d);
|
| 10476 |
+
```
|
| 10477 |
+
|
| 10478 |
+
*Effects:* Equivalent to: `return os << d.path();`
|
| 10479 |
+
|
| 10480 |
### Class `directory_iterator` <a id="fs.class.directory.iterator">[[fs.class.directory.iterator]]</a>
|
| 10481 |
|
| 10482 |
+
#### General <a id="fs.class.directory.iterator.general">[[fs.class.directory.iterator.general]]</a>
|
| 10483 |
+
|
| 10484 |
An object of type `directory_iterator` provides an iterator for a
|
| 10485 |
sequence of `directory_entry` elements representing the path and any
|
| 10486 |
cached attribute values [[fs.class.directory.entry]] for each file in a
|
| 10487 |
directory or in an *implementation-defined* directory-like file type.
|
| 10488 |
|
| 10489 |
+
[*Note 1*: For iteration into subdirectories, see class
|
| 10490 |
`recursive_directory_iterator` [[fs.class.rec.dir.itr]]. — *end note*]
|
| 10491 |
|
| 10492 |
``` cpp
|
| 10493 |
namespace std::filesystem {
|
| 10494 |
class directory_iterator {
|
|
|
|
| 10516 |
const directory_entry& operator*() const;
|
| 10517 |
const directory_entry* operator->() const;
|
| 10518 |
directory_iterator& operator++();
|
| 10519 |
directory_iterator& increment(error_code& ec);
|
| 10520 |
|
| 10521 |
+
bool operator==(default_sentinel_t) const noexcept {
|
| 10522 |
+
return *this == directory_iterator();
|
| 10523 |
+
}
|
| 10524 |
+
|
| 10525 |
// other members as required by [input.iterators], input iterators
|
| 10526 |
};
|
| 10527 |
}
|
| 10528 |
```
|
| 10529 |
|
|
|
|
| 10542 |
to a non-end iterator.
|
| 10543 |
|
| 10544 |
The result of calling the `path()` member of the `directory_entry`
|
| 10545 |
object obtained by dereferencing a `directory_iterator` is a reference
|
| 10546 |
to a `path` object composed of the directory argument from which the
|
| 10547 |
+
iterator was constructed with the filename of the directory entry
|
| 10548 |
+
appended as if by `operator/=`.
|
| 10549 |
|
| 10550 |
Directory iteration shall not yield directory entries for the current
|
| 10551 |
(dot) and parent (dot-dot) directories.
|
| 10552 |
|
| 10553 |
The order of directory entries obtained by dereferencing successive
|
|
|
|
| 10562 |
[*Note 2*: The exact mechanism for storing cached attribute values is
|
| 10563 |
not exposed to users. For exposition, class `directory_iterator` is
|
| 10564 |
shown in [[fs.class.directory.entry]] as a friend of class
|
| 10565 |
`directory_entry`. — *end note*]
|
| 10566 |
|
| 10567 |
+
[*Note 3*: A path obtained by dereferencing a directory iterator might
|
| 10568 |
+
not actually exist; it could be a symbolic link to a non-existent file.
|
| 10569 |
+
Recursively walking directory trees for purposes of removing and
|
| 10570 |
+
renaming entries might invalidate symbolic links that are being
|
| 10571 |
+
followed. — *end note*]
|
| 10572 |
|
| 10573 |
[*Note 4*: If a file is removed from or added to a directory after the
|
| 10574 |
construction of a `directory_iterator` for the directory, it is
|
| 10575 |
unspecified whether or not subsequently incrementing the iterator will
|
| 10576 |
ever result in an iterator referencing the removed or added directory
|
| 10577 |
+
entry. See POSIX `readdir`. — *end note*]
|
| 10578 |
|
| 10579 |
#### Members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
|
| 10580 |
|
| 10581 |
``` cpp
|
| 10582 |
directory_iterator() noexcept;
|
|
|
|
| 10650 |
```
|
| 10651 |
|
| 10652 |
*Returns:* `iter`.
|
| 10653 |
|
| 10654 |
``` cpp
|
| 10655 |
+
directory_iterator end(directory_iterator) noexcept;
|
| 10656 |
```
|
| 10657 |
|
| 10658 |
*Returns:* `directory_iterator()`.
|
| 10659 |
|
| 10660 |
### Class `recursive_directory_iterator` <a id="fs.class.rec.dir.itr">[[fs.class.rec.dir.itr]]</a>
|
| 10661 |
|
| 10662 |
+
#### General <a id="fs.class.rec.dir.itr.general">[[fs.class.rec.dir.itr.general]]</a>
|
| 10663 |
+
|
| 10664 |
An object of type `recursive_directory_iterator` provides an iterator
|
| 10665 |
for a sequence of `directory_entry` elements representing the files in a
|
| 10666 |
directory or in an *implementation-defined* directory-like file type,
|
| 10667 |
+
and its subdirectories.
|
| 10668 |
|
| 10669 |
``` cpp
|
| 10670 |
namespace std::filesystem {
|
| 10671 |
class recursive_directory_iterator {
|
| 10672 |
public:
|
|
|
|
| 10706 |
|
| 10707 |
void pop();
|
| 10708 |
void pop(error_code& ec);
|
| 10709 |
void disable_recursion_pending();
|
| 10710 |
|
| 10711 |
+
bool operator==(default_sentinel_t) const noexcept {
|
| 10712 |
+
return *this == recursive_directory_iterator();
|
| 10713 |
+
}
|
| 10714 |
+
|
| 10715 |
// other members as required by [input.iterators], input iterators
|
| 10716 |
};
|
| 10717 |
}
|
| 10718 |
```
|
| 10719 |
|
|
|
|
| 10723 |
|
| 10724 |
The behavior of a `recursive_directory_iterator` is the same as a
|
| 10725 |
`directory_iterator` unless otherwise specified.
|
| 10726 |
|
| 10727 |
[*Note 1*: If the directory structure being iterated over contains
|
| 10728 |
+
cycles then it is possible that the end iterator is
|
| 10729 |
+
unreachable. — *end note*]
|
| 10730 |
|
| 10731 |
#### Members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
|
| 10732 |
|
| 10733 |
``` cpp
|
| 10734 |
recursive_directory_iterator() noexcept;
|
|
|
|
| 10759 |
`directory_options` argument, otherwise
|
| 10760 |
`options() == directory_options::none`.
|
| 10761 |
|
| 10762 |
*Throws:* As specified in [[fs.err.report]].
|
| 10763 |
|
| 10764 |
+
[*Note 1*: Use `recursive_directory_iterator(".")` rather than
|
| 10765 |
+
`recursive_directory_iterator("")` to iterate over the current
|
| 10766 |
+
directory. — *end note*]
|
| 10767 |
|
| 10768 |
[*Note 2*: By default, `recursive_directory_iterator` does not follow
|
| 10769 |
directory symlinks. To follow directory symlinks, specify `options` as
|
| 10770 |
`directory_options::follow_directory_symlink`. — *end note*]
|
| 10771 |
|
|
|
|
| 10902 |
recursion into a directory. — *end note*]
|
| 10903 |
|
| 10904 |
#### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
|
| 10905 |
|
| 10906 |
These functions enable use of `recursive_directory_iterator` with
|
| 10907 |
+
range-based `for` statements.
|
| 10908 |
|
| 10909 |
``` cpp
|
| 10910 |
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 10911 |
```
|
| 10912 |
|
| 10913 |
*Returns:* `iter`.
|
| 10914 |
|
| 10915 |
``` cpp
|
| 10916 |
+
recursive_directory_iterator end(recursive_directory_iterator) noexcept;
|
| 10917 |
```
|
| 10918 |
|
| 10919 |
*Returns:* `recursive_directory_iterator()`.
|
| 10920 |
|
| 10921 |
### Filesystem operation functions <a id="fs.op.funcs">[[fs.op.funcs]]</a>
|
| 10922 |
|
| 10923 |
+
#### General <a id="fs.op.funcs.general">[[fs.op.funcs.general]]</a>
|
| 10924 |
+
|
| 10925 |
Filesystem operation functions query or modify files, including
|
| 10926 |
directories, in external storage.
|
| 10927 |
|
| 10928 |
[*Note 1*: Because hardware failures, network failures, file system
|
| 10929 |
races [[fs.race.behavior]], and many other kinds of errors occur
|
| 10930 |
+
frequently in file system operations, any filesystem operation function,
|
| 10931 |
+
no matter how apparently innocuous, can encounter an error; see
|
| 10932 |
+
[[fs.err.report]]. — *end note*]
|
| 10933 |
|
| 10934 |
#### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
|
| 10935 |
|
| 10936 |
``` cpp
|
| 10937 |
+
path filesystem::absolute(const path& p);
|
| 10938 |
+
path filesystem::absolute(const path& p, error_code& ec);
|
| 10939 |
```
|
| 10940 |
|
| 10941 |
*Effects:* Composes an absolute path referencing the same file system
|
| 10942 |
location as `p` according to the operating system [[fs.conform.os]].
|
| 10943 |
|
|
|
|
| 10947 |
[*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
|
| 10948 |
unless an error occurs. — *end note*]
|
| 10949 |
|
| 10950 |
*Throws:* As specified in [[fs.err.report]].
|
| 10951 |
|
| 10952 |
+
[*Note 2*: To resolve symlinks or perform other sanitization that can
|
| 10953 |
+
involve queries to secondary storage, such as hard disks, consider
|
| 10954 |
`canonical` [[fs.op.canonical]]. — *end note*]
|
| 10955 |
|
| 10956 |
[*Note 3*: Implementations are strongly encouraged to not query
|
| 10957 |
secondary storage, and not consider `!exists(p)` an
|
| 10958 |
error. — *end note*]
|
|
|
|
| 10963 |
`GetFullPathNameW`. — *end example*]
|
| 10964 |
|
| 10965 |
#### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
|
| 10966 |
|
| 10967 |
``` cpp
|
| 10968 |
+
path filesystem::canonical(const path& p);
|
| 10969 |
+
path filesystem::canonical(const path& p, error_code& ec);
|
| 10970 |
```
|
| 10971 |
|
| 10972 |
*Effects:* Converts `p` to an absolute path that has no symbolic link,
|
| 10973 |
dot, or dot-dot elements in its pathname in the generic format.
|
| 10974 |
|
|
|
|
| 10981 |
*Remarks:* `!exists(p)` is an error.
|
| 10982 |
|
| 10983 |
#### Copy <a id="fs.op.copy">[[fs.op.copy]]</a>
|
| 10984 |
|
| 10985 |
``` cpp
|
| 10986 |
+
void filesystem::copy(const path& from, const path& to);
|
| 10987 |
```
|
| 10988 |
|
| 10989 |
*Effects:* Equivalent to `copy(from, to, copy_options::none)`.
|
| 10990 |
|
| 10991 |
``` cpp
|
| 10992 |
+
void filesystem::copy(const path& from, const path& to, error_code& ec);
|
| 10993 |
```
|
| 10994 |
|
| 10995 |
*Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
|
| 10996 |
|
| 10997 |
``` cpp
|
| 10998 |
+
void filesystem::copy(const path& from, const path& to, copy_options options);
|
| 10999 |
+
void filesystem::copy(const path& from, const path& to, copy_options options,
|
| 11000 |
error_code& ec);
|
| 11001 |
```
|
| 11002 |
|
| 11003 |
*Preconditions:* At most one element from each option
|
| 11004 |
group [[fs.enum.copy.opts]] is set in `options`.
|
|
|
|
| 11135 |
— *end example*]
|
| 11136 |
|
| 11137 |
#### Copy file <a id="fs.op.copy.file">[[fs.op.copy.file]]</a>
|
| 11138 |
|
| 11139 |
``` cpp
|
| 11140 |
+
bool filesystem::copy_file(const path& from, const path& to);
|
| 11141 |
+
bool filesystem::copy_file(const path& from, const path& to, error_code& ec);
|
| 11142 |
```
|
| 11143 |
|
| 11144 |
*Returns:* `copy_file(from, to, copy_options::none)` or
|
| 11145 |
`copy_file(from, to, copy_options::none, ec)`, respectively.
|
| 11146 |
|
| 11147 |
*Throws:* As specified in [[fs.err.report]].
|
| 11148 |
|
| 11149 |
``` cpp
|
| 11150 |
+
bool filesystem::copy_file(const path& from, const path& to, copy_options options);
|
| 11151 |
+
bool filesystem::copy_file(const path& from, const path& to, copy_options options,
|
| 11152 |
error_code& ec);
|
| 11153 |
```
|
| 11154 |
|
| 11155 |
*Preconditions:* At most one element from each option
|
| 11156 |
group [[fs.enum.copy.opts]] is set in `options`.
|
|
|
|
| 11185 |
*Complexity:* At most one direct or indirect invocation of `status(to)`.
|
| 11186 |
|
| 11187 |
#### Copy symlink <a id="fs.op.copy.symlink">[[fs.op.copy.symlink]]</a>
|
| 11188 |
|
| 11189 |
``` cpp
|
| 11190 |
+
void filesystem::copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 11191 |
+
void filesystem::copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 11192 |
error_code& ec) noexcept;
|
| 11193 |
```
|
| 11194 |
|
| 11195 |
*Effects:* Equivalent to
|
| 11196 |
*`function`*`(read_symlink(existing_symlink), new_symlink)` or
|
|
|
|
| 11201 |
*Throws:* As specified in [[fs.err.report]].
|
| 11202 |
|
| 11203 |
#### Create directories <a id="fs.op.create.directories">[[fs.op.create.directories]]</a>
|
| 11204 |
|
| 11205 |
``` cpp
|
| 11206 |
+
bool filesystem::create_directories(const path& p);
|
| 11207 |
+
bool filesystem::create_directories(const path& p, error_code& ec);
|
| 11208 |
```
|
| 11209 |
|
| 11210 |
*Effects:* Calls `create_directory()` for each element of `p` that does
|
| 11211 |
not exist.
|
| 11212 |
|
|
|
|
| 11218 |
*Complexity:* 𝑂(n) where *n* is the number of elements of `p`.
|
| 11219 |
|
| 11220 |
#### Create directory <a id="fs.op.create.directory">[[fs.op.create.directory]]</a>
|
| 11221 |
|
| 11222 |
``` cpp
|
| 11223 |
+
bool filesystem::create_directory(const path& p);
|
| 11224 |
+
bool filesystem::create_directory(const path& p, error_code& ec) noexcept;
|
| 11225 |
```
|
| 11226 |
|
| 11227 |
*Effects:* Creates the directory `p` resolves to, as if by POSIX `mkdir`
|
| 11228 |
with a second argument of `static_cast<int>(perms::all)`. If `mkdir`
|
| 11229 |
fails because `p` resolves to an existing directory, no error is
|
|
|
|
| 11232 |
*Returns:* `true` if a new directory was created, otherwise `false`.
|
| 11233 |
|
| 11234 |
*Throws:* As specified in [[fs.err.report]].
|
| 11235 |
|
| 11236 |
``` cpp
|
| 11237 |
+
bool filesystem::create_directory(const path& p, const path& existing_p);
|
| 11238 |
+
bool filesystem::create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
|
| 11239 |
```
|
| 11240 |
|
| 11241 |
*Effects:* Creates the directory `p` resolves to, with attributes copied
|
| 11242 |
from directory `existing_p`. The set of attributes copied is operating
|
| 11243 |
system dependent. If `mkdir` fails because `p` resolves to an existing
|
|
|
|
| 11257 |
*Throws:* As specified in [[fs.err.report]].
|
| 11258 |
|
| 11259 |
#### Create directory symlink <a id="fs.op.create.dir.symlk">[[fs.op.create.dir.symlk]]</a>
|
| 11260 |
|
| 11261 |
``` cpp
|
| 11262 |
+
void filesystem::create_directory_symlink(const path& to, const path& new_symlink);
|
| 11263 |
+
void filesystem::create_directory_symlink(const path& to, const path& new_symlink,
|
| 11264 |
error_code& ec) noexcept;
|
| 11265 |
```
|
| 11266 |
|
| 11267 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 11268 |
|
|
|
|
| 11270 |
an unspecified representation of `to`.
|
| 11271 |
|
| 11272 |
*Throws:* As specified in [[fs.err.report]].
|
| 11273 |
|
| 11274 |
[*Note 1*: Some operating systems require symlink creation to identify
|
| 11275 |
+
that the link is to a directory. Thus, `create_symlink()` (instead of
|
| 11276 |
+
`create_directory_symlink()`) cannot be used reliably to create
|
| 11277 |
+
directory symlinks. — *end note*]
|
| 11278 |
|
| 11279 |
[*Note 2*: Some operating systems do not support symbolic links at all
|
| 11280 |
or support them only for regular files. Some file systems (such as the
|
| 11281 |
FAT file system) do not support symbolic links regardless of the
|
| 11282 |
operating system. — *end note*]
|
| 11283 |
|
| 11284 |
#### Create hard link <a id="fs.op.create.hard.lk">[[fs.op.create.hard.lk]]</a>
|
| 11285 |
|
| 11286 |
``` cpp
|
| 11287 |
+
void filesystem::create_hard_link(const path& to, const path& new_hard_link);
|
| 11288 |
+
void filesystem::create_hard_link(const path& to, const path& new_hard_link,
|
| 11289 |
error_code& ec) noexcept;
|
| 11290 |
```
|
| 11291 |
|
| 11292 |
*Effects:* Establishes the postcondition, as if by POSIX `link()`.
|
| 11293 |
|
|
|
|
| 11305 |
file. — *end note*]
|
| 11306 |
|
| 11307 |
#### Create symlink <a id="fs.op.create.symlink">[[fs.op.create.symlink]]</a>
|
| 11308 |
|
| 11309 |
``` cpp
|
| 11310 |
+
void filesystem::create_symlink(const path& to, const path& new_symlink);
|
| 11311 |
+
void filesystem::create_symlink(const path& to, const path& new_symlink,
|
| 11312 |
error_code& ec) noexcept;
|
| 11313 |
```
|
| 11314 |
|
| 11315 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 11316 |
|
|
|
|
| 11325 |
operating system. — *end note*]
|
| 11326 |
|
| 11327 |
#### Current path <a id="fs.op.current.path">[[fs.op.current.path]]</a>
|
| 11328 |
|
| 11329 |
``` cpp
|
| 11330 |
+
path filesystem::current_path();
|
| 11331 |
+
path filesystem::current_path(error_code& ec);
|
| 11332 |
```
|
| 11333 |
|
| 11334 |
*Returns:* The absolute path of the current working directory, whose
|
| 11335 |
pathname in the native format is obtained as if by POSIX `getcwd()`. The
|
| 11336 |
signature with argument `ec` returns `path()` if an error occurs.
|
|
|
|
| 11344 |
[*Note 1*: The `current_path()` name was chosen to emphasize that the
|
| 11345 |
returned value is a path, not just a single directory
|
| 11346 |
name. — *end note*]
|
| 11347 |
|
| 11348 |
[*Note 2*: The current path as returned by many operating systems is a
|
| 11349 |
+
dangerous global variable and can be changed unexpectedly by third-party
|
| 11350 |
or system library functions, or by another thread. — *end note*]
|
| 11351 |
|
| 11352 |
``` cpp
|
| 11353 |
+
void filesystem::current_path(const path& p);
|
| 11354 |
+
void filesystem::current_path(const path& p, error_code& ec) noexcept;
|
| 11355 |
```
|
| 11356 |
|
| 11357 |
*Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
|
| 11358 |
|
| 11359 |
*Ensures:* `equivalent(p, current_path())`.
|
| 11360 |
|
| 11361 |
*Throws:* As specified in [[fs.err.report]].
|
| 11362 |
|
| 11363 |
[*Note 3*: The current path for many operating systems is a dangerous
|
| 11364 |
+
global state and can be changed unexpectedly by third-party or system
|
| 11365 |
library functions, or by another thread. — *end note*]
|
| 11366 |
|
| 11367 |
#### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
|
| 11368 |
|
| 11369 |
``` cpp
|
| 11370 |
+
bool filesystem::equivalent(const path& p1, const path& p2);
|
| 11371 |
+
bool filesystem::equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 11372 |
```
|
| 11373 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11374 |
Two paths are considered to resolve to the same file system entity if
|
| 11375 |
two candidate entities reside on the same device at the same location.
|
| 11376 |
|
| 11377 |
[*Note 1*: On POSIX platforms, this is determined as if by the values
|
| 11378 |
of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
|
| 11379 |
having equal `st_dev` values and equal `st_ino` values. — *end note*]
|
| 11380 |
|
| 11381 |
+
*Returns:* `true`, if `p1` and `p2` resolve to the same file system
|
| 11382 |
+
entity, otherwise `false`. The signature with argument `ec` returns
|
| 11383 |
+
`false` if an error occurs.
|
| 11384 |
+
|
| 11385 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 11386 |
+
|
| 11387 |
*Remarks:* `!exists(p1) || !exists(p2)` is an error.
|
| 11388 |
|
|
|
|
|
|
|
| 11389 |
#### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
|
| 11390 |
|
| 11391 |
``` cpp
|
| 11392 |
+
bool filesystem::exists(file_status s) noexcept;
|
| 11393 |
```
|
| 11394 |
|
| 11395 |
*Returns:* `status_known(s) && s.type() != file_type::not_found`.
|
| 11396 |
|
| 11397 |
``` cpp
|
| 11398 |
+
bool filesystem::exists(const path& p);
|
| 11399 |
+
bool filesystem::exists(const path& p, error_code& ec) noexcept;
|
| 11400 |
```
|
| 11401 |
|
| 11402 |
Let `s` be a `file_status`, determined as if by `status(p)` or
|
| 11403 |
`status(p, ec)`, respectively.
|
| 11404 |
|
|
|
|
| 11410 |
*Throws:* As specified in [[fs.err.report]].
|
| 11411 |
|
| 11412 |
#### File size <a id="fs.op.file.size">[[fs.op.file.size]]</a>
|
| 11413 |
|
| 11414 |
``` cpp
|
| 11415 |
+
uintmax_t filesystem::file_size(const path& p);
|
| 11416 |
+
uintmax_t filesystem::file_size(const path& p, error_code& ec) noexcept;
|
| 11417 |
```
|
| 11418 |
|
| 11419 |
*Effects:* If `exists(p)` is `false`, an error is
|
| 11420 |
reported [[fs.err.report]].
|
| 11421 |
|
|
|
|
| 11432 |
*Throws:* As specified in [[fs.err.report]].
|
| 11433 |
|
| 11434 |
#### Hard link count <a id="fs.op.hard.lk.ct">[[fs.op.hard.lk.ct]]</a>
|
| 11435 |
|
| 11436 |
``` cpp
|
| 11437 |
+
uintmax_t filesystem::hard_link_count(const path& p);
|
| 11438 |
+
uintmax_t filesystem::hard_link_count(const path& p, error_code& ec) noexcept;
|
| 11439 |
```
|
| 11440 |
|
| 11441 |
*Returns:* The number of hard links for `p`. The signature with argument
|
| 11442 |
`ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
|
| 11443 |
|
| 11444 |
*Throws:* As specified in [[fs.err.report]].
|
| 11445 |
|
| 11446 |
#### Is block file <a id="fs.op.is.block.file">[[fs.op.is.block.file]]</a>
|
| 11447 |
|
| 11448 |
``` cpp
|
| 11449 |
+
bool filesystem::is_block_file(file_status s) noexcept;
|
| 11450 |
```
|
| 11451 |
|
| 11452 |
*Returns:* `s.type() == file_type::block`.
|
| 11453 |
|
| 11454 |
``` cpp
|
| 11455 |
+
bool filesystem::is_block_file(const path& p);
|
| 11456 |
+
bool filesystem::is_block_file(const path& p, error_code& ec) noexcept;
|
| 11457 |
```
|
| 11458 |
|
| 11459 |
*Returns:* `is_block_file(status(p))` or `is_block_file(status(p, ec))`,
|
| 11460 |
respectively. The signature with argument `ec` returns `false` if an
|
| 11461 |
error occurs.
|
|
|
|
| 11463 |
*Throws:* As specified in [[fs.err.report]].
|
| 11464 |
|
| 11465 |
#### Is character file <a id="fs.op.is.char.file">[[fs.op.is.char.file]]</a>
|
| 11466 |
|
| 11467 |
``` cpp
|
| 11468 |
+
bool filesystem::is_character_file(file_status s) noexcept;
|
| 11469 |
```
|
| 11470 |
|
| 11471 |
*Returns:* `s.type() == file_type::character`.
|
| 11472 |
|
| 11473 |
``` cpp
|
| 11474 |
+
bool filesystem::is_character_file(const path& p);
|
| 11475 |
+
bool filesystem::is_character_file(const path& p, error_code& ec) noexcept;
|
| 11476 |
```
|
| 11477 |
|
| 11478 |
*Returns:* `is_character_file(status(p))` or
|
| 11479 |
`is_character_file(status(p, ec))`, respectively.
|
| 11480 |
The signature with argument `ec` returns `false` if an error occurs.
|
|
|
|
| 11482 |
*Throws:* As specified in [[fs.err.report]].
|
| 11483 |
|
| 11484 |
#### Is directory <a id="fs.op.is.directory">[[fs.op.is.directory]]</a>
|
| 11485 |
|
| 11486 |
``` cpp
|
| 11487 |
+
bool filesystem::is_directory(file_status s) noexcept;
|
| 11488 |
```
|
| 11489 |
|
| 11490 |
*Returns:* `s.type() == file_type::directory`.
|
| 11491 |
|
| 11492 |
``` cpp
|
| 11493 |
+
bool filesystem::is_directory(const path& p);
|
| 11494 |
+
bool filesystem::is_directory(const path& p, error_code& ec) noexcept;
|
| 11495 |
```
|
| 11496 |
|
| 11497 |
*Returns:* `is_directory(status(p))` or `is_directory(status(p, ec))`,
|
| 11498 |
respectively. The signature with argument `ec` returns `false` if an
|
| 11499 |
error occurs.
|
|
|
|
| 11501 |
*Throws:* As specified in [[fs.err.report]].
|
| 11502 |
|
| 11503 |
#### Is empty <a id="fs.op.is.empty">[[fs.op.is.empty]]</a>
|
| 11504 |
|
| 11505 |
``` cpp
|
| 11506 |
+
bool filesystem::is_empty(const path& p);
|
| 11507 |
+
bool filesystem::is_empty(const path& p, error_code& ec);
|
| 11508 |
```
|
| 11509 |
|
| 11510 |
*Effects:*
|
| 11511 |
|
| 11512 |
- Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
|
|
|
|
| 11529 |
*Throws:* As specified in [[fs.err.report]].
|
| 11530 |
|
| 11531 |
#### Is fifo <a id="fs.op.is.fifo">[[fs.op.is.fifo]]</a>
|
| 11532 |
|
| 11533 |
``` cpp
|
| 11534 |
+
bool filesystem::is_fifo(file_status s) noexcept;
|
| 11535 |
```
|
| 11536 |
|
| 11537 |
*Returns:* `s.type() == file_type::fifo`.
|
| 11538 |
|
| 11539 |
``` cpp
|
| 11540 |
+
bool filesystem::is_fifo(const path& p);
|
| 11541 |
+
bool filesystem::is_fifo(const path& p, error_code& ec) noexcept;
|
| 11542 |
```
|
| 11543 |
|
| 11544 |
*Returns:* `is_fifo(status(p))` or `is_fifo(status(p, ec))`,
|
| 11545 |
respectively. The signature with argument `ec` returns `false` if an
|
| 11546 |
error occurs.
|
|
|
|
| 11548 |
*Throws:* As specified in [[fs.err.report]].
|
| 11549 |
|
| 11550 |
#### Is other <a id="fs.op.is.other">[[fs.op.is.other]]</a>
|
| 11551 |
|
| 11552 |
``` cpp
|
| 11553 |
+
bool filesystem::is_other(file_status s) noexcept;
|
| 11554 |
```
|
| 11555 |
|
| 11556 |
*Returns:*
|
| 11557 |
`exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)`.
|
| 11558 |
|
| 11559 |
``` cpp
|
| 11560 |
+
bool filesystem::is_other(const path& p);
|
| 11561 |
+
bool filesystem::is_other(const path& p, error_code& ec) noexcept;
|
| 11562 |
```
|
| 11563 |
|
| 11564 |
*Returns:* `is_other(status(p))` or `is_other(status(p, ec))`,
|
| 11565 |
respectively. The signature with argument `ec` returns `false` if an
|
| 11566 |
error occurs.
|
|
|
|
| 11568 |
*Throws:* As specified in [[fs.err.report]].
|
| 11569 |
|
| 11570 |
#### Is regular file <a id="fs.op.is.regular.file">[[fs.op.is.regular.file]]</a>
|
| 11571 |
|
| 11572 |
``` cpp
|
| 11573 |
+
bool filesystem::is_regular_file(file_status s) noexcept;
|
| 11574 |
```
|
| 11575 |
|
| 11576 |
*Returns:* `s.type() == file_type::regular`.
|
| 11577 |
|
| 11578 |
``` cpp
|
| 11579 |
+
bool filesystem::is_regular_file(const path& p);
|
| 11580 |
```
|
| 11581 |
|
| 11582 |
*Returns:* `is_regular_file(status(p))`.
|
| 11583 |
|
| 11584 |
*Throws:* `filesystem_error` if `status(p)` would throw
|
| 11585 |
`filesystem_error`.
|
| 11586 |
|
| 11587 |
``` cpp
|
| 11588 |
+
bool filesystem::is_regular_file(const path& p, error_code& ec) noexcept;
|
| 11589 |
```
|
| 11590 |
|
| 11591 |
*Effects:* Sets `ec` as if by `status(p, ec)`.
|
| 11592 |
|
| 11593 |
[*Note 1*: `file_type::none`, `file_type::not_found` and
|
|
|
|
| 11598 |
occurs.
|
| 11599 |
|
| 11600 |
#### Is socket <a id="fs.op.is.socket">[[fs.op.is.socket]]</a>
|
| 11601 |
|
| 11602 |
``` cpp
|
| 11603 |
+
bool filesystem::is_socket(file_status s) noexcept;
|
| 11604 |
```
|
| 11605 |
|
| 11606 |
*Returns:* `s.type() == file_type::socket`.
|
| 11607 |
|
| 11608 |
``` cpp
|
| 11609 |
+
bool filesystem::is_socket(const path& p);
|
| 11610 |
+
bool filesystem::is_socket(const path& p, error_code& ec) noexcept;
|
| 11611 |
```
|
| 11612 |
|
| 11613 |
*Returns:* `is_socket(status(p))` or `is_socket(status(p, ec))`,
|
| 11614 |
respectively. The signature with argument `ec` returns `false` if an
|
| 11615 |
error occurs.
|
|
|
|
| 11617 |
*Throws:* As specified in [[fs.err.report]].
|
| 11618 |
|
| 11619 |
#### Is symlink <a id="fs.op.is.symlink">[[fs.op.is.symlink]]</a>
|
| 11620 |
|
| 11621 |
``` cpp
|
| 11622 |
+
bool filesystem::is_symlink(file_status s) noexcept;
|
| 11623 |
```
|
| 11624 |
|
| 11625 |
*Returns:* `s.type() == file_type::symlink`.
|
| 11626 |
|
| 11627 |
``` cpp
|
| 11628 |
+
bool filesystem::is_symlink(const path& p);
|
| 11629 |
+
bool filesystem::is_symlink(const path& p, error_code& ec) noexcept;
|
| 11630 |
```
|
| 11631 |
|
| 11632 |
*Returns:* `is_symlink(symlink_status(p))` or
|
| 11633 |
`is_symlink(symlink_status(p, ec))`, respectively. The signature with
|
| 11634 |
argument `ec` returns `false` if an error occurs.
|
|
|
|
| 11636 |
*Throws:* As specified in [[fs.err.report]].
|
| 11637 |
|
| 11638 |
#### Last write time <a id="fs.op.last.write.time">[[fs.op.last.write.time]]</a>
|
| 11639 |
|
| 11640 |
``` cpp
|
| 11641 |
+
file_time_type filesystem::last_write_time(const path& p);
|
| 11642 |
+
file_time_type filesystem::last_write_time(const path& p, error_code& ec) noexcept;
|
| 11643 |
```
|
| 11644 |
|
| 11645 |
*Returns:* The time of last data modification of `p`, determined as if
|
| 11646 |
by the value of the POSIX `stat` class member `st_mtime` obtained as if
|
| 11647 |
by POSIX `stat()`. The signature with argument `ec` returns
|
| 11648 |
`file_time_type::min()` if an error occurs.
|
| 11649 |
|
| 11650 |
*Throws:* As specified in [[fs.err.report]].
|
| 11651 |
|
| 11652 |
``` cpp
|
| 11653 |
+
void filesystem::last_write_time(const path& p, file_time_type new_time);
|
| 11654 |
+
void filesystem::last_write_time(const path& p, file_time_type new_time,
|
| 11655 |
error_code& ec) noexcept;
|
| 11656 |
```
|
| 11657 |
|
| 11658 |
*Effects:* Sets the time of last data modification of the file resolved
|
| 11659 |
to by `p` to `new_time`, as if by POSIX `futimens()`.
|
| 11660 |
|
| 11661 |
*Throws:* As specified in [[fs.err.report]].
|
| 11662 |
|
| 11663 |
[*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
|
| 11664 |
+
specified because it does not necessarily hold for file systems with
|
| 11665 |
+
coarse time granularity. — *end note*]
|
| 11666 |
|
| 11667 |
#### Permissions <a id="fs.op.permissions">[[fs.op.permissions]]</a>
|
| 11668 |
|
| 11669 |
``` cpp
|
| 11670 |
+
void filesystem::permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
|
| 11671 |
+
void filesystem::permissions(const path& p, perms prms, error_code& ec) noexcept;
|
| 11672 |
+
void filesystem::permissions(const path& p, perms prms, perm_options opts, error_code& ec);
|
| 11673 |
```
|
| 11674 |
|
| 11675 |
*Preconditions:* Exactly one of the `perm_options` constants `replace`,
|
| 11676 |
`add`, or `remove` is present in `opts`.
|
| 11677 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11678 |
*Effects:* Applies the action specified by `opts` to the file `p`
|
| 11679 |
resolves to, or to file `p` itself if `p` is a symbolic link and
|
| 11680 |
`perm_options::nofollow` is set in `opts`. The action is applied as if
|
| 11681 |
by POSIX `fchmodat()`.
|
| 11682 |
|
| 11683 |
[*Note 1*: Conceptually permissions are viewed as bits, but the actual
|
| 11684 |
+
implementation can use some other mechanism. — *end note*]
|
| 11685 |
|
| 11686 |
*Throws:* As specified in [[fs.err.report]].
|
| 11687 |
|
| 11688 |
+
*Remarks:* The second signature behaves as if it had an additional
|
| 11689 |
+
parameter `perm_options` `opts` with an argument of
|
| 11690 |
+
`perm_options::replace`.
|
| 11691 |
+
|
| 11692 |
#### Proximate <a id="fs.op.proximate">[[fs.op.proximate]]</a>
|
| 11693 |
|
| 11694 |
``` cpp
|
| 11695 |
+
path filesystem::proximate(const path& p, error_code& ec);
|
| 11696 |
```
|
| 11697 |
|
| 11698 |
*Returns:* `proximate(p, current_path(), ec)`.
|
| 11699 |
|
| 11700 |
*Throws:* As specified in [[fs.err.report]].
|
| 11701 |
|
| 11702 |
``` cpp
|
| 11703 |
+
path filesystem::proximate(const path& p, const path& base = current_path());
|
| 11704 |
+
path filesystem::proximate(const path& p, const path& base, error_code& ec);
|
| 11705 |
```
|
| 11706 |
|
| 11707 |
*Returns:* For the first form:
|
| 11708 |
|
| 11709 |
``` cpp
|
|
|
|
| 11721 |
*Throws:* As specified in [[fs.err.report]].
|
| 11722 |
|
| 11723 |
#### Read symlink <a id="fs.op.read.symlink">[[fs.op.read.symlink]]</a>
|
| 11724 |
|
| 11725 |
``` cpp
|
| 11726 |
+
path filesystem::read_symlink(const path& p);
|
| 11727 |
+
path filesystem::read_symlink(const path& p, error_code& ec);
|
| 11728 |
```
|
| 11729 |
|
| 11730 |
*Returns:* If `p` resolves to a symbolic link, a `path` object
|
| 11731 |
containing the contents of that symbolic link. The signature with
|
| 11732 |
argument `ec` returns `path()` if an error occurs.
|
|
|
|
| 11737 |
link. — *end note*]
|
| 11738 |
|
| 11739 |
#### Relative <a id="fs.op.relative">[[fs.op.relative]]</a>
|
| 11740 |
|
| 11741 |
``` cpp
|
| 11742 |
+
path filesystem::relative(const path& p, error_code& ec);
|
| 11743 |
```
|
| 11744 |
|
| 11745 |
*Returns:* `relative(p, current_path(), ec)`.
|
| 11746 |
|
| 11747 |
*Throws:* As specified in [[fs.err.report]].
|
| 11748 |
|
| 11749 |
``` cpp
|
| 11750 |
+
path filesystem::relative(const path& p, const path& base = current_path());
|
| 11751 |
+
path filesystem::relative(const path& p, const path& base, error_code& ec);
|
| 11752 |
```
|
| 11753 |
|
| 11754 |
*Returns:* For the first form:
|
| 11755 |
|
| 11756 |
``` cpp
|
|
|
|
| 11768 |
*Throws:* As specified in [[fs.err.report]].
|
| 11769 |
|
| 11770 |
#### Remove <a id="fs.op.remove">[[fs.op.remove]]</a>
|
| 11771 |
|
| 11772 |
``` cpp
|
| 11773 |
+
bool filesystem::remove(const path& p);
|
| 11774 |
+
bool filesystem::remove(const path& p, error_code& ec) noexcept;
|
| 11775 |
```
|
| 11776 |
|
| 11777 |
*Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
|
| 11778 |
as if by POSIX `remove()`.
|
| 11779 |
|
|
|
|
| 11788 |
*Throws:* As specified in [[fs.err.report]].
|
| 11789 |
|
| 11790 |
#### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
|
| 11791 |
|
| 11792 |
``` cpp
|
| 11793 |
+
uintmax_t filesystem::remove_all(const path& p);
|
| 11794 |
+
uintmax_t filesystem::remove_all(const path& p, error_code& ec);
|
| 11795 |
```
|
| 11796 |
|
| 11797 |
*Effects:* Recursively deletes the contents of `p` if it exists, then
|
| 11798 |
deletes file `p` itself, as if by POSIX `remove()`.
|
| 11799 |
|
|
|
|
| 11808 |
*Throws:* As specified in [[fs.err.report]].
|
| 11809 |
|
| 11810 |
#### Rename <a id="fs.op.rename">[[fs.op.rename]]</a>
|
| 11811 |
|
| 11812 |
``` cpp
|
| 11813 |
+
void filesystem::rename(const path& old_p, const path& new_p);
|
| 11814 |
+
void filesystem::rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
|
| 11815 |
```
|
| 11816 |
|
| 11817 |
*Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
|
| 11818 |
|
| 11819 |
[*Note 1*:
|
| 11820 |
|
| 11821 |
- If `old_p` and `new_p` resolve to the same existing file, no action is
|
| 11822 |
taken.
|
| 11823 |
+
- Otherwise, the rename can include the following effects:
|
| 11824 |
- if `new_p` resolves to an existing non-directory file, `new_p` is
|
| 11825 |
removed; otherwise,
|
| 11826 |
- if `new_p` resolves to an existing directory, `new_p` is removed if
|
| 11827 |
+
empty on POSIX compliant operating systems but might be an error on
|
| 11828 |
other operating systems.
|
| 11829 |
|
| 11830 |
A symbolic link is itself renamed, rather than the file it resolves to.
|
| 11831 |
|
| 11832 |
— *end note*]
|
|
|
|
| 11834 |
*Throws:* As specified in [[fs.err.report]].
|
| 11835 |
|
| 11836 |
#### Resize file <a id="fs.op.resize.file">[[fs.op.resize.file]]</a>
|
| 11837 |
|
| 11838 |
``` cpp
|
| 11839 |
+
void filesystem::resize_file(const path& p, uintmax_t new_size);
|
| 11840 |
+
void filesystem::resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
|
| 11841 |
```
|
| 11842 |
|
| 11843 |
*Effects:* Causes the size that would be returned by `file_size(p)` to
|
| 11844 |
be equal to `new_size`, as if by POSIX `truncate()`.
|
| 11845 |
|
| 11846 |
*Throws:* As specified in [[fs.err.report]].
|
| 11847 |
|
| 11848 |
#### Space <a id="fs.op.space">[[fs.op.space]]</a>
|
| 11849 |
|
| 11850 |
``` cpp
|
| 11851 |
+
space_info filesystem::space(const path& p);
|
| 11852 |
+
space_info filesystem::space(const path& p, error_code& ec) noexcept;
|
| 11853 |
```
|
| 11854 |
|
| 11855 |
*Returns:* An object of type `space_info`. The value of the `space_info`
|
| 11856 |
object is determined as if by using POSIX `statvfs` to obtain a POSIX
|
| 11857 |
`struct statvfs`, and then multiplying its `f_blocks`, `f_bfree`, and
|
|
|
|
| 11864 |
*Throws:* As specified in [[fs.err.report]].
|
| 11865 |
|
| 11866 |
*Remarks:* The value of member `space_info::available` is operating
|
| 11867 |
system dependent.
|
| 11868 |
|
| 11869 |
+
[*Note 1*: `available` might be less than `free`. — *end note*]
|
| 11870 |
|
| 11871 |
#### Status <a id="fs.op.status">[[fs.op.status]]</a>
|
| 11872 |
|
| 11873 |
``` cpp
|
| 11874 |
+
file_status filesystem::status(const path& p);
|
| 11875 |
```
|
| 11876 |
|
| 11877 |
*Effects:* As if:
|
| 11878 |
|
| 11879 |
``` cpp
|
|
|
|
| 11891 |
[*Note 1*: `result` values of `file_status(file_type::not_found)` and
|
| 11892 |
`file_status(file_type::unknown)` are not considered failures and do not
|
| 11893 |
cause an exception to be thrown. — *end note*]
|
| 11894 |
|
| 11895 |
``` cpp
|
| 11896 |
+
file_status filesystem::status(const path& p, error_code& ec) noexcept;
|
| 11897 |
```
|
| 11898 |
|
| 11899 |
*Effects:* If possible, determines the attributes of the file `p`
|
| 11900 |
resolves to, as if by using POSIX `stat()` to obtain a POSIX
|
| 11901 |
`struct stat`. If, during attribute determination, the underlying file
|
|
|
|
| 11956 |
pathname resolution continues using the contents of the symbolic link.
|
| 11957 |
|
| 11958 |
#### Status known <a id="fs.op.status.known">[[fs.op.status.known]]</a>
|
| 11959 |
|
| 11960 |
``` cpp
|
| 11961 |
+
bool filesystem::status_known(file_status s) noexcept;
|
| 11962 |
```
|
| 11963 |
|
| 11964 |
*Returns:* `s.type() != file_type::none`.
|
| 11965 |
|
| 11966 |
#### Symlink status <a id="fs.op.symlink.status">[[fs.op.symlink.status]]</a>
|
| 11967 |
|
| 11968 |
``` cpp
|
| 11969 |
+
file_status filesystem::symlink_status(const path& p);
|
| 11970 |
+
file_status filesystem::symlink_status(const path& p, error_code& ec) noexcept;
|
| 11971 |
```
|
| 11972 |
|
| 11973 |
*Effects:* Same as `status()`, above, except that the attributes of `p`
|
| 11974 |
are determined as if by using POSIX `lstat()` to obtain a POSIX
|
| 11975 |
`struct stat`.
|
|
|
|
| 11981 |
*Returns:* Same as `status()`, above, except that if the attributes
|
| 11982 |
indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
|
| 11983 |
`file_status(file_type::symlink, prms)`. The signature with argument
|
| 11984 |
`ec` returns `file_status(file_type::none)` if an error occurs.
|
| 11985 |
|
| 11986 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 11987 |
+
|
| 11988 |
*Remarks:* Pathname resolution terminates if `p` names a symbolic link.
|
| 11989 |
|
|
|
|
|
|
|
| 11990 |
#### Temporary directory path <a id="fs.op.temp.dir.path">[[fs.op.temp.dir.path]]</a>
|
| 11991 |
|
| 11992 |
``` cpp
|
| 11993 |
+
path filesystem::temp_directory_path();
|
| 11994 |
+
path filesystem::temp_directory_path(error_code& ec);
|
| 11995 |
```
|
| 11996 |
|
| 11997 |
Let `p` be an unspecified directory path suitable for temporary files.
|
| 11998 |
|
| 11999 |
*Effects:* If `exists(p)` is `false` or `is_directory(p)` is `false`, an
|
|
|
|
| 12012 |
function. — *end example*]
|
| 12013 |
|
| 12014 |
#### Weakly canonical <a id="fs.op.weakly.canonical">[[fs.op.weakly.canonical]]</a>
|
| 12015 |
|
| 12016 |
``` cpp
|
| 12017 |
+
path filesystem::weakly_canonical(const path& p);
|
| 12018 |
+
path filesystem::weakly_canonical(const path& p, error_code& ec);
|
| 12019 |
```
|
| 12020 |
|
|
|
|
|
|
|
|
|
|
| 12021 |
*Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
|
| 12022 |
determine existence, return a path composed by `operator/=` from the
|
| 12023 |
result of calling `canonical()` with a path argument composed of the
|
| 12024 |
leading elements of `p` that exist, if any, followed by the elements of
|
| 12025 |
`p` that do not exist, if any. For the first form, `canonical()` is
|
|
|
|
| 12027 |
`canonical()` is called with `ec` as an `error_code` argument, and
|
| 12028 |
`path()` is returned at the first error occurrence, if any.
|
| 12029 |
|
| 12030 |
*Ensures:* The returned path is in normal form [[fs.path.generic]].
|
| 12031 |
|
| 12032 |
+
*Returns:* `p` with symlinks resolved and the result
|
| 12033 |
+
normalized [[fs.path.generic]].
|
| 12034 |
|
| 12035 |
*Throws:* As specified in [[fs.err.report]].
|
| 12036 |
|
| 12037 |
## C library files <a id="c.files">[[c.files]]</a>
|
| 12038 |
|
|
|
|
| 12126 |
#include <cstdint> // see [cstdint.syn]
|
| 12127 |
|
| 12128 |
namespace std {
|
| 12129 |
using imaxdiv_t = see below;
|
| 12130 |
|
| 12131 |
+
constexpr intmax_t imaxabs(intmax_t j);
|
| 12132 |
+
constexpr imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
|
| 12133 |
intmax_t strtoimax(const char* nptr, char** endptr, int base);
|
| 12134 |
uintmax_t strtoumax(const char* nptr, char** endptr, int base);
|
| 12135 |
intmax_t wcstoimax(const wchar_t* nptr, wchar_t** endptr, int base);
|
| 12136 |
uintmax_t wcstoumax(const wchar_t* nptr, wchar_t** endptr, int base);
|
| 12137 |
|
| 12138 |
+
constexpr intmax_t abs(intmax_t); // optional, see below
|
| 12139 |
+
constexpr imaxdiv_t div(intmax_t, intmax_t); // optional, see below
|
| 12140 |
}
|
| 12141 |
|
| 12142 |
#define PRIdN see below
|
| 12143 |
#define PRIiN see below
|
| 12144 |
#define PRIoN see below
|
|
|
|
| 12199 |
The contents and meaning of the header `<cinttypes>` are the same as the
|
| 12200 |
C standard library header `<inttypes.h>`, with the following changes:
|
| 12201 |
|
| 12202 |
- The header `<cinttypes>` includes the header `<cstdint>` instead of
|
| 12203 |
`<stdint.h>`, and
|
| 12204 |
+
- `intmax_t` and `uintmax_t` are not required to be able to represent
|
| 12205 |
+
all values of extended integer types wider than `long long` and
|
| 12206 |
+
`unsigned long long`, respectively, and
|
| 12207 |
- if and only if the type `intmax_t` designates an extended integer type
|
| 12208 |
[[basic.fundamental]], the following function signatures are added:
|
| 12209 |
``` cpp
|
| 12210 |
+
constexpr intmax_t abs(intmax_t);
|
| 12211 |
+
constexpr imaxdiv_t div(intmax_t, intmax_t);
|
| 12212 |
```
|
| 12213 |
|
| 12214 |
which shall have the same semantics as the function signatures
|
| 12215 |
+
`constexpr intmax_t imaxabs(intmax_t)` and
|
| 12216 |
+
`constexpr imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
|
| 12217 |
|
| 12218 |
See also: ISO C 7.8
|
| 12219 |
|
| 12220 |
+
Each of the `PRI` macros listed in this subclause is defined if and only
|
| 12221 |
+
if the implementation defines the corresponding *typedef-name* in
|
| 12222 |
+
[[cstdint.syn]]. Each of the `SCN` macros listed in this subclause is
|
| 12223 |
+
defined if and only if the implementation defines the corresponding
|
| 12224 |
+
*typedef-name* in [[cstdint.syn]] and has a suitable `fscanf` length
|
| 12225 |
+
modifier for the type.
|
| 12226 |
+
|
| 12227 |
<!-- Link reference definitions -->
|
| 12228 |
[adjustfield.manip]: #adjustfield.manip
|
| 12229 |
+
[allocator.requirements.general]: library.md#allocator.requirements.general
|
| 12230 |
[basefield.manip]: #basefield.manip
|
| 12231 |
[basic.fundamental]: basic.md#basic.fundamental
|
| 12232 |
[basic.ios.cons]: #basic.ios.cons
|
| 12233 |
[basic.ios.copyfmt]: #basic.ios.copyfmt
|
| 12234 |
[basic.ios.members]: #basic.ios.members
|
| 12235 |
+
[basic.start.dynamic]: basic.md#basic.start.dynamic
|
| 12236 |
[basic.start.main]: basic.md#basic.start.main
|
| 12237 |
[bidirectional.iterators]: iterators.md#bidirectional.iterators
|
| 12238 |
[bitmask.types]: library.md#bitmask.types
|
| 12239 |
[c.files]: #c.files
|
| 12240 |
[char.traits]: strings.md#char.traits
|
| 12241 |
+
[char.traits.specializations]: strings.md#char.traits.specializations
|
| 12242 |
+
[character.seq]: library.md#character.seq
|
| 12243 |
[cinttypes.syn]: #cinttypes.syn
|
| 12244 |
[container.requirements.general]: containers.md#container.requirements.general
|
|
|
|
| 12245 |
[cpp17.copyassignable]: #cpp17.copyassignable
|
| 12246 |
[cpp17.copyconstructible]: #cpp17.copyconstructible
|
| 12247 |
[cpp17.defaultconstructible]: #cpp17.defaultconstructible
|
| 12248 |
[cpp17.destructible]: #cpp17.destructible
|
| 12249 |
[cpp17.equalitycomparable]: #cpp17.equalitycomparable
|
| 12250 |
+
[cstdint.syn]: support.md#cstdint.syn
|
| 12251 |
[cstdio.syn]: #cstdio.syn
|
| 12252 |
+
[defns.ntcts]: intro.md#defns.ntcts
|
| 12253 |
[enumerated.types]: library.md#enumerated.types
|
| 12254 |
[error.reporting]: #error.reporting
|
| 12255 |
[ext.manip]: #ext.manip
|
| 12256 |
[file.streams]: #file.streams
|
| 12257 |
[filebuf]: #filebuf
|
| 12258 |
[filebuf.assign]: #filebuf.assign
|
| 12259 |
[filebuf.cons]: #filebuf.cons
|
| 12260 |
+
[filebuf.general]: #filebuf.general
|
| 12261 |
[filebuf.members]: #filebuf.members
|
| 12262 |
[filebuf.open.modes]: #filebuf.open.modes
|
| 12263 |
[filebuf.seekoff]: #filebuf.seekoff
|
| 12264 |
[filebuf.virtuals]: #filebuf.virtuals
|
| 12265 |
[filesystems]: #filesystems
|
| 12266 |
[floatfield.manip]: #floatfield.manip
|
| 12267 |
[fmtflags.manip]: #fmtflags.manip
|
| 12268 |
[fmtflags.state]: #fmtflags.state
|
| 12269 |
+
[format.err.report]: utilities.md#format.err.report
|
| 12270 |
[fpos]: #fpos
|
| 12271 |
[fpos.members]: #fpos.members
|
| 12272 |
[fpos.operations]: #fpos.operations
|
| 12273 |
[fs.class.directory.entry]: #fs.class.directory.entry
|
| 12274 |
+
[fs.class.directory.entry.general]: #fs.class.directory.entry.general
|
| 12275 |
[fs.class.directory.iterator]: #fs.class.directory.iterator
|
| 12276 |
+
[fs.class.directory.iterator.general]: #fs.class.directory.iterator.general
|
| 12277 |
[fs.class.file.status]: #fs.class.file.status
|
| 12278 |
+
[fs.class.file.status.general]: #fs.class.file.status.general
|
| 12279 |
[fs.class.filesystem.error]: #fs.class.filesystem.error
|
| 12280 |
+
[fs.class.filesystem.error.general]: #fs.class.filesystem.error.general
|
| 12281 |
[fs.class.path]: #fs.class.path
|
| 12282 |
+
[fs.class.path.general]: #fs.class.path.general
|
| 12283 |
[fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
|
| 12284 |
+
[fs.class.rec.dir.itr.general]: #fs.class.rec.dir.itr.general
|
| 12285 |
[fs.conform.9945]: #fs.conform.9945
|
| 12286 |
[fs.conform.os]: #fs.conform.os
|
| 12287 |
[fs.conformance]: #fs.conformance
|
| 12288 |
+
[fs.conformance.general]: #fs.conformance.general
|
| 12289 |
[fs.dir.entry.cons]: #fs.dir.entry.cons
|
| 12290 |
+
[fs.dir.entry.io]: #fs.dir.entry.io
|
| 12291 |
[fs.dir.entry.mods]: #fs.dir.entry.mods
|
| 12292 |
[fs.dir.entry.obs]: #fs.dir.entry.obs
|
| 12293 |
[fs.dir.itr.members]: #fs.dir.itr.members
|
| 12294 |
[fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
|
| 12295 |
[fs.enum]: #fs.enum
|
|
|
|
| 12304 |
[fs.file.status.mods]: #fs.file.status.mods
|
| 12305 |
[fs.file.status.obs]: #fs.file.status.obs
|
| 12306 |
[fs.filesystem.error.members]: #fs.filesystem.error.members
|
| 12307 |
[fs.filesystem.syn]: #fs.filesystem.syn
|
| 12308 |
[fs.general]: #fs.general
|
|
|
|
| 12309 |
[fs.op.absolute]: #fs.op.absolute
|
| 12310 |
[fs.op.canonical]: #fs.op.canonical
|
| 12311 |
[fs.op.copy]: #fs.op.copy
|
| 12312 |
[fs.op.copy.file]: #fs.op.copy.file
|
| 12313 |
[fs.op.copy.symlink]: #fs.op.copy.symlink
|
|
|
|
| 12319 |
[fs.op.current.path]: #fs.op.current.path
|
| 12320 |
[fs.op.equivalent]: #fs.op.equivalent
|
| 12321 |
[fs.op.exists]: #fs.op.exists
|
| 12322 |
[fs.op.file.size]: #fs.op.file.size
|
| 12323 |
[fs.op.funcs]: #fs.op.funcs
|
| 12324 |
+
[fs.op.funcs.general]: #fs.op.funcs.general
|
| 12325 |
[fs.op.hard.lk.ct]: #fs.op.hard.lk.ct
|
| 12326 |
[fs.op.is.block.file]: #fs.op.is.block.file
|
| 12327 |
[fs.op.is.char.file]: #fs.op.is.char.file
|
| 12328 |
[fs.op.is.directory]: #fs.op.is.directory
|
| 12329 |
[fs.op.is.empty]: #fs.op.is.empty
|
|
|
|
| 12356 |
[fs.path.decompose]: #fs.path.decompose
|
| 12357 |
[fs.path.fmt.cvt]: #fs.path.fmt.cvt
|
| 12358 |
[fs.path.gen]: #fs.path.gen
|
| 12359 |
[fs.path.generic]: #fs.path.generic
|
| 12360 |
[fs.path.generic.obs]: #fs.path.generic.obs
|
| 12361 |
+
[fs.path.hash]: #fs.path.hash
|
| 12362 |
[fs.path.io]: #fs.path.io
|
| 12363 |
[fs.path.itr]: #fs.path.itr
|
| 12364 |
[fs.path.member]: #fs.path.member
|
| 12365 |
[fs.path.modifiers]: #fs.path.modifiers
|
| 12366 |
[fs.path.native.obs]: #fs.path.native.obs
|
|
|
|
| 12370 |
[fs.path.type.cvt]: #fs.path.type.cvt
|
| 12371 |
[fs.race.behavior]: #fs.race.behavior
|
| 12372 |
[fs.rec.dir.itr.members]: #fs.rec.dir.itr.members
|
| 12373 |
[fs.rec.dir.itr.nonmembers]: #fs.rec.dir.itr.nonmembers
|
| 12374 |
[fs.req]: #fs.req
|
|
|
|
| 12375 |
[fstream]: #fstream
|
|
|
|
| 12376 |
[fstream.cons]: #fstream.cons
|
| 12377 |
+
[fstream.general]: #fstream.general
|
| 12378 |
[fstream.members]: #fstream.members
|
| 12379 |
+
[fstream.swap]: #fstream.swap
|
| 12380 |
[fstream.syn]: #fstream.syn
|
| 12381 |
[ifstream]: #ifstream
|
|
|
|
| 12382 |
[ifstream.cons]: #ifstream.cons
|
| 12383 |
+
[ifstream.general]: #ifstream.general
|
| 12384 |
[ifstream.members]: #ifstream.members
|
| 12385 |
+
[ifstream.swap]: #ifstream.swap
|
| 12386 |
[input.iterators]: iterators.md#input.iterators
|
| 12387 |
[input.output]: #input.output
|
| 12388 |
[input.output.general]: #input.output.general
|
| 12389 |
[input.streams]: #input.streams
|
| 12390 |
+
[input.streams.general]: #input.streams.general
|
| 12391 |
[intro.multithread]: basic.md#intro.multithread
|
| 12392 |
[intro.races]: basic.md#intro.races
|
| 12393 |
[iomanip.syn]: #iomanip.syn
|
| 12394 |
[ios]: #ios
|
| 12395 |
[ios.base]: #ios.base
|
| 12396 |
[ios.base.callback]: #ios.base.callback
|
| 12397 |
[ios.base.cons]: #ios.base.cons
|
| 12398 |
+
[ios.base.general]: #ios.base.general
|
| 12399 |
[ios.base.locales]: #ios.base.locales
|
| 12400 |
[ios.base.storage]: #ios.base.storage
|
| 12401 |
[ios.failure]: #ios.failure
|
| 12402 |
[ios.fmtflags]: #ios.fmtflags
|
| 12403 |
[ios.fmtflags.const]: #ios.fmtflags.const
|
|
|
|
| 12420 |
[iostream.limits.imbue]: #iostream.limits.imbue
|
| 12421 |
[iostream.objects]: #iostream.objects
|
| 12422 |
[iostream.objects.overview]: #iostream.objects.overview
|
| 12423 |
[iostream.syn]: #iostream.syn
|
| 12424 |
[iostreamclass]: #iostreamclass
|
| 12425 |
+
[iostreamclass.general]: #iostreamclass.general
|
| 12426 |
[iostreams.base]: #iostreams.base
|
| 12427 |
[iostreams.limits.pos]: #iostreams.limits.pos
|
| 12428 |
[iostreams.requirements]: #iostreams.requirements
|
| 12429 |
[iostreams.summary]: #iostreams.summary
|
| 12430 |
[iostreams.threadsafety]: #iostreams.threadsafety
|
| 12431 |
+
[ispanstream]: #ispanstream
|
| 12432 |
+
[ispanstream.cons]: #ispanstream.cons
|
| 12433 |
+
[ispanstream.general]: #ispanstream.general
|
| 12434 |
+
[ispanstream.members]: #ispanstream.members
|
| 12435 |
+
[ispanstream.swap]: #ispanstream.swap
|
| 12436 |
[istream]: #istream
|
| 12437 |
[istream.assign]: #istream.assign
|
| 12438 |
[istream.cons]: #istream.cons
|
| 12439 |
[istream.extractors]: #istream.extractors
|
| 12440 |
[istream.formatted]: #istream.formatted
|
| 12441 |
[istream.formatted.arithmetic]: #istream.formatted.arithmetic
|
| 12442 |
[istream.formatted.reqmts]: #istream.formatted.reqmts
|
| 12443 |
+
[istream.general]: #istream.general
|
| 12444 |
[istream.manip]: #istream.manip
|
| 12445 |
[istream.rvalue]: #istream.rvalue
|
| 12446 |
[istream.sentry]: #istream.sentry
|
| 12447 |
[istream.syn]: #istream.syn
|
| 12448 |
[istream.unformatted]: #istream.unformatted
|
| 12449 |
[istringstream]: #istringstream
|
|
|
|
| 12450 |
[istringstream.cons]: #istringstream.cons
|
| 12451 |
+
[istringstream.general]: #istringstream.general
|
| 12452 |
[istringstream.members]: #istringstream.members
|
| 12453 |
+
[istringstream.swap]: #istringstream.swap
|
| 12454 |
[lex.charset]: lex.md#lex.charset
|
| 12455 |
[locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
|
| 12456 |
[locale.num.get]: localization.md#locale.num.get
|
| 12457 |
[namespace.std]: library.md#namespace.std
|
| 12458 |
[narrow.stream.objects]: #narrow.stream.objects
|
| 12459 |
[numeric.limits]: support.md#numeric.limits
|
| 12460 |
[ofstream]: #ofstream
|
|
|
|
| 12461 |
[ofstream.cons]: #ofstream.cons
|
| 12462 |
+
[ofstream.general]: #ofstream.general
|
| 12463 |
[ofstream.members]: #ofstream.members
|
| 12464 |
+
[ofstream.swap]: #ofstream.swap
|
| 12465 |
+
[ospanstream]: #ospanstream
|
| 12466 |
+
[ospanstream.cons]: #ospanstream.cons
|
| 12467 |
+
[ospanstream.general]: #ospanstream.general
|
| 12468 |
+
[ospanstream.members]: #ospanstream.members
|
| 12469 |
+
[ospanstream.swap]: #ospanstream.swap
|
| 12470 |
[ostream]: #ostream
|
| 12471 |
[ostream.assign]: #ostream.assign
|
| 12472 |
[ostream.cons]: #ostream.cons
|
| 12473 |
[ostream.formatted]: #ostream.formatted
|
| 12474 |
+
[ostream.formatted.print]: #ostream.formatted.print
|
| 12475 |
[ostream.formatted.reqmts]: #ostream.formatted.reqmts
|
| 12476 |
+
[ostream.general]: #ostream.general
|
| 12477 |
[ostream.inserters]: #ostream.inserters
|
| 12478 |
[ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
|
| 12479 |
[ostream.inserters.character]: #ostream.inserters.character
|
| 12480 |
[ostream.manip]: #ostream.manip
|
| 12481 |
[ostream.rvalue]: #ostream.rvalue
|
| 12482 |
[ostream.seeks]: #ostream.seeks
|
| 12483 |
[ostream.sentry]: #ostream.sentry
|
| 12484 |
[ostream.syn]: #ostream.syn
|
| 12485 |
[ostream.unformatted]: #ostream.unformatted
|
| 12486 |
[ostringstream]: #ostringstream
|
|
|
|
| 12487 |
[ostringstream.cons]: #ostringstream.cons
|
| 12488 |
+
[ostringstream.general]: #ostringstream.general
|
| 12489 |
[ostringstream.members]: #ostringstream.members
|
| 12490 |
+
[ostringstream.swap]: #ostringstream.swap
|
| 12491 |
[output.streams]: #output.streams
|
| 12492 |
+
[output.streams.general]: #output.streams.general
|
| 12493 |
+
[print.fun]: #print.fun
|
| 12494 |
+
[print.syn]: #print.syn
|
| 12495 |
[quoted.manip]: #quoted.manip
|
| 12496 |
[res.on.data.races]: library.md#res.on.data.races
|
| 12497 |
[res.on.exception.handling]: library.md#res.on.exception.handling
|
| 12498 |
+
[span.streams]: #span.streams
|
| 12499 |
+
[span.streams.overview]: #span.streams.overview
|
| 12500 |
+
[spanbuf]: #spanbuf
|
| 12501 |
+
[spanbuf.assign]: #spanbuf.assign
|
| 12502 |
+
[spanbuf.cons]: #spanbuf.cons
|
| 12503 |
+
[spanbuf.general]: #spanbuf.general
|
| 12504 |
+
[spanbuf.members]: #spanbuf.members
|
| 12505 |
+
[spanbuf.virtuals]: #spanbuf.virtuals
|
| 12506 |
+
[spanstream]: #spanstream
|
| 12507 |
+
[spanstream.cons]: #spanstream.cons
|
| 12508 |
+
[spanstream.general]: #spanstream.general
|
| 12509 |
+
[spanstream.members]: #spanstream.members
|
| 12510 |
+
[spanstream.swap]: #spanstream.swap
|
| 12511 |
+
[spanstream.syn]: #spanstream.syn
|
| 12512 |
[sstream.syn]: #sstream.syn
|
| 12513 |
[std.ios.manip]: #std.ios.manip
|
| 12514 |
[std.manip]: #std.manip
|
| 12515 |
+
[std.modules]: library.md#std.modules
|
| 12516 |
[stream.buffers]: #stream.buffers
|
| 12517 |
[stream.types]: #stream.types
|
| 12518 |
[streambuf]: #streambuf
|
| 12519 |
[streambuf.assign]: #streambuf.assign
|
| 12520 |
[streambuf.buffer]: #streambuf.buffer
|
| 12521 |
[streambuf.cons]: #streambuf.cons
|
| 12522 |
+
[streambuf.general]: #streambuf.general
|
| 12523 |
[streambuf.get.area]: #streambuf.get.area
|
| 12524 |
[streambuf.locales]: #streambuf.locales
|
| 12525 |
[streambuf.members]: #streambuf.members
|
| 12526 |
[streambuf.protected]: #streambuf.protected
|
| 12527 |
[streambuf.pub.get]: #streambuf.pub.get
|
|
|
|
| 12539 |
[string.classes]: strings.md#string.classes
|
| 12540 |
[string.streams]: #string.streams
|
| 12541 |
[stringbuf]: #stringbuf
|
| 12542 |
[stringbuf.assign]: #stringbuf.assign
|
| 12543 |
[stringbuf.cons]: #stringbuf.cons
|
| 12544 |
+
[stringbuf.general]: #stringbuf.general
|
| 12545 |
[stringbuf.members]: #stringbuf.members
|
| 12546 |
[stringbuf.seekoff.newoff]: #stringbuf.seekoff.newoff
|
| 12547 |
[stringbuf.seekoff.pos]: #stringbuf.seekoff.pos
|
| 12548 |
[stringbuf.virtuals]: #stringbuf.virtuals
|
| 12549 |
[strings]: strings.md#strings
|
| 12550 |
[stringstream]: #stringstream
|
|
|
|
| 12551 |
[stringstream.cons]: #stringstream.cons
|
| 12552 |
+
[stringstream.general]: #stringstream.general
|
| 12553 |
[stringstream.members]: #stringstream.members
|
| 12554 |
+
[stringstream.swap]: #stringstream.swap
|
| 12555 |
[syncstream]: #syncstream
|
| 12556 |
[syncstream.osyncstream]: #syncstream.osyncstream
|
| 12557 |
[syncstream.osyncstream.cons]: #syncstream.osyncstream.cons
|
| 12558 |
[syncstream.osyncstream.members]: #syncstream.osyncstream.members
|
| 12559 |
[syncstream.osyncstream.overview]: #syncstream.osyncstream.overview
|
|
|
|
| 12564 |
[syncstream.syncbuf.members]: #syncstream.syncbuf.members
|
| 12565 |
[syncstream.syncbuf.overview]: #syncstream.syncbuf.overview
|
| 12566 |
[syncstream.syncbuf.special]: #syncstream.syncbuf.special
|
| 12567 |
[syncstream.syncbuf.virtuals]: #syncstream.syncbuf.virtuals
|
| 12568 |
[temp.deduct]: temp.md#temp.deduct
|
| 12569 |
+
[term.unevaluated.operand]: expr.md#term.unevaluated.operand
|
| 12570 |
+
[views.span]: containers.md#views.span
|
| 12571 |
[wide.stream.objects]: #wide.stream.objects
|
| 12572 |
|
| 12573 |
+
[^1]: Typically `long long`.
|
| 12574 |
+
|
| 12575 |
+
[^2]: Most places where `streamsize` is used would use `size_t` in ISO
|
| 12576 |
+
C, or `ssize_t` in POSIX.
|
| 12577 |
+
|
| 12578 |
+
[^3]: It is the implementation’s responsibility to implement headers so
|
| 12579 |
that including `<iosfwd>` and other headers does not violate the
|
| 12580 |
rules about multiple occurrences of default arguments.
|
| 12581 |
|
| 12582 |
+
[^4]: Constructors and destructors for objects with static storage
|
|
|
|
|
|
|
|
|
|
| 12583 |
duration can access these objects to read input from `stdin` or
|
| 12584 |
write output to `stdout` or `stderr`.
|
| 12585 |
|
| 12586 |
+
[^5]: This implies that operations on a standard iostream object can be
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 12587 |
mixed arbitrarily with operations on the corresponding stdio stream.
|
| 12588 |
In practical terms, synchronization usually means that a standard
|
| 12589 |
iostream object and a standard stdio object share a buffer.
|
| 12590 |
|
| 12591 |
+
[^6]: An implementation is free to implement both the integer array
|
| 12592 |
pointed at by `iarray` and the pointer array pointed at by `parray`
|
| 12593 |
as sparse data structures, possibly with a one-element cache for
|
| 12594 |
each.
|
| 12595 |
|
| 12596 |
+
[^7]: For example, because it cannot allocate space.
|
| 12597 |
+
|
| 12598 |
[^8]: For example, because it cannot allocate space.
|
| 12599 |
|
| 12600 |
+
[^9]: This suggests an infinite amount of copying, but the
|
|
|
|
|
|
|
| 12601 |
implementation can keep track of the maximum element of the arrays
|
| 12602 |
that is nonzero.
|
| 12603 |
|
| 12604 |
+
[^10]: Checking `badbit` also for `fail()` is historical practice.
|
| 12605 |
|
| 12606 |
+
[^11]: The function signature `dec(ios_base&)` can be called by the
|
| 12607 |
function signature
|
| 12608 |
`basic_ostream& stream::operator<<(ios_base& (*)(ios_base&))` to
|
| 12609 |
permit expressions of the form `cout << dec` to change the format
|
| 12610 |
flags stored in `cout`.
|
| 12611 |
|
| 12612 |
+
[^12]: The default constructor is protected for class `basic_streambuf`
|
| 12613 |
+
to assure that only objects for classes derived from this class can
|
| 12614 |
be constructed.
|
| 12615 |
|
| 12616 |
+
[^13]: The morphemes of `showmanyc` are “es-how-many-see”, not
|
| 12617 |
+
“show-manic”.
|
| 12618 |
+
|
| 12619 |
+
[^14]: `underflow` or `uflow` can fail by throwing an exception
|
| 12620 |
prematurely. The intention is not only that the calls will not
|
| 12621 |
return `eof()` but that they will return “immediately”.
|
| 12622 |
|
| 12623 |
[^15]: Classes derived from `basic_streambuf` can provide more efficient
|
| 12624 |
ways to implement `xsgetn()` and `xsputn()` by overriding these
|
| 12625 |
definitions from the base class.
|
| 12626 |
|
| 12627 |
+
[^16]: That is, for each class derived from a specialization of
|
| 12628 |
+
`basic_streambuf` in this Clause [[stringbuf]], [[filebuf]],
|
| 12629 |
+
a specification of how consuming a character effects the associated
|
| 12630 |
+
output sequence is given. There is no requirement on a
|
| 12631 |
+
program-defined class.
|
| 12632 |
|
| 12633 |
[^17]: Typically, `overflow` returns `c` to indicate success, except
|
| 12634 |
when `traits::eq_int_type(c, traits::eof())` returns `true`, in
|
| 12635 |
which case it returns `traits::not_eof(c)`.
|
| 12636 |
|
|
|
|
| 12639 |
specified.
|
| 12640 |
|
| 12641 |
[^19]: The `sentry` constructor and destructor can also perform
|
| 12642 |
additional implementation-dependent operations.
|
| 12643 |
|
| 12644 |
+
[^20]: See, for example, the function signature
|
|
|
|
|
|
|
| 12645 |
`ws(basic_istream&)`[[istream.manip]].
|
| 12646 |
|
| 12647 |
+
[^21]: See, for example, the function signature
|
| 12648 |
`dec(ios_base&)`[[basefield.manip]].
|
| 12649 |
|
| 12650 |
+
[^22]: Note that this function is not overloaded on types `signed char`
|
| 12651 |
+
and `unsigned char`.
|
| 12652 |
+
|
| 12653 |
+
[^23]: Note that this function is not overloaded on types `signed char`
|
| 12654 |
+
and `unsigned char`.
|
| 12655 |
|
| 12656 |
[^24]: Note that this function is not overloaded on types `signed char`
|
| 12657 |
and `unsigned char`.
|
| 12658 |
|
| 12659 |
+
[^25]: Since the final input character is “extracted”, it is counted in
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 12660 |
the `gcount()`, even though it is not stored.
|
| 12661 |
|
| 12662 |
+
[^26]: This allows an input line which exactly fills the buffer, without
|
| 12663 |
setting `failbit`. This is different behavior than the historical
|
| 12664 |
AT&T implementation.
|
| 12665 |
|
| 12666 |
+
[^27]: This implies an empty input line will not cause `failbit` to be
|
| 12667 |
set.
|
| 12668 |
|
| 12669 |
+
[^28]: Note that this function is not overloaded on types `signed char`
|
| 12670 |
and `unsigned char`.
|
| 12671 |
|
| 12672 |
+
[^29]: The call `os.tie()->flush()` does not necessarily occur if the
|
| 12673 |
function can determine that no synchronization is necessary.
|
| 12674 |
|
| 12675 |
+
[^30]: The `sentry` constructor and destructor can also perform
|
| 12676 |
additional implementation-dependent operations.
|
| 12677 |
|
| 12678 |
+
[^31]: This is done without causing an `ios_base::failure` to be thrown.
|
| 12679 |
|
| 12680 |
+
[^32]: See, for example, the function signature
|
| 12681 |
`endl(basic_ostream&)`[[ostream.manip]].
|
| 12682 |
|
| 12683 |
+
[^33]: See, for example, the function signature
|
| 12684 |
`dec(ios_base&)`[[basefield.manip]].
|
| 12685 |
|
| 12686 |
+
[^34]: This is done without causing an `ios_base::failure` to be thrown.
|
| 12687 |
|
| 12688 |
+
[^35]: Note that this function is not overloaded on types `signed char`
|
| 12689 |
and `unsigned char`.
|
| 12690 |
|
| 12691 |
+
[^36]: Note that this function is not overloaded on types `signed char`
|
| 12692 |
and `unsigned char`.
|
| 12693 |
|
| 12694 |
+
[^37]: The expression `cin >> resetiosflags(ios_base::skipws)` clears
|
| 12695 |
`ios_base::skipws` in the format flags stored in the
|
| 12696 |
`basic_istream<charT, traits>` object `cin` (the same as
|
| 12697 |
`cin >> noskipws`), and the expression
|
| 12698 |
`cout << resetiosflags(ios_base::showbase)` clears
|
| 12699 |
`ios_base::showbase` in the format flags stored in the
|
| 12700 |
`basic_ostream<charT, traits>` object `cout` (the same as
|
| 12701 |
`cout << noshowbase`).
|
| 12702 |
|
| 12703 |
+
[^38]: The macro `SEEK_END` is defined, and the function signatures
|
| 12704 |
`fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
|
| 12705 |
declared, in `<cstdio>`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|