- tmp/tmpq_l8sgxm/{from.md → to.md} +2590 -1776
tmp/tmpq_l8sgxm/{from.md → to.md}
RENAMED
|
@@ -7,75 +7,74 @@ input/output operations.
|
|
| 7 |
|
| 8 |
The following subclauses describe requirements for stream parameters,
|
| 9 |
and components for forward declarations of iostreams, predefined
|
| 10 |
iostreams objects, base iostreams classes, stream buffering, stream
|
| 11 |
formatting and manipulators, string streams, and file streams, as
|
| 12 |
-
summarized in
|
| 13 |
|
| 14 |
-
**Table: Input/output library summary** <a id="
|
| 15 |
|
| 16 |
| Subclause | | Header |
|
| 17 |
-
| -------------------------- | --------------------------- | -------------- |
|
| 18 |
| [[iostreams.requirements]] | Requirements | |
|
| 19 |
| [[iostream.forward]] | Forward declarations | `<iosfwd>` |
|
| 20 |
| [[iostream.objects]] | Standard iostream objects | `<iostream>` |
|
| 21 |
| [[iostreams.base]] | Iostreams base classes | `<ios>` |
|
| 22 |
| [[stream.buffers]] | Stream buffers | `<streambuf>` |
|
| 23 |
-
| [[iostream.format]] | Formatting and manipulators | `<istream>`
|
| 24 |
-
| | | `<ostream>` |
|
| 25 |
-
| | | `<iomanip>` |
|
| 26 |
| [[string.streams]] | String streams | `<sstream>` |
|
| 27 |
| [[file.streams]] | File streams | `<fstream>` |
|
|
|
|
| 28 |
| [[filesystems]] | File systems | `<filesystem>` |
|
| 29 |
-
| [[c.files]] | C library files | `<cstdio>`
|
| 30 |
-
| | | `<cinttypes>` |
|
| 31 |
|
| 32 |
|
| 33 |
-
Figure
|
| 34 |
-
described in this clause. A line from
|
| 35 |
-
**A**
|
| 36 |
-
terms of **B**.
|
| 37 |
|
| 38 |
-
<a id="fig:streampos"></a>
|
| 39 |
|
| 40 |
-
![Stream position, offset, and size types \[
|
|
|
|
|
|
|
| 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
|
| 47 |
-
|
| 48 |
-
|
| 49 |
-
|
| 50 |
-
|
| 51 |
-
|
| 52 |
|
| 53 |
### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
|
| 54 |
|
| 55 |
-
The classes of
|
| 56 |
-
|
| 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
|
| 62 |
-
|
| 63 |
`wchar_t`, and any other *implementation-defined* character types that
|
| 64 |
-
|
| 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 |
-
[[file.streams]]), stream buffer object
|
| 71 |
-
|
| 72 |
-
|
| 73 |
-
[[iostream.objects]]).
|
| 74 |
|
| 75 |
-
[*Note 1*: Data races result in undefined behavior
|
| 76 |
-
[[intro.multithread]]
|
| 77 |
|
| 78 |
If one thread makes a library call *a* that writes a value to a stream
|
| 79 |
and, as a result, another thread reads this value from the stream
|
| 80 |
through a library call *b* such that this does not result in a data
|
| 81 |
race, then *a*’s write synchronizes with *b*’s read.
|
|
@@ -84,15 +83,16 @@ race, then *a*’s write synchronizes with *b*’s read.
|
|
| 84 |
|
| 85 |
### Header `<iosfwd>` synopsis <a id="iosfwd.syn">[[iosfwd.syn]]</a>
|
| 86 |
|
| 87 |
``` cpp
|
| 88 |
namespace std {
|
| 89 |
-
template<class charT>
|
| 90 |
-
template<>
|
| 91 |
-
template<>
|
| 92 |
-
template<>
|
| 93 |
-
template<>
|
|
|
|
| 94 |
|
| 95 |
template<class T> class allocator;
|
| 96 |
|
| 97 |
template<class charT, class traits = char_traits<charT>>
|
| 98 |
class basic_ios;
|
|
@@ -125,10 +125,17 @@ namespace std {
|
|
| 125 |
template<class charT, class traits = char_traits<charT>>
|
| 126 |
class basic_ofstream;
|
| 127 |
template<class charT, class traits = char_traits<charT>>
|
| 128 |
class basic_fstream;
|
| 129 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 130 |
template<class charT, class traits = char_traits<charT>>
|
| 131 |
class istreambuf_iterator;
|
| 132 |
template<class charT, class traits = char_traits<charT>>
|
| 133 |
class ostreambuf_iterator;
|
| 134 |
|
|
@@ -148,10 +155,13 @@ namespace std {
|
|
| 148 |
using filebuf = basic_filebuf<char>;
|
| 149 |
using ifstream = basic_ifstream<char>;
|
| 150 |
using ofstream = basic_ofstream<char>;
|
| 151 |
using fstream = basic_fstream<char>;
|
| 152 |
|
|
|
|
|
|
|
|
|
|
| 153 |
using wstreambuf = basic_streambuf<wchar_t>;
|
| 154 |
using wistream = basic_istream<wchar_t>;
|
| 155 |
using wostream = basic_ostream<wchar_t>;
|
| 156 |
using wiostream = basic_iostream<wchar_t>;
|
| 157 |
|
|
@@ -163,13 +173,19 @@ namespace std {
|
|
| 163 |
using wfilebuf = basic_filebuf<wchar_t>;
|
| 164 |
using wifstream = basic_ifstream<wchar_t>;
|
| 165 |
using wofstream = basic_ofstream<wchar_t>;
|
| 166 |
using wfstream = basic_fstream<wchar_t>;
|
| 167 |
|
|
|
|
|
|
|
|
|
|
| 168 |
template<class state> class fpos;
|
| 169 |
using streampos = fpos<char_traits<char>::state_type>;
|
| 170 |
using wstreampos = fpos<char_traits<wchar_t>::state_type>;
|
|
|
|
|
|
|
|
|
|
| 171 |
}
|
| 172 |
```
|
| 173 |
|
| 174 |
Default template arguments are described as appearing both in `<iosfwd>`
|
| 175 |
and in the synopsis of other headers but it is well-formed to include
|
|
@@ -182,52 +198,42 @@ virtual base class for the class templates `basic_istream`,
|
|
| 182 |
`basic_ostream`, and class templates derived from them. `basic_iostream`
|
| 183 |
is a class template derived from both `basic_istream<charT, traits>` and
|
| 184 |
`basic_ostream<charT, traits>`.
|
| 185 |
|
| 186 |
The class template specialization `basic_streambuf<charT, traits>`
|
| 187 |
-
serves as a base class for class templates `basic_stringbuf`
|
| 188 |
-
`basic_filebuf`.
|
| 189 |
|
| 190 |
The class template specialization `basic_istream<charT, traits>` serves
|
| 191 |
as a base class for class templates `basic_istringstream` and
|
| 192 |
`basic_ifstream`.
|
| 193 |
|
| 194 |
The class template specialization `basic_ostream<charT, traits>` serves
|
| 195 |
-
as a base class for class templates `basic_ostringstream`
|
| 196 |
-
`basic_ofstream`.
|
| 197 |
|
| 198 |
The class template specialization `basic_iostream<charT, traits>` serves
|
| 199 |
as a base class for class templates `basic_stringstream` and
|
| 200 |
`basic_fstream`.
|
| 201 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 202 |
Other *typedef-name*s define instances of class templates specialized
|
| 203 |
for `char` or `wchar_t` types.
|
| 204 |
|
| 205 |
Specializations of the class template `fpos` are used for specifying
|
| 206 |
file position information.
|
| 207 |
|
| 208 |
-
The types `streampos` and `wstreampos` are used for
|
| 209 |
-
specialized on `char` and `wchar_t`
|
|
|
|
| 210 |
|
| 211 |
-
[*Note
|
| 212 |
-
|
| 213 |
-
This synopsis suggests a circularity between `streampos` and
|
| 214 |
`char_traits<char>`. An implementation can avoid this circularity by
|
| 215 |
-
substituting equivalent types.
|
| 216 |
-
|
| 217 |
-
``` cpp
|
| 218 |
-
template<class stateT> class fpos { ... }; // depends on nothing
|
| 219 |
-
using _STATE = ... ; // implementation private declaration of stateT
|
| 220 |
-
|
| 221 |
-
using streampos = fpos<_STATE>;
|
| 222 |
-
|
| 223 |
-
template<> struct char_traits<char> {
|
| 224 |
-
using pos_type = streampos;
|
| 225 |
-
}
|
| 226 |
-
```
|
| 227 |
-
|
| 228 |
-
— *end note*]
|
| 229 |
|
| 230 |
## Standard iostream objects <a id="iostream.objects">[[iostream.objects]]</a>
|
| 231 |
|
| 232 |
### Header `<iostream>` synopsis <a id="iostream.syn">[[iostream.syn]]</a>
|
| 233 |
|
|
@@ -251,115 +257,114 @@ namespace std {
|
|
| 251 |
```
|
| 252 |
|
| 253 |
### Overview <a id="iostream.objects.overview">[[iostream.objects.overview]]</a>
|
| 254 |
|
| 255 |
In this Clause, the type name `FILE` refers to the type `FILE` declared
|
| 256 |
-
in `<cstdio>`
|
| 257 |
|
| 258 |
The header `<iostream>` declares objects that associate objects with the
|
| 259 |
-
standard C streams provided for by the functions declared in
|
| 260 |
-
|
| 261 |
-
these objects.
|
| 262 |
|
| 263 |
The objects are constructed and the associations are established at some
|
| 264 |
time prior to or during the first time an object of class
|
| 265 |
`ios_base::Init` is constructed, and in any case before the body of
|
| 266 |
-
`main`
|
| 267 |
destroyed during program execution.[^3] The results of including
|
| 268 |
`<iostream>` in a translation unit shall be as if `<iostream>` defined
|
| 269 |
an instance of `ios_base::Init` with static storage duration.
|
| 270 |
|
| 271 |
Mixing operations on corresponding wide- and narrow-character streams
|
| 272 |
follows the same semantics as mixing such operations on `FILE`s, as
|
| 273 |
specified in the C standard library.
|
| 274 |
|
| 275 |
-
Concurrent access to a synchronized
|
| 276 |
-
iostream object’s formatted and unformatted input
|
| 277 |
-
|
| 278 |
-
|
| 279 |
|
| 280 |
[*Note 1*: Users must still synchronize concurrent use of these objects
|
| 281 |
and streams by multiple threads if they wish to avoid interleaved
|
| 282 |
characters. — *end note*]
|
| 283 |
|
| 284 |
-
|
| 285 |
|
| 286 |
### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
|
| 287 |
|
| 288 |
``` cpp
|
| 289 |
istream cin;
|
| 290 |
```
|
| 291 |
|
| 292 |
The object `cin` controls input from a stream buffer associated with the
|
| 293 |
-
object `stdin`, declared in `<cstdio>`
|
| 294 |
|
| 295 |
After the object `cin` is initialized, `cin.tie()` returns `&cout`. Its
|
| 296 |
-
state is otherwise the same as required for
|
| 297 |
-
|
| 298 |
|
| 299 |
``` cpp
|
| 300 |
ostream cout;
|
| 301 |
```
|
| 302 |
|
| 303 |
The object `cout` controls output to a stream buffer associated with the
|
| 304 |
-
object `stdout`, declared in `<cstdio>`
|
| 305 |
|
| 306 |
``` cpp
|
| 307 |
ostream cerr;
|
| 308 |
```
|
| 309 |
|
| 310 |
The object `cerr` controls output to a stream buffer associated with the
|
| 311 |
-
object `stderr`, declared in `<cstdio>`
|
| 312 |
|
| 313 |
After the object `cerr` is initialized, `cerr.flags() & unitbuf` is
|
| 314 |
nonzero and `cerr.tie()` returns `&cout`. Its state is otherwise the
|
| 315 |
-
same as required for `basic_ios<char>::init`
|
| 316 |
|
| 317 |
``` cpp
|
| 318 |
ostream clog;
|
| 319 |
```
|
| 320 |
|
| 321 |
The object `clog` controls output to a stream buffer associated with the
|
| 322 |
-
object `stderr`, declared in `<cstdio>`
|
| 323 |
|
| 324 |
### Wide stream objects <a id="wide.stream.objects">[[wide.stream.objects]]</a>
|
| 325 |
|
| 326 |
``` cpp
|
| 327 |
wistream wcin;
|
| 328 |
```
|
| 329 |
|
| 330 |
The object `wcin` controls input from a stream buffer associated with
|
| 331 |
-
the object `stdin`, declared in `<cstdio>`
|
| 332 |
|
| 333 |
After the object `wcin` is initialized, `wcin.tie()` returns `&wcout`.
|
| 334 |
Its state is otherwise the same as required for
|
| 335 |
-
`basic_ios<wchar_t>::init`
|
| 336 |
|
| 337 |
``` cpp
|
| 338 |
wostream wcout;
|
| 339 |
```
|
| 340 |
|
| 341 |
The object `wcout` controls output to a stream buffer associated with
|
| 342 |
-
the object `stdout`, declared in `<cstdio>`
|
| 343 |
|
| 344 |
``` cpp
|
| 345 |
wostream wcerr;
|
| 346 |
```
|
| 347 |
|
| 348 |
The object `wcerr` controls output to a stream buffer associated with
|
| 349 |
-
the object `stderr`, declared in `<cstdio>`
|
| 350 |
|
| 351 |
After the object `wcerr` is initialized, `wcerr.flags() & unitbuf` is
|
| 352 |
nonzero and `wcerr.tie()` returns `&wcout`. Its state is otherwise the
|
| 353 |
-
same as required for `basic_ios<wchar_t>::init`
|
| 354 |
|
| 355 |
``` cpp
|
| 356 |
wostream wclog;
|
| 357 |
```
|
| 358 |
|
| 359 |
The object `wclog` controls output to a stream buffer associated with
|
| 360 |
-
the object `stderr`, declared in `<cstdio>`
|
| 361 |
|
| 362 |
## Iostreams base classes <a id="iostreams.base">[[iostreams.base]]</a>
|
| 363 |
|
| 364 |
### Header `<ios>` synopsis <a id="ios.syn">[[ios.syn]]</a>
|
| 365 |
|
|
@@ -449,11 +454,11 @@ an I/O operation, or the size of I/O buffers.[^5]
|
|
| 449 |
namespace std {
|
| 450 |
class ios_base {
|
| 451 |
public:
|
| 452 |
class failure; // see below
|
| 453 |
|
| 454 |
-
// [ios
|
| 455 |
using fmtflags = T1;
|
| 456 |
static constexpr fmtflags boolalpha = unspecified;
|
| 457 |
static constexpr fmtflags dec = unspecified;
|
| 458 |
static constexpr fmtflags fixed = unspecified;
|
| 459 |
static constexpr fmtflags hex = unspecified;
|
|
@@ -470,27 +475,27 @@ namespace std {
|
|
| 470 |
static constexpr fmtflags uppercase = unspecified;
|
| 471 |
static constexpr fmtflags adjustfield = see below;
|
| 472 |
static constexpr fmtflags basefield = see below;
|
| 473 |
static constexpr fmtflags floatfield = see below;
|
| 474 |
|
| 475 |
-
// [ios
|
| 476 |
using iostate = T2;
|
| 477 |
static constexpr iostate badbit = unspecified;
|
| 478 |
static constexpr iostate eofbit = unspecified;
|
| 479 |
static constexpr iostate failbit = unspecified;
|
| 480 |
static constexpr iostate goodbit = see below;
|
| 481 |
|
| 482 |
-
// [ios
|
| 483 |
using openmode = T3;
|
| 484 |
static constexpr openmode app = unspecified;
|
| 485 |
static constexpr openmode ate = unspecified;
|
| 486 |
static constexpr openmode binary = unspecified;
|
| 487 |
static constexpr openmode in = unspecified;
|
| 488 |
static constexpr openmode out = unspecified;
|
| 489 |
static constexpr openmode trunc = unspecified;
|
| 490 |
|
| 491 |
-
// [ios
|
| 492 |
using seekdir = T4;
|
| 493 |
static constexpr seekdir beg = unspecified;
|
| 494 |
static constexpr seekdir cur = unspecified;
|
| 495 |
static constexpr seekdir end = unspecified;
|
| 496 |
|
|
@@ -512,20 +517,20 @@ namespace std {
|
|
| 512 |
locale imbue(const locale& loc);
|
| 513 |
locale getloc() const;
|
| 514 |
|
| 515 |
// [ios.base.storage], storage
|
| 516 |
static int xalloc();
|
| 517 |
-
long& iword(int
|
| 518 |
-
void*& pword(int
|
| 519 |
|
| 520 |
-
// destructor
|
| 521 |
virtual ~ios_base();
|
| 522 |
|
| 523 |
-
// [ios.base.callback], callbacks
|
| 524 |
enum event { erase_event, imbue_event, copyfmt_event };
|
| 525 |
-
using event_callback = void (*)(event, ios_base&, int
|
| 526 |
-
void register_callback(event_callback fn, int
|
| 527 |
|
| 528 |
ios_base(const ios_base&) = delete;
|
| 529 |
ios_base& operator=(const ios_base&) = delete;
|
| 530 |
|
| 531 |
static bool sync_with_stdio(bool sync = true);
|
|
@@ -573,11 +578,11 @@ For the sake of exposition, the maintained data is presented here as:
|
|
| 573 |
|
| 574 |
— *end note*]
|
| 575 |
|
| 576 |
#### Types <a id="ios.types">[[ios.types]]</a>
|
| 577 |
|
| 578 |
-
##### Class `ios_base::failure` <a id="ios
|
| 579 |
|
| 580 |
``` cpp
|
| 581 |
namespace std {
|
| 582 |
class ios_base::failure : public system_error {
|
| 583 |
public:
|
|
@@ -589,13 +594,13 @@ namespace std {
|
|
| 589 |
|
| 590 |
An implementation is permitted to define `ios_base::failure` as a
|
| 591 |
synonym for a class with equivalent functionality to class
|
| 592 |
`ios_base::failure` shown in this subclause.
|
| 593 |
|
| 594 |
-
[*Note 1*: When `ios_base::failure` is a synonym for another type
|
| 595 |
-
|
| 596 |
-
name. — *end note*]
|
| 597 |
|
| 598 |
The class `failure` defines the base class for the types of all objects
|
| 599 |
thrown as exceptions, by functions in the iostreams library, to report
|
| 600 |
errors detected during stream buffer operations.
|
| 601 |
|
|
@@ -612,31 +617,28 @@ iostream_category())`. — *end note*]
|
|
| 612 |
|
| 613 |
``` cpp
|
| 614 |
explicit failure(const string& msg, const error_code& ec = io_errc::stream);
|
| 615 |
```
|
| 616 |
|
| 617 |
-
*Effects:* Constructs
|
| 618 |
-
base class with `msg` and `ec`.
|
| 619 |
|
| 620 |
``` cpp
|
| 621 |
explicit failure(const char* msg, const error_code& ec = io_errc::stream);
|
| 622 |
```
|
| 623 |
|
| 624 |
-
*Effects:* Constructs
|
| 625 |
-
base class with `msg` and `ec`.
|
| 626 |
|
| 627 |
-
##### Type `ios_base::fmtflags` <a id="ios
|
| 628 |
|
| 629 |
``` cpp
|
| 630 |
using fmtflags = T1;
|
| 631 |
```
|
| 632 |
|
| 633 |
-
The type `fmtflags` is a bitmask type
|
| 634 |
-
elements has the effects indicated in
|
| 635 |
-
Table [[tab:iostreams.fmtflags.effects]].
|
| 636 |
|
| 637 |
-
**Table: `fmtflags` effects** <a id="
|
| 638 |
|
| 639 |
| Element | Effect(s) if set |
|
| 640 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
| 641 |
| `boolalpha` | insert and extract `bool` type in alphabetic format |
|
| 642 |
| `dec` | converts integer input or generates integer output in decimal base |
|
|
@@ -654,31 +656,31 @@ Table [[tab:iostreams.fmtflags.effects]].
|
|
| 654 |
| `unitbuf` | flushes output after each output operation |
|
| 655 |
| `uppercase` | replaces certain lowercase letters with their uppercase equivalents in generated output |
|
| 656 |
|
| 657 |
|
| 658 |
Type `fmtflags` also defines the constants indicated in
|
| 659 |
-
|
| 660 |
|
| 661 |
-
**Table: `fmtflags` constants** <a id="
|
| 662 |
|
| 663 |
| Constant | Allowable values |
|
| 664 |
| ------------- | ------------------------- |
|
| 665 |
| `adjustfield` | `left | right | internal` |
|
| 666 |
| `basefield` | `dec | oct | hex` |
|
| 667 |
| `floatfield` | `scientific | fixed` |
|
| 668 |
|
| 669 |
|
| 670 |
-
##### Type `ios_base::iostate` <a id="ios
|
| 671 |
|
| 672 |
``` cpp
|
| 673 |
using iostate = T2;
|
| 674 |
```
|
| 675 |
|
| 676 |
-
The type `iostate` is a bitmask type
|
| 677 |
-
|
| 678 |
|
| 679 |
-
**Table: `iostate` effects** <a id="
|
| 680 |
|
| 681 |
| Element | Effect(s) if set |
|
| 682 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
| 683 |
| `badbit` | indicates a loss of integrity in an input or output sequence (such as an irrecoverable read error from a file); |
|
| 684 |
| `eofbit` | indicates that an input operation reached the end of an input sequence; |
|
|
@@ -687,20 +689,20 @@ the elements indicated in Table [[tab:iostreams.iostate.effects]].
|
|
| 687 |
|
| 688 |
Type `iostate` also defines the constant:
|
| 689 |
|
| 690 |
- `goodbit`, the value zero.
|
| 691 |
|
| 692 |
-
##### Type `ios_base::openmode` <a id="ios
|
| 693 |
|
| 694 |
``` cpp
|
| 695 |
using openmode = T3;
|
| 696 |
```
|
| 697 |
|
| 698 |
-
The type `openmode` is a bitmask type
|
| 699 |
-
|
| 700 |
|
| 701 |
-
**Table: `openmode` effects** <a id="
|
| 702 |
|
| 703 |
| Element | Effect(s) if set |
|
| 704 |
| -------- | ----------------------------------------------------------------- |
|
| 705 |
| `app` | seek to end before each write |
|
| 706 |
| `ate` | open and seek to end immediately after opening |
|
|
@@ -708,73 +710,71 @@ the elements indicated in Table [[tab:iostreams.openmode.effects]].
|
|
| 708 |
| `in` | open for input |
|
| 709 |
| `out` | open for output |
|
| 710 |
| `trunc` | truncate an existing stream when opening |
|
| 711 |
|
| 712 |
|
| 713 |
-
##### Type `ios_base::seekdir` <a id="ios
|
| 714 |
|
| 715 |
``` cpp
|
| 716 |
using seekdir = T4;
|
| 717 |
```
|
| 718 |
|
| 719 |
-
The type `seekdir` is an enumerated type
|
| 720 |
-
contains the elements indicated in
|
| 721 |
-
Table [[tab:iostreams.seekdir.effects]].
|
| 722 |
|
| 723 |
-
**Table: `seekdir` effects** <a id="
|
| 724 |
|
| 725 |
| Element | Meaning |
|
| 726 |
| ------- | --------------------------------------------------------------------------------------- |
|
| 727 |
| `beg` | request a seek (for subsequent input or output) relative to the beginning of the stream |
|
| 728 |
| `cur` | request a seek relative to the current position within the sequence |
|
| 729 |
| `end` | request a seek relative to the current end of the sequence |
|
| 730 |
|
| 731 |
|
| 732 |
-
##### Class `ios_base::Init` <a id="ios
|
| 733 |
|
| 734 |
``` cpp
|
| 735 |
namespace std {
|
| 736 |
class ios_base::Init {
|
| 737 |
public:
|
| 738 |
Init();
|
|
|
|
| 739 |
~Init();
|
|
|
|
| 740 |
private:
|
| 741 |
static int init_cnt; // exposition only
|
| 742 |
};
|
| 743 |
}
|
| 744 |
```
|
| 745 |
|
| 746 |
The class `Init` describes an object whose construction ensures the
|
| 747 |
-
construction of the eight objects declared in `<iostream>`
|
| 748 |
-
[[iostream.objects]]
|
| 749 |
-
standard C streams provided for by the functions declared in
|
| 750 |
-
`<cstdio>` ([[cstdio.syn]]).
|
| 751 |
|
| 752 |
For the sake of exposition, the maintained data is presented here as:
|
| 753 |
|
| 754 |
- `static int init_cnt`, counts the number of constructor and destructor
|
| 755 |
calls for class `Init`, initialized to zero.
|
| 756 |
|
| 757 |
``` cpp
|
| 758 |
Init();
|
| 759 |
```
|
| 760 |
|
| 761 |
-
*Effects:* Constructs
|
| 762 |
-
|
| 763 |
-
|
| 764 |
-
initialized.
|
| 765 |
|
| 766 |
``` cpp
|
| 767 |
~Init();
|
| 768 |
```
|
| 769 |
|
| 770 |
-
*Effects:*
|
| 771 |
-
|
| 772 |
-
`
|
| 773 |
-
`wclog.flush()`.
|
| 774 |
|
| 775 |
-
####
|
| 776 |
|
| 777 |
``` cpp
|
| 778 |
fmtflags flags() const;
|
| 779 |
```
|
| 780 |
|
|
@@ -782,11 +782,11 @@ fmtflags flags() const;
|
|
| 782 |
|
| 783 |
``` cpp
|
| 784 |
fmtflags flags(fmtflags fmtfl);
|
| 785 |
```
|
| 786 |
|
| 787 |
-
*
|
| 788 |
|
| 789 |
*Returns:* The previous value of `flags()`.
|
| 790 |
|
| 791 |
``` cpp
|
| 792 |
fmtflags setf(fmtflags fmtfl);
|
|
@@ -818,11 +818,11 @@ streamsize precision() const;
|
|
| 818 |
|
| 819 |
``` cpp
|
| 820 |
streamsize precision(streamsize prec);
|
| 821 |
```
|
| 822 |
|
| 823 |
-
*
|
| 824 |
|
| 825 |
*Returns:* The previous value of `precision()`.
|
| 826 |
|
| 827 |
``` cpp
|
| 828 |
streamsize width() const;
|
|
@@ -833,47 +833,46 @@ certain output conversions.
|
|
| 833 |
|
| 834 |
``` cpp
|
| 835 |
streamsize width(streamsize wide);
|
| 836 |
```
|
| 837 |
|
| 838 |
-
*
|
| 839 |
|
| 840 |
*Returns:* The previous value of `width()`.
|
| 841 |
|
| 842 |
-
####
|
| 843 |
|
| 844 |
``` cpp
|
| 845 |
locale imbue(const locale& loc);
|
| 846 |
```
|
| 847 |
|
| 848 |
-
*Effects:* Calls each registered callback pair
|
| 849 |
-
|
| 850 |
-
`(
|
| 851 |
-
|
| 852 |
-
|
|
|
|
| 853 |
|
| 854 |
*Returns:* The previous value of `getloc()`.
|
| 855 |
|
| 856 |
-
*Postconditions:* `loc == getloc()`.
|
| 857 |
-
|
| 858 |
``` cpp
|
| 859 |
locale getloc() const;
|
| 860 |
```
|
| 861 |
|
| 862 |
-
*Returns:* If no locale has been imbued, a copy of the global C++
|
| 863 |
-
`locale()`, in effect at the time of construction. Otherwise,
|
| 864 |
-
the imbued locale, to be used to perform locale-dependent input
|
| 865 |
-
output operations.
|
| 866 |
|
| 867 |
-
####
|
| 868 |
|
| 869 |
``` cpp
|
| 870 |
-
bool sync_with_stdio(bool sync = true);
|
| 871 |
```
|
| 872 |
|
| 873 |
*Returns:* `true` if the previous state of the standard iostream
|
| 874 |
-
objects
|
| 875 |
`false`. The first time it is called, the function returns `true`.
|
| 876 |
|
| 877 |
*Effects:* If any input or output operation has occurred using the
|
| 878 |
standard streams prior to the call, the effect is
|
| 879 |
*implementation-defined*. Otherwise, called with a `false` argument, it
|
|
@@ -919,25 +918,27 @@ is the same as the effect of
|
|
| 919 |
str.rdbuf()->sputbackc(c);
|
| 920 |
```
|
| 921 |
|
| 922 |
for any sequence of characters.[^6]
|
| 923 |
|
| 924 |
-
####
|
| 925 |
|
| 926 |
``` cpp
|
| 927 |
static int xalloc();
|
| 928 |
```
|
| 929 |
|
| 930 |
*Returns:* `index` `++`.
|
| 931 |
|
| 932 |
-
*Remarks:* Concurrent access to this function by multiple threads
|
| 933 |
-
not result in a data race
|
| 934 |
|
| 935 |
``` cpp
|
| 936 |
long& iword(int idx);
|
| 937 |
```
|
| 938 |
|
|
|
|
|
|
|
| 939 |
*Effects:* If `iarray` is a null pointer, allocates an array of `long`
|
| 940 |
of unspecified size and stores a pointer to its first element in
|
| 941 |
`iarray`. The function then extends the array pointed at by `iarray` as
|
| 942 |
necessary to include the element `iarray[idx]`. Each newly allocated
|
| 943 |
element of the array is initialized to zero. The reference returned is
|
|
@@ -954,10 +955,12 @@ initialized to 0.
|
|
| 954 |
|
| 955 |
``` cpp
|
| 956 |
void*& pword(int idx);
|
| 957 |
```
|
| 958 |
|
|
|
|
|
|
|
| 959 |
*Effects:* If `parray` is a null pointer, allocates an array of pointers
|
| 960 |
to `void` of unspecified size and stores a pointer to its first element
|
| 961 |
in `parray`. The function then extends the array pointed at by `parray`
|
| 962 |
as necessary to include the element `parray[idx]`. Each newly allocated
|
| 963 |
element of the array is initialized to a null pointer. The reference
|
|
@@ -973,29 +976,29 @@ object (which may throw `failure`).
|
|
| 973 |
initialized to 0.
|
| 974 |
|
| 975 |
*Remarks:* After a subsequent call to `pword(int)` for the same object,
|
| 976 |
the earlier return value may no longer be valid.
|
| 977 |
|
| 978 |
-
####
|
| 979 |
|
| 980 |
``` cpp
|
| 981 |
-
void register_callback(event_callback fn, int
|
| 982 |
```
|
| 983 |
|
| 984 |
-
*
|
| 985 |
-
`imbue()` ([[ios.base.locales]]), `copyfmt()`, or
|
| 986 |
-
`~ios_base()` ([[ios.base.cons]]), the function `fn` is called with
|
| 987 |
-
argument `index`. Functions registered are called when an event occurs,
|
| 988 |
-
in opposite order of registration. Functions registered while a callback
|
| 989 |
-
function is active are not called until the next event.
|
| 990 |
|
| 991 |
-
*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 992 |
|
| 993 |
*Remarks:* Identical pairs are not merged. A function registered twice
|
| 994 |
will be called twice.
|
| 995 |
|
| 996 |
-
####
|
| 997 |
|
| 998 |
``` cpp
|
| 999 |
ios_base();
|
| 1000 |
```
|
| 1001 |
|
|
@@ -1006,14 +1009,14 @@ destroyed, whichever comes first; otherwise the behavior is undefined.
|
|
| 1006 |
|
| 1007 |
``` cpp
|
| 1008 |
~ios_base();
|
| 1009 |
```
|
| 1010 |
|
| 1011 |
-
*Effects:*
|
| 1012 |
-
|
| 1013 |
-
|
| 1014 |
-
|
| 1015 |
|
| 1016 |
### Class template `fpos` <a id="fpos">[[fpos]]</a>
|
| 1017 |
|
| 1018 |
``` cpp
|
| 1019 |
namespace std {
|
|
@@ -1026,11 +1029,11 @@ namespace std {
|
|
| 1026 |
stateT st; // exposition only
|
| 1027 |
};
|
| 1028 |
}
|
| 1029 |
```
|
| 1030 |
|
| 1031 |
-
####
|
| 1032 |
|
| 1033 |
``` cpp
|
| 1034 |
void state(stateT s);
|
| 1035 |
```
|
| 1036 |
|
|
@@ -1040,27 +1043,36 @@ void state(stateT s);
|
|
| 1040 |
stateT state() const;
|
| 1041 |
```
|
| 1042 |
|
| 1043 |
*Returns:* Current value of `st`.
|
| 1044 |
|
| 1045 |
-
####
|
| 1046 |
|
| 1047 |
-
|
| 1048 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1049 |
|
| 1050 |
- `P` refers to an instance of `fpos`,
|
| 1051 |
-
- `p` and `q` refer to values of type `P`,
|
| 1052 |
-
- `
|
| 1053 |
-
- `
|
| 1054 |
-
- `
|
| 1055 |
-
- `i` refers to a value of type `int`.
|
| 1056 |
-
|
| 1057 |
-
[*Note 1*: Every implementation is required to supply overloaded
|
| 1058 |
-
operators on `fpos` objects to satisfy the requirements of
|
| 1059 |
-
[[fpos.operations]]. It is unspecified whether these operators are
|
| 1060 |
-
members of `fpos`, global operators, or provided in some other
|
| 1061 |
-
way. — *end note*]
|
| 1062 |
|
| 1063 |
Stream operations that return a value of type `traits::pos_type` return
|
| 1064 |
`P(O(-1))` as an invalid value to signal an error. If this value is used
|
| 1065 |
as an argument to any `istream`, `ostream`, or `streambuf` member that
|
| 1066 |
accepts a value of type `traits::pos_type` then the behavior of that
|
|
@@ -1129,28 +1141,27 @@ namespace std {
|
|
| 1129 |
|
| 1130 |
};
|
| 1131 |
}
|
| 1132 |
```
|
| 1133 |
|
| 1134 |
-
####
|
| 1135 |
|
| 1136 |
``` cpp
|
| 1137 |
explicit basic_ios(basic_streambuf<charT, traits>* sb);
|
| 1138 |
```
|
| 1139 |
|
| 1140 |
-
*Effects:*
|
| 1141 |
-
|
| 1142 |
|
| 1143 |
``` cpp
|
| 1144 |
basic_ios();
|
| 1145 |
```
|
| 1146 |
|
| 1147 |
-
*Effects:*
|
| 1148 |
-
`basic_ios`
|
| 1149 |
-
|
| 1150 |
-
|
| 1151 |
-
whichever comes first; otherwise the behavior is undefined.
|
| 1152 |
|
| 1153 |
``` cpp
|
| 1154 |
~basic_ios();
|
| 1155 |
```
|
| 1156 |
|
|
@@ -1158,14 +1169,14 @@ whichever comes first; otherwise the behavior is undefined.
|
|
| 1158 |
|
| 1159 |
``` cpp
|
| 1160 |
void init(basic_streambuf<charT, traits>* sb);
|
| 1161 |
```
|
| 1162 |
|
| 1163 |
-
*
|
| 1164 |
-
|
| 1165 |
|
| 1166 |
-
**Table: `basic_ios::init()` effects** <a id="
|
| 1167 |
|
| 1168 |
| Element | Value |
|
| 1169 |
| -------------- | ------------------------------------------------------------ |
|
| 1170 |
| `rdbuf()` | `sb` |
|
| 1171 |
| `tie()` | `0` |
|
|
@@ -1191,15 +1202,15 @@ sequence controlled by the stream buffer.
|
|
| 1191 |
|
| 1192 |
``` cpp
|
| 1193 |
basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
|
| 1194 |
```
|
| 1195 |
|
| 1196 |
-
*
|
| 1197 |
traversing the linked list of tied stream objects starting from
|
| 1198 |
`tiestr->tie()`.
|
| 1199 |
|
| 1200 |
-
*
|
| 1201 |
|
| 1202 |
*Returns:* The previous value of `tie()`.
|
| 1203 |
|
| 1204 |
``` cpp
|
| 1205 |
basic_streambuf<charT, traits>* rdbuf() const;
|
|
@@ -1209,22 +1220,22 @@ basic_streambuf<charT, traits>* rdbuf() const;
|
|
| 1209 |
|
| 1210 |
``` cpp
|
| 1211 |
basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
|
| 1212 |
```
|
| 1213 |
|
| 1214 |
-
*Postconditions:* `sb == rdbuf()`.
|
| 1215 |
-
|
| 1216 |
*Effects:* Calls `clear()`.
|
| 1217 |
|
|
|
|
|
|
|
| 1218 |
*Returns:* The previous value of `rdbuf()`.
|
| 1219 |
|
| 1220 |
``` cpp
|
| 1221 |
locale imbue(const locale& loc);
|
| 1222 |
```
|
| 1223 |
|
| 1224 |
-
*Effects:* Calls `ios_base::imbue(loc)`
|
| 1225 |
-
`rdbuf() != 0` then `rdbuf()->pubimbue(loc)`
|
| 1226 |
|
| 1227 |
*Returns:* The prior value of `ios_base::imbue()`.
|
| 1228 |
|
| 1229 |
``` cpp
|
| 1230 |
char narrow(char_type c, char dfault) const;
|
|
@@ -1247,45 +1258,45 @@ specified field width.
|
|
| 1247 |
|
| 1248 |
``` cpp
|
| 1249 |
char_type fill(char_type fillch);
|
| 1250 |
```
|
| 1251 |
|
| 1252 |
-
*
|
| 1253 |
|
| 1254 |
*Returns:* The previous value of `fill()`.
|
| 1255 |
|
| 1256 |
``` cpp
|
| 1257 |
basic_ios& copyfmt(const basic_ios& rhs);
|
| 1258 |
```
|
| 1259 |
|
| 1260 |
-
*Effects:* If `(this ==
|
| 1261 |
-
|
| 1262 |
-
follows:
|
| 1263 |
|
| 1264 |
-
|
| 1265 |
-
|
| 1266 |
-
|
| 1267 |
-
|
| 1268 |
- `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
|
| 1269 |
-
|
| 1270 |
-
|
| 1271 |
- if any newly stored pointer values in `*this` point at objects
|
| 1272 |
-
|
| 1273 |
-
|
| 1274 |
-
|
| 1275 |
-
|
| 1276 |
-
|
| 1277 |
-
|
| 1278 |
|
| 1279 |
[*Note 1*: The second pass through the callback pairs permits a copied
|
| 1280 |
`pword` value to be zeroed, or to have its referent deep copied or
|
| 1281 |
reference counted, or to have other special action taken. — *end note*]
|
| 1282 |
|
| 1283 |
-
*
|
| 1284 |
-
|
| 1285 |
|
| 1286 |
-
**Table: `basic_ios::copyfmt()` effects** <a id="
|
| 1287 |
|
| 1288 |
| Element | Value |
|
| 1289 |
| -------------- | ------------------ |
|
| 1290 |
| `rdbuf()` | unchanged |
|
| 1291 |
| `tie()` | `rhs.tie()` |
|
|
@@ -1303,39 +1314,38 @@ Table [[tab:iostreams.copyfmt.effects]].
|
|
| 1303 |
``` cpp
|
| 1304 |
void move(basic_ios& rhs);
|
| 1305 |
void move(basic_ios&& rhs);
|
| 1306 |
```
|
| 1307 |
|
| 1308 |
-
*
|
| 1309 |
-
|
| 1310 |
-
|
| 1311 |
-
|
| 1312 |
-
shall return 0.
|
| 1313 |
|
| 1314 |
``` cpp
|
| 1315 |
void swap(basic_ios& rhs) noexcept;
|
| 1316 |
```
|
| 1317 |
|
| 1318 |
-
*Effects:* The states of `*this` and `rhs`
|
| 1319 |
-
|
| 1320 |
-
|
| 1321 |
-
|
| 1322 |
|
| 1323 |
``` cpp
|
| 1324 |
void set_rdbuf(basic_streambuf<charT, traits>* sb);
|
| 1325 |
```
|
| 1326 |
|
| 1327 |
-
*
|
| 1328 |
|
| 1329 |
*Effects:* Associates the `basic_streambuf` object pointed to by `sb`
|
| 1330 |
with this stream without calling `clear()`.
|
| 1331 |
|
| 1332 |
-
*
|
| 1333 |
|
| 1334 |
*Throws:* Nothing.
|
| 1335 |
|
| 1336 |
-
####
|
| 1337 |
|
| 1338 |
``` cpp
|
| 1339 |
explicit operator bool() const;
|
| 1340 |
```
|
| 1341 |
|
|
@@ -1355,25 +1365,25 @@ iostate rdstate() const;
|
|
| 1355 |
|
| 1356 |
``` cpp
|
| 1357 |
void clear(iostate state = goodbit);
|
| 1358 |
```
|
| 1359 |
|
| 1360 |
-
*
|
| 1361 |
`rdstate() == (state | ios_base::badbit)`.
|
| 1362 |
|
| 1363 |
*Effects:* If
|
| 1364 |
`((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
|
| 1365 |
-
Otherwise, the function throws an object of class
|
| 1366 |
-
|
| 1367 |
-
|
| 1368 |
|
| 1369 |
``` cpp
|
| 1370 |
void setstate(iostate state);
|
| 1371 |
```
|
| 1372 |
|
| 1373 |
*Effects:* Calls `clear(rdstate() | state)` (which may throw
|
| 1374 |
-
`
|
| 1375 |
|
| 1376 |
``` cpp
|
| 1377 |
bool good() const;
|
| 1378 |
```
|
| 1379 |
|
|
@@ -1406,18 +1416,21 @@ exceptions to be thrown.
|
|
| 1406 |
|
| 1407 |
``` cpp
|
| 1408 |
void exceptions(iostate except);
|
| 1409 |
```
|
| 1410 |
|
| 1411 |
-
*
|
| 1412 |
|
| 1413 |
*Effects:* Calls `clear(rdstate())`.
|
| 1414 |
|
| 1415 |
### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
|
| 1416 |
|
| 1417 |
#### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
|
| 1418 |
|
|
|
|
|
|
|
|
|
|
| 1419 |
``` cpp
|
| 1420 |
ios_base& boolalpha(ios_base& str);
|
| 1421 |
```
|
| 1422 |
|
| 1423 |
*Effects:* Calls `str.setf(ios_base::boolalpha)`.
|
|
@@ -1528,10 +1541,13 @@ ios_base& nounitbuf(ios_base& str);
|
|
| 1528 |
|
| 1529 |
*Returns:* `str`.
|
| 1530 |
|
| 1531 |
#### `adjustfield` manipulators <a id="adjustfield.manip">[[adjustfield.manip]]</a>
|
| 1532 |
|
|
|
|
|
|
|
|
|
|
| 1533 |
``` cpp
|
| 1534 |
ios_base& internal(ios_base& str);
|
| 1535 |
```
|
| 1536 |
|
| 1537 |
*Effects:* Calls `str.setf(ios_base::internal, ios_base::adjustfield)`.
|
|
@@ -1554,10 +1570,13 @@ ios_base& right(ios_base& str);
|
|
| 1554 |
|
| 1555 |
*Returns:* `str`.
|
| 1556 |
|
| 1557 |
#### `basefield` manipulators <a id="basefield.manip">[[basefield.manip]]</a>
|
| 1558 |
|
|
|
|
|
|
|
|
|
|
| 1559 |
``` cpp
|
| 1560 |
ios_base& dec(ios_base& str);
|
| 1561 |
```
|
| 1562 |
|
| 1563 |
*Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
|
|
@@ -1580,10 +1599,13 @@ ios_base& oct(ios_base& str);
|
|
| 1580 |
|
| 1581 |
*Returns:* `str`.
|
| 1582 |
|
| 1583 |
#### `floatfield` manipulators <a id="floatfield.manip">[[floatfield.manip]]</a>
|
| 1584 |
|
|
|
|
|
|
|
|
|
|
| 1585 |
``` cpp
|
| 1586 |
ios_base& fixed(ios_base& str);
|
| 1587 |
```
|
| 1588 |
|
| 1589 |
*Effects:* Calls `str.setf(ios_base::fixed, ios_base::floatfield)`.
|
|
@@ -1607,22 +1629,22 @@ ios_base& hexfloat(ios_base& str);
|
|
| 1607 |
|
| 1608 |
*Returns:* `str`.
|
| 1609 |
|
| 1610 |
[*Note 1*: The more obvious use of `ios_base::hex` to specify
|
| 1611 |
hexadecimal floating-point format would change the meaning of existing
|
| 1612 |
-
well
|
| 1613 |
`fixed` and `scientific`. — *end note*]
|
| 1614 |
|
| 1615 |
``` cpp
|
| 1616 |
ios_base& defaultfloat(ios_base& str);
|
| 1617 |
```
|
| 1618 |
|
| 1619 |
*Effects:* Calls `str.unsetf(ios_base::floatfield)`.
|
| 1620 |
|
| 1621 |
*Returns:* `str`.
|
| 1622 |
|
| 1623 |
-
###
|
| 1624 |
|
| 1625 |
``` cpp
|
| 1626 |
error_code make_error_code(io_errc e) noexcept;
|
| 1627 |
```
|
| 1628 |
|
|
@@ -1740,11 +1762,11 @@ namespace std {
|
|
| 1740 |
pos_type pubseekpos(pos_type sp,
|
| 1741 |
ios_base::openmode which
|
| 1742 |
= ios_base::in | ios_base::out);
|
| 1743 |
int pubsync();
|
| 1744 |
|
| 1745 |
-
//
|
| 1746 |
// [streambuf.pub.get], get area
|
| 1747 |
streamsize in_avail();
|
| 1748 |
int_type snextc();
|
| 1749 |
int_type sbumpc();
|
| 1750 |
int_type sgetc();
|
|
@@ -1814,20 +1836,19 @@ for deriving various *stream buffers* whose objects each control two
|
|
| 1814 |
*character sequences*:
|
| 1815 |
|
| 1816 |
- a character *input sequence*;
|
| 1817 |
- a character *output sequence*.
|
| 1818 |
|
| 1819 |
-
####
|
| 1820 |
|
| 1821 |
``` cpp
|
| 1822 |
basic_streambuf();
|
| 1823 |
```
|
| 1824 |
|
| 1825 |
-
*Effects:*
|
| 1826 |
-
`basic_streambuf<charT, traits>` and initializes:[^13]
|
| 1827 |
|
| 1828 |
-
- all
|
| 1829 |
- the `getloc()` member to a copy the global locale, `locale()`, at the
|
| 1830 |
time of construction.
|
| 1831 |
|
| 1832 |
*Remarks:* Once the `getloc()` member is initialized, results of calling
|
| 1833 |
locale member functions, and of members of facets so obtained, can
|
|
@@ -1835,13 +1856,11 @@ safely be cached until the next time the member `imbue` is called.
|
|
| 1835 |
|
| 1836 |
``` cpp
|
| 1837 |
basic_streambuf(const basic_streambuf& rhs);
|
| 1838 |
```
|
| 1839 |
|
| 1840 |
-
*
|
| 1841 |
-
|
| 1842 |
-
*Postconditions:*
|
| 1843 |
|
| 1844 |
- `eback() == rhs.eback()`
|
| 1845 |
- `gptr() == rhs.gptr()`
|
| 1846 |
- `egptr() == rhs.egptr()`
|
| 1847 |
- `pbase() == rhs.pbase()`
|
|
@@ -1853,22 +1872,22 @@ basic_streambuf(const basic_streambuf& rhs);
|
|
| 1853 |
~basic_streambuf();
|
| 1854 |
```
|
| 1855 |
|
| 1856 |
*Effects:* None.
|
| 1857 |
|
| 1858 |
-
####
|
| 1859 |
|
| 1860 |
##### Locales <a id="streambuf.locales">[[streambuf.locales]]</a>
|
| 1861 |
|
| 1862 |
``` cpp
|
| 1863 |
locale pubimbue(const locale& loc);
|
| 1864 |
```
|
| 1865 |
|
| 1866 |
-
*Postconditions:* `loc == getloc()`.
|
| 1867 |
-
|
| 1868 |
*Effects:* Calls `imbue(loc)`.
|
| 1869 |
|
|
|
|
|
|
|
| 1870 |
*Returns:* Previous value of `getloc()`.
|
| 1871 |
|
| 1872 |
``` cpp
|
| 1873 |
locale getloc() const;
|
| 1874 |
```
|
|
@@ -1914,11 +1933,11 @@ int pubsync();
|
|
| 1914 |
``` cpp
|
| 1915 |
streamsize in_avail();
|
| 1916 |
```
|
| 1917 |
|
| 1918 |
*Returns:* If a read position is available, returns `egptr() - gptr()`.
|
| 1919 |
-
Otherwise returns `showmanyc()`
|
| 1920 |
|
| 1921 |
``` cpp
|
| 1922 |
int_type snextc();
|
| 1923 |
```
|
| 1924 |
|
|
@@ -1929,11 +1948,11 @@ int_type snextc();
|
|
| 1929 |
|
| 1930 |
``` cpp
|
| 1931 |
int_type sbumpc();
|
| 1932 |
```
|
| 1933 |
|
| 1934 |
-
*
|
| 1935 |
`uflow()`. Otherwise, returns `traits::to_int_type(*gptr())` and
|
| 1936 |
increments the next pointer for the input sequence.
|
| 1937 |
|
| 1938 |
``` cpp
|
| 1939 |
int_type sgetc();
|
|
@@ -1952,52 +1971,50 @@ streamsize sgetn(char_type* s, streamsize n);
|
|
| 1952 |
|
| 1953 |
``` cpp
|
| 1954 |
int_type sputbackc(char_type c);
|
| 1955 |
```
|
| 1956 |
|
| 1957 |
-
*
|
| 1958 |
if `traits::eq(c, gptr()[-1])` is `false`, returns
|
| 1959 |
`pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
|
| 1960 |
pointer for the input sequence and returns
|
| 1961 |
`traits::to_int_type(*gptr())`.
|
| 1962 |
|
| 1963 |
``` cpp
|
| 1964 |
int_type sungetc();
|
| 1965 |
```
|
| 1966 |
|
| 1967 |
-
*
|
| 1968 |
returns `pbackfail()`. Otherwise, decrements the next pointer for the
|
| 1969 |
input sequence and returns `traits::to_int_type(*gptr())`.
|
| 1970 |
|
| 1971 |
##### Put area <a id="streambuf.pub.put">[[streambuf.pub.put]]</a>
|
| 1972 |
|
| 1973 |
``` cpp
|
| 1974 |
int_type sputc(char_type c);
|
| 1975 |
```
|
| 1976 |
|
| 1977 |
-
*
|
| 1978 |
returns `overflow(traits::to_int_type(c))`. Otherwise, stores `c` at the
|
| 1979 |
next pointer for the output sequence, increments the pointer, and
|
| 1980 |
returns `traits::to_int_type(c)`.
|
| 1981 |
|
| 1982 |
``` cpp
|
| 1983 |
streamsize sputn(const char_type* s, streamsize n);
|
| 1984 |
```
|
| 1985 |
|
| 1986 |
*Returns:* `xsputn(s, n)`.
|
| 1987 |
|
| 1988 |
-
####
|
| 1989 |
|
| 1990 |
##### Assignment <a id="streambuf.assign">[[streambuf.assign]]</a>
|
| 1991 |
|
| 1992 |
``` cpp
|
| 1993 |
basic_streambuf& operator=(const basic_streambuf& rhs);
|
| 1994 |
```
|
| 1995 |
|
| 1996 |
-
*
|
| 1997 |
-
|
| 1998 |
-
*Postconditions:*
|
| 1999 |
|
| 2000 |
- `eback() == rhs.eback()`
|
| 2001 |
- `gptr() == rhs.gptr()`
|
| 2002 |
- `egptr() == rhs.egptr()`
|
| 2003 |
- `pbase() == rhs.pbase()`
|
|
@@ -2041,12 +2058,12 @@ void gbump(int n);
|
|
| 2041 |
|
| 2042 |
``` cpp
|
| 2043 |
void setg(char_type* gbeg, char_type* gnext, char_type* gend);
|
| 2044 |
```
|
| 2045 |
|
| 2046 |
-
*
|
| 2047 |
-
|
| 2048 |
|
| 2049 |
##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
|
| 2050 |
|
| 2051 |
``` cpp
|
| 2052 |
char_type* pbase() const;
|
|
@@ -2074,14 +2091,14 @@ void pbump(int n);
|
|
| 2074 |
|
| 2075 |
``` cpp
|
| 2076 |
void setp(char_type* pbeg, char_type* pend);
|
| 2077 |
```
|
| 2078 |
|
| 2079 |
-
*
|
| 2080 |
-
|
| 2081 |
|
| 2082 |
-
####
|
| 2083 |
|
| 2084 |
##### Locales <a id="streambuf.virt.locales">[[streambuf.virt.locales]]</a>
|
| 2085 |
|
| 2086 |
``` cpp
|
| 2087 |
void imbue(const locale&);
|
|
@@ -2142,11 +2159,11 @@ int sync();
|
|
| 2142 |
is, if `pbase()` is non-null the characters between `pbase()` and
|
| 2143 |
`pptr()` are written to the controlled sequence. The pointers may then
|
| 2144 |
be reset as appropriate.
|
| 2145 |
|
| 2146 |
*Returns:* `-1` on failure. What constitutes failure is determined by
|
| 2147 |
-
each derived class
|
| 2148 |
|
| 2149 |
*Default behavior:* Returns zero.
|
| 2150 |
|
| 2151 |
##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
|
| 2152 |
|
|
@@ -2183,11 +2200,11 @@ to `sbumpc()` would return `traits::eof()`.
|
|
| 2183 |
``` cpp
|
| 2184 |
int_type underflow();
|
| 2185 |
```
|
| 2186 |
|
| 2187 |
*Remarks:* The public members of `basic_streambuf` call this virtual
|
| 2188 |
-
function only if `gptr()` is null or `gptr() >= egptr()`
|
| 2189 |
|
| 2190 |
*Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
|
| 2191 |
of the *pending sequence*, without moving the input sequence position
|
| 2192 |
past it. If the pending sequence is null then the function returns
|
| 2193 |
`traits::eof()` to indicate failure.
|
|
@@ -2225,13 +2242,13 @@ that either
|
|
| 2225 |
|
| 2226 |
``` cpp
|
| 2227 |
int_type uflow();
|
| 2228 |
```
|
| 2229 |
|
| 2230 |
-
*
|
| 2231 |
-
that the result character
|
| 2232 |
-
to the backup sequence, and the pending sequence
|
| 2233 |
before the transfer.
|
| 2234 |
|
| 2235 |
*Default behavior:* Calls `underflow()`. If `underflow()` returns
|
| 2236 |
`traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
|
| 2237 |
of `traits::to_int_type(*gptr())` and increment the value of the next
|
|
@@ -2258,11 +2275,11 @@ modifications that
|
|
| 2258 |
is determined.
|
| 2259 |
- If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
|
| 2260 |
is prepended. Whether the input sequence is backed up or modified in
|
| 2261 |
any other way is unspecified.
|
| 2262 |
|
| 2263 |
-
*
|
| 2264 |
`pptr()` are the same as for `underflow()`.
|
| 2265 |
|
| 2266 |
*Returns:* `traits::eof()` to indicate failure. Failure may occur
|
| 2267 |
because the input sequence could not be backed up, or if for some other
|
| 2268 |
reason the pointers could not be set consistent with the constraints.
|
|
@@ -2294,32 +2311,32 @@ int_type overflow(int_type c = traits::eof());
|
|
| 2294 |
|
| 2295 |
*Effects:* Consumes some initial subsequence of the characters of the
|
| 2296 |
*pending sequence*. The pending sequence is defined as the concatenation
|
| 2297 |
of
|
| 2298 |
|
| 2299 |
-
- the empty sequence if `pbase()` is
|
| 2300 |
`pptr() - pbase()` characters beginning at `pbase()`, followed by
|
| 2301 |
- the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
|
| 2302 |
`true`, otherwise the sequence consisting of `c`.
|
| 2303 |
|
| 2304 |
*Remarks:* The member functions `sputc()` and `sputn()` call this
|
| 2305 |
function in case that no room can be found in the put buffer enough to
|
| 2306 |
accommodate the argument character sequence.
|
| 2307 |
|
| 2308 |
-
*
|
| 2309 |
-
|
| 2310 |
|
| 2311 |
-
|
| 2312 |
-
|
| 2313 |
-
|
| 2314 |
-
|
| 2315 |
-
|
| 2316 |
`pbase()` are the associated output stream. In case `r` is zero (all
|
| 2317 |
characters of the pending sequence have been consumed) then either
|
| 2318 |
-
|
| 2319 |
-
|
| 2320 |
-
|
| 2321 |
associated output stream fails or if it is unable to establish
|
| 2322 |
`pbase()` and `pptr()` according to the above rules.
|
| 2323 |
|
| 2324 |
*Returns:* `traits::eof()` or throws an exception if the function fails.
|
| 2325 |
|
|
@@ -2369,10 +2386,17 @@ namespace std {
|
|
| 2369 |
template<class charT, class traits>
|
| 2370 |
basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
|
| 2371 |
template<class charT, class traits>
|
| 2372 |
basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
|
| 2373 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2374 |
template<class charT, class traits, class T>
|
| 2375 |
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
|
| 2376 |
}
|
| 2377 |
```
|
| 2378 |
|
|
@@ -2382,11 +2406,11 @@ namespace std {
|
|
| 2382 |
namespace std {
|
| 2383 |
// types T1, T2, ... are unspecified implementation types
|
| 2384 |
T1 resetiosflags(ios_base::fmtflags mask);
|
| 2385 |
T2 setiosflags (ios_base::fmtflags mask);
|
| 2386 |
T3 setbase(int base);
|
| 2387 |
-
template<charT> T4 setfill(charT c);
|
| 2388 |
T5 setprecision(int n);
|
| 2389 |
T6 setw(int n);
|
| 2390 |
template<class moneyT> T7 get_money(moneyT& mon, bool intl = false);
|
| 2391 |
template<class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
|
| 2392 |
template<class charT> T9 get_time(struct tm* tmb, const charT* fmt);
|
|
@@ -2420,22 +2444,22 @@ extracts from stream rvalues.
|
|
| 2420 |
``` cpp
|
| 2421 |
namespace std {
|
| 2422 |
template<class charT, class traits = char_traits<charT>>
|
| 2423 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 2424 |
public:
|
| 2425 |
-
// types (inherited from basic_ios
|
| 2426 |
using char_type = charT;
|
| 2427 |
using int_type = typename traits::int_type;
|
| 2428 |
using pos_type = typename traits::pos_type;
|
| 2429 |
using off_type = typename traits::off_type;
|
| 2430 |
using traits_type = traits;
|
| 2431 |
|
| 2432 |
// [istream.cons], constructor/destructor
|
| 2433 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2434 |
virtual ~basic_istream();
|
| 2435 |
|
| 2436 |
-
// [istream
|
| 2437 |
class sentry;
|
| 2438 |
|
| 2439 |
// [istream.formatted], formatted input
|
| 2440 |
basic_istream<charT, traits>&
|
| 2441 |
operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
|
|
@@ -2485,15 +2509,15 @@ namespace std {
|
|
| 2485 |
basic_istream<charT, traits>& seekg(pos_type);
|
| 2486 |
basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
|
| 2487 |
|
| 2488 |
protected:
|
| 2489 |
// [istream.cons], copy/move constructor
|
| 2490 |
-
basic_istream(const basic_istream&
|
| 2491 |
basic_istream(basic_istream&& rhs);
|
| 2492 |
|
| 2493 |
// [istream.assign], assign and swap
|
| 2494 |
-
basic_istream& operator=(const basic_istream&
|
| 2495 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2496 |
void swap(basic_istream& rhs);
|
| 2497 |
};
|
| 2498 |
|
| 2499 |
// [istream.extractors], character extraction templates
|
|
@@ -2502,16 +2526,16 @@ namespace std {
|
|
| 2502 |
template<class traits>
|
| 2503 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char&);
|
| 2504 |
template<class traits>
|
| 2505 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char&);
|
| 2506 |
|
| 2507 |
-
template<class charT, class traits>
|
| 2508 |
-
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT
|
| 2509 |
-
template<class traits>
|
| 2510 |
-
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char
|
| 2511 |
-
template<class traits>
|
| 2512 |
-
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char
|
| 2513 |
}
|
| 2514 |
```
|
| 2515 |
|
| 2516 |
The class template `basic_istream` defines a number of member function
|
| 2517 |
signatures that assist in reading and interpreting input from sequences
|
|
@@ -2524,72 +2548,67 @@ obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
|
|
| 2524 |
or `rdbuf()->sgetc()`. They may use other public members of `istream`.
|
| 2525 |
|
| 2526 |
If `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`,
|
| 2527 |
then the input function, except as explicitly noted otherwise, completes
|
| 2528 |
its actions and does `setstate(eofbit)`, which may throw
|
| 2529 |
-
`ios_base::failure`
|
| 2530 |
|
| 2531 |
If one of these called functions throws an exception, then unless
|
| 2532 |
-
explicitly noted otherwise, the input function sets `badbit` in
|
| 2533 |
-
state. If `badbit` is
|
| 2534 |
-
the exception without completing its actions, otherwise it does
|
| 2535 |
-
throw anything and proceeds as if the called function had returned a
|
| 2536 |
failure indication.
|
| 2537 |
|
| 2538 |
-
#####
|
| 2539 |
|
| 2540 |
``` cpp
|
| 2541 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2542 |
```
|
| 2543 |
|
| 2544 |
-
*Effects:*
|
| 2545 |
-
|
| 2546 |
-
`basic_ios::init(sb)` ([[basic.ios.cons]]).
|
| 2547 |
|
| 2548 |
-
*
|
| 2549 |
|
| 2550 |
``` cpp
|
| 2551 |
basic_istream(basic_istream&& rhs);
|
| 2552 |
```
|
| 2553 |
|
| 2554 |
-
*Effects:*
|
| 2555 |
-
|
| 2556 |
-
|
| 2557 |
-
base class, and setting the `gcount()` for `rhs` to 0.
|
| 2558 |
|
| 2559 |
``` cpp
|
| 2560 |
virtual ~basic_istream();
|
| 2561 |
```
|
| 2562 |
|
| 2563 |
-
*Effects:* Destroys an object of class `basic_istream`.
|
| 2564 |
-
|
| 2565 |
*Remarks:* Does not perform any operations of `rdbuf()`.
|
| 2566 |
|
| 2567 |
-
#####
|
| 2568 |
|
| 2569 |
``` cpp
|
| 2570 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2571 |
```
|
| 2572 |
|
| 2573 |
-
*Effects:*
|
| 2574 |
|
| 2575 |
*Returns:* `*this`.
|
| 2576 |
|
| 2577 |
``` cpp
|
| 2578 |
void swap(basic_istream& rhs);
|
| 2579 |
```
|
| 2580 |
|
| 2581 |
*Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`. Exchanges the
|
| 2582 |
values returned by `gcount()` and `rhs.gcount()`.
|
| 2583 |
|
| 2584 |
-
##### Class `basic_istream::sentry` <a id="istream
|
| 2585 |
|
| 2586 |
``` cpp
|
| 2587 |
namespace std {
|
| 2588 |
template<class charT, class traits = char_traits<charT>>
|
| 2589 |
class basic_istream<charT, traits>::sentry {
|
| 2590 |
-
using traits_type = traits;
|
| 2591 |
bool ok_; // exposition only
|
| 2592 |
public:
|
| 2593 |
explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
|
| 2594 |
~sentry();
|
| 2595 |
explicit operator bool() const { return ok_; }
|
|
@@ -2640,11 +2659,11 @@ if (ctype.is(ctype.space, c) != 0)
|
|
| 2640 |
```
|
| 2641 |
|
| 2642 |
If, after any preparation is completed, `is.good()` is `true`,
|
| 2643 |
`ok_ != false` otherwise, `ok_ == false`. During preparation, the
|
| 2644 |
constructor may call `setstate(failbit)` (which may throw
|
| 2645 |
-
`ios_base::failure`
|
| 2646 |
|
| 2647 |
``` cpp
|
| 2648 |
~sentry();
|
| 2649 |
```
|
| 2650 |
|
|
@@ -2652,23 +2671,23 @@ constructor may call `setstate(failbit)` (which may throw
|
|
| 2652 |
|
| 2653 |
``` cpp
|
| 2654 |
explicit operator bool() const;
|
| 2655 |
```
|
| 2656 |
|
| 2657 |
-
*
|
| 2658 |
|
| 2659 |
#### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
|
| 2660 |
|
| 2661 |
##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
|
| 2662 |
|
| 2663 |
Each formatted input function begins execution by constructing an object
|
| 2664 |
of class `sentry` with the `noskipws` (second) argument `false`. If the
|
| 2665 |
`sentry` object returns `true`, when converted to a value of type
|
| 2666 |
`bool`, the function endeavors to obtain the requested input. If an
|
| 2667 |
-
exception is thrown during input then `
|
| 2668 |
-
`*this`’s error state. If `(exceptions()&badbit) != 0` then
|
| 2669 |
-
exception is rethrown. In any case, the formatted input function
|
| 2670 |
destroys the `sentry` object. If no exception has been thrown, it
|
| 2671 |
returns `*this`.
|
| 2672 |
|
| 2673 |
##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
|
| 2674 |
|
|
@@ -2685,11 +2704,11 @@ operator>>(long double& val);
|
|
| 2685 |
operator>>(bool& val);
|
| 2686 |
operator>>(void*& val);
|
| 2687 |
```
|
| 2688 |
|
| 2689 |
As in the case of the inserters, these extractors depend on the locale’s
|
| 2690 |
-
`num_get<>`
|
| 2691 |
stream data. These extractors behave as formatted input functions (as
|
| 2692 |
described in [[istream.formatted.reqmts]]). After a sentry object is
|
| 2693 |
constructed, the conversion occurs as if performed by the following code
|
| 2694 |
fragment:
|
| 2695 |
|
|
@@ -2789,26 +2808,23 @@ formatted input function (as described
|
|
| 2789 |
in [[istream.formatted.reqmts]]).
|
| 2790 |
|
| 2791 |
*Returns:* `*this`.
|
| 2792 |
|
| 2793 |
``` cpp
|
| 2794 |
-
template<class charT, class traits>
|
| 2795 |
-
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT
|
| 2796 |
-
template<class traits>
|
| 2797 |
-
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char
|
| 2798 |
-
template<class traits>
|
| 2799 |
-
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char
|
| 2800 |
```
|
| 2801 |
|
| 2802 |
*Effects:* Behaves like a formatted input member (as described
|
| 2803 |
in [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
|
| 2804 |
-
constructed, `operator>>` extracts characters and stores them into
|
| 2805 |
-
|
| 2806 |
-
`
|
| 2807 |
-
is the number of elements of the largest array of `char_type` that can
|
| 2808 |
-
store a terminating `charT()`. `n` is the maximum number of characters
|
| 2809 |
-
stored.
|
| 2810 |
|
| 2811 |
Characters are extracted and stored until any of the following occurs:
|
| 2812 |
|
| 2813 |
- `n-1` characters are stored;
|
| 2814 |
- end of file occurs on the input sequence;
|
|
@@ -2818,11 +2834,11 @@ Characters are extracted and stored until any of the following occurs:
|
|
| 2818 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 2819 |
which may be the first position if no characters were extracted.
|
| 2820 |
`operator>>` then calls `width(0)`.
|
| 2821 |
|
| 2822 |
If the function extracted no characters, it calls `setstate(failbit)`,
|
| 2823 |
-
which may throw `ios_base::failure`
|
| 2824 |
|
| 2825 |
*Returns:* `in`.
|
| 2826 |
|
| 2827 |
``` cpp
|
| 2828 |
template<class charT, class traits>
|
|
@@ -2842,28 +2858,28 @@ stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
|
|
| 2842 |
|
| 2843 |
``` cpp
|
| 2844 |
basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
|
| 2845 |
```
|
| 2846 |
|
| 2847 |
-
*Effects:* Behaves as an unformatted input
|
| 2848 |
-
|
| 2849 |
-
which may throw `ios_base::failure`
|
| 2850 |
-
object is constructed, extracts
|
| 2851 |
-
|
| 2852 |
-
inserted until any of
|
|
|
|
| 2853 |
|
| 2854 |
- end-of-file occurs on the input sequence;
|
| 2855 |
- inserting in the output sequence fails (in which case the character to
|
| 2856 |
be inserted is not extracted);
|
| 2857 |
- an exception occurs (in which case the exception is caught).
|
| 2858 |
|
| 2859 |
If the function inserts no characters, it calls `setstate(failbit)`,
|
| 2860 |
-
which may throw `ios_base::failure`
|
| 2861 |
-
|
| 2862 |
-
characters from `*this` and `failbit` is
|
| 2863 |
-
|
| 2864 |
-
rethrown.
|
| 2865 |
|
| 2866 |
*Returns:* `*this`.
|
| 2867 |
|
| 2868 |
#### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
|
| 2869 |
|
|
@@ -2876,14 +2892,14 @@ an exception or if the sentry object returns `false`, when converted to
|
|
| 2876 |
a value of type `bool`, the function returns without attempting to
|
| 2877 |
obtain any input. In either case the number of extracted characters is
|
| 2878 |
set to 0; unformatted input functions taking a character array of
|
| 2879 |
nonzero size as an argument shall also store a null character (using
|
| 2880 |
`charT()`) in the first location of the array. If an exception is thrown
|
| 2881 |
-
during input then `
|
| 2882 |
-
state. (Exceptions thrown from `basic_ios<>::clear()` are not
|
| 2883 |
-
rethrown.) If `(exceptions()&badbit) != 0` then the exception
|
| 2884 |
-
rethrown. It also counts the number of characters extracted. If no
|
| 2885 |
exception has been thrown it ends by storing the count in a member
|
| 2886 |
object and returning the value specified. In any event the `sentry`
|
| 2887 |
object is destroyed before leaving the unformatted input function.
|
| 2888 |
|
| 2889 |
``` cpp
|
|
@@ -2901,23 +2917,23 @@ int_type get();
|
|
| 2901 |
```
|
| 2902 |
|
| 2903 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2904 |
above). After constructing a sentry object, extracts a character `c`, if
|
| 2905 |
one is available. Otherwise, the function calls `setstate(failbit)`,
|
| 2906 |
-
which may throw `ios_base::failure`
|
| 2907 |
|
| 2908 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 2909 |
|
| 2910 |
``` cpp
|
| 2911 |
basic_istream<charT, traits>& get(char_type& c);
|
| 2912 |
```
|
| 2913 |
|
| 2914 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2915 |
above). After constructing a sentry object, extracts a character, if one
|
| 2916 |
is available, and assigns it to `c`.[^24] Otherwise, the function calls
|
| 2917 |
-
`setstate(failbit)` (which may throw
|
| 2918 |
-
|
| 2919 |
|
| 2920 |
*Returns:* `*this`.
|
| 2921 |
|
| 2922 |
``` cpp
|
| 2923 |
basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
|
|
@@ -2934,13 +2950,13 @@ the following occurs:
|
|
| 2934 |
calls `setstate(eofbit)`);
|
| 2935 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 2936 |
which case `c` is not extracted).
|
| 2937 |
|
| 2938 |
If the function stores no characters, it calls `setstate(failbit)`
|
| 2939 |
-
(which may throw `ios_base::failure`
|
| 2940 |
-
|
| 2941 |
-
|
| 2942 |
|
| 2943 |
*Returns:* `*this`.
|
| 2944 |
|
| 2945 |
``` cpp
|
| 2946 |
basic_istream<charT, traits>& get(char_type* s, streamsize n);
|
|
@@ -2966,11 +2982,11 @@ extracted and inserted until any of the following occurs:
|
|
| 2966 |
which case `c` is not extracted);
|
| 2967 |
- an exception occurs (in which case, the exception is caught but not
|
| 2968 |
rethrown).
|
| 2969 |
|
| 2970 |
If the function inserts no characters, it calls `setstate(failbit)`,
|
| 2971 |
-
which may throw `ios_base::failure`
|
| 2972 |
|
| 2973 |
*Returns:* `*this`.
|
| 2974 |
|
| 2975 |
``` cpp
|
| 2976 |
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
|
|
@@ -2999,11 +3015,11 @@ the following occurs:
|
|
| 2999 |
the function calls `setstate(failbit)`).
|
| 3000 |
|
| 3001 |
These conditions are tested in the order shown.[^28]
|
| 3002 |
|
| 3003 |
If the function extracts no characters, it calls `setstate(failbit)`
|
| 3004 |
-
(which may throw `ios_base::failure`
|
| 3005 |
|
| 3006 |
In any case, if `n` is greater than zero, it then stores a null
|
| 3007 |
character (using `charT()`) into the next successive location of the
|
| 3008 |
array.
|
| 3009 |
|
|
@@ -3051,15 +3067,15 @@ basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::
|
|
| 3051 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3052 |
above). After constructing a sentry object, extracts characters and
|
| 3053 |
discards them. Characters are extracted until any of the following
|
| 3054 |
occurs:
|
| 3055 |
|
| 3056 |
-
- `n != numeric_limits<streamsize>::max()`
|
| 3057 |
characters have been extracted so far
|
| 3058 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3059 |
-
calls `setstate(eofbit)`, which may throw
|
| 3060 |
-
|
| 3061 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
| 3062 |
available input character `c` (in which case `c` is extracted).
|
| 3063 |
|
| 3064 |
*Remarks:* The last condition will never occur if
|
| 3065 |
`traits::eq_int_type(delim, traits::eof())`.
|
|
@@ -3089,11 +3105,11 @@ array whose first element is designated by `s`.[^30] Characters are
|
|
| 3089 |
extracted and stored until either of the following occurs:
|
| 3090 |
|
| 3091 |
- `n` characters are stored;
|
| 3092 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3093 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 3094 |
-
`ios_base::failure`
|
| 3095 |
|
| 3096 |
*Returns:* `*this`.
|
| 3097 |
|
| 3098 |
``` cpp
|
| 3099 |
streamsize readsome(char_type* s, streamsize n);
|
|
@@ -3103,11 +3119,11 @@ streamsize readsome(char_type* s, streamsize n);
|
|
| 3103 |
above). After constructing a sentry object, if `!good()` calls
|
| 3104 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3105 |
extracts characters and stores them into successive locations of an
|
| 3106 |
array whose first element is designated by `s`. If
|
| 3107 |
`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
|
| 3108 |
-
`ios_base::failure`
|
| 3109 |
|
| 3110 |
- If `rdbuf()->in_avail() == 0`, extracts no characters
|
| 3111 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 3112 |
|
| 3113 |
*Returns:* The number of characters extracted.
|
|
@@ -3118,13 +3134,13 @@ basic_istream<charT, traits>& putback(char_type c);
|
|
| 3118 |
|
| 3119 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3120 |
above), except that the function first clears `eofbit`. After
|
| 3121 |
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3122 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3123 |
-
calls `rdbuf->sputbackc()`. If `rdbuf()` is null, or if `sputbackc
|
| 3124 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3125 |
-
`ios_base::failure`
|
| 3126 |
|
| 3127 |
[*Note 1*: This function extracts no characters, so the value returned
|
| 3128 |
by the next call to `gcount()` is 0. — *end note*]
|
| 3129 |
|
| 3130 |
*Returns:* `*this`.
|
|
@@ -3135,13 +3151,13 @@ basic_istream<charT, traits>& unget();
|
|
| 3135 |
|
| 3136 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3137 |
above), except that the function first clears `eofbit`. After
|
| 3138 |
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3139 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3140 |
-
calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc
|
| 3141 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3142 |
-
`ios_base::failure`
|
| 3143 |
|
| 3144 |
[*Note 2*: This function extracts no characters, so the value returned
|
| 3145 |
by the next call to `gcount()` is 0. — *end note*]
|
| 3146 |
|
| 3147 |
*Returns:* `*this`.
|
|
@@ -3154,11 +3170,11 @@ int sync();
|
|
| 3154 |
above), except that it does not count the number of characters extracted
|
| 3155 |
and does not affect the value returned by subsequent calls to
|
| 3156 |
`gcount()`. After constructing a sentry object, if `rdbuf()` is a null
|
| 3157 |
pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
|
| 3158 |
that function returns `-1` calls `setstate(badbit)` (which may throw
|
| 3159 |
-
`ios_base::failure`
|
| 3160 |
returns zero.
|
| 3161 |
|
| 3162 |
``` cpp
|
| 3163 |
pos_type tellg();
|
| 3164 |
```
|
|
@@ -3202,45 +3218,49 @@ function calls `setstate(failbit)` (which may throw
|
|
| 3202 |
|
| 3203 |
*Returns:* `*this`.
|
| 3204 |
|
| 3205 |
#### Standard `basic_istream` manipulators <a id="istream.manip">[[istream.manip]]</a>
|
| 3206 |
|
|
|
|
|
|
|
|
|
|
| 3207 |
``` cpp
|
| 3208 |
template<class charT, class traits>
|
| 3209 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 3210 |
```
|
| 3211 |
|
| 3212 |
-
*Effects:* Behaves as an unformatted input
|
| 3213 |
-
|
| 3214 |
-
characters extracted and does not affect the value returned by
|
| 3215 |
-
subsequent calls to is.gcount(). After constructing a sentry object
|
| 3216 |
extracts characters as long as the next available character `c` is
|
| 3217 |
whitespace or until there are no more characters in the sequence.
|
| 3218 |
Whitespace characters are distinguished with the same criterion as used
|
| 3219 |
-
by `sentry::sentry`
|
| 3220 |
characters because there are no more available it sets `eofbit`, but not
|
| 3221 |
`failbit`.
|
| 3222 |
|
| 3223 |
*Returns:* `is`.
|
| 3224 |
|
| 3225 |
#### Rvalue stream extraction <a id="istream.rvalue">[[istream.rvalue]]</a>
|
| 3226 |
|
| 3227 |
``` cpp
|
| 3228 |
-
template
|
| 3229 |
-
|
| 3230 |
```
|
| 3231 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3232 |
*Effects:* Equivalent to:
|
| 3233 |
|
| 3234 |
``` cpp
|
| 3235 |
is >> std::forward<T>(x);
|
| 3236 |
-
return is;
|
| 3237 |
```
|
| 3238 |
|
| 3239 |
-
*Remarks:* This function shall not participate in overload resolution
|
| 3240 |
-
unless the expression `is >> std::forward<T>(x)` is well-formed.
|
| 3241 |
-
|
| 3242 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 3243 |
|
| 3244 |
``` cpp
|
| 3245 |
namespace std {
|
| 3246 |
template<class charT, class traits = char_traits<charT>>
|
|
@@ -3260,62 +3280,59 @@ namespace std {
|
|
| 3260 |
// [iostream.dest], destructor
|
| 3261 |
virtual ~basic_iostream();
|
| 3262 |
|
| 3263 |
protected:
|
| 3264 |
// [iostream.cons], constructor
|
| 3265 |
-
basic_iostream(const basic_iostream&
|
| 3266 |
basic_iostream(basic_iostream&& rhs);
|
| 3267 |
|
| 3268 |
// [iostream.assign], assign and swap
|
| 3269 |
-
basic_iostream& operator=(const basic_iostream&
|
| 3270 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3271 |
void swap(basic_iostream& rhs);
|
| 3272 |
};
|
| 3273 |
}
|
| 3274 |
```
|
| 3275 |
|
| 3276 |
The class template `basic_iostream` inherits a number of functions that
|
| 3277 |
allow reading input and writing output to sequences controlled by a
|
| 3278 |
stream buffer.
|
| 3279 |
|
| 3280 |
-
#####
|
| 3281 |
|
| 3282 |
``` cpp
|
| 3283 |
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
| 3284 |
```
|
| 3285 |
|
| 3286 |
-
*Effects:*
|
| 3287 |
-
|
| 3288 |
-
`
|
| 3289 |
-
`basic_ostream<charT, traits>(sb)` ([[ostream]]).
|
| 3290 |
|
| 3291 |
-
*
|
| 3292 |
|
| 3293 |
``` cpp
|
| 3294 |
basic_iostream(basic_iostream&& rhs);
|
| 3295 |
```
|
| 3296 |
|
| 3297 |
*Effects:* Move constructs from the rvalue `rhs` by constructing the
|
| 3298 |
`basic_istream` base class with `move(rhs)`.
|
| 3299 |
|
| 3300 |
-
#####
|
| 3301 |
|
| 3302 |
``` cpp
|
| 3303 |
virtual ~basic_iostream();
|
| 3304 |
```
|
| 3305 |
|
| 3306 |
-
*Effects:* Destroys an object of class `basic_iostream`.
|
| 3307 |
-
|
| 3308 |
*Remarks:* Does not perform any operations on `rdbuf()`.
|
| 3309 |
|
| 3310 |
-
#####
|
| 3311 |
|
| 3312 |
``` cpp
|
| 3313 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3314 |
```
|
| 3315 |
|
| 3316 |
-
*Effects:*
|
| 3317 |
|
| 3318 |
``` cpp
|
| 3319 |
void swap(basic_iostream& rhs);
|
| 3320 |
```
|
| 3321 |
|
|
@@ -3332,22 +3349,22 @@ that inserts into stream rvalues.
|
|
| 3332 |
``` cpp
|
| 3333 |
namespace std {
|
| 3334 |
template<class charT, class traits = char_traits<charT>>
|
| 3335 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 3336 |
public:
|
| 3337 |
-
// types (inherited from basic_ios
|
| 3338 |
using char_type = charT;
|
| 3339 |
using int_type = typename traits::int_type;
|
| 3340 |
using pos_type = typename traits::pos_type;
|
| 3341 |
using off_type = typename traits::off_type;
|
| 3342 |
using traits_type = traits;
|
| 3343 |
|
| 3344 |
// [ostream.cons], constructor/destructor
|
| 3345 |
explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
|
| 3346 |
virtual ~basic_ostream();
|
| 3347 |
|
| 3348 |
-
// [ostream
|
| 3349 |
class sentry;
|
| 3350 |
|
| 3351 |
// [ostream.formatted], formatted output
|
| 3352 |
basic_ostream<charT, traits>&
|
| 3353 |
operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
|
|
@@ -3384,15 +3401,15 @@ namespace std {
|
|
| 3384 |
basic_ostream<charT, traits>& seekp(pos_type);
|
| 3385 |
basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
|
| 3386 |
|
| 3387 |
protected:
|
| 3388 |
// [ostream.cons], copy/move constructor
|
| 3389 |
-
basic_ostream(const basic_ostream&
|
| 3390 |
basic_ostream(basic_ostream&& rhs);
|
| 3391 |
|
| 3392 |
// [ostream.assign], assign and swap
|
| 3393 |
-
basic_ostream& operator=(const basic_ostream&
|
| 3394 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3395 |
void swap(basic_ostream& rhs);
|
| 3396 |
};
|
| 3397 |
|
| 3398 |
// [ostream.inserters.character], character inserters
|
|
@@ -3406,10 +3423,28 @@ namespace std {
|
|
| 3406 |
template<class traits>
|
| 3407 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, signed char);
|
| 3408 |
template<class traits>
|
| 3409 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, unsigned char);
|
| 3410 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3411 |
template<class charT, class traits>
|
| 3412 |
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const charT*);
|
| 3413 |
template<class charT, class traits>
|
| 3414 |
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const char*);
|
| 3415 |
template<class traits>
|
|
@@ -3417,10 +3452,32 @@ namespace std {
|
|
| 3417 |
|
| 3418 |
template<class traits>
|
| 3419 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const signed char*);
|
| 3420 |
template<class traits>
|
| 3421 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const unsigned char*);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3422 |
}
|
| 3423 |
```
|
| 3424 |
|
| 3425 |
The class template `basic_ostream` defines a number of member function
|
| 3426 |
signatures that assist in formatting and writing output to output
|
|
@@ -3433,26 +3490,29 @@ output functions.* Both groups of output functions generate (or
|
|
| 3433 |
`rdbuf()->sputc(int_type)`. They may use other public members of
|
| 3434 |
`basic_ostream` except that they shall not invoke any virtual members of
|
| 3435 |
`rdbuf()` except `overflow()`, `xsputn()`, and `sync()`.
|
| 3436 |
|
| 3437 |
If one of these called functions throws an exception, then unless
|
| 3438 |
-
explicitly noted otherwise the output function sets `badbit` in
|
| 3439 |
-
state. If `badbit` is
|
| 3440 |
-
the exception without completing its actions, otherwise it does
|
| 3441 |
-
throw anything and
|
|
|
|
| 3442 |
|
| 3443 |
-
|
|
|
|
|
|
|
|
|
|
| 3444 |
|
| 3445 |
``` cpp
|
| 3446 |
explicit basic_ostream(basic_streambuf<charT, traits>* sb);
|
| 3447 |
```
|
| 3448 |
|
| 3449 |
-
*Effects:*
|
| 3450 |
-
|
| 3451 |
-
`basic_ios<charT, traits>::init(sb)` ([[basic.ios.cons]]).
|
| 3452 |
|
| 3453 |
-
*
|
| 3454 |
|
| 3455 |
``` cpp
|
| 3456 |
basic_ostream(basic_ostream&& rhs);
|
| 3457 |
```
|
| 3458 |
|
|
@@ -3462,31 +3522,29 @@ by default constructing the base class and calling
|
|
| 3462 |
|
| 3463 |
``` cpp
|
| 3464 |
virtual ~basic_ostream();
|
| 3465 |
```
|
| 3466 |
|
| 3467 |
-
*Effects:* Destroys an object of class `basic_ostream`.
|
| 3468 |
-
|
| 3469 |
*Remarks:* Does not perform any operations on `rdbuf()`.
|
| 3470 |
|
| 3471 |
-
#####
|
| 3472 |
|
| 3473 |
``` cpp
|
| 3474 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3475 |
```
|
| 3476 |
|
| 3477 |
-
*Effects:*
|
| 3478 |
|
| 3479 |
*Returns:* `*this`.
|
| 3480 |
|
| 3481 |
``` cpp
|
| 3482 |
void swap(basic_ostream& rhs);
|
| 3483 |
```
|
| 3484 |
|
| 3485 |
*Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`.
|
| 3486 |
|
| 3487 |
-
##### Class `basic_ostream::sentry` <a id="ostream
|
| 3488 |
|
| 3489 |
``` cpp
|
| 3490 |
namespace std {
|
| 3491 |
template<class charT, class traits = char_traits<charT>>
|
| 3492 |
class basic_ostream<charT, traits>::sentry {
|
|
@@ -3513,11 +3571,11 @@ If `os.good()` is nonzero, prepares for formatted or unformatted output.
|
|
| 3513 |
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^31]
|
| 3514 |
|
| 3515 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 3516 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 3517 |
constructor may call `setstate(failbit)` (which may throw
|
| 3518 |
-
`ios_base::failure`
|
| 3519 |
|
| 3520 |
``` cpp
|
| 3521 |
~sentry();
|
| 3522 |
```
|
| 3523 |
|
|
@@ -3530,11 +3588,11 @@ sets `badbit` in `os.rdstate()` without propagating an exception.
|
|
| 3530 |
explicit operator bool() const;
|
| 3531 |
```
|
| 3532 |
|
| 3533 |
*Effects:* Returns `ok_`.
|
| 3534 |
|
| 3535 |
-
#####
|
| 3536 |
|
| 3537 |
Each seek member function begins execution by constructing an object of
|
| 3538 |
class `sentry`. It returns by destroying the `sentry` object.
|
| 3539 |
|
| 3540 |
``` cpp
|
|
@@ -3573,12 +3631,12 @@ function calls `setstate(failbit)` (which may throw
|
|
| 3573 |
Each formatted output function begins execution by constructing an
|
| 3574 |
object of class `sentry`. If this object returns `true` when converted
|
| 3575 |
to a value of type `bool`, the function endeavors to generate the
|
| 3576 |
requested output. If the generation fails, then the formatted output
|
| 3577 |
function does `setstate(ios_base::failbit)`, which might throw an
|
| 3578 |
-
exception. If an exception is thrown during output, then
|
| 3579 |
-
is turned on[^33] in `*this`’s error state. If
|
| 3580 |
`(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
|
| 3581 |
not an exception is thrown, the `sentry` object is destroyed before
|
| 3582 |
leaving the formatted output function. If no exception is thrown, the
|
| 3583 |
result of the formatted output function is `*this`.
|
| 3584 |
|
|
@@ -3719,13 +3777,13 @@ in [[ostream.formatted.reqmts]]).
|
|
| 3719 |
|
| 3720 |
``` cpp
|
| 3721 |
basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
|
| 3722 |
```
|
| 3723 |
|
| 3724 |
-
*Effects:* Behaves as an unformatted output
|
| 3725 |
-
|
| 3726 |
-
`sb` is null calls `setstate(badbit)` (which may throw
|
| 3727 |
`ios_base::failure`).
|
| 3728 |
|
| 3729 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 3730 |
read from `sb` and inserted until any of the following occurs:
|
| 3731 |
|
|
@@ -3733,14 +3791,14 @@ read from `sb` and inserted until any of the following occurs:
|
|
| 3733 |
- inserting in the output sequence fails (in which case the character to
|
| 3734 |
be inserted is not extracted);
|
| 3735 |
- an exception occurs while getting a character from `sb`.
|
| 3736 |
|
| 3737 |
If the function inserts no characters, it calls `setstate(failbit)`
|
| 3738 |
-
(which may throw `ios_base::failure`
|
| 3739 |
-
|
| 3740 |
-
|
| 3741 |
-
|
| 3742 |
|
| 3743 |
*Returns:* `*this`.
|
| 3744 |
|
| 3745 |
``` cpp
|
| 3746 |
basic_ostream<charT, traits>& operator<<(nullptr_t);
|
|
@@ -3750,11 +3808,11 @@ basic_ostream<charT, traits>& operator<<(nullptr_t);
|
|
| 3750 |
|
| 3751 |
``` cpp
|
| 3752 |
return *this << s;
|
| 3753 |
```
|
| 3754 |
|
| 3755 |
-
where `s` is an *implementation-defined* NTCTS
|
| 3756 |
|
| 3757 |
##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
|
| 3758 |
|
| 3759 |
``` cpp
|
| 3760 |
template<class charT, class traits>
|
|
@@ -3770,16 +3828,16 @@ template<class traits>
|
|
| 3770 |
template<class traits>
|
| 3771 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
|
| 3772 |
```
|
| 3773 |
|
| 3774 |
*Effects:* Behaves as a formatted output
|
| 3775 |
-
function
|
| 3776 |
-
|
| 3777 |
-
|
| 3778 |
-
|
| 3779 |
-
|
| 3780 |
-
|
| 3781 |
|
| 3782 |
*Returns:* `out`.
|
| 3783 |
|
| 3784 |
``` cpp
|
| 3785 |
template<class charT, class traits>
|
|
@@ -3793,17 +3851,17 @@ template<class traits>
|
|
| 3793 |
template<class traits>
|
| 3794 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
|
| 3795 |
const unsigned char* s);
|
| 3796 |
```
|
| 3797 |
|
| 3798 |
-
*
|
| 3799 |
|
| 3800 |
*Effects:* Behaves like a formatted inserter (as described
|
| 3801 |
in [[ostream.formatted.reqmts]]) of `out`. Creates a character sequence
|
| 3802 |
`seq` of `n` characters starting at `s`, each widened using
|
| 3803 |
-
`out.widen()`
|
| 3804 |
-
|
| 3805 |
|
| 3806 |
- `traits::length(s)` for the overload where the first argument is of
|
| 3807 |
type `basic_ostream<charT, traits>&` and the second is of type
|
| 3808 |
`const charT*`, and also for the overload where the first argument is
|
| 3809 |
of type `basic_ostream<char, traits>&` and the second is of type
|
|
@@ -3824,11 +3882,11 @@ in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
|
|
| 3824 |
|
| 3825 |
Each unformatted output function begins execution by constructing an
|
| 3826 |
object of class `sentry`. If this object returns `true`, while
|
| 3827 |
converting to a value of type `bool`, the function endeavors to generate
|
| 3828 |
the requested output. If an exception is thrown during output, then
|
| 3829 |
-
`
|
| 3830 |
`(exceptions() & badbit) != 0` then the exception is rethrown. In any
|
| 3831 |
case, the unformatted output function ends by destroying the sentry
|
| 3832 |
object, then, if no exception was thrown, returning the value specified
|
| 3833 |
for the unformatted output function.
|
| 3834 |
|
|
@@ -3838,12 +3896,12 @@ basic_ostream<charT, traits>& put(char_type c);
|
|
| 3838 |
|
| 3839 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3840 |
above). After constructing a sentry object, inserts the character `c`,
|
| 3841 |
if possible.[^37]
|
| 3842 |
|
| 3843 |
-
Otherwise, calls `setstate(badbit)` (which may throw
|
| 3844 |
-
|
| 3845 |
|
| 3846 |
*Returns:* `*this`.
|
| 3847 |
|
| 3848 |
``` cpp
|
| 3849 |
basic_ostream& write(const char_type* s, streamsize n);
|
|
@@ -3855,12 +3913,12 @@ from successive locations of an array whose first element is designated
|
|
| 3855 |
by `s`.[^38] Characters are inserted until either of the following
|
| 3856 |
occurs:
|
| 3857 |
|
| 3858 |
- `n` characters are inserted;
|
| 3859 |
- inserting in the output sequence fails (in which case the function
|
| 3860 |
-
calls `setstate(badbit)`, which may throw
|
| 3861 |
-
|
| 3862 |
|
| 3863 |
*Returns:* `*this`.
|
| 3864 |
|
| 3865 |
``` cpp
|
| 3866 |
basic_ostream& flush();
|
|
@@ -3868,17 +3926,20 @@ basic_ostream& flush();
|
|
| 3868 |
|
| 3869 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3870 |
above). If `rdbuf()` is not a null pointer, constructs a sentry object.
|
| 3871 |
If this object returns `true` when converted to a value of type `bool`
|
| 3872 |
the function calls `rdbuf()->pubsync()`. If that function returns -1
|
| 3873 |
-
calls `setstate(badbit)` (which may throw
|
| 3874 |
-
|
| 3875 |
-
|
| 3876 |
|
| 3877 |
*Returns:* `*this`.
|
| 3878 |
|
| 3879 |
-
#### Standard
|
|
|
|
|
|
|
|
|
|
| 3880 |
|
| 3881 |
``` cpp
|
| 3882 |
template<class charT, class traits>
|
| 3883 |
basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
|
| 3884 |
```
|
|
@@ -3904,23 +3965,64 @@ template <class charT, class traits>
|
|
| 3904 |
|
| 3905 |
*Effects:* Calls `os.flush()`.
|
| 3906 |
|
| 3907 |
*Returns:* `os`.
|
| 3908 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3909 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 3910 |
|
| 3911 |
``` cpp
|
| 3912 |
-
template
|
| 3913 |
-
|
| 3914 |
```
|
| 3915 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3916 |
*Effects:* As if by: `os << x;`
|
| 3917 |
|
| 3918 |
-
*Returns:* `os`.
|
| 3919 |
-
|
| 3920 |
-
*Remarks:* This function shall not participate in overload resolution
|
| 3921 |
-
unless the expression `os << x` is well-formed.
|
| 3922 |
|
| 3923 |
### Standard manipulators <a id="std.manip">[[std.manip]]</a>
|
| 3924 |
|
| 3925 |
The header `<iomanip>` defines several functions that support extractors
|
| 3926 |
and inserters that alter information maintained by class `ios_base` and
|
|
@@ -3942,14 +4044,14 @@ void f(ios_base& str, ios_base::fmtflags mask) {
|
|
| 3942 |
// reset specified flags
|
| 3943 |
str.setf(ios_base::fmtflags(0), mask);
|
| 3944 |
}
|
| 3945 |
```
|
| 3946 |
|
| 3947 |
-
The expression `out << resetiosflags(mask)`
|
| 3948 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3949 |
-
`in >> resetiosflags(mask)`
|
| 3950 |
-
|
| 3951 |
|
| 3952 |
``` cpp
|
| 3953 |
unspecified setiosflags(ios_base::fmtflags mask);
|
| 3954 |
```
|
| 3955 |
|
|
@@ -3965,14 +4067,14 @@ void f(ios_base& str, ios_base::fmtflags mask) {
|
|
| 3965 |
// set specified flags
|
| 3966 |
str.setf(mask);
|
| 3967 |
}
|
| 3968 |
```
|
| 3969 |
|
| 3970 |
-
The expression `out << setiosflags(mask)`
|
| 3971 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3972 |
-
`in >> setiosflags(mask)`
|
| 3973 |
-
|
| 3974 |
|
| 3975 |
``` cpp
|
| 3976 |
unspecified setbase(int base);
|
| 3977 |
```
|
| 3978 |
|
|
@@ -3991,14 +4093,14 @@ void f(ios_base& str, int base) {
|
|
| 3991 |
base == 16 ? ios_base::hex :
|
| 3992 |
ios_base::fmtflags(0), ios_base::basefield);
|
| 3993 |
}
|
| 3994 |
```
|
| 3995 |
|
| 3996 |
-
The expression `out << setbase(base)`
|
| 3997 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3998 |
-
`in >> setbase(base)`
|
| 3999 |
-
|
| 4000 |
|
| 4001 |
``` cpp
|
| 4002 |
unspecified setfill(char_type c);
|
| 4003 |
```
|
| 4004 |
|
|
@@ -4013,11 +4115,11 @@ void f(basic_ios<charT, traits>& str, charT c) {
|
|
| 4013 |
// set fill character
|
| 4014 |
str.fill(c);
|
| 4015 |
}
|
| 4016 |
```
|
| 4017 |
|
| 4018 |
-
The expression `out << setfill(c)`
|
| 4019 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4020 |
|
| 4021 |
``` cpp
|
| 4022 |
unspecified setprecision(int n);
|
| 4023 |
```
|
|
@@ -4034,14 +4136,14 @@ void f(ios_base& str, int n) {
|
|
| 4034 |
// set precision
|
| 4035 |
str.precision(n);
|
| 4036 |
}
|
| 4037 |
```
|
| 4038 |
|
| 4039 |
-
The expression `out << setprecision(n)`
|
| 4040 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 4041 |
-
`in >> setprecision(n)`
|
| 4042 |
-
|
| 4043 |
|
| 4044 |
``` cpp
|
| 4045 |
unspecified setw(int n);
|
| 4046 |
```
|
| 4047 |
|
|
@@ -4057,14 +4159,13 @@ void f(ios_base& str, int n) {
|
|
| 4057 |
// set width
|
| 4058 |
str.width(n);
|
| 4059 |
}
|
| 4060 |
```
|
| 4061 |
|
| 4062 |
-
The expression `out << setw(n)`
|
| 4063 |
-
|
| 4064 |
-
`
|
| 4065 |
-
value `in`.
|
| 4066 |
|
| 4067 |
### Extended manipulators <a id="ext.manip">[[ext.manip]]</a>
|
| 4068 |
|
| 4069 |
The header `<iomanip>` defines several functions that support extractors
|
| 4070 |
and inserters that allow for the parsing and formatting of sequences and
|
|
@@ -4072,15 +4173,15 @@ values for money and time.
|
|
| 4072 |
|
| 4073 |
``` cpp
|
| 4074 |
template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
|
| 4075 |
```
|
| 4076 |
|
| 4077 |
-
*
|
| 4078 |
-
specialization of the `basic_string` template
|
| 4079 |
|
| 4080 |
*Effects:* The expression `in >> get_money(mon, intl)` described below
|
| 4081 |
-
behaves as a formatted input function
|
| 4082 |
|
| 4083 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4084 |
of type `basic_istream<charT, traits>` then the expression
|
| 4085 |
`in >> get_money(mon, intl)` behaves as if it called `f(in, mon, intl)`,
|
| 4086 |
where the function `f` is defined as:
|
|
@@ -4099,24 +4200,24 @@ void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
|
|
| 4099 |
if (ios_base::goodbit != err)
|
| 4100 |
str.setstate(err);
|
| 4101 |
}
|
| 4102 |
```
|
| 4103 |
|
| 4104 |
-
The expression `in >> get_money(mon, intl)`
|
| 4105 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4106 |
|
| 4107 |
``` cpp
|
| 4108 |
template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
|
| 4109 |
```
|
| 4110 |
|
| 4111 |
-
*
|
| 4112 |
-
specialization of the `basic_string` template
|
| 4113 |
|
| 4114 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4115 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4116 |
`out << put_money(mon, intl)` behaves as a formatted output
|
| 4117 |
-
function
|
| 4118 |
where the function `f` is defined as:
|
| 4119 |
|
| 4120 |
``` cpp
|
| 4121 |
template<class charT, class traits, class moneyT>
|
| 4122 |
void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
|
|
@@ -4125,25 +4226,24 @@ void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
|
|
| 4125 |
|
| 4126 |
const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
|
| 4127 |
const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);
|
| 4128 |
|
| 4129 |
if (end.failed())
|
| 4130 |
-
str.setstate(
|
| 4131 |
}
|
| 4132 |
```
|
| 4133 |
|
| 4134 |
-
The expression `out << put_money(mon, intl)`
|
| 4135 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4136 |
|
| 4137 |
``` cpp
|
| 4138 |
template<class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
|
| 4139 |
```
|
| 4140 |
|
| 4141 |
-
*
|
| 4142 |
-
type `struct tm`
|
| 4143 |
-
|
| 4144 |
-
elements.
|
| 4145 |
|
| 4146 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4147 |
of type `basic_istream<charT, traits>` then the expression
|
| 4148 |
`in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
|
| 4149 |
where the function `f` is defined as:
|
|
@@ -4163,21 +4263,20 @@ void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
|
|
| 4163 |
if (err != ios_base::goodbit)
|
| 4164 |
str.setstate(err);
|
| 4165 |
}
|
| 4166 |
```
|
| 4167 |
|
| 4168 |
-
The expression `in >> get_time(tmb, fmt)`
|
| 4169 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4170 |
|
| 4171 |
``` cpp
|
| 4172 |
template<class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
|
| 4173 |
```
|
| 4174 |
|
| 4175 |
-
*
|
| 4176 |
-
type `struct tm`, and
|
| 4177 |
-
|
| 4178 |
-
elements.
|
| 4179 |
|
| 4180 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4181 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4182 |
`out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
|
| 4183 |
where the function `f` is defined as:
|
|
@@ -4195,11 +4294,11 @@ void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
|
|
| 4195 |
if (end.failed())
|
| 4196 |
str.setstate(ios_base::badbit);
|
| 4197 |
}
|
| 4198 |
```
|
| 4199 |
|
| 4200 |
-
The expression `out << put_time(tmb, fmt)`
|
| 4201 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4202 |
|
| 4203 |
### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
|
| 4204 |
|
| 4205 |
[*Note 1*: Quoted manipulators provide string insertion and extraction
|
|
@@ -4222,13 +4321,12 @@ template <class charT, class traits>
|
|
| 4222 |
*Returns:* An object of unspecified type such that if `out` is an
|
| 4223 |
instance of `basic_ostream` with member type `char_type` the same as
|
| 4224 |
`charT` and with member type `traits_type`, which in the second and
|
| 4225 |
third forms is the same as `traits`, then the expression
|
| 4226 |
`out << quoted(s, delim, escape)` behaves as a formatted output
|
| 4227 |
-
function
|
| 4228 |
-
|
| 4229 |
-
elements:
|
| 4230 |
|
| 4231 |
- `delim`.
|
| 4232 |
- Each character in `s`. If the character to be output is equal to
|
| 4233 |
`escape` or `delim`, as determined by `traits_type::eq`, first output
|
| 4234 |
`escape`.
|
|
@@ -4236,11 +4334,11 @@ elements:
|
|
| 4236 |
|
| 4237 |
Let `x` be the number of elements initially in `seq`. Then padding is
|
| 4238 |
determined for `seq` as described in [[ostream.formatted.reqmts]],
|
| 4239 |
`seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
|
| 4240 |
`n` is the larger of `out.width()` and `x`, and `out.width(0)` is
|
| 4241 |
-
called. The expression `out << quoted(s, delim, escape)`
|
| 4242 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4243 |
|
| 4244 |
``` cpp
|
| 4245 |
template<class charT, class traits, class Allocator>
|
| 4246 |
unspecified quoted(basic_string<charT, traits, Allocator>& s,
|
|
@@ -4251,12 +4349,13 @@ template <class charT, class traits, class Allocator>
|
|
| 4251 |
|
| 4252 |
- If `in` is an instance of `basic_istream` with member types
|
| 4253 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4254 |
respectively, then the expression `in >> quoted(s, delim, escape)`
|
| 4255 |
behaves as if it extracts the following characters from `in` using
|
| 4256 |
-
`operator>>(basic_istream<charT, traits>&, charT&)`
|
| 4257 |
-
which may throw `ios_base::failure`
|
|
|
|
| 4258 |
- If the first character extracted is equal to `delim`, as determined
|
| 4259 |
by `traits_type::eq`, then:
|
| 4260 |
- Turn off the `skipws` flag.
|
| 4261 |
- `s.clear()`
|
| 4262 |
- Until an unescaped `delim` character is reached or `!in`, extract
|
|
@@ -4270,14 +4369,13 @@ template <class charT, class traits, class Allocator>
|
|
| 4270 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4271 |
respectively, then the expression `out << quoted(s, delim, escape)`
|
| 4272 |
behaves as specified for the
|
| 4273 |
`const basic_string<charT, traits, Allocator>&` overload of the
|
| 4274 |
`quoted` function.
|
| 4275 |
-
|
| 4276 |
-
|
| 4277 |
-
|
| 4278 |
-
`out << quoted(s, delim, escape)` shall have type
|
| 4279 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4280 |
|
| 4281 |
## String-based streams <a id="string.streams">[[string.streams]]</a>
|
| 4282 |
|
| 4283 |
### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
|
|
@@ -4330,26 +4428,55 @@ namespace std {
|
|
| 4330 |
using off_type = typename traits::off_type;
|
| 4331 |
using traits_type = traits;
|
| 4332 |
using allocator_type = Allocator;
|
| 4333 |
|
| 4334 |
// [stringbuf.cons], constructors
|
|
|
|
|
|
|
| 4335 |
explicit basic_stringbuf(
|
|
|
|
| 4336 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
|
|
|
|
|
|
|
|
|
| 4337 |
explicit basic_stringbuf(
|
| 4338 |
-
|
| 4339 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4340 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4341 |
basic_stringbuf(basic_stringbuf&& rhs);
|
|
|
|
| 4342 |
|
| 4343 |
// [stringbuf.assign], assign and swap
|
| 4344 |
-
basic_stringbuf& operator=(const basic_stringbuf&
|
| 4345 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4346 |
-
void swap(basic_stringbuf& rhs);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4347 |
|
| 4348 |
-
// [stringbuf.members], get and set
|
| 4349 |
-
basic_string<charT, traits, Allocator> str() const;
|
| 4350 |
void str(const basic_string<charT, traits, Allocator>& s);
|
|
|
|
|
|
|
|
|
|
| 4351 |
|
| 4352 |
protected:
|
| 4353 |
// [stringbuf.virtuals], overridden virtual functions
|
| 4354 |
int_type underflow() override;
|
| 4355 |
int_type pbackfail(int_type c = traits::eof()) override;
|
|
@@ -4363,66 +4490,120 @@ namespace std {
|
|
| 4363 |
ios_base::openmode which
|
| 4364 |
= ios_base::in | ios_base::out) override;
|
| 4365 |
|
| 4366 |
private:
|
| 4367 |
ios_base::openmode mode; // exposition only
|
|
|
|
|
|
|
| 4368 |
};
|
| 4369 |
|
| 4370 |
template<class charT, class traits, class Allocator>
|
| 4371 |
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4372 |
-
basic_stringbuf<charT, traits, Allocator>& y);
|
| 4373 |
}
|
| 4374 |
```
|
| 4375 |
|
| 4376 |
The class `basic_stringbuf` is derived from `basic_streambuf` to
|
| 4377 |
associate possibly the input sequence and possibly the output sequence
|
| 4378 |
with a sequence of arbitrary *characters*. The sequence can be
|
| 4379 |
initialized from, or made available as, an object of class
|
| 4380 |
`basic_string`.
|
| 4381 |
|
| 4382 |
-
For the sake of exposition, the maintained data
|
|
|
|
| 4383 |
|
| 4384 |
- `ios_base::openmode mode`, has `in` set if the input sequence can be
|
| 4385 |
read, and `out` set if the output sequence can be written.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4386 |
|
| 4387 |
-
####
|
| 4388 |
|
| 4389 |
``` cpp
|
| 4390 |
-
explicit basic_stringbuf(
|
| 4391 |
-
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4392 |
```
|
| 4393 |
|
| 4394 |
-
*Effects:*
|
| 4395 |
-
|
| 4396 |
-
|
|
|
|
|
|
|
| 4397 |
|
| 4398 |
-
*
|
| 4399 |
|
| 4400 |
``` cpp
|
| 4401 |
explicit basic_stringbuf(
|
| 4402 |
const basic_string<charT, traits, Allocator>& s,
|
| 4403 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4404 |
```
|
| 4405 |
|
| 4406 |
-
*Effects:*
|
| 4407 |
-
|
| 4408 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4409 |
|
| 4410 |
``` cpp
|
| 4411 |
basic_stringbuf(basic_stringbuf&& rhs);
|
|
|
|
| 4412 |
```
|
| 4413 |
|
| 4414 |
-
*Effects:*
|
| 4415 |
-
|
| 4416 |
-
|
| 4417 |
-
|
| 4418 |
-
|
| 4419 |
-
|
| 4420 |
|
| 4421 |
-
*
|
| 4422 |
-
|
| 4423 |
-
|
| 4424 |
|
| 4425 |
- `str() == rhs_p.str()`
|
| 4426 |
- `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
|
| 4427 |
- `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
|
| 4428 |
- `pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()`
|
|
@@ -4431,12 +4612,14 @@ this construction.
|
|
| 4431 |
- `if (gptr()) gptr() != rhs_a.gptr()`
|
| 4432 |
- `if (egptr()) egptr() != rhs_a.egptr()`
|
| 4433 |
- `if (pbase()) pbase() != rhs_a.pbase()`
|
| 4434 |
- `if (pptr()) pptr() != rhs_a.pptr()`
|
| 4435 |
- `if (epptr()) epptr() != rhs_a.epptr()`
|
|
|
|
|
|
|
| 4436 |
|
| 4437 |
-
####
|
| 4438 |
|
| 4439 |
``` cpp
|
| 4440 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4441 |
```
|
| 4442 |
|
|
@@ -4445,62 +4628,165 @@ would have had if it had been move constructed from `rhs`
|
|
| 4445 |
(see [[stringbuf.cons]]).
|
| 4446 |
|
| 4447 |
*Returns:* `*this`.
|
| 4448 |
|
| 4449 |
``` cpp
|
| 4450 |
-
void swap(basic_stringbuf& rhs);
|
| 4451 |
```
|
| 4452 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4453 |
*Effects:* Exchanges the state of `*this` and `rhs`.
|
| 4454 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4455 |
``` cpp
|
| 4456 |
template<class charT, class traits, class Allocator>
|
| 4457 |
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4458 |
-
basic_stringbuf<charT, traits, Allocator>& y);
|
| 4459 |
```
|
| 4460 |
|
| 4461 |
-
*Effects:*
|
| 4462 |
|
| 4463 |
#### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
|
| 4464 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4465 |
``` cpp
|
| 4466 |
-
|
| 4467 |
-
|
| 4468 |
-
|
| 4469 |
-
|
| 4470 |
-
`
|
| 4471 |
-
|
| 4472 |
-
|
| 4473 |
-
|
| 4474 |
-
|
| 4475 |
-
|
| 4476 |
-
|
| 4477 |
-
|
| 4478 |
-
|
| 4479 |
-
`
|
| 4480 |
-
|
| 4481 |
-
|
| 4482 |
-
|
| 4483 |
-
`basic_string
|
| 4484 |
-
|
| 4485 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4486 |
|
| 4487 |
``` cpp
|
| 4488 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4489 |
```
|
| 4490 |
|
| 4491 |
-
*Effects:*
|
| 4492 |
-
|
| 4493 |
-
|
| 4494 |
-
|
| 4495 |
-
|
| 4496 |
-
|
| 4497 |
-
|
| 4498 |
-
`
|
| 4499 |
-
|
| 4500 |
-
|
| 4501 |
-
`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4502 |
|
| 4503 |
#### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
|
| 4504 |
|
| 4505 |
``` cpp
|
| 4506 |
int_type underflow() override;
|
|
@@ -4527,11 +4813,11 @@ sequence, if possible, in one of three ways:
|
|
| 4527 |
`ios_base::out` is nonzero, assigns `c` to `*``gptr()`. Returns: `c`.
|
| 4528 |
- If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
|
| 4529 |
input sequence has a putback position available, assigns `gptr() - 1`
|
| 4530 |
to `gptr()`. Returns: `traits::not_eof(c)`.
|
| 4531 |
|
| 4532 |
-
*Returns:* `traits::eof()` to indicate failure.
|
| 4533 |
|
| 4534 |
*Remarks:* If the function can succeed in more than one of these ways,
|
| 4535 |
it is unspecified which way is chosen.
|
| 4536 |
|
| 4537 |
``` cpp
|
|
@@ -4550,56 +4836,55 @@ sequence, if possible, in one of two ways:
|
|
| 4550 |
`traits::eof()`.
|
| 4551 |
|
| 4552 |
*Remarks:* The function can alter the number of write positions
|
| 4553 |
available as a result of any call.
|
| 4554 |
|
| 4555 |
-
*Returns:* `traits::eof()` to indicate failure.
|
| 4556 |
|
| 4557 |
-
The function can make a write position available only if
|
| 4558 |
-
|
| 4559 |
-
|
| 4560 |
-
|
| 4561 |
-
|
| 4562 |
-
|
| 4563 |
-
|
| 4564 |
|
| 4565 |
``` cpp
|
| 4566 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 4567 |
ios_base::openmode which
|
| 4568 |
= ios_base::in | ios_base::out) override;
|
| 4569 |
```
|
| 4570 |
|
| 4571 |
*Effects:* Alters the stream position within one of the controlled
|
| 4572 |
-
sequences, if possible, as indicated in
|
| 4573 |
-
Table [[tab:iostreams.seekoff.positioning]].
|
| 4574 |
|
| 4575 |
-
**Table: `seekoff` positioning** <a id="
|
| 4576 |
|
| 4577 |
| Conditions | Result |
|
| 4578 |
-
| ------------------------------------------------------------------------------------------------------------------------------
|
| 4579 |
-
| `
|
| 4580 |
-
| `
|
| 4581 |
-
|
|
| 4582 |
| Otherwise | the positioning operation fails. |
|
| 4583 |
|
| 4584 |
|
| 4585 |
-
For a sequence to be positioned,
|
| 4586 |
-
|
| 4587 |
-
|
| 4588 |
-
|
| 4589 |
|
| 4590 |
-
**Table: `newoff` values** <a id="
|
| 4591 |
|
| 4592 |
| Condition | `newoff` Value |
|
| 4593 |
| ---------------------- | ----------------------------------------------------------------------- |
|
| 4594 |
| `way == ios_base::beg` | 0 |
|
| 4595 |
| `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
|
| 4596 |
| `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
|
| 4597 |
|
| 4598 |
|
| 4599 |
If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
|
| 4600 |
-
character
|
| 4601 |
Otherwise, the function assigns `xbeg + newoff + off` to the next
|
| 4602 |
pointer `xnext`.
|
| 4603 |
|
| 4604 |
*Returns:* `pos_type(newoff)`, constructed from the resultant offset
|
| 4605 |
`newoff` (of type `off_type`), that stores the resultant stream
|
|
@@ -4641,28 +4926,52 @@ namespace std {
|
|
| 4641 |
using off_type = typename traits::off_type;
|
| 4642 |
using traits_type = traits;
|
| 4643 |
using allocator_type = Allocator;
|
| 4644 |
|
| 4645 |
// [istringstream.cons], constructors
|
|
|
|
|
|
|
| 4646 |
explicit basic_istringstream(
|
|
|
|
| 4647 |
ios_base::openmode which = ios_base::in);
|
|
|
|
| 4648 |
explicit basic_istringstream(
|
| 4649 |
-
|
| 4650 |
ios_base::openmode which = ios_base::in);
|
| 4651 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4652 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4653 |
|
| 4654 |
// [istringstream.assign], assign and swap
|
| 4655 |
-
basic_istringstream& operator=(const basic_istringstream&
|
| 4656 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
| 4657 |
void swap(basic_istringstream& rhs);
|
| 4658 |
|
| 4659 |
// [istringstream.members], members
|
| 4660 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4661 |
|
| 4662 |
-
basic_string<charT, traits, Allocator> str() const;
|
| 4663 |
void str(const basic_string<charT, traits, Allocator>& s);
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4664 |
private:
|
| 4665 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 4666 |
};
|
| 4667 |
|
| 4668 |
template<class charT, class traits, class Allocator>
|
|
@@ -4677,87 +4986,157 @@ uses a `basic_stringbuf<charT, traits, Allocator>` object to control the
|
|
| 4677 |
associated storage. For the sake of exposition, the maintained data is
|
| 4678 |
presented here as:
|
| 4679 |
|
| 4680 |
- `sb`, the `stringbuf` object.
|
| 4681 |
|
| 4682 |
-
####
|
| 4683 |
|
| 4684 |
``` cpp
|
| 4685 |
-
explicit basic_istringstream(ios_base::openmode which
|
| 4686 |
```
|
| 4687 |
|
| 4688 |
-
*Effects:*
|
| 4689 |
-
`
|
| 4690 |
-
`
|
| 4691 |
-
|
| 4692 |
|
| 4693 |
``` cpp
|
| 4694 |
explicit basic_istringstream(
|
| 4695 |
-
const basic_string<charT, traits, Allocator>&
|
| 4696 |
ios_base::openmode which = ios_base::in);
|
| 4697 |
```
|
| 4698 |
|
| 4699 |
-
*Effects:*
|
| 4700 |
-
`
|
| 4701 |
-
`
|
| 4702 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4703 |
|
| 4704 |
``` cpp
|
| 4705 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4706 |
```
|
| 4707 |
|
| 4708 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4709 |
by move constructing the base class, and the contained
|
| 4710 |
-
`basic_stringbuf`.
|
| 4711 |
-
|
|
|
|
| 4712 |
|
| 4713 |
-
####
|
| 4714 |
-
|
| 4715 |
-
``` cpp
|
| 4716 |
-
basic_istringstream& operator=(basic_istringstream&& rhs);
|
| 4717 |
-
```
|
| 4718 |
-
|
| 4719 |
-
*Effects:* Move assigns the base and members of `*this` from the base
|
| 4720 |
-
and corresponding members of `rhs`.
|
| 4721 |
-
|
| 4722 |
-
*Returns:* `*this`.
|
| 4723 |
|
| 4724 |
``` cpp
|
| 4725 |
void swap(basic_istringstream& rhs);
|
| 4726 |
```
|
| 4727 |
|
| 4728 |
-
*Effects:*
|
| 4729 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4730 |
|
| 4731 |
``` cpp
|
| 4732 |
template<class charT, class traits, class Allocator>
|
| 4733 |
void swap(basic_istringstream<charT, traits, Allocator>& x,
|
| 4734 |
basic_istringstream<charT, traits, Allocator>& y);
|
| 4735 |
```
|
| 4736 |
|
| 4737 |
-
*Effects:*
|
| 4738 |
|
| 4739 |
#### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
|
| 4740 |
|
| 4741 |
``` cpp
|
| 4742 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4743 |
```
|
| 4744 |
|
| 4745 |
*Returns:*
|
| 4746 |
-
`const_cast<basic_stringbuf<charT, traits, Allocator>*>(
|
| 4747 |
|
| 4748 |
``` cpp
|
| 4749 |
-
basic_string<charT, traits, Allocator> str() const;
|
| 4750 |
```
|
| 4751 |
|
| 4752 |
-
*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4753 |
|
| 4754 |
``` cpp
|
| 4755 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4756 |
```
|
| 4757 |
|
| 4758 |
-
*Effects:*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4759 |
|
| 4760 |
### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
|
| 4761 |
|
| 4762 |
``` cpp
|
| 4763 |
namespace std {
|
|
@@ -4771,28 +5150,53 @@ namespace std {
|
|
| 4771 |
using off_type = typename traits::off_type;
|
| 4772 |
using traits_type = traits;
|
| 4773 |
using allocator_type = Allocator;
|
| 4774 |
|
| 4775 |
// [ostringstream.cons], constructors
|
|
|
|
|
|
|
| 4776 |
explicit basic_ostringstream(
|
|
|
|
| 4777 |
ios_base::openmode which = ios_base::out);
|
|
|
|
| 4778 |
explicit basic_ostringstream(
|
| 4779 |
-
|
| 4780 |
ios_base::openmode which = ios_base::out);
|
| 4781 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4782 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 4783 |
|
| 4784 |
// [ostringstream.assign], assign and swap
|
| 4785 |
-
basic_ostringstream& operator=(const basic_ostringstream&
|
| 4786 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
| 4787 |
void swap(basic_ostringstream& rhs);
|
| 4788 |
|
| 4789 |
// [ostringstream.members], members
|
| 4790 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4791 |
|
| 4792 |
-
basic_string<charT, traits, Allocator> str() const;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4793 |
void str(const basic_string<charT, traits, Allocator>& s);
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4794 |
private:
|
| 4795 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 4796 |
};
|
| 4797 |
|
| 4798 |
template<class charT, class traits, class Allocator>
|
|
@@ -4806,88 +5210,157 @@ writing objects of class `basic_string<{}charT, traits, Allocator>`. It
|
|
| 4806 |
uses a `basic_stringbuf` object to control the associated storage. For
|
| 4807 |
the sake of exposition, the maintained data is presented here as:
|
| 4808 |
|
| 4809 |
- `sb`, the `stringbuf` object.
|
| 4810 |
|
| 4811 |
-
####
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4812 |
|
| 4813 |
``` cpp
|
| 4814 |
explicit basic_ostringstream(
|
|
|
|
| 4815 |
ios_base::openmode which = ios_base::out);
|
| 4816 |
```
|
| 4817 |
|
| 4818 |
-
*Effects:*
|
| 4819 |
-
|
| 4820 |
-
`
|
| 4821 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4822 |
|
| 4823 |
``` cpp
|
| 4824 |
explicit basic_ostringstream(
|
| 4825 |
-
|
| 4826 |
ios_base::openmode which = ios_base::out);
|
| 4827 |
```
|
| 4828 |
|
| 4829 |
-
*Effects:*
|
| 4830 |
-
`
|
| 4831 |
-
`
|
| 4832 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4833 |
|
| 4834 |
``` cpp
|
| 4835 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 4836 |
```
|
| 4837 |
|
| 4838 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4839 |
by move constructing the base class, and the contained
|
| 4840 |
-
`basic_stringbuf`.
|
| 4841 |
-
|
|
|
|
| 4842 |
|
| 4843 |
-
####
|
| 4844 |
-
|
| 4845 |
-
``` cpp
|
| 4846 |
-
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
| 4847 |
-
```
|
| 4848 |
-
|
| 4849 |
-
*Effects:* Move assigns the base and members of `*this` from the base
|
| 4850 |
-
and corresponding members of `rhs`.
|
| 4851 |
-
|
| 4852 |
-
*Returns:* `*this`.
|
| 4853 |
|
| 4854 |
``` cpp
|
| 4855 |
void swap(basic_ostringstream& rhs);
|
| 4856 |
```
|
| 4857 |
|
| 4858 |
-
*Effects:*
|
| 4859 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4860 |
|
| 4861 |
``` cpp
|
| 4862 |
template<class charT, class traits, class Allocator>
|
| 4863 |
void swap(basic_ostringstream<charT, traits, Allocator>& x,
|
| 4864 |
basic_ostringstream<charT, traits, Allocator>& y);
|
| 4865 |
```
|
| 4866 |
|
| 4867 |
-
*Effects:*
|
| 4868 |
|
| 4869 |
#### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
|
| 4870 |
|
| 4871 |
``` cpp
|
| 4872 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4873 |
```
|
| 4874 |
|
| 4875 |
*Returns:*
|
| 4876 |
-
`const_cast<basic_stringbuf<charT, traits, Allocator>*>(
|
| 4877 |
|
| 4878 |
``` cpp
|
| 4879 |
-
basic_string<charT, traits, Allocator> str() const;
|
| 4880 |
```
|
| 4881 |
|
| 4882 |
-
*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4883 |
|
| 4884 |
``` cpp
|
| 4885 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4886 |
```
|
| 4887 |
|
| 4888 |
-
*Effects:*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4889 |
|
| 4890 |
### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
|
| 4891 |
|
| 4892 |
``` cpp
|
| 4893 |
namespace std {
|
|
@@ -4901,27 +5374,52 @@ namespace std {
|
|
| 4901 |
using off_type = typename traits::off_type;
|
| 4902 |
using traits_type = traits;
|
| 4903 |
using allocator_type = Allocator;
|
| 4904 |
|
| 4905 |
// [stringstream.cons], constructors
|
|
|
|
|
|
|
| 4906 |
explicit basic_stringstream(
|
|
|
|
| 4907 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
|
|
|
| 4908 |
explicit basic_stringstream(
|
| 4909 |
-
|
| 4910 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4911 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4912 |
basic_stringstream(basic_stringstream&& rhs);
|
| 4913 |
|
| 4914 |
// [stringstream.assign], assign and swap
|
| 4915 |
-
basic_stringstream& operator=(const basic_stringstream&
|
| 4916 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
| 4917 |
void swap(basic_stringstream& rhs);
|
| 4918 |
|
| 4919 |
// [stringstream.members], members
|
| 4920 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4921 |
-
|
| 4922 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4923 |
|
| 4924 |
private:
|
| 4925 |
basic_stringbuf<charT, traits> sb; // exposition only
|
| 4926 |
};
|
| 4927 |
|
|
@@ -4938,87 +5436,160 @@ and writing from objects of class
|
|
| 4938 |
associated sequence. For the sake of exposition, the maintained data is
|
| 4939 |
presented here as
|
| 4940 |
|
| 4941 |
- `sb`, the `stringbuf` object.
|
| 4942 |
|
| 4943 |
-
####
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4944 |
|
| 4945 |
``` cpp
|
| 4946 |
explicit basic_stringstream(
|
|
|
|
| 4947 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4948 |
```
|
| 4949 |
|
| 4950 |
-
*Effects:*
|
| 4951 |
-
`
|
| 4952 |
-
`
|
| 4953 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4954 |
|
| 4955 |
``` cpp
|
| 4956 |
explicit basic_stringstream(
|
| 4957 |
-
|
| 4958 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4959 |
```
|
| 4960 |
|
| 4961 |
-
*Effects:*
|
| 4962 |
-
`
|
| 4963 |
-
`
|
| 4964 |
-
`basic_stringbuf<charT, traits, Allocator>(
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4965 |
|
| 4966 |
``` cpp
|
| 4967 |
basic_stringstream(basic_stringstream&& rhs);
|
| 4968 |
```
|
| 4969 |
|
| 4970 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4971 |
by move constructing the base class, and the contained
|
| 4972 |
-
`basic_stringbuf`.
|
| 4973 |
-
|
|
|
|
| 4974 |
|
| 4975 |
-
####
|
| 4976 |
-
|
| 4977 |
-
``` cpp
|
| 4978 |
-
basic_stringstream& operator=(basic_stringstream&& rhs);
|
| 4979 |
-
```
|
| 4980 |
-
|
| 4981 |
-
*Effects:* Move assigns the base and members of `*this` from the base
|
| 4982 |
-
and corresponding members of `rhs`.
|
| 4983 |
-
|
| 4984 |
-
*Returns:* `*this`.
|
| 4985 |
|
| 4986 |
``` cpp
|
| 4987 |
void swap(basic_stringstream& rhs);
|
| 4988 |
```
|
| 4989 |
|
| 4990 |
-
*Effects:*
|
| 4991 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4992 |
|
| 4993 |
``` cpp
|
| 4994 |
template<class charT, class traits, class Allocator>
|
| 4995 |
void swap(basic_stringstream<charT, traits, Allocator>& x,
|
| 4996 |
basic_stringstream<charT, traits, Allocator>& y);
|
| 4997 |
```
|
| 4998 |
|
| 4999 |
-
*Effects:*
|
| 5000 |
|
| 5001 |
#### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
|
| 5002 |
|
| 5003 |
``` cpp
|
| 5004 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5005 |
```
|
| 5006 |
|
| 5007 |
-
*Returns:*
|
|
|
|
| 5008 |
|
| 5009 |
``` cpp
|
| 5010 |
-
basic_string<charT, traits, Allocator> str() const;
|
| 5011 |
```
|
| 5012 |
|
| 5013 |
-
*
|
| 5014 |
|
| 5015 |
``` cpp
|
| 5016 |
-
|
|
|
|
| 5017 |
```
|
| 5018 |
|
| 5019 |
-
*Effects:*
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5020 |
|
| 5021 |
## File-based streams <a id="file.streams">[[file.streams]]</a>
|
| 5022 |
|
| 5023 |
### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
|
| 5024 |
|
|
@@ -5054,13 +5625,13 @@ files.
|
|
| 5054 |
or sink of bytes. In an environment that uses a large character set, the
|
| 5055 |
file typically holds multibyte character sequences and the
|
| 5056 |
`basic_filebuf` object converts those multibyte sequences into wide
|
| 5057 |
character sequences. — *end note*]
|
| 5058 |
|
| 5059 |
-
In
|
| 5060 |
`const filesystem::path::value_type*` are only be provided on systems
|
| 5061 |
-
where `filesystem::path::value_type`
|
| 5062 |
|
| 5063 |
[*Note 2*: These functions enable class `path` support for systems with
|
| 5064 |
a wide native path character type, such as `wchar_t`. — *end note*]
|
| 5065 |
|
| 5066 |
### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
|
|
@@ -5076,16 +5647,16 @@ namespace std {
|
|
| 5076 |
using off_type = typename traits::off_type;
|
| 5077 |
using traits_type = traits;
|
| 5078 |
|
| 5079 |
// [filebuf.cons], constructors/destructor
|
| 5080 |
basic_filebuf();
|
| 5081 |
-
basic_filebuf(const basic_filebuf&
|
| 5082 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5083 |
virtual ~basic_filebuf();
|
| 5084 |
|
| 5085 |
// [filebuf.assign], assign and swap
|
| 5086 |
-
basic_filebuf& operator=(const basic_filebuf&
|
| 5087 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5088 |
void swap(basic_filebuf& rhs);
|
| 5089 |
|
| 5090 |
// [filebuf.members], members
|
| 5091 |
bool is_open() const;
|
|
@@ -5143,45 +5714,44 @@ An instance of `basic_filebuf` behaves as described in [[filebuf]]
|
|
| 5143 |
provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
|
| 5144 |
the behavior is undefined.
|
| 5145 |
|
| 5146 |
In order to support file I/O and multibyte/wide character conversion,
|
| 5147 |
conversions are performed using members of a facet, referred to as
|
| 5148 |
-
`a_codecvt` in following
|
| 5149 |
|
| 5150 |
``` cpp
|
| 5151 |
const codecvt<charT, char, typename traits::state_type>& a_codecvt =
|
| 5152 |
use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());
|
| 5153 |
```
|
| 5154 |
|
| 5155 |
-
####
|
| 5156 |
|
| 5157 |
``` cpp
|
| 5158 |
basic_filebuf();
|
| 5159 |
```
|
| 5160 |
|
| 5161 |
-
*Effects:*
|
| 5162 |
-
|
| 5163 |
-
`basic_streambuf<charT, traits>()` ([[streambuf.cons]]).
|
| 5164 |
|
| 5165 |
-
*
|
| 5166 |
|
| 5167 |
``` cpp
|
| 5168 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5169 |
```
|
| 5170 |
|
| 5171 |
-
*Effects:*
|
| 5172 |
-
*
|
| 5173 |
-
|
| 5174 |
-
|
| 5175 |
-
|
| 5176 |
-
|
| 5177 |
-
construction, and
|
| 5178 |
-
|
| 5179 |
|
| 5180 |
-
*
|
| 5181 |
-
|
| 5182 |
-
|
| 5183 |
|
| 5184 |
- `is_open() == rhs_p.is_open()`
|
| 5185 |
- `rhs_a.is_open() == false`
|
| 5186 |
- `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
|
| 5187 |
- `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
|
|
@@ -5196,16 +5766,16 @@ this construction.
|
|
| 5196 |
|
| 5197 |
``` cpp
|
| 5198 |
virtual ~basic_filebuf();
|
| 5199 |
```
|
| 5200 |
|
| 5201 |
-
*Effects:*
|
| 5202 |
-
|
| 5203 |
-
|
| 5204 |
-
|
| 5205 |
|
| 5206 |
-
####
|
| 5207 |
|
| 5208 |
``` cpp
|
| 5209 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5210 |
```
|
| 5211 |
|
|
@@ -5225,11 +5795,11 @@ void swap(basic_filebuf& rhs);
|
|
| 5225 |
template<class charT, class traits>
|
| 5226 |
void swap(basic_filebuf<charT, traits>& x,
|
| 5227 |
basic_filebuf<charT, traits>& y);
|
| 5228 |
```
|
| 5229 |
|
| 5230 |
-
*Effects:*
|
| 5231 |
|
| 5232 |
#### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
|
| 5233 |
|
| 5234 |
``` cpp
|
| 5235 |
bool is_open() const;
|
|
@@ -5242,19 +5812,20 @@ non-null value) and there has been no intervening call to close.
|
|
| 5242 |
basic_filebuf* open(const char* s, ios_base::openmode mode);
|
| 5243 |
basic_filebuf* open(const filesystem::path::value_type* s,
|
| 5244 |
ios_base::openmode mode); // wide systems only; see [fstream.syn]
|
| 5245 |
```
|
| 5246 |
|
|
|
|
|
|
|
| 5247 |
*Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
|
| 5248 |
-
initializes the `filebuf` as required. It then opens
|
| 5249 |
-
possible,
|
| 5250 |
-
|
| 5251 |
-
`mode
|
| 5252 |
-
|
| 5253 |
-
combination of flags shown in the table then the open fails.
|
| 5254 |
|
| 5255 |
-
**Table: File open modes** <a id="
|
| 5256 |
|
| 5257 |
| `binary` | `in` | `out` | `trunc` | `app` | | `stdio` equivalent |
|
| 5258 |
| -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
|
| 5259 |
| | | + | | | `"w"` |
|
| 5260 |
| | | + | | + | `"a"` |
|
|
@@ -5273,13 +5844,14 @@ combination of flags shown in the table then the open fails.
|
|
| 5273 |
| + | + | + | + | | `"w+b"` |
|
| 5274 |
| + | + | + | | + | `"a+b"` |
|
| 5275 |
| + | + | | | + | `"a+b"` |
|
| 5276 |
|
| 5277 |
|
| 5278 |
-
If the open operation succeeds and `
|
| 5279 |
positions the file to the end (as if by calling
|
| 5280 |
-
`fseek(file, 0, SEEK_END)`
|
|
|
|
| 5281 |
|
| 5282 |
If the repositioning operation fails, calls `close()` and returns a null
|
| 5283 |
pointer to indicate failure.
|
| 5284 |
|
| 5285 |
*Returns:* `this` if successful, a null pointer otherwise.
|
|
@@ -5308,20 +5880,20 @@ or throws an exception, the function closes the file (as if by calling
|
|
| 5308 |
these calls throws an exception, the exception is caught and rethrown
|
| 5309 |
after closing the file.
|
| 5310 |
|
| 5311 |
*Returns:* `this` on success, a null pointer otherwise.
|
| 5312 |
|
| 5313 |
-
*
|
| 5314 |
|
| 5315 |
#### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
|
| 5316 |
|
| 5317 |
``` cpp
|
| 5318 |
streamsize showmanyc() override;
|
| 5319 |
```
|
| 5320 |
|
| 5321 |
-
*Effects:* Behaves the same as
|
| 5322 |
-
|
| 5323 |
|
| 5324 |
*Remarks:* An implementation might well provide an overriding definition
|
| 5325 |
for this function signature if it can determine that more characters can
|
| 5326 |
be read from the input sequence.
|
| 5327 |
|
|
@@ -5378,11 +5950,11 @@ sequence, if possible, in one of three ways:
|
|
| 5378 |
either the input sequence has a putback position available or the
|
| 5379 |
function makes a putback position available, decrements the next
|
| 5380 |
pointer for the input sequence, `gptr()`. Returns:
|
| 5381 |
`traits::not_eof(c)`.
|
| 5382 |
|
| 5383 |
-
*Returns:* `traits::eof()` to indicate failure.
|
| 5384 |
|
| 5385 |
*Remarks:* If `is_open() == false`, the function always fails.
|
| 5386 |
|
| 5387 |
The function does not put back a character directly to the input
|
| 5388 |
sequence.
|
|
@@ -5452,13 +6024,13 @@ and write any unshift sequence. Next, seek to the new position: if
|
|
| 5452 |
operation was overflow or the put buffer is non-empty. “Write any
|
| 5453 |
unshift sequence” means, if `width` if less than zero then call
|
| 5454 |
`a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
|
| 5455 |
resulting unshift sequence. The function determines one of three values
|
| 5456 |
for the argument `whence`, of type `int`, as indicated in
|
| 5457 |
-
|
| 5458 |
|
| 5459 |
-
**Table: `seekoff` effects** <a id="
|
| 5460 |
|
| 5461 |
| `way` Value | `stdio` Equivalent |
|
| 5462 |
| ---------------- | ------------------ |
|
| 5463 |
| `basic_ios::beg` | `SEEK_SET` |
|
| 5464 |
| `basic_ios::cur` | `SEEK_CUR` |
|
|
@@ -5507,13 +6079,13 @@ characters to the file, then flushes the file as if by calling
|
|
| 5507 |
|
| 5508 |
``` cpp
|
| 5509 |
void imbue(const locale& loc) override;
|
| 5510 |
```
|
| 5511 |
|
| 5512 |
-
*
|
| 5513 |
encoding of the current locale as determined by `a_codecvt.encoding()`
|
| 5514 |
-
is state-dependent
|
| 5515 |
same as the corresponding facet of `loc`.
|
| 5516 |
|
| 5517 |
*Effects:* Causes characters inserted or extracted after this call to be
|
| 5518 |
converted according to `loc` until another call of `imbue`.
|
| 5519 |
|
|
@@ -5542,15 +6114,15 @@ namespace std {
|
|
| 5542 |
ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
|
| 5543 |
explicit basic_ifstream(const string& s,
|
| 5544 |
ios_base::openmode mode = ios_base::in);
|
| 5545 |
explicit basic_ifstream(const filesystem::path& s,
|
| 5546 |
ios_base::openmode mode = ios_base::in);
|
| 5547 |
-
basic_ifstream(const basic_ifstream&
|
| 5548 |
basic_ifstream(basic_ifstream&& rhs);
|
| 5549 |
|
| 5550 |
// [ifstream.assign], assign and swap
|
| 5551 |
-
basic_ifstream& operator=(const basic_ifstream&
|
| 5552 |
basic_ifstream& operator=(basic_ifstream&& rhs);
|
| 5553 |
void swap(basic_ifstream& rhs);
|
| 5554 |
|
| 5555 |
// [ifstream.members], members
|
| 5556 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
@@ -5577,62 +6149,52 @@ files. It uses a `basic_filebuf<{}charT, traits>` object to control the
|
|
| 5577 |
associated sequence. For the sake of exposition, the maintained data is
|
| 5578 |
presented here as:
|
| 5579 |
|
| 5580 |
- `sb`, the `filebuf` object.
|
| 5581 |
|
| 5582 |
-
####
|
| 5583 |
|
| 5584 |
``` cpp
|
| 5585 |
basic_ifstream();
|
| 5586 |
```
|
| 5587 |
|
| 5588 |
-
*Effects:*
|
| 5589 |
-
`
|
| 5590 |
-
`
|
| 5591 |
-
`basic_filebuf<charT, traits>())` ([[istream.cons]], [[filebuf.cons]]).
|
| 5592 |
|
| 5593 |
``` cpp
|
| 5594 |
explicit basic_ifstream(const char* s,
|
| 5595 |
ios_base::openmode mode = ios_base::in);
|
| 5596 |
explicit basic_ifstream(const filesystem::path::value_type* s,
|
| 5597 |
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 5598 |
```
|
| 5599 |
|
| 5600 |
-
*Effects:*
|
| 5601 |
-
|
| 5602 |
-
`basic_filebuf<charT, traits>()
|
| 5603 |
-
|
| 5604 |
-
|
| 5605 |
|
| 5606 |
``` cpp
|
| 5607 |
explicit basic_ifstream(const string& s,
|
| 5608 |
ios_base::openmode mode = ios_base::in);
|
| 5609 |
explicit basic_ifstream(const filesystem::path& s,
|
| 5610 |
ios_base::openmode mode = ios_base::in);
|
| 5611 |
```
|
| 5612 |
|
| 5613 |
-
*Effects:*
|
| 5614 |
|
| 5615 |
``` cpp
|
| 5616 |
basic_ifstream(basic_ifstream&& rhs);
|
| 5617 |
```
|
| 5618 |
|
| 5619 |
-
*Effects:* Move constructs
|
| 5620 |
-
|
| 5621 |
-
|
| 5622 |
-
|
| 5623 |
|
| 5624 |
-
####
|
| 5625 |
-
|
| 5626 |
-
``` cpp
|
| 5627 |
-
basic_ifstream& operator=(basic_ifstream&& rhs);
|
| 5628 |
-
```
|
| 5629 |
-
|
| 5630 |
-
*Effects:* Move assigns the base and members of `*this` from the base
|
| 5631 |
-
and corresponding members of `rhs`.
|
| 5632 |
-
|
| 5633 |
-
*Returns:* `*this`.
|
| 5634 |
|
| 5635 |
``` cpp
|
| 5636 |
void swap(basic_ifstream& rhs);
|
| 5637 |
```
|
| 5638 |
|
|
@@ -5643,19 +6205,19 @@ void swap(basic_ifstream& rhs);
|
|
| 5643 |
template<class charT, class traits>
|
| 5644 |
void swap(basic_ifstream<charT, traits>& x,
|
| 5645 |
basic_ifstream<charT, traits>& y);
|
| 5646 |
```
|
| 5647 |
|
| 5648 |
-
*Effects:*
|
| 5649 |
|
| 5650 |
#### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
|
| 5651 |
|
| 5652 |
``` cpp
|
| 5653 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5654 |
```
|
| 5655 |
|
| 5656 |
-
*Returns:* `const_cast<basic_filebuf<charT, traits>*>(
|
| 5657 |
|
| 5658 |
``` cpp
|
| 5659 |
bool is_open() const;
|
| 5660 |
```
|
| 5661 |
|
|
@@ -5667,12 +6229,12 @@ void open(const filesystem::path::value_type* s,
|
|
| 5667 |
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 5668 |
```
|
| 5669 |
|
| 5670 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::in)`. If that
|
| 5671 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 5672 |
-
`setstate(failbit)` (which may throw
|
| 5673 |
-
|
| 5674 |
|
| 5675 |
``` cpp
|
| 5676 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
| 5677 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
|
| 5678 |
```
|
|
@@ -5683,11 +6245,11 @@ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
|
|
| 5683 |
void close();
|
| 5684 |
```
|
| 5685 |
|
| 5686 |
*Effects:* Calls `rdbuf()->close()` and, if that function returns a null
|
| 5687 |
pointer, calls `setstate(failbit)` (which may throw
|
| 5688 |
-
`ios_base::failure`)
|
| 5689 |
|
| 5690 |
### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
|
| 5691 |
|
| 5692 |
``` cpp
|
| 5693 |
namespace std {
|
|
@@ -5702,21 +6264,21 @@ namespace std {
|
|
| 5702 |
|
| 5703 |
// [ofstream.cons], constructors
|
| 5704 |
basic_ofstream();
|
| 5705 |
explicit basic_ofstream(const char* s,
|
| 5706 |
ios_base::openmode mode = ios_base::out);
|
| 5707 |
-
explicit basic_ofstream(const filesystem::path::value_type* s,
|
| 5708 |
-
ios_base::openmode mode = ios_base::out);
|
| 5709 |
explicit basic_ofstream(const string& s,
|
| 5710 |
ios_base::openmode mode = ios_base::out);
|
| 5711 |
explicit basic_ofstream(const filesystem::path& s,
|
| 5712 |
ios_base::openmode mode = ios_base::out);
|
| 5713 |
-
basic_ofstream(const basic_ofstream&
|
| 5714 |
basic_ofstream(basic_ofstream&& rhs);
|
| 5715 |
|
| 5716 |
// [ofstream.assign], assign and swap
|
| 5717 |
-
basic_ofstream& operator=(const basic_ofstream&
|
| 5718 |
basic_ofstream& operator=(basic_ofstream&& rhs);
|
| 5719 |
void swap(basic_ofstream& rhs);
|
| 5720 |
|
| 5721 |
// [ofstream.members], members
|
| 5722 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
@@ -5743,63 +6305,52 @@ files. It uses a `basic_filebuf<{}charT, traits>` object to control the
|
|
| 5743 |
associated sequence. For the sake of exposition, the maintained data is
|
| 5744 |
presented here as:
|
| 5745 |
|
| 5746 |
- `sb`, the `filebuf` object.
|
| 5747 |
|
| 5748 |
-
####
|
| 5749 |
|
| 5750 |
``` cpp
|
| 5751 |
basic_ofstream();
|
| 5752 |
```
|
| 5753 |
|
| 5754 |
-
*Effects:*
|
| 5755 |
-
`
|
| 5756 |
-
`
|
| 5757 |
-
`basic_filebuf<charT, traits>())` ([[ostream.cons]], [[filebuf.cons]]).
|
| 5758 |
|
| 5759 |
``` cpp
|
| 5760 |
explicit basic_ofstream(const char* s,
|
| 5761 |
ios_base::openmode mode = ios_base::out);
|
| 5762 |
explicit basic_ofstream(const filesystem::path::value_type* s,
|
| 5763 |
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 5764 |
```
|
| 5765 |
|
| 5766 |
-
*Effects:*
|
| 5767 |
-
`
|
| 5768 |
-
`
|
| 5769 |
-
`
|
| 5770 |
-
|
| 5771 |
-
returns a null pointer, calls `setstate(failbit)`.
|
| 5772 |
|
| 5773 |
``` cpp
|
| 5774 |
explicit basic_ofstream(const string& s,
|
| 5775 |
ios_base::openmode mode = ios_base::out);
|
| 5776 |
explicit basic_ofstream(const filesystem::path& s,
|
| 5777 |
ios_base::openmode mode = ios_base::out);
|
| 5778 |
```
|
| 5779 |
|
| 5780 |
-
*Effects:*
|
| 5781 |
|
| 5782 |
``` cpp
|
| 5783 |
basic_ofstream(basic_ofstream&& rhs);
|
| 5784 |
```
|
| 5785 |
|
| 5786 |
-
*Effects:* Move constructs
|
| 5787 |
-
|
| 5788 |
-
|
| 5789 |
-
|
| 5790 |
|
| 5791 |
-
####
|
| 5792 |
-
|
| 5793 |
-
``` cpp
|
| 5794 |
-
basic_ofstream& operator=(basic_ofstream&& rhs);
|
| 5795 |
-
```
|
| 5796 |
-
|
| 5797 |
-
*Effects:* Move assigns the base and members of `*this` from the base
|
| 5798 |
-
and corresponding members of `rhs`.
|
| 5799 |
-
|
| 5800 |
-
*Returns:* `*this`.
|
| 5801 |
|
| 5802 |
``` cpp
|
| 5803 |
void swap(basic_ofstream& rhs);
|
| 5804 |
```
|
| 5805 |
|
|
@@ -5810,19 +6361,19 @@ void swap(basic_ofstream& rhs);
|
|
| 5810 |
template<class charT, class traits>
|
| 5811 |
void swap(basic_ofstream<charT, traits>& x,
|
| 5812 |
basic_ofstream<charT, traits>& y);
|
| 5813 |
```
|
| 5814 |
|
| 5815 |
-
*Effects:*
|
| 5816 |
|
| 5817 |
#### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
|
| 5818 |
|
| 5819 |
``` cpp
|
| 5820 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5821 |
```
|
| 5822 |
|
| 5823 |
-
*Returns:* `const_cast<basic_filebuf<charT, traits>*>(
|
| 5824 |
|
| 5825 |
``` cpp
|
| 5826 |
bool is_open() const;
|
| 5827 |
```
|
| 5828 |
|
|
@@ -5834,20 +6385,20 @@ void open(const filesystem::path::value_type* s,
|
|
| 5834 |
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 5835 |
```
|
| 5836 |
|
| 5837 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::out)`. If that
|
| 5838 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 5839 |
-
`setstate(failbit)` (which may throw
|
| 5840 |
-
|
| 5841 |
|
| 5842 |
``` cpp
|
| 5843 |
void close();
|
| 5844 |
```
|
| 5845 |
|
| 5846 |
*Effects:* Calls `rdbuf()->close()` and, if that function fails (returns
|
| 5847 |
a null pointer), calls `setstate(failbit)` (which may throw
|
| 5848 |
-
`ios_base::failure`)
|
| 5849 |
|
| 5850 |
``` cpp
|
| 5851 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
| 5852 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
|
| 5853 |
```
|
|
@@ -5871,34 +6422,34 @@ namespace std {
|
|
| 5871 |
basic_fstream();
|
| 5872 |
explicit basic_fstream(
|
| 5873 |
const char* s,
|
| 5874 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5875 |
explicit basic_fstream(
|
| 5876 |
-
const
|
| 5877 |
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 5878 |
explicit basic_fstream(
|
| 5879 |
const string& s,
|
| 5880 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5881 |
explicit basic_fstream(
|
| 5882 |
const filesystem::path& s,
|
| 5883 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5884 |
-
basic_fstream(const basic_fstream&
|
| 5885 |
basic_fstream(basic_fstream&& rhs);
|
| 5886 |
|
| 5887 |
// [fstream.assign], assign and swap
|
| 5888 |
-
basic_fstream& operator=(const basic_fstream&
|
| 5889 |
basic_fstream& operator=(basic_fstream&& rhs);
|
| 5890 |
void swap(basic_fstream& rhs);
|
| 5891 |
|
| 5892 |
// [fstream.members], members
|
| 5893 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5894 |
bool is_open() const;
|
| 5895 |
void open(
|
| 5896 |
const char* s,
|
| 5897 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5898 |
void open(
|
| 5899 |
-
const
|
| 5900 |
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 5901 |
void open(
|
| 5902 |
const string& s,
|
| 5903 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5904 |
void open(
|
|
@@ -5921,18 +6472,18 @@ writing from named files. It uses a `basic_filebuf<charT, traits>`
|
|
| 5921 |
object to control the associated sequences. For the sake of exposition,
|
| 5922 |
the maintained data is presented here as:
|
| 5923 |
|
| 5924 |
- `sb`, the `basic_filebuf` object.
|
| 5925 |
|
| 5926 |
-
####
|
| 5927 |
|
| 5928 |
``` cpp
|
| 5929 |
basic_fstream();
|
| 5930 |
```
|
| 5931 |
|
| 5932 |
-
*Effects:*
|
| 5933 |
-
|
| 5934 |
`sb` with `basic_filebuf<charT, traits>()`.
|
| 5935 |
|
| 5936 |
``` cpp
|
| 5937 |
explicit basic_fstream(
|
| 5938 |
const char* s,
|
|
@@ -5940,12 +6491,12 @@ explicit basic_fstream(
|
|
| 5940 |
explicit basic_fstream(
|
| 5941 |
const filesystem::path::value_type* s,
|
| 5942 |
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
|
| 5943 |
```
|
| 5944 |
|
| 5945 |
-
*Effects:*
|
| 5946 |
-
|
| 5947 |
`sb` with `basic_filebuf<charT, traits>()`. Then calls
|
| 5948 |
`rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
|
| 5949 |
`setstate(failbit)`.
|
| 5950 |
|
| 5951 |
``` cpp
|
|
@@ -5955,31 +6506,22 @@ explicit basic_fstream(
|
|
| 5955 |
explicit basic_fstream(
|
| 5956 |
const filesystem::path& s,
|
| 5957 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5958 |
```
|
| 5959 |
|
| 5960 |
-
*Effects:*
|
| 5961 |
|
| 5962 |
``` cpp
|
| 5963 |
basic_fstream(basic_fstream&& rhs);
|
| 5964 |
```
|
| 5965 |
|
| 5966 |
-
*Effects:* Move constructs
|
| 5967 |
-
|
| 5968 |
-
|
| 5969 |
-
|
| 5970 |
|
| 5971 |
-
####
|
| 5972 |
-
|
| 5973 |
-
``` cpp
|
| 5974 |
-
basic_fstream& operator=(basic_fstream&& rhs);
|
| 5975 |
-
```
|
| 5976 |
-
|
| 5977 |
-
*Effects:* Move assigns the base and members of `*this` from the base
|
| 5978 |
-
and corresponding members of `rhs`.
|
| 5979 |
-
|
| 5980 |
-
*Returns:* `*this`.
|
| 5981 |
|
| 5982 |
``` cpp
|
| 5983 |
void swap(basic_fstream& rhs);
|
| 5984 |
```
|
| 5985 |
|
|
@@ -5990,19 +6532,19 @@ void swap(basic_fstream& rhs);
|
|
| 5990 |
template<class charT, class traits>
|
| 5991 |
void swap(basic_fstream<charT, traits>& x,
|
| 5992 |
basic_fstream<charT, traits>& y);
|
| 5993 |
```
|
| 5994 |
|
| 5995 |
-
*Effects:*
|
| 5996 |
|
| 5997 |
#### Member functions <a id="fstream.members">[[fstream.members]]</a>
|
| 5998 |
|
| 5999 |
``` cpp
|
| 6000 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6001 |
```
|
| 6002 |
|
| 6003 |
-
*Returns:* `const_cast<basic_filebuf<charT, traits>*>(
|
| 6004 |
|
| 6005 |
``` cpp
|
| 6006 |
bool is_open() const;
|
| 6007 |
```
|
| 6008 |
|
|
@@ -6018,11 +6560,11 @@ void open(
|
|
| 6018 |
```
|
| 6019 |
|
| 6020 |
*Effects:* Calls `rdbuf()->open(s, mode)`. If that function does not
|
| 6021 |
return a null pointer calls `clear()`, otherwise calls
|
| 6022 |
`setstate(failbit)` (which may throw
|
| 6023 |
-
`ios_base::failure`)
|
| 6024 |
|
| 6025 |
``` cpp
|
| 6026 |
void open(
|
| 6027 |
const string& s,
|
| 6028 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
|
@@ -6037,41 +6579,489 @@ void open(
|
|
| 6037 |
void close();
|
| 6038 |
```
|
| 6039 |
|
| 6040 |
*Effects:* Calls `rdbuf()->close()` and, if that function returns a null
|
| 6041 |
pointer, calls `setstate(failbit)` (which may throw
|
| 6042 |
-
`ios_base::failure`)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6043 |
|
| 6044 |
## File systems <a id="filesystems">[[filesystems]]</a>
|
| 6045 |
|
| 6046 |
### General <a id="fs.general">[[fs.general]]</a>
|
| 6047 |
|
| 6048 |
-
|
| 6049 |
-
components, such as paths, regular files, and directories.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6050 |
|
| 6051 |
### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
|
| 6052 |
|
| 6053 |
Conformance is specified in terms of behavior. Ideal behavior is not
|
| 6054 |
always implementable, so the conformance subclauses take that into
|
| 6055 |
account.
|
| 6056 |
|
| 6057 |
#### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
|
| 6058 |
|
| 6059 |
-
Some behavior is specified by reference to POSIX
|
| 6060 |
such behavior is actually implemented is unspecified.
|
| 6061 |
|
| 6062 |
[*Note 1*: This constitutes an “as if” rule allowing implementations to
|
| 6063 |
call native operating system or other APIs. — *end note*]
|
| 6064 |
|
| 6065 |
-
Implementations
|
| 6066 |
-
|
| 6067 |
-
|
| 6068 |
-
POSIX behavior
|
| 6069 |
-
|
| 6070 |
-
systems
|
| 6071 |
-
|
| 6072 |
-
|
| 6073 |
|
| 6074 |
[*Note 2*: This allows users to rely on an exception being thrown or an
|
| 6075 |
error code being set when an implementation cannot provide any
|
| 6076 |
reasonable behavior. — *end note*]
|
| 6077 |
|
|
@@ -6084,225 +7074,88 @@ other features of more capable file systems, so implementations are not
|
|
| 6084 |
required to support those features on the FAT file system but instead
|
| 6085 |
are required to report an error as described above. — *end example*]
|
| 6086 |
|
| 6087 |
#### Operating system dependent behavior conformance <a id="fs.conform.os">[[fs.conform.os]]</a>
|
| 6088 |
|
| 6089 |
-
|
| 6090 |
-
|
| 6091 |
-
|
|
|
|
| 6092 |
|
| 6093 |
It is permissible for an implementation to be dependent upon an
|
| 6094 |
operating system emulator rather than the actual underlying operating
|
| 6095 |
system.
|
| 6096 |
|
| 6097 |
#### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
|
| 6098 |
|
| 6099 |
-
|
| 6100 |
-
|
|
|
|
|
|
|
|
|
|
| 6101 |
|
| 6102 |
If the possibility of a file system race would make it unreliable for a
|
| 6103 |
program to test for a precondition before calling a function described
|
| 6104 |
-
herein, *
|
| 6105 |
|
| 6106 |
[*Note 1*: As a design practice, preconditions are not specified when
|
| 6107 |
it is unreasonable for a program to detect them prior to calling the
|
| 6108 |
function. — *end note*]
|
| 6109 |
|
| 6110 |
### Normative references <a id="fs.norm.ref">[[fs.norm.ref]]</a>
|
| 6111 |
|
| 6112 |
-
|
| 6113 |
-
purposes of exposition.[^41]
|
| 6114 |
-
|
| 6115 |
-
### Terms and definitions <a id="fs.definitions">[[fs.definitions]]</a>
|
| 6116 |
-
|
| 6117 |
-
A path that unambiguously identifies the location of a file without
|
| 6118 |
-
reference to an additional starting location. The elements of a path
|
| 6119 |
-
that determine if it is absolute are operating system dependent.
|
| 6120 |
-
|
| 6121 |
-
A file within a file system that acts as a container of directory
|
| 6122 |
-
entries that contain information about other files, possibly including
|
| 6123 |
-
other directory files.
|
| 6124 |
-
|
| 6125 |
-
An object within a file system that holds user or system data. Files can
|
| 6126 |
-
be written to, or read from, or both. A file has certain attributes,
|
| 6127 |
-
including type. File types include regular files and directories. Other
|
| 6128 |
-
types of files, such as symbolic links ([[fs.def.symlink]]), may be
|
| 6129 |
-
supported by the implementation.
|
| 6130 |
-
|
| 6131 |
-
A collection of files and their attributes.
|
| 6132 |
-
|
| 6133 |
-
The condition that occurs when multiple threads, processes, or computers
|
| 6134 |
-
interleave access and modification of the same object within a file
|
| 6135 |
-
system.
|
| 6136 |
-
|
| 6137 |
-
The name of a file. Filenames *dot* and *dot-dot*, consisting solely of
|
| 6138 |
-
one and two period characters respectively, have special meaning. The
|
| 6139 |
-
following characteristics of filenames are operating system dependent:
|
| 6140 |
-
|
| 6141 |
-
- The permitted characters. \[*Example 1*: Some operating systems
|
| 6142 |
-
prohibit the ASCII control characters (0x00 – 0x1F) in
|
| 6143 |
-
filenames. — *end example*]
|
| 6144 |
-
- The maximum permitted length.
|
| 6145 |
-
- Filenames that are not permitted.
|
| 6146 |
-
- Filenames that have special meaning.
|
| 6147 |
-
- Case awareness and sensitivity during path resolution.
|
| 6148 |
-
- Special rules that may apply to file types other than regular files,
|
| 6149 |
-
such as directories.
|
| 6150 |
-
|
| 6151 |
-
A link ([[fs.def.link]]) to an existing file. Some file systems support
|
| 6152 |
-
multiple hard links to a file. If the last hard link to a file is
|
| 6153 |
-
removed, the file itself is removed.
|
| 6154 |
-
|
| 6155 |
-
[*Note 1*: A hard link can be thought of as a shared-ownership smart
|
| 6156 |
-
pointer to a file. — *end note*]
|
| 6157 |
-
|
| 6158 |
-
An object that associates a filename with a file. Several links can
|
| 6159 |
-
associate names with the same file.
|
| 6160 |
-
|
| 6161 |
-
For narrow character strings, the operating system dependent current
|
| 6162 |
-
encoding for pathnames ([[fs.def.pathname]]). For wide character
|
| 6163 |
-
strings, the implementation-defined execution wide-character set
|
| 6164 |
-
encoding ([[lex.charset]]).
|
| 6165 |
-
|
| 6166 |
-
The operating system dependent pathname format accepted by the host
|
| 6167 |
-
operating system.
|
| 6168 |
-
|
| 6169 |
-
A path in normal form is said to be *normalized*. The process of
|
| 6170 |
-
obtaining a normalized path from a path that is not in normal form is
|
| 6171 |
-
called *normalization*.
|
| 6172 |
-
|
| 6173 |
-
Normalization of a generic format pathname means:
|
| 6174 |
-
|
| 6175 |
-
1. If the path is empty, stop.
|
| 6176 |
-
2. Replace each slash character in the *root-name* with a
|
| 6177 |
-
*preferred-separator*.
|
| 6178 |
-
3. Replace each *directory-separator* with a *preferred-separator*.
|
| 6179 |
-
\[*Note 2*: The generic pathname grammar ([[fs.path.generic]])
|
| 6180 |
-
defines *directory-separator* as one or more slashes and
|
| 6181 |
-
*preferred-separator*s. — *end note*]
|
| 6182 |
-
4. Remove each *dot* filename and any immediately following
|
| 6183 |
-
*directory-separator*.
|
| 6184 |
-
5. As long as any appear, remove a non-*dot-dot* filename immediately
|
| 6185 |
-
followed by a *directory-separator* and a *dot-dot* filename, along
|
| 6186 |
-
with any immediately following *directory-separator*.
|
| 6187 |
-
6. If there is a *root-directory*, remove all *dot-dot* filenames and
|
| 6188 |
-
any *directory-separator*s immediately following them.
|
| 6189 |
-
\[*Note 3*: These *dot-dot* filenames attempt to refer to
|
| 6190 |
-
nonexistent parent directories. — *end note*]
|
| 6191 |
-
7. If the last filename is *dot-dot*, remove any trailing
|
| 6192 |
-
*directory-separator*.
|
| 6193 |
-
8. If the path is empty, add a *dot*.
|
| 6194 |
-
|
| 6195 |
-
Behavior that is dependent upon the behavior and characteristics of an
|
| 6196 |
-
operating system. See [[fs.conform.os]].
|
| 6197 |
-
|
| 6198 |
-
the directory that both contains a directory entry for the given
|
| 6199 |
-
directory and is represented by the filename *dot-dot* in the given
|
| 6200 |
-
directory.
|
| 6201 |
-
|
| 6202 |
-
a directory containing a directory entry for the file under discussion.
|
| 6203 |
-
|
| 6204 |
-
A sequence of elements that identify the location of a file within a
|
| 6205 |
-
filesystem. The elements are the *root-name*ₒₚₜ , *root-directory*ₒₚₜ ,
|
| 6206 |
-
and an optional sequence of filenames. The maximum number of elements in
|
| 6207 |
-
the sequence is operating system dependent.
|
| 6208 |
-
|
| 6209 |
-
A character string that represents the name of a path. Pathnames are
|
| 6210 |
-
formatted according to the generic pathname format grammar (
|
| 6211 |
-
[[fs.path.generic]]) or an operating system dependent native pathname
|
| 6212 |
-
format.
|
| 6213 |
-
|
| 6214 |
-
Pathname resolution is the operating system dependent mechanism for
|
| 6215 |
-
resolving a pathname to a particular file in a file hierarchy. There may
|
| 6216 |
-
be multiple pathnames that resolve to the same file.
|
| 6217 |
-
|
| 6218 |
-
[*Example 2*: POSIX specifies the mechanism in section 4.11, Pathname
|
| 6219 |
-
resolution. — *end example*]
|
| 6220 |
-
|
| 6221 |
-
A path that is not absolute, and as such, only unambiguously identifies
|
| 6222 |
-
the location of a file when resolved ([[fs.def.pathres]]) relative to
|
| 6223 |
-
an implied starting location. The elements of a path that determine if
|
| 6224 |
-
it is relative are operating system dependent.
|
| 6225 |
-
|
| 6226 |
-
[*Note 4*: Pathnames “.” and “..” are relative paths. — *end note*]
|
| 6227 |
-
|
| 6228 |
-
A type of file with the property that when the file is encountered
|
| 6229 |
-
during pathname resolution, a string stored by the file is used to
|
| 6230 |
-
modify the pathname resolution.
|
| 6231 |
-
|
| 6232 |
-
[*Note 5*: Symbolic links are often called symlinks. A symbolic link
|
| 6233 |
-
can be thought of as a raw pointer to a file. If the file pointed to
|
| 6234 |
-
does not exist, the symbolic link is said to be a “dangling” symbolic
|
| 6235 |
-
link. — *end note*]
|
| 6236 |
|
| 6237 |
### Requirements <a id="fs.req">[[fs.req]]</a>
|
| 6238 |
|
| 6239 |
-
Throughout
|
| 6240 |
-
are collectively called *encoded character
|
|
|
|
| 6241 |
|
| 6242 |
Functions with template parameters named `EcharT` shall not participate
|
| 6243 |
in overload resolution unless `EcharT` is one of the encoded character
|
| 6244 |
types.
|
| 6245 |
|
| 6246 |
-
Template parameters named `InputIterator` shall meet the
|
| 6247 |
-
requirements
|
| 6248 |
-
one of the encoded character types.
|
| 6249 |
|
| 6250 |
[*Note 1*: Use of an encoded character type implies an associated
|
| 6251 |
character set and encoding. Since `signed char` and `unsigned char` have
|
| 6252 |
no implied character set and encoding, they are not included as
|
| 6253 |
permitted types. — *end note*]
|
| 6254 |
|
| 6255 |
-
Template parameters named `Allocator` shall meet the
|
| 6256 |
-
requirements
|
| 6257 |
|
| 6258 |
#### Namespaces and headers <a id="fs.req.namespace">[[fs.req.namespace]]</a>
|
| 6259 |
|
| 6260 |
-
Unless otherwise specified, references to entities described in
|
| 6261 |
-
subclause are assumed to be qualified with
|
|
|
|
| 6262 |
|
| 6263 |
### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
|
| 6264 |
|
| 6265 |
``` cpp
|
|
|
|
|
|
|
| 6266 |
namespace std::filesystem {
|
| 6267 |
// [fs.class.path], paths
|
| 6268 |
class path;
|
| 6269 |
|
| 6270 |
// [fs.path.nonmember], path non-member functions
|
| 6271 |
void swap(path& lhs, path& rhs) noexcept;
|
| 6272 |
size_t hash_value(const path& p) noexcept;
|
| 6273 |
|
| 6274 |
-
|
| 6275 |
-
bool operator!=(const path& lhs, const path& rhs) noexcept;
|
| 6276 |
-
bool operator< (const path& lhs, const path& rhs) noexcept;
|
| 6277 |
-
bool operator<=(const path& lhs, const path& rhs) noexcept;
|
| 6278 |
-
bool operator> (const path& lhs, const path& rhs) noexcept;
|
| 6279 |
-
bool operator>=(const path& lhs, const path& rhs) noexcept;
|
| 6280 |
-
|
| 6281 |
-
path operator/ (const path& lhs, const path& rhs);
|
| 6282 |
-
|
| 6283 |
-
// [fs.path.io], path inserter and extractor
|
| 6284 |
-
template <class charT, class traits>
|
| 6285 |
-
basic_ostream<charT, traits>&
|
| 6286 |
-
operator<<(basic_ostream<charT, traits>& os, const path& p);
|
| 6287 |
-
template <class charT, class traits>
|
| 6288 |
-
basic_istream<charT, traits>&
|
| 6289 |
-
operator>>(basic_istream<charT, traits>& is, path& p);
|
| 6290 |
-
|
| 6291 |
-
// [fs.path.factory], path factory functions
|
| 6292 |
-
template <class Source>
|
| 6293 |
-
path u8path(const Source& source);
|
| 6294 |
-
template <class InputIterator>
|
| 6295 |
-
path u8path(InputIterator first, InputIterator last);
|
| 6296 |
-
|
| 6297 |
-
// [fs.class.filesystem_error], filesystem errors
|
| 6298 |
class filesystem_error;
|
| 6299 |
|
| 6300 |
-
// [fs.class.
|
| 6301 |
class directory_entry;
|
| 6302 |
|
| 6303 |
-
// [fs.class.
|
| 6304 |
class directory_iterator;
|
| 6305 |
|
| 6306 |
// [fs.dir.itr.nonmembers], range access for directory iterators
|
| 6307 |
directory_iterator begin(directory_iterator iter) noexcept;
|
| 6308 |
directory_iterator end(const directory_iterator&) noexcept;
|
|
@@ -6312,53 +7165,55 @@ namespace std::filesystem {
|
|
| 6312 |
|
| 6313 |
// [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
|
| 6314 |
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 6315 |
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
|
| 6316 |
|
| 6317 |
-
// [fs.class.
|
| 6318 |
class file_status;
|
| 6319 |
|
| 6320 |
struct space_info {
|
| 6321 |
uintmax_t capacity;
|
| 6322 |
uintmax_t free;
|
| 6323 |
uintmax_t available;
|
|
|
|
|
|
|
| 6324 |
};
|
| 6325 |
|
| 6326 |
// [fs.enum], enumerations
|
| 6327 |
enum class file_type;
|
| 6328 |
enum class perms;
|
| 6329 |
enum class perm_options;
|
| 6330 |
enum class copy_options;
|
| 6331 |
enum class directory_options;
|
| 6332 |
|
| 6333 |
-
using file_time_type = chrono::time_point<
|
| 6334 |
|
| 6335 |
// [fs.op.funcs], filesystem operations
|
| 6336 |
-
path absolute(const path& p
|
|
|
|
| 6337 |
|
| 6338 |
-
path canonical(const path& p
|
| 6339 |
path canonical(const path& p, error_code& ec);
|
| 6340 |
-
path canonical(const path& p, const path& base, error_code& ec);
|
| 6341 |
|
| 6342 |
void copy(const path& from, const path& to);
|
| 6343 |
-
void copy(const path& from, const path& to, error_code& ec)
|
| 6344 |
void copy(const path& from, const path& to, copy_options options);
|
| 6345 |
void copy(const path& from, const path& to, copy_options options,
|
| 6346 |
-
error_code& ec)
|
| 6347 |
|
| 6348 |
bool copy_file(const path& from, const path& to);
|
| 6349 |
-
bool copy_file(const path& from, const path& to, error_code& ec)
|
| 6350 |
bool copy_file(const path& from, const path& to, copy_options option);
|
| 6351 |
bool copy_file(const path& from, const path& to, copy_options option,
|
| 6352 |
-
error_code& ec)
|
| 6353 |
|
| 6354 |
void copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 6355 |
void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 6356 |
error_code& ec) noexcept;
|
| 6357 |
|
| 6358 |
bool create_directories(const path& p);
|
| 6359 |
-
bool create_directories(const path& p, error_code& ec)
|
| 6360 |
|
| 6361 |
bool create_directory(const path& p);
|
| 6362 |
bool create_directory(const path& p, error_code& ec) noexcept;
|
| 6363 |
|
| 6364 |
bool create_directory(const path& p, const path& attributes);
|
|
@@ -6380,17 +7235,17 @@ namespace std::filesystem {
|
|
| 6380 |
path current_path();
|
| 6381 |
path current_path(error_code& ec);
|
| 6382 |
void current_path(const path& p);
|
| 6383 |
void current_path(const path& p, error_code& ec) noexcept;
|
| 6384 |
|
|
|
|
|
|
|
|
|
|
| 6385 |
bool exists(file_status s) noexcept;
|
| 6386 |
bool exists(const path& p);
|
| 6387 |
bool exists(const path& p, error_code& ec) noexcept;
|
| 6388 |
|
| 6389 |
-
bool equivalent(const path& p1, const path& p2);
|
| 6390 |
-
bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 6391 |
-
|
| 6392 |
uintmax_t file_size(const path& p);
|
| 6393 |
uintmax_t file_size(const path& p, error_code& ec) noexcept;
|
| 6394 |
|
| 6395 |
uintmax_t hard_link_count(const path& p);
|
| 6396 |
uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
|
@@ -6406,11 +7261,11 @@ namespace std::filesystem {
|
|
| 6406 |
bool is_directory(file_status s) noexcept;
|
| 6407 |
bool is_directory(const path& p);
|
| 6408 |
bool is_directory(const path& p, error_code& ec) noexcept;
|
| 6409 |
|
| 6410 |
bool is_empty(const path& p);
|
| 6411 |
-
bool is_empty(const path& p, error_code& ec)
|
| 6412 |
|
| 6413 |
bool is_fifo(file_status s) noexcept;
|
| 6414 |
bool is_fifo(const path& p);
|
| 6415 |
bool is_fifo(const path& p, error_code& ec) noexcept;
|
| 6416 |
|
|
@@ -6453,11 +7308,11 @@ namespace std::filesystem {
|
|
| 6453 |
|
| 6454 |
bool remove(const path& p);
|
| 6455 |
bool remove(const path& p, error_code& ec) noexcept;
|
| 6456 |
|
| 6457 |
uintmax_t remove_all(const path& p);
|
| 6458 |
-
uintmax_t remove_all(const path& p, error_code& ec)
|
| 6459 |
|
| 6460 |
void rename(const path& from, const path& to);
|
| 6461 |
void rename(const path& from, const path& to, error_code& ec) noexcept;
|
| 6462 |
|
| 6463 |
void resize_file(const path& p, uintmax_t size);
|
|
@@ -6480,15 +7335,13 @@ namespace std::filesystem {
|
|
| 6480 |
path weakly_canonical(const path& p);
|
| 6481 |
path weakly_canonical(const path& p, error_code& ec);
|
| 6482 |
}
|
| 6483 |
```
|
| 6484 |
|
| 6485 |
-
|
| 6486 |
-
`
|
| 6487 |
-
|
| 6488 |
-
ensure that the resolution and range of `file_time_type` reflect the
|
| 6489 |
-
operating system dependent resolution and range of file time values.
|
| 6490 |
|
| 6491 |
### Error reporting <a id="fs.err.report">[[fs.err.report]]</a>
|
| 6492 |
|
| 6493 |
Filesystem library functions often provide two overloads, one that
|
| 6494 |
throws an exception to report file system errors, and another that sets
|
|
@@ -6534,22 +7387,49 @@ follows, unless otherwise specified:
|
|
| 6534 |
appropriate for the specific operating system dependent error.
|
| 6535 |
Otherwise, `clear()` is called on the `error_code&` argument.
|
| 6536 |
|
| 6537 |
### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
|
| 6538 |
|
| 6539 |
-
An object of class `path` represents a path
|
| 6540 |
-
|
| 6541 |
-
|
| 6542 |
-
|
| 6543 |
-
|
| 6544 |
-
file system.
|
| 6545 |
|
| 6546 |
[*Note 1*: Class `path` is used to support the differences between the
|
| 6547 |
string types used by different operating systems to represent pathnames,
|
| 6548 |
and to perform conversions between encodings when
|
| 6549 |
necessary. — *end note*]
|
| 6550 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6551 |
``` cpp
|
| 6552 |
namespace std::filesystem {
|
| 6553 |
class path {
|
| 6554 |
public:
|
| 6555 |
using value_type = see below;
|
|
@@ -6580,11 +7460,11 @@ namespace std::filesystem {
|
|
| 6580 |
path& operator=(string_type&& source);
|
| 6581 |
path& assign(string_type&& source);
|
| 6582 |
template<class Source>
|
| 6583 |
path& operator=(const Source& source);
|
| 6584 |
template<class Source>
|
| 6585 |
-
path& assign(const Source& source)
|
| 6586 |
template<class InputIterator>
|
| 6587 |
path& assign(InputIterator first, InputIterator last);
|
| 6588 |
|
| 6589 |
// [fs.path.append], appends
|
| 6590 |
path& operator/=(const path& p);
|
|
@@ -6616,10 +7496,16 @@ namespace std::filesystem {
|
|
| 6616 |
path& remove_filename();
|
| 6617 |
path& replace_filename(const path& replacement);
|
| 6618 |
path& replace_extension(const path& replacement = path());
|
| 6619 |
void swap(path& rhs) noexcept;
|
| 6620 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6621 |
// [fs.path.native.obs], native format observers
|
| 6622 |
const string_type& native() const noexcept;
|
| 6623 |
const value_type* c_str() const noexcept;
|
| 6624 |
operator string_type() const;
|
| 6625 |
|
|
@@ -6627,22 +7513,22 @@ namespace std::filesystem {
|
|
| 6627 |
class Allocator = allocator<EcharT>>
|
| 6628 |
basic_string<EcharT, traits, Allocator>
|
| 6629 |
string(const Allocator& a = Allocator()) const;
|
| 6630 |
std::string string() const;
|
| 6631 |
std::wstring wstring() const;
|
| 6632 |
-
std::
|
| 6633 |
std::u16string u16string() const;
|
| 6634 |
std::u32string u32string() const;
|
| 6635 |
|
| 6636 |
// [fs.path.generic.obs], generic format observers
|
| 6637 |
template<class EcharT, class traits = char_traits<EcharT>,
|
| 6638 |
class Allocator = allocator<EcharT>>
|
| 6639 |
basic_string<EcharT, traits, Allocator>
|
| 6640 |
generic_string(const Allocator& a = Allocator()) const;
|
| 6641 |
std::string generic_string() const;
|
| 6642 |
std::wstring generic_wstring() const;
|
| 6643 |
-
std::
|
| 6644 |
std::u16string generic_u16string() const;
|
| 6645 |
std::u32string generic_u32string() const;
|
| 6646 |
|
| 6647 |
// [fs.path.compare], compare
|
| 6648 |
int compare(const path& p) const noexcept;
|
|
@@ -6659,11 +7545,11 @@ namespace std::filesystem {
|
|
| 6659 |
path filename() const;
|
| 6660 |
path stem() const;
|
| 6661 |
path extension() const;
|
| 6662 |
|
| 6663 |
// [fs.path.query], query
|
| 6664 |
-
bool empty() const noexcept;
|
| 6665 |
bool has_root_name() const;
|
| 6666 |
bool has_root_directory() const;
|
| 6667 |
bool has_root_path() const;
|
| 6668 |
bool has_relative_path() const;
|
| 6669 |
bool has_parent_path() const;
|
|
@@ -6682,21 +7568,29 @@ namespace std::filesystem {
|
|
| 6682 |
class iterator;
|
| 6683 |
using const_iterator = iterator;
|
| 6684 |
|
| 6685 |
iterator begin() const;
|
| 6686 |
iterator end() const;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6687 |
};
|
| 6688 |
}
|
| 6689 |
```
|
| 6690 |
|
| 6691 |
`value_type` is a `typedef` for the operating system dependent encoded
|
| 6692 |
character type used to represent pathnames.
|
| 6693 |
|
| 6694 |
The value of the `preferred_separator` member is the operating system
|
| 6695 |
-
dependent *preferred-separator* character
|
| 6696 |
|
| 6697 |
-
[*Example
|
| 6698 |
and `preferred_separator` is the slash character (`'/'`). For
|
| 6699 |
Windows-based operating systems, `value_type` is `wchar_t` and
|
| 6700 |
`preferred_separator` is the backslash character
|
| 6701 |
(`L'\\'`). — *end example*]
|
| 6702 |
|
|
@@ -6744,31 +7638,42 @@ preferred-separator:
|
|
| 6744 |
``` bnf
|
| 6745 |
fallback-separator:
|
| 6746 |
/, if *preferred-separator* is not /
|
| 6747 |
```
|
| 6748 |
|
| 6749 |
-
|
| 6750 |
-
|
| 6751 |
-
|
| 6752 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6753 |
`A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
|
| 6754 |
`a b c d e f g h i j k l m n o p q r s t u v w x y z`
|
| 6755 |
`0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6756 |
|
| 6757 |
Except in a *root-name*, multiple successive *directory-separator*
|
| 6758 |
characters are considered to be the same as one *directory-separator*
|
| 6759 |
character.
|
| 6760 |
|
| 6761 |
-
The
|
| 6762 |
-
|
| 6763 |
-
|
| 6764 |
-
*dot-dot* refers to relative to *root-directory* is
|
| 6765 |
*implementation-defined*. Specific filenames may have special meanings
|
| 6766 |
for a particular operating system.
|
| 6767 |
|
| 6768 |
-
A *root-name* identifies the starting location for pathname resolution
|
| 6769 |
-
[[fs.
|
| 6770 |
*root-name*s, at least one *implementation-defined* *root-name* is
|
| 6771 |
required.
|
| 6772 |
|
| 6773 |
[*Note 2*: Many operating systems define a name beginning with two
|
| 6774 |
*directory-separator* characters as a *root-name* that identifies
|
|
@@ -6781,17 +7686,42 @@ longest sequence of characters is chosen.
|
|
| 6781 |
|
| 6782 |
[*Note 3*: On a POSIX-like operating system, it is impossible to have a
|
| 6783 |
*root-name* and a *relative-path* without an intervening
|
| 6784 |
*root-directory* element. — *end note*]
|
| 6785 |
|
| 6786 |
-
|
| 6787 |
|
| 6788 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6789 |
|
| 6790 |
[*Note 1*:
|
| 6791 |
|
| 6792 |
-
The format conversions described in this
|
| 6793 |
POSIX-based operating systems because on these systems:
|
| 6794 |
|
| 6795 |
- The generic format is acceptable as a native path.
|
| 6796 |
- There is no need to distinguish between native format and generic
|
| 6797 |
format in function arguments.
|
|
@@ -6800,15 +7730,15 @@ POSIX-based operating systems because on these systems:
|
|
| 6800 |
|
| 6801 |
— *end note*]
|
| 6802 |
|
| 6803 |
Several functions are defined to accept *detected-format* arguments,
|
| 6804 |
which are character sequences. A detected-format argument represents a
|
| 6805 |
-
path using either a pathname in the generic format
|
| 6806 |
-
|
| 6807 |
-
|
| 6808 |
-
format
|
| 6809 |
-
|
| 6810 |
|
| 6811 |
[*Note 2*: Some operating systems may have no unambiguous way to
|
| 6812 |
distinguish between native format and generic format arguments. This is
|
| 6813 |
by design as it simplifies use for operating systems that do not require
|
| 6814 |
disambiguation. An implementation for an operating system where
|
|
@@ -6827,12 +7757,12 @@ native-to-generic and generic-to-native formats respectively. If
|
|
| 6827 |
If the native format requires paths for regular files to be formatted
|
| 6828 |
differently from paths for directories, the path shall be treated as a
|
| 6829 |
directory path if its last element is a *directory-separator*, otherwise
|
| 6830 |
it shall be treated as a path to a regular file.
|
| 6831 |
|
| 6832 |
-
[*Note 4*: A path stores a native format pathname
|
| 6833 |
-
[[fs.path.native.obs]]
|
| 6834 |
pathname, related as given below. The implementation may generate the
|
| 6835 |
generic format pathname based on the native format pathname (and
|
| 6836 |
possibly other information) when requested. — *end note*]
|
| 6837 |
|
| 6838 |
When a path is constructed from or is assigned a single representation
|
|
@@ -6845,95 +7775,101 @@ the other representation. The value *q* converts to *p* (by *G* or *N*
|
|
| 6845 |
as appropriate) if any such value does so; *q* is otherwise unspecified.
|
| 6846 |
|
| 6847 |
[*Note 5*: If *q* is the result of converting any path at all, it is
|
| 6848 |
the result of converting *p*. — *end note*]
|
| 6849 |
|
| 6850 |
-
#####
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6851 |
|
| 6852 |
For member function arguments that take character sequences representing
|
| 6853 |
paths and for member functions returning strings, value type and
|
| 6854 |
encoding conversion is performed if the value type of the argument or
|
| 6855 |
return value differs from `path::value_type`. For the argument or return
|
| 6856 |
value, the method of conversion and the encoding to be converted to is
|
| 6857 |
determined by its value type:
|
| 6858 |
|
| 6859 |
-
- `char`: The encoding is the native
|
| 6860 |
-
|
| 6861 |
-
operating
|
| 6862 |
-
|
| 6863 |
-
|
| 6864 |
-
|
| 6865 |
-
encoding is determined by calling a Windows API
|
| 6866 |
function. — *end note*] \[*Note 7*: This results in behavior
|
| 6867 |
identical to other C and C++ standard library functions that perform
|
| 6868 |
-
file operations using
|
| 6869 |
Changing this behavior would be surprising and error
|
| 6870 |
prone. — *end note*]
|
| 6871 |
-
- `wchar_t`: The encoding is the native wide encoding
|
| 6872 |
-
|
| 6873 |
-
|
| 6874 |
-
`wchar_t`
|
| 6875 |
-
|
|
|
|
|
|
|
| 6876 |
- `char16_t`: The encoding is UTF-16. The method of conversion is
|
| 6877 |
unspecified.
|
| 6878 |
- `char32_t`: The encoding is UTF-32. The method of conversion is
|
| 6879 |
unspecified.
|
| 6880 |
|
| 6881 |
If the encoding being converted to has no representation for source
|
| 6882 |
characters, the resulting converted characters, if any, are unspecified.
|
| 6883 |
Implementations should not modify member function arguments if already
|
| 6884 |
of type `path::value_type`.
|
| 6885 |
|
| 6886 |
-
####
|
| 6887 |
|
| 6888 |
-
In addition to the requirements
|
| 6889 |
-
|
| 6890 |
|
| 6891 |
- `basic_string<EcharT, traits, Allocator>`. A function argument
|
| 6892 |
`const Source&` `source` shall have an effective range
|
| 6893 |
\[`source.begin()`, `source.end()`).
|
| 6894 |
- `basic_string_view<EcharT, traits>`. A function argument
|
| 6895 |
`const Source&` `source` shall have an effective range
|
| 6896 |
\[`source.begin()`, `source.end()`).
|
| 6897 |
-
- A type meeting the
|
| 6898 |
-
NTCTS. The value type shall be an encoded character type. A
|
| 6899 |
-
argument `const Source&` `source` shall have an effective
|
| 6900 |
-
\[`source`, `end`) where `end` is the first iterator value with
|
| 6901 |
-
element value equal to `iterator_traits<Source>::value_type()`.
|
| 6902 |
- A character array that after array-to-pointer decay results in a
|
| 6903 |
pointer to the start of a NTCTS. The value type shall be an encoded
|
| 6904 |
character type. A function argument `const Source&` `source` shall
|
| 6905 |
have an effective range \[`source`, `end`) where `end` is the first
|
| 6906 |
iterator value with an element value equal to
|
| 6907 |
`iterator_traits<decay_t<Source>>::value_type()`.
|
| 6908 |
|
| 6909 |
Functions taking template parameters named `Source` shall not
|
| 6910 |
-
participate in overload resolution unless
|
|
|
|
| 6911 |
|
| 6912 |
- `Source` is a specialization of `basic_string` or `basic_string_view`,
|
| 6913 |
or
|
| 6914 |
- the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
|
| 6915 |
-
valid and denotes a possibly `const` encoded character type
|
| 6916 |
-
[[temp.deduct]]
|
| 6917 |
|
| 6918 |
-
[*Note 1*: See path conversions
|
| 6919 |
-
|
| 6920 |
encoding. — *end note*]
|
| 6921 |
|
| 6922 |
Arguments of type `Source` shall not be null pointers.
|
| 6923 |
|
| 6924 |
-
####
|
| 6925 |
|
| 6926 |
-
#####
|
| 6927 |
|
| 6928 |
``` cpp
|
| 6929 |
path() noexcept;
|
| 6930 |
```
|
| 6931 |
|
| 6932 |
-
*
|
| 6933 |
-
|
| 6934 |
-
*Postconditions:* `empty() == true`.
|
| 6935 |
|
| 6936 |
``` cpp
|
| 6937 |
path(const path& p);
|
| 6938 |
path(path&& p) noexcept;
|
| 6939 |
```
|
|
@@ -6946,49 +7882,48 @@ state.
|
|
| 6946 |
``` cpp
|
| 6947 |
path(string_type&& source, format fmt = auto_format);
|
| 6948 |
```
|
| 6949 |
|
| 6950 |
*Effects:* Constructs an object of class `path` for which the pathname
|
| 6951 |
-
in the detected-format of `source` has the original value of
|
| 6952 |
-
|
| 6953 |
-
|
| 6954 |
-
unspecified state.
|
| 6955 |
|
| 6956 |
``` cpp
|
| 6957 |
template<class Source>
|
| 6958 |
path(const Source& source, format fmt = auto_format);
|
| 6959 |
template<class InputIterator>
|
| 6960 |
path(InputIterator first, InputIterator last, format fmt = auto_format);
|
| 6961 |
```
|
| 6962 |
|
| 6963 |
-
*Effects:* Let `s` be the effective range of `source`
|
| 6964 |
-
|
| 6965 |
-
required
|
| 6966 |
-
|
| 6967 |
-
|
| 6968 |
|
| 6969 |
``` cpp
|
| 6970 |
template<class Source>
|
| 6971 |
path(const Source& source, const locale& loc, format fmt = auto_format);
|
| 6972 |
template<class InputIterator>
|
| 6973 |
path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
|
| 6974 |
```
|
| 6975 |
|
| 6976 |
-
*
|
| 6977 |
|
| 6978 |
*Effects:* Let `s` be the effective range of `source` or the range
|
| 6979 |
\[`first`, `last`), after converting the encoding as follows:
|
| 6980 |
|
| 6981 |
- If `value_type` is `wchar_t`, converts to the native wide
|
| 6982 |
-
encoding
|
| 6983 |
`codecvt<wchar_t, char, mbstate_t>` facet of `loc`.
|
| 6984 |
- Otherwise a conversion is performed using the
|
| 6985 |
`codecvt<wchar_t, char, mbstate_t>` facet of `loc`, and then a second
|
| 6986 |
-
conversion to the current
|
| 6987 |
|
| 6988 |
-
Finds the detected-format of `s`
|
| 6989 |
-
|
| 6990 |
|
| 6991 |
[*Example 1*:
|
| 6992 |
|
| 6993 |
A string is to be read from a database that is encoded in ISO/IEC
|
| 6994 |
8859-1, and used to create a directory:
|
|
@@ -7002,27 +7937,27 @@ fs::create_directory(fs::path(latin1_string, latin1_locale));
|
|
| 7002 |
```
|
| 7003 |
|
| 7004 |
For POSIX-based operating systems, the path is constructed by first
|
| 7005 |
using `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string`
|
| 7006 |
to a wide character string in the native wide
|
| 7007 |
-
encoding
|
| 7008 |
-
converted to
|
| 7009 |
-
|
| 7010 |
-
the current native
|
| 7011 |
the ISO/IEC 8859-1 character set will be converted to their Unicode
|
| 7012 |
-
representation, but for other native
|
| 7013 |
may have no representation.
|
| 7014 |
|
| 7015 |
For Windows-based operating systems, the path is constructed by using
|
| 7016 |
`latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string` to a
|
| 7017 |
UTF-16 encoded wide character pathname string. All of the characters in
|
| 7018 |
the ISO/IEC 8859-1 character set will be converted to their Unicode
|
| 7019 |
representation.
|
| 7020 |
|
| 7021 |
— *end example*]
|
| 7022 |
|
| 7023 |
-
#####
|
| 7024 |
|
| 7025 |
``` cpp
|
| 7026 |
path& operator=(const path& p);
|
| 7027 |
```
|
| 7028 |
|
|
@@ -7062,18 +7997,18 @@ template <class Source>
|
|
| 7062 |
path& assign(const Source& source);
|
| 7063 |
template<class InputIterator>
|
| 7064 |
path& assign(InputIterator first, InputIterator last);
|
| 7065 |
```
|
| 7066 |
|
| 7067 |
-
*Effects:* Let `s` be the effective range of `source`
|
| 7068 |
-
|
| 7069 |
-
required
|
| 7070 |
-
|
| 7071 |
|
| 7072 |
*Returns:* `*this`.
|
| 7073 |
|
| 7074 |
-
#####
|
| 7075 |
|
| 7076 |
The append operations use `operator/=` to denote their semantic effect
|
| 7077 |
of appending *preferred-separator* when needed.
|
| 7078 |
|
| 7079 |
``` cpp
|
|
@@ -7096,26 +8031,28 @@ Otherwise, modifies `*this` as if by these steps:
|
|
| 7096 |
pathname.
|
| 7097 |
|
| 7098 |
[*Example 2*:
|
| 7099 |
|
| 7100 |
Even if `//host` is interpreted as a *root-name*, both of the paths
|
| 7101 |
-
`path("//host")/"foo"` and `path("//host/")/"foo"` equal `"//host/foo"`
|
|
|
|
| 7102 |
|
| 7103 |
Expression examples:
|
| 7104 |
|
| 7105 |
``` cpp
|
| 7106 |
// On POSIX,
|
| 7107 |
-
path("foo") / "";
|
| 7108 |
-
path("foo") / "/bar";
|
| 7109 |
-
// On Windows, backslashes replace slashes in the above yields
|
| 7110 |
|
| 7111 |
// On Windows,
|
| 7112 |
-
path("foo") / "
|
| 7113 |
-
path("foo") / "
|
| 7114 |
-
path("
|
| 7115 |
-
path("
|
| 7116 |
-
path("c:
|
|
|
|
|
|
|
| 7117 |
```
|
| 7118 |
|
| 7119 |
— *end example*]
|
| 7120 |
|
| 7121 |
*Returns:* `*this`.
|
|
@@ -7134,22 +8071,19 @@ template <class InputIterator>
|
|
| 7134 |
path& append(InputIterator first, InputIterator last);
|
| 7135 |
```
|
| 7136 |
|
| 7137 |
*Effects:* Equivalent to: `return operator/=(path(first, last));`
|
| 7138 |
|
| 7139 |
-
#####
|
| 7140 |
|
| 7141 |
``` cpp
|
| 7142 |
path& operator+=(const path& x);
|
| 7143 |
path& operator+=(const string_type& x);
|
| 7144 |
path& operator+=(basic_string_view<value_type> x);
|
| 7145 |
path& operator+=(const value_type* x);
|
| 7146 |
-
path& operator+=(value_type x);
|
| 7147 |
template<class Source>
|
| 7148 |
path& operator+=(const Source& x);
|
| 7149 |
-
template <class EcharT>
|
| 7150 |
-
path& operator+=(EcharT x);
|
| 7151 |
template<class Source>
|
| 7152 |
path& concat(const Source& x);
|
| 7153 |
```
|
| 7154 |
|
| 7155 |
*Effects:* Appends `path(x).native()` to the pathname in the native
|
|
@@ -7158,24 +8092,32 @@ format.
|
|
| 7158 |
[*Note 2*: This directly manipulates the value of `native()` and may
|
| 7159 |
not be portable between operating systems. — *end note*]
|
| 7160 |
|
| 7161 |
*Returns:* `*this`.
|
| 7162 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7163 |
``` cpp
|
| 7164 |
template<class InputIterator>
|
| 7165 |
path& concat(InputIterator first, InputIterator last);
|
| 7166 |
```
|
| 7167 |
|
| 7168 |
-
*Effects:* Equivalent to `return *this += path(first, last)`
|
| 7169 |
|
| 7170 |
-
#####
|
| 7171 |
|
| 7172 |
``` cpp
|
| 7173 |
void clear() noexcept;
|
| 7174 |
```
|
| 7175 |
|
| 7176 |
-
*
|
| 7177 |
|
| 7178 |
``` cpp
|
| 7179 |
path& make_preferred();
|
| 7180 |
```
|
| 7181 |
|
|
@@ -7213,15 +8155,15 @@ output is:
|
|
| 7213 |
|
| 7214 |
``` cpp
|
| 7215 |
path& remove_filename();
|
| 7216 |
```
|
| 7217 |
|
| 7218 |
-
*Postconditions:* `!has_filename()`.
|
| 7219 |
-
|
| 7220 |
*Effects:* Remove the generic format pathname of `filename()` from the
|
| 7221 |
generic format pathname.
|
| 7222 |
|
|
|
|
|
|
|
| 7223 |
*Returns:* `*this`.
|
| 7224 |
|
| 7225 |
[*Example 4*:
|
| 7226 |
|
| 7227 |
``` cpp
|
|
@@ -7259,12 +8201,12 @@ path("/").replace_filename("bar"); // yields "/bar" on POSIX
|
|
| 7259 |
path& replace_extension(const path& replacement = path());
|
| 7260 |
```
|
| 7261 |
|
| 7262 |
*Effects:*
|
| 7263 |
|
| 7264 |
-
- Any existing `extension()
|
| 7265 |
-
|
| 7266 |
- If `replacement` is not empty and does not begin with a dot character,
|
| 7267 |
a dot character is appended to the pathname in the generic format,
|
| 7268 |
then
|
| 7269 |
- `operator+=(replacement);`.
|
| 7270 |
|
|
@@ -7276,14 +8218,14 @@ void swap(path& rhs) noexcept;
|
|
| 7276 |
|
| 7277 |
*Effects:* Swaps the contents (in all formats) of the two paths.
|
| 7278 |
|
| 7279 |
*Complexity:* Constant time.
|
| 7280 |
|
| 7281 |
-
#####
|
| 7282 |
|
| 7283 |
The string returned by all native format observers is in the native
|
| 7284 |
-
pathname format
|
| 7285 |
|
| 7286 |
``` cpp
|
| 7287 |
const string_type& native() const noexcept;
|
| 7288 |
```
|
| 7289 |
|
|
@@ -7291,11 +8233,11 @@ const string_type& native() const noexcept;
|
|
| 7291 |
|
| 7292 |
``` cpp
|
| 7293 |
const value_type* c_str() const noexcept;
|
| 7294 |
```
|
| 7295 |
|
| 7296 |
-
*
|
| 7297 |
|
| 7298 |
``` cpp
|
| 7299 |
operator string_type() const;
|
| 7300 |
```
|
| 7301 |
|
|
@@ -7319,26 +8261,25 @@ be performed by `a`. Conversion, if any, is specified by
|
|
| 7319 |
[[fs.path.cvt]].
|
| 7320 |
|
| 7321 |
``` cpp
|
| 7322 |
std::string string() const;
|
| 7323 |
std::wstring wstring() const;
|
| 7324 |
-
std::
|
| 7325 |
std::u16string u16string() const;
|
| 7326 |
std::u32string u32string() const;
|
| 7327 |
```
|
| 7328 |
|
| 7329 |
-
*Returns:* `
|
| 7330 |
|
| 7331 |
*Remarks:* Conversion, if any, is performed as specified by
|
| 7332 |
-
[[fs.path.cvt]].
|
| 7333 |
-
always UTF-8.
|
| 7334 |
|
| 7335 |
-
#####
|
| 7336 |
|
| 7337 |
Generic format observer functions return strings formatted according to
|
| 7338 |
-
the generic pathname format
|
| 7339 |
-
|
| 7340 |
|
| 7341 |
[*Example 1*:
|
| 7342 |
|
| 7343 |
On an operating system that uses backslash as its *preferred-separator*,
|
| 7344 |
|
|
@@ -7364,53 +8305,51 @@ be performed by `a`. Conversion, if any, is specified by
|
|
| 7364 |
[[fs.path.cvt]].
|
| 7365 |
|
| 7366 |
``` cpp
|
| 7367 |
std::string generic_string() const;
|
| 7368 |
std::wstring generic_wstring() const;
|
| 7369 |
-
std::
|
| 7370 |
std::u16string generic_u16string() const;
|
| 7371 |
std::u32string generic_u32string() const;
|
| 7372 |
```
|
| 7373 |
|
| 7374 |
*Returns:* The pathname in the generic format.
|
| 7375 |
|
| 7376 |
-
*Remarks:* Conversion, if any, is specified by [[fs.path.cvt]].
|
| 7377 |
-
encoding of the string returned by `generic_u8string()` is always UTF-8.
|
| 7378 |
|
| 7379 |
-
#####
|
| 7380 |
|
| 7381 |
``` cpp
|
| 7382 |
int compare(const path& p) const noexcept;
|
| 7383 |
```
|
| 7384 |
|
| 7385 |
*Returns:*
|
| 7386 |
|
| 7387 |
-
-
|
| 7388 |
-
|
| 7389 |
-
|
| 7390 |
-
-
|
| 7391 |
-
|
| 7392 |
-
|
| 7393 |
-
|
| 7394 |
-
|
| 7395 |
-
|
| 7396 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7397 |
|
| 7398 |
``` cpp
|
| 7399 |
-
int compare(const string_type& s) const
|
| 7400 |
int compare(basic_string_view<value_type> s) const;
|
|
|
|
| 7401 |
```
|
| 7402 |
|
| 7403 |
-
*
|
| 7404 |
|
| 7405 |
-
|
| 7406 |
-
int compare(const value_type* s) const
|
| 7407 |
-
```
|
| 7408 |
-
|
| 7409 |
-
*Returns:* `compare(path(s))`.
|
| 7410 |
-
|
| 7411 |
-
##### `path` decomposition <a id="fs.path.decompose">[[fs.path.decompose]]</a>
|
| 7412 |
|
| 7413 |
``` cpp
|
| 7414 |
path root_name() const;
|
| 7415 |
```
|
| 7416 |
|
|
@@ -7433,20 +8372,21 @@ path root_path() const;
|
|
| 7433 |
``` cpp
|
| 7434 |
path relative_path() const;
|
| 7435 |
```
|
| 7436 |
|
| 7437 |
*Returns:* A `path` composed from the pathname in the generic format, if
|
| 7438 |
-
`
|
| 7439 |
-
Otherwise, `path()`.
|
| 7440 |
|
| 7441 |
``` cpp
|
| 7442 |
path parent_path() const;
|
| 7443 |
```
|
| 7444 |
|
| 7445 |
-
*Returns:* `*this` if `
|
| 7446 |
-
generic format pathname is the longest prefix of the generic
|
| 7447 |
-
pathname of `*this` that produces one fewer element in its
|
|
|
|
| 7448 |
|
| 7449 |
``` cpp
|
| 7450 |
path filename() const;
|
| 7451 |
```
|
| 7452 |
|
|
@@ -7493,11 +8433,11 @@ for (; !p.extension().empty(); p = p.stem())
|
|
| 7493 |
|
| 7494 |
``` cpp
|
| 7495 |
path extension() const;
|
| 7496 |
```
|
| 7497 |
|
| 7498 |
-
*Returns:*
|
| 7499 |
`filename()` not included in `stem()`.
|
| 7500 |
|
| 7501 |
[*Example 8*:
|
| 7502 |
|
| 7503 |
``` cpp
|
|
@@ -7516,18 +8456,18 @@ extension. — *end note*]
|
|
| 7516 |
|
| 7517 |
[*Note 5*: On non-POSIX operating systems, for a path `p`, it may not
|
| 7518 |
be the case that `p.stem() + p.extension() == p.filename()`, even though
|
| 7519 |
the generic format pathnames are the same. — *end note*]
|
| 7520 |
|
| 7521 |
-
#####
|
| 7522 |
|
| 7523 |
``` cpp
|
| 7524 |
-
bool empty() const noexcept;
|
| 7525 |
```
|
| 7526 |
|
| 7527 |
-
*Returns:* `true` if the pathname in the generic format is empty,
|
| 7528 |
-
`false`.
|
| 7529 |
|
| 7530 |
``` cpp
|
| 7531 |
bool has_root_path() const;
|
| 7532 |
```
|
| 7533 |
|
|
@@ -7578,11 +8518,11 @@ bool has_extension() const;
|
|
| 7578 |
``` cpp
|
| 7579 |
bool is_absolute() const;
|
| 7580 |
```
|
| 7581 |
|
| 7582 |
*Returns:* `true` if the pathname in the native format contains an
|
| 7583 |
-
absolute path
|
| 7584 |
|
| 7585 |
[*Example 9*: `path("/").is_absolute()` is `true` for POSIX-based
|
| 7586 |
operating systems, and `false` for Windows-based operating
|
| 7587 |
systems. — *end example*]
|
| 7588 |
|
|
@@ -7590,18 +8530,18 @@ systems. — *end example*]
|
|
| 7590 |
bool is_relative() const;
|
| 7591 |
```
|
| 7592 |
|
| 7593 |
*Returns:* `!is_absolute()`.
|
| 7594 |
|
| 7595 |
-
#####
|
| 7596 |
|
| 7597 |
``` cpp
|
| 7598 |
path lexically_normal() const;
|
| 7599 |
```
|
| 7600 |
|
| 7601 |
*Returns:* A path whose pathname in the generic format is the normal
|
| 7602 |
-
form
|
| 7603 |
`*this`.
|
| 7604 |
|
| 7605 |
[*Example 10*:
|
| 7606 |
|
| 7607 |
``` cpp
|
|
@@ -7618,29 +8558,40 @@ slashes, but that does not affect `path` equality.
|
|
| 7618 |
``` cpp
|
| 7619 |
path lexically_relative(const path& base) const;
|
| 7620 |
```
|
| 7621 |
|
| 7622 |
*Returns:* `*this` made relative to `base`. Does not
|
| 7623 |
-
resolve
|
| 7624 |
-
normalize
|
| 7625 |
-
|
| 7626 |
-
*Effects:* If
|
| 7627 |
-
|
| 7628 |
-
`
|
| 7629 |
-
`
|
| 7630 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7631 |
|
| 7632 |
``` cpp
|
| 7633 |
auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
|
| 7634 |
```
|
| 7635 |
|
| 7636 |
Then,
|
| 7637 |
|
| 7638 |
- if `a == end()` and `b == base.end()`, returns `path(".")`; otherwise
|
| 7639 |
- let `n` be the number of *filename* elements in \[`b`, `base.end()`)
|
| 7640 |
-
that are not
|
| 7641 |
-
If `n<0,` returns `path()`; otherwise
|
|
|
|
|
|
|
| 7642 |
- returns an object of class `path` that is default-constructed,
|
| 7643 |
followed by
|
| 7644 |
- application of `operator/=(path(".."))` `n` times, and then
|
| 7645 |
- application of `operator/=` for each element in \[`a`, `end()`).
|
| 7646 |
|
|
@@ -7659,41 +8610,41 @@ The above assertions will succeed. On Windows, the returned path’s
|
|
| 7659 |
*directory-separator* characters will be backslashes rather than
|
| 7660 |
slashes, but that does not affect `path` equality.
|
| 7661 |
|
| 7662 |
— *end example*]
|
| 7663 |
|
| 7664 |
-
[*Note
|
| 7665 |
operational function `relative()`. — *end note*]
|
| 7666 |
|
| 7667 |
-
[*Note
|
| 7668 |
-
|
| 7669 |
-
`
|
| 7670 |
|
| 7671 |
``` cpp
|
| 7672 |
path lexically_proximate(const path& base) const;
|
| 7673 |
```
|
| 7674 |
|
| 7675 |
*Returns:* If the value of `lexically_relative(base)` is not an empty
|
| 7676 |
path, return it. Otherwise return `*this`.
|
| 7677 |
|
| 7678 |
-
[*Note
|
| 7679 |
operational function `proximate()`. — *end note*]
|
| 7680 |
|
| 7681 |
-
[*Note
|
| 7682 |
-
|
| 7683 |
-
`
|
| 7684 |
|
| 7685 |
-
####
|
| 7686 |
|
| 7687 |
Path iterators iterate over the elements of the pathname in the generic
|
| 7688 |
-
format
|
| 7689 |
|
| 7690 |
-
A `path::iterator` is a constant iterator
|
| 7691 |
-
|
| 7692 |
-
|
| 7693 |
-
`
|
| 7694 |
-
|
| 7695 |
|
| 7696 |
Calling any non-const member function of a `path` object invalidates all
|
| 7697 |
iterators referring to elements of that object.
|
| 7698 |
|
| 7699 |
For the elements of the pathname in the generic format, the forward
|
|
@@ -7720,171 +8671,94 @@ list above. If no elements are present, the end iterator.
|
|
| 7720 |
iterator end() const;
|
| 7721 |
```
|
| 7722 |
|
| 7723 |
*Returns:* The end iterator.
|
| 7724 |
|
| 7725 |
-
####
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7726 |
|
| 7727 |
``` cpp
|
| 7728 |
void swap(path& lhs, path& rhs) noexcept;
|
| 7729 |
```
|
| 7730 |
|
| 7731 |
-
*Effects:* Equivalent to
|
| 7732 |
|
| 7733 |
``` cpp
|
| 7734 |
size_t hash_value (const path& p) noexcept;
|
| 7735 |
```
|
| 7736 |
|
| 7737 |
*Returns:* A hash value for the path `p`. If for two paths, `p1 == p2`
|
| 7738 |
then `hash_value(p1) == hash_value(p2)`.
|
| 7739 |
|
| 7740 |
``` cpp
|
| 7741 |
-
bool operator
|
| 7742 |
```
|
| 7743 |
|
| 7744 |
-
*Returns:* `lhs.compare(rhs)
|
| 7745 |
-
|
| 7746 |
-
``` cpp
|
| 7747 |
-
bool operator<=(const path& lhs, const path& rhs) noexcept;
|
| 7748 |
-
```
|
| 7749 |
-
|
| 7750 |
-
*Returns:* `!(rhs < lhs)`.
|
| 7751 |
-
|
| 7752 |
-
``` cpp
|
| 7753 |
-
bool operator> (const path& lhs, const path& rhs) noexcept;
|
| 7754 |
-
```
|
| 7755 |
-
|
| 7756 |
-
*Returns:* `rhs < lhs`.
|
| 7757 |
-
|
| 7758 |
-
``` cpp
|
| 7759 |
-
bool operator>=(const path& lhs, const path& rhs) noexcept;
|
| 7760 |
-
```
|
| 7761 |
-
|
| 7762 |
-
*Returns:* `!(lhs < rhs)`.
|
| 7763 |
-
|
| 7764 |
-
``` cpp
|
| 7765 |
-
bool operator==(const path& lhs, const path& rhs) noexcept;
|
| 7766 |
-
```
|
| 7767 |
-
|
| 7768 |
-
*Returns:* `!(lhs < rhs) && !(rhs < lhs)`.
|
| 7769 |
|
| 7770 |
[*Note 1*:
|
| 7771 |
|
| 7772 |
Path equality and path equivalence have different semantics.
|
| 7773 |
|
| 7774 |
- Equality is determined by the `path` non-member `operator==`, which
|
| 7775 |
-
considers the two
|
| 7776 |
\[*Example 1*: `path("foo") == "bar"` is never
|
| 7777 |
`true`. — *end example*]
|
| 7778 |
- Equivalence is determined by the `equivalent()` non-member function,
|
| 7779 |
-
which determines if two paths resolve
|
| 7780 |
-
|
| 7781 |
-
|
| 7782 |
-
file. — *end example*]
|
| 7783 |
|
| 7784 |
Programmers wishing to determine if two paths are “the same” must decide
|
| 7785 |
if “the same” means “the same representation” or “resolve to the same
|
| 7786 |
actual file”, and choose the appropriate function accordingly.
|
| 7787 |
|
| 7788 |
— *end note*]
|
| 7789 |
|
| 7790 |
``` cpp
|
| 7791 |
-
|
| 7792 |
```
|
| 7793 |
|
| 7794 |
-
*Returns:* `
|
| 7795 |
|
| 7796 |
``` cpp
|
| 7797 |
-
path operator/ (const path& lhs, const path& rhs);
|
| 7798 |
```
|
| 7799 |
|
| 7800 |
*Effects:* Equivalent to: `return path(lhs) /= rhs;`
|
| 7801 |
|
| 7802 |
-
###
|
| 7803 |
-
|
| 7804 |
-
``` cpp
|
| 7805 |
-
template <class charT, class traits>
|
| 7806 |
-
basic_ostream<charT, traits>&
|
| 7807 |
-
operator<<(basic_ostream<charT, traits>& os, const path& p);
|
| 7808 |
-
```
|
| 7809 |
-
|
| 7810 |
-
*Effects:* Equivalent to: `os << quoted(p.string<charT, traits>());`
|
| 7811 |
-
|
| 7812 |
-
[*Note 2*: The `quoted` function is described
|
| 7813 |
-
in [[quoted.manip]]. — *end note*]
|
| 7814 |
-
|
| 7815 |
-
*Returns:* `os`.
|
| 7816 |
-
|
| 7817 |
-
``` cpp
|
| 7818 |
-
template <class charT, class traits>
|
| 7819 |
-
basic_istream<charT, traits>&
|
| 7820 |
-
operator>>(basic_istream<charT, traits>& is, path& p);
|
| 7821 |
-
```
|
| 7822 |
-
|
| 7823 |
-
*Effects:* Equivalent to:
|
| 7824 |
-
|
| 7825 |
-
``` cpp
|
| 7826 |
-
basic_string<charT, traits> tmp;
|
| 7827 |
-
is >> quoted(tmp);
|
| 7828 |
-
p = tmp;
|
| 7829 |
-
```
|
| 7830 |
-
|
| 7831 |
-
*Returns:* `is`.
|
| 7832 |
-
|
| 7833 |
-
##### `path` factory functions <a id="fs.path.factory">[[fs.path.factory]]</a>
|
| 7834 |
-
|
| 7835 |
-
``` cpp
|
| 7836 |
-
template <class Source>
|
| 7837 |
-
path u8path(const Source& source);
|
| 7838 |
-
template <class InputIterator>
|
| 7839 |
-
path u8path(InputIterator first, InputIterator last);
|
| 7840 |
-
```
|
| 7841 |
-
|
| 7842 |
-
*Requires:* The `source` and \[`first`, `last`) sequences are UTF-8
|
| 7843 |
-
encoded. The value type of `Source` and `InputIterator` is `char`.
|
| 7844 |
-
|
| 7845 |
-
*Returns:*
|
| 7846 |
-
|
| 7847 |
-
- If `value_type` is `char` and the current native narrow
|
| 7848 |
-
encoding ([[fs.def.native.encode]]) is UTF-8, return `path(source)`
|
| 7849 |
-
or `path(first, last)`; otherwise,
|
| 7850 |
-
- if `value_type` is `wchar_t` and the native wide encoding is UTF-16,
|
| 7851 |
-
or if `value_type` is `char16_t` or `char32_t`, convert `source` or
|
| 7852 |
-
\[`first`, `last`) to a temporary, `tmp`, of type `string_type` and
|
| 7853 |
-
return `path(tmp)`; otherwise,
|
| 7854 |
-
- convert `source` or \[`first`, `last`) to a temporary, `tmp`, of type
|
| 7855 |
-
`u32string` and return `path(tmp)`.
|
| 7856 |
-
|
| 7857 |
-
*Remarks:* Argument format conversion ([[fs.path.fmt.cvt]]) applies to
|
| 7858 |
-
the arguments for these functions. How Unicode encoding conversions are
|
| 7859 |
-
performed is unspecified.
|
| 7860 |
-
|
| 7861 |
-
[*Example 1*:
|
| 7862 |
-
|
| 7863 |
-
A string is to be read from a database that is encoded in UTF-8, and
|
| 7864 |
-
used to create a directory using the native encoding for filenames:
|
| 7865 |
-
|
| 7866 |
-
``` cpp
|
| 7867 |
-
namespace fs = std::filesystem;
|
| 7868 |
-
std::string utf8_string = read_utf8_data();
|
| 7869 |
-
fs::create_directory(fs::u8path(utf8_string));
|
| 7870 |
-
```
|
| 7871 |
-
|
| 7872 |
-
For POSIX-based operating systems with the native narrow encoding set to
|
| 7873 |
-
UTF-8, no encoding or type conversion occurs.
|
| 7874 |
-
|
| 7875 |
-
For POSIX-based operating systems with the native narrow encoding not
|
| 7876 |
-
set to UTF-8, a conversion to UTF-32 occurs, followed by a conversion to
|
| 7877 |
-
the current native narrow encoding. Some Unicode characters may have no
|
| 7878 |
-
native character set representation.
|
| 7879 |
-
|
| 7880 |
-
For Windows-based operating systems a conversion from UTF-8 to UTF-16
|
| 7881 |
-
occurs.
|
| 7882 |
-
|
| 7883 |
-
— *end example*]
|
| 7884 |
-
|
| 7885 |
-
### Class `filesystem_error` <a id="fs.class.filesystem_error">[[fs.class.filesystem_error]]</a>
|
| 7886 |
|
| 7887 |
``` cpp
|
| 7888 |
namespace std::filesystem {
|
| 7889 |
class filesystem_error : public system_error {
|
| 7890 |
public:
|
|
@@ -7900,65 +8774,50 @@ namespace std::filesystem {
|
|
| 7900 |
};
|
| 7901 |
}
|
| 7902 |
```
|
| 7903 |
|
| 7904 |
The class `filesystem_error` defines the type of objects thrown as
|
| 7905 |
-
exceptions to report file system errors from functions described in
|
| 7906 |
-
subclause.
|
| 7907 |
|
| 7908 |
-
####
|
| 7909 |
|
| 7910 |
Constructors are provided that store zero, one, or two paths associated
|
| 7911 |
with an error.
|
| 7912 |
|
| 7913 |
``` cpp
|
| 7914 |
filesystem_error(const string& what_arg, error_code ec);
|
| 7915 |
```
|
| 7916 |
|
| 7917 |
-
*
|
| 7918 |
-
Table [[tab:filesystem_error.1]].
|
| 7919 |
|
| 7920 |
-
|
| 7921 |
-
|
| 7922 |
-
|
| 7923 |
-
|
| 7924 |
-
| `runtime_error::what()` | `what_arg.c_str()` |
|
| 7925 |
-
| `code()` | `ec` |
|
| 7926 |
-
| `path1().empty()` | `true` |
|
| 7927 |
-
| `path2().empty()` | `true` |
|
| 7928 |
|
| 7929 |
``` cpp
|
| 7930 |
filesystem_error(const string& what_arg, const path& p1, error_code ec);
|
| 7931 |
```
|
| 7932 |
|
| 7933 |
-
*
|
| 7934 |
-
Table [[tab:filesystem_error.2]].
|
| 7935 |
|
| 7936 |
-
|
| 7937 |
-
|
| 7938 |
-
|
| 7939 |
-
|
| 7940 |
-
| `runtime_error::what()` | `what_arg.c_str()` |
|
| 7941 |
-
| `code()` | `ec` |
|
| 7942 |
-
| `path1()` | Reference to stored copy of `p1` |
|
| 7943 |
-
| `path2().empty()` | `true` |
|
| 7944 |
|
| 7945 |
``` cpp
|
| 7946 |
filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
|
| 7947 |
```
|
| 7948 |
|
| 7949 |
-
*
|
| 7950 |
-
Table [[tab:filesystem_error.3]].
|
| 7951 |
|
| 7952 |
-
|
| 7953 |
-
|
| 7954 |
-
|
| 7955 |
-
|
| 7956 |
-
| `runtime_error::what()` | `what_arg.c_str()` |
|
| 7957 |
-
| `code()` | `ec` |
|
| 7958 |
-
| `path1()` | Reference to stored copy of `p1` |
|
| 7959 |
-
| `path2()` | Reference to stored copy of `p2` |
|
| 7960 |
|
| 7961 |
``` cpp
|
| 7962 |
const path& path1() const noexcept;
|
| 7963 |
```
|
| 7964 |
|
|
@@ -7974,45 +8833,46 @@ or, if none, an empty path.
|
|
| 7974 |
|
| 7975 |
``` cpp
|
| 7976 |
const char* what() const noexcept override;
|
| 7977 |
```
|
| 7978 |
|
| 7979 |
-
*Returns:*
|
| 7980 |
-
|
| 7981 |
-
include `
|
| 7982 |
-
|
| 7983 |
|
| 7984 |
### Enumerations <a id="fs.enum">[[fs.enum]]</a>
|
| 7985 |
|
| 7986 |
#### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
|
| 7987 |
|
| 7988 |
This enum specifies constants used to identify the format of the
|
| 7989 |
-
character sequence, with the meanings listed in
|
| 7990 |
-
[[tab:enum.path.format]].
|
| 7991 |
|
| 7992 |
[*Note 1*: For POSIX-based systems, native and generic formats are
|
| 7993 |
equivalent and the character sequence should always be interpreted in
|
| 7994 |
the same way. — *end note*]
|
| 7995 |
|
| 7996 |
-
#### Enum class `file_type` <a id="fs.enum.
|
| 7997 |
|
| 7998 |
This enum class specifies constants used to identify file types, with
|
| 7999 |
-
the meanings listed in
|
|
|
|
| 8000 |
|
| 8001 |
[*Note 1*: The file not being found is not considered an error while
|
| 8002 |
determining the type of a file. — *end note*]
|
| 8003 |
|
| 8004 |
#### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
|
| 8005 |
|
| 8006 |
-
The `enum class` type `copy_options` is a bitmask type
|
| 8007 |
-
|
| 8008 |
-
|
| 8009 |
-
|
| 8010 |
-
|
| 8011 |
exposition; implementations shall provide only a single definition.
|
|
|
|
| 8012 |
|
| 8013 |
-
**Table: Enum class `copy_options`** <a id="
|
| 8014 |
|
| 8015 |
| Constant | Meaning |
|
| 8016 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 8017 |
| `none` | (Default) Error; file already exists. |
|
| 8018 |
| `skip_existing` | Do not overwrite existing file, do not report an error. |
|
|
@@ -8026,15 +8886,15 @@ exposition; implementations shall provide only a single definition.
|
|
| 8026 |
| `create_hard_links` | Make hard links instead of copies of files. |
|
| 8027 |
|
| 8028 |
|
| 8029 |
#### Enum class `perms` <a id="fs.enum.perms">[[fs.enum.perms]]</a>
|
| 8030 |
|
| 8031 |
-
The `enum class` type `perms` is a bitmask type
|
| 8032 |
-
|
| 8033 |
-
|
| 8034 |
|
| 8035 |
-
**Table: Enum class `perms`** <a id="
|
| 8036 |
|
| 8037 |
| Name | Value (octal) | POSIX macro | Definition or notes |
|
| 8038 |
| -------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
|
| 8039 |
| `none` | `0` | | There are no permissions set for the file. |
|
| 8040 |
| `owner_read` | `0400` | `S_IRUSR` | Read permission, owner |
|
|
@@ -8057,81 +8917,85 @@ the meanings listed in Table [[tab:fs.enum.perms]].
|
|
| 8057 |
| `unknown` | `0xFFFF` | | The permissions are not known, such as when a `file_status` object is created without specifying the permissions |
|
| 8058 |
|
| 8059 |
|
| 8060 |
#### Enum class `perm_options` <a id="fs.enum.perm.opts">[[fs.enum.perm.opts]]</a>
|
| 8061 |
|
| 8062 |
-
The `enum class` type `perm_options` is a bitmask type
|
| 8063 |
-
|
| 8064 |
-
|
| 8065 |
-
[[
|
| 8066 |
-
|
| 8067 |
-
`
|
| 8068 |
|
| 8069 |
-
**Table: Enum class `perm_options`** <a id="
|
| 8070 |
|
| 8071 |
| Name | Meaning |
|
| 8072 |
-
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 8073 |
| `replace` | `permissions` shall replace the file's permission bits with `perm` |
|
| 8074 |
-
| `add` | `permissions` shall replace the file's permission bits with the bitwise OR of `perm` and the file's current permission bits. |
|
| 8075 |
-
| `remove` | `permissions` shall replace the file's permission bits with the bitwise AND of the complement of `perm` and the file's current permission bits. |
|
| 8076 |
| `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
|
| 8077 |
|
| 8078 |
|
| 8079 |
#### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
|
| 8080 |
|
| 8081 |
-
The `enum class` type `directory_options` is a bitmask type
|
| 8082 |
-
[[bitmask.types]]
|
| 8083 |
-
directory traversal options, with the meanings listed in
|
| 8084 |
-
[[
|
|
|
|
| 8085 |
|
| 8086 |
-
**Table: Enum class `directory_options`** <a id="
|
| 8087 |
|
| 8088 |
| Name | Meaning |
|
| 8089 |
| -------------------------- | ------------------------------------------------------------------ |
|
| 8090 |
| `none` | (Default) Skip directory symlinks, permission denied is an error. |
|
| 8091 |
| `follow_directory_symlink` | Follow rather than skip directory symlinks. |
|
| 8092 |
| `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
|
| 8093 |
|
| 8094 |
|
| 8095 |
-
### Class `file_status` <a id="fs.class.
|
| 8096 |
|
| 8097 |
``` cpp
|
| 8098 |
namespace std::filesystem {
|
| 8099 |
class file_status {
|
| 8100 |
public:
|
| 8101 |
-
// [fs.
|
| 8102 |
file_status() noexcept : file_status(file_type::none) {}
|
| 8103 |
explicit file_status(file_type ft,
|
| 8104 |
perms prms = perms::unknown) noexcept;
|
| 8105 |
file_status(const file_status&) noexcept = default;
|
| 8106 |
file_status(file_status&&) noexcept = default;
|
| 8107 |
~file_status();
|
| 8108 |
|
| 8109 |
-
// assignments
|
| 8110 |
file_status& operator=(const file_status&) noexcept = default;
|
| 8111 |
file_status& operator=(file_status&&) noexcept = default;
|
| 8112 |
|
| 8113 |
-
// [fs.
|
| 8114 |
void type(file_type ft) noexcept;
|
| 8115 |
void permissions(perms prms) noexcept;
|
| 8116 |
|
| 8117 |
-
// [fs.
|
| 8118 |
file_type type() const noexcept;
|
| 8119 |
perms permissions() const noexcept;
|
|
|
|
|
|
|
|
|
|
| 8120 |
};
|
| 8121 |
}
|
| 8122 |
```
|
| 8123 |
|
| 8124 |
-
####
|
| 8125 |
|
| 8126 |
``` cpp
|
| 8127 |
explicit file_status(file_type ft, perms prms = perms::unknown) noexcept;
|
| 8128 |
```
|
| 8129 |
|
| 8130 |
-
*
|
| 8131 |
|
| 8132 |
-
####
|
| 8133 |
|
| 8134 |
``` cpp
|
| 8135 |
file_type type() const noexcept;
|
| 8136 |
```
|
| 8137 |
|
|
@@ -8145,53 +9009,53 @@ perms permissions() const noexcept;
|
|
| 8145 |
|
| 8146 |
*Returns:* The value of `permissions()` specified by the postconditions
|
| 8147 |
of the most recent call to a constructor, `operator=`, or
|
| 8148 |
`permissions(perms)` function.
|
| 8149 |
|
| 8150 |
-
####
|
| 8151 |
|
| 8152 |
``` cpp
|
| 8153 |
void type(file_type ft) noexcept;
|
| 8154 |
```
|
| 8155 |
|
| 8156 |
-
*
|
| 8157 |
|
| 8158 |
``` cpp
|
| 8159 |
void permissions(perms prms) noexcept;
|
| 8160 |
```
|
| 8161 |
|
| 8162 |
-
*
|
| 8163 |
|
| 8164 |
-
### Class `directory_entry` <a id="fs.class.
|
| 8165 |
|
| 8166 |
``` cpp
|
| 8167 |
namespace std::filesystem {
|
| 8168 |
class directory_entry {
|
| 8169 |
public:
|
| 8170 |
// [fs.dir.entry.cons], constructors and destructor
|
| 8171 |
directory_entry() noexcept = default;
|
| 8172 |
directory_entry(const directory_entry&) = default;
|
| 8173 |
directory_entry(directory_entry&&) noexcept = default;
|
| 8174 |
-
explicit directory_entry(const path& p);
|
| 8175 |
-
directory_entry(const path& p, error_code& ec);
|
| 8176 |
~directory_entry();
|
| 8177 |
|
| 8178 |
-
// assignments
|
| 8179 |
directory_entry& operator=(const directory_entry&) = default;
|
| 8180 |
directory_entry& operator=(directory_entry&&) noexcept = default;
|
| 8181 |
|
| 8182 |
// [fs.dir.entry.mods], modifiers
|
| 8183 |
-
void assign(const path& p);
|
| 8184 |
-
void assign(const path& p, error_code& ec);
|
| 8185 |
-
void replace_filename(const path& p);
|
| 8186 |
-
void replace_filename(const path& p, error_code& ec);
|
| 8187 |
void refresh();
|
| 8188 |
void refresh(error_code& ec) noexcept;
|
| 8189 |
|
| 8190 |
// [fs.dir.entry.obs], observers
|
| 8191 |
-
const path& path() const noexcept;
|
| 8192 |
-
operator const path&() const noexcept;
|
| 8193 |
bool exists() const;
|
| 8194 |
bool exists(error_code& ec) const noexcept;
|
| 8195 |
bool is_block_file() const;
|
| 8196 |
bool is_block_file(error_code& ec) const noexcept;
|
| 8197 |
bool is_character_file() const;
|
|
@@ -8217,36 +9081,32 @@ namespace std::filesystem {
|
|
| 8217 |
file_status status() const;
|
| 8218 |
file_status status(error_code& ec) const noexcept;
|
| 8219 |
file_status symlink_status() const;
|
| 8220 |
file_status symlink_status(error_code& ec) const noexcept;
|
| 8221 |
|
| 8222 |
-
bool operator< (const directory_entry& rhs) const noexcept;
|
| 8223 |
bool operator==(const directory_entry& rhs) const noexcept;
|
| 8224 |
-
|
| 8225 |
-
bool operator<=(const directory_entry& rhs) const noexcept;
|
| 8226 |
-
bool operator> (const directory_entry& rhs) const noexcept;
|
| 8227 |
-
bool operator>=(const directory_entry& rhs) const noexcept;
|
| 8228 |
|
| 8229 |
private:
|
| 8230 |
-
path pathobject;
|
| 8231 |
friend class directory_iterator; // exposition only
|
| 8232 |
};
|
| 8233 |
}
|
| 8234 |
```
|
| 8235 |
|
| 8236 |
A `directory_entry` object stores a `path` object and may store
|
| 8237 |
additional objects for file attributes such as hard link count, status,
|
| 8238 |
symlink status, file size, and last write time.
|
| 8239 |
|
| 8240 |
-
Implementations
|
| 8241 |
-
|
| 8242 |
-
|
| 8243 |
-
|
| 8244 |
-
|
| 8245 |
|
| 8246 |
-
[*Note 1*: For purposes of exposition, class `directory_iterator`
|
| 8247 |
-
[[fs.class.
|
| 8248 |
`directory_entry`. Friendship allows the `directory_iterator`
|
| 8249 |
implementation to cache already available attribute values directly into
|
| 8250 |
a `directory_entry` object without the cost of an unneeded call to
|
| 8251 |
`refresh()`. — *end note*]
|
| 8252 |
|
|
@@ -8278,41 +9138,40 @@ so will not result in a potentially expensive call to the
|
|
| 8278 |
`std::filesystem::last_write_time` function. The code is portable to any
|
| 8279 |
implementation, regardless of whether or not it employs caching.
|
| 8280 |
|
| 8281 |
— *end example*]
|
| 8282 |
|
| 8283 |
-
####
|
| 8284 |
|
| 8285 |
``` cpp
|
| 8286 |
-
explicit directory_entry(const path& p);
|
| 8287 |
-
directory_entry(const path& p, error_code& ec);
|
| 8288 |
```
|
| 8289 |
|
| 8290 |
-
*Effects:*
|
| 8291 |
-
`refresh()` or `refresh(ec)`, respectively.
|
| 8292 |
|
| 8293 |
-
*
|
| 8294 |
-
`path() ==
|
| 8295 |
|
| 8296 |
*Throws:* As specified in [[fs.err.report]].
|
| 8297 |
|
| 8298 |
-
####
|
| 8299 |
|
| 8300 |
``` cpp
|
| 8301 |
-
void assign(const path& p);
|
| 8302 |
-
void assign(const path& p, error_code& ec);
|
| 8303 |
```
|
| 8304 |
|
| 8305 |
*Effects:* Equivalent to `pathobject = p`, then `refresh()` or
|
| 8306 |
`refresh(ec)`, respectively. If an error occurs, the values of any
|
| 8307 |
cached attributes are unspecified.
|
| 8308 |
|
| 8309 |
*Throws:* As specified in [[fs.err.report]].
|
| 8310 |
|
| 8311 |
``` cpp
|
| 8312 |
-
void replace_filename(const path& p);
|
| 8313 |
-
void replace_filename(const path& p, error_code& ec);
|
| 8314 |
```
|
| 8315 |
|
| 8316 |
*Effects:* Equivalent to `pathobject.replace_filename(p)`, then
|
| 8317 |
`refresh()` or `refresh(ec)`, respectively. If an error occurs, the
|
| 8318 |
values of any cached attributes are unspecified.
|
|
@@ -8324,121 +9183,121 @@ void refresh();
|
|
| 8324 |
void refresh(error_code& ec) noexcept;
|
| 8325 |
```
|
| 8326 |
|
| 8327 |
*Effects:* Stores the current values of any cached attributes of the
|
| 8328 |
file `p` resolves to. If an error occurs, an error is
|
| 8329 |
-
reported
|
| 8330 |
-
|
| 8331 |
|
| 8332 |
*Throws:* As specified in [[fs.err.report]].
|
| 8333 |
|
| 8334 |
-
[*Note 1*: Implementations of
|
| 8335 |
-
|
| 8336 |
-
|
| 8337 |
-
|
| 8338 |
-
|
| 8339 |
|
| 8340 |
-
####
|
| 8341 |
|
| 8342 |
Unqualified function names in the *Returns:* elements of the
|
| 8343 |
`directory_entry` observers described below refer to members of the
|
| 8344 |
`std::filesystem` namespace.
|
| 8345 |
|
| 8346 |
``` cpp
|
| 8347 |
-
const path& path() const noexcept;
|
| 8348 |
-
operator const path&() const noexcept;
|
| 8349 |
```
|
| 8350 |
|
| 8351 |
*Returns:* `pathobject`.
|
| 8352 |
|
| 8353 |
``` cpp
|
| 8354 |
bool exists() const;
|
| 8355 |
bool exists(error_code& ec) const noexcept;
|
| 8356 |
```
|
| 8357 |
|
| 8358 |
-
*Returns:* `exists(this->status())` or `exists(this->status(
|
| 8359 |
respectively.
|
| 8360 |
|
| 8361 |
*Throws:* As specified in [[fs.err.report]].
|
| 8362 |
|
| 8363 |
``` cpp
|
| 8364 |
bool is_block_file() const;
|
| 8365 |
bool is_block_file(error_code& ec) const noexcept;
|
| 8366 |
```
|
| 8367 |
|
| 8368 |
*Returns:* `is_block_file(this->status())` or
|
| 8369 |
-
`is_block_file(this->status(
|
| 8370 |
|
| 8371 |
*Throws:* As specified in [[fs.err.report]].
|
| 8372 |
|
| 8373 |
``` cpp
|
| 8374 |
bool is_character_file() const;
|
| 8375 |
bool is_character_file(error_code& ec) const noexcept;
|
| 8376 |
```
|
| 8377 |
|
| 8378 |
*Returns:* `is_character_file(this->status())` or
|
| 8379 |
-
`is_character_file(this->status(
|
| 8380 |
|
| 8381 |
*Throws:* As specified in [[fs.err.report]].
|
| 8382 |
|
| 8383 |
``` cpp
|
| 8384 |
bool is_directory() const;
|
| 8385 |
bool is_directory(error_code& ec) const noexcept;
|
| 8386 |
```
|
| 8387 |
|
| 8388 |
*Returns:* `is_directory(this->status())` or
|
| 8389 |
-
`is_directory(this->status(
|
| 8390 |
|
| 8391 |
*Throws:* As specified in [[fs.err.report]].
|
| 8392 |
|
| 8393 |
``` cpp
|
| 8394 |
bool is_fifo() const;
|
| 8395 |
bool is_fifo(error_code& ec) const noexcept;
|
| 8396 |
```
|
| 8397 |
|
| 8398 |
-
*Returns:* `is_fifo(this->status())` or `is_fifo(this->status(
|
| 8399 |
respectively.
|
| 8400 |
|
| 8401 |
*Throws:* As specified in [[fs.err.report]].
|
| 8402 |
|
| 8403 |
``` cpp
|
| 8404 |
bool is_other() const;
|
| 8405 |
bool is_other(error_code& ec) const noexcept;
|
| 8406 |
```
|
| 8407 |
|
| 8408 |
-
*Returns:* `is_other(this->status())` or `is_other(this->status(
|
| 8409 |
respectively.
|
| 8410 |
|
| 8411 |
*Throws:* As specified in [[fs.err.report]].
|
| 8412 |
|
| 8413 |
``` cpp
|
| 8414 |
bool is_regular_file() const;
|
| 8415 |
bool is_regular_file(error_code& ec) const noexcept;
|
| 8416 |
```
|
| 8417 |
|
| 8418 |
*Returns:* `is_regular_file(this->status())` or
|
| 8419 |
-
`is_regular_file(this->status(
|
| 8420 |
|
| 8421 |
*Throws:* As specified in [[fs.err.report]].
|
| 8422 |
|
| 8423 |
``` cpp
|
| 8424 |
bool is_socket() const;
|
| 8425 |
bool is_socket(error_code& ec) const noexcept;
|
| 8426 |
```
|
| 8427 |
|
| 8428 |
-
*Returns:* `is_socket(this->status())` or
|
| 8429 |
-
|
| 8430 |
|
| 8431 |
*Throws:* As specified in [[fs.err.report]].
|
| 8432 |
|
| 8433 |
``` cpp
|
| 8434 |
bool is_symlink() const;
|
| 8435 |
bool is_symlink(error_code& ec) const noexcept;
|
| 8436 |
```
|
| 8437 |
|
| 8438 |
*Returns:* `is_symlink(this->symlink_status())` or
|
| 8439 |
-
`is_symlink(this->symlink_status(
|
| 8440 |
|
| 8441 |
*Throws:* As specified in [[fs.err.report]].
|
| 8442 |
|
| 8443 |
``` cpp
|
| 8444 |
uintmax_t file_size() const;
|
|
@@ -8497,49 +9356,24 @@ bool operator==(const directory_entry& rhs) const noexcept;
|
|
| 8497 |
```
|
| 8498 |
|
| 8499 |
*Returns:* `pathobject == rhs.pathobject`.
|
| 8500 |
|
| 8501 |
``` cpp
|
| 8502 |
-
|
| 8503 |
```
|
| 8504 |
|
| 8505 |
-
*Returns:* `pathobject
|
| 8506 |
|
| 8507 |
-
``
|
| 8508 |
-
bool operator< (const directory_entry& rhs) const noexcept;
|
| 8509 |
-
```
|
| 8510 |
-
|
| 8511 |
-
*Returns:* `pathobject < rhs.pathobject`.
|
| 8512 |
-
|
| 8513 |
-
``` cpp
|
| 8514 |
-
bool operator<=(const directory_entry& rhs) const noexcept;
|
| 8515 |
-
```
|
| 8516 |
-
|
| 8517 |
-
*Returns:* `pathobject <= rhs.pathobject`.
|
| 8518 |
-
|
| 8519 |
-
``` cpp
|
| 8520 |
-
bool operator> (const directory_entry& rhs) const noexcept;
|
| 8521 |
-
```
|
| 8522 |
-
|
| 8523 |
-
*Returns:* `pathobject > rhs.pathobject`.
|
| 8524 |
-
|
| 8525 |
-
``` cpp
|
| 8526 |
-
bool operator>=(const directory_entry& rhs) const noexcept;
|
| 8527 |
-
```
|
| 8528 |
-
|
| 8529 |
-
*Returns:* `pathobject >= rhs.pathobject`.
|
| 8530 |
-
|
| 8531 |
-
### Class `directory_iterator` <a id="fs.class.directory_iterator">[[fs.class.directory_iterator]]</a>
|
| 8532 |
|
| 8533 |
An object of type `directory_iterator` provides an iterator for a
|
| 8534 |
sequence of `directory_entry` elements representing the path and any
|
| 8535 |
-
cached attribute values
|
| 8536 |
-
|
| 8537 |
|
| 8538 |
[*Note 1*: For iteration into sub-directories, see class
|
| 8539 |
-
`recursive_directory_iterator`
|
| 8540 |
-
[[fs.class.rec.dir.itr]]). — *end note*]
|
| 8541 |
|
| 8542 |
``` cpp
|
| 8543 |
namespace std::filesystem {
|
| 8544 |
class directory_iterator {
|
| 8545 |
public:
|
|
@@ -8551,32 +9385,32 @@ namespace std::filesystem {
|
|
| 8551 |
|
| 8552 |
// [fs.dir.itr.members], member functions
|
| 8553 |
directory_iterator() noexcept;
|
| 8554 |
explicit directory_iterator(const path& p);
|
| 8555 |
directory_iterator(const path& p, directory_options options);
|
| 8556 |
-
directory_iterator(const path& p, error_code& ec)
|
| 8557 |
directory_iterator(const path& p, directory_options options,
|
| 8558 |
-
error_code& ec)
|
| 8559 |
directory_iterator(const directory_iterator& rhs);
|
| 8560 |
directory_iterator(directory_iterator&& rhs) noexcept;
|
| 8561 |
~directory_iterator();
|
| 8562 |
|
| 8563 |
directory_iterator& operator=(const directory_iterator& rhs);
|
| 8564 |
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
|
| 8565 |
|
| 8566 |
const directory_entry& operator*() const;
|
| 8567 |
const directory_entry* operator->() const;
|
| 8568 |
directory_iterator& operator++();
|
| 8569 |
-
directory_iterator& increment(error_code& ec)
|
| 8570 |
|
| 8571 |
// other members as required by [input.iterators], input iterators
|
| 8572 |
};
|
| 8573 |
}
|
| 8574 |
```
|
| 8575 |
|
| 8576 |
-
`directory_iterator`
|
| 8577 |
-
[[input.iterators]]
|
| 8578 |
|
| 8579 |
If an iterator of type `directory_iterator` reports an error or is
|
| 8580 |
advanced past the last directory element, that iterator shall become
|
| 8581 |
equal to the end iterator value. The `directory_iterator` default
|
| 8582 |
constructor shall create an iterator equal to the end iterator value,
|
|
@@ -8592,24 +9426,24 @@ object obtained by dereferencing a `directory_iterator` is a reference
|
|
| 8592 |
to a `path` object composed of the directory argument from which the
|
| 8593 |
iterator was constructed with filename of the directory entry appended
|
| 8594 |
as if by `operator/=`.
|
| 8595 |
|
| 8596 |
Directory iteration shall not yield directory entries for the current
|
| 8597 |
-
(
|
| 8598 |
|
| 8599 |
The order of directory entries obtained by dereferencing successive
|
| 8600 |
increments of a `directory_iterator` is unspecified.
|
| 8601 |
|
| 8602 |
Constructors and non-const `directory_iterator` member functions store
|
| 8603 |
-
the values of any cached attributes
|
| 8604 |
-
|
| 8605 |
`directory_iterator` member functions shall not directly or indirectly
|
| 8606 |
call any `directory_entry` `refresh` function.
|
| 8607 |
|
| 8608 |
[*Note 2*: The exact mechanism for storing cached attribute values is
|
| 8609 |
not exposed to users. For exposition, class `directory_iterator` is
|
| 8610 |
-
shown in [[fs.class.
|
| 8611 |
`directory_entry`. — *end note*]
|
| 8612 |
|
| 8613 |
[*Note 3*: Programs performing directory iteration may wish to test if
|
| 8614 |
the path obtained by dereferencing a directory iterator actually exists.
|
| 8615 |
It could be a symbolic link to a non-existent file. Programs recursively
|
|
@@ -8620,23 +9454,23 @@ may wish to avoid following symbolic links. — *end note*]
|
|
| 8620 |
construction of a `directory_iterator` for the directory, it is
|
| 8621 |
unspecified whether or not subsequently incrementing the iterator will
|
| 8622 |
ever result in an iterator referencing the removed or added directory
|
| 8623 |
entry. See POSIX `readdir_r`. — *end note*]
|
| 8624 |
|
| 8625 |
-
####
|
| 8626 |
|
| 8627 |
``` cpp
|
| 8628 |
directory_iterator() noexcept;
|
| 8629 |
```
|
| 8630 |
|
| 8631 |
*Effects:* Constructs the end iterator.
|
| 8632 |
|
| 8633 |
``` cpp
|
| 8634 |
explicit directory_iterator(const path& p);
|
| 8635 |
directory_iterator(const path& p, directory_options options);
|
| 8636 |
-
directory_iterator(const path& p, error_code& ec)
|
| 8637 |
-
directory_iterator(const path& p, directory_options options, error_code& ec)
|
| 8638 |
```
|
| 8639 |
|
| 8640 |
*Effects:* For the directory that `p` resolves to, constructs an
|
| 8641 |
iterator for the first element in a sequence of `directory_entry`
|
| 8642 |
elements representing the files in the directory, if any; otherwise the
|
|
@@ -8659,39 +9493,37 @@ error.
|
|
| 8659 |
``` cpp
|
| 8660 |
directory_iterator(const directory_iterator& rhs);
|
| 8661 |
directory_iterator(directory_iterator&& rhs) noexcept;
|
| 8662 |
```
|
| 8663 |
|
| 8664 |
-
*
|
| 8665 |
-
|
| 8666 |
-
*Postconditions:* `*this` has the original value of `rhs`.
|
| 8667 |
|
| 8668 |
``` cpp
|
| 8669 |
directory_iterator& operator=(const directory_iterator& rhs);
|
| 8670 |
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
|
| 8671 |
```
|
| 8672 |
|
| 8673 |
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 8674 |
effect.
|
| 8675 |
|
| 8676 |
-
*
|
| 8677 |
|
| 8678 |
*Returns:* `*this`.
|
| 8679 |
|
| 8680 |
``` cpp
|
| 8681 |
directory_iterator& operator++();
|
| 8682 |
-
directory_iterator& increment(error_code& ec)
|
| 8683 |
```
|
| 8684 |
|
| 8685 |
*Effects:* As specified for the prefix increment operation of Input
|
| 8686 |
-
iterators
|
| 8687 |
|
| 8688 |
*Returns:* `*this`.
|
| 8689 |
|
| 8690 |
*Throws:* As specified in [[fs.err.report]].
|
| 8691 |
|
| 8692 |
-
####
|
| 8693 |
|
| 8694 |
These functions enable range access for `directory_iterator`.
|
| 8695 |
|
| 8696 |
``` cpp
|
| 8697 |
directory_iterator begin(directory_iterator iter) noexcept;
|
|
@@ -8725,12 +9557,12 @@ namespace std::filesystem {
|
|
| 8725 |
// [fs.rec.dir.itr.members], constructors and destructor
|
| 8726 |
recursive_directory_iterator() noexcept;
|
| 8727 |
explicit recursive_directory_iterator(const path& p);
|
| 8728 |
recursive_directory_iterator(const path& p, directory_options options);
|
| 8729 |
recursive_directory_iterator(const path& p, directory_options options,
|
| 8730 |
-
error_code& ec)
|
| 8731 |
-
recursive_directory_iterator(const path& p, error_code& ec)
|
| 8732 |
recursive_directory_iterator(const recursive_directory_iterator& rhs);
|
| 8733 |
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
|
| 8734 |
~recursive_directory_iterator();
|
| 8735 |
|
| 8736 |
// [fs.rec.dir.itr.members], observers
|
|
@@ -8746,11 +9578,11 @@ namespace std::filesystem {
|
|
| 8746 |
operator=(const recursive_directory_iterator& rhs);
|
| 8747 |
recursive_directory_iterator&
|
| 8748 |
operator=(recursive_directory_iterator&& rhs) noexcept;
|
| 8749 |
|
| 8750 |
recursive_directory_iterator& operator++();
|
| 8751 |
-
recursive_directory_iterator& increment(error_code& ec)
|
| 8752 |
|
| 8753 |
void pop();
|
| 8754 |
void pop(error_code& ec);
|
| 8755 |
void disable_recursion_pending();
|
| 8756 |
|
|
@@ -8767,38 +9599,38 @@ The behavior of a `recursive_directory_iterator` is the same as a
|
|
| 8767 |
`directory_iterator` unless otherwise specified.
|
| 8768 |
|
| 8769 |
[*Note 1*: If the directory structure being iterated over contains
|
| 8770 |
cycles then the end iterator may be unreachable. — *end note*]
|
| 8771 |
|
| 8772 |
-
####
|
| 8773 |
|
| 8774 |
``` cpp
|
| 8775 |
recursive_directory_iterator() noexcept;
|
| 8776 |
```
|
| 8777 |
|
| 8778 |
*Effects:* Constructs the end iterator.
|
| 8779 |
|
| 8780 |
``` cpp
|
| 8781 |
explicit recursive_directory_iterator(const path& p);
|
| 8782 |
recursive_directory_iterator(const path& p, directory_options options);
|
| 8783 |
-
recursive_directory_iterator(const path& p, directory_options options, error_code& ec)
|
| 8784 |
-
recursive_directory_iterator(const path& p, error_code& ec)
|
| 8785 |
```
|
| 8786 |
|
| 8787 |
-
*Effects:* Constructs
|
| 8788 |
-
directory `p` resolves
|
| 8789 |
-
if
|
| 8790 |
|
| 8791 |
``` cpp
|
| 8792 |
(options & directory_options::skip_permission_denied) != directory_options::none
|
| 8793 |
```
|
| 8794 |
|
| 8795 |
and construction encounters an error indicating that permission to
|
| 8796 |
access `p` is denied, constructs the end iterator and does not report an
|
| 8797 |
error.
|
| 8798 |
|
| 8799 |
-
*
|
| 8800 |
`directory_options` argument, otherwise
|
| 8801 |
`options() == directory_options::none`.
|
| 8802 |
|
| 8803 |
*Throws:* As specified in [[fs.err.report]].
|
| 8804 |
|
|
@@ -8806,42 +9638,38 @@ error.
|
|
| 8806 |
`recursive_directory_iterator(".")` rather than
|
| 8807 |
`recursive_directory_iterator("")`. — *end note*]
|
| 8808 |
|
| 8809 |
[*Note 2*: By default, `recursive_directory_iterator` does not follow
|
| 8810 |
directory symlinks. To follow directory symlinks, specify `options` as
|
| 8811 |
-
`directory_options::follow_directory_symlink` — *end note*]
|
| 8812 |
|
| 8813 |
``` cpp
|
| 8814 |
recursive_directory_iterator(const recursive_directory_iterator& rhs);
|
| 8815 |
```
|
| 8816 |
|
| 8817 |
-
*
|
| 8818 |
-
|
| 8819 |
-
*Postconditions:*
|
| 8820 |
|
| 8821 |
- `options() == rhs.options()`
|
| 8822 |
- `depth() == rhs.depth()`
|
| 8823 |
- `recursion_pending() == rhs.recursion_pending()`
|
| 8824 |
|
| 8825 |
``` cpp
|
| 8826 |
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
|
| 8827 |
```
|
| 8828 |
|
| 8829 |
-
*
|
| 8830 |
-
|
| 8831 |
-
*Postconditions:* `options()`, `depth()`, and `recursion_pending()` have
|
| 8832 |
-
the values that `rhs.options()`, `rhs.depth()`, and
|
| 8833 |
`rhs.recursion_pending()`, respectively, had before the function call.
|
| 8834 |
|
| 8835 |
``` cpp
|
| 8836 |
recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
|
| 8837 |
```
|
| 8838 |
|
| 8839 |
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 8840 |
effect.
|
| 8841 |
|
| 8842 |
-
*
|
| 8843 |
|
| 8844 |
- `options() == rhs.options()`
|
| 8845 |
- `depth() == rhs.depth()`
|
| 8846 |
- `recursion_pending() == rhs.recursion_pending()`
|
| 8847 |
|
|
@@ -8852,12 +9680,12 @@ recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noex
|
|
| 8852 |
```
|
| 8853 |
|
| 8854 |
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 8855 |
effect.
|
| 8856 |
|
| 8857 |
-
*
|
| 8858 |
-
|
| 8859 |
`rhs.recursion_pending()`, respectively, had before the function call.
|
| 8860 |
|
| 8861 |
*Returns:* `*this`.
|
| 8862 |
|
| 8863 |
``` cpp
|
|
@@ -8890,15 +9718,15 @@ subsequent to the prior construction or increment operation, otherwise
|
|
| 8890 |
|
| 8891 |
*Throws:* Nothing.
|
| 8892 |
|
| 8893 |
``` cpp
|
| 8894 |
recursive_directory_iterator& operator++();
|
| 8895 |
-
recursive_directory_iterator& increment(error_code& ec)
|
| 8896 |
```
|
| 8897 |
|
| 8898 |
*Effects:* As specified for the prefix increment operation of Input
|
| 8899 |
-
iterators
|
| 8900 |
|
| 8901 |
- If there are no more entries at the current depth, then if
|
| 8902 |
`depth() != 0` iteration over the parent directory resumes; otherwise
|
| 8903 |
`*this = recursive_directory_iterator()`.
|
| 8904 |
- Otherwise if
|
|
@@ -8932,20 +9760,23 @@ void pop(error_code& ec);
|
|
| 8932 |
directory currently being iterated over, and continue iteration over the
|
| 8933 |
parent directory.
|
| 8934 |
|
| 8935 |
*Throws:* As specified in [[fs.err.report]].
|
| 8936 |
|
|
|
|
|
|
|
|
|
|
| 8937 |
``` cpp
|
| 8938 |
void disable_recursion_pending();
|
| 8939 |
```
|
| 8940 |
|
| 8941 |
-
*
|
| 8942 |
|
| 8943 |
[*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
|
| 8944 |
recursion into a directory. — *end note*]
|
| 8945 |
|
| 8946 |
-
####
|
| 8947 |
|
| 8948 |
These functions enable use of `recursive_directory_iterator` with
|
| 8949 |
range-based for statements.
|
| 8950 |
|
| 8951 |
``` cpp
|
|
@@ -8964,11 +9795,11 @@ recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
|
|
| 8964 |
|
| 8965 |
Filesystem operation functions query or modify files, including
|
| 8966 |
directories, in external storage.
|
| 8967 |
|
| 8968 |
[*Note 1*: Because hardware failures, network failures, file system
|
| 8969 |
-
races
|
| 8970 |
frequently in file system operations, users should be aware that any
|
| 8971 |
filesystem operation function, no matter how apparently innocuous, may
|
| 8972 |
encounter an error; see [[fs.err.report]]. — *end note*]
|
| 8973 |
|
| 8974 |
#### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
|
|
@@ -8977,11 +9808,11 @@ encounter an error; see [[fs.err.report]]. — *end note*]
|
|
| 8977 |
path absolute(const path& p);
|
| 8978 |
path absolute(const path& p, error_code& ec);
|
| 8979 |
```
|
| 8980 |
|
| 8981 |
*Effects:* Composes an absolute path referencing the same file system
|
| 8982 |
-
location as `p` according to the operating system
|
| 8983 |
|
| 8984 |
*Returns:* The composed path. The signature with argument `ec` returns
|
| 8985 |
`path()` if an error occurs.
|
| 8986 |
|
| 8987 |
[*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
|
|
@@ -8989,11 +9820,11 @@ unless an error occurs. — *end note*]
|
|
| 8989 |
|
| 8990 |
*Throws:* As specified in [[fs.err.report]].
|
| 8991 |
|
| 8992 |
[*Note 2*: To resolve symlinks, or perform other sanitization which
|
| 8993 |
might require queries to secondary storage, such as hard disks, consider
|
| 8994 |
-
`canonical`
|
| 8995 |
|
| 8996 |
[*Note 3*: Implementations are strongly encouraged to not query
|
| 8997 |
secondary storage, and not consider `!exists(p)` an
|
| 8998 |
error. — *end note*]
|
| 8999 |
|
|
@@ -9003,22 +9834,19 @@ simply `current_path()/p`. For Windows-based operating systems,
|
|
| 9003 |
`GetFullPathNameW`. — *end example*]
|
| 9004 |
|
| 9005 |
#### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
|
| 9006 |
|
| 9007 |
``` cpp
|
| 9008 |
-
path canonical(const path& p
|
| 9009 |
path canonical(const path& p, error_code& ec);
|
| 9010 |
-
path canonical(const path& p, const path& base, error_code& ec);
|
| 9011 |
```
|
| 9012 |
|
| 9013 |
-
*Effects:* Converts `p`
|
| 9014 |
-
|
| 9015 |
-
generic format.
|
| 9016 |
|
| 9017 |
*Returns:* A path that refers to the same file system object as
|
| 9018 |
-
`absolute(p
|
| 9019 |
-
is `current_path()`. Signatures with argument `ec` return `path()` if an
|
| 9020 |
error occurs.
|
| 9021 |
|
| 9022 |
*Throws:* As specified in [[fs.err.report]].
|
| 9023 |
|
| 9024 |
*Remarks:* `!exists(p)` is an error.
|
|
@@ -9030,23 +9858,23 @@ void copy(const path& from, const path& to);
|
|
| 9030 |
```
|
| 9031 |
|
| 9032 |
*Effects:* Equivalent to `copy(from, to, copy_options::none)`.
|
| 9033 |
|
| 9034 |
``` cpp
|
| 9035 |
-
void copy(const path& from, const path& to, error_code& ec)
|
| 9036 |
```
|
| 9037 |
|
| 9038 |
*Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
|
| 9039 |
|
| 9040 |
``` cpp
|
| 9041 |
void copy(const path& from, const path& to, copy_options options);
|
| 9042 |
void copy(const path& from, const path& to, copy_options options,
|
| 9043 |
-
error_code& ec)
|
| 9044 |
```
|
| 9045 |
|
| 9046 |
-
*
|
| 9047 |
-
|
| 9048 |
|
| 9049 |
*Effects:* Before the first use of `f` and `t`:
|
| 9050 |
|
| 9051 |
- If
|
| 9052 |
``` cpp
|
|
@@ -9067,17 +9895,17 @@ void copy(const path& from, const path& to, copy_options options,
|
|
| 9067 |
`auto t = status(to)`.
|
| 9068 |
|
| 9069 |
Effects are then as follows:
|
| 9070 |
|
| 9071 |
- If `f.type()` or `t.type()` is an implementation-defined file
|
| 9072 |
-
type
|
| 9073 |
*implementation-defined*.
|
| 9074 |
- Otherwise, an error is reported as specified in [[fs.err.report]] if:
|
| 9075 |
-
- `
|
| 9076 |
-
- `equivalent(from, to)`, or
|
| 9077 |
-
- `is_other(f) || is_other(t)`, or
|
| 9078 |
-
- `is_directory(f) && is_regular_file(t)`.
|
| 9079 |
- Otherwise, if `is_symlink(f)`, then:
|
| 9080 |
- If `(options & copy_options::skip_symlinks) != copy_options::none`
|
| 9081 |
then return.
|
| 9082 |
- Otherwise if
|
| 9083 |
``` cpp
|
|
@@ -9097,24 +9925,36 @@ Effects are then as follows:
|
|
| 9097 |
`(options & copy_options::create_hard_links) != copy_options::none`,
|
| 9098 |
then create a hard link to the source file.
|
| 9099 |
- Otherwise, if `is_directory(t)`, then
|
| 9100 |
`copy_file(from, to/from.filename(), options)`.
|
| 9101 |
- Otherwise, `copy_file(from, to, options)`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9102 |
- Otherwise, if
|
| 9103 |
``` cpp
|
| 9104 |
is_directory(f) &&
|
| 9105 |
((options & copy_options::recursive) != copy_options::none ||
|
| 9106 |
options == copy_options::none)
|
| 9107 |
```
|
| 9108 |
|
| 9109 |
then:
|
| 9110 |
-
- If `
|
| 9111 |
- Then, iterate over the files in `from`, as if by
|
| 9112 |
``` cpp
|
| 9113 |
for (const directory_entry& x : directory_iterator(from))
|
| 9114 |
-
copy(x.path(), to/x.path().filename(),
|
|
|
|
| 9115 |
```
|
|
|
|
|
|
|
|
|
|
| 9116 |
- Otherwise, for the signature with argument `ec`, `ec.clear()`.
|
| 9117 |
- Otherwise, no effects.
|
| 9118 |
|
| 9119 |
*Throws:* As specified in [[fs.err.report]].
|
| 9120 |
|
|
@@ -9163,62 +10003,61 @@ would result in:
|
|
| 9163 |
file3
|
| 9164 |
```
|
| 9165 |
|
| 9166 |
— *end example*]
|
| 9167 |
|
| 9168 |
-
#### Copy file <a id="fs.op.
|
| 9169 |
|
| 9170 |
``` cpp
|
| 9171 |
bool copy_file(const path& from, const path& to);
|
| 9172 |
-
bool copy_file(const path& from, const path& to, error_code& ec)
|
| 9173 |
```
|
| 9174 |
|
| 9175 |
*Returns:* `copy_file(from, to, copy_options::none)` or
|
| 9176 |
`copy_file(from, to, copy_options::none, ec)`, respectively.
|
| 9177 |
|
| 9178 |
*Throws:* As specified in [[fs.err.report]].
|
| 9179 |
|
| 9180 |
``` cpp
|
| 9181 |
bool copy_file(const path& from, const path& to, copy_options options);
|
| 9182 |
bool copy_file(const path& from, const path& to, copy_options options,
|
| 9183 |
-
error_code& ec)
|
| 9184 |
```
|
| 9185 |
|
| 9186 |
-
*
|
| 9187 |
-
|
| 9188 |
|
| 9189 |
*Effects:* As follows:
|
| 9190 |
|
| 9191 |
-
- Report
|
| 9192 |
-
|
| 9193 |
-
- `
|
| 9194 |
-
- `exists(to)` and `
|
| 9195 |
-
- `exists(to)`
|
| 9196 |
-
- `exists(to)` and
|
| 9197 |
``` cpp
|
| 9198 |
(options & (copy_options::skip_existing |
|
| 9199 |
copy_options::overwrite_existing |
|
| 9200 |
copy_options::update_existing)) == copy_options::none
|
| 9201 |
```
|
| 9202 |
- Otherwise, copy the contents and attributes of the file `from`
|
| 9203 |
resolves to, to the file `to` resolves to, if:
|
| 9204 |
-
- `
|
| 9205 |
- `(options & copy_options::overwrite_existing) != copy_options::none`,
|
| 9206 |
or
|
| 9207 |
- `(options & copy_options::update_existing) `` `` != copy_options::none`
|
| 9208 |
and `from` is more recent than `to`, determined as if by use of the
|
| 9209 |
-
`last_write_time` function
|
| 9210 |
- Otherwise, no effects.
|
| 9211 |
|
| 9212 |
*Returns:* `true` if the `from` file was copied, otherwise `false`. The
|
| 9213 |
signature with argument `ec` returns `false` if an error occurs.
|
| 9214 |
|
| 9215 |
*Throws:* As specified in [[fs.err.report]].
|
| 9216 |
|
| 9217 |
*Complexity:* At most one direct or indirect invocation of `status(to)`.
|
| 9218 |
|
| 9219 |
-
#### Copy symlink <a id="fs.op.
|
| 9220 |
|
| 9221 |
``` cpp
|
| 9222 |
void copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 9223 |
void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 9224 |
error_code& ec) noexcept;
|
|
@@ -9230,86 +10069,78 @@ void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
|
| 9230 |
respectively, where in each case *`function`* is `create_symlink` or
|
| 9231 |
`create_directory_symlink` as appropriate.
|
| 9232 |
|
| 9233 |
*Throws:* As specified in [[fs.err.report]].
|
| 9234 |
|
| 9235 |
-
#### Create directories <a id="fs.op.
|
| 9236 |
|
| 9237 |
``` cpp
|
| 9238 |
bool create_directories(const path& p);
|
| 9239 |
-
bool create_directories(const path& p, error_code& ec)
|
| 9240 |
```
|
| 9241 |
|
| 9242 |
-
*Effects:*
|
| 9243 |
-
for any element of `p` that does not exist.
|
| 9244 |
-
|
| 9245 |
-
*Postconditions:* `is_directory(p)`.
|
| 9246 |
-
|
| 9247 |
-
*Returns:* `true` if a new directory was created, otherwise `false`. The
|
| 9248 |
-
signature with argument `ec` returns `false` if an error occurs.
|
| 9249 |
-
|
| 9250 |
-
*Throws:* As specified in [[fs.err.report]].
|
| 9251 |
-
|
| 9252 |
-
*Complexity:* 𝑂(n) where *n* is the number of elements of `p` that do
|
| 9253 |
not exist.
|
| 9254 |
|
| 9255 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9256 |
|
| 9257 |
``` cpp
|
| 9258 |
bool create_directory(const path& p);
|
| 9259 |
bool create_directory(const path& p, error_code& ec) noexcept;
|
| 9260 |
```
|
| 9261 |
|
| 9262 |
-
*Effects:*
|
| 9263 |
-
|
| 9264 |
-
|
| 9265 |
-
|
| 9266 |
|
| 9267 |
-
*
|
| 9268 |
-
|
| 9269 |
-
*Returns:* `true` if a new directory was created, otherwise `false`. The
|
| 9270 |
-
signature with argument `ec` returns `false` if an error occurs.
|
| 9271 |
|
| 9272 |
*Throws:* As specified in [[fs.err.report]].
|
| 9273 |
|
| 9274 |
``` cpp
|
| 9275 |
bool create_directory(const path& p, const path& existing_p);
|
| 9276 |
bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
|
| 9277 |
```
|
| 9278 |
|
| 9279 |
-
*Effects:*
|
| 9280 |
-
directory `
|
| 9281 |
-
|
| 9282 |
-
|
| 9283 |
-
|
| 9284 |
|
| 9285 |
[*Note 1*: For POSIX-based operating systems, the attributes are those
|
| 9286 |
copied by native API `stat(existing_p.c_str(), &attributes_stat)`
|
| 9287 |
followed by `mkdir(p.c_str(), attributes_stat.st_mode)`. For
|
| 9288 |
Windows-based operating systems, the attributes are those copied by
|
| 9289 |
native API
|
| 9290 |
`CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0)`. — *end note*]
|
| 9291 |
|
| 9292 |
-
*
|
| 9293 |
-
|
| 9294 |
-
*Returns:* `true` if a new directory was created, otherwise `false`. The
|
| 9295 |
-
signature with argument `ec` returns `false` if an error occurs.
|
| 9296 |
|
| 9297 |
*Throws:* As specified in [[fs.err.report]].
|
| 9298 |
|
| 9299 |
-
#### Create directory symlink <a id="fs.op.
|
| 9300 |
|
| 9301 |
``` cpp
|
| 9302 |
void create_directory_symlink(const path& to, const path& new_symlink);
|
| 9303 |
void create_directory_symlink(const path& to, const path& new_symlink,
|
| 9304 |
error_code& ec) noexcept;
|
| 9305 |
```
|
| 9306 |
|
| 9307 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 9308 |
|
| 9309 |
-
*
|
| 9310 |
-
|
| 9311 |
|
| 9312 |
*Throws:* As specified in [[fs.err.report]].
|
| 9313 |
|
| 9314 |
[*Note 1*: Some operating systems require symlink creation to identify
|
| 9315 |
that the link is to a directory. Portable code should use
|
|
@@ -9319,21 +10150,21 @@ that the link is to a directory. Portable code should use
|
|
| 9319 |
[*Note 2*: Some operating systems do not support symbolic links at all
|
| 9320 |
or support them only for regular files. Some file systems (such as the
|
| 9321 |
FAT file system) do not support symbolic links regardless of the
|
| 9322 |
operating system. — *end note*]
|
| 9323 |
|
| 9324 |
-
#### Create hard link <a id="fs.op.
|
| 9325 |
|
| 9326 |
``` cpp
|
| 9327 |
void create_hard_link(const path& to, const path& new_hard_link);
|
| 9328 |
void create_hard_link(const path& to, const path& new_hard_link,
|
| 9329 |
error_code& ec) noexcept;
|
| 9330 |
```
|
| 9331 |
|
| 9332 |
*Effects:* Establishes the postcondition, as if by POSIX `link()`.
|
| 9333 |
|
| 9334 |
-
*
|
| 9335 |
|
| 9336 |
- `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
|
| 9337 |
- The contents of the file or directory `to` resolves to are unchanged.
|
| 9338 |
|
| 9339 |
*Throws:* As specified in [[fs.err.report]].
|
|
@@ -9342,31 +10173,31 @@ void create_hard_link(const path& to, const path& new_hard_link,
|
|
| 9342 |
support them only for regular files. Some file systems (such as the FAT
|
| 9343 |
file system) do not support hard links regardless of the operating
|
| 9344 |
system. Some file systems limit the number of links per
|
| 9345 |
file. — *end note*]
|
| 9346 |
|
| 9347 |
-
#### Create symlink <a id="fs.op.
|
| 9348 |
|
| 9349 |
``` cpp
|
| 9350 |
void create_symlink(const path& to, const path& new_symlink);
|
| 9351 |
void create_symlink(const path& to, const path& new_symlink,
|
| 9352 |
error_code& ec) noexcept;
|
| 9353 |
```
|
| 9354 |
|
| 9355 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 9356 |
|
| 9357 |
-
*
|
| 9358 |
-
|
| 9359 |
|
| 9360 |
*Throws:* As specified in [[fs.err.report]].
|
| 9361 |
|
| 9362 |
[*Note 1*: Some operating systems do not support symbolic links at all
|
| 9363 |
or support them only for regular files. Some file systems (such as the
|
| 9364 |
FAT file system) do not support symbolic links regardless of the
|
| 9365 |
operating system. — *end note*]
|
| 9366 |
|
| 9367 |
-
#### Current path <a id="fs.op.
|
| 9368 |
|
| 9369 |
``` cpp
|
| 9370 |
path current_path();
|
| 9371 |
path current_path(error_code& ec);
|
| 9372 |
```
|
|
@@ -9384,22 +10215,21 @@ resolution for relative paths.
|
|
| 9384 |
[*Note 1*: The `current_path()` name was chosen to emphasize that the
|
| 9385 |
returned value is a path, not just a single directory
|
| 9386 |
name. — *end note*]
|
| 9387 |
|
| 9388 |
[*Note 2*: The current path as returned by many operating systems is a
|
| 9389 |
-
dangerous global variable. It may be changed unexpectedly by
|
| 9390 |
-
|
| 9391 |
-
thread. — *end note*]
|
| 9392 |
|
| 9393 |
``` cpp
|
| 9394 |
void current_path(const path& p);
|
| 9395 |
void current_path(const path& p, error_code& ec) noexcept;
|
| 9396 |
```
|
| 9397 |
|
| 9398 |
*Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
|
| 9399 |
|
| 9400 |
-
*
|
| 9401 |
|
| 9402 |
*Throws:* As specified in [[fs.err.report]].
|
| 9403 |
|
| 9404 |
[*Note 3*: The current path for many operating systems is a dangerous
|
| 9405 |
global state. It may be changed unexpectedly by a third-party or system
|
|
@@ -9410,26 +10240,22 @@ library functions, or by another thread. — *end note*]
|
|
| 9410 |
``` cpp
|
| 9411 |
bool equivalent(const path& p1, const path& p2);
|
| 9412 |
bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 9413 |
```
|
| 9414 |
|
| 9415 |
-
|
| 9416 |
-
|
| 9417 |
-
|
| 9418 |
-
*Effects:* Determines `s1` and `s2`. If
|
| 9419 |
-
`(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))` an
|
| 9420 |
-
error is reported ([[fs.err.report]]).
|
| 9421 |
-
|
| 9422 |
-
*Returns:* `true`, if `s1 == s2` and `p1` and `p2` resolve to the same
|
| 9423 |
-
file system entity, else `false`. The signature with argument `ec`
|
| 9424 |
-
returns `false` if an error occurs.
|
| 9425 |
|
| 9426 |
Two paths are considered to resolve to the same file system entity if
|
| 9427 |
two candidate entities reside on the same device at the same location.
|
| 9428 |
-
|
| 9429 |
-
|
| 9430 |
-
|
|
|
|
|
|
|
|
|
|
| 9431 |
|
| 9432 |
*Throws:* As specified in [[fs.err.report]].
|
| 9433 |
|
| 9434 |
#### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
|
| 9435 |
|
|
@@ -9452,31 +10278,33 @@ Let `s` be a `file_status`, determined as if by `status(p)` or
|
|
| 9452 |
|
| 9453 |
*Returns:* `exists(s)`.
|
| 9454 |
|
| 9455 |
*Throws:* As specified in [[fs.err.report]].
|
| 9456 |
|
| 9457 |
-
#### File size <a id="fs.op.
|
| 9458 |
|
| 9459 |
``` cpp
|
| 9460 |
uintmax_t file_size(const path& p);
|
| 9461 |
uintmax_t file_size(const path& p, error_code& ec) noexcept;
|
| 9462 |
```
|
| 9463 |
|
|
|
|
|
|
|
|
|
|
| 9464 |
*Returns:*
|
| 9465 |
|
| 9466 |
-
- If `
|
| 9467 |
-
|
| 9468 |
-
|
| 9469 |
-
structure member `st_size` obtained as if by POSIX `stat()`.
|
| 9470 |
- Otherwise, the result is *implementation-defined*.
|
| 9471 |
|
| 9472 |
The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
|
| 9473 |
an error occurs.
|
| 9474 |
|
| 9475 |
*Throws:* As specified in [[fs.err.report]].
|
| 9476 |
|
| 9477 |
-
#### Hard link count <a id="fs.op.
|
| 9478 |
|
| 9479 |
``` cpp
|
| 9480 |
uintmax_t hard_link_count(const path& p);
|
| 9481 |
uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
| 9482 |
```
|
|
@@ -9484,11 +10312,11 @@ uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
|
| 9484 |
*Returns:* The number of hard links for `p`. The signature with argument
|
| 9485 |
`ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
|
| 9486 |
|
| 9487 |
*Throws:* As specified in [[fs.err.report]].
|
| 9488 |
|
| 9489 |
-
#### Is block file <a id="fs.op.
|
| 9490 |
|
| 9491 |
``` cpp
|
| 9492 |
bool is_block_file(file_status s) noexcept;
|
| 9493 |
```
|
| 9494 |
|
|
@@ -9503,11 +10331,11 @@ bool is_block_file(const path& p, error_code& ec) noexcept;
|
|
| 9503 |
respectively. The signature with argument `ec` returns `false` if an
|
| 9504 |
error occurs.
|
| 9505 |
|
| 9506 |
*Throws:* As specified in [[fs.err.report]].
|
| 9507 |
|
| 9508 |
-
#### Is character file <a id="fs.op.
|
| 9509 |
|
| 9510 |
``` cpp
|
| 9511 |
bool is_character_file(file_status s) noexcept;
|
| 9512 |
```
|
| 9513 |
|
|
@@ -9522,11 +10350,11 @@ bool is_character_file(const path& p, error_code& ec) noexcept;
|
|
| 9522 |
`is_character_file(status(p, ec))`, respectively.
|
| 9523 |
The signature with argument `ec` returns `false` if an error occurs.
|
| 9524 |
|
| 9525 |
*Throws:* As specified in [[fs.err.report]].
|
| 9526 |
|
| 9527 |
-
#### Is directory <a id="fs.op.
|
| 9528 |
|
| 9529 |
``` cpp
|
| 9530 |
bool is_directory(file_status s) noexcept;
|
| 9531 |
```
|
| 9532 |
|
|
@@ -9541,15 +10369,15 @@ bool is_directory(const path& p, error_code& ec) noexcept;
|
|
| 9541 |
respectively. The signature with argument `ec` returns `false` if an
|
| 9542 |
error occurs.
|
| 9543 |
|
| 9544 |
*Throws:* As specified in [[fs.err.report]].
|
| 9545 |
|
| 9546 |
-
#### Is empty <a id="fs.op.
|
| 9547 |
|
| 9548 |
``` cpp
|
| 9549 |
bool is_empty(const path& p);
|
| 9550 |
-
bool is_empty(const path& p, error_code& ec)
|
| 9551 |
```
|
| 9552 |
|
| 9553 |
*Effects:*
|
| 9554 |
|
| 9555 |
- Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
|
|
@@ -9569,11 +10397,11 @@ bool is_empty(const path& p, error_code& ec) noexcept;
|
|
| 9569 |
occurred.
|
| 9570 |
- Otherwise, return `sz == 0`.
|
| 9571 |
|
| 9572 |
*Throws:* As specified in [[fs.err.report]].
|
| 9573 |
|
| 9574 |
-
#### Is fifo <a id="fs.op.
|
| 9575 |
|
| 9576 |
``` cpp
|
| 9577 |
bool is_fifo(file_status s) noexcept;
|
| 9578 |
```
|
| 9579 |
|
|
@@ -9588,11 +10416,11 @@ bool is_fifo(const path& p, error_code& ec) noexcept;
|
|
| 9588 |
respectively. The signature with argument `ec` returns `false` if an
|
| 9589 |
error occurs.
|
| 9590 |
|
| 9591 |
*Throws:* As specified in [[fs.err.report]].
|
| 9592 |
|
| 9593 |
-
#### Is other <a id="fs.op.
|
| 9594 |
|
| 9595 |
``` cpp
|
| 9596 |
bool is_other(file_status s) noexcept;
|
| 9597 |
```
|
| 9598 |
|
|
@@ -9608,11 +10436,11 @@ bool is_other(const path& p, error_code& ec) noexcept;
|
|
| 9608 |
respectively. The signature with argument `ec` returns `false` if an
|
| 9609 |
error occurs.
|
| 9610 |
|
| 9611 |
*Throws:* As specified in [[fs.err.report]].
|
| 9612 |
|
| 9613 |
-
#### Is regular file <a id="fs.op.
|
| 9614 |
|
| 9615 |
``` cpp
|
| 9616 |
bool is_regular_file(file_status s) noexcept;
|
| 9617 |
```
|
| 9618 |
|
|
@@ -9623,11 +10451,11 @@ bool is_regular_file(const path& p);
|
|
| 9623 |
```
|
| 9624 |
|
| 9625 |
*Returns:* `is_regular_file(status(p))`.
|
| 9626 |
|
| 9627 |
*Throws:* `filesystem_error` if `status(p)` would throw
|
| 9628 |
-
`filesystem_error
|
| 9629 |
|
| 9630 |
``` cpp
|
| 9631 |
bool is_regular_file(const path& p, error_code& ec) noexcept;
|
| 9632 |
```
|
| 9633 |
|
|
@@ -9638,11 +10466,11 @@ bool is_regular_file(const path& p, error_code& ec) noexcept;
|
|
| 9638 |
between cases, call the `status` function directly. — *end note*]
|
| 9639 |
|
| 9640 |
*Returns:* `is_regular_file(status(p, ec))`. Returns `false` if an error
|
| 9641 |
occurs.
|
| 9642 |
|
| 9643 |
-
#### Is socket <a id="fs.op.
|
| 9644 |
|
| 9645 |
``` cpp
|
| 9646 |
bool is_socket(file_status s) noexcept;
|
| 9647 |
```
|
| 9648 |
|
|
@@ -9657,11 +10485,11 @@ bool is_socket(const path& p, error_code& ec) noexcept;
|
|
| 9657 |
respectively. The signature with argument `ec` returns `false` if an
|
| 9658 |
error occurs.
|
| 9659 |
|
| 9660 |
*Throws:* As specified in [[fs.err.report]].
|
| 9661 |
|
| 9662 |
-
#### Is symlink <a id="fs.op.
|
| 9663 |
|
| 9664 |
``` cpp
|
| 9665 |
bool is_symlink(file_status s) noexcept;
|
| 9666 |
```
|
| 9667 |
|
|
@@ -9676,20 +10504,20 @@ bool is_symlink(const path& p, error_code& ec) noexcept;
|
|
| 9676 |
`is_symlink(symlink_status(p, ec))`, respectively. The signature with
|
| 9677 |
argument `ec` returns `false` if an error occurs.
|
| 9678 |
|
| 9679 |
*Throws:* As specified in [[fs.err.report]].
|
| 9680 |
|
| 9681 |
-
#### Last write time <a id="fs.op.
|
| 9682 |
|
| 9683 |
``` cpp
|
| 9684 |
file_time_type last_write_time(const path& p);
|
| 9685 |
file_time_type last_write_time(const path& p, error_code& ec) noexcept;
|
| 9686 |
```
|
| 9687 |
|
| 9688 |
*Returns:* The time of last data modification of `p`, determined as if
|
| 9689 |
-
by the value of the POSIX `stat`
|
| 9690 |
-
|
| 9691 |
`file_time_type::min()` if an error occurs.
|
| 9692 |
|
| 9693 |
*Throws:* As specified in [[fs.err.report]].
|
| 9694 |
|
| 9695 |
``` cpp
|
|
@@ -9713,11 +10541,11 @@ granularity. — *end note*]
|
|
| 9713 |
void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
|
| 9714 |
void permissions(const path& p, perms prms, error_code& ec) noexcept;
|
| 9715 |
void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
|
| 9716 |
```
|
| 9717 |
|
| 9718 |
-
*
|
| 9719 |
`add`, or `remove` is present in `opts`.
|
| 9720 |
|
| 9721 |
*Remarks:* The second signature behaves as if it had an additional
|
| 9722 |
parameter `perm_options` `opts` with an argument of
|
| 9723 |
`perm_options::replace`.
|
|
@@ -9761,11 +10589,11 @@ weakly_canonical(p, ec).lexically_proximate(weakly_canonical(base, ec));
|
|
| 9761 |
|
| 9762 |
or `path()` at the first error occurrence, if any.
|
| 9763 |
|
| 9764 |
*Throws:* As specified in [[fs.err.report]].
|
| 9765 |
|
| 9766 |
-
#### Read symlink <a id="fs.op.
|
| 9767 |
|
| 9768 |
``` cpp
|
| 9769 |
path read_symlink(const path& p);
|
| 9770 |
path read_symlink(const path& p, error_code& ec);
|
| 9771 |
```
|
|
@@ -9821,31 +10649,31 @@ bool remove(const path& p, error_code& ec) noexcept;
|
|
| 9821 |
as if by POSIX `remove()`.
|
| 9822 |
|
| 9823 |
[*Note 1*: A symbolic link is itself removed, rather than the file it
|
| 9824 |
resolves to. — *end note*]
|
| 9825 |
|
| 9826 |
-
*
|
| 9827 |
|
| 9828 |
*Returns:* `false` if `p` did not exist, otherwise `true`. The signature
|
| 9829 |
with argument `ec` returns `false` if an error occurs.
|
| 9830 |
|
| 9831 |
*Throws:* As specified in [[fs.err.report]].
|
| 9832 |
|
| 9833 |
-
#### Remove all <a id="fs.op.
|
| 9834 |
|
| 9835 |
``` cpp
|
| 9836 |
uintmax_t remove_all(const path& p);
|
| 9837 |
-
uintmax_t remove_all(const path& p, error_code& ec)
|
| 9838 |
```
|
| 9839 |
|
| 9840 |
*Effects:* Recursively deletes the contents of `p` if it exists, then
|
| 9841 |
deletes file `p` itself, as if by POSIX `remove()`.
|
| 9842 |
|
| 9843 |
[*Note 1*: A symbolic link is itself removed, rather than the file it
|
| 9844 |
resolves to. — *end note*]
|
| 9845 |
|
| 9846 |
-
*
|
| 9847 |
|
| 9848 |
*Returns:* The number of files removed. The signature with argument `ec`
|
| 9849 |
returns `static_cast< uintmax_t>(-1)` if an error occurs.
|
| 9850 |
|
| 9851 |
*Throws:* As specified in [[fs.err.report]].
|
|
@@ -9874,23 +10702,22 @@ A symbolic link is itself renamed, rather than the file it resolves to.
|
|
| 9874 |
|
| 9875 |
— *end note*]
|
| 9876 |
|
| 9877 |
*Throws:* As specified in [[fs.err.report]].
|
| 9878 |
|
| 9879 |
-
#### Resize file <a id="fs.op.
|
| 9880 |
|
| 9881 |
``` cpp
|
| 9882 |
void resize_file(const path& p, uintmax_t new_size);
|
| 9883 |
void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
|
| 9884 |
```
|
| 9885 |
|
| 9886 |
-
*
|
|
|
|
| 9887 |
|
| 9888 |
*Throws:* As specified in [[fs.err.report]].
|
| 9889 |
|
| 9890 |
-
*Remarks:* Achieves its postconditions as if by POSIX `truncate()`.
|
| 9891 |
-
|
| 9892 |
#### Space <a id="fs.op.space">[[fs.op.space]]</a>
|
| 9893 |
|
| 9894 |
``` cpp
|
| 9895 |
space_info space(const path& p);
|
| 9896 |
space_info space(const path& p, error_code& ec) noexcept;
|
|
@@ -9989,27 +10816,27 @@ determined as if by converting the `st_mode` member of the obtained
|
|
| 9989 |
- Otherwise, if the attributes indicate a fifo or pipe file, as if by
|
| 9990 |
POSIX `S_ISFIFO`, returns `file_status(file_type::fifo, prms)`.
|
| 9991 |
- Otherwise, if the attributes indicate a socket, as if by POSIX
|
| 9992 |
`S_ISSOCK`, returns `file_status(file_type::socket, prms)`.
|
| 9993 |
- Otherwise, if the attributes indicate an implementation-defined file
|
| 9994 |
-
type
|
| 9995 |
`file_status(file_type::`*`A`*`, prms)`, where *A* is the constant
|
| 9996 |
for the *implementation-defined* file type.
|
| 9997 |
- Otherwise, returns `file_status(file_type::unknown, prms)`.
|
| 9998 |
|
| 9999 |
*Remarks:* If a symbolic link is encountered during pathname resolution,
|
| 10000 |
pathname resolution continues using the contents of the symbolic link.
|
| 10001 |
|
| 10002 |
-
#### Status known <a id="fs.op.
|
| 10003 |
|
| 10004 |
``` cpp
|
| 10005 |
bool status_known(file_status s) noexcept;
|
| 10006 |
```
|
| 10007 |
|
| 10008 |
*Returns:* `s.type() != file_type::none`.
|
| 10009 |
|
| 10010 |
-
#### Symlink status <a id="fs.op.
|
| 10011 |
|
| 10012 |
``` cpp
|
| 10013 |
file_status symlink_status(const path& p);
|
| 10014 |
file_status symlink_status(const path& p, error_code& ec) noexcept;
|
| 10015 |
```
|
|
@@ -10029,20 +10856,23 @@ indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
|
|
| 10029 |
|
| 10030 |
*Remarks:* Pathname resolution terminates if `p` names a symbolic link.
|
| 10031 |
|
| 10032 |
*Throws:* As specified in [[fs.err.report]].
|
| 10033 |
|
| 10034 |
-
#### Temporary directory path <a id="fs.op.
|
| 10035 |
|
| 10036 |
``` cpp
|
| 10037 |
path temp_directory_path();
|
| 10038 |
path temp_directory_path(error_code& ec);
|
| 10039 |
```
|
| 10040 |
|
| 10041 |
-
|
| 10042 |
-
|
| 10043 |
-
|
|
|
|
|
|
|
|
|
|
| 10044 |
`path()` if an error occurs.
|
| 10045 |
|
| 10046 |
*Throws:* As specified in [[fs.err.report]].
|
| 10047 |
|
| 10048 |
[*Example 1*: For POSIX-based operating systems, an implementation
|
|
@@ -10050,36 +10880,33 @@ might return the path supplied by the first environment variable found
|
|
| 10050 |
in the list TMPDIR, TMP, TEMP, TEMPDIR, or if none of these are found,
|
| 10051 |
`"/tmp"`. For Windows-based operating systems, an implementation might
|
| 10052 |
return the path reported by the Windows `GetTempPath` API
|
| 10053 |
function. — *end example*]
|
| 10054 |
|
| 10055 |
-
#### Weakly canonical <a id="fs.op.
|
| 10056 |
|
| 10057 |
``` cpp
|
| 10058 |
path weakly_canonical(const path& p);
|
| 10059 |
path weakly_canonical(const path& p, error_code& ec);
|
| 10060 |
```
|
| 10061 |
|
| 10062 |
*Returns:* `p` with symlinks resolved and the result
|
| 10063 |
-
normalized
|
| 10064 |
|
| 10065 |
*Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
|
| 10066 |
determine existence, return a path composed by `operator/=` from the
|
| 10067 |
-
result of calling `canonical()`
|
| 10068 |
-
|
| 10069 |
-
|
| 10070 |
-
|
| 10071 |
-
|
| 10072 |
-
`
|
| 10073 |
-
occurrence, if any.
|
| 10074 |
|
| 10075 |
-
*
|
| 10076 |
-
form ([[fs.def.normal.form]]).
|
| 10077 |
|
| 10078 |
-
*Remarks:* Implementations
|
| 10079 |
-
|
| 10080 |
-
entirety of `p`.
|
| 10081 |
|
| 10082 |
*Throws:* As specified in [[fs.err.report]].
|
| 10083 |
|
| 10084 |
## C library files <a id="c.files">[[c.files]]</a>
|
| 10085 |
|
|
@@ -10109,11 +10936,11 @@ namespace std {
|
|
| 10109 |
#define stdin see below
|
| 10110 |
#define stdout see below
|
| 10111 |
|
| 10112 |
namespace std {
|
| 10113 |
int remove(const char* filename);
|
| 10114 |
-
int rename(const char*
|
| 10115 |
FILE* tmpfile();
|
| 10116 |
char* tmpnam(char* s);
|
| 10117 |
int fclose(FILE* stream);
|
| 10118 |
int fflush(FILE* stream);
|
| 10119 |
FILE* fopen(const char* filename, const char* mode);
|
|
@@ -10160,14 +10987,14 @@ namespace std {
|
|
| 10160 |
|
| 10161 |
The contents and meaning of the header `<cstdio>` are the same as the C
|
| 10162 |
standard library header `<stdio.h>`.
|
| 10163 |
|
| 10164 |
Calls to the function `tmpnam` with an argument that is a null pointer
|
| 10165 |
-
value may introduce a data race
|
| 10166 |
-
|
| 10167 |
|
| 10168 |
-
ISO C
|
| 10169 |
|
| 10170 |
### Header `<cinttypes>` synopsis <a id="cinttypes.syn">[[cinttypes.syn]]</a>
|
| 10171 |
|
| 10172 |
``` cpp
|
| 10173 |
#include <cstdint> // see [cstdint.syn]
|
|
@@ -10246,145 +11073,139 @@ namespace std {
|
|
| 10246 |
The contents and meaning of the header `<cinttypes>` are the same as the
|
| 10247 |
C standard library header `<inttypes.h>`, with the following changes:
|
| 10248 |
|
| 10249 |
- The header `<cinttypes>` includes the header `<cstdint>` instead of
|
| 10250 |
`<stdint.h>`, and
|
| 10251 |
-
- if and only if the type `intmax_t` designates an extended integer
|
| 10252 |
-
|
| 10253 |
-
added:
|
| 10254 |
``` cpp
|
| 10255 |
intmax_t abs(intmax_t);
|
| 10256 |
imaxdiv_t div(intmax_t, intmax_t);
|
| 10257 |
```
|
| 10258 |
|
| 10259 |
which shall have the same semantics as the function signatures
|
| 10260 |
`intmax_t imaxabs(intmax_t)` and
|
| 10261 |
`imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
|
| 10262 |
|
| 10263 |
-
ISO C
|
| 10264 |
|
| 10265 |
<!-- Link reference definitions -->
|
| 10266 |
[adjustfield.manip]: #adjustfield.manip
|
| 10267 |
-
[allocator.requirements]: library.md#allocator.requirements
|
| 10268 |
[basefield.manip]: #basefield.manip
|
| 10269 |
[basic.fundamental]: basic.md#basic.fundamental
|
| 10270 |
[basic.ios.cons]: #basic.ios.cons
|
|
|
|
| 10271 |
[basic.ios.members]: #basic.ios.members
|
| 10272 |
[basic.start.main]: basic.md#basic.start.main
|
| 10273 |
[bidirectional.iterators]: iterators.md#bidirectional.iterators
|
| 10274 |
[bitmask.types]: library.md#bitmask.types
|
| 10275 |
[c.files]: #c.files
|
|
|
|
| 10276 |
[cinttypes.syn]: #cinttypes.syn
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 10277 |
[cstdio.syn]: #cstdio.syn
|
| 10278 |
[defns.ntcts]: library.md#defns.ntcts
|
| 10279 |
[enumerated.types]: library.md#enumerated.types
|
| 10280 |
[error.reporting]: #error.reporting
|
| 10281 |
[ext.manip]: #ext.manip
|
| 10282 |
-
[fig:streampos]: #fig:streampos
|
| 10283 |
[file.streams]: #file.streams
|
| 10284 |
[filebuf]: #filebuf
|
| 10285 |
[filebuf.assign]: #filebuf.assign
|
| 10286 |
[filebuf.cons]: #filebuf.cons
|
| 10287 |
[filebuf.members]: #filebuf.members
|
|
|
|
|
|
|
| 10288 |
[filebuf.virtuals]: #filebuf.virtuals
|
| 10289 |
-
[filesystem_error.members]: #filesystem_error.members
|
| 10290 |
[filesystems]: #filesystems
|
| 10291 |
[floatfield.manip]: #floatfield.manip
|
| 10292 |
[fmtflags.manip]: #fmtflags.manip
|
| 10293 |
[fmtflags.state]: #fmtflags.state
|
| 10294 |
[fpos]: #fpos
|
| 10295 |
[fpos.members]: #fpos.members
|
| 10296 |
[fpos.operations]: #fpos.operations
|
| 10297 |
-
[fs.class.
|
| 10298 |
-
[fs.class.
|
| 10299 |
-
[fs.class.
|
| 10300 |
-
[fs.class.
|
| 10301 |
[fs.class.path]: #fs.class.path
|
| 10302 |
[fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
|
| 10303 |
[fs.conform.9945]: #fs.conform.9945
|
| 10304 |
[fs.conform.os]: #fs.conform.os
|
| 10305 |
[fs.conformance]: #fs.conformance
|
| 10306 |
-
[fs.def.absolute.path]: #fs.def.absolute.path
|
| 10307 |
-
[fs.def.filename]: #fs.def.filename
|
| 10308 |
-
[fs.def.link]: #fs.def.link
|
| 10309 |
-
[fs.def.native]: #fs.def.native
|
| 10310 |
-
[fs.def.native.encode]: #fs.def.native.encode
|
| 10311 |
-
[fs.def.normal.form]: #fs.def.normal.form
|
| 10312 |
-
[fs.def.osdep]: #fs.def.osdep
|
| 10313 |
-
[fs.def.path]: #fs.def.path
|
| 10314 |
-
[fs.def.pathname]: #fs.def.pathname
|
| 10315 |
-
[fs.def.pathres]: #fs.def.pathres
|
| 10316 |
-
[fs.def.race]: #fs.def.race
|
| 10317 |
-
[fs.def.symlink]: #fs.def.symlink
|
| 10318 |
-
[fs.definitions]: #fs.definitions
|
| 10319 |
[fs.dir.entry.cons]: #fs.dir.entry.cons
|
| 10320 |
[fs.dir.entry.mods]: #fs.dir.entry.mods
|
| 10321 |
[fs.dir.entry.obs]: #fs.dir.entry.obs
|
| 10322 |
[fs.dir.itr.members]: #fs.dir.itr.members
|
| 10323 |
[fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
|
| 10324 |
[fs.enum]: #fs.enum
|
| 10325 |
[fs.enum.copy.opts]: #fs.enum.copy.opts
|
| 10326 |
[fs.enum.dir.opts]: #fs.enum.dir.opts
|
| 10327 |
-
[fs.enum.
|
| 10328 |
[fs.enum.path.format]: #fs.enum.path.format
|
| 10329 |
[fs.enum.perm.opts]: #fs.enum.perm.opts
|
| 10330 |
[fs.enum.perms]: #fs.enum.perms
|
| 10331 |
[fs.err.report]: #fs.err.report
|
| 10332 |
-
[fs.
|
| 10333 |
-
[fs.
|
| 10334 |
-
[fs.
|
|
|
|
| 10335 |
[fs.filesystem.syn]: #fs.filesystem.syn
|
| 10336 |
[fs.general]: #fs.general
|
| 10337 |
[fs.norm.ref]: #fs.norm.ref
|
| 10338 |
[fs.op.absolute]: #fs.op.absolute
|
| 10339 |
[fs.op.canonical]: #fs.op.canonical
|
| 10340 |
[fs.op.copy]: #fs.op.copy
|
| 10341 |
-
[fs.op.
|
| 10342 |
-
[fs.op.
|
| 10343 |
-
[fs.op.
|
| 10344 |
-
[fs.op.
|
| 10345 |
-
[fs.op.
|
| 10346 |
-
[fs.op.
|
| 10347 |
-
[fs.op.
|
| 10348 |
-
[fs.op.
|
| 10349 |
[fs.op.equivalent]: #fs.op.equivalent
|
| 10350 |
[fs.op.exists]: #fs.op.exists
|
| 10351 |
-
[fs.op.
|
| 10352 |
[fs.op.funcs]: #fs.op.funcs
|
| 10353 |
-
[fs.op.
|
| 10354 |
-
[fs.op.
|
| 10355 |
-
[fs.op.
|
| 10356 |
-
[fs.op.
|
| 10357 |
-
[fs.op.
|
| 10358 |
-
[fs.op.
|
| 10359 |
-
[fs.op.
|
| 10360 |
-
[fs.op.
|
| 10361 |
-
[fs.op.
|
| 10362 |
-
[fs.op.
|
| 10363 |
-
[fs.op.
|
| 10364 |
[fs.op.permissions]: #fs.op.permissions
|
| 10365 |
[fs.op.proximate]: #fs.op.proximate
|
| 10366 |
-
[fs.op.
|
| 10367 |
[fs.op.relative]: #fs.op.relative
|
| 10368 |
[fs.op.remove]: #fs.op.remove
|
| 10369 |
-
[fs.op.
|
| 10370 |
[fs.op.rename]: #fs.op.rename
|
| 10371 |
-
[fs.op.
|
| 10372 |
[fs.op.space]: #fs.op.space
|
| 10373 |
[fs.op.status]: #fs.op.status
|
| 10374 |
-
[fs.op.
|
| 10375 |
-
[fs.op.
|
| 10376 |
-
[fs.op.
|
| 10377 |
-
[fs.op.
|
| 10378 |
[fs.path.append]: #fs.path.append
|
| 10379 |
[fs.path.assign]: #fs.path.assign
|
| 10380 |
[fs.path.compare]: #fs.path.compare
|
| 10381 |
[fs.path.concat]: #fs.path.concat
|
| 10382 |
[fs.path.construct]: #fs.path.construct
|
| 10383 |
[fs.path.cvt]: #fs.path.cvt
|
| 10384 |
[fs.path.decompose]: #fs.path.decompose
|
| 10385 |
-
[fs.path.factory]: #fs.path.factory
|
| 10386 |
[fs.path.fmt.cvt]: #fs.path.fmt.cvt
|
| 10387 |
[fs.path.gen]: #fs.path.gen
|
| 10388 |
[fs.path.generic]: #fs.path.generic
|
| 10389 |
[fs.path.generic.obs]: #fs.path.generic.obs
|
| 10390 |
[fs.path.io]: #fs.path.io
|
|
@@ -10412,28 +11233,30 @@ ISO C 7.8.
|
|
| 10412 |
[ifstream.members]: #ifstream.members
|
| 10413 |
[input.iterators]: iterators.md#input.iterators
|
| 10414 |
[input.output]: #input.output
|
| 10415 |
[input.output.general]: #input.output.general
|
| 10416 |
[input.streams]: #input.streams
|
| 10417 |
-
[intro.multithread]:
|
|
|
|
| 10418 |
[iomanip.syn]: #iomanip.syn
|
| 10419 |
[ios]: #ios
|
| 10420 |
[ios.base]: #ios.base
|
| 10421 |
[ios.base.callback]: #ios.base.callback
|
| 10422 |
[ios.base.cons]: #ios.base.cons
|
| 10423 |
[ios.base.locales]: #ios.base.locales
|
| 10424 |
[ios.base.storage]: #ios.base.storage
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 10425 |
[ios.members.static]: #ios.members.static
|
|
|
|
| 10426 |
[ios.overview]: #ios.overview
|
|
|
|
| 10427 |
[ios.syn]: #ios.syn
|
| 10428 |
[ios.types]: #ios.types
|
| 10429 |
-
[ios::Init]: #ios::Init
|
| 10430 |
-
[ios::failure]: #ios::failure
|
| 10431 |
-
[ios::fmtflags]: #ios::fmtflags
|
| 10432 |
-
[ios::iostate]: #ios::iostate
|
| 10433 |
-
[ios::openmode]: #ios::openmode
|
| 10434 |
-
[ios::seekdir]: #ios::seekdir
|
| 10435 |
[iosfwd.syn]: #iosfwd.syn
|
| 10436 |
[iostate.flags]: #iostate.flags
|
| 10437 |
[iostream.assign]: #iostream.assign
|
| 10438 |
[iostream.cons]: #iostream.cons
|
| 10439 |
[iostream.dest]: #iostream.dest
|
|
@@ -10446,32 +11269,34 @@ ISO C 7.8.
|
|
| 10446 |
[iostream.syn]: #iostream.syn
|
| 10447 |
[iostreamclass]: #iostreamclass
|
| 10448 |
[iostreams.base]: #iostreams.base
|
| 10449 |
[iostreams.limits.pos]: #iostreams.limits.pos
|
| 10450 |
[iostreams.requirements]: #iostreams.requirements
|
|
|
|
| 10451 |
[iostreams.threadsafety]: #iostreams.threadsafety
|
| 10452 |
[istream]: #istream
|
| 10453 |
[istream.assign]: #istream.assign
|
| 10454 |
[istream.cons]: #istream.cons
|
| 10455 |
[istream.extractors]: #istream.extractors
|
| 10456 |
[istream.formatted]: #istream.formatted
|
| 10457 |
[istream.formatted.arithmetic]: #istream.formatted.arithmetic
|
| 10458 |
[istream.formatted.reqmts]: #istream.formatted.reqmts
|
| 10459 |
[istream.manip]: #istream.manip
|
| 10460 |
[istream.rvalue]: #istream.rvalue
|
|
|
|
| 10461 |
[istream.syn]: #istream.syn
|
| 10462 |
[istream.unformatted]: #istream.unformatted
|
| 10463 |
-
[istream::sentry]: #istream::sentry
|
| 10464 |
[istringstream]: #istringstream
|
| 10465 |
[istringstream.assign]: #istringstream.assign
|
| 10466 |
[istringstream.cons]: #istringstream.cons
|
| 10467 |
[istringstream.members]: #istringstream.members
|
| 10468 |
[lex.charset]: lex.md#lex.charset
|
| 10469 |
[locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
|
| 10470 |
[locale.num.get]: localization.md#locale.num.get
|
|
|
|
| 10471 |
[narrow.stream.objects]: #narrow.stream.objects
|
| 10472 |
-
[numeric.limits]:
|
| 10473 |
[ofstream]: #ofstream
|
| 10474 |
[ofstream.assign]: #ofstream.assign
|
| 10475 |
[ofstream.cons]: #ofstream.cons
|
| 10476 |
[ofstream.members]: #ofstream.members
|
| 10477 |
[ostream]: #ostream
|
|
@@ -10483,13 +11308,13 @@ ISO C 7.8.
|
|
| 10483 |
[ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
|
| 10484 |
[ostream.inserters.character]: #ostream.inserters.character
|
| 10485 |
[ostream.manip]: #ostream.manip
|
| 10486 |
[ostream.rvalue]: #ostream.rvalue
|
| 10487 |
[ostream.seeks]: #ostream.seeks
|
|
|
|
| 10488 |
[ostream.syn]: #ostream.syn
|
| 10489 |
[ostream.unformatted]: #ostream.unformatted
|
| 10490 |
-
[ostream::sentry]: #ostream::sentry
|
| 10491 |
[ostringstream]: #ostringstream
|
| 10492 |
[ostringstream.assign]: #ostringstream.assign
|
| 10493 |
[ostringstream.cons]: #ostringstream.cons
|
| 10494 |
[ostringstream.members]: #ostringstream.members
|
| 10495 |
[output.streams]: #output.streams
|
|
@@ -10525,60 +11350,49 @@ ISO C 7.8.
|
|
| 10525 |
[string.streams]: #string.streams
|
| 10526 |
[stringbuf]: #stringbuf
|
| 10527 |
[stringbuf.assign]: #stringbuf.assign
|
| 10528 |
[stringbuf.cons]: #stringbuf.cons
|
| 10529 |
[stringbuf.members]: #stringbuf.members
|
|
|
|
|
|
|
| 10530 |
[stringbuf.virtuals]: #stringbuf.virtuals
|
| 10531 |
[strings]: strings.md#strings
|
| 10532 |
[stringstream]: #stringstream
|
| 10533 |
[stringstream.assign]: #stringstream.assign
|
| 10534 |
[stringstream.cons]: #stringstream.cons
|
| 10535 |
[stringstream.members]: #stringstream.members
|
| 10536 |
-
[
|
| 10537 |
-
[
|
| 10538 |
-
[
|
| 10539 |
-
[
|
| 10540 |
-
[
|
| 10541 |
-
[
|
| 10542 |
-
[
|
| 10543 |
-
[
|
| 10544 |
-
[
|
| 10545 |
-
[
|
| 10546 |
-
[
|
| 10547 |
-
[
|
| 10548 |
-
[
|
| 10549 |
-
[tab:iostreams.fmtflags.effects]: #tab:iostreams.fmtflags.effects
|
| 10550 |
-
[tab:iostreams.iostate.effects]: #tab:iostreams.iostate.effects
|
| 10551 |
-
[tab:iostreams.lib.summary]: #tab:iostreams.lib.summary
|
| 10552 |
-
[tab:iostreams.newoff.values]: #tab:iostreams.newoff.values
|
| 10553 |
-
[tab:iostreams.openmode.effects]: #tab:iostreams.openmode.effects
|
| 10554 |
-
[tab:iostreams.position.requirements]: #tab:iostreams.position.requirements
|
| 10555 |
-
[tab:iostreams.seekdir.effects]: #tab:iostreams.seekdir.effects
|
| 10556 |
-
[tab:iostreams.seekoff.effects]: #tab:iostreams.seekoff.effects
|
| 10557 |
-
[tab:iostreams.seekoff.positioning]: #tab:iostreams.seekoff.positioning
|
| 10558 |
[temp.deduct]: temp.md#temp.deduct
|
| 10559 |
-
[time.clock.req]: utilities.md#time.clock.req
|
| 10560 |
[wide.stream.objects]: #wide.stream.objects
|
| 10561 |
|
| 10562 |
[^1]: It is the implementation’s responsibility to implement headers so
|
| 10563 |
that including `<iosfwd>` and other headers does not violate the
|
| 10564 |
rules about multiple occurrences of default arguments.
|
| 10565 |
|
| 10566 |
-
[^2]: If it is possible for them to do so, implementations
|
| 10567 |
-
|
| 10568 |
|
| 10569 |
-
[^3]: Constructors and destructors for
|
| 10570 |
-
objects to read input from `stdin` or
|
| 10571 |
-
`stderr`.
|
| 10572 |
|
| 10573 |
[^4]: Typically `long long`.
|
| 10574 |
|
| 10575 |
[^5]: `streamsize` is used in most places where ISO C would use
|
| 10576 |
-
`size_t`.
|
| 10577 |
-
except for the `strstreambuf` constructors, which require negative
|
| 10578 |
-
values. It should probably be the signed type corresponding to
|
| 10579 |
-
`size_t` (which is what Posix.2 calls `ssize_t`).
|
| 10580 |
|
| 10581 |
[^6]: This implies that operations on a standard iostream object can be
|
| 10582 |
mixed arbitrarily with operations on the corresponding stdio stream.
|
| 10583 |
In practical terms, synchronization usually means that a standard
|
| 10584 |
iostream object and a standard stdio object share a buffer.
|
|
@@ -10586,13 +11400,13 @@ ISO C 7.8.
|
|
| 10586 |
[^7]: An implementation is free to implement both the integer array
|
| 10587 |
pointed at by `iarray` and the pointer array pointed at by `parray`
|
| 10588 |
as sparse data structures, possibly with a one-element cache for
|
| 10589 |
each.
|
| 10590 |
|
| 10591 |
-
[^8]:
|
| 10592 |
|
| 10593 |
-
[^9]:
|
| 10594 |
|
| 10595 |
[^10]: This suggests an infinite amount of copying, but the
|
| 10596 |
implementation can keep track of the maximum element of the arrays
|
| 10597 |
that is nonzero.
|
| 10598 |
|
|
@@ -10628,22 +11442,22 @@ ISO C 7.8.
|
|
| 10628 |
|
| 10629 |
[^18]: This will be possible only in functions that are part of the
|
| 10630 |
library. The semantics of the constructor used in user code is as
|
| 10631 |
specified.
|
| 10632 |
|
| 10633 |
-
[^19]: The sentry constructor and destructor can also perform
|
| 10634 |
-
implementation-dependent operations.
|
| 10635 |
|
| 10636 |
-
[^20]: This is done without causing an `
|
| 10637 |
|
| 10638 |
[^21]: See, for example, the function signature
|
| 10639 |
-
`ws(basic_istream&)`
|
| 10640 |
|
| 10641 |
[^22]: See, for example, the function signature
|
| 10642 |
-
`dec(ios_base&)`
|
| 10643 |
|
| 10644 |
-
[^23]: This is done without causing an `
|
| 10645 |
|
| 10646 |
[^24]: Note that this function is not overloaded on types `signed char`
|
| 10647 |
and `unsigned char`.
|
| 10648 |
|
| 10649 |
[^25]: Note that this function is not overloaded on types `signed char`
|
|
@@ -10669,19 +11483,19 @@ ISO C 7.8.
|
|
| 10669 |
function can determine that no synchronization is necessary.
|
| 10670 |
|
| 10671 |
[^32]: The `sentry` constructor and destructor can also perform
|
| 10672 |
additional implementation-dependent operations.
|
| 10673 |
|
| 10674 |
-
[^33]: without causing an `
|
| 10675 |
|
| 10676 |
[^34]: See, for example, the function signature
|
| 10677 |
-
`endl(basic_ostream&)`
|
| 10678 |
|
| 10679 |
[^35]: See, for example, the function signature
|
| 10680 |
-
`dec(ios_base&)`
|
| 10681 |
|
| 10682 |
-
[^36]: without causing an `
|
| 10683 |
|
| 10684 |
[^37]: Note that this function is not overloaded on types `signed char`
|
| 10685 |
and `unsigned char`.
|
| 10686 |
|
| 10687 |
[^38]: Note that this function is not overloaded on types `signed char`
|
|
@@ -10696,11 +11510,11 @@ ISO C 7.8.
|
|
| 10696 |
`basic_ostream<charT, traits>` object `cout` (the same as
|
| 10697 |
`cout << noshowbase`).
|
| 10698 |
|
| 10699 |
[^40]: The macro `SEEK_END` is defined, and the function signatures
|
| 10700 |
`fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
|
| 10701 |
-
declared, in `<cstdio>`
|
| 10702 |
|
| 10703 |
[^41]: POSIX® is a registered trademark of The IEEE. Windows® is a
|
| 10704 |
registered trademark of Microsoft Corporation. This information is
|
| 10705 |
given for the convenience of users of this document and does not
|
| 10706 |
constitute an endorsement by ISO or IEC of these products.
|
|
|
|
| 7 |
|
| 8 |
The following subclauses describe requirements for stream parameters,
|
| 9 |
and components for forward declarations of iostreams, predefined
|
| 10 |
iostreams objects, base iostreams classes, stream buffering, stream
|
| 11 |
formatting and manipulators, string streams, and file streams, as
|
| 12 |
+
summarized in [[iostreams.summary]].
|
| 13 |
|
| 14 |
+
**Table: Input/output library summary** <a id="iostreams.summary">[iostreams.summary]</a>
|
| 15 |
|
| 16 |
| Subclause | | Header |
|
| 17 |
+
| -------------------------- | --------------------------- | ------------------------------------- |
|
| 18 |
| [[iostreams.requirements]] | Requirements | |
|
| 19 |
| [[iostream.forward]] | Forward declarations | `<iosfwd>` |
|
| 20 |
| [[iostream.objects]] | Standard iostream objects | `<iostream>` |
|
| 21 |
| [[iostreams.base]] | Iostreams base classes | `<ios>` |
|
| 22 |
| [[stream.buffers]] | Stream buffers | `<streambuf>` |
|
| 23 |
+
| [[iostream.format]] | Formatting and manipulators | `<iomanip>`, `<istream>`, `<ostream>` |
|
|
|
|
|
|
|
| 24 |
| [[string.streams]] | String streams | `<sstream>` |
|
| 25 |
| [[file.streams]] | File streams | `<fstream>` |
|
| 26 |
+
| [[syncstream]] | Synchronized output streams | `<syncstream>` |
|
| 27 |
| [[filesystems]] | File systems | `<filesystem>` |
|
| 28 |
+
| [[c.files]] | C library files | `<cstdio>`, `<cinttypes>` |
|
|
|
|
| 29 |
|
| 30 |
|
| 31 |
+
[*Note 1*: Figure [[fig:iostreams.streampos]] illustrates
|
| 32 |
+
relationships among various types described in this clause. A line from
|
| 33 |
+
**A** to **B** indicates that **A** is an alias (e.g., a typedef) for
|
| 34 |
+
**B** or that **A** is defined in terms of **B**.
|
| 35 |
|
| 36 |
+
<a id="fig:iostreams.streampos"></a>
|
| 37 |
|
| 38 |
+
![Stream position, offset, and size types \[fig:iostreams.streampos\]](images/figstreampos.svg)
|
| 39 |
+
|
| 40 |
+
— *end note*]
|
| 41 |
|
| 42 |
## Iostreams requirements <a id="iostreams.requirements">[[iostreams.requirements]]</a>
|
| 43 |
|
| 44 |
### Imbue limitations <a id="iostream.limits.imbue">[[iostream.limits.imbue]]</a>
|
| 45 |
|
| 46 |
+
No function described in [[input.output]] except for `ios_base::imbue`
|
| 47 |
+
and `basic_filebuf::pubimbue` causes any instance of `basic_ios::imbue`
|
| 48 |
+
or `basic_streambuf::imbue` to be called. If any user function called
|
| 49 |
+
from a function declared in [[input.output]] or as an overriding virtual
|
| 50 |
+
function of any class declared in [[input.output]] calls `imbue`, the
|
| 51 |
+
behavior is undefined.
|
| 52 |
|
| 53 |
### Positioning type limitations <a id="iostreams.limits.pos">[[iostreams.limits.pos]]</a>
|
| 54 |
|
| 55 |
+
The classes of [[input.output]] with template arguments `charT` and
|
| 56 |
+
`traits` behave as described if `traits::pos_type` and
|
| 57 |
`traits::off_type` are `streampos` and `streamoff` respectively. Except
|
| 58 |
as noted explicitly below, their behavior when `traits::pos_type` and
|
| 59 |
`traits::off_type` are other types is *implementation-defined*.
|
| 60 |
|
| 61 |
+
In the classes of [[input.output]], a template parameter with name
|
| 62 |
+
`charT` represents a member of the set of types containing `char`,
|
| 63 |
`wchar_t`, and any other *implementation-defined* character types that
|
| 64 |
+
meet the requirements for a character on which any of the iostream
|
| 65 |
components can be instantiated.
|
| 66 |
|
| 67 |
### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
|
| 68 |
|
| 69 |
+
Concurrent access to a stream object ([[string.streams]],
|
| 70 |
+
[[file.streams]]), stream buffer object [[stream.buffers]], or C Library
|
| 71 |
+
stream [[c.files]] by multiple threads may result in a data race
|
| 72 |
+
[[intro.multithread]] unless otherwise specified [[iostream.objects]].
|
|
|
|
| 73 |
|
| 74 |
+
[*Note 1*: Data races result in undefined behavior
|
| 75 |
+
[[intro.multithread]]. — *end note*]
|
| 76 |
|
| 77 |
If one thread makes a library call *a* that writes a value to a stream
|
| 78 |
and, as a result, another thread reads this value from the stream
|
| 79 |
through a library call *b* such that this does not result in a data
|
| 80 |
race, then *a*’s write synchronizes with *b*’s read.
|
|
|
|
| 83 |
|
| 84 |
### Header `<iosfwd>` synopsis <a id="iosfwd.syn">[[iosfwd.syn]]</a>
|
| 85 |
|
| 86 |
``` cpp
|
| 87 |
namespace std {
|
| 88 |
+
template<class charT> struct char_traits;
|
| 89 |
+
template<> struct char_traits<char>;
|
| 90 |
+
template<> struct char_traits<char8_t>;
|
| 91 |
+
template<> struct char_traits<char16_t>;
|
| 92 |
+
template<> struct char_traits<char32_t>;
|
| 93 |
+
template<> struct char_traits<wchar_t>;
|
| 94 |
|
| 95 |
template<class T> class allocator;
|
| 96 |
|
| 97 |
template<class charT, class traits = char_traits<charT>>
|
| 98 |
class basic_ios;
|
|
|
|
| 125 |
template<class charT, class traits = char_traits<charT>>
|
| 126 |
class basic_ofstream;
|
| 127 |
template<class charT, class traits = char_traits<charT>>
|
| 128 |
class basic_fstream;
|
| 129 |
|
| 130 |
+
template<class charT, class traits = char_traits<charT>,
|
| 131 |
+
class Allocator = allocator<charT>>
|
| 132 |
+
class basic_syncbuf;
|
| 133 |
+
template<class charT, class traits = char_traits<charT>,
|
| 134 |
+
class Allocator = allocator<charT>>
|
| 135 |
+
class basic_osyncstream;
|
| 136 |
+
|
| 137 |
template<class charT, class traits = char_traits<charT>>
|
| 138 |
class istreambuf_iterator;
|
| 139 |
template<class charT, class traits = char_traits<charT>>
|
| 140 |
class ostreambuf_iterator;
|
| 141 |
|
|
|
|
| 155 |
using filebuf = basic_filebuf<char>;
|
| 156 |
using ifstream = basic_ifstream<char>;
|
| 157 |
using ofstream = basic_ofstream<char>;
|
| 158 |
using fstream = basic_fstream<char>;
|
| 159 |
|
| 160 |
+
using syncbuf = basic_syncbuf<char>;
|
| 161 |
+
using osyncstream = basic_osyncstream<char>;
|
| 162 |
+
|
| 163 |
using wstreambuf = basic_streambuf<wchar_t>;
|
| 164 |
using wistream = basic_istream<wchar_t>;
|
| 165 |
using wostream = basic_ostream<wchar_t>;
|
| 166 |
using wiostream = basic_iostream<wchar_t>;
|
| 167 |
|
|
|
|
| 173 |
using wfilebuf = basic_filebuf<wchar_t>;
|
| 174 |
using wifstream = basic_ifstream<wchar_t>;
|
| 175 |
using wofstream = basic_ofstream<wchar_t>;
|
| 176 |
using wfstream = basic_fstream<wchar_t>;
|
| 177 |
|
| 178 |
+
using wsyncbuf = basic_syncbuf<wchar_t>;
|
| 179 |
+
using wosyncstream = basic_osyncstream<wchar_t>;
|
| 180 |
+
|
| 181 |
template<class state> class fpos;
|
| 182 |
using streampos = fpos<char_traits<char>::state_type>;
|
| 183 |
using wstreampos = fpos<char_traits<wchar_t>::state_type>;
|
| 184 |
+
using u8streampos = fpos<char_traits<char8_t>::state_type>;
|
| 185 |
+
using u16streampos = fpos<char_traits<char16_t>::state_type>;
|
| 186 |
+
using u32streampos = fpos<char_traits<char32_t>::state_type>;
|
| 187 |
}
|
| 188 |
```
|
| 189 |
|
| 190 |
Default template arguments are described as appearing both in `<iosfwd>`
|
| 191 |
and in the synopsis of other headers but it is well-formed to include
|
|
|
|
| 198 |
`basic_ostream`, and class templates derived from them. `basic_iostream`
|
| 199 |
is a class template derived from both `basic_istream<charT, traits>` and
|
| 200 |
`basic_ostream<charT, traits>`.
|
| 201 |
|
| 202 |
The class template specialization `basic_streambuf<charT, traits>`
|
| 203 |
+
serves as a base class for class templates `basic_stringbuf`,
|
| 204 |
+
`basic_filebuf`, and `basic_syncbuf`.
|
| 205 |
|
| 206 |
The class template specialization `basic_istream<charT, traits>` serves
|
| 207 |
as a base class for class templates `basic_istringstream` and
|
| 208 |
`basic_ifstream`.
|
| 209 |
|
| 210 |
The class template specialization `basic_ostream<charT, traits>` serves
|
| 211 |
+
as a base class for class templates `basic_ostringstream`,
|
| 212 |
+
`basic_ofstream`, and `basic_osyncstream`.
|
| 213 |
|
| 214 |
The class template specialization `basic_iostream<charT, traits>` serves
|
| 215 |
as a base class for class templates `basic_stringstream` and
|
| 216 |
`basic_fstream`.
|
| 217 |
|
| 218 |
+
[*Note 1*: For each of the class templates above, the program is
|
| 219 |
+
ill-formed if `traits::char_type` is not the same type as `charT`
|
| 220 |
+
[[char.traits]]. — *end note*]
|
| 221 |
+
|
| 222 |
Other *typedef-name*s define instances of class templates specialized
|
| 223 |
for `char` or `wchar_t` types.
|
| 224 |
|
| 225 |
Specializations of the class template `fpos` are used for specifying
|
| 226 |
file position information.
|
| 227 |
|
| 228 |
+
[*Example 1*: The types `streampos` and `wstreampos` are used for
|
| 229 |
+
positioning streams specialized on `char` and `wchar_t`
|
| 230 |
+
respectively. — *end example*]
|
| 231 |
|
| 232 |
+
[*Note 2*: This synopsis suggests a circularity between `streampos` and
|
|
|
|
|
|
|
| 233 |
`char_traits<char>`. An implementation can avoid this circularity by
|
| 234 |
+
substituting equivalent types. — *end note*]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 235 |
|
| 236 |
## Standard iostream objects <a id="iostream.objects">[[iostream.objects]]</a>
|
| 237 |
|
| 238 |
### Header `<iostream>` synopsis <a id="iostream.syn">[[iostream.syn]]</a>
|
| 239 |
|
|
|
|
| 257 |
```
|
| 258 |
|
| 259 |
### Overview <a id="iostream.objects.overview">[[iostream.objects.overview]]</a>
|
| 260 |
|
| 261 |
In this Clause, the type name `FILE` refers to the type `FILE` declared
|
| 262 |
+
in `<cstdio>`.
|
| 263 |
|
| 264 |
The header `<iostream>` declares objects that associate objects with the
|
| 265 |
+
standard C streams provided for by the functions declared in `<cstdio>`,
|
| 266 |
+
and includes all the headers necessary to use these objects.
|
|
|
|
| 267 |
|
| 268 |
The objects are constructed and the associations are established at some
|
| 269 |
time prior to or during the first time an object of class
|
| 270 |
`ios_base::Init` is constructed, and in any case before the body of
|
| 271 |
+
`main` [[basic.start.main]] begins execution.[^2] The objects are not
|
| 272 |
destroyed during program execution.[^3] The results of including
|
| 273 |
`<iostream>` in a translation unit shall be as if `<iostream>` defined
|
| 274 |
an instance of `ios_base::Init` with static storage duration.
|
| 275 |
|
| 276 |
Mixing operations on corresponding wide- and narrow-character streams
|
| 277 |
follows the same semantics as mixing such operations on `FILE`s, as
|
| 278 |
specified in the C standard library.
|
| 279 |
|
| 280 |
+
Concurrent access to a synchronized [[ios.members.static]] standard
|
| 281 |
+
iostream object’s formatted and unformatted input [[istream]] and output
|
| 282 |
+
[[ostream]] functions or a standard C stream by multiple threads does
|
| 283 |
+
not result in a data race [[intro.multithread]].
|
| 284 |
|
| 285 |
[*Note 1*: Users must still synchronize concurrent use of these objects
|
| 286 |
and streams by multiple threads if they wish to avoid interleaved
|
| 287 |
characters. — *end note*]
|
| 288 |
|
| 289 |
+
See also: ISO C 7.21.2
|
| 290 |
|
| 291 |
### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
|
| 292 |
|
| 293 |
``` cpp
|
| 294 |
istream cin;
|
| 295 |
```
|
| 296 |
|
| 297 |
The object `cin` controls input from a stream buffer associated with the
|
| 298 |
+
object `stdin`, declared in `<cstdio>`.
|
| 299 |
|
| 300 |
After the object `cin` is initialized, `cin.tie()` returns `&cout`. Its
|
| 301 |
+
state is otherwise the same as required for `basic_ios<char>::init`
|
| 302 |
+
[[basic.ios.cons]].
|
| 303 |
|
| 304 |
``` cpp
|
| 305 |
ostream cout;
|
| 306 |
```
|
| 307 |
|
| 308 |
The object `cout` controls output to a stream buffer associated with the
|
| 309 |
+
object `stdout`, declared in `<cstdio>`.
|
| 310 |
|
| 311 |
``` cpp
|
| 312 |
ostream cerr;
|
| 313 |
```
|
| 314 |
|
| 315 |
The object `cerr` controls output to a stream buffer associated with the
|
| 316 |
+
object `stderr`, declared in `<cstdio>`.
|
| 317 |
|
| 318 |
After the object `cerr` is initialized, `cerr.flags() & unitbuf` is
|
| 319 |
nonzero and `cerr.tie()` returns `&cout`. Its state is otherwise the
|
| 320 |
+
same as required for `basic_ios<char>::init` [[basic.ios.cons]].
|
| 321 |
|
| 322 |
``` cpp
|
| 323 |
ostream clog;
|
| 324 |
```
|
| 325 |
|
| 326 |
The object `clog` controls output to a stream buffer associated with the
|
| 327 |
+
object `stderr`, declared in `<cstdio>`.
|
| 328 |
|
| 329 |
### Wide stream objects <a id="wide.stream.objects">[[wide.stream.objects]]</a>
|
| 330 |
|
| 331 |
``` cpp
|
| 332 |
wistream wcin;
|
| 333 |
```
|
| 334 |
|
| 335 |
The object `wcin` controls input from a stream buffer associated with
|
| 336 |
+
the object `stdin`, declared in `<cstdio>`.
|
| 337 |
|
| 338 |
After the object `wcin` is initialized, `wcin.tie()` returns `&wcout`.
|
| 339 |
Its state is otherwise the same as required for
|
| 340 |
+
`basic_ios<wchar_t>::init` [[basic.ios.cons]].
|
| 341 |
|
| 342 |
``` cpp
|
| 343 |
wostream wcout;
|
| 344 |
```
|
| 345 |
|
| 346 |
The object `wcout` controls output to a stream buffer associated with
|
| 347 |
+
the object `stdout`, declared in `<cstdio>`.
|
| 348 |
|
| 349 |
``` cpp
|
| 350 |
wostream wcerr;
|
| 351 |
```
|
| 352 |
|
| 353 |
The object `wcerr` controls output to a stream buffer associated with
|
| 354 |
+
the object `stderr`, declared in `<cstdio>`.
|
| 355 |
|
| 356 |
After the object `wcerr` is initialized, `wcerr.flags() & unitbuf` is
|
| 357 |
nonzero and `wcerr.tie()` returns `&wcout`. Its state is otherwise the
|
| 358 |
+
same as required for `basic_ios<wchar_t>::init` [[basic.ios.cons]].
|
| 359 |
|
| 360 |
``` cpp
|
| 361 |
wostream wclog;
|
| 362 |
```
|
| 363 |
|
| 364 |
The object `wclog` controls output to a stream buffer associated with
|
| 365 |
+
the object `stderr`, declared in `<cstdio>`.
|
| 366 |
|
| 367 |
## Iostreams base classes <a id="iostreams.base">[[iostreams.base]]</a>
|
| 368 |
|
| 369 |
### Header `<ios>` synopsis <a id="ios.syn">[[ios.syn]]</a>
|
| 370 |
|
|
|
|
| 454 |
namespace std {
|
| 455 |
class ios_base {
|
| 456 |
public:
|
| 457 |
class failure; // see below
|
| 458 |
|
| 459 |
+
// [ios.fmtflags], fmtflags
|
| 460 |
using fmtflags = T1;
|
| 461 |
static constexpr fmtflags boolalpha = unspecified;
|
| 462 |
static constexpr fmtflags dec = unspecified;
|
| 463 |
static constexpr fmtflags fixed = unspecified;
|
| 464 |
static constexpr fmtflags hex = unspecified;
|
|
|
|
| 475 |
static constexpr fmtflags uppercase = unspecified;
|
| 476 |
static constexpr fmtflags adjustfield = see below;
|
| 477 |
static constexpr fmtflags basefield = see below;
|
| 478 |
static constexpr fmtflags floatfield = see below;
|
| 479 |
|
| 480 |
+
// [ios.iostate], iostate
|
| 481 |
using iostate = T2;
|
| 482 |
static constexpr iostate badbit = unspecified;
|
| 483 |
static constexpr iostate eofbit = unspecified;
|
| 484 |
static constexpr iostate failbit = unspecified;
|
| 485 |
static constexpr iostate goodbit = see below;
|
| 486 |
|
| 487 |
+
// [ios.openmode], openmode
|
| 488 |
using openmode = T3;
|
| 489 |
static constexpr openmode app = unspecified;
|
| 490 |
static constexpr openmode ate = unspecified;
|
| 491 |
static constexpr openmode binary = unspecified;
|
| 492 |
static constexpr openmode in = unspecified;
|
| 493 |
static constexpr openmode out = unspecified;
|
| 494 |
static constexpr openmode trunc = unspecified;
|
| 495 |
|
| 496 |
+
// [ios.seekdir], seekdir
|
| 497 |
using seekdir = T4;
|
| 498 |
static constexpr seekdir beg = unspecified;
|
| 499 |
static constexpr seekdir cur = unspecified;
|
| 500 |
static constexpr seekdir end = unspecified;
|
| 501 |
|
|
|
|
| 517 |
locale imbue(const locale& loc);
|
| 518 |
locale getloc() const;
|
| 519 |
|
| 520 |
// [ios.base.storage], storage
|
| 521 |
static int xalloc();
|
| 522 |
+
long& iword(int idx);
|
| 523 |
+
void*& pword(int idx);
|
| 524 |
|
| 525 |
+
// destructor
|
| 526 |
virtual ~ios_base();
|
| 527 |
|
| 528 |
+
// [ios.base.callback], callbacks
|
| 529 |
enum event { erase_event, imbue_event, copyfmt_event };
|
| 530 |
+
using event_callback = void (*)(event, ios_base&, int idx);
|
| 531 |
+
void register_callback(event_callback fn, int idx);
|
| 532 |
|
| 533 |
ios_base(const ios_base&) = delete;
|
| 534 |
ios_base& operator=(const ios_base&) = delete;
|
| 535 |
|
| 536 |
static bool sync_with_stdio(bool sync = true);
|
|
|
|
| 578 |
|
| 579 |
— *end note*]
|
| 580 |
|
| 581 |
#### Types <a id="ios.types">[[ios.types]]</a>
|
| 582 |
|
| 583 |
+
##### Class `ios_base::failure` <a id="ios.failure">[[ios.failure]]</a>
|
| 584 |
|
| 585 |
``` cpp
|
| 586 |
namespace std {
|
| 587 |
class ios_base::failure : public system_error {
|
| 588 |
public:
|
|
|
|
| 594 |
|
| 595 |
An implementation is permitted to define `ios_base::failure` as a
|
| 596 |
synonym for a class with equivalent functionality to class
|
| 597 |
`ios_base::failure` shown in this subclause.
|
| 598 |
|
| 599 |
+
[*Note 1*: When `ios_base::failure` is a synonym for another type, that
|
| 600 |
+
type is required to provide a nested type `failure` to emulate the
|
| 601 |
+
injected-class-name. — *end note*]
|
| 602 |
|
| 603 |
The class `failure` defines the base class for the types of all objects
|
| 604 |
thrown as exceptions, by functions in the iostreams library, to report
|
| 605 |
errors detected during stream buffer operations.
|
| 606 |
|
|
|
|
| 617 |
|
| 618 |
``` cpp
|
| 619 |
explicit failure(const string& msg, const error_code& ec = io_errc::stream);
|
| 620 |
```
|
| 621 |
|
| 622 |
+
*Effects:* Constructs the base class with `msg` and `ec`.
|
|
|
|
| 623 |
|
| 624 |
``` cpp
|
| 625 |
explicit failure(const char* msg, const error_code& ec = io_errc::stream);
|
| 626 |
```
|
| 627 |
|
| 628 |
+
*Effects:* Constructs the base class with `msg` and `ec`.
|
|
|
|
| 629 |
|
| 630 |
+
##### Type `ios_base::fmtflags` <a id="ios.fmtflags">[[ios.fmtflags]]</a>
|
| 631 |
|
| 632 |
``` cpp
|
| 633 |
using fmtflags = T1;
|
| 634 |
```
|
| 635 |
|
| 636 |
+
The type `fmtflags` is a bitmask type [[bitmask.types]]. Setting its
|
| 637 |
+
elements has the effects indicated in [[ios.fmtflags]].
|
|
|
|
| 638 |
|
| 639 |
+
**Table: `fmtflags` effects** <a id="ios.fmtflags">[ios.fmtflags]</a>
|
| 640 |
|
| 641 |
| Element | Effect(s) if set |
|
| 642 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
| 643 |
| `boolalpha` | insert and extract `bool` type in alphabetic format |
|
| 644 |
| `dec` | converts integer input or generates integer output in decimal base |
|
|
|
|
| 656 |
| `unitbuf` | flushes output after each output operation |
|
| 657 |
| `uppercase` | replaces certain lowercase letters with their uppercase equivalents in generated output |
|
| 658 |
|
| 659 |
|
| 660 |
Type `fmtflags` also defines the constants indicated in
|
| 661 |
+
[[ios.fmtflags.const]].
|
| 662 |
|
| 663 |
+
**Table: `fmtflags` constants** <a id="ios.fmtflags.const">[ios.fmtflags.const]</a>
|
| 664 |
|
| 665 |
| Constant | Allowable values |
|
| 666 |
| ------------- | ------------------------- |
|
| 667 |
| `adjustfield` | `left | right | internal` |
|
| 668 |
| `basefield` | `dec | oct | hex` |
|
| 669 |
| `floatfield` | `scientific | fixed` |
|
| 670 |
|
| 671 |
|
| 672 |
+
##### Type `ios_base::iostate` <a id="ios.iostate">[[ios.iostate]]</a>
|
| 673 |
|
| 674 |
``` cpp
|
| 675 |
using iostate = T2;
|
| 676 |
```
|
| 677 |
|
| 678 |
+
The type `iostate` is a bitmask type [[bitmask.types]] that contains the
|
| 679 |
+
elements indicated in [[ios.iostate]].
|
| 680 |
|
| 681 |
+
**Table: `iostate` effects** <a id="ios.iostate">[ios.iostate]</a>
|
| 682 |
|
| 683 |
| Element | Effect(s) if set |
|
| 684 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
| 685 |
| `badbit` | indicates a loss of integrity in an input or output sequence (such as an irrecoverable read error from a file); |
|
| 686 |
| `eofbit` | indicates that an input operation reached the end of an input sequence; |
|
|
|
|
| 689 |
|
| 690 |
Type `iostate` also defines the constant:
|
| 691 |
|
| 692 |
- `goodbit`, the value zero.
|
| 693 |
|
| 694 |
+
##### Type `ios_base::openmode` <a id="ios.openmode">[[ios.openmode]]</a>
|
| 695 |
|
| 696 |
``` cpp
|
| 697 |
using openmode = T3;
|
| 698 |
```
|
| 699 |
|
| 700 |
+
The type `openmode` is a bitmask type [[bitmask.types]]. It contains the
|
| 701 |
+
elements indicated in [[ios.openmode]].
|
| 702 |
|
| 703 |
+
**Table: `openmode` effects** <a id="ios.openmode">[ios.openmode]</a>
|
| 704 |
|
| 705 |
| Element | Effect(s) if set |
|
| 706 |
| -------- | ----------------------------------------------------------------- |
|
| 707 |
| `app` | seek to end before each write |
|
| 708 |
| `ate` | open and seek to end immediately after opening |
|
|
|
|
| 710 |
| `in` | open for input |
|
| 711 |
| `out` | open for output |
|
| 712 |
| `trunc` | truncate an existing stream when opening |
|
| 713 |
|
| 714 |
|
| 715 |
+
##### Type `ios_base::seekdir` <a id="ios.seekdir">[[ios.seekdir]]</a>
|
| 716 |
|
| 717 |
``` cpp
|
| 718 |
using seekdir = T4;
|
| 719 |
```
|
| 720 |
|
| 721 |
+
The type `seekdir` is an enumerated type [[enumerated.types]] that
|
| 722 |
+
contains the elements indicated in [[ios.seekdir]].
|
|
|
|
| 723 |
|
| 724 |
+
**Table: `seekdir` effects** <a id="ios.seekdir">[ios.seekdir]</a>
|
| 725 |
|
| 726 |
| Element | Meaning |
|
| 727 |
| ------- | --------------------------------------------------------------------------------------- |
|
| 728 |
| `beg` | request a seek (for subsequent input or output) relative to the beginning of the stream |
|
| 729 |
| `cur` | request a seek relative to the current position within the sequence |
|
| 730 |
| `end` | request a seek relative to the current end of the sequence |
|
| 731 |
|
| 732 |
|
| 733 |
+
##### Class `ios_base::Init` <a id="ios.init">[[ios.init]]</a>
|
| 734 |
|
| 735 |
``` cpp
|
| 736 |
namespace std {
|
| 737 |
class ios_base::Init {
|
| 738 |
public:
|
| 739 |
Init();
|
| 740 |
+
Init(const Init&) = default;
|
| 741 |
~Init();
|
| 742 |
+
Init& operator=(const Init&) = default;
|
| 743 |
private:
|
| 744 |
static int init_cnt; // exposition only
|
| 745 |
};
|
| 746 |
}
|
| 747 |
```
|
| 748 |
|
| 749 |
The class `Init` describes an object whose construction ensures the
|
| 750 |
+
construction of the eight objects declared in `<iostream>`
|
| 751 |
+
[[iostream.objects]] that associate file stream buffers with the
|
| 752 |
+
standard C streams provided for by the functions declared in `<cstdio>`.
|
|
|
|
| 753 |
|
| 754 |
For the sake of exposition, the maintained data is presented here as:
|
| 755 |
|
| 756 |
- `static int init_cnt`, counts the number of constructor and destructor
|
| 757 |
calls for class `Init`, initialized to zero.
|
| 758 |
|
| 759 |
``` cpp
|
| 760 |
Init();
|
| 761 |
```
|
| 762 |
|
| 763 |
+
*Effects:* Constructs and initializes the objects `cin`, `cout`, `cerr`,
|
| 764 |
+
`clog`, `wcin`, `wcout`, `wcerr`, and `wclog` if they have not already
|
| 765 |
+
been constructed and initialized.
|
|
|
|
| 766 |
|
| 767 |
``` cpp
|
| 768 |
~Init();
|
| 769 |
```
|
| 770 |
|
| 771 |
+
*Effects:* If there are no other instances of the class still in
|
| 772 |
+
existence, calls `cout.flush()`, `cerr.flush()`, `clog.flush()`,
|
| 773 |
+
`wcout.flush()`, `wcerr.flush()`, `wclog.flush()`.
|
|
|
|
| 774 |
|
| 775 |
+
#### State functions <a id="fmtflags.state">[[fmtflags.state]]</a>
|
| 776 |
|
| 777 |
``` cpp
|
| 778 |
fmtflags flags() const;
|
| 779 |
```
|
| 780 |
|
|
|
|
| 782 |
|
| 783 |
``` cpp
|
| 784 |
fmtflags flags(fmtflags fmtfl);
|
| 785 |
```
|
| 786 |
|
| 787 |
+
*Ensures:* `fmtfl == flags()`.
|
| 788 |
|
| 789 |
*Returns:* The previous value of `flags()`.
|
| 790 |
|
| 791 |
``` cpp
|
| 792 |
fmtflags setf(fmtflags fmtfl);
|
|
|
|
| 818 |
|
| 819 |
``` cpp
|
| 820 |
streamsize precision(streamsize prec);
|
| 821 |
```
|
| 822 |
|
| 823 |
+
*Ensures:* `prec == precision()`.
|
| 824 |
|
| 825 |
*Returns:* The previous value of `precision()`.
|
| 826 |
|
| 827 |
``` cpp
|
| 828 |
streamsize width() const;
|
|
|
|
| 833 |
|
| 834 |
``` cpp
|
| 835 |
streamsize width(streamsize wide);
|
| 836 |
```
|
| 837 |
|
| 838 |
+
*Ensures:* `wide == width()`.
|
| 839 |
|
| 840 |
*Returns:* The previous value of `width()`.
|
| 841 |
|
| 842 |
+
#### Functions <a id="ios.base.locales">[[ios.base.locales]]</a>
|
| 843 |
|
| 844 |
``` cpp
|
| 845 |
locale imbue(const locale& loc);
|
| 846 |
```
|
| 847 |
|
| 848 |
+
*Effects:* Calls each registered callback pair `(fn, idx)`
|
| 849 |
+
[[ios.base.callback]] as `(*fn)(imbue_event, *this, idx)` at such a time
|
| 850 |
+
that a call to `ios_base::getloc()` from within `fn` returns the new
|
| 851 |
+
locale value `loc`.
|
| 852 |
+
|
| 853 |
+
*Ensures:* `loc == getloc()`.
|
| 854 |
|
| 855 |
*Returns:* The previous value of `getloc()`.
|
| 856 |
|
|
|
|
|
|
|
| 857 |
``` cpp
|
| 858 |
locale getloc() const;
|
| 859 |
```
|
| 860 |
|
| 861 |
+
*Returns:* If no locale has been imbued, a copy of the global C++
|
| 862 |
+
locale, `locale()`, in effect at the time of construction. Otherwise,
|
| 863 |
+
returns the imbued locale, to be used to perform locale-dependent input
|
| 864 |
+
and output operations.
|
| 865 |
|
| 866 |
+
#### Static members <a id="ios.members.static">[[ios.members.static]]</a>
|
| 867 |
|
| 868 |
``` cpp
|
| 869 |
+
static bool sync_with_stdio(bool sync = true);
|
| 870 |
```
|
| 871 |
|
| 872 |
*Returns:* `true` if the previous state of the standard iostream
|
| 873 |
+
objects [[iostream.objects]] was synchronized and otherwise returns
|
| 874 |
`false`. The first time it is called, the function returns `true`.
|
| 875 |
|
| 876 |
*Effects:* If any input or output operation has occurred using the
|
| 877 |
standard streams prior to the call, the effect is
|
| 878 |
*implementation-defined*. Otherwise, called with a `false` argument, it
|
|
|
|
| 918 |
str.rdbuf()->sputbackc(c);
|
| 919 |
```
|
| 920 |
|
| 921 |
for any sequence of characters.[^6]
|
| 922 |
|
| 923 |
+
#### Storage functions <a id="ios.base.storage">[[ios.base.storage]]</a>
|
| 924 |
|
| 925 |
``` cpp
|
| 926 |
static int xalloc();
|
| 927 |
```
|
| 928 |
|
| 929 |
*Returns:* `index` `++`.
|
| 930 |
|
| 931 |
+
*Remarks:* Concurrent access to this function by multiple threads does
|
| 932 |
+
not result in a data race [[intro.multithread]].
|
| 933 |
|
| 934 |
``` cpp
|
| 935 |
long& iword(int idx);
|
| 936 |
```
|
| 937 |
|
| 938 |
+
*Preconditions:* `idx` is a value obtained by a call to `xalloc`.
|
| 939 |
+
|
| 940 |
*Effects:* If `iarray` is a null pointer, allocates an array of `long`
|
| 941 |
of unspecified size and stores a pointer to its first element in
|
| 942 |
`iarray`. The function then extends the array pointed at by `iarray` as
|
| 943 |
necessary to include the element `iarray[idx]`. Each newly allocated
|
| 944 |
element of the array is initialized to zero. The reference returned is
|
|
|
|
| 955 |
|
| 956 |
``` cpp
|
| 957 |
void*& pword(int idx);
|
| 958 |
```
|
| 959 |
|
| 960 |
+
*Preconditions:* `idx` is a value obtained by a call to `xalloc`.
|
| 961 |
+
|
| 962 |
*Effects:* If `parray` is a null pointer, allocates an array of pointers
|
| 963 |
to `void` of unspecified size and stores a pointer to its first element
|
| 964 |
in `parray`. The function then extends the array pointed at by `parray`
|
| 965 |
as necessary to include the element `parray[idx]`. Each newly allocated
|
| 966 |
element of the array is initialized to a null pointer. The reference
|
|
|
|
| 976 |
initialized to 0.
|
| 977 |
|
| 978 |
*Remarks:* After a subsequent call to `pword(int)` for the same object,
|
| 979 |
the earlier return value may no longer be valid.
|
| 980 |
|
| 981 |
+
#### Callbacks <a id="ios.base.callback">[[ios.base.callback]]</a>
|
| 982 |
|
| 983 |
``` cpp
|
| 984 |
+
void register_callback(event_callback fn, int idx);
|
| 985 |
```
|
| 986 |
|
| 987 |
+
*Preconditions:* The function `fn` does not throw exceptions.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 988 |
|
| 989 |
+
*Effects:* Registers the pair `(fn, idx)` such that during calls to
|
| 990 |
+
`imbue()` [[ios.base.locales]], `copyfmt()`, or `~ios_base()`
|
| 991 |
+
[[ios.base.cons]], the function `fn` is called with argument `idx`.
|
| 992 |
+
Functions registered are called when an event occurs, in opposite order
|
| 993 |
+
of registration. Functions registered while a callback function is
|
| 994 |
+
active are not called until the next event.
|
| 995 |
|
| 996 |
*Remarks:* Identical pairs are not merged. A function registered twice
|
| 997 |
will be called twice.
|
| 998 |
|
| 999 |
+
#### Constructors and destructor <a id="ios.base.cons">[[ios.base.cons]]</a>
|
| 1000 |
|
| 1001 |
``` cpp
|
| 1002 |
ios_base();
|
| 1003 |
```
|
| 1004 |
|
|
|
|
| 1009 |
|
| 1010 |
``` cpp
|
| 1011 |
~ios_base();
|
| 1012 |
```
|
| 1013 |
|
| 1014 |
+
*Effects:* Calls each registered callback pair `(fn, idx)`
|
| 1015 |
+
[[ios.base.callback]] as `(*fn)(erase_event, *this, idx)` at such time
|
| 1016 |
+
that any `ios_base` member function called from within `fn` has
|
| 1017 |
+
well-defined results.
|
| 1018 |
|
| 1019 |
### Class template `fpos` <a id="fpos">[[fpos]]</a>
|
| 1020 |
|
| 1021 |
``` cpp
|
| 1022 |
namespace std {
|
|
|
|
| 1029 |
stateT st; // exposition only
|
| 1030 |
};
|
| 1031 |
}
|
| 1032 |
```
|
| 1033 |
|
| 1034 |
+
#### Members <a id="fpos.members">[[fpos.members]]</a>
|
| 1035 |
|
| 1036 |
``` cpp
|
| 1037 |
void state(stateT s);
|
| 1038 |
```
|
| 1039 |
|
|
|
|
| 1043 |
stateT state() const;
|
| 1044 |
```
|
| 1045 |
|
| 1046 |
*Returns:* Current value of `st`.
|
| 1047 |
|
| 1048 |
+
#### Requirements <a id="fpos.operations">[[fpos.operations]]</a>
|
| 1049 |
|
| 1050 |
+
An `fpos` type specifies file position information. It holds a state
|
| 1051 |
+
object whose type is equal to the template parameter `stateT`. Type
|
| 1052 |
+
`stateT` shall meet the *Cpp17DefaultConstructible* (
|
| 1053 |
+
[[cpp17.defaultconstructible]]), *Cpp17CopyConstructible* (
|
| 1054 |
+
[[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
|
| 1055 |
+
[[cpp17.copyassignable]]), and *Cpp17Destructible* (
|
| 1056 |
+
[[cpp17.destructible]]) requirements. If
|
| 1057 |
+
`is_trivially_copy_constructible_v<stateT>` is `true`, then
|
| 1058 |
+
`fpos<stateT>` has a trivial copy constructor. If
|
| 1059 |
+
`is_trivially_copy_assignable<stateT>` is `true`, then `fpos<stateT>`
|
| 1060 |
+
has a trivial copy assignment operator. If
|
| 1061 |
+
`is_trivially_destructible_v<stateT>` is `true`, then `fpos<stateT>` has
|
| 1062 |
+
a trivial destructor. All specializations of `fpos` meet the
|
| 1063 |
+
*Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
|
| 1064 |
+
*Cpp17CopyAssignable*, *Cpp17Destructible*, and
|
| 1065 |
+
*Cpp17EqualityComparable* ([[cpp17.equalitycomparable]]) requirements.
|
| 1066 |
+
In addition, the expressions shown in [[fpos.operations]] are valid and
|
| 1067 |
+
have the indicated semantics. In that table,
|
| 1068 |
|
| 1069 |
- `P` refers to an instance of `fpos`,
|
| 1070 |
+
- `p` and `q` refer to values of type `P` or `const P`,
|
| 1071 |
+
- `pl` and `ql` refer to modifiable lvalues of type `P`,
|
| 1072 |
+
- `O` refers to type `streamoff`, and
|
| 1073 |
+
- `o` refers to a value of type `streamoff` or `const streamoff`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1074 |
|
| 1075 |
Stream operations that return a value of type `traits::pos_type` return
|
| 1076 |
`P(O(-1))` as an invalid value to signal an error. If this value is used
|
| 1077 |
as an argument to any `istream`, `ostream`, or `streambuf` member that
|
| 1078 |
accepts a value of type `traits::pos_type` then the behavior of that
|
|
|
|
| 1141 |
|
| 1142 |
};
|
| 1143 |
}
|
| 1144 |
```
|
| 1145 |
|
| 1146 |
+
#### Constructors <a id="basic.ios.cons">[[basic.ios.cons]]</a>
|
| 1147 |
|
| 1148 |
``` cpp
|
| 1149 |
explicit basic_ios(basic_streambuf<charT, traits>* sb);
|
| 1150 |
```
|
| 1151 |
|
| 1152 |
+
*Effects:* Assigns initial values to its member objects by calling
|
| 1153 |
+
`init(sb)`.
|
| 1154 |
|
| 1155 |
``` cpp
|
| 1156 |
basic_ios();
|
| 1157 |
```
|
| 1158 |
|
| 1159 |
+
*Effects:* Leaves its member objects uninitialized. The object shall be
|
| 1160 |
+
initialized by calling `basic_ios::init` before its first use or before
|
| 1161 |
+
it is destroyed, whichever comes first; otherwise the behavior is
|
| 1162 |
+
undefined.
|
|
|
|
| 1163 |
|
| 1164 |
``` cpp
|
| 1165 |
~basic_ios();
|
| 1166 |
```
|
| 1167 |
|
|
|
|
| 1169 |
|
| 1170 |
``` cpp
|
| 1171 |
void init(basic_streambuf<charT, traits>* sb);
|
| 1172 |
```
|
| 1173 |
|
| 1174 |
+
*Ensures:* The postconditions of this function are indicated in
|
| 1175 |
+
[[basic.ios.cons]].
|
| 1176 |
|
| 1177 |
+
**Table: `basic_ios::init()` effects** <a id="basic.ios.cons">[basic.ios.cons]</a>
|
| 1178 |
|
| 1179 |
| Element | Value |
|
| 1180 |
| -------------- | ------------------------------------------------------------ |
|
| 1181 |
| `rdbuf()` | `sb` |
|
| 1182 |
| `tie()` | `0` |
|
|
|
|
| 1202 |
|
| 1203 |
``` cpp
|
| 1204 |
basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
|
| 1205 |
```
|
| 1206 |
|
| 1207 |
+
*Preconditions:* If `tiestr` is not null, `tiestr` is not reachable by
|
| 1208 |
traversing the linked list of tied stream objects starting from
|
| 1209 |
`tiestr->tie()`.
|
| 1210 |
|
| 1211 |
+
*Ensures:* `tiestr == tie()`.
|
| 1212 |
|
| 1213 |
*Returns:* The previous value of `tie()`.
|
| 1214 |
|
| 1215 |
``` cpp
|
| 1216 |
basic_streambuf<charT, traits>* rdbuf() const;
|
|
|
|
| 1220 |
|
| 1221 |
``` cpp
|
| 1222 |
basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
|
| 1223 |
```
|
| 1224 |
|
|
|
|
|
|
|
| 1225 |
*Effects:* Calls `clear()`.
|
| 1226 |
|
| 1227 |
+
*Ensures:* `sb == rdbuf()`.
|
| 1228 |
+
|
| 1229 |
*Returns:* The previous value of `rdbuf()`.
|
| 1230 |
|
| 1231 |
``` cpp
|
| 1232 |
locale imbue(const locale& loc);
|
| 1233 |
```
|
| 1234 |
|
| 1235 |
+
*Effects:* Calls `ios_base::imbue(loc)` [[ios.base.locales]] and if
|
| 1236 |
+
`rdbuf() != 0` then `rdbuf()->pubimbue(loc)` [[streambuf.locales]].
|
| 1237 |
|
| 1238 |
*Returns:* The prior value of `ios_base::imbue()`.
|
| 1239 |
|
| 1240 |
``` cpp
|
| 1241 |
char narrow(char_type c, char dfault) const;
|
|
|
|
| 1258 |
|
| 1259 |
``` cpp
|
| 1260 |
char_type fill(char_type fillch);
|
| 1261 |
```
|
| 1262 |
|
| 1263 |
+
*Ensures:* `traits::eq(fillch, fill())`.
|
| 1264 |
|
| 1265 |
*Returns:* The previous value of `fill()`.
|
| 1266 |
|
| 1267 |
``` cpp
|
| 1268 |
basic_ios& copyfmt(const basic_ios& rhs);
|
| 1269 |
```
|
| 1270 |
|
| 1271 |
+
*Effects:* If `(this == addressof(rhs))` is `true` does nothing.
|
| 1272 |
+
Otherwise assigns to the member objects of `*this` the corresponding
|
| 1273 |
+
member objects of `rhs` as follows:
|
| 1274 |
|
| 1275 |
+
- calls each registered callback pair `(fn, idx)` as
|
| 1276 |
+
`(*fn)(erase_event, *this, idx)`;
|
| 1277 |
+
- then, assigns to the member objects of `*this` the corresponding
|
| 1278 |
+
member objects of `rhs`, except that
|
| 1279 |
- `rdstate()`, `rdbuf()`, and `exceptions()` are left unchanged;
|
| 1280 |
+
- the contents of arrays pointed at by `pword` and `iword` are copied,
|
| 1281 |
+
not the pointers themselves;[^10] and
|
| 1282 |
- if any newly stored pointer values in `*this` point at objects
|
| 1283 |
+
stored outside the object `rhs` and those objects are destroyed when
|
| 1284 |
+
`rhs` is destroyed, the newly stored pointer values are altered to
|
| 1285 |
+
point at newly constructed copies of the objects;
|
| 1286 |
+
- then, calls each callback pair that was copied from `rhs` as
|
| 1287 |
+
`(*fn)(copyfmt_event, *this, idx)`;
|
| 1288 |
+
- then, calls `exceptions(rhs.exceptions())`.
|
| 1289 |
|
| 1290 |
[*Note 1*: The second pass through the callback pairs permits a copied
|
| 1291 |
`pword` value to be zeroed, or to have its referent deep copied or
|
| 1292 |
reference counted, or to have other special action taken. — *end note*]
|
| 1293 |
|
| 1294 |
+
*Ensures:* The postconditions of this function are indicated in
|
| 1295 |
+
[[basic.ios.copyfmt]].
|
| 1296 |
|
| 1297 |
+
**Table: `basic_ios::copyfmt()` effects** <a id="basic.ios.copyfmt">[basic.ios.copyfmt]</a>
|
| 1298 |
|
| 1299 |
| Element | Value |
|
| 1300 |
| -------------- | ------------------ |
|
| 1301 |
| `rdbuf()` | unchanged |
|
| 1302 |
| `tie()` | `rhs.tie()` |
|
|
|
|
| 1314 |
``` cpp
|
| 1315 |
void move(basic_ios& rhs);
|
| 1316 |
void move(basic_ios&& rhs);
|
| 1317 |
```
|
| 1318 |
|
| 1319 |
+
*Ensures:* `*this` has the state that `rhs` had before the function
|
| 1320 |
+
call, except that `rdbuf()` returns `nullptr`. `rhs` is in a valid but
|
| 1321 |
+
unspecified state, except that `rhs.rdbuf()` returns the same value as
|
| 1322 |
+
it returned before the function call, and `rhs.tie()` returns `nullptr`.
|
|
|
|
| 1323 |
|
| 1324 |
``` cpp
|
| 1325 |
void swap(basic_ios& rhs) noexcept;
|
| 1326 |
```
|
| 1327 |
|
| 1328 |
+
*Effects:* The states of `*this` and `rhs` are exchanged, except that
|
| 1329 |
+
`rdbuf()` returns the same value as it returned before the function
|
| 1330 |
+
call, and `rhs.rdbuf()` returns the same value as it returned before the
|
| 1331 |
+
function call.
|
| 1332 |
|
| 1333 |
``` cpp
|
| 1334 |
void set_rdbuf(basic_streambuf<charT, traits>* sb);
|
| 1335 |
```
|
| 1336 |
|
| 1337 |
+
*Preconditions:* `sb != nullptr` is `true`.
|
| 1338 |
|
| 1339 |
*Effects:* Associates the `basic_streambuf` object pointed to by `sb`
|
| 1340 |
with this stream without calling `clear()`.
|
| 1341 |
|
| 1342 |
+
*Ensures:* `rdbuf() == sb` is `true`.
|
| 1343 |
|
| 1344 |
*Throws:* Nothing.
|
| 1345 |
|
| 1346 |
+
#### Flags functions <a id="iostate.flags">[[iostate.flags]]</a>
|
| 1347 |
|
| 1348 |
``` cpp
|
| 1349 |
explicit operator bool() const;
|
| 1350 |
```
|
| 1351 |
|
|
|
|
| 1365 |
|
| 1366 |
``` cpp
|
| 1367 |
void clear(iostate state = goodbit);
|
| 1368 |
```
|
| 1369 |
|
| 1370 |
+
*Ensures:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
|
| 1371 |
`rdstate() == (state | ios_base::badbit)`.
|
| 1372 |
|
| 1373 |
*Effects:* If
|
| 1374 |
`((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
|
| 1375 |
+
Otherwise, the function throws an object of class `ios_base::failure`
|
| 1376 |
+
[[ios.failure]], constructed with *implementation-defined* argument
|
| 1377 |
+
values.
|
| 1378 |
|
| 1379 |
``` cpp
|
| 1380 |
void setstate(iostate state);
|
| 1381 |
```
|
| 1382 |
|
| 1383 |
*Effects:* Calls `clear(rdstate() | state)` (which may throw
|
| 1384 |
+
`ios_base::failure` [[ios.failure]]).
|
| 1385 |
|
| 1386 |
``` cpp
|
| 1387 |
bool good() const;
|
| 1388 |
```
|
| 1389 |
|
|
|
|
| 1416 |
|
| 1417 |
``` cpp
|
| 1418 |
void exceptions(iostate except);
|
| 1419 |
```
|
| 1420 |
|
| 1421 |
+
*Ensures:* `except == exceptions()`.
|
| 1422 |
|
| 1423 |
*Effects:* Calls `clear(rdstate())`.
|
| 1424 |
|
| 1425 |
### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
|
| 1426 |
|
| 1427 |
#### `fmtflags` manipulators <a id="fmtflags.manip">[[fmtflags.manip]]</a>
|
| 1428 |
|
| 1429 |
+
Each function specified in this subclause is a designated addressable
|
| 1430 |
+
function [[namespace.std]].
|
| 1431 |
+
|
| 1432 |
``` cpp
|
| 1433 |
ios_base& boolalpha(ios_base& str);
|
| 1434 |
```
|
| 1435 |
|
| 1436 |
*Effects:* Calls `str.setf(ios_base::boolalpha)`.
|
|
|
|
| 1541 |
|
| 1542 |
*Returns:* `str`.
|
| 1543 |
|
| 1544 |
#### `adjustfield` manipulators <a id="adjustfield.manip">[[adjustfield.manip]]</a>
|
| 1545 |
|
| 1546 |
+
Each function specified in this subclause is a designated addressable
|
| 1547 |
+
function [[namespace.std]].
|
| 1548 |
+
|
| 1549 |
``` cpp
|
| 1550 |
ios_base& internal(ios_base& str);
|
| 1551 |
```
|
| 1552 |
|
| 1553 |
*Effects:* Calls `str.setf(ios_base::internal, ios_base::adjustfield)`.
|
|
|
|
| 1570 |
|
| 1571 |
*Returns:* `str`.
|
| 1572 |
|
| 1573 |
#### `basefield` manipulators <a id="basefield.manip">[[basefield.manip]]</a>
|
| 1574 |
|
| 1575 |
+
Each function specified in this subclause is a designated addressable
|
| 1576 |
+
function [[namespace.std]].
|
| 1577 |
+
|
| 1578 |
``` cpp
|
| 1579 |
ios_base& dec(ios_base& str);
|
| 1580 |
```
|
| 1581 |
|
| 1582 |
*Effects:* Calls `str.setf(ios_base::dec, ios_base::basefield)`.
|
|
|
|
| 1599 |
|
| 1600 |
*Returns:* `str`.
|
| 1601 |
|
| 1602 |
#### `floatfield` manipulators <a id="floatfield.manip">[[floatfield.manip]]</a>
|
| 1603 |
|
| 1604 |
+
Each function specified in this subclause is a designated addressable
|
| 1605 |
+
function [[namespace.std]].
|
| 1606 |
+
|
| 1607 |
``` cpp
|
| 1608 |
ios_base& fixed(ios_base& str);
|
| 1609 |
```
|
| 1610 |
|
| 1611 |
*Effects:* Calls `str.setf(ios_base::fixed, ios_base::floatfield)`.
|
|
|
|
| 1629 |
|
| 1630 |
*Returns:* `str`.
|
| 1631 |
|
| 1632 |
[*Note 1*: The more obvious use of `ios_base::hex` to specify
|
| 1633 |
hexadecimal floating-point format would change the meaning of existing
|
| 1634 |
+
well-defined programs. C++03 gives no meaning to the combination of
|
| 1635 |
`fixed` and `scientific`. — *end note*]
|
| 1636 |
|
| 1637 |
``` cpp
|
| 1638 |
ios_base& defaultfloat(ios_base& str);
|
| 1639 |
```
|
| 1640 |
|
| 1641 |
*Effects:* Calls `str.unsetf(ios_base::floatfield)`.
|
| 1642 |
|
| 1643 |
*Returns:* `str`.
|
| 1644 |
|
| 1645 |
+
### Error reporting <a id="error.reporting">[[error.reporting]]</a>
|
| 1646 |
|
| 1647 |
``` cpp
|
| 1648 |
error_code make_error_code(io_errc e) noexcept;
|
| 1649 |
```
|
| 1650 |
|
|
|
|
| 1762 |
pos_type pubseekpos(pos_type sp,
|
| 1763 |
ios_base::openmode which
|
| 1764 |
= ios_base::in | ios_base::out);
|
| 1765 |
int pubsync();
|
| 1766 |
|
| 1767 |
+
// get and put areas
|
| 1768 |
// [streambuf.pub.get], get area
|
| 1769 |
streamsize in_avail();
|
| 1770 |
int_type snextc();
|
| 1771 |
int_type sbumpc();
|
| 1772 |
int_type sgetc();
|
|
|
|
| 1836 |
*character sequences*:
|
| 1837 |
|
| 1838 |
- a character *input sequence*;
|
| 1839 |
- a character *output sequence*.
|
| 1840 |
|
| 1841 |
+
#### Constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
|
| 1842 |
|
| 1843 |
``` cpp
|
| 1844 |
basic_streambuf();
|
| 1845 |
```
|
| 1846 |
|
| 1847 |
+
*Effects:* Initializes:[^13]
|
|
|
|
| 1848 |
|
| 1849 |
+
- all pointer member objects to null pointers,
|
| 1850 |
- the `getloc()` member to a copy the global locale, `locale()`, at the
|
| 1851 |
time of construction.
|
| 1852 |
|
| 1853 |
*Remarks:* Once the `getloc()` member is initialized, results of calling
|
| 1854 |
locale member functions, and of members of facets so obtained, can
|
|
|
|
| 1856 |
|
| 1857 |
``` cpp
|
| 1858 |
basic_streambuf(const basic_streambuf& rhs);
|
| 1859 |
```
|
| 1860 |
|
| 1861 |
+
*Ensures:*
|
|
|
|
|
|
|
| 1862 |
|
| 1863 |
- `eback() == rhs.eback()`
|
| 1864 |
- `gptr() == rhs.gptr()`
|
| 1865 |
- `egptr() == rhs.egptr()`
|
| 1866 |
- `pbase() == rhs.pbase()`
|
|
|
|
| 1872 |
~basic_streambuf();
|
| 1873 |
```
|
| 1874 |
|
| 1875 |
*Effects:* None.
|
| 1876 |
|
| 1877 |
+
#### Public member functions <a id="streambuf.members">[[streambuf.members]]</a>
|
| 1878 |
|
| 1879 |
##### Locales <a id="streambuf.locales">[[streambuf.locales]]</a>
|
| 1880 |
|
| 1881 |
``` cpp
|
| 1882 |
locale pubimbue(const locale& loc);
|
| 1883 |
```
|
| 1884 |
|
|
|
|
|
|
|
| 1885 |
*Effects:* Calls `imbue(loc)`.
|
| 1886 |
|
| 1887 |
+
*Ensures:* `loc == getloc()`.
|
| 1888 |
+
|
| 1889 |
*Returns:* Previous value of `getloc()`.
|
| 1890 |
|
| 1891 |
``` cpp
|
| 1892 |
locale getloc() const;
|
| 1893 |
```
|
|
|
|
| 1933 |
``` cpp
|
| 1934 |
streamsize in_avail();
|
| 1935 |
```
|
| 1936 |
|
| 1937 |
*Returns:* If a read position is available, returns `egptr() - gptr()`.
|
| 1938 |
+
Otherwise returns `showmanyc()` [[streambuf.virt.get]].
|
| 1939 |
|
| 1940 |
``` cpp
|
| 1941 |
int_type snextc();
|
| 1942 |
```
|
| 1943 |
|
|
|
|
| 1948 |
|
| 1949 |
``` cpp
|
| 1950 |
int_type sbumpc();
|
| 1951 |
```
|
| 1952 |
|
| 1953 |
+
*Effects:* If the input sequence read position is not available, returns
|
| 1954 |
`uflow()`. Otherwise, returns `traits::to_int_type(*gptr())` and
|
| 1955 |
increments the next pointer for the input sequence.
|
| 1956 |
|
| 1957 |
``` cpp
|
| 1958 |
int_type sgetc();
|
|
|
|
| 1971 |
|
| 1972 |
``` cpp
|
| 1973 |
int_type sputbackc(char_type c);
|
| 1974 |
```
|
| 1975 |
|
| 1976 |
+
*Effects:* If the input sequence putback position is not available, or
|
| 1977 |
if `traits::eq(c, gptr()[-1])` is `false`, returns
|
| 1978 |
`pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
|
| 1979 |
pointer for the input sequence and returns
|
| 1980 |
`traits::to_int_type(*gptr())`.
|
| 1981 |
|
| 1982 |
``` cpp
|
| 1983 |
int_type sungetc();
|
| 1984 |
```
|
| 1985 |
|
| 1986 |
+
*Effects:* If the input sequence putback position is not available,
|
| 1987 |
returns `pbackfail()`. Otherwise, decrements the next pointer for the
|
| 1988 |
input sequence and returns `traits::to_int_type(*gptr())`.
|
| 1989 |
|
| 1990 |
##### Put area <a id="streambuf.pub.put">[[streambuf.pub.put]]</a>
|
| 1991 |
|
| 1992 |
``` cpp
|
| 1993 |
int_type sputc(char_type c);
|
| 1994 |
```
|
| 1995 |
|
| 1996 |
+
*Effects:* If the output sequence write position is not available,
|
| 1997 |
returns `overflow(traits::to_int_type(c))`. Otherwise, stores `c` at the
|
| 1998 |
next pointer for the output sequence, increments the pointer, and
|
| 1999 |
returns `traits::to_int_type(c)`.
|
| 2000 |
|
| 2001 |
``` cpp
|
| 2002 |
streamsize sputn(const char_type* s, streamsize n);
|
| 2003 |
```
|
| 2004 |
|
| 2005 |
*Returns:* `xsputn(s, n)`.
|
| 2006 |
|
| 2007 |
+
#### Protected member functions <a id="streambuf.protected">[[streambuf.protected]]</a>
|
| 2008 |
|
| 2009 |
##### Assignment <a id="streambuf.assign">[[streambuf.assign]]</a>
|
| 2010 |
|
| 2011 |
``` cpp
|
| 2012 |
basic_streambuf& operator=(const basic_streambuf& rhs);
|
| 2013 |
```
|
| 2014 |
|
| 2015 |
+
*Ensures:*
|
|
|
|
|
|
|
| 2016 |
|
| 2017 |
- `eback() == rhs.eback()`
|
| 2018 |
- `gptr() == rhs.gptr()`
|
| 2019 |
- `egptr() == rhs.egptr()`
|
| 2020 |
- `pbase() == rhs.pbase()`
|
|
|
|
| 2058 |
|
| 2059 |
``` cpp
|
| 2060 |
void setg(char_type* gbeg, char_type* gnext, char_type* gend);
|
| 2061 |
```
|
| 2062 |
|
| 2063 |
+
*Ensures:* `gbeg == eback()`, `gnext == gptr()`, and `gend == egptr()`
|
| 2064 |
+
are all `true`.
|
| 2065 |
|
| 2066 |
##### Put area access <a id="streambuf.put.area">[[streambuf.put.area]]</a>
|
| 2067 |
|
| 2068 |
``` cpp
|
| 2069 |
char_type* pbase() const;
|
|
|
|
| 2091 |
|
| 2092 |
``` cpp
|
| 2093 |
void setp(char_type* pbeg, char_type* pend);
|
| 2094 |
```
|
| 2095 |
|
| 2096 |
+
*Ensures:* `pbeg == pbase()`, `pbeg == pptr()`, and `pend == epptr()`
|
| 2097 |
+
are all `true`.
|
| 2098 |
|
| 2099 |
+
#### Virtual functions <a id="streambuf.virtuals">[[streambuf.virtuals]]</a>
|
| 2100 |
|
| 2101 |
##### Locales <a id="streambuf.virt.locales">[[streambuf.virt.locales]]</a>
|
| 2102 |
|
| 2103 |
``` cpp
|
| 2104 |
void imbue(const locale&);
|
|
|
|
| 2159 |
is, if `pbase()` is non-null the characters between `pbase()` and
|
| 2160 |
`pptr()` are written to the controlled sequence. The pointers may then
|
| 2161 |
be reset as appropriate.
|
| 2162 |
|
| 2163 |
*Returns:* `-1` on failure. What constitutes failure is determined by
|
| 2164 |
+
each derived class [[filebuf.virtuals]].
|
| 2165 |
|
| 2166 |
*Default behavior:* Returns zero.
|
| 2167 |
|
| 2168 |
##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
|
| 2169 |
|
|
|
|
| 2200 |
``` cpp
|
| 2201 |
int_type underflow();
|
| 2202 |
```
|
| 2203 |
|
| 2204 |
*Remarks:* The public members of `basic_streambuf` call this virtual
|
| 2205 |
+
function only if `gptr()` is null or `gptr() >= egptr()`.
|
| 2206 |
|
| 2207 |
*Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
|
| 2208 |
of the *pending sequence*, without moving the input sequence position
|
| 2209 |
past it. If the pending sequence is null then the function returns
|
| 2210 |
`traits::eof()` to indicate failure.
|
|
|
|
| 2242 |
|
| 2243 |
``` cpp
|
| 2244 |
int_type uflow();
|
| 2245 |
```
|
| 2246 |
|
| 2247 |
+
*Preconditions:* The constraints are the same as for `underflow()`,
|
| 2248 |
+
except that the result character is transferred from the pending
|
| 2249 |
+
sequence to the backup sequence, and the pending sequence is not empty
|
| 2250 |
before the transfer.
|
| 2251 |
|
| 2252 |
*Default behavior:* Calls `underflow()`. If `underflow()` returns
|
| 2253 |
`traits::eof()`, returns `traits::eof()`. Otherwise, returns the value
|
| 2254 |
of `traits::to_int_type(*gptr())` and increment the value of the next
|
|
|
|
| 2275 |
is determined.
|
| 2276 |
- If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
|
| 2277 |
is prepended. Whether the input sequence is backed up or modified in
|
| 2278 |
any other way is unspecified.
|
| 2279 |
|
| 2280 |
+
*Ensures:* On return, the constraints of `gptr()`, `eback()`, and
|
| 2281 |
`pptr()` are the same as for `underflow()`.
|
| 2282 |
|
| 2283 |
*Returns:* `traits::eof()` to indicate failure. Failure may occur
|
| 2284 |
because the input sequence could not be backed up, or if for some other
|
| 2285 |
reason the pointers could not be set consistent with the constraints.
|
|
|
|
| 2311 |
|
| 2312 |
*Effects:* Consumes some initial subsequence of the characters of the
|
| 2313 |
*pending sequence*. The pending sequence is defined as the concatenation
|
| 2314 |
of
|
| 2315 |
|
| 2316 |
+
- the empty sequence if `pbase()` is null, otherwise the
|
| 2317 |
`pptr() - pbase()` characters beginning at `pbase()`, followed by
|
| 2318 |
- the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
|
| 2319 |
`true`, otherwise the sequence consisting of `c`.
|
| 2320 |
|
| 2321 |
*Remarks:* The member functions `sputc()` and `sputn()` call this
|
| 2322 |
function in case that no room can be found in the put buffer enough to
|
| 2323 |
accommodate the argument character sequence.
|
| 2324 |
|
| 2325 |
+
*Preconditions:* Every overriding definition of this virtual function
|
| 2326 |
+
obeys the following constraints:
|
| 2327 |
|
| 2328 |
+
- The effect of consuming a character on the associated output sequence
|
| 2329 |
+
is specified.[^16]
|
| 2330 |
+
- Let `r` be the number of characters in the pending sequence not
|
| 2331 |
+
consumed. If `r` is nonzero then `pbase()` and `pptr()` are set so
|
| 2332 |
+
that: `pptr() - pbase() == r` and the `r` characters starting at
|
| 2333 |
`pbase()` are the associated output stream. In case `r` is zero (all
|
| 2334 |
characters of the pending sequence have been consumed) then either
|
| 2335 |
+
`pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both set
|
| 2336 |
+
to the same non-null value.
|
| 2337 |
+
- The function may fail if either appending some character to the
|
| 2338 |
associated output stream fails or if it is unable to establish
|
| 2339 |
`pbase()` and `pptr()` according to the above rules.
|
| 2340 |
|
| 2341 |
*Returns:* `traits::eof()` or throws an exception if the function fails.
|
| 2342 |
|
|
|
|
| 2386 |
template<class charT, class traits>
|
| 2387 |
basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
|
| 2388 |
template<class charT, class traits>
|
| 2389 |
basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
|
| 2390 |
|
| 2391 |
+
template<class charT, class traits>
|
| 2392 |
+
basic_ostream<charT, traits>& emit_on_flush(basic_ostream<charT, traits>& os);
|
| 2393 |
+
template<class charT, class traits>
|
| 2394 |
+
basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
|
| 2395 |
+
template<class charT, class traits>
|
| 2396 |
+
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 2397 |
+
|
| 2398 |
template<class charT, class traits, class T>
|
| 2399 |
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
|
| 2400 |
}
|
| 2401 |
```
|
| 2402 |
|
|
|
|
| 2406 |
namespace std {
|
| 2407 |
// types T1, T2, ... are unspecified implementation types
|
| 2408 |
T1 resetiosflags(ios_base::fmtflags mask);
|
| 2409 |
T2 setiosflags (ios_base::fmtflags mask);
|
| 2410 |
T3 setbase(int base);
|
| 2411 |
+
template<class charT> T4 setfill(charT c);
|
| 2412 |
T5 setprecision(int n);
|
| 2413 |
T6 setw(int n);
|
| 2414 |
template<class moneyT> T7 get_money(moneyT& mon, bool intl = false);
|
| 2415 |
template<class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
|
| 2416 |
template<class charT> T9 get_time(struct tm* tmb, const charT* fmt);
|
|
|
|
| 2444 |
``` cpp
|
| 2445 |
namespace std {
|
| 2446 |
template<class charT, class traits = char_traits<charT>>
|
| 2447 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 2448 |
public:
|
| 2449 |
+
// types (inherited from basic_ios[ios])
|
| 2450 |
using char_type = charT;
|
| 2451 |
using int_type = typename traits::int_type;
|
| 2452 |
using pos_type = typename traits::pos_type;
|
| 2453 |
using off_type = typename traits::off_type;
|
| 2454 |
using traits_type = traits;
|
| 2455 |
|
| 2456 |
// [istream.cons], constructor/destructor
|
| 2457 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2458 |
virtual ~basic_istream();
|
| 2459 |
|
| 2460 |
+
// [istream.sentry], prefix/suffix
|
| 2461 |
class sentry;
|
| 2462 |
|
| 2463 |
// [istream.formatted], formatted input
|
| 2464 |
basic_istream<charT, traits>&
|
| 2465 |
operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
|
|
|
|
| 2509 |
basic_istream<charT, traits>& seekg(pos_type);
|
| 2510 |
basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
|
| 2511 |
|
| 2512 |
protected:
|
| 2513 |
// [istream.cons], copy/move constructor
|
| 2514 |
+
basic_istream(const basic_istream&) = delete;
|
| 2515 |
basic_istream(basic_istream&& rhs);
|
| 2516 |
|
| 2517 |
// [istream.assign], assign and swap
|
| 2518 |
+
basic_istream& operator=(const basic_istream&) = delete;
|
| 2519 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2520 |
void swap(basic_istream& rhs);
|
| 2521 |
};
|
| 2522 |
|
| 2523 |
// [istream.extractors], character extraction templates
|
|
|
|
| 2526 |
template<class traits>
|
| 2527 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char&);
|
| 2528 |
template<class traits>
|
| 2529 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char&);
|
| 2530 |
|
| 2531 |
+
template<class charT, class traits, size_t N>
|
| 2532 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT(&)[N]);
|
| 2533 |
+
template<class traits, size_t N>
|
| 2534 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char(&)[N]);
|
| 2535 |
+
template<class traits, size_t N>
|
| 2536 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char(&)[N]);
|
| 2537 |
}
|
| 2538 |
```
|
| 2539 |
|
| 2540 |
The class template `basic_istream` defines a number of member function
|
| 2541 |
signatures that assist in reading and interpreting input from sequences
|
|
|
|
| 2548 |
or `rdbuf()->sgetc()`. They may use other public members of `istream`.
|
| 2549 |
|
| 2550 |
If `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`,
|
| 2551 |
then the input function, except as explicitly noted otherwise, completes
|
| 2552 |
its actions and does `setstate(eofbit)`, which may throw
|
| 2553 |
+
`ios_base::failure` [[iostate.flags]], before returning.
|
| 2554 |
|
| 2555 |
If one of these called functions throws an exception, then unless
|
| 2556 |
+
explicitly noted otherwise, the input function sets `badbit` in the
|
| 2557 |
+
error state. If `badbit` is set in `exceptions()`, the input function
|
| 2558 |
+
rethrows the exception without completing its actions, otherwise it does
|
| 2559 |
+
not throw anything and proceeds as if the called function had returned a
|
| 2560 |
failure indication.
|
| 2561 |
|
| 2562 |
+
##### Constructors <a id="istream.cons">[[istream.cons]]</a>
|
| 2563 |
|
| 2564 |
``` cpp
|
| 2565 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2566 |
```
|
| 2567 |
|
| 2568 |
+
*Effects:* Initializes the base class subobject with
|
| 2569 |
+
`basic_ios::init(sb)` [[basic.ios.cons]].
|
|
|
|
| 2570 |
|
| 2571 |
+
*Ensures:* `gcount() == 0`.
|
| 2572 |
|
| 2573 |
``` cpp
|
| 2574 |
basic_istream(basic_istream&& rhs);
|
| 2575 |
```
|
| 2576 |
|
| 2577 |
+
*Effects:* Default constructs the base class, copies the `gcount()` from
|
| 2578 |
+
`rhs`, calls `basic_ios<charT, traits>::move(rhs)` to initialize the
|
| 2579 |
+
base class, and sets the `gcount()` for `rhs` to 0.
|
|
|
|
| 2580 |
|
| 2581 |
``` cpp
|
| 2582 |
virtual ~basic_istream();
|
| 2583 |
```
|
| 2584 |
|
|
|
|
|
|
|
| 2585 |
*Remarks:* Does not perform any operations of `rdbuf()`.
|
| 2586 |
|
| 2587 |
+
##### Assignment and swap <a id="istream.assign">[[istream.assign]]</a>
|
| 2588 |
|
| 2589 |
``` cpp
|
| 2590 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2591 |
```
|
| 2592 |
|
| 2593 |
+
*Effects:* Equivalent to: `swap(rhs)`.
|
| 2594 |
|
| 2595 |
*Returns:* `*this`.
|
| 2596 |
|
| 2597 |
``` cpp
|
| 2598 |
void swap(basic_istream& rhs);
|
| 2599 |
```
|
| 2600 |
|
| 2601 |
*Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`. Exchanges the
|
| 2602 |
values returned by `gcount()` and `rhs.gcount()`.
|
| 2603 |
|
| 2604 |
+
##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
|
| 2605 |
|
| 2606 |
``` cpp
|
| 2607 |
namespace std {
|
| 2608 |
template<class charT, class traits = char_traits<charT>>
|
| 2609 |
class basic_istream<charT, traits>::sentry {
|
|
|
|
| 2610 |
bool ok_; // exposition only
|
| 2611 |
public:
|
| 2612 |
explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
|
| 2613 |
~sentry();
|
| 2614 |
explicit operator bool() const { return ok_; }
|
|
|
|
| 2659 |
```
|
| 2660 |
|
| 2661 |
If, after any preparation is completed, `is.good()` is `true`,
|
| 2662 |
`ok_ != false` otherwise, `ok_ == false`. During preparation, the
|
| 2663 |
constructor may call `setstate(failbit)` (which may throw
|
| 2664 |
+
`ios_base::failure` [[iostate.flags]]).[^19]
|
| 2665 |
|
| 2666 |
``` cpp
|
| 2667 |
~sentry();
|
| 2668 |
```
|
| 2669 |
|
|
|
|
| 2671 |
|
| 2672 |
``` cpp
|
| 2673 |
explicit operator bool() const;
|
| 2674 |
```
|
| 2675 |
|
| 2676 |
+
*Returns:* `ok_`.
|
| 2677 |
|
| 2678 |
#### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
|
| 2679 |
|
| 2680 |
##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
|
| 2681 |
|
| 2682 |
Each formatted input function begins execution by constructing an object
|
| 2683 |
of class `sentry` with the `noskipws` (second) argument `false`. If the
|
| 2684 |
`sentry` object returns `true`, when converted to a value of type
|
| 2685 |
`bool`, the function endeavors to obtain the requested input. If an
|
| 2686 |
+
exception is thrown during input then `ios_base::badbit` is turned
|
| 2687 |
+
on[^20] in `*this`’s error state. If `(exceptions()&badbit) != 0` then
|
| 2688 |
+
the exception is rethrown. In any case, the formatted input function
|
| 2689 |
destroys the `sentry` object. If no exception has been thrown, it
|
| 2690 |
returns `*this`.
|
| 2691 |
|
| 2692 |
##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
|
| 2693 |
|
|
|
|
| 2704 |
operator>>(bool& val);
|
| 2705 |
operator>>(void*& val);
|
| 2706 |
```
|
| 2707 |
|
| 2708 |
As in the case of the inserters, these extractors depend on the locale’s
|
| 2709 |
+
`num_get<>` [[locale.num.get]] object to perform parsing the input
|
| 2710 |
stream data. These extractors behave as formatted input functions (as
|
| 2711 |
described in [[istream.formatted.reqmts]]). After a sentry object is
|
| 2712 |
constructed, the conversion occurs as if performed by the following code
|
| 2713 |
fragment:
|
| 2714 |
|
|
|
|
| 2808 |
in [[istream.formatted.reqmts]]).
|
| 2809 |
|
| 2810 |
*Returns:* `*this`.
|
| 2811 |
|
| 2812 |
``` cpp
|
| 2813 |
+
template<class charT, class traits, size_t N>
|
| 2814 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT (&s)[N]);
|
| 2815 |
+
template<class traits, size_t N>
|
| 2816 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char (&s)[N]);
|
| 2817 |
+
template<class traits, size_t N>
|
| 2818 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char (&s)[N]);
|
| 2819 |
```
|
| 2820 |
|
| 2821 |
*Effects:* Behaves like a formatted input member (as described
|
| 2822 |
in [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
|
| 2823 |
+
constructed, `operator>>` extracts characters and stores them into `s`.
|
| 2824 |
+
If `width()` is greater than zero, `n` is `min(size_t(width()), N)`.
|
| 2825 |
+
Otherwise `n` is `N`. `n` is the maximum number of characters stored.
|
|
|
|
|
|
|
|
|
|
| 2826 |
|
| 2827 |
Characters are extracted and stored until any of the following occurs:
|
| 2828 |
|
| 2829 |
- `n-1` characters are stored;
|
| 2830 |
- end of file occurs on the input sequence;
|
|
|
|
| 2834 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 2835 |
which may be the first position if no characters were extracted.
|
| 2836 |
`operator>>` then calls `width(0)`.
|
| 2837 |
|
| 2838 |
If the function extracted no characters, it calls `setstate(failbit)`,
|
| 2839 |
+
which may throw `ios_base::failure` [[iostate.flags]].
|
| 2840 |
|
| 2841 |
*Returns:* `in`.
|
| 2842 |
|
| 2843 |
``` cpp
|
| 2844 |
template<class charT, class traits>
|
|
|
|
| 2858 |
|
| 2859 |
``` cpp
|
| 2860 |
basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
|
| 2861 |
```
|
| 2862 |
|
| 2863 |
+
*Effects:* Behaves as an unformatted input
|
| 2864 |
+
function [[istream.unformatted]]. If `sb` is null, calls
|
| 2865 |
+
`setstate(failbit)`, which may throw `ios_base::failure`
|
| 2866 |
+
[[iostate.flags]]. After a sentry object is constructed, extracts
|
| 2867 |
+
characters from `*this` and inserts them in the output sequence
|
| 2868 |
+
controlled by `sb`. Characters are extracted and inserted until any of
|
| 2869 |
+
the following occurs:
|
| 2870 |
|
| 2871 |
- end-of-file occurs on the input sequence;
|
| 2872 |
- inserting in the output sequence fails (in which case the character to
|
| 2873 |
be inserted is not extracted);
|
| 2874 |
- an exception occurs (in which case the exception is caught).
|
| 2875 |
|
| 2876 |
If the function inserts no characters, it calls `setstate(failbit)`,
|
| 2877 |
+
which may throw `ios_base::failure` [[iostate.flags]]. If it inserted no
|
| 2878 |
+
characters because it caught an exception thrown while extracting
|
| 2879 |
+
characters from `*this` and `failbit` is set in `exceptions()`
|
| 2880 |
+
[[iostate.flags]], then the caught exception is rethrown.
|
|
|
|
| 2881 |
|
| 2882 |
*Returns:* `*this`.
|
| 2883 |
|
| 2884 |
#### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
|
| 2885 |
|
|
|
|
| 2892 |
a value of type `bool`, the function returns without attempting to
|
| 2893 |
obtain any input. In either case the number of extracted characters is
|
| 2894 |
set to 0; unformatted input functions taking a character array of
|
| 2895 |
nonzero size as an argument shall also store a null character (using
|
| 2896 |
`charT()`) in the first location of the array. If an exception is thrown
|
| 2897 |
+
during input then `ios_base::badbit` is turned on[^23] in `*this`’s
|
| 2898 |
+
error state. (Exceptions thrown from `basic_ios<>::clear()` are not
|
| 2899 |
+
caught or rethrown.) If `(exceptions()&badbit) != 0` then the exception
|
| 2900 |
+
is rethrown. It also counts the number of characters extracted. If no
|
| 2901 |
exception has been thrown it ends by storing the count in a member
|
| 2902 |
object and returning the value specified. In any event the `sentry`
|
| 2903 |
object is destroyed before leaving the unformatted input function.
|
| 2904 |
|
| 2905 |
``` cpp
|
|
|
|
| 2917 |
```
|
| 2918 |
|
| 2919 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2920 |
above). After constructing a sentry object, extracts a character `c`, if
|
| 2921 |
one is available. Otherwise, the function calls `setstate(failbit)`,
|
| 2922 |
+
which may throw `ios_base::failure` [[iostate.flags]].
|
| 2923 |
|
| 2924 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 2925 |
|
| 2926 |
``` cpp
|
| 2927 |
basic_istream<charT, traits>& get(char_type& c);
|
| 2928 |
```
|
| 2929 |
|
| 2930 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2931 |
above). After constructing a sentry object, extracts a character, if one
|
| 2932 |
is available, and assigns it to `c`.[^24] Otherwise, the function calls
|
| 2933 |
+
`setstate(failbit)` (which may throw `ios_base::failure`
|
| 2934 |
+
[[iostate.flags]]).
|
| 2935 |
|
| 2936 |
*Returns:* `*this`.
|
| 2937 |
|
| 2938 |
``` cpp
|
| 2939 |
basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
|
|
|
|
| 2950 |
calls `setstate(eofbit)`);
|
| 2951 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 2952 |
which case `c` is not extracted).
|
| 2953 |
|
| 2954 |
If the function stores no characters, it calls `setstate(failbit)`
|
| 2955 |
+
(which may throw `ios_base::failure` [[iostate.flags]]). In any case, if
|
| 2956 |
+
`n` is greater than zero it then stores a null character into the next
|
| 2957 |
+
successive location of the array.
|
| 2958 |
|
| 2959 |
*Returns:* `*this`.
|
| 2960 |
|
| 2961 |
``` cpp
|
| 2962 |
basic_istream<charT, traits>& get(char_type* s, streamsize n);
|
|
|
|
| 2982 |
which case `c` is not extracted);
|
| 2983 |
- an exception occurs (in which case, the exception is caught but not
|
| 2984 |
rethrown).
|
| 2985 |
|
| 2986 |
If the function inserts no characters, it calls `setstate(failbit)`,
|
| 2987 |
+
which may throw `ios_base::failure` [[iostate.flags]].
|
| 2988 |
|
| 2989 |
*Returns:* `*this`.
|
| 2990 |
|
| 2991 |
``` cpp
|
| 2992 |
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
|
|
|
|
| 3015 |
the function calls `setstate(failbit)`).
|
| 3016 |
|
| 3017 |
These conditions are tested in the order shown.[^28]
|
| 3018 |
|
| 3019 |
If the function extracts no characters, it calls `setstate(failbit)`
|
| 3020 |
+
(which may throw `ios_base::failure` [[iostate.flags]]).[^29]
|
| 3021 |
|
| 3022 |
In any case, if `n` is greater than zero, it then stores a null
|
| 3023 |
character (using `charT()`) into the next successive location of the
|
| 3024 |
array.
|
| 3025 |
|
|
|
|
| 3067 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3068 |
above). After constructing a sentry object, extracts characters and
|
| 3069 |
discards them. Characters are extracted until any of the following
|
| 3070 |
occurs:
|
| 3071 |
|
| 3072 |
+
- `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
|
| 3073 |
characters have been extracted so far
|
| 3074 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3075 |
+
calls `setstate(eofbit)`, which may throw `ios_base::failure`
|
| 3076 |
+
[[iostate.flags]]);
|
| 3077 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
| 3078 |
available input character `c` (in which case `c` is extracted).
|
| 3079 |
|
| 3080 |
*Remarks:* The last condition will never occur if
|
| 3081 |
`traits::eq_int_type(delim, traits::eof())`.
|
|
|
|
| 3105 |
extracted and stored until either of the following occurs:
|
| 3106 |
|
| 3107 |
- `n` characters are stored;
|
| 3108 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3109 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 3110 |
+
`ios_base::failure` [[iostate.flags]]).
|
| 3111 |
|
| 3112 |
*Returns:* `*this`.
|
| 3113 |
|
| 3114 |
``` cpp
|
| 3115 |
streamsize readsome(char_type* s, streamsize n);
|
|
|
|
| 3119 |
above). After constructing a sentry object, if `!good()` calls
|
| 3120 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3121 |
extracts characters and stores them into successive locations of an
|
| 3122 |
array whose first element is designated by `s`. If
|
| 3123 |
`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
|
| 3124 |
+
`ios_base::failure` [[iostate.flags]]), and extracts no characters;
|
| 3125 |
|
| 3126 |
- If `rdbuf()->in_avail() == 0`, extracts no characters
|
| 3127 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 3128 |
|
| 3129 |
*Returns:* The number of characters extracted.
|
|
|
|
| 3134 |
|
| 3135 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3136 |
above), except that the function first clears `eofbit`. After
|
| 3137 |
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3138 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3139 |
+
calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
|
| 3140 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3141 |
+
`ios_base::failure` [[iostate.flags]]).
|
| 3142 |
|
| 3143 |
[*Note 1*: This function extracts no characters, so the value returned
|
| 3144 |
by the next call to `gcount()` is 0. — *end note*]
|
| 3145 |
|
| 3146 |
*Returns:* `*this`.
|
|
|
|
| 3151 |
|
| 3152 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3153 |
above), except that the function first clears `eofbit`. After
|
| 3154 |
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3155 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3156 |
+
calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
|
| 3157 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3158 |
+
`ios_base::failure` [[iostate.flags]]).
|
| 3159 |
|
| 3160 |
[*Note 2*: This function extracts no characters, so the value returned
|
| 3161 |
by the next call to `gcount()` is 0. — *end note*]
|
| 3162 |
|
| 3163 |
*Returns:* `*this`.
|
|
|
|
| 3170 |
above), except that it does not count the number of characters extracted
|
| 3171 |
and does not affect the value returned by subsequent calls to
|
| 3172 |
`gcount()`. After constructing a sentry object, if `rdbuf()` is a null
|
| 3173 |
pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
|
| 3174 |
that function returns `-1` calls `setstate(badbit)` (which may throw
|
| 3175 |
+
`ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
|
| 3176 |
returns zero.
|
| 3177 |
|
| 3178 |
``` cpp
|
| 3179 |
pos_type tellg();
|
| 3180 |
```
|
|
|
|
| 3218 |
|
| 3219 |
*Returns:* `*this`.
|
| 3220 |
|
| 3221 |
#### Standard `basic_istream` manipulators <a id="istream.manip">[[istream.manip]]</a>
|
| 3222 |
|
| 3223 |
+
Each instantiation of the function template specified in this subclause
|
| 3224 |
+
is a designated addressable function [[namespace.std]].
|
| 3225 |
+
|
| 3226 |
``` cpp
|
| 3227 |
template<class charT, class traits>
|
| 3228 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 3229 |
```
|
| 3230 |
|
| 3231 |
+
*Effects:* Behaves as an unformatted input
|
| 3232 |
+
function [[istream.unformatted]], except that it does not count the
|
| 3233 |
+
number of characters extracted and does not affect the value returned by
|
| 3234 |
+
subsequent calls to `is.gcount()`. After constructing a sentry object
|
| 3235 |
extracts characters as long as the next available character `c` is
|
| 3236 |
whitespace or until there are no more characters in the sequence.
|
| 3237 |
Whitespace characters are distinguished with the same criterion as used
|
| 3238 |
+
by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
|
| 3239 |
characters because there are no more available it sets `eofbit`, but not
|
| 3240 |
`failbit`.
|
| 3241 |
|
| 3242 |
*Returns:* `is`.
|
| 3243 |
|
| 3244 |
#### Rvalue stream extraction <a id="istream.rvalue">[[istream.rvalue]]</a>
|
| 3245 |
|
| 3246 |
``` cpp
|
| 3247 |
+
template<class Istream, class T>
|
| 3248 |
+
Istream&& operator>>(Istream&& is, T&& x);
|
| 3249 |
```
|
| 3250 |
|
| 3251 |
+
*Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
|
| 3252 |
+
when treated as an unevaluated operand and `Istream` is publicly and
|
| 3253 |
+
unambiguously derived from `ios_base`.
|
| 3254 |
+
|
| 3255 |
*Effects:* Equivalent to:
|
| 3256 |
|
| 3257 |
``` cpp
|
| 3258 |
is >> std::forward<T>(x);
|
| 3259 |
+
return std::move(is);
|
| 3260 |
```
|
| 3261 |
|
|
|
|
|
|
|
|
|
|
| 3262 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 3263 |
|
| 3264 |
``` cpp
|
| 3265 |
namespace std {
|
| 3266 |
template<class charT, class traits = char_traits<charT>>
|
|
|
|
| 3280 |
// [iostream.dest], destructor
|
| 3281 |
virtual ~basic_iostream();
|
| 3282 |
|
| 3283 |
protected:
|
| 3284 |
// [iostream.cons], constructor
|
| 3285 |
+
basic_iostream(const basic_iostream&) = delete;
|
| 3286 |
basic_iostream(basic_iostream&& rhs);
|
| 3287 |
|
| 3288 |
// [iostream.assign], assign and swap
|
| 3289 |
+
basic_iostream& operator=(const basic_iostream&) = delete;
|
| 3290 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3291 |
void swap(basic_iostream& rhs);
|
| 3292 |
};
|
| 3293 |
}
|
| 3294 |
```
|
| 3295 |
|
| 3296 |
The class template `basic_iostream` inherits a number of functions that
|
| 3297 |
allow reading input and writing output to sequences controlled by a
|
| 3298 |
stream buffer.
|
| 3299 |
|
| 3300 |
+
##### Constructors <a id="iostream.cons">[[iostream.cons]]</a>
|
| 3301 |
|
| 3302 |
``` cpp
|
| 3303 |
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
| 3304 |
```
|
| 3305 |
|
| 3306 |
+
*Effects:* Initializes the base class subobjects with
|
| 3307 |
+
`basic_istream<charT, traits>(sb)` [[istream]] and
|
| 3308 |
+
`basic_ostream<charT, traits>(sb)` [[ostream]].
|
|
|
|
| 3309 |
|
| 3310 |
+
*Ensures:* `rdbuf() == sb` and `gcount() == 0`.
|
| 3311 |
|
| 3312 |
``` cpp
|
| 3313 |
basic_iostream(basic_iostream&& rhs);
|
| 3314 |
```
|
| 3315 |
|
| 3316 |
*Effects:* Move constructs from the rvalue `rhs` by constructing the
|
| 3317 |
`basic_istream` base class with `move(rhs)`.
|
| 3318 |
|
| 3319 |
+
##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
|
| 3320 |
|
| 3321 |
``` cpp
|
| 3322 |
virtual ~basic_iostream();
|
| 3323 |
```
|
| 3324 |
|
|
|
|
|
|
|
| 3325 |
*Remarks:* Does not perform any operations on `rdbuf()`.
|
| 3326 |
|
| 3327 |
+
##### Assignment and swap <a id="iostream.assign">[[iostream.assign]]</a>
|
| 3328 |
|
| 3329 |
``` cpp
|
| 3330 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3331 |
```
|
| 3332 |
|
| 3333 |
+
*Effects:* Equivalent to: `swap(rhs)`.
|
| 3334 |
|
| 3335 |
``` cpp
|
| 3336 |
void swap(basic_iostream& rhs);
|
| 3337 |
```
|
| 3338 |
|
|
|
|
| 3349 |
``` cpp
|
| 3350 |
namespace std {
|
| 3351 |
template<class charT, class traits = char_traits<charT>>
|
| 3352 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 3353 |
public:
|
| 3354 |
+
// types (inherited from basic_ios[ios])
|
| 3355 |
using char_type = charT;
|
| 3356 |
using int_type = typename traits::int_type;
|
| 3357 |
using pos_type = typename traits::pos_type;
|
| 3358 |
using off_type = typename traits::off_type;
|
| 3359 |
using traits_type = traits;
|
| 3360 |
|
| 3361 |
// [ostream.cons], constructor/destructor
|
| 3362 |
explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
|
| 3363 |
virtual ~basic_ostream();
|
| 3364 |
|
| 3365 |
+
// [ostream.sentry], prefix/suffix
|
| 3366 |
class sentry;
|
| 3367 |
|
| 3368 |
// [ostream.formatted], formatted output
|
| 3369 |
basic_ostream<charT, traits>&
|
| 3370 |
operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
|
|
|
|
| 3401 |
basic_ostream<charT, traits>& seekp(pos_type);
|
| 3402 |
basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
|
| 3403 |
|
| 3404 |
protected:
|
| 3405 |
// [ostream.cons], copy/move constructor
|
| 3406 |
+
basic_ostream(const basic_ostream&) = delete;
|
| 3407 |
basic_ostream(basic_ostream&& rhs);
|
| 3408 |
|
| 3409 |
// [ostream.assign], assign and swap
|
| 3410 |
+
basic_ostream& operator=(const basic_ostream&) = delete;
|
| 3411 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3412 |
void swap(basic_ostream& rhs);
|
| 3413 |
};
|
| 3414 |
|
| 3415 |
// [ostream.inserters.character], character inserters
|
|
|
|
| 3423 |
template<class traits>
|
| 3424 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, signed char);
|
| 3425 |
template<class traits>
|
| 3426 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, unsigned char);
|
| 3427 |
|
| 3428 |
+
template<class traits>
|
| 3429 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, wchar_t) = delete;
|
| 3430 |
+
template<class traits>
|
| 3431 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char8_t) = delete;
|
| 3432 |
+
template<class traits>
|
| 3433 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char16_t) = delete;
|
| 3434 |
+
template<class traits>
|
| 3435 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char32_t) = delete;
|
| 3436 |
+
template<class traits>
|
| 3437 |
+
basic_ostream<wchar_t, traits>&
|
| 3438 |
+
operator<<(basic_ostream<wchar_t, traits>&, char8_t) = delete;
|
| 3439 |
+
template<class traits>
|
| 3440 |
+
basic_ostream<wchar_t, traits>&
|
| 3441 |
+
operator<<(basic_ostream<wchar_t, traits>&, char16_t) = delete;
|
| 3442 |
+
template<class traits>
|
| 3443 |
+
basic_ostream<wchar_t, traits>&
|
| 3444 |
+
operator<<(basic_ostream<wchar_t, traits>&, char32_t) = delete;
|
| 3445 |
+
|
| 3446 |
template<class charT, class traits>
|
| 3447 |
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const charT*);
|
| 3448 |
template<class charT, class traits>
|
| 3449 |
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const char*);
|
| 3450 |
template<class traits>
|
|
|
|
| 3452 |
|
| 3453 |
template<class traits>
|
| 3454 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const signed char*);
|
| 3455 |
template<class traits>
|
| 3456 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const unsigned char*);
|
| 3457 |
+
|
| 3458 |
+
template<class traits>
|
| 3459 |
+
basic_ostream<char, traits>&
|
| 3460 |
+
operator<<(basic_ostream<char, traits>&, const wchar_t*) = delete;
|
| 3461 |
+
template<class traits>
|
| 3462 |
+
basic_ostream<char, traits>&
|
| 3463 |
+
operator<<(basic_ostream<char, traits>&, const char8_t*) = delete;
|
| 3464 |
+
template<class traits>
|
| 3465 |
+
basic_ostream<char, traits>&
|
| 3466 |
+
operator<<(basic_ostream<char, traits>&, const char16_t*) = delete;
|
| 3467 |
+
template<class traits>
|
| 3468 |
+
basic_ostream<char, traits>&
|
| 3469 |
+
operator<<(basic_ostream<char, traits>&, const char32_t*) = delete;
|
| 3470 |
+
template<class traits>
|
| 3471 |
+
basic_ostream<wchar_t, traits>&
|
| 3472 |
+
operator<<(basic_ostream<wchar_t, traits>&, const char8_t*) = delete;
|
| 3473 |
+
template<class traits>
|
| 3474 |
+
basic_ostream<wchar_t, traits>&
|
| 3475 |
+
operator<<(basic_ostream<wchar_t, traits>&, const char16_t*) = delete;
|
| 3476 |
+
template<class traits>
|
| 3477 |
+
basic_ostream<wchar_t, traits>&
|
| 3478 |
+
operator<<(basic_ostream<wchar_t, traits>&, const char32_t*) = delete;
|
| 3479 |
}
|
| 3480 |
```
|
| 3481 |
|
| 3482 |
The class template `basic_ostream` defines a number of member function
|
| 3483 |
signatures that assist in formatting and writing output to output
|
|
|
|
| 3490 |
`rdbuf()->sputc(int_type)`. They may use other public members of
|
| 3491 |
`basic_ostream` except that they shall not invoke any virtual members of
|
| 3492 |
`rdbuf()` except `overflow()`, `xsputn()`, and `sync()`.
|
| 3493 |
|
| 3494 |
If one of these called functions throws an exception, then unless
|
| 3495 |
+
explicitly noted otherwise the output function sets `badbit` in the
|
| 3496 |
+
error state. If `badbit` is set in `exceptions()`, the output function
|
| 3497 |
+
rethrows the exception without completing its actions, otherwise it does
|
| 3498 |
+
not throw anything and proceeds as if the called function had returned a
|
| 3499 |
+
failure indication.
|
| 3500 |
|
| 3501 |
+
[*Note 1*: The deleted overloads of `operator<<` prevent formatting
|
| 3502 |
+
characters as integers and strings as pointers. — *end note*]
|
| 3503 |
+
|
| 3504 |
+
##### Constructors <a id="ostream.cons">[[ostream.cons]]</a>
|
| 3505 |
|
| 3506 |
``` cpp
|
| 3507 |
explicit basic_ostream(basic_streambuf<charT, traits>* sb);
|
| 3508 |
```
|
| 3509 |
|
| 3510 |
+
*Effects:* Initializes the base class subobject with
|
| 3511 |
+
`basic_ios<charT, traits>::init(sb)` [[basic.ios.cons]].
|
|
|
|
| 3512 |
|
| 3513 |
+
*Ensures:* `rdbuf() == sb`.
|
| 3514 |
|
| 3515 |
``` cpp
|
| 3516 |
basic_ostream(basic_ostream&& rhs);
|
| 3517 |
```
|
| 3518 |
|
|
|
|
| 3522 |
|
| 3523 |
``` cpp
|
| 3524 |
virtual ~basic_ostream();
|
| 3525 |
```
|
| 3526 |
|
|
|
|
|
|
|
| 3527 |
*Remarks:* Does not perform any operations on `rdbuf()`.
|
| 3528 |
|
| 3529 |
+
##### Assignment and swap <a id="ostream.assign">[[ostream.assign]]</a>
|
| 3530 |
|
| 3531 |
``` cpp
|
| 3532 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3533 |
```
|
| 3534 |
|
| 3535 |
+
*Effects:* Equivalent to: `swap(rhs)`.
|
| 3536 |
|
| 3537 |
*Returns:* `*this`.
|
| 3538 |
|
| 3539 |
``` cpp
|
| 3540 |
void swap(basic_ostream& rhs);
|
| 3541 |
```
|
| 3542 |
|
| 3543 |
*Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`.
|
| 3544 |
|
| 3545 |
+
##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
|
| 3546 |
|
| 3547 |
``` cpp
|
| 3548 |
namespace std {
|
| 3549 |
template<class charT, class traits = char_traits<charT>>
|
| 3550 |
class basic_ostream<charT, traits>::sentry {
|
|
|
|
| 3571 |
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^31]
|
| 3572 |
|
| 3573 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 3574 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 3575 |
constructor may call `setstate(failbit)` (which may throw
|
| 3576 |
+
`ios_base::failure` [[iostate.flags]]).[^32]
|
| 3577 |
|
| 3578 |
``` cpp
|
| 3579 |
~sentry();
|
| 3580 |
```
|
| 3581 |
|
|
|
|
| 3588 |
explicit operator bool() const;
|
| 3589 |
```
|
| 3590 |
|
| 3591 |
*Effects:* Returns `ok_`.
|
| 3592 |
|
| 3593 |
+
##### Seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
|
| 3594 |
|
| 3595 |
Each seek member function begins execution by constructing an object of
|
| 3596 |
class `sentry`. It returns by destroying the `sentry` object.
|
| 3597 |
|
| 3598 |
``` cpp
|
|
|
|
| 3631 |
Each formatted output function begins execution by constructing an
|
| 3632 |
object of class `sentry`. If this object returns `true` when converted
|
| 3633 |
to a value of type `bool`, the function endeavors to generate the
|
| 3634 |
requested output. If the generation fails, then the formatted output
|
| 3635 |
function does `setstate(ios_base::failbit)`, which might throw an
|
| 3636 |
+
exception. If an exception is thrown during output, then
|
| 3637 |
+
`ios_base::badbit` is turned on[^33] in `*this`’s error state. If
|
| 3638 |
`(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
|
| 3639 |
not an exception is thrown, the `sentry` object is destroyed before
|
| 3640 |
leaving the formatted output function. If no exception is thrown, the
|
| 3641 |
result of the formatted output function is `*this`.
|
| 3642 |
|
|
|
|
| 3777 |
|
| 3778 |
``` cpp
|
| 3779 |
basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
|
| 3780 |
```
|
| 3781 |
|
| 3782 |
+
*Effects:* Behaves as an unformatted output
|
| 3783 |
+
function [[ostream.unformatted]]. After the sentry object is
|
| 3784 |
+
constructed, if `sb` is null calls `setstate(badbit)` (which may throw
|
| 3785 |
`ios_base::failure`).
|
| 3786 |
|
| 3787 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 3788 |
read from `sb` and inserted until any of the following occurs:
|
| 3789 |
|
|
|
|
| 3791 |
- inserting in the output sequence fails (in which case the character to
|
| 3792 |
be inserted is not extracted);
|
| 3793 |
- an exception occurs while getting a character from `sb`.
|
| 3794 |
|
| 3795 |
If the function inserts no characters, it calls `setstate(failbit)`
|
| 3796 |
+
(which may throw `ios_base::failure` [[iostate.flags]]). If an exception
|
| 3797 |
+
was thrown while extracting a character, the function sets `failbit` in
|
| 3798 |
+
the error state, and if `failbit` is set in `exceptions()` the caught
|
| 3799 |
+
exception is rethrown.
|
| 3800 |
|
| 3801 |
*Returns:* `*this`.
|
| 3802 |
|
| 3803 |
``` cpp
|
| 3804 |
basic_ostream<charT, traits>& operator<<(nullptr_t);
|
|
|
|
| 3808 |
|
| 3809 |
``` cpp
|
| 3810 |
return *this << s;
|
| 3811 |
```
|
| 3812 |
|
| 3813 |
+
where `s` is an *implementation-defined* NTCTS [[defns.ntcts]].
|
| 3814 |
|
| 3815 |
##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
|
| 3816 |
|
| 3817 |
``` cpp
|
| 3818 |
template<class charT, class traits>
|
|
|
|
| 3828 |
template<class traits>
|
| 3829 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
|
| 3830 |
```
|
| 3831 |
|
| 3832 |
*Effects:* Behaves as a formatted output
|
| 3833 |
+
function [[ostream.formatted.reqmts]] of `out`. Constructs a character
|
| 3834 |
+
sequence `seq`. If `c` has type `char` and the character type of the
|
| 3835 |
+
stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
|
| 3836 |
+
`seq` consists of `c`. Determines padding for `seq` as described
|
| 3837 |
+
in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
|
| 3838 |
+
`os.width(0)`.
|
| 3839 |
|
| 3840 |
*Returns:* `out`.
|
| 3841 |
|
| 3842 |
``` cpp
|
| 3843 |
template<class charT, class traits>
|
|
|
|
| 3851 |
template<class traits>
|
| 3852 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
|
| 3853 |
const unsigned char* s);
|
| 3854 |
```
|
| 3855 |
|
| 3856 |
+
*Preconditions:* `s` is not a null pointer.
|
| 3857 |
|
| 3858 |
*Effects:* Behaves like a formatted inserter (as described
|
| 3859 |
in [[ostream.formatted.reqmts]]) of `out`. Creates a character sequence
|
| 3860 |
`seq` of `n` characters starting at `s`, each widened using
|
| 3861 |
+
`out.widen()` [[basic.ios.members]], where `n` is the number that would
|
| 3862 |
+
be computed as if by:
|
| 3863 |
|
| 3864 |
- `traits::length(s)` for the overload where the first argument is of
|
| 3865 |
type `basic_ostream<charT, traits>&` and the second is of type
|
| 3866 |
`const charT*`, and also for the overload where the first argument is
|
| 3867 |
of type `basic_ostream<char, traits>&` and the second is of type
|
|
|
|
| 3882 |
|
| 3883 |
Each unformatted output function begins execution by constructing an
|
| 3884 |
object of class `sentry`. If this object returns `true`, while
|
| 3885 |
converting to a value of type `bool`, the function endeavors to generate
|
| 3886 |
the requested output. If an exception is thrown during output, then
|
| 3887 |
+
`ios_base::badbit` is turned on[^36] in `*this`’s error state. If
|
| 3888 |
`(exceptions() & badbit) != 0` then the exception is rethrown. In any
|
| 3889 |
case, the unformatted output function ends by destroying the sentry
|
| 3890 |
object, then, if no exception was thrown, returning the value specified
|
| 3891 |
for the unformatted output function.
|
| 3892 |
|
|
|
|
| 3896 |
|
| 3897 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3898 |
above). After constructing a sentry object, inserts the character `c`,
|
| 3899 |
if possible.[^37]
|
| 3900 |
|
| 3901 |
+
Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 3902 |
+
[[iostate.flags]]).
|
| 3903 |
|
| 3904 |
*Returns:* `*this`.
|
| 3905 |
|
| 3906 |
``` cpp
|
| 3907 |
basic_ostream& write(const char_type* s, streamsize n);
|
|
|
|
| 3913 |
by `s`.[^38] Characters are inserted until either of the following
|
| 3914 |
occurs:
|
| 3915 |
|
| 3916 |
- `n` characters are inserted;
|
| 3917 |
- inserting in the output sequence fails (in which case the function
|
| 3918 |
+
calls `setstate(badbit)`, which may throw `ios_base::failure`
|
| 3919 |
+
[[iostate.flags]]).
|
| 3920 |
|
| 3921 |
*Returns:* `*this`.
|
| 3922 |
|
| 3923 |
``` cpp
|
| 3924 |
basic_ostream& flush();
|
|
|
|
| 3926 |
|
| 3927 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3928 |
above). If `rdbuf()` is not a null pointer, constructs a sentry object.
|
| 3929 |
If this object returns `true` when converted to a value of type `bool`
|
| 3930 |
the function calls `rdbuf()->pubsync()`. If that function returns -1
|
| 3931 |
+
calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 3932 |
+
[[iostate.flags]]). Otherwise, if the sentry object returns `false`,
|
| 3933 |
+
does nothing.
|
| 3934 |
|
| 3935 |
*Returns:* `*this`.
|
| 3936 |
|
| 3937 |
+
#### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
|
| 3938 |
+
|
| 3939 |
+
Each instantiation of any of the function templates specified in this
|
| 3940 |
+
subclause is a designated addressable function [[namespace.std]].
|
| 3941 |
|
| 3942 |
``` cpp
|
| 3943 |
template<class charT, class traits>
|
| 3944 |
basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
|
| 3945 |
```
|
|
|
|
| 3965 |
|
| 3966 |
*Effects:* Calls `os.flush()`.
|
| 3967 |
|
| 3968 |
*Returns:* `os`.
|
| 3969 |
|
| 3970 |
+
``` cpp
|
| 3971 |
+
template<class charT, class traits>
|
| 3972 |
+
basic_ostream<charT, traits>& emit_on_flush(basic_ostream<charT, traits>& os);
|
| 3973 |
+
```
|
| 3974 |
+
|
| 3975 |
+
*Effects:* If `os.rdbuf()` is a
|
| 3976 |
+
`basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
|
| 3977 |
+
of exposition, calls `buf->set_emit_on_sync(true)`. Otherwise this
|
| 3978 |
+
manipulator has no effect.
|
| 3979 |
+
|
| 3980 |
+
[*Note 1*: To work around the issue that the `Allocator` template
|
| 3981 |
+
argument cannot be deduced, implementations can introduce an
|
| 3982 |
+
intermediate base class to `basic_syncbuf` that manages its
|
| 3983 |
+
`emit_on_sync` flag. — *end note*]
|
| 3984 |
+
|
| 3985 |
+
*Returns:* `os`.
|
| 3986 |
+
|
| 3987 |
+
``` cpp
|
| 3988 |
+
template<class charT, class traits>
|
| 3989 |
+
basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
|
| 3990 |
+
```
|
| 3991 |
+
|
| 3992 |
+
*Effects:* If `os.rdbuf()` is a
|
| 3993 |
+
`basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
|
| 3994 |
+
of exposition, calls `buf->set_emit_on_sync(false)`. Otherwise this
|
| 3995 |
+
manipulator has no effect.
|
| 3996 |
+
|
| 3997 |
+
*Returns:* `os`.
|
| 3998 |
+
|
| 3999 |
+
``` cpp
|
| 4000 |
+
template<class charT, class traits>
|
| 4001 |
+
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 4002 |
+
```
|
| 4003 |
+
|
| 4004 |
+
*Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
|
| 4005 |
+
`basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
|
| 4006 |
+
of exposition, calls `buf->emit()`.
|
| 4007 |
+
|
| 4008 |
+
*Returns:* `os`.
|
| 4009 |
+
|
| 4010 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 4011 |
|
| 4012 |
``` cpp
|
| 4013 |
+
template<class Ostream, class T>
|
| 4014 |
+
Ostream&& operator<<(Ostream&& os, const T& x);
|
| 4015 |
```
|
| 4016 |
|
| 4017 |
+
*Constraints:* The expression `os << x` is well-formed when treated as
|
| 4018 |
+
an unevaluated operand and `Ostream` is publicly and unambiguously
|
| 4019 |
+
derived from `ios_base`.
|
| 4020 |
+
|
| 4021 |
*Effects:* As if by: `os << x;`
|
| 4022 |
|
| 4023 |
+
*Returns:* `std::move(os)`.
|
|
|
|
|
|
|
|
|
|
| 4024 |
|
| 4025 |
### Standard manipulators <a id="std.manip">[[std.manip]]</a>
|
| 4026 |
|
| 4027 |
The header `<iomanip>` defines several functions that support extractors
|
| 4028 |
and inserters that alter information maintained by class `ios_base` and
|
|
|
|
| 4044 |
// reset specified flags
|
| 4045 |
str.setf(ios_base::fmtflags(0), mask);
|
| 4046 |
}
|
| 4047 |
```
|
| 4048 |
|
| 4049 |
+
The expression `out << resetiosflags(mask)` has type
|
| 4050 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 4051 |
+
`in >> resetiosflags(mask)` has type `basic_istream<charT, traits>&` and
|
| 4052 |
+
value `in`.
|
| 4053 |
|
| 4054 |
``` cpp
|
| 4055 |
unspecified setiosflags(ios_base::fmtflags mask);
|
| 4056 |
```
|
| 4057 |
|
|
|
|
| 4067 |
// set specified flags
|
| 4068 |
str.setf(mask);
|
| 4069 |
}
|
| 4070 |
```
|
| 4071 |
|
| 4072 |
+
The expression `out << setiosflags(mask)` has type
|
| 4073 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 4074 |
+
`in >> setiosflags(mask)` has type `basic_istream<charT, traits>&` and
|
| 4075 |
+
value `in`.
|
| 4076 |
|
| 4077 |
``` cpp
|
| 4078 |
unspecified setbase(int base);
|
| 4079 |
```
|
| 4080 |
|
|
|
|
| 4093 |
base == 16 ? ios_base::hex :
|
| 4094 |
ios_base::fmtflags(0), ios_base::basefield);
|
| 4095 |
}
|
| 4096 |
```
|
| 4097 |
|
| 4098 |
+
The expression `out << setbase(base)` has type
|
| 4099 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 4100 |
+
`in >> setbase(base)` has type `basic_istream<charT, traits>&` and value
|
| 4101 |
+
`in`.
|
| 4102 |
|
| 4103 |
``` cpp
|
| 4104 |
unspecified setfill(char_type c);
|
| 4105 |
```
|
| 4106 |
|
|
|
|
| 4115 |
// set fill character
|
| 4116 |
str.fill(c);
|
| 4117 |
}
|
| 4118 |
```
|
| 4119 |
|
| 4120 |
+
The expression `out << setfill(c)` has type
|
| 4121 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4122 |
|
| 4123 |
``` cpp
|
| 4124 |
unspecified setprecision(int n);
|
| 4125 |
```
|
|
|
|
| 4136 |
// set precision
|
| 4137 |
str.precision(n);
|
| 4138 |
}
|
| 4139 |
```
|
| 4140 |
|
| 4141 |
+
The expression `out << setprecision(n)` has type
|
| 4142 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 4143 |
+
`in >> setprecision(n)` has type `basic_istream<charT, traits>&` and
|
| 4144 |
+
value `in`.
|
| 4145 |
|
| 4146 |
``` cpp
|
| 4147 |
unspecified setw(int n);
|
| 4148 |
```
|
| 4149 |
|
|
|
|
| 4159 |
// set width
|
| 4160 |
str.width(n);
|
| 4161 |
}
|
| 4162 |
```
|
| 4163 |
|
| 4164 |
+
The expression `out << setw(n)` has type `basic_ostream<charT, traits>&`
|
| 4165 |
+
and value `out`. The expression `in >> setw(n)` has type
|
| 4166 |
+
`basic_istream<charT, traits>&` and value `in`.
|
|
|
|
| 4167 |
|
| 4168 |
### Extended manipulators <a id="ext.manip">[[ext.manip]]</a>
|
| 4169 |
|
| 4170 |
The header `<iomanip>` defines several functions that support extractors
|
| 4171 |
and inserters that allow for the parsing and formatting of sequences and
|
|
|
|
| 4173 |
|
| 4174 |
``` cpp
|
| 4175 |
template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
|
| 4176 |
```
|
| 4177 |
|
| 4178 |
+
*Mandates:* The type `moneyT` is either `long double` or a
|
| 4179 |
+
specialization of the `basic_string` template [[strings]].
|
| 4180 |
|
| 4181 |
*Effects:* The expression `in >> get_money(mon, intl)` described below
|
| 4182 |
+
behaves as a formatted input function [[istream.formatted.reqmts]].
|
| 4183 |
|
| 4184 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4185 |
of type `basic_istream<charT, traits>` then the expression
|
| 4186 |
`in >> get_money(mon, intl)` behaves as if it called `f(in, mon, intl)`,
|
| 4187 |
where the function `f` is defined as:
|
|
|
|
| 4200 |
if (ios_base::goodbit != err)
|
| 4201 |
str.setstate(err);
|
| 4202 |
}
|
| 4203 |
```
|
| 4204 |
|
| 4205 |
+
The expression `in >> get_money(mon, intl)` has type
|
| 4206 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4207 |
|
| 4208 |
``` cpp
|
| 4209 |
template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
|
| 4210 |
```
|
| 4211 |
|
| 4212 |
+
*Mandates:* The type `moneyT` is either `long double` or a
|
| 4213 |
+
specialization of the `basic_string` template [[strings]].
|
| 4214 |
|
| 4215 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4216 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4217 |
`out << put_money(mon, intl)` behaves as a formatted output
|
| 4218 |
+
function [[ostream.formatted.reqmts]] that calls `f(out, mon, intl)`,
|
| 4219 |
where the function `f` is defined as:
|
| 4220 |
|
| 4221 |
``` cpp
|
| 4222 |
template<class charT, class traits, class moneyT>
|
| 4223 |
void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
|
|
|
|
| 4226 |
|
| 4227 |
const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
|
| 4228 |
const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);
|
| 4229 |
|
| 4230 |
if (end.failed())
|
| 4231 |
+
str.setstate(ios_base::badbit);
|
| 4232 |
}
|
| 4233 |
```
|
| 4234 |
|
| 4235 |
+
The expression `out << put_money(mon, intl)` has type
|
| 4236 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4237 |
|
| 4238 |
``` cpp
|
| 4239 |
template<class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
|
| 4240 |
```
|
| 4241 |
|
| 4242 |
+
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 4243 |
+
type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
|
| 4244 |
+
is a valid range.
|
|
|
|
| 4245 |
|
| 4246 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4247 |
of type `basic_istream<charT, traits>` then the expression
|
| 4248 |
`in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
|
| 4249 |
where the function `f` is defined as:
|
|
|
|
| 4263 |
if (err != ios_base::goodbit)
|
| 4264 |
str.setstate(err);
|
| 4265 |
}
|
| 4266 |
```
|
| 4267 |
|
| 4268 |
+
The expression `in >> get_time(tmb, fmt)` has type
|
| 4269 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4270 |
|
| 4271 |
``` cpp
|
| 4272 |
template<class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
|
| 4273 |
```
|
| 4274 |
|
| 4275 |
+
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 4276 |
+
type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
|
| 4277 |
+
is a valid range.
|
|
|
|
| 4278 |
|
| 4279 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4280 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4281 |
`out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
|
| 4282 |
where the function `f` is defined as:
|
|
|
|
| 4294 |
if (end.failed())
|
| 4295 |
str.setstate(ios_base::badbit);
|
| 4296 |
}
|
| 4297 |
```
|
| 4298 |
|
| 4299 |
+
The expression `out << put_time(tmb, fmt)` has type
|
| 4300 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4301 |
|
| 4302 |
### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
|
| 4303 |
|
| 4304 |
[*Note 1*: Quoted manipulators provide string insertion and extraction
|
|
|
|
| 4321 |
*Returns:* An object of unspecified type such that if `out` is an
|
| 4322 |
instance of `basic_ostream` with member type `char_type` the same as
|
| 4323 |
`charT` and with member type `traits_type`, which in the second and
|
| 4324 |
third forms is the same as `traits`, then the expression
|
| 4325 |
`out << quoted(s, delim, escape)` behaves as a formatted output
|
| 4326 |
+
function [[ostream.formatted.reqmts]] of `out`. This forms a character
|
| 4327 |
+
sequence `seq`, initially consisting of the following elements:
|
|
|
|
| 4328 |
|
| 4329 |
- `delim`.
|
| 4330 |
- Each character in `s`. If the character to be output is equal to
|
| 4331 |
`escape` or `delim`, as determined by `traits_type::eq`, first output
|
| 4332 |
`escape`.
|
|
|
|
| 4334 |
|
| 4335 |
Let `x` be the number of elements initially in `seq`. Then padding is
|
| 4336 |
determined for `seq` as described in [[ostream.formatted.reqmts]],
|
| 4337 |
`seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
|
| 4338 |
`n` is the larger of `out.width()` and `x`, and `out.width(0)` is
|
| 4339 |
+
called. The expression `out << quoted(s, delim, escape)` has type
|
| 4340 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4341 |
|
| 4342 |
``` cpp
|
| 4343 |
template<class charT, class traits, class Allocator>
|
| 4344 |
unspecified quoted(basic_string<charT, traits, Allocator>& s,
|
|
|
|
| 4349 |
|
| 4350 |
- If `in` is an instance of `basic_istream` with member types
|
| 4351 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4352 |
respectively, then the expression `in >> quoted(s, delim, escape)`
|
| 4353 |
behaves as if it extracts the following characters from `in` using
|
| 4354 |
+
`operator>>(basic_istream<charT, traits>&, charT&)`
|
| 4355 |
+
[[istream.extractors]] which may throw `ios_base::failure`
|
| 4356 |
+
[[ios.failure]]:
|
| 4357 |
- If the first character extracted is equal to `delim`, as determined
|
| 4358 |
by `traits_type::eq`, then:
|
| 4359 |
- Turn off the `skipws` flag.
|
| 4360 |
- `s.clear()`
|
| 4361 |
- Until an unescaped `delim` character is reached or `!in`, extract
|
|
|
|
| 4369 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4370 |
respectively, then the expression `out << quoted(s, delim, escape)`
|
| 4371 |
behaves as specified for the
|
| 4372 |
`const basic_string<charT, traits, Allocator>&` overload of the
|
| 4373 |
`quoted` function.
|
| 4374 |
+
- The expression `in >> quoted(s, delim, escape)` has type
|
| 4375 |
+
`basic_istream<charT, traits>&` and value `in`.
|
| 4376 |
+
- The expression `out << quoted(s, delim, escape)` has type
|
|
|
|
| 4377 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4378 |
|
| 4379 |
## String-based streams <a id="string.streams">[[string.streams]]</a>
|
| 4380 |
|
| 4381 |
### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
|
|
|
|
| 4428 |
using off_type = typename traits::off_type;
|
| 4429 |
using traits_type = traits;
|
| 4430 |
using allocator_type = Allocator;
|
| 4431 |
|
| 4432 |
// [stringbuf.cons], constructors
|
| 4433 |
+
basic_stringbuf() : basic_stringbuf(ios_base::in | ios_base::out) {}
|
| 4434 |
+
explicit basic_stringbuf(ios_base::openmode which);
|
| 4435 |
explicit basic_stringbuf(
|
| 4436 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 4437 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4438 |
+
explicit basic_stringbuf(const Allocator& a)
|
| 4439 |
+
: basic_stringbuf(ios_base::in | ios_base::out, a) {}
|
| 4440 |
+
basic_stringbuf(ios_base::openmode which, const Allocator& a);
|
| 4441 |
explicit basic_stringbuf(
|
| 4442 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 4443 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4444 |
+
template<class SAlloc>
|
| 4445 |
+
basic_stringbuf(
|
| 4446 |
+
const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
|
| 4447 |
+
: basic_stringbuf(s, ios_base::in | ios_base::out, a) {}
|
| 4448 |
+
template<class SAlloc>
|
| 4449 |
+
basic_stringbuf(
|
| 4450 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 4451 |
+
ios_base::openmode which, const Allocator& a);
|
| 4452 |
+
template<class SAlloc>
|
| 4453 |
+
explicit basic_stringbuf(
|
| 4454 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 4455 |
+
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4456 |
+
basic_stringbuf(const basic_stringbuf&) = delete;
|
| 4457 |
basic_stringbuf(basic_stringbuf&& rhs);
|
| 4458 |
+
basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
|
| 4459 |
|
| 4460 |
// [stringbuf.assign], assign and swap
|
| 4461 |
+
basic_stringbuf& operator=(const basic_stringbuf&) = delete;
|
| 4462 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4463 |
+
void swap(basic_stringbuf& rhs) noexcept(see below);
|
| 4464 |
+
|
| 4465 |
+
// [stringbuf.members], getters and setters
|
| 4466 |
+
allocator_type get_allocator() const noexcept;
|
| 4467 |
+
|
| 4468 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 4469 |
+
template<class SAlloc>
|
| 4470 |
+
basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
|
| 4471 |
+
basic_string<charT, traits, Allocator> str() &&;
|
| 4472 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 4473 |
|
|
|
|
|
|
|
| 4474 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4475 |
+
template<class SAlloc>
|
| 4476 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 4477 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 4478 |
|
| 4479 |
protected:
|
| 4480 |
// [stringbuf.virtuals], overridden virtual functions
|
| 4481 |
int_type underflow() override;
|
| 4482 |
int_type pbackfail(int_type c = traits::eof()) override;
|
|
|
|
| 4490 |
ios_base::openmode which
|
| 4491 |
= ios_base::in | ios_base::out) override;
|
| 4492 |
|
| 4493 |
private:
|
| 4494 |
ios_base::openmode mode; // exposition only
|
| 4495 |
+
basic_string<charT, traits, Allocator> buf; // exposition only
|
| 4496 |
+
void init_buf_ptrs(); // exposition only
|
| 4497 |
};
|
| 4498 |
|
| 4499 |
template<class charT, class traits, class Allocator>
|
| 4500 |
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4501 |
+
basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
|
| 4502 |
}
|
| 4503 |
```
|
| 4504 |
|
| 4505 |
The class `basic_stringbuf` is derived from `basic_streambuf` to
|
| 4506 |
associate possibly the input sequence and possibly the output sequence
|
| 4507 |
with a sequence of arbitrary *characters*. The sequence can be
|
| 4508 |
initialized from, or made available as, an object of class
|
| 4509 |
`basic_string`.
|
| 4510 |
|
| 4511 |
+
For the sake of exposition, the maintained data and internal pointer
|
| 4512 |
+
initialization is presented here as:
|
| 4513 |
|
| 4514 |
- `ios_base::openmode mode`, has `in` set if the input sequence can be
|
| 4515 |
read, and `out` set if the output sequence can be written.
|
| 4516 |
+
- `basic_string<charT, traits, Allocator> buf` contains the underlying
|
| 4517 |
+
character sequence.
|
| 4518 |
+
- `init_buf_ptrs()` sets the base class’ get area [[streambuf.get.area]]
|
| 4519 |
+
and put area [[streambuf.put.area]] pointers after initializing,
|
| 4520 |
+
moving from, or assigning to `buf` accordingly.
|
| 4521 |
|
| 4522 |
+
#### Constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
|
| 4523 |
|
| 4524 |
``` cpp
|
| 4525 |
+
explicit basic_stringbuf(ios_base::openmode which);
|
|
|
|
| 4526 |
```
|
| 4527 |
|
| 4528 |
+
*Effects:* Initializes the base class with `basic_streambuf()`
|
| 4529 |
+
[[streambuf.cons]], and `mode` with `which`. It is
|
| 4530 |
+
*implementation-defined* whether the sequence pointers (`eback()`,
|
| 4531 |
+
`gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) are initialized to
|
| 4532 |
+
null pointers.
|
| 4533 |
|
| 4534 |
+
*Ensures:* `str().empty()` is `true`.
|
| 4535 |
|
| 4536 |
``` cpp
|
| 4537 |
explicit basic_stringbuf(
|
| 4538 |
const basic_string<charT, traits, Allocator>& s,
|
| 4539 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4540 |
```
|
| 4541 |
|
| 4542 |
+
*Effects:* Initializes the base class with `basic_streambuf()`
|
| 4543 |
+
[[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
|
| 4544 |
+
`init_buf_ptrs()`.
|
| 4545 |
+
|
| 4546 |
+
``` cpp
|
| 4547 |
+
basic_stringbuf(ios_base::openmode which, const Allocator &a);
|
| 4548 |
+
```
|
| 4549 |
+
|
| 4550 |
+
*Effects:* Initializes the base class with `basic_streambuf()`
|
| 4551 |
+
[[streambuf.cons]], `mode` with `which`, and `buf` with `a`, then calls
|
| 4552 |
+
`init_buf_ptrs()`.
|
| 4553 |
+
|
| 4554 |
+
*Ensures:* `str().empty()` is `true`.
|
| 4555 |
+
|
| 4556 |
+
``` cpp
|
| 4557 |
+
explicit basic_stringbuf(
|
| 4558 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 4559 |
+
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4560 |
+
```
|
| 4561 |
+
|
| 4562 |
+
*Effects:* Initializes the base class with `basic_streambuf()`
|
| 4563 |
+
[[streambuf.cons]], `mode` with `which`, and `buf` with `std::move(s)`,
|
| 4564 |
+
then calls `init_buf_ptrs()`.
|
| 4565 |
+
|
| 4566 |
+
``` cpp
|
| 4567 |
+
template<class SAlloc>
|
| 4568 |
+
basic_stringbuf(
|
| 4569 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 4570 |
+
ios_base::openmode which, const Allocator &a);
|
| 4571 |
+
```
|
| 4572 |
+
|
| 4573 |
+
*Effects:* Initializes the base class with `basic_streambuf()`
|
| 4574 |
+
[[streambuf.cons]], `mode` with `which`, and `buf` with `{s,a}`, then
|
| 4575 |
+
calls `init_buf_ptrs()`.
|
| 4576 |
+
|
| 4577 |
+
``` cpp
|
| 4578 |
+
template<class SAlloc>
|
| 4579 |
+
explicit basic_stringbuf(
|
| 4580 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 4581 |
+
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4582 |
+
```
|
| 4583 |
+
|
| 4584 |
+
*Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
|
| 4585 |
+
|
| 4586 |
+
*Effects:* Initializes the base class with `basic_streambuf()`
|
| 4587 |
+
[[streambuf.cons]], `mode` with `which`, and `buf` with `s`, then calls
|
| 4588 |
+
`init_buf_ptrs()`.
|
| 4589 |
|
| 4590 |
``` cpp
|
| 4591 |
basic_stringbuf(basic_stringbuf&& rhs);
|
| 4592 |
+
basic_stringbuf(basic_stringbuf&& rhs, const Allocator& a);
|
| 4593 |
```
|
| 4594 |
|
| 4595 |
+
*Effects:* Copy constructs the base class from `rhs` and initializes
|
| 4596 |
+
`mode` with `rhs.mode`. In the first form `buf` is initialized from
|
| 4597 |
+
`std::move(rhs).str()`. In the second form `buf` is initialized from
|
| 4598 |
+
`{std::move(rhs).str(), a}`. It is *implementation-defined* whether the
|
| 4599 |
+
sequence pointers in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`,
|
| 4600 |
+
`pptr()`, `epptr()`) obtain the values which `rhs` had.
|
| 4601 |
|
| 4602 |
+
*Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
|
| 4603 |
+
construction and let `rhs_a` refer to the state of `rhs` just after this
|
| 4604 |
+
construction.
|
| 4605 |
|
| 4606 |
- `str() == rhs_p.str()`
|
| 4607 |
- `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
|
| 4608 |
- `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
|
| 4609 |
- `pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()`
|
|
|
|
| 4612 |
- `if (gptr()) gptr() != rhs_a.gptr()`
|
| 4613 |
- `if (egptr()) egptr() != rhs_a.egptr()`
|
| 4614 |
- `if (pbase()) pbase() != rhs_a.pbase()`
|
| 4615 |
- `if (pptr()) pptr() != rhs_a.pptr()`
|
| 4616 |
- `if (epptr()) epptr() != rhs_a.epptr()`
|
| 4617 |
+
- `getloc() == rhs_p.getloc()`
|
| 4618 |
+
- `rhs` is empty but usable, as if `std::move(rhs).str()` was called.
|
| 4619 |
|
| 4620 |
+
#### Assignment and swap <a id="stringbuf.assign">[[stringbuf.assign]]</a>
|
| 4621 |
|
| 4622 |
``` cpp
|
| 4623 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4624 |
```
|
| 4625 |
|
|
|
|
| 4628 |
(see [[stringbuf.cons]]).
|
| 4629 |
|
| 4630 |
*Returns:* `*this`.
|
| 4631 |
|
| 4632 |
``` cpp
|
| 4633 |
+
void swap(basic_stringbuf& rhs) noexcept(see below);
|
| 4634 |
```
|
| 4635 |
|
| 4636 |
+
*Preconditions:*
|
| 4637 |
+
`allocator_traits<Allocator>::propagate_on_container_swap::value` is
|
| 4638 |
+
`true` or `get_allocator() == s.get_allocator()` is `true`.
|
| 4639 |
+
|
| 4640 |
*Effects:* Exchanges the state of `*this` and `rhs`.
|
| 4641 |
|
| 4642 |
+
*Remarks:* The expression inside `noexcept` is equivalent to:
|
| 4643 |
+
`allocator_traits<Allocator>::propagate_on_container_swap::value ||`
|
| 4644 |
+
`allocator_traits<Allocator>::is_always_equal::value`.
|
| 4645 |
+
|
| 4646 |
``` cpp
|
| 4647 |
template<class charT, class traits, class Allocator>
|
| 4648 |
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4649 |
+
basic_stringbuf<charT, traits, Allocator>& y) noexcept(noexcept(x.swap(y)));
|
| 4650 |
```
|
| 4651 |
|
| 4652 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 4653 |
|
| 4654 |
#### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
|
| 4655 |
|
| 4656 |
+
The member functions getting the underlying character sequence all refer
|
| 4657 |
+
to a `high_mark` value, where `high_mark` represents the position one
|
| 4658 |
+
past the highest initialized character in the buffer. Characters can be
|
| 4659 |
+
initialized by writing to the stream, by constructing the
|
| 4660 |
+
`basic_stringbuf` passing a `basic_string` argument, or by calling one
|
| 4661 |
+
of the `str` member functions passing a `basic_string` as an argument.
|
| 4662 |
+
In the latter case, all characters initialized prior to the call are now
|
| 4663 |
+
considered uninitialized (except for those characters re-initialized by
|
| 4664 |
+
the new `basic_string`).
|
| 4665 |
+
|
| 4666 |
+
``` cpp
|
| 4667 |
+
void init_buf_ptrs(); // exposition only
|
| 4668 |
+
```
|
| 4669 |
+
|
| 4670 |
+
*Effects:* Initializes the input and output sequences from `buf`
|
| 4671 |
+
according to `mode`.
|
| 4672 |
+
|
| 4673 |
+
*Ensures:*
|
| 4674 |
+
|
| 4675 |
+
- If `ios_base::out` is set in `mode`, `pbase()` points to `buf.front()`
|
| 4676 |
+
and `epptr() >= pbase() + buf.size()` is `true`;
|
| 4677 |
+
- in addition, if `ios_base::ate` is set in `mode`,
|
| 4678 |
+
`pptr() == pbase() + buf.size()` is `true`,
|
| 4679 |
+
- otherwise `pptr() == pbase()` is `true`.
|
| 4680 |
+
- If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
|
| 4681 |
+
and `(gptr() == eback() && egptr() == eback() + buf.size())` is
|
| 4682 |
+
`true`.
|
| 4683 |
+
|
| 4684 |
+
[*Note 1*: For efficiency reasons, stream buffer operations might
|
| 4685 |
+
violate invariants of `buf` while it is held encapsulated in the
|
| 4686 |
+
`basic_stringbuf`, e.g., by writing to characters in the range
|
| 4687 |
+
\[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
|
| 4688 |
+
operations retrieving a `basic_string` from `buf` ensure that the
|
| 4689 |
+
`basic_string` invariants hold on the returned value. — *end note*]
|
| 4690 |
+
|
| 4691 |
+
``` cpp
|
| 4692 |
+
allocator_type get_allocator() const noexcept;
|
| 4693 |
+
```
|
| 4694 |
+
|
| 4695 |
+
*Returns:* `buf.get_allocator()`.
|
| 4696 |
+
|
| 4697 |
+
``` cpp
|
| 4698 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 4699 |
+
```
|
| 4700 |
+
|
| 4701 |
+
*Effects:* Equivalent to:
|
| 4702 |
+
|
| 4703 |
+
``` cpp
|
| 4704 |
+
return basic_string<charT, traits, Allocator>(view(), get_allocator());
|
| 4705 |
+
```
|
| 4706 |
+
|
| 4707 |
``` cpp
|
| 4708 |
+
template<class SAlloc>
|
| 4709 |
+
basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
|
| 4710 |
+
```
|
| 4711 |
+
|
| 4712 |
+
*Constraints:* `SAlloc` is a type that qualifies as an
|
| 4713 |
+
allocator [[container.requirements.general]].
|
| 4714 |
+
|
| 4715 |
+
*Effects:* Equivalent to:
|
| 4716 |
+
|
| 4717 |
+
``` cpp
|
| 4718 |
+
return basic_string<charT, traits, SAlloc>(view(), sa);
|
| 4719 |
+
```
|
| 4720 |
+
|
| 4721 |
+
``` cpp
|
| 4722 |
+
basic_string<charT, traits, Allocator> str() &&;
|
| 4723 |
+
```
|
| 4724 |
+
|
| 4725 |
+
*Returns:* A `basic_string<charT, traits, Allocator>` object move
|
| 4726 |
+
constructed from the `basic_stringbuf`’s underlying character sequence
|
| 4727 |
+
in `buf`. This can be achieved by first adjusting `buf` to have the same
|
| 4728 |
+
content as `view()`.
|
| 4729 |
+
|
| 4730 |
+
*Ensures:* The underlying character sequence `buf` is empty and
|
| 4731 |
+
`pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
|
| 4732 |
+
initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
|
| 4733 |
+
|
| 4734 |
+
``` cpp
|
| 4735 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 4736 |
+
```
|
| 4737 |
+
|
| 4738 |
+
Let `sv` be `basic_string_view<charT, traits>`.
|
| 4739 |
+
|
| 4740 |
+
*Returns:* A `sv` object referring to the `basic_stringbuf`’s underlying
|
| 4741 |
+
character sequence in `buf`:
|
| 4742 |
+
|
| 4743 |
+
- If `ios_base::out` is set in `mode`, then
|
| 4744 |
+
`sv(pbase(), high_mark-pbase())` is returned.
|
| 4745 |
+
- Otherwise, if `ios_base::in` is set in `mode`, then
|
| 4746 |
+
`sv(eback(), egptr()-eback())` is returned.
|
| 4747 |
+
- Otherwise, `sv()` is returned.
|
| 4748 |
+
|
| 4749 |
+
[*Note 2*: Using the returned `sv` object after destruction or
|
| 4750 |
+
invalidation of the character sequence underlying `*this` is undefined
|
| 4751 |
+
behavior, unless `sv.empty()` is `true`. — *end note*]
|
| 4752 |
|
| 4753 |
``` cpp
|
| 4754 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4755 |
```
|
| 4756 |
|
| 4757 |
+
*Effects:* Equivalent to:
|
| 4758 |
+
|
| 4759 |
+
``` cpp
|
| 4760 |
+
buf = s;
|
| 4761 |
+
init_buf_ptrs();
|
| 4762 |
+
```
|
| 4763 |
+
|
| 4764 |
+
``` cpp
|
| 4765 |
+
template<class SAlloc>
|
| 4766 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 4767 |
+
```
|
| 4768 |
+
|
| 4769 |
+
*Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
|
| 4770 |
+
|
| 4771 |
+
*Effects:* Equivalent to:
|
| 4772 |
+
|
| 4773 |
+
``` cpp
|
| 4774 |
+
buf = s;
|
| 4775 |
+
init_buf_ptrs();
|
| 4776 |
+
```
|
| 4777 |
+
|
| 4778 |
+
``` cpp
|
| 4779 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 4780 |
+
```
|
| 4781 |
+
|
| 4782 |
+
*Effects:* Equivalent to:
|
| 4783 |
+
|
| 4784 |
+
``` cpp
|
| 4785 |
+
buf = std::move(s);
|
| 4786 |
+
init_buf_ptrs();
|
| 4787 |
+
```
|
| 4788 |
|
| 4789 |
#### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
|
| 4790 |
|
| 4791 |
``` cpp
|
| 4792 |
int_type underflow() override;
|
|
|
|
| 4813 |
`ios_base::out` is nonzero, assigns `c` to `*``gptr()`. Returns: `c`.
|
| 4814 |
- If `traits::eq_int_type(c, traits::eof())` returns `true` and if the
|
| 4815 |
input sequence has a putback position available, assigns `gptr() - 1`
|
| 4816 |
to `gptr()`. Returns: `traits::not_eof(c)`.
|
| 4817 |
|
| 4818 |
+
*Returns:* As specified above, or `traits::eof()` to indicate failure.
|
| 4819 |
|
| 4820 |
*Remarks:* If the function can succeed in more than one of these ways,
|
| 4821 |
it is unspecified which way is chosen.
|
| 4822 |
|
| 4823 |
``` cpp
|
|
|
|
| 4836 |
`traits::eof()`.
|
| 4837 |
|
| 4838 |
*Remarks:* The function can alter the number of write positions
|
| 4839 |
available as a result of any call.
|
| 4840 |
|
| 4841 |
+
*Returns:* As specified above, or `traits::eof()` to indicate failure.
|
| 4842 |
|
| 4843 |
+
The function can make a write position available only if `ios_base::out`
|
| 4844 |
+
is set in `mode`. To make a write position available, the function
|
| 4845 |
+
reallocates (or initially allocates) an array object with a sufficient
|
| 4846 |
+
number of elements to hold the current array object (if any), plus at
|
| 4847 |
+
least one additional write position. If `ios_base::in` is set in `mode`,
|
| 4848 |
+
the function alters the read end pointer `egptr()` to point just past
|
| 4849 |
+
the new write position.
|
| 4850 |
|
| 4851 |
``` cpp
|
| 4852 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 4853 |
ios_base::openmode which
|
| 4854 |
= ios_base::in | ios_base::out) override;
|
| 4855 |
```
|
| 4856 |
|
| 4857 |
*Effects:* Alters the stream position within one of the controlled
|
| 4858 |
+
sequences, if possible, as indicated in [[stringbuf.seekoff.pos]].
|
|
|
|
| 4859 |
|
| 4860 |
+
**Table: `seekoff` positioning** <a id="stringbuf.seekoff.pos">[stringbuf.seekoff.pos]</a>
|
| 4861 |
|
| 4862 |
| Conditions | Result |
|
| 4863 |
+
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
|
| 4864 |
+
| `ios_base::in` is set in `which` | positions the input sequence |
|
| 4865 |
+
| `ios_base::out` is set in `which` | positions the output sequence |
|
| 4866 |
+
| both `ios_base::in` and `ios_base::out` are set in `which` and either<br> `way == ios_base::beg` or<br> `way == ios_base::end` | positions both the input and the output sequences |
|
| 4867 |
| Otherwise | the positioning operation fails. |
|
| 4868 |
|
| 4869 |
|
| 4870 |
+
For a sequence to be positioned, the function determines `newoff` as
|
| 4871 |
+
indicated in [[stringbuf.seekoff.newoff]]. If the sequence’s next
|
| 4872 |
+
pointer (either `gptr()` or `pptr()`) is a null pointer and `newoff` is
|
| 4873 |
+
nonzero, the positioning operation fails.
|
| 4874 |
|
| 4875 |
+
**Table: `newoff` values** <a id="stringbuf.seekoff.newoff">[stringbuf.seekoff.newoff]</a>
|
| 4876 |
|
| 4877 |
| Condition | `newoff` Value |
|
| 4878 |
| ---------------------- | ----------------------------------------------------------------------- |
|
| 4879 |
| `way == ios_base::beg` | 0 |
|
| 4880 |
| `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
|
| 4881 |
| `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
|
| 4882 |
|
| 4883 |
|
| 4884 |
If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
|
| 4885 |
+
character [[stringbuf.members]], the positioning operation fails.
|
| 4886 |
Otherwise, the function assigns `xbeg + newoff + off` to the next
|
| 4887 |
pointer `xnext`.
|
| 4888 |
|
| 4889 |
*Returns:* `pos_type(newoff)`, constructed from the resultant offset
|
| 4890 |
`newoff` (of type `off_type`), that stores the resultant stream
|
|
|
|
| 4926 |
using off_type = typename traits::off_type;
|
| 4927 |
using traits_type = traits;
|
| 4928 |
using allocator_type = Allocator;
|
| 4929 |
|
| 4930 |
// [istringstream.cons], constructors
|
| 4931 |
+
basic_istringstream() : basic_istringstream(ios_base::in) {}
|
| 4932 |
+
explicit basic_istringstream(ios_base::openmode which);
|
| 4933 |
explicit basic_istringstream(
|
| 4934 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 4935 |
ios_base::openmode which = ios_base::in);
|
| 4936 |
+
basic_istringstream(ios_base::openmode which, const Allocator& a);
|
| 4937 |
explicit basic_istringstream(
|
| 4938 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 4939 |
ios_base::openmode which = ios_base::in);
|
| 4940 |
+
template<class SAlloc>
|
| 4941 |
+
basic_istringstream(
|
| 4942 |
+
const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
|
| 4943 |
+
: basic_istringstream(s, ios_base::in, a) {}
|
| 4944 |
+
template<class SAlloc>
|
| 4945 |
+
basic_istringstream(
|
| 4946 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 4947 |
+
ios_base::openmode which, const Allocator& a);
|
| 4948 |
+
template<class SAlloc>
|
| 4949 |
+
explicit basic_istringstream(
|
| 4950 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 4951 |
+
ios_base::openmode which = ios_base::in);
|
| 4952 |
+
basic_istringstream(const basic_istringstream&) = delete;
|
| 4953 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4954 |
|
| 4955 |
// [istringstream.assign], assign and swap
|
| 4956 |
+
basic_istringstream& operator=(const basic_istringstream&) = delete;
|
| 4957 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
| 4958 |
void swap(basic_istringstream& rhs);
|
| 4959 |
|
| 4960 |
// [istringstream.members], members
|
| 4961 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4962 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 4963 |
+
template<class SAlloc>
|
| 4964 |
+
basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
|
| 4965 |
+
basic_string<charT, traits, Allocator> str() &&;
|
| 4966 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 4967 |
|
|
|
|
| 4968 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4969 |
+
template<class SAlloc>
|
| 4970 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 4971 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 4972 |
+
|
| 4973 |
private:
|
| 4974 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 4975 |
};
|
| 4976 |
|
| 4977 |
template<class charT, class traits, class Allocator>
|
|
|
|
| 4986 |
associated storage. For the sake of exposition, the maintained data is
|
| 4987 |
presented here as:
|
| 4988 |
|
| 4989 |
- `sb`, the `stringbuf` object.
|
| 4990 |
|
| 4991 |
+
#### Constructors <a id="istringstream.cons">[[istringstream.cons]]</a>
|
| 4992 |
|
| 4993 |
``` cpp
|
| 4994 |
+
explicit basic_istringstream(ios_base::openmode which);
|
| 4995 |
```
|
| 4996 |
|
| 4997 |
+
*Effects:* Initializes the base class with
|
| 4998 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 4999 |
+
`basic_stringbuf<charT, traits, Allocator>(which | ios_base::in)`
|
| 5000 |
+
[[stringbuf.cons]].
|
| 5001 |
|
| 5002 |
``` cpp
|
| 5003 |
explicit basic_istringstream(
|
| 5004 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 5005 |
ios_base::openmode which = ios_base::in);
|
| 5006 |
```
|
| 5007 |
|
| 5008 |
+
*Effects:* Initializes the base class with
|
| 5009 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5010 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`([[stringbuf.cons]]).
|
| 5011 |
+
|
| 5012 |
+
``` cpp
|
| 5013 |
+
basic_istringstream(ios_base::openmode which, const Allocator& a);
|
| 5014 |
+
```
|
| 5015 |
+
|
| 5016 |
+
*Effects:* Initializes the base class with
|
| 5017 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5018 |
+
`basic_stringbuf<charT, traits, Allocator>(which | ios_base::in, a)`
|
| 5019 |
+
[[stringbuf.cons]].
|
| 5020 |
+
|
| 5021 |
+
``` cpp
|
| 5022 |
+
explicit basic_istringstream(
|
| 5023 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 5024 |
+
ios_base::openmode which = ios_base::in);
|
| 5025 |
+
```
|
| 5026 |
+
|
| 5027 |
+
*Effects:* Initializes the base class with
|
| 5028 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5029 |
+
`basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::in)`
|
| 5030 |
+
[[stringbuf.cons]].
|
| 5031 |
+
|
| 5032 |
+
``` cpp
|
| 5033 |
+
template<class SAlloc>
|
| 5034 |
+
basic_istringstream(
|
| 5035 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5036 |
+
ios_base::openmode which, const Allocator& a);
|
| 5037 |
+
```
|
| 5038 |
+
|
| 5039 |
+
*Effects:* Initializes the base class with
|
| 5040 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5041 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in, a)`([[stringbuf.cons]]).
|
| 5042 |
+
|
| 5043 |
+
``` cpp
|
| 5044 |
+
template<class SAlloc>
|
| 5045 |
+
explicit basic_istringstream(
|
| 5046 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5047 |
+
ios_base::openmode which = ios_base::in);
|
| 5048 |
+
```
|
| 5049 |
+
|
| 5050 |
+
*Effects:* Initializes the base class with
|
| 5051 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream]] and `sb` with
|
| 5052 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::in)`
|
| 5053 |
+
[[stringbuf.cons]].
|
| 5054 |
|
| 5055 |
``` cpp
|
| 5056 |
basic_istringstream(basic_istringstream&& rhs);
|
| 5057 |
```
|
| 5058 |
|
| 5059 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 5060 |
by move constructing the base class, and the contained
|
| 5061 |
+
`basic_stringbuf`. Then calls
|
| 5062 |
+
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5063 |
+
contained `basic_stringbuf`.
|
| 5064 |
|
| 5065 |
+
#### Assignment and swap <a id="istringstream.assign">[[istringstream.assign]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5066 |
|
| 5067 |
``` cpp
|
| 5068 |
void swap(basic_istringstream& rhs);
|
| 5069 |
```
|
| 5070 |
|
| 5071 |
+
*Effects:* Equivalent to:
|
| 5072 |
+
|
| 5073 |
+
``` cpp
|
| 5074 |
+
basic_istream<charT, traits>::swap(rhs);
|
| 5075 |
+
sb.swap(rhs.sb);
|
| 5076 |
+
```
|
| 5077 |
|
| 5078 |
``` cpp
|
| 5079 |
template<class charT, class traits, class Allocator>
|
| 5080 |
void swap(basic_istringstream<charT, traits, Allocator>& x,
|
| 5081 |
basic_istringstream<charT, traits, Allocator>& y);
|
| 5082 |
```
|
| 5083 |
|
| 5084 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 5085 |
|
| 5086 |
#### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
|
| 5087 |
|
| 5088 |
``` cpp
|
| 5089 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5090 |
```
|
| 5091 |
|
| 5092 |
*Returns:*
|
| 5093 |
+
`const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
|
| 5094 |
|
| 5095 |
``` cpp
|
| 5096 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 5097 |
```
|
| 5098 |
|
| 5099 |
+
*Effects:* Equivalent to: `return rdbuf()->str();`
|
| 5100 |
+
|
| 5101 |
+
``` cpp
|
| 5102 |
+
template<class SAlloc>
|
| 5103 |
+
basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
|
| 5104 |
+
```
|
| 5105 |
+
|
| 5106 |
+
*Effects:* Equivalent to: `return rdbuf()->str(sa);`
|
| 5107 |
+
|
| 5108 |
+
``` cpp
|
| 5109 |
+
basic_string<charT,traits,Allocator> str() &&;
|
| 5110 |
+
```
|
| 5111 |
+
|
| 5112 |
+
*Effects:* Equivalent to: `return std::move(*rdbuf()).str();`
|
| 5113 |
+
|
| 5114 |
+
``` cpp
|
| 5115 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 5116 |
+
```
|
| 5117 |
+
|
| 5118 |
+
*Effects:* Equivalent to: `return rdbuf()->view();`
|
| 5119 |
|
| 5120 |
``` cpp
|
| 5121 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 5122 |
```
|
| 5123 |
|
| 5124 |
+
*Effects:* Equivalent to: `rdbuf()->str(s);`
|
| 5125 |
+
|
| 5126 |
+
``` cpp
|
| 5127 |
+
template<class SAlloc>
|
| 5128 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 5129 |
+
```
|
| 5130 |
+
|
| 5131 |
+
*Effects:* Equivalent to: `rdbuf()->str(s);`
|
| 5132 |
+
|
| 5133 |
+
``` cpp
|
| 5134 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5135 |
+
```
|
| 5136 |
+
|
| 5137 |
+
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5138 |
|
| 5139 |
### Class template `basic_ostringstream` <a id="ostringstream">[[ostringstream]]</a>
|
| 5140 |
|
| 5141 |
``` cpp
|
| 5142 |
namespace std {
|
|
|
|
| 5150 |
using off_type = typename traits::off_type;
|
| 5151 |
using traits_type = traits;
|
| 5152 |
using allocator_type = Allocator;
|
| 5153 |
|
| 5154 |
// [ostringstream.cons], constructors
|
| 5155 |
+
basic_ostringstream() : basic_ostringstream(ios_base::out) {}
|
| 5156 |
+
explicit basic_ostringstream(ios_base::openmode which);
|
| 5157 |
explicit basic_ostringstream(
|
| 5158 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 5159 |
ios_base::openmode which = ios_base::out);
|
| 5160 |
+
basic_ostringstream(ios_base::openmode which, const Allocator& a);
|
| 5161 |
explicit basic_ostringstream(
|
| 5162 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 5163 |
ios_base::openmode which = ios_base::out);
|
| 5164 |
+
template<class SAlloc>
|
| 5165 |
+
basic_ostringstream(
|
| 5166 |
+
const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
|
| 5167 |
+
: basic_ostringstream(s, ios_base::out, a) {}
|
| 5168 |
+
template<class SAlloc>
|
| 5169 |
+
basic_ostringstream(
|
| 5170 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5171 |
+
ios_base::openmode which, const Allocator& a);
|
| 5172 |
+
template<class SAlloc>
|
| 5173 |
+
explicit basic_ostringstream(
|
| 5174 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5175 |
+
ios_base::openmode which = ios_base::out);
|
| 5176 |
+
basic_ostringstream(const basic_ostringstream&) = delete;
|
| 5177 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 5178 |
|
| 5179 |
// [ostringstream.assign], assign and swap
|
| 5180 |
+
basic_ostringstream& operator=(const basic_ostringstream&) = delete;
|
| 5181 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
| 5182 |
void swap(basic_ostringstream& rhs);
|
| 5183 |
|
| 5184 |
// [ostringstream.members], members
|
| 5185 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5186 |
|
| 5187 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 5188 |
+
template<class SAlloc>
|
| 5189 |
+
basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
|
| 5190 |
+
basic_string<charT, traits, Allocator> str() &&;
|
| 5191 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 5192 |
+
|
| 5193 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 5194 |
+
template<class SAlloc>
|
| 5195 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 5196 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5197 |
+
|
| 5198 |
private:
|
| 5199 |
basic_stringbuf<charT, traits, Allocator> sb; // exposition only
|
| 5200 |
};
|
| 5201 |
|
| 5202 |
template<class charT, class traits, class Allocator>
|
|
|
|
| 5210 |
uses a `basic_stringbuf` object to control the associated storage. For
|
| 5211 |
the sake of exposition, the maintained data is presented here as:
|
| 5212 |
|
| 5213 |
- `sb`, the `stringbuf` object.
|
| 5214 |
|
| 5215 |
+
#### Constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
|
| 5216 |
+
|
| 5217 |
+
``` cpp
|
| 5218 |
+
explicit basic_ostringstream(ios_base::openmode which);
|
| 5219 |
+
```
|
| 5220 |
+
|
| 5221 |
+
*Effects:* Initializes the base class with
|
| 5222 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5223 |
+
`basic_stringbuf<charT, traits, Allocator>(which | ios_base::out)`
|
| 5224 |
+
[[stringbuf.cons]].
|
| 5225 |
|
| 5226 |
``` cpp
|
| 5227 |
explicit basic_ostringstream(
|
| 5228 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 5229 |
ios_base::openmode which = ios_base::out);
|
| 5230 |
```
|
| 5231 |
|
| 5232 |
+
*Effects:* Initializes the base class with
|
| 5233 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5234 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`([[stringbuf.cons]]).
|
| 5235 |
+
|
| 5236 |
+
``` cpp
|
| 5237 |
+
basic_ostringstream(ios_base::openmode which, const Allocator& a);
|
| 5238 |
+
```
|
| 5239 |
+
|
| 5240 |
+
*Effects:* Initializes the base class with
|
| 5241 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5242 |
+
`basic_stringbuf<charT, traits, Allocator>(which | ios_base::out, a)`([[stringbuf.cons]]).
|
| 5243 |
|
| 5244 |
``` cpp
|
| 5245 |
explicit basic_ostringstream(
|
| 5246 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 5247 |
ios_base::openmode which = ios_base::out);
|
| 5248 |
```
|
| 5249 |
|
| 5250 |
+
*Effects:* Initializes the base class with
|
| 5251 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5252 |
+
`basic_stringbuf<charT, traits, Allocator>(std::move(s), which | ios_base::out)`
|
| 5253 |
+
[[stringbuf.cons]].
|
| 5254 |
+
|
| 5255 |
+
``` cpp
|
| 5256 |
+
template<class SAlloc>
|
| 5257 |
+
basic_ostringstream(
|
| 5258 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5259 |
+
ios_base::openmode which, const Allocator& a);
|
| 5260 |
+
```
|
| 5261 |
+
|
| 5262 |
+
*Effects:* Initializes the base class with
|
| 5263 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5264 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out, a)`([[stringbuf.cons]]).
|
| 5265 |
+
|
| 5266 |
+
``` cpp
|
| 5267 |
+
template<class SAlloc>
|
| 5268 |
+
explicit basic_ostringstream(
|
| 5269 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5270 |
+
ios_base::openmode which = ios_base::out);
|
| 5271 |
+
```
|
| 5272 |
+
|
| 5273 |
+
*Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
|
| 5274 |
+
|
| 5275 |
+
*Effects:* Initializes the base class with
|
| 5276 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream]] and `sb` with
|
| 5277 |
+
`basic_stringbuf<charT, traits, Allocator>(s, which | ios_base::out)`([[stringbuf.cons]]).
|
| 5278 |
|
| 5279 |
``` cpp
|
| 5280 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 5281 |
```
|
| 5282 |
|
| 5283 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 5284 |
by move constructing the base class, and the contained
|
| 5285 |
+
`basic_stringbuf`. Then calls
|
| 5286 |
+
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5287 |
+
contained `basic_stringbuf`.
|
| 5288 |
|
| 5289 |
+
#### Assignment and swap <a id="ostringstream.assign">[[ostringstream.assign]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5290 |
|
| 5291 |
``` cpp
|
| 5292 |
void swap(basic_ostringstream& rhs);
|
| 5293 |
```
|
| 5294 |
|
| 5295 |
+
*Effects:* Equivalent to:
|
| 5296 |
+
|
| 5297 |
+
``` cpp
|
| 5298 |
+
basic_ostream<charT, traits>::swap(rhs);
|
| 5299 |
+
sb.swap(rhs.sb);
|
| 5300 |
+
```
|
| 5301 |
|
| 5302 |
``` cpp
|
| 5303 |
template<class charT, class traits, class Allocator>
|
| 5304 |
void swap(basic_ostringstream<charT, traits, Allocator>& x,
|
| 5305 |
basic_ostringstream<charT, traits, Allocator>& y);
|
| 5306 |
```
|
| 5307 |
|
| 5308 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 5309 |
|
| 5310 |
#### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
|
| 5311 |
|
| 5312 |
``` cpp
|
| 5313 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5314 |
```
|
| 5315 |
|
| 5316 |
*Returns:*
|
| 5317 |
+
`const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
|
| 5318 |
|
| 5319 |
``` cpp
|
| 5320 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 5321 |
```
|
| 5322 |
|
| 5323 |
+
*Effects:* Equivalent to: `return rdbuf()->str();`
|
| 5324 |
+
|
| 5325 |
+
``` cpp
|
| 5326 |
+
template<class SAlloc>
|
| 5327 |
+
basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
|
| 5328 |
+
```
|
| 5329 |
+
|
| 5330 |
+
*Effects:* Equivalent to: `return rdbuf()->str(sa);`
|
| 5331 |
+
|
| 5332 |
+
``` cpp
|
| 5333 |
+
basic_string<charT,traits,Allocator> str() &&;
|
| 5334 |
+
```
|
| 5335 |
+
|
| 5336 |
+
*Effects:* Equivalent to: `return std::move(*rdbuf()).str();`
|
| 5337 |
+
|
| 5338 |
+
``` cpp
|
| 5339 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 5340 |
+
```
|
| 5341 |
+
|
| 5342 |
+
*Effects:* Equivalent to: `return rdbuf()->view();`
|
| 5343 |
|
| 5344 |
``` cpp
|
| 5345 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 5346 |
```
|
| 5347 |
|
| 5348 |
+
*Effects:* Equivalent to: `rdbuf()->str(s);`
|
| 5349 |
+
|
| 5350 |
+
``` cpp
|
| 5351 |
+
template<class SAlloc>
|
| 5352 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 5353 |
+
```
|
| 5354 |
+
|
| 5355 |
+
*Effects:* Equivalent to: `rdbuf()->str(s);`
|
| 5356 |
+
|
| 5357 |
+
``` cpp
|
| 5358 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5359 |
+
```
|
| 5360 |
+
|
| 5361 |
+
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5362 |
|
| 5363 |
### Class template `basic_stringstream` <a id="stringstream">[[stringstream]]</a>
|
| 5364 |
|
| 5365 |
``` cpp
|
| 5366 |
namespace std {
|
|
|
|
| 5374 |
using off_type = typename traits::off_type;
|
| 5375 |
using traits_type = traits;
|
| 5376 |
using allocator_type = Allocator;
|
| 5377 |
|
| 5378 |
// [stringstream.cons], constructors
|
| 5379 |
+
basic_stringstream() : basic_stringstream(ios_base::out | ios_base::in) {}
|
| 5380 |
+
explicit basic_stringstream(ios_base::openmode which);
|
| 5381 |
explicit basic_stringstream(
|
| 5382 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 5383 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5384 |
+
basic_stringstream(ios_base::openmode which, const Allocator& a);
|
| 5385 |
explicit basic_stringstream(
|
| 5386 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 5387 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5388 |
+
template<class SAlloc>
|
| 5389 |
+
basic_stringstream(
|
| 5390 |
+
const basic_string<charT, traits, SAlloc>& s, const Allocator& a)
|
| 5391 |
+
: basic_stringstream(s, ios_base::out | ios_base::in, a) {}
|
| 5392 |
+
template<class SAlloc>
|
| 5393 |
+
basic_stringstream(
|
| 5394 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5395 |
+
ios_base::openmode which, const Allocator& a);
|
| 5396 |
+
template<class SAlloc>
|
| 5397 |
+
explicit basic_stringstream(
|
| 5398 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5399 |
+
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5400 |
+
basic_stringstream(const basic_stringstream&) = delete;
|
| 5401 |
basic_stringstream(basic_stringstream&& rhs);
|
| 5402 |
|
| 5403 |
// [stringstream.assign], assign and swap
|
| 5404 |
+
basic_stringstream& operator=(const basic_stringstream&) = delete;
|
| 5405 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
| 5406 |
void swap(basic_stringstream& rhs);
|
| 5407 |
|
| 5408 |
// [stringstream.members], members
|
| 5409 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5410 |
+
|
| 5411 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 5412 |
+
template<class SAlloc>
|
| 5413 |
+
basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
|
| 5414 |
+
basic_string<charT, traits, Allocator> str() &&;
|
| 5415 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 5416 |
+
|
| 5417 |
+
void str(const basic_string<charT, traits, Allocator>& s);
|
| 5418 |
+
template<class SAlloc>
|
| 5419 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 5420 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5421 |
|
| 5422 |
private:
|
| 5423 |
basic_stringbuf<charT, traits> sb; // exposition only
|
| 5424 |
};
|
| 5425 |
|
|
|
|
| 5436 |
associated sequence. For the sake of exposition, the maintained data is
|
| 5437 |
presented here as
|
| 5438 |
|
| 5439 |
- `sb`, the `stringbuf` object.
|
| 5440 |
|
| 5441 |
+
#### Constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
|
| 5442 |
+
|
| 5443 |
+
``` cpp
|
| 5444 |
+
explicit basic_stringstream(ios_base::openmode which);
|
| 5445 |
+
```
|
| 5446 |
+
|
| 5447 |
+
*Effects:* Initializes the base class with
|
| 5448 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 5449 |
+
`sb` with `basic_stringbuf<charT, traits, Allocator>(which)`.
|
| 5450 |
|
| 5451 |
``` cpp
|
| 5452 |
explicit basic_stringstream(
|
| 5453 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 5454 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5455 |
```
|
| 5456 |
|
| 5457 |
+
*Effects:* Initializes the base class with
|
| 5458 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 5459 |
+
`sb` with `basic_stringbuf<charT, traits, Allocator>(s, which)`.
|
| 5460 |
+
|
| 5461 |
+
``` cpp
|
| 5462 |
+
basic_stringstream(ios_base::openmode which, const Allocator& a);
|
| 5463 |
+
```
|
| 5464 |
+
|
| 5465 |
+
*Effects:* Initializes the base class with
|
| 5466 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 5467 |
+
`sb` with `basic_stringbuf<charT, traits, Allocator>(which, a)`
|
| 5468 |
+
[[stringbuf.cons]].
|
| 5469 |
|
| 5470 |
``` cpp
|
| 5471 |
explicit basic_stringstream(
|
| 5472 |
+
basic_string<charT, traits, Allocator>&& s,
|
| 5473 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5474 |
```
|
| 5475 |
|
| 5476 |
+
*Effects:* Initializes the base class with
|
| 5477 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 5478 |
+
`sb` with
|
| 5479 |
+
`basic_stringbuf<charT, traits, Allocator>(std::move(s), which)`
|
| 5480 |
+
[[stringbuf.cons]].
|
| 5481 |
+
|
| 5482 |
+
``` cpp
|
| 5483 |
+
template<class SAlloc>
|
| 5484 |
+
basic_stringstream(
|
| 5485 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5486 |
+
ios_base::openmode which, const Allocator& a);
|
| 5487 |
+
```
|
| 5488 |
+
|
| 5489 |
+
*Effects:* Initializes the base class with
|
| 5490 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 5491 |
+
`sb` with `basic_stringbuf<charT, traits, Allocator>(s, which, a)`
|
| 5492 |
+
[[stringbuf.cons]].
|
| 5493 |
+
|
| 5494 |
+
``` cpp
|
| 5495 |
+
template<class SAlloc>
|
| 5496 |
+
explicit basic_stringstream(
|
| 5497 |
+
const basic_string<charT, traits, SAlloc>& s,
|
| 5498 |
+
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 5499 |
+
```
|
| 5500 |
+
|
| 5501 |
+
*Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
|
| 5502 |
+
|
| 5503 |
+
*Effects:* Initializes the base class with
|
| 5504 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 5505 |
+
`sb` with `basic_stringbuf<charT, traits, Allocator>(s, which)`
|
| 5506 |
+
[[stringbuf.cons]].
|
| 5507 |
|
| 5508 |
``` cpp
|
| 5509 |
basic_stringstream(basic_stringstream&& rhs);
|
| 5510 |
```
|
| 5511 |
|
| 5512 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 5513 |
by move constructing the base class, and the contained
|
| 5514 |
+
`basic_stringbuf`. Then calls
|
| 5515 |
+
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 5516 |
+
contained `basic_stringbuf`.
|
| 5517 |
|
| 5518 |
+
#### Assignment and swap <a id="stringstream.assign">[[stringstream.assign]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5519 |
|
| 5520 |
``` cpp
|
| 5521 |
void swap(basic_stringstream& rhs);
|
| 5522 |
```
|
| 5523 |
|
| 5524 |
+
*Effects:* Equivalent to:
|
| 5525 |
+
|
| 5526 |
+
``` cpp
|
| 5527 |
+
basic_iostream<charT,traits>::swap(rhs);
|
| 5528 |
+
sb.swap(rhs.sb);
|
| 5529 |
+
```
|
| 5530 |
|
| 5531 |
``` cpp
|
| 5532 |
template<class charT, class traits, class Allocator>
|
| 5533 |
void swap(basic_stringstream<charT, traits, Allocator>& x,
|
| 5534 |
basic_stringstream<charT, traits, Allocator>& y);
|
| 5535 |
```
|
| 5536 |
|
| 5537 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 5538 |
|
| 5539 |
#### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
|
| 5540 |
|
| 5541 |
``` cpp
|
| 5542 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 5543 |
```
|
| 5544 |
|
| 5545 |
+
*Returns:*
|
| 5546 |
+
`const_cast<basic_stringbuf<charT, traits, Allocator>*>(addressof(sb))`.
|
| 5547 |
|
| 5548 |
``` cpp
|
| 5549 |
+
basic_string<charT, traits, Allocator> str() const &;
|
| 5550 |
```
|
| 5551 |
|
| 5552 |
+
*Effects:* Equivalent to: `return rdbuf()->str();`
|
| 5553 |
|
| 5554 |
``` cpp
|
| 5555 |
+
template<class SAlloc>
|
| 5556 |
+
basic_string<charT,traits,SAlloc> str(const SAlloc& sa) const;
|
| 5557 |
```
|
| 5558 |
|
| 5559 |
+
*Effects:* Equivalent to: `return rdbuf()->str(sa);`
|
| 5560 |
+
|
| 5561 |
+
``` cpp
|
| 5562 |
+
basic_string<charT,traits,Allocator> str() &&;
|
| 5563 |
+
```
|
| 5564 |
+
|
| 5565 |
+
*Effects:* Equivalent to: `return std::move(*rdbuf()).str();`
|
| 5566 |
+
|
| 5567 |
+
``` cpp
|
| 5568 |
+
basic_string_view<charT, traits> view() const noexcept;
|
| 5569 |
+
```
|
| 5570 |
+
|
| 5571 |
+
*Effects:* Equivalent to: `return rdbuf()->view();`
|
| 5572 |
+
|
| 5573 |
+
``` cpp
|
| 5574 |
+
void str(const basic_string<charT, traits, Allocator>& s);
|
| 5575 |
+
```
|
| 5576 |
+
|
| 5577 |
+
*Effects:* Equivalent to: `rdbuf()->str(s);`
|
| 5578 |
+
|
| 5579 |
+
``` cpp
|
| 5580 |
+
template<class SAlloc>
|
| 5581 |
+
void str(const basic_string<charT, traits, SAlloc>& s);
|
| 5582 |
+
```
|
| 5583 |
+
|
| 5584 |
+
*Effects:* Equivalent to: `rdbuf()->str(s);`
|
| 5585 |
+
|
| 5586 |
+
``` cpp
|
| 5587 |
+
void str(basic_string<charT, traits, Allocator>&& s);
|
| 5588 |
+
```
|
| 5589 |
+
|
| 5590 |
+
*Effects:* Equivalent to: `rdbuf()->str(std::move(s));`
|
| 5591 |
|
| 5592 |
## File-based streams <a id="file.streams">[[file.streams]]</a>
|
| 5593 |
|
| 5594 |
### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
|
| 5595 |
|
|
|
|
| 5625 |
or sink of bytes. In an environment that uses a large character set, the
|
| 5626 |
file typically holds multibyte character sequences and the
|
| 5627 |
`basic_filebuf` object converts those multibyte sequences into wide
|
| 5628 |
character sequences. — *end note*]
|
| 5629 |
|
| 5630 |
+
In subclause [[file.streams]], member functions taking arguments of
|
| 5631 |
`const filesystem::path::value_type*` are only be provided on systems
|
| 5632 |
+
where `filesystem::path::value_type` [[fs.class.path]] is not `char`.
|
| 5633 |
|
| 5634 |
[*Note 2*: These functions enable class `path` support for systems with
|
| 5635 |
a wide native path character type, such as `wchar_t`. — *end note*]
|
| 5636 |
|
| 5637 |
### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
|
|
|
|
| 5647 |
using off_type = typename traits::off_type;
|
| 5648 |
using traits_type = traits;
|
| 5649 |
|
| 5650 |
// [filebuf.cons], constructors/destructor
|
| 5651 |
basic_filebuf();
|
| 5652 |
+
basic_filebuf(const basic_filebuf&) = delete;
|
| 5653 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5654 |
virtual ~basic_filebuf();
|
| 5655 |
|
| 5656 |
// [filebuf.assign], assign and swap
|
| 5657 |
+
basic_filebuf& operator=(const basic_filebuf&) = delete;
|
| 5658 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5659 |
void swap(basic_filebuf& rhs);
|
| 5660 |
|
| 5661 |
// [filebuf.members], members
|
| 5662 |
bool is_open() const;
|
|
|
|
| 5714 |
provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
|
| 5715 |
the behavior is undefined.
|
| 5716 |
|
| 5717 |
In order to support file I/O and multibyte/wide character conversion,
|
| 5718 |
conversions are performed using members of a facet, referred to as
|
| 5719 |
+
`a_codecvt` in following subclauses, obtained as if by
|
| 5720 |
|
| 5721 |
``` cpp
|
| 5722 |
const codecvt<charT, char, typename traits::state_type>& a_codecvt =
|
| 5723 |
use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());
|
| 5724 |
```
|
| 5725 |
|
| 5726 |
+
#### Constructors <a id="filebuf.cons">[[filebuf.cons]]</a>
|
| 5727 |
|
| 5728 |
``` cpp
|
| 5729 |
basic_filebuf();
|
| 5730 |
```
|
| 5731 |
|
| 5732 |
+
*Effects:* Initializes the base class with
|
| 5733 |
+
`basic_streambuf<charT, traits>()` [[streambuf.cons]].
|
|
|
|
| 5734 |
|
| 5735 |
+
*Ensures:* `is_open() == false`.
|
| 5736 |
|
| 5737 |
``` cpp
|
| 5738 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5739 |
```
|
| 5740 |
|
| 5741 |
+
*Effects:* It is *implementation-defined* whether the sequence pointers
|
| 5742 |
+
in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`, `pptr()`,
|
| 5743 |
+
`epptr()`) obtain the values which `rhs` had. Whether they do or not,
|
| 5744 |
+
`*this` and `rhs` reference separate buffers (if any at all) after the
|
| 5745 |
+
construction. Additionally `*this` references the file which `rhs` did
|
| 5746 |
+
before the construction, and `rhs` references no file after the
|
| 5747 |
+
construction. The openmode, locale and any other state of `rhs` is also
|
| 5748 |
+
copied.
|
| 5749 |
|
| 5750 |
+
*Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
|
| 5751 |
+
construction and let `rhs_a` refer to the state of `rhs` just after this
|
| 5752 |
+
construction.
|
| 5753 |
|
| 5754 |
- `is_open() == rhs_p.is_open()`
|
| 5755 |
- `rhs_a.is_open() == false`
|
| 5756 |
- `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
|
| 5757 |
- `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
|
|
|
|
| 5766 |
|
| 5767 |
``` cpp
|
| 5768 |
virtual ~basic_filebuf();
|
| 5769 |
```
|
| 5770 |
|
| 5771 |
+
*Effects:* Calls `close()`. If an exception occurs during the
|
| 5772 |
+
destruction of the object, including the call to `close()`, the
|
| 5773 |
+
exception is caught but not rethrown
|
| 5774 |
+
(see [[res.on.exception.handling]]).
|
| 5775 |
|
| 5776 |
+
#### Assignment and swap <a id="filebuf.assign">[[filebuf.assign]]</a>
|
| 5777 |
|
| 5778 |
``` cpp
|
| 5779 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5780 |
```
|
| 5781 |
|
|
|
|
| 5795 |
template<class charT, class traits>
|
| 5796 |
void swap(basic_filebuf<charT, traits>& x,
|
| 5797 |
basic_filebuf<charT, traits>& y);
|
| 5798 |
```
|
| 5799 |
|
| 5800 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 5801 |
|
| 5802 |
#### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
|
| 5803 |
|
| 5804 |
``` cpp
|
| 5805 |
bool is_open() const;
|
|
|
|
| 5812 |
basic_filebuf* open(const char* s, ios_base::openmode mode);
|
| 5813 |
basic_filebuf* open(const filesystem::path::value_type* s,
|
| 5814 |
ios_base::openmode mode); // wide systems only; see [fstream.syn]
|
| 5815 |
```
|
| 5816 |
|
| 5817 |
+
*Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
|
| 5818 |
+
|
| 5819 |
*Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
|
| 5820 |
+
initializes the `filebuf` as required. It then opens the file to which
|
| 5821 |
+
`s` resolves, if possible, as if by a call to `fopen` with the second
|
| 5822 |
+
argument determined from `mode & ~ios_base::ate` as indicated in
|
| 5823 |
+
[[filebuf.open.modes]]. If `mode` is not some combination of flags shown
|
| 5824 |
+
in the table then the open fails.
|
|
|
|
| 5825 |
|
| 5826 |
+
**Table: File open modes** <a id="filebuf.open.modes">[filebuf.open.modes]</a>
|
| 5827 |
|
| 5828 |
| `binary` | `in` | `out` | `trunc` | `app` | | `stdio` equivalent |
|
| 5829 |
| -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
|
| 5830 |
| | | + | | | `"w"` |
|
| 5831 |
| | | + | | + | `"a"` |
|
|
|
|
| 5844 |
| + | + | + | + | | `"w+b"` |
|
| 5845 |
| + | + | + | | + | `"a+b"` |
|
| 5846 |
| + | + | | | + | `"a+b"` |
|
| 5847 |
|
| 5848 |
|
| 5849 |
+
If the open operation succeeds and `ios_base::ate` is set in `mode`,
|
| 5850 |
positions the file to the end (as if by calling
|
| 5851 |
+
`fseek(file, 0, SEEK_END)`, where `file` is the pointer returned by
|
| 5852 |
+
calling `fopen`). [^40]
|
| 5853 |
|
| 5854 |
If the repositioning operation fails, calls `close()` and returns a null
|
| 5855 |
pointer to indicate failure.
|
| 5856 |
|
| 5857 |
*Returns:* `this` if successful, a null pointer otherwise.
|
|
|
|
| 5880 |
these calls throws an exception, the exception is caught and rethrown
|
| 5881 |
after closing the file.
|
| 5882 |
|
| 5883 |
*Returns:* `this` on success, a null pointer otherwise.
|
| 5884 |
|
| 5885 |
+
*Ensures:* `is_open() == false`.
|
| 5886 |
|
| 5887 |
#### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
|
| 5888 |
|
| 5889 |
``` cpp
|
| 5890 |
streamsize showmanyc() override;
|
| 5891 |
```
|
| 5892 |
|
| 5893 |
+
*Effects:* Behaves the same as `basic_streambuf::showmanyc()`
|
| 5894 |
+
[[streambuf.virtuals]].
|
| 5895 |
|
| 5896 |
*Remarks:* An implementation might well provide an overriding definition
|
| 5897 |
for this function signature if it can determine that more characters can
|
| 5898 |
be read from the input sequence.
|
| 5899 |
|
|
|
|
| 5950 |
either the input sequence has a putback position available or the
|
| 5951 |
function makes a putback position available, decrements the next
|
| 5952 |
pointer for the input sequence, `gptr()`. Returns:
|
| 5953 |
`traits::not_eof(c)`.
|
| 5954 |
|
| 5955 |
+
*Returns:* As specified above, or `traits::eof()` to indicate failure.
|
| 5956 |
|
| 5957 |
*Remarks:* If `is_open() == false`, the function always fails.
|
| 5958 |
|
| 5959 |
The function does not put back a character directly to the input
|
| 5960 |
sequence.
|
|
|
|
| 6024 |
operation was overflow or the put buffer is non-empty. “Write any
|
| 6025 |
unshift sequence” means, if `width` if less than zero then call
|
| 6026 |
`a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
|
| 6027 |
resulting unshift sequence. The function determines one of three values
|
| 6028 |
for the argument `whence`, of type `int`, as indicated in
|
| 6029 |
+
[[filebuf.seekoff]].
|
| 6030 |
|
| 6031 |
+
**Table: `seekoff` effects** <a id="filebuf.seekoff">[filebuf.seekoff]</a>
|
| 6032 |
|
| 6033 |
| `way` Value | `stdio` Equivalent |
|
| 6034 |
| ---------------- | ------------------ |
|
| 6035 |
| `basic_ios::beg` | `SEEK_SET` |
|
| 6036 |
| `basic_ios::cur` | `SEEK_CUR` |
|
|
|
|
| 6079 |
|
| 6080 |
``` cpp
|
| 6081 |
void imbue(const locale& loc) override;
|
| 6082 |
```
|
| 6083 |
|
| 6084 |
+
*Preconditions:* If the file is not positioned at its beginning and the
|
| 6085 |
encoding of the current locale as determined by `a_codecvt.encoding()`
|
| 6086 |
+
is state-dependent [[locale.codecvt.virtuals]] then that facet is the
|
| 6087 |
same as the corresponding facet of `loc`.
|
| 6088 |
|
| 6089 |
*Effects:* Causes characters inserted or extracted after this call to be
|
| 6090 |
converted according to `loc` until another call of `imbue`.
|
| 6091 |
|
|
|
|
| 6114 |
ios_base::openmode mode = ios_base::in);// wide systems only; see [fstream.syn]
|
| 6115 |
explicit basic_ifstream(const string& s,
|
| 6116 |
ios_base::openmode mode = ios_base::in);
|
| 6117 |
explicit basic_ifstream(const filesystem::path& s,
|
| 6118 |
ios_base::openmode mode = ios_base::in);
|
| 6119 |
+
basic_ifstream(const basic_ifstream&) = delete;
|
| 6120 |
basic_ifstream(basic_ifstream&& rhs);
|
| 6121 |
|
| 6122 |
// [ifstream.assign], assign and swap
|
| 6123 |
+
basic_ifstream& operator=(const basic_ifstream&) = delete;
|
| 6124 |
basic_ifstream& operator=(basic_ifstream&& rhs);
|
| 6125 |
void swap(basic_ifstream& rhs);
|
| 6126 |
|
| 6127 |
// [ifstream.members], members
|
| 6128 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
|
|
| 6149 |
associated sequence. For the sake of exposition, the maintained data is
|
| 6150 |
presented here as:
|
| 6151 |
|
| 6152 |
- `sb`, the `filebuf` object.
|
| 6153 |
|
| 6154 |
+
#### Constructors <a id="ifstream.cons">[[ifstream.cons]]</a>
|
| 6155 |
|
| 6156 |
``` cpp
|
| 6157 |
basic_ifstream();
|
| 6158 |
```
|
| 6159 |
|
| 6160 |
+
*Effects:* Initializes the base class with
|
| 6161 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
|
| 6162 |
+
with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
|
|
|
|
| 6163 |
|
| 6164 |
``` cpp
|
| 6165 |
explicit basic_ifstream(const char* s,
|
| 6166 |
ios_base::openmode mode = ios_base::in);
|
| 6167 |
explicit basic_ifstream(const filesystem::path::value_type* s,
|
| 6168 |
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 6169 |
```
|
| 6170 |
|
| 6171 |
+
*Effects:* Initializes the base class with
|
| 6172 |
+
`basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
|
| 6173 |
+
with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
|
| 6174 |
+
`rdbuf()->open(s, mode | ios_base::in)`. If that function returns a null
|
| 6175 |
+
pointer, calls `setstate(failbit)`.
|
| 6176 |
|
| 6177 |
``` cpp
|
| 6178 |
explicit basic_ifstream(const string& s,
|
| 6179 |
ios_base::openmode mode = ios_base::in);
|
| 6180 |
explicit basic_ifstream(const filesystem::path& s,
|
| 6181 |
ios_base::openmode mode = ios_base::in);
|
| 6182 |
```
|
| 6183 |
|
| 6184 |
+
*Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
|
| 6185 |
|
| 6186 |
``` cpp
|
| 6187 |
basic_ifstream(basic_ifstream&& rhs);
|
| 6188 |
```
|
| 6189 |
|
| 6190 |
+
*Effects:* Move constructs the base class, and the contained
|
| 6191 |
+
`basic_filebuf`. Then calls
|
| 6192 |
+
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 6193 |
+
contained `basic_filebuf`.
|
| 6194 |
|
| 6195 |
+
#### Assignment and swap <a id="ifstream.assign">[[ifstream.assign]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6196 |
|
| 6197 |
``` cpp
|
| 6198 |
void swap(basic_ifstream& rhs);
|
| 6199 |
```
|
| 6200 |
|
|
|
|
| 6205 |
template<class charT, class traits>
|
| 6206 |
void swap(basic_ifstream<charT, traits>& x,
|
| 6207 |
basic_ifstream<charT, traits>& y);
|
| 6208 |
```
|
| 6209 |
|
| 6210 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 6211 |
|
| 6212 |
#### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
|
| 6213 |
|
| 6214 |
``` cpp
|
| 6215 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6216 |
```
|
| 6217 |
|
| 6218 |
+
*Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
|
| 6219 |
|
| 6220 |
``` cpp
|
| 6221 |
bool is_open() const;
|
| 6222 |
```
|
| 6223 |
|
|
|
|
| 6229 |
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 6230 |
```
|
| 6231 |
|
| 6232 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::in)`. If that
|
| 6233 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 6234 |
+
`setstate(failbit)` (which may throw
|
| 6235 |
+
`ios_base::failure`) [[iostate.flags]].
|
| 6236 |
|
| 6237 |
``` cpp
|
| 6238 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
| 6239 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
|
| 6240 |
```
|
|
|
|
| 6245 |
void close();
|
| 6246 |
```
|
| 6247 |
|
| 6248 |
*Effects:* Calls `rdbuf()->close()` and, if that function returns a null
|
| 6249 |
pointer, calls `setstate(failbit)` (which may throw
|
| 6250 |
+
`ios_base::failure`) [[iostate.flags]].
|
| 6251 |
|
| 6252 |
### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
|
| 6253 |
|
| 6254 |
``` cpp
|
| 6255 |
namespace std {
|
|
|
|
| 6264 |
|
| 6265 |
// [ofstream.cons], constructors
|
| 6266 |
basic_ofstream();
|
| 6267 |
explicit basic_ofstream(const char* s,
|
| 6268 |
ios_base::openmode mode = ios_base::out);
|
| 6269 |
+
explicit basic_ofstream(const filesystem::path::value_type* s, // wide systems only; see [fstream.syn]
|
| 6270 |
+
ios_base::openmode mode = ios_base::out);
|
| 6271 |
explicit basic_ofstream(const string& s,
|
| 6272 |
ios_base::openmode mode = ios_base::out);
|
| 6273 |
explicit basic_ofstream(const filesystem::path& s,
|
| 6274 |
ios_base::openmode mode = ios_base::out);
|
| 6275 |
+
basic_ofstream(const basic_ofstream&) = delete;
|
| 6276 |
basic_ofstream(basic_ofstream&& rhs);
|
| 6277 |
|
| 6278 |
// [ofstream.assign], assign and swap
|
| 6279 |
+
basic_ofstream& operator=(const basic_ofstream&) = delete;
|
| 6280 |
basic_ofstream& operator=(basic_ofstream&& rhs);
|
| 6281 |
void swap(basic_ofstream& rhs);
|
| 6282 |
|
| 6283 |
// [ofstream.members], members
|
| 6284 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
|
|
| 6305 |
associated sequence. For the sake of exposition, the maintained data is
|
| 6306 |
presented here as:
|
| 6307 |
|
| 6308 |
- `sb`, the `filebuf` object.
|
| 6309 |
|
| 6310 |
+
#### Constructors <a id="ofstream.cons">[[ofstream.cons]]</a>
|
| 6311 |
|
| 6312 |
``` cpp
|
| 6313 |
basic_ofstream();
|
| 6314 |
```
|
| 6315 |
|
| 6316 |
+
*Effects:* Initializes the base class with
|
| 6317 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
|
| 6318 |
+
with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
|
|
|
|
| 6319 |
|
| 6320 |
``` cpp
|
| 6321 |
explicit basic_ofstream(const char* s,
|
| 6322 |
ios_base::openmode mode = ios_base::out);
|
| 6323 |
explicit basic_ofstream(const filesystem::path::value_type* s,
|
| 6324 |
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 6325 |
```
|
| 6326 |
|
| 6327 |
+
*Effects:* Initializes the base class with
|
| 6328 |
+
`basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
|
| 6329 |
+
with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
|
| 6330 |
+
`rdbuf()->open(s, mode | ios_base::out)`. If that function returns a
|
| 6331 |
+
null pointer, calls `setstate(failbit)`.
|
|
|
|
| 6332 |
|
| 6333 |
``` cpp
|
| 6334 |
explicit basic_ofstream(const string& s,
|
| 6335 |
ios_base::openmode mode = ios_base::out);
|
| 6336 |
explicit basic_ofstream(const filesystem::path& s,
|
| 6337 |
ios_base::openmode mode = ios_base::out);
|
| 6338 |
```
|
| 6339 |
|
| 6340 |
+
*Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
|
| 6341 |
|
| 6342 |
``` cpp
|
| 6343 |
basic_ofstream(basic_ofstream&& rhs);
|
| 6344 |
```
|
| 6345 |
|
| 6346 |
+
*Effects:* Move constructs the base class, and the contained
|
| 6347 |
+
`basic_filebuf`. Then calls
|
| 6348 |
+
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 6349 |
+
contained `basic_filebuf`.
|
| 6350 |
|
| 6351 |
+
#### Assignment and swap <a id="ofstream.assign">[[ofstream.assign]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6352 |
|
| 6353 |
``` cpp
|
| 6354 |
void swap(basic_ofstream& rhs);
|
| 6355 |
```
|
| 6356 |
|
|
|
|
| 6361 |
template<class charT, class traits>
|
| 6362 |
void swap(basic_ofstream<charT, traits>& x,
|
| 6363 |
basic_ofstream<charT, traits>& y);
|
| 6364 |
```
|
| 6365 |
|
| 6366 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 6367 |
|
| 6368 |
#### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
|
| 6369 |
|
| 6370 |
``` cpp
|
| 6371 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6372 |
```
|
| 6373 |
|
| 6374 |
+
*Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
|
| 6375 |
|
| 6376 |
``` cpp
|
| 6377 |
bool is_open() const;
|
| 6378 |
```
|
| 6379 |
|
|
|
|
| 6385 |
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 6386 |
```
|
| 6387 |
|
| 6388 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::out)`. If that
|
| 6389 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 6390 |
+
`setstate(failbit)` (which may throw
|
| 6391 |
+
`ios_base::failure`) [[iostate.flags]].
|
| 6392 |
|
| 6393 |
``` cpp
|
| 6394 |
void close();
|
| 6395 |
```
|
| 6396 |
|
| 6397 |
*Effects:* Calls `rdbuf()->close()` and, if that function fails (returns
|
| 6398 |
a null pointer), calls `setstate(failbit)` (which may throw
|
| 6399 |
+
`ios_base::failure`) [[iostate.flags]].
|
| 6400 |
|
| 6401 |
``` cpp
|
| 6402 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
| 6403 |
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
|
| 6404 |
```
|
|
|
|
| 6422 |
basic_fstream();
|
| 6423 |
explicit basic_fstream(
|
| 6424 |
const char* s,
|
| 6425 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6426 |
explicit basic_fstream(
|
| 6427 |
+
const filesystem::path::value_type* s,
|
| 6428 |
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 6429 |
explicit basic_fstream(
|
| 6430 |
const string& s,
|
| 6431 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6432 |
explicit basic_fstream(
|
| 6433 |
const filesystem::path& s,
|
| 6434 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6435 |
+
basic_fstream(const basic_fstream&) = delete;
|
| 6436 |
basic_fstream(basic_fstream&& rhs);
|
| 6437 |
|
| 6438 |
// [fstream.assign], assign and swap
|
| 6439 |
+
basic_fstream& operator=(const basic_fstream&) = delete;
|
| 6440 |
basic_fstream& operator=(basic_fstream&& rhs);
|
| 6441 |
void swap(basic_fstream& rhs);
|
| 6442 |
|
| 6443 |
// [fstream.members], members
|
| 6444 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6445 |
bool is_open() const;
|
| 6446 |
void open(
|
| 6447 |
const char* s,
|
| 6448 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6449 |
void open(
|
| 6450 |
+
const filesystem::path::value_type* s,
|
| 6451 |
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 6452 |
void open(
|
| 6453 |
const string& s,
|
| 6454 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6455 |
void open(
|
|
|
|
| 6472 |
object to control the associated sequences. For the sake of exposition,
|
| 6473 |
the maintained data is presented here as:
|
| 6474 |
|
| 6475 |
- `sb`, the `basic_filebuf` object.
|
| 6476 |
|
| 6477 |
+
#### Constructors <a id="fstream.cons">[[fstream.cons]]</a>
|
| 6478 |
|
| 6479 |
``` cpp
|
| 6480 |
basic_fstream();
|
| 6481 |
```
|
| 6482 |
|
| 6483 |
+
*Effects:* Initializes the base class with
|
| 6484 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 6485 |
`sb` with `basic_filebuf<charT, traits>()`.
|
| 6486 |
|
| 6487 |
``` cpp
|
| 6488 |
explicit basic_fstream(
|
| 6489 |
const char* s,
|
|
|
|
| 6491 |
explicit basic_fstream(
|
| 6492 |
const filesystem::path::value_type* s,
|
| 6493 |
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
|
| 6494 |
```
|
| 6495 |
|
| 6496 |
+
*Effects:* Initializes the base class with
|
| 6497 |
+
`basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
|
| 6498 |
`sb` with `basic_filebuf<charT, traits>()`. Then calls
|
| 6499 |
`rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
|
| 6500 |
`setstate(failbit)`.
|
| 6501 |
|
| 6502 |
``` cpp
|
|
|
|
| 6506 |
explicit basic_fstream(
|
| 6507 |
const filesystem::path& s,
|
| 6508 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6509 |
```
|
| 6510 |
|
| 6511 |
+
*Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
|
| 6512 |
|
| 6513 |
``` cpp
|
| 6514 |
basic_fstream(basic_fstream&& rhs);
|
| 6515 |
```
|
| 6516 |
|
| 6517 |
+
*Effects:* Move constructs the base class, and the contained
|
| 6518 |
+
`basic_filebuf`. Then calls
|
| 6519 |
+
`basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
|
| 6520 |
+
contained `basic_filebuf`.
|
| 6521 |
|
| 6522 |
+
#### Assignment and swap <a id="fstream.assign">[[fstream.assign]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6523 |
|
| 6524 |
``` cpp
|
| 6525 |
void swap(basic_fstream& rhs);
|
| 6526 |
```
|
| 6527 |
|
|
|
|
| 6532 |
template<class charT, class traits>
|
| 6533 |
void swap(basic_fstream<charT, traits>& x,
|
| 6534 |
basic_fstream<charT, traits>& y);
|
| 6535 |
```
|
| 6536 |
|
| 6537 |
+
*Effects:* Equivalent to: `x.swap(y)`.
|
| 6538 |
|
| 6539 |
#### Member functions <a id="fstream.members">[[fstream.members]]</a>
|
| 6540 |
|
| 6541 |
``` cpp
|
| 6542 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 6543 |
```
|
| 6544 |
|
| 6545 |
+
*Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
|
| 6546 |
|
| 6547 |
``` cpp
|
| 6548 |
bool is_open() const;
|
| 6549 |
```
|
| 6550 |
|
|
|
|
| 6560 |
```
|
| 6561 |
|
| 6562 |
*Effects:* Calls `rdbuf()->open(s, mode)`. If that function does not
|
| 6563 |
return a null pointer calls `clear()`, otherwise calls
|
| 6564 |
`setstate(failbit)` (which may throw
|
| 6565 |
+
`ios_base::failure`) [[iostate.flags]].
|
| 6566 |
|
| 6567 |
``` cpp
|
| 6568 |
void open(
|
| 6569 |
const string& s,
|
| 6570 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
|
|
|
| 6579 |
void close();
|
| 6580 |
```
|
| 6581 |
|
| 6582 |
*Effects:* Calls `rdbuf()->close()` and, if that function returns a null
|
| 6583 |
pointer, calls `setstate(failbit)` (which may throw
|
| 6584 |
+
`ios_base::failure`) [[iostate.flags]].
|
| 6585 |
+
|
| 6586 |
+
## Synchronized output streams <a id="syncstream">[[syncstream]]</a>
|
| 6587 |
+
|
| 6588 |
+
### Header `<syncstream>` synopsis <a id="syncstream.syn">[[syncstream.syn]]</a>
|
| 6589 |
+
|
| 6590 |
+
``` cpp
|
| 6591 |
+
#include <ostream> // see [ostream.syn]
|
| 6592 |
+
|
| 6593 |
+
namespace std {
|
| 6594 |
+
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 6595 |
+
class basic_syncbuf;
|
| 6596 |
+
|
| 6597 |
+
using syncbuf = basic_syncbuf<char>;
|
| 6598 |
+
using wsyncbuf = basic_syncbuf<wchar_t>;
|
| 6599 |
+
|
| 6600 |
+
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 6601 |
+
class basic_osyncstream;
|
| 6602 |
+
|
| 6603 |
+
using osyncstream = basic_osyncstream<char>;
|
| 6604 |
+
using wosyncstream = basic_osyncstream<wchar_t>;
|
| 6605 |
+
}
|
| 6606 |
+
```
|
| 6607 |
+
|
| 6608 |
+
The header `<syncstream>` provides a mechanism to synchronize execution
|
| 6609 |
+
agents writing to the same stream.
|
| 6610 |
+
|
| 6611 |
+
### Class template `basic_syncbuf` <a id="syncstream.syncbuf">[[syncstream.syncbuf]]</a>
|
| 6612 |
+
|
| 6613 |
+
#### Overview <a id="syncstream.syncbuf.overview">[[syncstream.syncbuf.overview]]</a>
|
| 6614 |
+
|
| 6615 |
+
``` cpp
|
| 6616 |
+
namespace std {
|
| 6617 |
+
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 6618 |
+
class basic_syncbuf : public basic_streambuf<charT, traits> {
|
| 6619 |
+
public:
|
| 6620 |
+
using char_type = charT;
|
| 6621 |
+
using int_type = typename traits::int_type;
|
| 6622 |
+
using pos_type = typename traits::pos_type;
|
| 6623 |
+
using off_type = typename traits::off_type;
|
| 6624 |
+
using traits_type = traits;
|
| 6625 |
+
using allocator_type = Allocator;
|
| 6626 |
+
|
| 6627 |
+
using streambuf_type = basic_streambuf<charT, traits>;
|
| 6628 |
+
|
| 6629 |
+
// [syncstream.syncbuf.cons], construction and destruction
|
| 6630 |
+
basic_syncbuf()
|
| 6631 |
+
: basic_syncbuf(nullptr) {}
|
| 6632 |
+
explicit basic_syncbuf(streambuf_type* obuf)
|
| 6633 |
+
: basic_syncbuf(obuf, Allocator()) {}
|
| 6634 |
+
basic_syncbuf(streambuf_type*, const Allocator&);
|
| 6635 |
+
basic_syncbuf(basic_syncbuf&&);
|
| 6636 |
+
~basic_syncbuf();
|
| 6637 |
+
|
| 6638 |
+
// [syncstream.syncbuf.assign], assignment and swap
|
| 6639 |
+
basic_syncbuf& operator=(basic_syncbuf&&);
|
| 6640 |
+
void swap(basic_syncbuf&);
|
| 6641 |
+
|
| 6642 |
+
// [syncstream.syncbuf.members], member functions
|
| 6643 |
+
bool emit();
|
| 6644 |
+
streambuf_type* get_wrapped() const noexcept;
|
| 6645 |
+
allocator_type get_allocator() const noexcept;
|
| 6646 |
+
void set_emit_on_sync(bool) noexcept;
|
| 6647 |
+
|
| 6648 |
+
protected:
|
| 6649 |
+
// [syncstream.syncbuf.virtuals], overridden virtual functions
|
| 6650 |
+
int sync() override;
|
| 6651 |
+
|
| 6652 |
+
private:
|
| 6653 |
+
streambuf_type* wrapped; // exposition only
|
| 6654 |
+
bool emit_on_sync{}; // exposition only
|
| 6655 |
+
};
|
| 6656 |
+
|
| 6657 |
+
// [syncstream.syncbuf.special], specialized algorithms
|
| 6658 |
+
template<class charT, class traits, class Allocator>
|
| 6659 |
+
void swap(basic_syncbuf<charT, traits, Allocator>&,
|
| 6660 |
+
basic_syncbuf<charT, traits, Allocator>&);
|
| 6661 |
+
}
|
| 6662 |
+
```
|
| 6663 |
+
|
| 6664 |
+
Class template `basic_syncbuf` stores character data written to it,
|
| 6665 |
+
known as the associated output, into internal buffers allocated using
|
| 6666 |
+
the object’s allocator. The associated output is transferred to the
|
| 6667 |
+
wrapped stream buffer object `*wrapped` when `emit()` is called or when
|
| 6668 |
+
the `basic_syncbuf` object is destroyed. Such transfers are atomic with
|
| 6669 |
+
respect to transfers by other `basic_syncbuf` objects with the same
|
| 6670 |
+
wrapped stream buffer object.
|
| 6671 |
+
|
| 6672 |
+
#### Construction and destruction <a id="syncstream.syncbuf.cons">[[syncstream.syncbuf.cons]]</a>
|
| 6673 |
+
|
| 6674 |
+
``` cpp
|
| 6675 |
+
basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
|
| 6676 |
+
```
|
| 6677 |
+
|
| 6678 |
+
*Effects:* Sets `wrapped` to `obuf`.
|
| 6679 |
+
|
| 6680 |
+
*Remarks:* A copy of `allocator` is used to allocate memory for internal
|
| 6681 |
+
buffers holding the associated output.
|
| 6682 |
+
|
| 6683 |
+
*Throws:* Nothing unless an exception is thrown by the construction of a
|
| 6684 |
+
mutex or by memory allocation.
|
| 6685 |
+
|
| 6686 |
+
*Ensures:* `get_wrapped() == obuf` and `get_allocator() == allocator`
|
| 6687 |
+
are `true`.
|
| 6688 |
+
|
| 6689 |
+
``` cpp
|
| 6690 |
+
basic_syncbuf(basic_syncbuf&& other);
|
| 6691 |
+
```
|
| 6692 |
+
|
| 6693 |
+
*Ensures:* The value returned by `this->get_wrapped()` is the value
|
| 6694 |
+
returned by `other.get_wrapped()` prior to calling this constructor.
|
| 6695 |
+
Output stored in `other` prior to calling this constructor will be
|
| 6696 |
+
stored in `*this` afterwards.
|
| 6697 |
+
`other.rdbuf()->pbase() == other.rdbuf()->pptr()` and
|
| 6698 |
+
`other.get_wrapped() == nullptr` are `true`.
|
| 6699 |
+
|
| 6700 |
+
*Remarks:* This constructor disassociates `other` from its wrapped
|
| 6701 |
+
stream buffer, ensuring destruction of `other` produces no output.
|
| 6702 |
+
|
| 6703 |
+
``` cpp
|
| 6704 |
+
~basic_syncbuf();
|
| 6705 |
+
```
|
| 6706 |
+
|
| 6707 |
+
*Effects:* Calls `emit()`.
|
| 6708 |
+
|
| 6709 |
+
*Throws:* Nothing. If an exception is thrown from `emit()`, the
|
| 6710 |
+
destructor catches and ignores that exception.
|
| 6711 |
+
|
| 6712 |
+
#### Assignment and swap <a id="syncstream.syncbuf.assign">[[syncstream.syncbuf.assign]]</a>
|
| 6713 |
+
|
| 6714 |
+
``` cpp
|
| 6715 |
+
basic_syncbuf& operator=(basic_syncbuf&& rhs) noexcept;
|
| 6716 |
+
```
|
| 6717 |
+
|
| 6718 |
+
*Effects:* Calls `emit()` then move assigns from `rhs`. After the move
|
| 6719 |
+
assignment `*this` has the observable state it would have had if it had
|
| 6720 |
+
been move constructed from `rhs` [[syncstream.syncbuf.cons]].
|
| 6721 |
+
|
| 6722 |
+
*Returns:* `*this`.
|
| 6723 |
+
|
| 6724 |
+
*Ensures:*
|
| 6725 |
+
|
| 6726 |
+
- `rhs.get_wrapped() == nullptr` is `true`.
|
| 6727 |
+
- `this->get_allocator() == rhs.get_allocator()` is `true` when
|
| 6728 |
+
``` cpp
|
| 6729 |
+
allocator_traits<Allocator>::propagate_on_container_move_assignment::value
|
| 6730 |
+
```
|
| 6731 |
+
|
| 6732 |
+
is `true`; otherwise, the allocator is unchanged.
|
| 6733 |
+
|
| 6734 |
+
*Remarks:* This assignment operator disassociates `rhs` from its wrapped
|
| 6735 |
+
stream buffer, ensuring destruction of `rhs` produces no output.
|
| 6736 |
+
|
| 6737 |
+
``` cpp
|
| 6738 |
+
void swap(basic_syncbuf& other) noexcept;
|
| 6739 |
+
```
|
| 6740 |
+
|
| 6741 |
+
*Preconditions:* Either
|
| 6742 |
+
`allocator_traits<Allocator>::propagate_on_container_swap::value` is
|
| 6743 |
+
`true` or `this->get_allocator() == other.get_allocator()` is `true`.
|
| 6744 |
+
|
| 6745 |
+
*Effects:* Exchanges the state of `*this` and `other`.
|
| 6746 |
+
|
| 6747 |
+
#### Member functions <a id="syncstream.syncbuf.members">[[syncstream.syncbuf.members]]</a>
|
| 6748 |
+
|
| 6749 |
+
``` cpp
|
| 6750 |
+
bool emit();
|
| 6751 |
+
```
|
| 6752 |
+
|
| 6753 |
+
*Effects:* Atomically transfers the associated output of `*this` to the
|
| 6754 |
+
stream buffer `*wrapped`, so that it appears in the output stream as a
|
| 6755 |
+
contiguous sequence of characters. `wrapped->pubsync()` is called if and
|
| 6756 |
+
only if a call was made to `sync()` since the most recent call to
|
| 6757 |
+
`emit()`, if any.
|
| 6758 |
+
|
| 6759 |
+
*Returns:* `true` if all of the following conditions hold; otherwise
|
| 6760 |
+
`false`:
|
| 6761 |
+
|
| 6762 |
+
- `wrapped == nullptr` is `false`.
|
| 6763 |
+
- All of the characters in the associated output were successfully
|
| 6764 |
+
transferred.
|
| 6765 |
+
- The call to `wrapped->pubsync()` (if any) succeeded.
|
| 6766 |
+
|
| 6767 |
+
*Ensures:* On success, the associated output is empty.
|
| 6768 |
+
|
| 6769 |
+
*Synchronization:* All `emit()` calls transferring characters to the
|
| 6770 |
+
same stream buffer object appear to execute in a total order consistent
|
| 6771 |
+
with the “happens before” relation [[intro.races]], where each `emit()`
|
| 6772 |
+
call synchronizes with subsequent `emit()` calls in that total order.
|
| 6773 |
+
|
| 6774 |
+
*Remarks:* May call member functions of `wrapped` while holding a lock
|
| 6775 |
+
uniquely associated with `wrapped`.
|
| 6776 |
+
|
| 6777 |
+
``` cpp
|
| 6778 |
+
streambuf_type* get_wrapped() const noexcept;
|
| 6779 |
+
```
|
| 6780 |
+
|
| 6781 |
+
*Returns:* `wrapped`.
|
| 6782 |
+
|
| 6783 |
+
``` cpp
|
| 6784 |
+
allocator_type get_allocator() const noexcept;
|
| 6785 |
+
```
|
| 6786 |
+
|
| 6787 |
+
*Returns:* A copy of the allocator that was set in the constructor or
|
| 6788 |
+
assignment operator.
|
| 6789 |
+
|
| 6790 |
+
``` cpp
|
| 6791 |
+
void set_emit_on_sync(bool b) noexcept;
|
| 6792 |
+
```
|
| 6793 |
+
|
| 6794 |
+
*Effects:* `emit_on_sync = b`.
|
| 6795 |
+
|
| 6796 |
+
#### Overridden virtual functions <a id="syncstream.syncbuf.virtuals">[[syncstream.syncbuf.virtuals]]</a>
|
| 6797 |
+
|
| 6798 |
+
``` cpp
|
| 6799 |
+
int sync() override;
|
| 6800 |
+
```
|
| 6801 |
+
|
| 6802 |
+
*Effects:* Records that the wrapped stream buffer is to be flushed.
|
| 6803 |
+
Then, if `emit_on_sync` is `true`, calls `emit()`.
|
| 6804 |
+
|
| 6805 |
+
[*Note 1*: If `emit_on_sync` is `false`, the actual flush is delayed
|
| 6806 |
+
until a call to `emit()`. — *end note*]
|
| 6807 |
+
|
| 6808 |
+
*Returns:* If `emit()` was called and returned `false`, returns `-1`;
|
| 6809 |
+
otherwise `0`.
|
| 6810 |
+
|
| 6811 |
+
#### Specialized algorithms <a id="syncstream.syncbuf.special">[[syncstream.syncbuf.special]]</a>
|
| 6812 |
+
|
| 6813 |
+
``` cpp
|
| 6814 |
+
template<class charT, class traits, class Allocator>
|
| 6815 |
+
void swap(basic_syncbuf<charT, traits, Allocator>& a,
|
| 6816 |
+
basic_syncbuf<charT, traits, Allocator>& b) noexcept;
|
| 6817 |
+
```
|
| 6818 |
+
|
| 6819 |
+
*Effects:* Equivalent to `a.swap(b)`.
|
| 6820 |
+
|
| 6821 |
+
### Class template `basic_osyncstream` <a id="syncstream.osyncstream">[[syncstream.osyncstream]]</a>
|
| 6822 |
+
|
| 6823 |
+
#### Overview <a id="syncstream.osyncstream.overview">[[syncstream.osyncstream.overview]]</a>
|
| 6824 |
+
|
| 6825 |
+
``` cpp
|
| 6826 |
+
namespace std {
|
| 6827 |
+
template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
|
| 6828 |
+
class basic_osyncstream : public basic_ostream<charT, traits> {
|
| 6829 |
+
public:
|
| 6830 |
+
using char_type = charT;
|
| 6831 |
+
using int_type = typename traits::int_type;
|
| 6832 |
+
using pos_type = typename traits::pos_type;
|
| 6833 |
+
using off_type = typename traits::off_type;
|
| 6834 |
+
using traits_type = traits;
|
| 6835 |
+
|
| 6836 |
+
using allocator_type = Allocator;
|
| 6837 |
+
using streambuf_type = basic_streambuf<charT, traits>;
|
| 6838 |
+
using syncbuf_type = basic_syncbuf<charT, traits, Allocator>;
|
| 6839 |
+
|
| 6840 |
+
// [syncstream.osyncstream.cons], construction and destruction
|
| 6841 |
+
basic_osyncstream(streambuf_type*, const Allocator&);
|
| 6842 |
+
explicit basic_osyncstream(streambuf_type* obuf)
|
| 6843 |
+
: basic_osyncstream(obuf, Allocator()) {}
|
| 6844 |
+
basic_osyncstream(basic_ostream<charT, traits>& os, const Allocator& allocator)
|
| 6845 |
+
: basic_osyncstream(os.rdbuf(), allocator) {}
|
| 6846 |
+
explicit basic_osyncstream(basic_ostream<charT, traits>& os)
|
| 6847 |
+
: basic_osyncstream(os, Allocator()) {}
|
| 6848 |
+
basic_osyncstream(basic_osyncstream&&) noexcept;
|
| 6849 |
+
~basic_osyncstream();
|
| 6850 |
+
|
| 6851 |
+
// assignment
|
| 6852 |
+
basic_osyncstream& operator=(basic_osyncstream&&) noexcept;
|
| 6853 |
+
|
| 6854 |
+
// [syncstream.osyncstream.members], member functions
|
| 6855 |
+
void emit();
|
| 6856 |
+
streambuf_type* get_wrapped() const noexcept;
|
| 6857 |
+
syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); }
|
| 6858 |
+
|
| 6859 |
+
private:
|
| 6860 |
+
syncbuf_type sb; // exposition only
|
| 6861 |
+
};
|
| 6862 |
+
}
|
| 6863 |
+
```
|
| 6864 |
+
|
| 6865 |
+
`Allocator` shall meet the *Cpp17Allocator* requirements (
|
| 6866 |
+
[[cpp17.allocator]]).
|
| 6867 |
+
|
| 6868 |
+
[*Example 1*:
|
| 6869 |
+
|
| 6870 |
+
A named variable can be used within a block statement for streaming.
|
| 6871 |
+
|
| 6872 |
+
``` cpp
|
| 6873 |
+
{
|
| 6874 |
+
osyncstream bout(cout);
|
| 6875 |
+
bout << "Hello, ";
|
| 6876 |
+
bout << "World!";
|
| 6877 |
+
bout << endl; // flush is noted
|
| 6878 |
+
bout << "and more!\n";
|
| 6879 |
+
} // characters are transferred and cout is flushed
|
| 6880 |
+
```
|
| 6881 |
+
|
| 6882 |
+
— *end example*]
|
| 6883 |
+
|
| 6884 |
+
[*Example 2*:
|
| 6885 |
+
|
| 6886 |
+
A temporary object can be used for streaming within a single statement.
|
| 6887 |
+
|
| 6888 |
+
``` cpp
|
| 6889 |
+
osyncstream(cout) << "Hello, " << "World!" << '\n';
|
| 6890 |
+
```
|
| 6891 |
+
|
| 6892 |
+
In this example, `cout` is not flushed.
|
| 6893 |
+
|
| 6894 |
+
— *end example*]
|
| 6895 |
+
|
| 6896 |
+
#### Construction and destruction <a id="syncstream.osyncstream.cons">[[syncstream.osyncstream.cons]]</a>
|
| 6897 |
+
|
| 6898 |
+
``` cpp
|
| 6899 |
+
basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
|
| 6900 |
+
```
|
| 6901 |
+
|
| 6902 |
+
*Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
|
| 6903 |
+
base class with `basic_ostream<charT, traits>(addressof(sb))`.
|
| 6904 |
+
|
| 6905 |
+
[*Note 1*: The member functions of the provided stream buffer might be
|
| 6906 |
+
called from `emit()` while a lock is held. Care should be taken to
|
| 6907 |
+
ensure that this does not result in deadlock. — *end note*]
|
| 6908 |
+
|
| 6909 |
+
*Ensures:* `get_wrapped() == buf` is `true`.
|
| 6910 |
+
|
| 6911 |
+
``` cpp
|
| 6912 |
+
basic_osyncstream(basic_osyncstream&& other) noexcept;
|
| 6913 |
+
```
|
| 6914 |
+
|
| 6915 |
+
*Effects:* Move constructs the base class and `sb` from the
|
| 6916 |
+
corresponding subobjects of `other`, and calls
|
| 6917 |
+
`basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
|
| 6918 |
+
|
| 6919 |
+
*Ensures:* The value returned by `get_wrapped()` is the value returned
|
| 6920 |
+
by `os.get_wrapped()` prior to calling this constructor.
|
| 6921 |
+
`nullptr == other.get_wrapped()` is `true`.
|
| 6922 |
+
|
| 6923 |
+
#### Member functions <a id="syncstream.osyncstream.members">[[syncstream.osyncstream.members]]</a>
|
| 6924 |
+
|
| 6925 |
+
``` cpp
|
| 6926 |
+
void emit();
|
| 6927 |
+
```
|
| 6928 |
+
|
| 6929 |
+
*Effects:* Calls `sb.emit()`. If that call returns `false`, calls
|
| 6930 |
+
`setstate(ios_base::badbit)`.
|
| 6931 |
+
|
| 6932 |
+
[*Example 1*:
|
| 6933 |
+
|
| 6934 |
+
A flush on a `basic_osyncstream` does not flush immediately:
|
| 6935 |
+
|
| 6936 |
+
``` cpp
|
| 6937 |
+
{
|
| 6938 |
+
osyncstream bout(cout);
|
| 6939 |
+
bout << "Hello," << '\n'; // no flush
|
| 6940 |
+
bout.emit(); // characters transferred; cout not flushed
|
| 6941 |
+
bout << "World!" << endl; // flush noted; cout not flushed
|
| 6942 |
+
bout.emit(); // characters transferred; cout flushed
|
| 6943 |
+
bout << "Greetings." << '\n'; // no flush
|
| 6944 |
+
} // characters transferred; cout not flushed
|
| 6945 |
+
```
|
| 6946 |
+
|
| 6947 |
+
— *end example*]
|
| 6948 |
+
|
| 6949 |
+
[*Example 2*:
|
| 6950 |
+
|
| 6951 |
+
The function `emit()` can be used to handle exceptions from operations
|
| 6952 |
+
on the underlying stream.
|
| 6953 |
+
|
| 6954 |
+
``` cpp
|
| 6955 |
+
{
|
| 6956 |
+
osyncstream bout(cout);
|
| 6957 |
+
bout << "Hello, " << "World!" << '\n';
|
| 6958 |
+
try {
|
| 6959 |
+
bout.emit();
|
| 6960 |
+
} catch (...) {
|
| 6961 |
+
// handle exception
|
| 6962 |
+
}
|
| 6963 |
+
}
|
| 6964 |
+
```
|
| 6965 |
+
|
| 6966 |
+
— *end example*]
|
| 6967 |
+
|
| 6968 |
+
``` cpp
|
| 6969 |
+
streambuf_type* get_wrapped() const noexcept;
|
| 6970 |
+
```
|
| 6971 |
+
|
| 6972 |
+
*Returns:* `sb.get_wrapped()`.
|
| 6973 |
+
|
| 6974 |
+
[*Example 3*:
|
| 6975 |
+
|
| 6976 |
+
Obtaining the wrapped stream buffer with `get_wrapped()` allows wrapping
|
| 6977 |
+
it again with an `osyncstream`. For example,
|
| 6978 |
+
|
| 6979 |
+
``` cpp
|
| 6980 |
+
{
|
| 6981 |
+
osyncstream bout1(cout);
|
| 6982 |
+
bout1 << "Hello, ";
|
| 6983 |
+
{
|
| 6984 |
+
osyncstream(bout1.get_wrapped()) << "Goodbye, " << "Planet!" << '\n';
|
| 6985 |
+
}
|
| 6986 |
+
bout1 << "World!" << '\n';
|
| 6987 |
+
}
|
| 6988 |
+
```
|
| 6989 |
+
|
| 6990 |
+
produces the *uninterleaved* output
|
| 6991 |
+
|
| 6992 |
+
``` text
|
| 6993 |
+
Goodbye, Planet!
|
| 6994 |
+
Hello, World!
|
| 6995 |
+
```
|
| 6996 |
+
|
| 6997 |
+
— *end example*]
|
| 6998 |
|
| 6999 |
## File systems <a id="filesystems">[[filesystems]]</a>
|
| 7000 |
|
| 7001 |
### General <a id="fs.general">[[fs.general]]</a>
|
| 7002 |
|
| 7003 |
+
Subclause [[filesystems]] describes operations on file systems and
|
| 7004 |
+
their components, such as paths, regular files, and directories.
|
| 7005 |
+
|
| 7006 |
+
A *file system* is a collection of files and their attributes.
|
| 7007 |
+
|
| 7008 |
+
A *file* is an object within a file system that holds user or system
|
| 7009 |
+
data. Files can be written to, or read from, or both. A file has certain
|
| 7010 |
+
attributes, including type. File types include regular files and
|
| 7011 |
+
directories. Other types of files, such as symbolic links, may be
|
| 7012 |
+
supported by the implementation.
|
| 7013 |
+
|
| 7014 |
+
A *directory* is a file within a file system that acts as a container of
|
| 7015 |
+
directory entries that contain information about other files, possibly
|
| 7016 |
+
including other directory files. The *parent directory* of a directory
|
| 7017 |
+
is the directory that both contains a directory entry for the given
|
| 7018 |
+
directory and is represented by the dot-dot filename [[fs.path.generic]]
|
| 7019 |
+
in the given directory. The *parent directory* of other types of files
|
| 7020 |
+
is a directory containing a directory entry for the file under
|
| 7021 |
+
discussion.
|
| 7022 |
+
|
| 7023 |
+
A *link* is an object that associates a filename with a file. Several
|
| 7024 |
+
links can associate names with the same file. A *hard link* is a link to
|
| 7025 |
+
an existing file. Some file systems support multiple hard links to a
|
| 7026 |
+
file. If the last hard link to a file is removed, the file itself is
|
| 7027 |
+
removed.
|
| 7028 |
+
|
| 7029 |
+
[*Note 1*: A hard link can be thought of as a shared-ownership smart
|
| 7030 |
+
pointer to a file. — *end note*]
|
| 7031 |
+
|
| 7032 |
+
A *symbolic link* is a type of file with the property that when the file
|
| 7033 |
+
is encountered during pathname resolution [[fs.class.path]], a string
|
| 7034 |
+
stored by the file is used to modify the pathname resolution.
|
| 7035 |
+
|
| 7036 |
+
[*Note 2*: Symbolic links are often called symlinks. A symbolic link
|
| 7037 |
+
can be thought of as a raw pointer to a file. If the file pointed to
|
| 7038 |
+
does not exist, the symbolic link is said to be a “dangling” symbolic
|
| 7039 |
+
link. — *end note*]
|
| 7040 |
|
| 7041 |
### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
|
| 7042 |
|
| 7043 |
Conformance is specified in terms of behavior. Ideal behavior is not
|
| 7044 |
always implementable, so the conformance subclauses take that into
|
| 7045 |
account.
|
| 7046 |
|
| 7047 |
#### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
|
| 7048 |
|
| 7049 |
+
Some behavior is specified by reference to POSIX [[fs.norm.ref]]. How
|
| 7050 |
such behavior is actually implemented is unspecified.
|
| 7051 |
|
| 7052 |
[*Note 1*: This constitutes an “as if” rule allowing implementations to
|
| 7053 |
call native operating system or other APIs. — *end note*]
|
| 7054 |
|
| 7055 |
+
Implementations should provide such behavior as it is defined by POSIX.
|
| 7056 |
+
Implementations shall document any behavior that differs from the
|
| 7057 |
+
behavior defined by POSIX. Implementations that do not support exact
|
| 7058 |
+
POSIX behavior should provide behavior as close to POSIX behavior as is
|
| 7059 |
+
reasonable given the limitations of actual operating systems and file
|
| 7060 |
+
systems. If an implementation cannot provide any reasonable behavior,
|
| 7061 |
+
the implementation shall report an error as specified in
|
| 7062 |
+
[[fs.err.report]].
|
| 7063 |
|
| 7064 |
[*Note 2*: This allows users to rely on an exception being thrown or an
|
| 7065 |
error code being set when an implementation cannot provide any
|
| 7066 |
reasonable behavior. — *end note*]
|
| 7067 |
|
|
|
|
| 7074 |
required to support those features on the FAT file system but instead
|
| 7075 |
are required to report an error as described above. — *end example*]
|
| 7076 |
|
| 7077 |
#### Operating system dependent behavior conformance <a id="fs.conform.os">[[fs.conform.os]]</a>
|
| 7078 |
|
| 7079 |
+
Behavior that is specified as being *operating system dependent* is
|
| 7080 |
+
dependent upon the behavior and characteristics of an operating system.
|
| 7081 |
+
The operating system an implementation is dependent upon is
|
| 7082 |
+
*implementation-defined*.
|
| 7083 |
|
| 7084 |
It is permissible for an implementation to be dependent upon an
|
| 7085 |
operating system emulator rather than the actual underlying operating
|
| 7086 |
system.
|
| 7087 |
|
| 7088 |
#### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
|
| 7089 |
|
| 7090 |
+
A *file system race* is the condition that occurs when multiple threads,
|
| 7091 |
+
processes, or computers interleave access and modification of the same
|
| 7092 |
+
object within a file system. Behavior is undefined if calls to functions
|
| 7093 |
+
provided by subclause [[fs.race.behavior]] introduce a file system
|
| 7094 |
+
race.
|
| 7095 |
|
| 7096 |
If the possibility of a file system race would make it unreliable for a
|
| 7097 |
program to test for a precondition before calling a function described
|
| 7098 |
+
herein, *Preconditions:* is not specified for the function.
|
| 7099 |
|
| 7100 |
[*Note 1*: As a design practice, preconditions are not specified when
|
| 7101 |
it is unreasonable for a program to detect them prior to calling the
|
| 7102 |
function. — *end note*]
|
| 7103 |
|
| 7104 |
### Normative references <a id="fs.norm.ref">[[fs.norm.ref]]</a>
|
| 7105 |
|
| 7106 |
+
Subclause [[filesystems]] mentions commercially available operating
|
| 7107 |
+
systems for purposes of exposition.[^41]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7108 |
|
| 7109 |
### Requirements <a id="fs.req">[[fs.req]]</a>
|
| 7110 |
|
| 7111 |
+
Throughout subclause [[filesystems]], `char`, `wchar_t`, `char8_t`,
|
| 7112 |
+
`char16_t`, and `char32_t` are collectively called *encoded character
|
| 7113 |
+
types*.
|
| 7114 |
|
| 7115 |
Functions with template parameters named `EcharT` shall not participate
|
| 7116 |
in overload resolution unless `EcharT` is one of the encoded character
|
| 7117 |
types.
|
| 7118 |
|
| 7119 |
+
Template parameters named `InputIterator` shall meet the
|
| 7120 |
+
*Cpp17InputIterator* requirements [[input.iterators]] and shall have a
|
| 7121 |
+
value type that is one of the encoded character types.
|
| 7122 |
|
| 7123 |
[*Note 1*: Use of an encoded character type implies an associated
|
| 7124 |
character set and encoding. Since `signed char` and `unsigned char` have
|
| 7125 |
no implied character set and encoding, they are not included as
|
| 7126 |
permitted types. — *end note*]
|
| 7127 |
|
| 7128 |
+
Template parameters named `Allocator` shall meet the *Cpp17Allocator*
|
| 7129 |
+
requirements ([[cpp17.allocator]]).
|
| 7130 |
|
| 7131 |
#### Namespaces and headers <a id="fs.req.namespace">[[fs.req.namespace]]</a>
|
| 7132 |
|
| 7133 |
+
Unless otherwise specified, references to entities described in
|
| 7134 |
+
subclause [[filesystems]] are assumed to be qualified with
|
| 7135 |
+
`::std::filesystem::`.
|
| 7136 |
|
| 7137 |
### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
|
| 7138 |
|
| 7139 |
``` cpp
|
| 7140 |
+
#include <compare> // see [compare.syn]
|
| 7141 |
+
|
| 7142 |
namespace std::filesystem {
|
| 7143 |
// [fs.class.path], paths
|
| 7144 |
class path;
|
| 7145 |
|
| 7146 |
// [fs.path.nonmember], path non-member functions
|
| 7147 |
void swap(path& lhs, path& rhs) noexcept;
|
| 7148 |
size_t hash_value(const path& p) noexcept;
|
| 7149 |
|
| 7150 |
+
// [fs.class.filesystem.error], filesystem errors
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7151 |
class filesystem_error;
|
| 7152 |
|
| 7153 |
+
// [fs.class.directory.entry], directory entries
|
| 7154 |
class directory_entry;
|
| 7155 |
|
| 7156 |
+
// [fs.class.directory.iterator], directory iterators
|
| 7157 |
class directory_iterator;
|
| 7158 |
|
| 7159 |
// [fs.dir.itr.nonmembers], range access for directory iterators
|
| 7160 |
directory_iterator begin(directory_iterator iter) noexcept;
|
| 7161 |
directory_iterator end(const directory_iterator&) noexcept;
|
|
|
|
| 7165 |
|
| 7166 |
// [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
|
| 7167 |
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 7168 |
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
|
| 7169 |
|
| 7170 |
+
// [fs.class.file.status], file status
|
| 7171 |
class file_status;
|
| 7172 |
|
| 7173 |
struct space_info {
|
| 7174 |
uintmax_t capacity;
|
| 7175 |
uintmax_t free;
|
| 7176 |
uintmax_t available;
|
| 7177 |
+
|
| 7178 |
+
friend bool operator==(const space_info&, const space_info&) = default;
|
| 7179 |
};
|
| 7180 |
|
| 7181 |
// [fs.enum], enumerations
|
| 7182 |
enum class file_type;
|
| 7183 |
enum class perms;
|
| 7184 |
enum class perm_options;
|
| 7185 |
enum class copy_options;
|
| 7186 |
enum class directory_options;
|
| 7187 |
|
| 7188 |
+
using file_time_type = chrono::time_point<chrono::file_clock>;
|
| 7189 |
|
| 7190 |
// [fs.op.funcs], filesystem operations
|
| 7191 |
+
path absolute(const path& p);
|
| 7192 |
+
path absolute(const path& p, error_code& ec);
|
| 7193 |
|
| 7194 |
+
path canonical(const path& p);
|
| 7195 |
path canonical(const path& p, error_code& ec);
|
|
|
|
| 7196 |
|
| 7197 |
void copy(const path& from, const path& to);
|
| 7198 |
+
void copy(const path& from, const path& to, error_code& ec);
|
| 7199 |
void copy(const path& from, const path& to, copy_options options);
|
| 7200 |
void copy(const path& from, const path& to, copy_options options,
|
| 7201 |
+
error_code& ec);
|
| 7202 |
|
| 7203 |
bool copy_file(const path& from, const path& to);
|
| 7204 |
+
bool copy_file(const path& from, const path& to, error_code& ec);
|
| 7205 |
bool copy_file(const path& from, const path& to, copy_options option);
|
| 7206 |
bool copy_file(const path& from, const path& to, copy_options option,
|
| 7207 |
+
error_code& ec);
|
| 7208 |
|
| 7209 |
void copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 7210 |
void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 7211 |
error_code& ec) noexcept;
|
| 7212 |
|
| 7213 |
bool create_directories(const path& p);
|
| 7214 |
+
bool create_directories(const path& p, error_code& ec);
|
| 7215 |
|
| 7216 |
bool create_directory(const path& p);
|
| 7217 |
bool create_directory(const path& p, error_code& ec) noexcept;
|
| 7218 |
|
| 7219 |
bool create_directory(const path& p, const path& attributes);
|
|
|
|
| 7235 |
path current_path();
|
| 7236 |
path current_path(error_code& ec);
|
| 7237 |
void current_path(const path& p);
|
| 7238 |
void current_path(const path& p, error_code& ec) noexcept;
|
| 7239 |
|
| 7240 |
+
bool equivalent(const path& p1, const path& p2);
|
| 7241 |
+
bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 7242 |
+
|
| 7243 |
bool exists(file_status s) noexcept;
|
| 7244 |
bool exists(const path& p);
|
| 7245 |
bool exists(const path& p, error_code& ec) noexcept;
|
| 7246 |
|
|
|
|
|
|
|
|
|
|
| 7247 |
uintmax_t file_size(const path& p);
|
| 7248 |
uintmax_t file_size(const path& p, error_code& ec) noexcept;
|
| 7249 |
|
| 7250 |
uintmax_t hard_link_count(const path& p);
|
| 7251 |
uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
|
|
|
| 7261 |
bool is_directory(file_status s) noexcept;
|
| 7262 |
bool is_directory(const path& p);
|
| 7263 |
bool is_directory(const path& p, error_code& ec) noexcept;
|
| 7264 |
|
| 7265 |
bool is_empty(const path& p);
|
| 7266 |
+
bool is_empty(const path& p, error_code& ec);
|
| 7267 |
|
| 7268 |
bool is_fifo(file_status s) noexcept;
|
| 7269 |
bool is_fifo(const path& p);
|
| 7270 |
bool is_fifo(const path& p, error_code& ec) noexcept;
|
| 7271 |
|
|
|
|
| 7308 |
|
| 7309 |
bool remove(const path& p);
|
| 7310 |
bool remove(const path& p, error_code& ec) noexcept;
|
| 7311 |
|
| 7312 |
uintmax_t remove_all(const path& p);
|
| 7313 |
+
uintmax_t remove_all(const path& p, error_code& ec);
|
| 7314 |
|
| 7315 |
void rename(const path& from, const path& to);
|
| 7316 |
void rename(const path& from, const path& to, error_code& ec) noexcept;
|
| 7317 |
|
| 7318 |
void resize_file(const path& p, uintmax_t size);
|
|
|
|
| 7335 |
path weakly_canonical(const path& p);
|
| 7336 |
path weakly_canonical(const path& p, error_code& ec);
|
| 7337 |
}
|
| 7338 |
```
|
| 7339 |
|
| 7340 |
+
Implementations should ensure that the resolution and range of
|
| 7341 |
+
`file_time_type` reflect the operating system dependent resolution and
|
| 7342 |
+
range of file time values.
|
|
|
|
|
|
|
| 7343 |
|
| 7344 |
### Error reporting <a id="fs.err.report">[[fs.err.report]]</a>
|
| 7345 |
|
| 7346 |
Filesystem library functions often provide two overloads, one that
|
| 7347 |
throws an exception to report file system errors, and another that sets
|
|
|
|
| 7387 |
appropriate for the specific operating system dependent error.
|
| 7388 |
Otherwise, `clear()` is called on the `error_code&` argument.
|
| 7389 |
|
| 7390 |
### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
|
| 7391 |
|
| 7392 |
+
An object of class `path` represents a path and contains a pathname.
|
| 7393 |
+
Such an object is concerned only with the lexical and syntactic aspects
|
| 7394 |
+
of a path. The path does not necessarily exist in external storage, and
|
| 7395 |
+
the pathname is not necessarily valid for the current operating system
|
| 7396 |
+
or for a particular file system.
|
|
|
|
| 7397 |
|
| 7398 |
[*Note 1*: Class `path` is used to support the differences between the
|
| 7399 |
string types used by different operating systems to represent pathnames,
|
| 7400 |
and to perform conversions between encodings when
|
| 7401 |
necessary. — *end note*]
|
| 7402 |
|
| 7403 |
+
A *path* is a sequence of elements that identify the location of a file
|
| 7404 |
+
within a filesystem. The elements are the *root-name*ₒₚₜ ,
|
| 7405 |
+
*root-directory*ₒₚₜ , and an optional sequence of *filename*s
|
| 7406 |
+
[[fs.path.generic]]. The maximum number of elements in the sequence is
|
| 7407 |
+
operating system dependent [[fs.conform.os]].
|
| 7408 |
+
|
| 7409 |
+
An *absolute path* is a path that unambiguously identifies the location
|
| 7410 |
+
of a file without reference to an additional starting location. The
|
| 7411 |
+
elements of a path that determine if it is absolute are operating system
|
| 7412 |
+
dependent. A *relative path* is a path that is not absolute, and as
|
| 7413 |
+
such, only unambiguously identifies the location of a file when resolved
|
| 7414 |
+
relative to an implied starting location. The elements of a path that
|
| 7415 |
+
determine if it is relative are operating system dependent.
|
| 7416 |
+
|
| 7417 |
+
[*Note 2*: Pathnames “.” and “..” are relative paths. — *end note*]
|
| 7418 |
+
|
| 7419 |
+
A *pathname* is a character string that represents the name of a path.
|
| 7420 |
+
Pathnames are formatted according to the generic pathname format grammar
|
| 7421 |
+
[[fs.path.generic]] or according to an operating system dependent
|
| 7422 |
+
*native pathname format* accepted by the host operating system.
|
| 7423 |
+
|
| 7424 |
+
*Pathname resolution* is the operating system dependent mechanism for
|
| 7425 |
+
resolving a pathname to a particular file in a file hierarchy. There may
|
| 7426 |
+
be multiple pathnames that resolve to the same file.
|
| 7427 |
+
|
| 7428 |
+
[*Example 1*: POSIX specifies the mechanism in section 4.11, Pathname
|
| 7429 |
+
resolution. — *end example*]
|
| 7430 |
+
|
| 7431 |
``` cpp
|
| 7432 |
namespace std::filesystem {
|
| 7433 |
class path {
|
| 7434 |
public:
|
| 7435 |
using value_type = see below;
|
|
|
|
| 7460 |
path& operator=(string_type&& source);
|
| 7461 |
path& assign(string_type&& source);
|
| 7462 |
template<class Source>
|
| 7463 |
path& operator=(const Source& source);
|
| 7464 |
template<class Source>
|
| 7465 |
+
path& assign(const Source& source);
|
| 7466 |
template<class InputIterator>
|
| 7467 |
path& assign(InputIterator first, InputIterator last);
|
| 7468 |
|
| 7469 |
// [fs.path.append], appends
|
| 7470 |
path& operator/=(const path& p);
|
|
|
|
| 7496 |
path& remove_filename();
|
| 7497 |
path& replace_filename(const path& replacement);
|
| 7498 |
path& replace_extension(const path& replacement = path());
|
| 7499 |
void swap(path& rhs) noexcept;
|
| 7500 |
|
| 7501 |
+
// [fs.path.nonmember], non-member operators
|
| 7502 |
+
friend bool operator==(const path& lhs, const path& rhs) noexcept;
|
| 7503 |
+
friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
|
| 7504 |
+
|
| 7505 |
+
friend path operator/ (const path& lhs, const path& rhs);
|
| 7506 |
+
|
| 7507 |
// [fs.path.native.obs], native format observers
|
| 7508 |
const string_type& native() const noexcept;
|
| 7509 |
const value_type* c_str() const noexcept;
|
| 7510 |
operator string_type() const;
|
| 7511 |
|
|
|
|
| 7513 |
class Allocator = allocator<EcharT>>
|
| 7514 |
basic_string<EcharT, traits, Allocator>
|
| 7515 |
string(const Allocator& a = Allocator()) const;
|
| 7516 |
std::string string() const;
|
| 7517 |
std::wstring wstring() const;
|
| 7518 |
+
std::u8string u8string() const;
|
| 7519 |
std::u16string u16string() const;
|
| 7520 |
std::u32string u32string() const;
|
| 7521 |
|
| 7522 |
// [fs.path.generic.obs], generic format observers
|
| 7523 |
template<class EcharT, class traits = char_traits<EcharT>,
|
| 7524 |
class Allocator = allocator<EcharT>>
|
| 7525 |
basic_string<EcharT, traits, Allocator>
|
| 7526 |
generic_string(const Allocator& a = Allocator()) const;
|
| 7527 |
std::string generic_string() const;
|
| 7528 |
std::wstring generic_wstring() const;
|
| 7529 |
+
std::u8string generic_u8string() const;
|
| 7530 |
std::u16string generic_u16string() const;
|
| 7531 |
std::u32string generic_u32string() const;
|
| 7532 |
|
| 7533 |
// [fs.path.compare], compare
|
| 7534 |
int compare(const path& p) const noexcept;
|
|
|
|
| 7545 |
path filename() const;
|
| 7546 |
path stem() const;
|
| 7547 |
path extension() const;
|
| 7548 |
|
| 7549 |
// [fs.path.query], query
|
| 7550 |
+
[[nodiscard]] bool empty() const noexcept;
|
| 7551 |
bool has_root_name() const;
|
| 7552 |
bool has_root_directory() const;
|
| 7553 |
bool has_root_path() const;
|
| 7554 |
bool has_relative_path() const;
|
| 7555 |
bool has_parent_path() const;
|
|
|
|
| 7568 |
class iterator;
|
| 7569 |
using const_iterator = iterator;
|
| 7570 |
|
| 7571 |
iterator begin() const;
|
| 7572 |
iterator end() const;
|
| 7573 |
+
|
| 7574 |
+
// [fs.path.io], path inserter and extractor
|
| 7575 |
+
template<class charT, class traits>
|
| 7576 |
+
friend basic_ostream<charT, traits>&
|
| 7577 |
+
operator<<(basic_ostream<charT, traits>& os, const path& p);
|
| 7578 |
+
template<class charT, class traits>
|
| 7579 |
+
friend basic_istream<charT, traits>&
|
| 7580 |
+
operator>>(basic_istream<charT, traits>& is, path& p);
|
| 7581 |
};
|
| 7582 |
}
|
| 7583 |
```
|
| 7584 |
|
| 7585 |
`value_type` is a `typedef` for the operating system dependent encoded
|
| 7586 |
character type used to represent pathnames.
|
| 7587 |
|
| 7588 |
The value of the `preferred_separator` member is the operating system
|
| 7589 |
+
dependent *preferred-separator* character [[fs.path.generic]].
|
| 7590 |
|
| 7591 |
+
[*Example 2*: For POSIX-based operating systems, `value_type` is `char`
|
| 7592 |
and `preferred_separator` is the slash character (`'/'`). For
|
| 7593 |
Windows-based operating systems, `value_type` is `wchar_t` and
|
| 7594 |
`preferred_separator` is the backslash character
|
| 7595 |
(`L'\\'`). — *end example*]
|
| 7596 |
|
|
|
|
| 7638 |
``` bnf
|
| 7639 |
fallback-separator:
|
| 7640 |
/, if *preferred-separator* is not /
|
| 7641 |
```
|
| 7642 |
|
| 7643 |
+
A *filename* is the name of a file. The *dot* and *dot-dot* filenames,
|
| 7644 |
+
consisting solely of one and two period characters respectively, have
|
| 7645 |
+
special meaning. The following characteristics of filenames are
|
| 7646 |
+
operating system dependent:
|
| 7647 |
+
|
| 7648 |
+
- The permitted characters. \[*Example 1*: Some operating systems
|
| 7649 |
+
prohibit the ASCII control characters (0x00 – 0x1F) in
|
| 7650 |
+
filenames. — *end example*] \[*Note 1*: For wide portability, users
|
| 7651 |
+
may wish to limit *filename* characters to the POSIX Portable Filename
|
| 7652 |
+
Character Set:
|
| 7653 |
`A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
|
| 7654 |
`a b c d e f g h i j k l m n o p q r s t u v w x y z`
|
| 7655 |
`0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
|
| 7656 |
+
- The maximum permitted length.
|
| 7657 |
+
- Filenames that are not permitted.
|
| 7658 |
+
- Filenames that have special meaning.
|
| 7659 |
+
- Case awareness and sensitivity during path resolution.
|
| 7660 |
+
- Special rules that may apply to file types other than regular files,
|
| 7661 |
+
such as directories.
|
| 7662 |
|
| 7663 |
Except in a *root-name*, multiple successive *directory-separator*
|
| 7664 |
characters are considered to be the same as one *directory-separator*
|
| 7665 |
character.
|
| 7666 |
|
| 7667 |
+
The dot filename is treated as a reference to the current directory. The
|
| 7668 |
+
dot-dot filename is treated as a reference to the parent directory. What
|
| 7669 |
+
the dot-dot filename refers to relative to *root-directory* is
|
|
|
|
| 7670 |
*implementation-defined*. Specific filenames may have special meanings
|
| 7671 |
for a particular operating system.
|
| 7672 |
|
| 7673 |
+
A *root-name* identifies the starting location for pathname resolution
|
| 7674 |
+
[[fs.class.path]]. If there are no operating system dependent
|
| 7675 |
*root-name*s, at least one *implementation-defined* *root-name* is
|
| 7676 |
required.
|
| 7677 |
|
| 7678 |
[*Note 2*: Many operating systems define a name beginning with two
|
| 7679 |
*directory-separator* characters as a *root-name* that identifies
|
|
|
|
| 7686 |
|
| 7687 |
[*Note 3*: On a POSIX-like operating system, it is impossible to have a
|
| 7688 |
*root-name* and a *relative-path* without an intervening
|
| 7689 |
*root-directory* element. — *end note*]
|
| 7690 |
|
| 7691 |
+
*Normalization* of a generic format pathname means:
|
| 7692 |
|
| 7693 |
+
1. If the path is empty, stop.
|
| 7694 |
+
2. Replace each slash character in the *root-name* with a
|
| 7695 |
+
*preferred-separator*.
|
| 7696 |
+
3. Replace each *directory-separator* with a *preferred-separator*.
|
| 7697 |
+
\[*Note 4*: The generic pathname grammar [[fs.path.generic]] defines
|
| 7698 |
+
*directory-separator* as one or more slashes and
|
| 7699 |
+
*preferred-separator*s. — *end note*]
|
| 7700 |
+
4. Remove each dot filename and any immediately following
|
| 7701 |
+
*directory-separator*.
|
| 7702 |
+
5. As long as any appear, remove a non-dot-dot filename immediately
|
| 7703 |
+
followed by a *directory-separator* and a dot-dot filename, along
|
| 7704 |
+
with any immediately following *directory-separator*.
|
| 7705 |
+
6. If there is a *root-directory*, remove all dot-dot filenames and any
|
| 7706 |
+
*directory-separator*s immediately following them. \[*Note 5*: These
|
| 7707 |
+
dot-dot filenames attempt to refer to nonexistent parent
|
| 7708 |
+
directories. — *end note*]
|
| 7709 |
+
7. If the last filename is dot-dot, remove any trailing
|
| 7710 |
+
*directory-separator*.
|
| 7711 |
+
8. If the path is empty, add a dot.
|
| 7712 |
+
|
| 7713 |
+
The result of normalization is a path in *normal form*, which is said to
|
| 7714 |
+
be *normalized*.
|
| 7715 |
+
|
| 7716 |
+
#### Conversions <a id="fs.path.cvt">[[fs.path.cvt]]</a>
|
| 7717 |
+
|
| 7718 |
+
##### Argument format conversions <a id="fs.path.fmt.cvt">[[fs.path.fmt.cvt]]</a>
|
| 7719 |
|
| 7720 |
[*Note 1*:
|
| 7721 |
|
| 7722 |
+
The format conversions described in this subclause are not applied on
|
| 7723 |
POSIX-based operating systems because on these systems:
|
| 7724 |
|
| 7725 |
- The generic format is acceptable as a native path.
|
| 7726 |
- There is no need to distinguish between native format and generic
|
| 7727 |
format in function arguments.
|
|
|
|
| 7730 |
|
| 7731 |
— *end note*]
|
| 7732 |
|
| 7733 |
Several functions are defined to accept *detected-format* arguments,
|
| 7734 |
which are character sequences. A detected-format argument represents a
|
| 7735 |
+
path using either a pathname in the generic format [[fs.path.generic]]
|
| 7736 |
+
or a pathname in the native format [[fs.class.path]]. Such an argument
|
| 7737 |
+
is taken to be in the generic format if and only if it matches the
|
| 7738 |
+
generic format and is not acceptable to the operating system as a native
|
| 7739 |
+
path.
|
| 7740 |
|
| 7741 |
[*Note 2*: Some operating systems may have no unambiguous way to
|
| 7742 |
distinguish between native format and generic format arguments. This is
|
| 7743 |
by design as it simplifies use for operating systems that do not require
|
| 7744 |
disambiguation. An implementation for an operating system where
|
|
|
|
| 7757 |
If the native format requires paths for regular files to be formatted
|
| 7758 |
differently from paths for directories, the path shall be treated as a
|
| 7759 |
directory path if its last element is a *directory-separator*, otherwise
|
| 7760 |
it shall be treated as a path to a regular file.
|
| 7761 |
|
| 7762 |
+
[*Note 4*: A path stores a native format pathname
|
| 7763 |
+
[[fs.path.native.obs]] and acts as if it also stores a generic format
|
| 7764 |
pathname, related as given below. The implementation may generate the
|
| 7765 |
generic format pathname based on the native format pathname (and
|
| 7766 |
possibly other information) when requested. — *end note*]
|
| 7767 |
|
| 7768 |
When a path is constructed from or is assigned a single representation
|
|
|
|
| 7775 |
as appropriate) if any such value does so; *q* is otherwise unspecified.
|
| 7776 |
|
| 7777 |
[*Note 5*: If *q* is the result of converting any path at all, it is
|
| 7778 |
the result of converting *p*. — *end note*]
|
| 7779 |
|
| 7780 |
+
##### Type and encoding conversions <a id="fs.path.type.cvt">[[fs.path.type.cvt]]</a>
|
| 7781 |
+
|
| 7782 |
+
The *native encoding* of an ordinary character string is the operating
|
| 7783 |
+
system dependent current encoding for pathnames [[fs.class.path]]. The
|
| 7784 |
+
*native encoding* for wide character strings is the
|
| 7785 |
+
implementation-defined execution wide-character set encoding
|
| 7786 |
+
[[lex.charset]].
|
| 7787 |
|
| 7788 |
For member function arguments that take character sequences representing
|
| 7789 |
paths and for member functions returning strings, value type and
|
| 7790 |
encoding conversion is performed if the value type of the argument or
|
| 7791 |
return value differs from `path::value_type`. For the argument or return
|
| 7792 |
value, the method of conversion and the encoding to be converted to is
|
| 7793 |
determined by its value type:
|
| 7794 |
|
| 7795 |
+
- `char`: The encoding is the native ordinary encoding. The method of
|
| 7796 |
+
conversion, if any, is operating system dependent. \[*Note 6*: For
|
| 7797 |
+
POSIX-based operating systems `path::value_type` is `char` so no
|
| 7798 |
+
conversion from `char` value type arguments or to `char` value type
|
| 7799 |
+
return values is performed. For Windows-based operating systems, the
|
| 7800 |
+
native ordinary encoding is determined by calling a Windows API
|
|
|
|
| 7801 |
function. — *end note*] \[*Note 7*: This results in behavior
|
| 7802 |
identical to other C and C++ standard library functions that perform
|
| 7803 |
+
file operations using ordinary character strings to identify paths.
|
| 7804 |
Changing this behavior would be surprising and error
|
| 7805 |
prone. — *end note*]
|
| 7806 |
+
- `wchar_t`: The encoding is the native wide encoding. The method of
|
| 7807 |
+
conversion is unspecified. \[*Note 8*: For Windows-based operating
|
| 7808 |
+
systems `path::value_type` is `wchar_t` so no conversion from
|
| 7809 |
+
`wchar_t` value type arguments or to `wchar_t` value type return
|
| 7810 |
+
values is performed. — *end note*]
|
| 7811 |
+
- `char8_t`: The encoding is UTF-8. The method of conversion is
|
| 7812 |
+
unspecified.
|
| 7813 |
- `char16_t`: The encoding is UTF-16. The method of conversion is
|
| 7814 |
unspecified.
|
| 7815 |
- `char32_t`: The encoding is UTF-32. The method of conversion is
|
| 7816 |
unspecified.
|
| 7817 |
|
| 7818 |
If the encoding being converted to has no representation for source
|
| 7819 |
characters, the resulting converted characters, if any, are unspecified.
|
| 7820 |
Implementations should not modify member function arguments if already
|
| 7821 |
of type `path::value_type`.
|
| 7822 |
|
| 7823 |
+
#### Requirements <a id="fs.path.req">[[fs.path.req]]</a>
|
| 7824 |
|
| 7825 |
+
In addition to the requirements [[fs.req]], function template parameters
|
| 7826 |
+
named `Source` shall be one of:
|
| 7827 |
|
| 7828 |
- `basic_string<EcharT, traits, Allocator>`. A function argument
|
| 7829 |
`const Source&` `source` shall have an effective range
|
| 7830 |
\[`source.begin()`, `source.end()`).
|
| 7831 |
- `basic_string_view<EcharT, traits>`. A function argument
|
| 7832 |
`const Source&` `source` shall have an effective range
|
| 7833 |
\[`source.begin()`, `source.end()`).
|
| 7834 |
+
- A type meeting the *Cpp17InputIterator* requirements that iterates
|
| 7835 |
+
over a NTCTS. The value type shall be an encoded character type. A
|
| 7836 |
+
function argument `const Source&` `source` shall have an effective
|
| 7837 |
+
range \[`source`, `end`) where `end` is the first iterator value with
|
| 7838 |
+
an element value equal to `iterator_traits<Source>::value_type()`.
|
| 7839 |
- A character array that after array-to-pointer decay results in a
|
| 7840 |
pointer to the start of a NTCTS. The value type shall be an encoded
|
| 7841 |
character type. A function argument `const Source&` `source` shall
|
| 7842 |
have an effective range \[`source`, `end`) where `end` is the first
|
| 7843 |
iterator value with an element value equal to
|
| 7844 |
`iterator_traits<decay_t<Source>>::value_type()`.
|
| 7845 |
|
| 7846 |
Functions taking template parameters named `Source` shall not
|
| 7847 |
+
participate in overload resolution unless `Source` denotes a type other
|
| 7848 |
+
than `path`, and either
|
| 7849 |
|
| 7850 |
- `Source` is a specialization of `basic_string` or `basic_string_view`,
|
| 7851 |
or
|
| 7852 |
- the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
|
| 7853 |
+
valid and denotes a possibly `const` encoded character type
|
| 7854 |
+
[[temp.deduct]].
|
| 7855 |
|
| 7856 |
+
[*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
|
| 7857 |
+
above and their encodings convert to `path::value_type` and its
|
| 7858 |
encoding. — *end note*]
|
| 7859 |
|
| 7860 |
Arguments of type `Source` shall not be null pointers.
|
| 7861 |
|
| 7862 |
+
#### Members <a id="fs.path.member">[[fs.path.member]]</a>
|
| 7863 |
|
| 7864 |
+
##### Constructors <a id="fs.path.construct">[[fs.path.construct]]</a>
|
| 7865 |
|
| 7866 |
``` cpp
|
| 7867 |
path() noexcept;
|
| 7868 |
```
|
| 7869 |
|
| 7870 |
+
*Ensures:* `empty() == true`.
|
|
|
|
|
|
|
| 7871 |
|
| 7872 |
``` cpp
|
| 7873 |
path(const path& p);
|
| 7874 |
path(path&& p) noexcept;
|
| 7875 |
```
|
|
|
|
| 7882 |
``` cpp
|
| 7883 |
path(string_type&& source, format fmt = auto_format);
|
| 7884 |
```
|
| 7885 |
|
| 7886 |
*Effects:* Constructs an object of class `path` for which the pathname
|
| 7887 |
+
in the detected-format of `source` has the original value of `source`
|
| 7888 |
+
[[fs.path.fmt.cvt]], converting format if required [[fs.path.fmt.cvt]].
|
| 7889 |
+
`source` is left in a valid but unspecified state.
|
|
|
|
| 7890 |
|
| 7891 |
``` cpp
|
| 7892 |
template<class Source>
|
| 7893 |
path(const Source& source, format fmt = auto_format);
|
| 7894 |
template<class InputIterator>
|
| 7895 |
path(InputIterator first, InputIterator last, format fmt = auto_format);
|
| 7896 |
```
|
| 7897 |
|
| 7898 |
+
*Effects:* Let `s` be the effective range of `source` [[fs.path.req]] or
|
| 7899 |
+
the range \[`first`, `last`), with the encoding converted if
|
| 7900 |
+
required [[fs.path.cvt]]. Finds the detected-format of `s`
|
| 7901 |
+
[[fs.path.fmt.cvt]] and constructs an object of class `path` for which
|
| 7902 |
+
the pathname in that format is `s`.
|
| 7903 |
|
| 7904 |
``` cpp
|
| 7905 |
template<class Source>
|
| 7906 |
path(const Source& source, const locale& loc, format fmt = auto_format);
|
| 7907 |
template<class InputIterator>
|
| 7908 |
path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
|
| 7909 |
```
|
| 7910 |
|
| 7911 |
+
*Mandates:* The value type of `Source` and `InputIterator` is `char`.
|
| 7912 |
|
| 7913 |
*Effects:* Let `s` be the effective range of `source` or the range
|
| 7914 |
\[`first`, `last`), after converting the encoding as follows:
|
| 7915 |
|
| 7916 |
- If `value_type` is `wchar_t`, converts to the native wide
|
| 7917 |
+
encoding [[fs.path.type.cvt]] using the
|
| 7918 |
`codecvt<wchar_t, char, mbstate_t>` facet of `loc`.
|
| 7919 |
- Otherwise a conversion is performed using the
|
| 7920 |
`codecvt<wchar_t, char, mbstate_t>` facet of `loc`, and then a second
|
| 7921 |
+
conversion to the current ordinary encoding.
|
| 7922 |
|
| 7923 |
+
Finds the detected-format of `s` [[fs.path.fmt.cvt]] and constructs an
|
| 7924 |
+
object of class `path` for which the pathname in that format is `s`.
|
| 7925 |
|
| 7926 |
[*Example 1*:
|
| 7927 |
|
| 7928 |
A string is to be read from a database that is encoded in ISO/IEC
|
| 7929 |
8859-1, and used to create a directory:
|
|
|
|
| 7937 |
```
|
| 7938 |
|
| 7939 |
For POSIX-based operating systems, the path is constructed by first
|
| 7940 |
using `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string`
|
| 7941 |
to a wide character string in the native wide
|
| 7942 |
+
encoding [[fs.path.type.cvt]]. The resulting wide string is then
|
| 7943 |
+
converted to an ordinary character pathname string in the current native
|
| 7944 |
+
ordinary encoding. If the native wide encoding is UTF-16 or UTF-32, and
|
| 7945 |
+
the current native ordinary encoding is UTF-8, all of the characters in
|
| 7946 |
the ISO/IEC 8859-1 character set will be converted to their Unicode
|
| 7947 |
+
representation, but for other native ordinary encodings some characters
|
| 7948 |
may have no representation.
|
| 7949 |
|
| 7950 |
For Windows-based operating systems, the path is constructed by using
|
| 7951 |
`latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string` to a
|
| 7952 |
UTF-16 encoded wide character pathname string. All of the characters in
|
| 7953 |
the ISO/IEC 8859-1 character set will be converted to their Unicode
|
| 7954 |
representation.
|
| 7955 |
|
| 7956 |
— *end example*]
|
| 7957 |
|
| 7958 |
+
##### Assignments <a id="fs.path.assign">[[fs.path.assign]]</a>
|
| 7959 |
|
| 7960 |
``` cpp
|
| 7961 |
path& operator=(const path& p);
|
| 7962 |
```
|
| 7963 |
|
|
|
|
| 7997 |
path& assign(const Source& source);
|
| 7998 |
template<class InputIterator>
|
| 7999 |
path& assign(InputIterator first, InputIterator last);
|
| 8000 |
```
|
| 8001 |
|
| 8002 |
+
*Effects:* Let `s` be the effective range of `source` [[fs.path.req]] or
|
| 8003 |
+
the range \[`first`, `last`), with the encoding converted if
|
| 8004 |
+
required [[fs.path.cvt]]. Finds the detected-format of `s`
|
| 8005 |
+
[[fs.path.fmt.cvt]] and sets the pathname in that format to `s`.
|
| 8006 |
|
| 8007 |
*Returns:* `*this`.
|
| 8008 |
|
| 8009 |
+
##### Appends <a id="fs.path.append">[[fs.path.append]]</a>
|
| 8010 |
|
| 8011 |
The append operations use `operator/=` to denote their semantic effect
|
| 8012 |
of appending *preferred-separator* when needed.
|
| 8013 |
|
| 8014 |
``` cpp
|
|
|
|
| 8031 |
pathname.
|
| 8032 |
|
| 8033 |
[*Example 2*:
|
| 8034 |
|
| 8035 |
Even if `//host` is interpreted as a *root-name*, both of the paths
|
| 8036 |
+
`path("//host")/"foo"` and `path("//host/")/"foo"` equal `"//host/foo"`
|
| 8037 |
+
(although the former might use backslash as the preferred separator).
|
| 8038 |
|
| 8039 |
Expression examples:
|
| 8040 |
|
| 8041 |
``` cpp
|
| 8042 |
// On POSIX,
|
| 8043 |
+
path("foo") /= path(""); // yields path("foo/")
|
| 8044 |
+
path("foo") /= path("/bar"); // yields path("/bar")
|
|
|
|
| 8045 |
|
| 8046 |
// On Windows,
|
| 8047 |
+
path("foo") /= path(""); // yields path("foo\{")}
|
| 8048 |
+
path("foo") /= path("/bar"); // yields path("/bar")
|
| 8049 |
+
path("foo") /= path("c:/bar"); // yields path("c:/bar")
|
| 8050 |
+
path("foo") /= path("c:"); // yields path("c:")
|
| 8051 |
+
path("c:") /= path(""); // yields path("c:")
|
| 8052 |
+
path("c:foo") /= path("/bar"); // yields path("c:/bar")
|
| 8053 |
+
path("c:foo") /= path("c:bar"); // yields path("c:foo\{bar")}
|
| 8054 |
```
|
| 8055 |
|
| 8056 |
— *end example*]
|
| 8057 |
|
| 8058 |
*Returns:* `*this`.
|
|
|
|
| 8071 |
path& append(InputIterator first, InputIterator last);
|
| 8072 |
```
|
| 8073 |
|
| 8074 |
*Effects:* Equivalent to: `return operator/=(path(first, last));`
|
| 8075 |
|
| 8076 |
+
##### Concatenation <a id="fs.path.concat">[[fs.path.concat]]</a>
|
| 8077 |
|
| 8078 |
``` cpp
|
| 8079 |
path& operator+=(const path& x);
|
| 8080 |
path& operator+=(const string_type& x);
|
| 8081 |
path& operator+=(basic_string_view<value_type> x);
|
| 8082 |
path& operator+=(const value_type* x);
|
|
|
|
| 8083 |
template<class Source>
|
| 8084 |
path& operator+=(const Source& x);
|
|
|
|
|
|
|
| 8085 |
template<class Source>
|
| 8086 |
path& concat(const Source& x);
|
| 8087 |
```
|
| 8088 |
|
| 8089 |
*Effects:* Appends `path(x).native()` to the pathname in the native
|
|
|
|
| 8092 |
[*Note 2*: This directly manipulates the value of `native()` and may
|
| 8093 |
not be portable between operating systems. — *end note*]
|
| 8094 |
|
| 8095 |
*Returns:* `*this`.
|
| 8096 |
|
| 8097 |
+
``` cpp
|
| 8098 |
+
path& operator+=(value_type x);
|
| 8099 |
+
template<class EcharT>
|
| 8100 |
+
path& operator+=(EcharT x);
|
| 8101 |
+
```
|
| 8102 |
+
|
| 8103 |
+
*Effects:* Equivalent to: `return *this += basic_string_view(&x, 1);`
|
| 8104 |
+
|
| 8105 |
``` cpp
|
| 8106 |
template<class InputIterator>
|
| 8107 |
path& concat(InputIterator first, InputIterator last);
|
| 8108 |
```
|
| 8109 |
|
| 8110 |
+
*Effects:* Equivalent to: `return *this += path(first, last);`
|
| 8111 |
|
| 8112 |
+
##### Modifiers <a id="fs.path.modifiers">[[fs.path.modifiers]]</a>
|
| 8113 |
|
| 8114 |
``` cpp
|
| 8115 |
void clear() noexcept;
|
| 8116 |
```
|
| 8117 |
|
| 8118 |
+
*Ensures:* `empty() == true`.
|
| 8119 |
|
| 8120 |
``` cpp
|
| 8121 |
path& make_preferred();
|
| 8122 |
```
|
| 8123 |
|
|
|
|
| 8155 |
|
| 8156 |
``` cpp
|
| 8157 |
path& remove_filename();
|
| 8158 |
```
|
| 8159 |
|
|
|
|
|
|
|
| 8160 |
*Effects:* Remove the generic format pathname of `filename()` from the
|
| 8161 |
generic format pathname.
|
| 8162 |
|
| 8163 |
+
*Ensures:* `!has_filename()`.
|
| 8164 |
+
|
| 8165 |
*Returns:* `*this`.
|
| 8166 |
|
| 8167 |
[*Example 4*:
|
| 8168 |
|
| 8169 |
``` cpp
|
|
|
|
| 8201 |
path& replace_extension(const path& replacement = path());
|
| 8202 |
```
|
| 8203 |
|
| 8204 |
*Effects:*
|
| 8205 |
|
| 8206 |
+
- Any existing `extension()` [[fs.path.decompose]] is removed from the
|
| 8207 |
+
pathname in the generic format, then
|
| 8208 |
- If `replacement` is not empty and does not begin with a dot character,
|
| 8209 |
a dot character is appended to the pathname in the generic format,
|
| 8210 |
then
|
| 8211 |
- `operator+=(replacement);`.
|
| 8212 |
|
|
|
|
| 8218 |
|
| 8219 |
*Effects:* Swaps the contents (in all formats) of the two paths.
|
| 8220 |
|
| 8221 |
*Complexity:* Constant time.
|
| 8222 |
|
| 8223 |
+
##### Native format observers <a id="fs.path.native.obs">[[fs.path.native.obs]]</a>
|
| 8224 |
|
| 8225 |
The string returned by all native format observers is in the native
|
| 8226 |
+
pathname format [[fs.class.path]].
|
| 8227 |
|
| 8228 |
``` cpp
|
| 8229 |
const string_type& native() const noexcept;
|
| 8230 |
```
|
| 8231 |
|
|
|
|
| 8233 |
|
| 8234 |
``` cpp
|
| 8235 |
const value_type* c_str() const noexcept;
|
| 8236 |
```
|
| 8237 |
|
| 8238 |
+
*Effects:* Equivalent to: `return native().c_str();`
|
| 8239 |
|
| 8240 |
``` cpp
|
| 8241 |
operator string_type() const;
|
| 8242 |
```
|
| 8243 |
|
|
|
|
| 8261 |
[[fs.path.cvt]].
|
| 8262 |
|
| 8263 |
``` cpp
|
| 8264 |
std::string string() const;
|
| 8265 |
std::wstring wstring() const;
|
| 8266 |
+
std::u8string u8string() const;
|
| 8267 |
std::u16string u16string() const;
|
| 8268 |
std::u32string u32string() const;
|
| 8269 |
```
|
| 8270 |
|
| 8271 |
+
*Returns:* `native()`.
|
| 8272 |
|
| 8273 |
*Remarks:* Conversion, if any, is performed as specified by
|
| 8274 |
+
[[fs.path.cvt]].
|
|
|
|
| 8275 |
|
| 8276 |
+
##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
|
| 8277 |
|
| 8278 |
Generic format observer functions return strings formatted according to
|
| 8279 |
+
the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
|
| 8280 |
+
character is used as the *directory-separator*.
|
| 8281 |
|
| 8282 |
[*Example 1*:
|
| 8283 |
|
| 8284 |
On an operating system that uses backslash as its *preferred-separator*,
|
| 8285 |
|
|
|
|
| 8305 |
[[fs.path.cvt]].
|
| 8306 |
|
| 8307 |
``` cpp
|
| 8308 |
std::string generic_string() const;
|
| 8309 |
std::wstring generic_wstring() const;
|
| 8310 |
+
std::u8string generic_u8string() const;
|
| 8311 |
std::u16string generic_u16string() const;
|
| 8312 |
std::u32string generic_u32string() const;
|
| 8313 |
```
|
| 8314 |
|
| 8315 |
*Returns:* The pathname in the generic format.
|
| 8316 |
|
| 8317 |
+
*Remarks:* Conversion, if any, is specified by [[fs.path.cvt]].
|
|
|
|
| 8318 |
|
| 8319 |
+
##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
|
| 8320 |
|
| 8321 |
``` cpp
|
| 8322 |
int compare(const path& p) const noexcept;
|
| 8323 |
```
|
| 8324 |
|
| 8325 |
*Returns:*
|
| 8326 |
|
| 8327 |
+
- Let `rootNameComparison` be the result of
|
| 8328 |
+
`this->root_name().native().compare(p.root_name().native())`. If
|
| 8329 |
+
`rootNameComparison` is not `0`, `rootNameComparison`.
|
| 8330 |
+
- Otherwise, if `!this->has_root_directory()` and
|
| 8331 |
+
`p.has_root_directory()`, a value less than `0`.
|
| 8332 |
+
- Otherwise, if `this->has_root_directory()` and
|
| 8333 |
+
`!p.has_root_directory()`, a value greater than `0`.
|
| 8334 |
+
- Otherwise, if `native()` for the elements of `this->relative_path()`
|
| 8335 |
+
are lexicographically less than `native()` for the elements of
|
| 8336 |
+
`p.relative_path()`, a value less than `0`.
|
| 8337 |
+
- Otherwise, if `native()` for the elements of `this->relative_path()`
|
| 8338 |
+
are lexicographically greater than `native()` for the elements of
|
| 8339 |
+
`p.relative_path()`, a value greater than `0`.
|
| 8340 |
+
- Otherwise, `0`.
|
| 8341 |
|
| 8342 |
``` cpp
|
| 8343 |
+
int compare(const string_type& s) const;
|
| 8344 |
int compare(basic_string_view<value_type> s) const;
|
| 8345 |
+
int compare(const value_type* s) const;
|
| 8346 |
```
|
| 8347 |
|
| 8348 |
+
*Effects:* Equivalent to: `return compare(path(s));`
|
| 8349 |
|
| 8350 |
+
##### Decomposition <a id="fs.path.decompose">[[fs.path.decompose]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8351 |
|
| 8352 |
``` cpp
|
| 8353 |
path root_name() const;
|
| 8354 |
```
|
| 8355 |
|
|
|
|
| 8372 |
``` cpp
|
| 8373 |
path relative_path() const;
|
| 8374 |
```
|
| 8375 |
|
| 8376 |
*Returns:* A `path` composed from the pathname in the generic format, if
|
| 8377 |
+
`empty()` is `false`, beginning with the first *filename* after
|
| 8378 |
+
`root_path()`. Otherwise, `path()`.
|
| 8379 |
|
| 8380 |
``` cpp
|
| 8381 |
path parent_path() const;
|
| 8382 |
```
|
| 8383 |
|
| 8384 |
+
*Returns:* `*this` if `has_relative_path()` is `false`, otherwise a path
|
| 8385 |
+
whose generic format pathname is the longest prefix of the generic
|
| 8386 |
+
format pathname of `*this` that produces one fewer element in its
|
| 8387 |
+
iteration.
|
| 8388 |
|
| 8389 |
``` cpp
|
| 8390 |
path filename() const;
|
| 8391 |
```
|
| 8392 |
|
|
|
|
| 8433 |
|
| 8434 |
``` cpp
|
| 8435 |
path extension() const;
|
| 8436 |
```
|
| 8437 |
|
| 8438 |
+
*Returns:* A path whose pathname in the generic format is the suffix of
|
| 8439 |
`filename()` not included in `stem()`.
|
| 8440 |
|
| 8441 |
[*Example 8*:
|
| 8442 |
|
| 8443 |
``` cpp
|
|
|
|
| 8456 |
|
| 8457 |
[*Note 5*: On non-POSIX operating systems, for a path `p`, it may not
|
| 8458 |
be the case that `p.stem() + p.extension() == p.filename()`, even though
|
| 8459 |
the generic format pathnames are the same. — *end note*]
|
| 8460 |
|
| 8461 |
+
##### Query <a id="fs.path.query">[[fs.path.query]]</a>
|
| 8462 |
|
| 8463 |
``` cpp
|
| 8464 |
+
[[nodiscard]] bool empty() const noexcept;
|
| 8465 |
```
|
| 8466 |
|
| 8467 |
+
*Returns:* `true` if the pathname in the generic format is empty,
|
| 8468 |
+
otherwise `false`.
|
| 8469 |
|
| 8470 |
``` cpp
|
| 8471 |
bool has_root_path() const;
|
| 8472 |
```
|
| 8473 |
|
|
|
|
| 8518 |
``` cpp
|
| 8519 |
bool is_absolute() const;
|
| 8520 |
```
|
| 8521 |
|
| 8522 |
*Returns:* `true` if the pathname in the native format contains an
|
| 8523 |
+
absolute path [[fs.class.path]], otherwise `false`.
|
| 8524 |
|
| 8525 |
[*Example 9*: `path("/").is_absolute()` is `true` for POSIX-based
|
| 8526 |
operating systems, and `false` for Windows-based operating
|
| 8527 |
systems. — *end example*]
|
| 8528 |
|
|
|
|
| 8530 |
bool is_relative() const;
|
| 8531 |
```
|
| 8532 |
|
| 8533 |
*Returns:* `!is_absolute()`.
|
| 8534 |
|
| 8535 |
+
##### Generation <a id="fs.path.gen">[[fs.path.gen]]</a>
|
| 8536 |
|
| 8537 |
``` cpp
|
| 8538 |
path lexically_normal() const;
|
| 8539 |
```
|
| 8540 |
|
| 8541 |
*Returns:* A path whose pathname in the generic format is the normal
|
| 8542 |
+
form [[fs.path.generic]] of the pathname in the generic format of
|
| 8543 |
`*this`.
|
| 8544 |
|
| 8545 |
[*Example 10*:
|
| 8546 |
|
| 8547 |
``` cpp
|
|
|
|
| 8558 |
``` cpp
|
| 8559 |
path lexically_relative(const path& base) const;
|
| 8560 |
```
|
| 8561 |
|
| 8562 |
*Returns:* `*this` made relative to `base`. Does not
|
| 8563 |
+
resolve [[fs.class.path]] symlinks. Does not first
|
| 8564 |
+
normalize [[fs.path.generic]] `*this` or `base`.
|
| 8565 |
+
|
| 8566 |
+
*Effects:* If:
|
| 8567 |
+
|
| 8568 |
+
- `root_name() != base.root_name()` is `true`, or
|
| 8569 |
+
- `is_absolute() != base.is_absolute()` is `true`, or
|
| 8570 |
+
- `!has_root_directory() && base.has_root_directory()` is `true`, or
|
| 8571 |
+
- any *filename* in `relative_path()` or `base.relative_path()` can be
|
| 8572 |
+
interpreted as a *root-name*,
|
| 8573 |
+
|
| 8574 |
+
returns `path()`.
|
| 8575 |
+
|
| 8576 |
+
[*Note 6*: On a POSIX implementation, no *filename* in a
|
| 8577 |
+
*relative-path* is acceptable as a *root-name*. — *end note*]
|
| 8578 |
+
|
| 8579 |
+
Determines the first mismatched element of `*this` and `base` as if by:
|
| 8580 |
|
| 8581 |
``` cpp
|
| 8582 |
auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
|
| 8583 |
```
|
| 8584 |
|
| 8585 |
Then,
|
| 8586 |
|
| 8587 |
- if `a == end()` and `b == base.end()`, returns `path(".")`; otherwise
|
| 8588 |
- let `n` be the number of *filename* elements in \[`b`, `base.end()`)
|
| 8589 |
+
that are not dot or dot-dot or empty, minus the number that are
|
| 8590 |
+
dot-dot. If `n<0,` returns `path()`; otherwise
|
| 8591 |
+
- if `n == 0` and `(a == end() || a->empty())`, returns `path(".")`;
|
| 8592 |
+
otherwise
|
| 8593 |
- returns an object of class `path` that is default-constructed,
|
| 8594 |
followed by
|
| 8595 |
- application of `operator/=(path(".."))` `n` times, and then
|
| 8596 |
- application of `operator/=` for each element in \[`a`, `end()`).
|
| 8597 |
|
|
|
|
| 8610 |
*directory-separator* characters will be backslashes rather than
|
| 8611 |
slashes, but that does not affect `path` equality.
|
| 8612 |
|
| 8613 |
— *end example*]
|
| 8614 |
|
| 8615 |
+
[*Note 7*: If symlink following semantics are desired, use the
|
| 8616 |
operational function `relative()`. — *end note*]
|
| 8617 |
|
| 8618 |
+
[*Note 8*: If normalization [[fs.path.generic]] is needed to ensure
|
| 8619 |
+
consistent matching of elements, apply `lexically_normal()` to `*this`,
|
| 8620 |
+
`base`, or both. — *end note*]
|
| 8621 |
|
| 8622 |
``` cpp
|
| 8623 |
path lexically_proximate(const path& base) const;
|
| 8624 |
```
|
| 8625 |
|
| 8626 |
*Returns:* If the value of `lexically_relative(base)` is not an empty
|
| 8627 |
path, return it. Otherwise return `*this`.
|
| 8628 |
|
| 8629 |
+
[*Note 9*: If symlink following semantics are desired, use the
|
| 8630 |
operational function `proximate()`. — *end note*]
|
| 8631 |
|
| 8632 |
+
[*Note 10*: If normalization [[fs.path.generic]] is needed to ensure
|
| 8633 |
+
consistent matching of elements, apply `lexically_normal()` to `*this`,
|
| 8634 |
+
`base`, or both. — *end note*]
|
| 8635 |
|
| 8636 |
+
#### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
|
| 8637 |
|
| 8638 |
Path iterators iterate over the elements of the pathname in the generic
|
| 8639 |
+
format [[fs.path.generic]].
|
| 8640 |
|
| 8641 |
+
A `path::iterator` is a constant iterator meeting all the requirements
|
| 8642 |
+
of a bidirectional iterator [[bidirectional.iterators]] except that, for
|
| 8643 |
+
dereferenceable iterators `a` and `b` of type `path::iterator` with
|
| 8644 |
+
`a == b`, there is no requirement that `*a` and `*b` are bound to the
|
| 8645 |
+
same object. Its `value_type` is `path`.
|
| 8646 |
|
| 8647 |
Calling any non-const member function of a `path` object invalidates all
|
| 8648 |
iterators referring to elements of that object.
|
| 8649 |
|
| 8650 |
For the elements of the pathname in the generic format, the forward
|
|
|
|
| 8671 |
iterator end() const;
|
| 8672 |
```
|
| 8673 |
|
| 8674 |
*Returns:* The end iterator.
|
| 8675 |
|
| 8676 |
+
#### Inserter and extractor <a id="fs.path.io">[[fs.path.io]]</a>
|
| 8677 |
+
|
| 8678 |
+
``` cpp
|
| 8679 |
+
template<class charT, class traits>
|
| 8680 |
+
friend basic_ostream<charT, traits>&
|
| 8681 |
+
operator<<(basic_ostream<charT, traits>& os, const path& p);
|
| 8682 |
+
```
|
| 8683 |
+
|
| 8684 |
+
*Effects:* Equivalent to `os << quoted(p.string<charT, traits>())`.
|
| 8685 |
+
|
| 8686 |
+
[*Note 1*: The `quoted` function is described
|
| 8687 |
+
in [[quoted.manip]]. — *end note*]
|
| 8688 |
+
|
| 8689 |
+
*Returns:* `os`.
|
| 8690 |
+
|
| 8691 |
+
``` cpp
|
| 8692 |
+
template<class charT, class traits>
|
| 8693 |
+
friend basic_istream<charT, traits>&
|
| 8694 |
+
operator>>(basic_istream<charT, traits>& is, path& p);
|
| 8695 |
+
```
|
| 8696 |
+
|
| 8697 |
+
*Effects:* Equivalent to:
|
| 8698 |
+
|
| 8699 |
+
``` cpp
|
| 8700 |
+
basic_string<charT, traits> tmp;
|
| 8701 |
+
is >> quoted(tmp);
|
| 8702 |
+
p = tmp;
|
| 8703 |
+
```
|
| 8704 |
+
|
| 8705 |
+
*Returns:* `is`.
|
| 8706 |
+
|
| 8707 |
+
#### Non-member functions <a id="fs.path.nonmember">[[fs.path.nonmember]]</a>
|
| 8708 |
|
| 8709 |
``` cpp
|
| 8710 |
void swap(path& lhs, path& rhs) noexcept;
|
| 8711 |
```
|
| 8712 |
|
| 8713 |
+
*Effects:* Equivalent to `lhs.swap(rhs)`.
|
| 8714 |
|
| 8715 |
``` cpp
|
| 8716 |
size_t hash_value (const path& p) noexcept;
|
| 8717 |
```
|
| 8718 |
|
| 8719 |
*Returns:* A hash value for the path `p`. If for two paths, `p1 == p2`
|
| 8720 |
then `hash_value(p1) == hash_value(p2)`.
|
| 8721 |
|
| 8722 |
``` cpp
|
| 8723 |
+
friend bool operator==(const path& lhs, const path& rhs) noexcept;
|
| 8724 |
```
|
| 8725 |
|
| 8726 |
+
*Returns:* `lhs.compare(rhs) == 0`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8727 |
|
| 8728 |
[*Note 1*:
|
| 8729 |
|
| 8730 |
Path equality and path equivalence have different semantics.
|
| 8731 |
|
| 8732 |
- Equality is determined by the `path` non-member `operator==`, which
|
| 8733 |
+
considers the two paths’ lexical representations only.
|
| 8734 |
\[*Example 1*: `path("foo") == "bar"` is never
|
| 8735 |
`true`. — *end example*]
|
| 8736 |
- Equivalence is determined by the `equivalent()` non-member function,
|
| 8737 |
+
which determines if two paths resolve [[fs.class.path]] to the same
|
| 8738 |
+
file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
|
| 8739 |
+
`true` when both paths resolve to the same file. — *end example*]
|
|
|
|
| 8740 |
|
| 8741 |
Programmers wishing to determine if two paths are “the same” must decide
|
| 8742 |
if “the same” means “the same representation” or “resolve to the same
|
| 8743 |
actual file”, and choose the appropriate function accordingly.
|
| 8744 |
|
| 8745 |
— *end note*]
|
| 8746 |
|
| 8747 |
``` cpp
|
| 8748 |
+
friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
|
| 8749 |
```
|
| 8750 |
|
| 8751 |
+
*Returns:* `lhs.compare(rhs) <=> 0`.
|
| 8752 |
|
| 8753 |
``` cpp
|
| 8754 |
+
friend path operator/ (const path& lhs, const path& rhs);
|
| 8755 |
```
|
| 8756 |
|
| 8757 |
*Effects:* Equivalent to: `return path(lhs) /= rhs;`
|
| 8758 |
|
| 8759 |
+
### Class `filesystem_error` <a id="fs.class.filesystem.error">[[fs.class.filesystem.error]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8760 |
|
| 8761 |
``` cpp
|
| 8762 |
namespace std::filesystem {
|
| 8763 |
class filesystem_error : public system_error {
|
| 8764 |
public:
|
|
|
|
| 8774 |
};
|
| 8775 |
}
|
| 8776 |
```
|
| 8777 |
|
| 8778 |
The class `filesystem_error` defines the type of objects thrown as
|
| 8779 |
+
exceptions to report file system errors from functions described in
|
| 8780 |
+
subclause [[filesystems]].
|
| 8781 |
|
| 8782 |
+
#### Members <a id="fs.filesystem.error.members">[[fs.filesystem.error.members]]</a>
|
| 8783 |
|
| 8784 |
Constructors are provided that store zero, one, or two paths associated
|
| 8785 |
with an error.
|
| 8786 |
|
| 8787 |
``` cpp
|
| 8788 |
filesystem_error(const string& what_arg, error_code ec);
|
| 8789 |
```
|
| 8790 |
|
| 8791 |
+
*Ensures:*
|
|
|
|
| 8792 |
|
| 8793 |
+
- `code() == ec`,
|
| 8794 |
+
- `path1().empty() == true`,
|
| 8795 |
+
- `path2().empty() == true`, and
|
| 8796 |
+
- `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8797 |
|
| 8798 |
``` cpp
|
| 8799 |
filesystem_error(const string& what_arg, const path& p1, error_code ec);
|
| 8800 |
```
|
| 8801 |
|
| 8802 |
+
*Ensures:*
|
|
|
|
| 8803 |
|
| 8804 |
+
- `code() == ec`,
|
| 8805 |
+
- `path1()` returns a reference to the stored copy of `p1`,
|
| 8806 |
+
- `path2().empty() == true`, and
|
| 8807 |
+
- `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8808 |
|
| 8809 |
``` cpp
|
| 8810 |
filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
|
| 8811 |
```
|
| 8812 |
|
| 8813 |
+
*Ensures:*
|
|
|
|
| 8814 |
|
| 8815 |
+
- `code() == ec`,
|
| 8816 |
+
- `path1()` returns a reference to the stored copy of `p1`,
|
| 8817 |
+
- `path2()` returns a reference to the stored copy of `p2`, and
|
| 8818 |
+
- `string_view(what()).find(what_arg.c_str())` `!= string_view::npos`.
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8819 |
|
| 8820 |
``` cpp
|
| 8821 |
const path& path1() const noexcept;
|
| 8822 |
```
|
| 8823 |
|
|
|
|
| 8833 |
|
| 8834 |
``` cpp
|
| 8835 |
const char* what() const noexcept override;
|
| 8836 |
```
|
| 8837 |
|
| 8838 |
+
*Returns:* An NTBS that incorporates the `what_arg` argument supplied to
|
| 8839 |
+
the constructor. The exact format is unspecified. Implementations should
|
| 8840 |
+
include the `system_error::what()` string and the pathnames of `path1`
|
| 8841 |
+
and `path2` in the native format in the returned string.
|
| 8842 |
|
| 8843 |
### Enumerations <a id="fs.enum">[[fs.enum]]</a>
|
| 8844 |
|
| 8845 |
#### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
|
| 8846 |
|
| 8847 |
This enum specifies constants used to identify the format of the
|
| 8848 |
+
character sequence, with the meanings listed in [[fs.enum.path.format]].
|
|
|
|
| 8849 |
|
| 8850 |
[*Note 1*: For POSIX-based systems, native and generic formats are
|
| 8851 |
equivalent and the character sequence should always be interpreted in
|
| 8852 |
the same way. — *end note*]
|
| 8853 |
|
| 8854 |
+
#### Enum class `file_type` <a id="fs.enum.file.type">[[fs.enum.file.type]]</a>
|
| 8855 |
|
| 8856 |
This enum class specifies constants used to identify file types, with
|
| 8857 |
+
the meanings listed in [[fs.enum.file.type]]. The values of the
|
| 8858 |
+
constants are distinct.
|
| 8859 |
|
| 8860 |
[*Note 1*: The file not being found is not considered an error while
|
| 8861 |
determining the type of a file. — *end note*]
|
| 8862 |
|
| 8863 |
#### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
|
| 8864 |
|
| 8865 |
+
The `enum class` type `copy_options` is a bitmask type [[bitmask.types]]
|
| 8866 |
+
that specifies bitmask constants used to control the semantics of copy
|
| 8867 |
+
operations. The constants are specified in option groups with the
|
| 8868 |
+
meanings listed in [[fs.enum.copy.opts]]. The constant `none` represents
|
| 8869 |
+
the empty bitmask, and is shown in each option group for purposes of
|
| 8870 |
exposition; implementations shall provide only a single definition.
|
| 8871 |
+
Every other constant in the table represents a distinct bitmask element.
|
| 8872 |
|
| 8873 |
+
**Table: Enum class `copy_options`** <a id="fs.enum.copy.opts">[fs.enum.copy.opts]</a>
|
| 8874 |
|
| 8875 |
| Constant | Meaning |
|
| 8876 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 8877 |
| `none` | (Default) Error; file already exists. |
|
| 8878 |
| `skip_existing` | Do not overwrite existing file, do not report an error. |
|
|
|
|
| 8886 |
| `create_hard_links` | Make hard links instead of copies of files. |
|
| 8887 |
|
| 8888 |
|
| 8889 |
#### Enum class `perms` <a id="fs.enum.perms">[[fs.enum.perms]]</a>
|
| 8890 |
|
| 8891 |
+
The `enum class` type `perms` is a bitmask type [[bitmask.types]] that
|
| 8892 |
+
specifies bitmask constants used to identify file permissions, with the
|
| 8893 |
+
meanings listed in [[fs.enum.perms]].
|
| 8894 |
|
| 8895 |
+
**Table: Enum class `perms`** <a id="fs.enum.perms">[fs.enum.perms]</a>
|
| 8896 |
|
| 8897 |
| Name | Value (octal) | POSIX macro | Definition or notes |
|
| 8898 |
| -------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
|
| 8899 |
| `none` | `0` | | There are no permissions set for the file. |
|
| 8900 |
| `owner_read` | `0400` | `S_IRUSR` | Read permission, owner |
|
|
|
|
| 8917 |
| `unknown` | `0xFFFF` | | The permissions are not known, such as when a `file_status` object is created without specifying the permissions |
|
| 8918 |
|
| 8919 |
|
| 8920 |
#### Enum class `perm_options` <a id="fs.enum.perm.opts">[[fs.enum.perm.opts]]</a>
|
| 8921 |
|
| 8922 |
+
The `enum class` type `perm_options` is a bitmask type [[bitmask.types]]
|
| 8923 |
+
that specifies bitmask constants used to control the semantics of
|
| 8924 |
+
permissions operations, with the meanings listed in
|
| 8925 |
+
[[fs.enum.perm.opts]]. The bitmask constants are bitmask elements. In
|
| 8926 |
+
[[fs.enum.perm.opts]] `perm` denotes a value of type `perms` passed to
|
| 8927 |
+
`permissions`.
|
| 8928 |
|
| 8929 |
+
**Table: Enum class `perm_options`** <a id="fs.enum.perm.opts">[fs.enum.perm.opts]</a>
|
| 8930 |
|
| 8931 |
| Name | Meaning |
|
| 8932 |
+
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 8933 |
| `replace` | `permissions` shall replace the file's permission bits with `perm` |
|
| 8934 |
+
| `add` | `permissions` shall replace the file's permission bits with the bitwise \logop{OR} of `perm` and the file's current permission bits. |
|
| 8935 |
+
| `remove` | `permissions` shall replace the file's permission bits with the bitwise \logop{AND} of the complement of `perm` and the file's current permission bits. |
|
| 8936 |
| `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
|
| 8937 |
|
| 8938 |
|
| 8939 |
#### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
|
| 8940 |
|
| 8941 |
+
The `enum class` type `directory_options` is a bitmask type
|
| 8942 |
+
[[bitmask.types]] that specifies bitmask constants used to identify
|
| 8943 |
+
directory traversal options, with the meanings listed in
|
| 8944 |
+
[[fs.enum.dir.opts]]. The constant `none` represents the empty bitmask;
|
| 8945 |
+
every other constant in the table represents a distinct bitmask element.
|
| 8946 |
|
| 8947 |
+
**Table: Enum class `directory_options`** <a id="fs.enum.dir.opts">[fs.enum.dir.opts]</a>
|
| 8948 |
|
| 8949 |
| Name | Meaning |
|
| 8950 |
| -------------------------- | ------------------------------------------------------------------ |
|
| 8951 |
| `none` | (Default) Skip directory symlinks, permission denied is an error. |
|
| 8952 |
| `follow_directory_symlink` | Follow rather than skip directory symlinks. |
|
| 8953 |
| `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
|
| 8954 |
|
| 8955 |
|
| 8956 |
+
### Class `file_status` <a id="fs.class.file.status">[[fs.class.file.status]]</a>
|
| 8957 |
|
| 8958 |
``` cpp
|
| 8959 |
namespace std::filesystem {
|
| 8960 |
class file_status {
|
| 8961 |
public:
|
| 8962 |
+
// [fs.file.status.cons], constructors and destructor
|
| 8963 |
file_status() noexcept : file_status(file_type::none) {}
|
| 8964 |
explicit file_status(file_type ft,
|
| 8965 |
perms prms = perms::unknown) noexcept;
|
| 8966 |
file_status(const file_status&) noexcept = default;
|
| 8967 |
file_status(file_status&&) noexcept = default;
|
| 8968 |
~file_status();
|
| 8969 |
|
| 8970 |
+
// assignments
|
| 8971 |
file_status& operator=(const file_status&) noexcept = default;
|
| 8972 |
file_status& operator=(file_status&&) noexcept = default;
|
| 8973 |
|
| 8974 |
+
// [fs.file.status.mods], modifiers
|
| 8975 |
void type(file_type ft) noexcept;
|
| 8976 |
void permissions(perms prms) noexcept;
|
| 8977 |
|
| 8978 |
+
// [fs.file.status.obs], observers
|
| 8979 |
file_type type() const noexcept;
|
| 8980 |
perms permissions() const noexcept;
|
| 8981 |
+
|
| 8982 |
+
friend bool operator==(const file_status& lhs, const file_status& rhs) noexcept
|
| 8983 |
+
{ return lhs.type() == rhs.type() && lhs.permissions() == rhs.permissions(); }
|
| 8984 |
};
|
| 8985 |
}
|
| 8986 |
```
|
| 8987 |
|
| 8988 |
+
#### Constructors <a id="fs.file.status.cons">[[fs.file.status.cons]]</a>
|
| 8989 |
|
| 8990 |
``` cpp
|
| 8991 |
explicit file_status(file_type ft, perms prms = perms::unknown) noexcept;
|
| 8992 |
```
|
| 8993 |
|
| 8994 |
+
*Ensures:* `type() == ft` and `permissions() == prms`.
|
| 8995 |
|
| 8996 |
+
#### Observers <a id="fs.file.status.obs">[[fs.file.status.obs]]</a>
|
| 8997 |
|
| 8998 |
``` cpp
|
| 8999 |
file_type type() const noexcept;
|
| 9000 |
```
|
| 9001 |
|
|
|
|
| 9009 |
|
| 9010 |
*Returns:* The value of `permissions()` specified by the postconditions
|
| 9011 |
of the most recent call to a constructor, `operator=`, or
|
| 9012 |
`permissions(perms)` function.
|
| 9013 |
|
| 9014 |
+
#### Modifiers <a id="fs.file.status.mods">[[fs.file.status.mods]]</a>
|
| 9015 |
|
| 9016 |
``` cpp
|
| 9017 |
void type(file_type ft) noexcept;
|
| 9018 |
```
|
| 9019 |
|
| 9020 |
+
*Ensures:* `type() == ft`.
|
| 9021 |
|
| 9022 |
``` cpp
|
| 9023 |
void permissions(perms prms) noexcept;
|
| 9024 |
```
|
| 9025 |
|
| 9026 |
+
*Ensures:* `permissions() == prms`.
|
| 9027 |
|
| 9028 |
+
### Class `directory_entry` <a id="fs.class.directory.entry">[[fs.class.directory.entry]]</a>
|
| 9029 |
|
| 9030 |
``` cpp
|
| 9031 |
namespace std::filesystem {
|
| 9032 |
class directory_entry {
|
| 9033 |
public:
|
| 9034 |
// [fs.dir.entry.cons], constructors and destructor
|
| 9035 |
directory_entry() noexcept = default;
|
| 9036 |
directory_entry(const directory_entry&) = default;
|
| 9037 |
directory_entry(directory_entry&&) noexcept = default;
|
| 9038 |
+
explicit directory_entry(const filesystem::path& p);
|
| 9039 |
+
directory_entry(const filesystem::path& p, error_code& ec);
|
| 9040 |
~directory_entry();
|
| 9041 |
|
| 9042 |
+
// assignments
|
| 9043 |
directory_entry& operator=(const directory_entry&) = default;
|
| 9044 |
directory_entry& operator=(directory_entry&&) noexcept = default;
|
| 9045 |
|
| 9046 |
// [fs.dir.entry.mods], modifiers
|
| 9047 |
+
void assign(const filesystem::path& p);
|
| 9048 |
+
void assign(const filesystem::path& p, error_code& ec);
|
| 9049 |
+
void replace_filename(const filesystem::path& p);
|
| 9050 |
+
void replace_filename(const filesystem::path& p, error_code& ec);
|
| 9051 |
void refresh();
|
| 9052 |
void refresh(error_code& ec) noexcept;
|
| 9053 |
|
| 9054 |
// [fs.dir.entry.obs], observers
|
| 9055 |
+
const filesystem::path& path() const noexcept;
|
| 9056 |
+
operator const filesystem::path&() const noexcept;
|
| 9057 |
bool exists() const;
|
| 9058 |
bool exists(error_code& ec) const noexcept;
|
| 9059 |
bool is_block_file() const;
|
| 9060 |
bool is_block_file(error_code& ec) const noexcept;
|
| 9061 |
bool is_character_file() const;
|
|
|
|
| 9081 |
file_status status() const;
|
| 9082 |
file_status status(error_code& ec) const noexcept;
|
| 9083 |
file_status symlink_status() const;
|
| 9084 |
file_status symlink_status(error_code& ec) const noexcept;
|
| 9085 |
|
|
|
|
| 9086 |
bool operator==(const directory_entry& rhs) const noexcept;
|
| 9087 |
+
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
|
|
|
|
|
|
|
|
|
|
| 9088 |
|
| 9089 |
private:
|
| 9090 |
+
filesystem::path pathobject; // exposition only
|
| 9091 |
friend class directory_iterator; // exposition only
|
| 9092 |
};
|
| 9093 |
}
|
| 9094 |
```
|
| 9095 |
|
| 9096 |
A `directory_entry` object stores a `path` object and may store
|
| 9097 |
additional objects for file attributes such as hard link count, status,
|
| 9098 |
symlink status, file size, and last write time.
|
| 9099 |
|
| 9100 |
+
Implementations should store such additional file attributes during
|
| 9101 |
+
directory iteration if their values are available and storing the values
|
| 9102 |
+
would allow the implementation to eliminate file system accesses by
|
| 9103 |
+
`directory_entry` observer functions [[fs.op.funcs]]. Such stored file
|
| 9104 |
+
attribute values are said to be *cached*.
|
| 9105 |
|
| 9106 |
+
[*Note 1*: For purposes of exposition, class `directory_iterator`
|
| 9107 |
+
[[fs.class.directory.iterator]] is shown above as a friend of class
|
| 9108 |
`directory_entry`. Friendship allows the `directory_iterator`
|
| 9109 |
implementation to cache already available attribute values directly into
|
| 9110 |
a `directory_entry` object without the cost of an unneeded call to
|
| 9111 |
`refresh()`. — *end note*]
|
| 9112 |
|
|
|
|
| 9138 |
`std::filesystem::last_write_time` function. The code is portable to any
|
| 9139 |
implementation, regardless of whether or not it employs caching.
|
| 9140 |
|
| 9141 |
— *end example*]
|
| 9142 |
|
| 9143 |
+
#### Constructors <a id="fs.dir.entry.cons">[[fs.dir.entry.cons]]</a>
|
| 9144 |
|
| 9145 |
``` cpp
|
| 9146 |
+
explicit directory_entry(const filesystem::path& p);
|
| 9147 |
+
directory_entry(const filesystem::path& p, error_code& ec);
|
| 9148 |
```
|
| 9149 |
|
| 9150 |
+
*Effects:* Calls `refresh()` or `refresh(ec)`, respectively.
|
|
|
|
| 9151 |
|
| 9152 |
+
*Ensures:* `path() == p` if no error occurs, otherwise
|
| 9153 |
+
`path() == filesystem::path()`.
|
| 9154 |
|
| 9155 |
*Throws:* As specified in [[fs.err.report]].
|
| 9156 |
|
| 9157 |
+
#### Modifiers <a id="fs.dir.entry.mods">[[fs.dir.entry.mods]]</a>
|
| 9158 |
|
| 9159 |
``` cpp
|
| 9160 |
+
void assign(const filesystem::path& p);
|
| 9161 |
+
void assign(const filesystem::path& p, error_code& ec);
|
| 9162 |
```
|
| 9163 |
|
| 9164 |
*Effects:* Equivalent to `pathobject = p`, then `refresh()` or
|
| 9165 |
`refresh(ec)`, respectively. If an error occurs, the values of any
|
| 9166 |
cached attributes are unspecified.
|
| 9167 |
|
| 9168 |
*Throws:* As specified in [[fs.err.report]].
|
| 9169 |
|
| 9170 |
``` cpp
|
| 9171 |
+
void replace_filename(const filesystem::path& p);
|
| 9172 |
+
void replace_filename(const filesystem::path& p, error_code& ec);
|
| 9173 |
```
|
| 9174 |
|
| 9175 |
*Effects:* Equivalent to `pathobject.replace_filename(p)`, then
|
| 9176 |
`refresh()` or `refresh(ec)`, respectively. If an error occurs, the
|
| 9177 |
values of any cached attributes are unspecified.
|
|
|
|
| 9183 |
void refresh(error_code& ec) noexcept;
|
| 9184 |
```
|
| 9185 |
|
| 9186 |
*Effects:* Stores the current values of any cached attributes of the
|
| 9187 |
file `p` resolves to. If an error occurs, an error is
|
| 9188 |
+
reported [[fs.err.report]] and the values of any cached attributes are
|
| 9189 |
+
unspecified.
|
| 9190 |
|
| 9191 |
*Throws:* As specified in [[fs.err.report]].
|
| 9192 |
|
| 9193 |
+
[*Note 1*: Implementations of `directory_iterator`
|
| 9194 |
+
[[fs.class.directory.iterator]] are prohibited from directly or
|
| 9195 |
+
indirectly calling the `refresh` function since it must access the
|
| 9196 |
+
external file system, and the objective of caching is to avoid
|
| 9197 |
+
unnecessary file system accesses. — *end note*]
|
| 9198 |
|
| 9199 |
+
#### Observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
|
| 9200 |
|
| 9201 |
Unqualified function names in the *Returns:* elements of the
|
| 9202 |
`directory_entry` observers described below refer to members of the
|
| 9203 |
`std::filesystem` namespace.
|
| 9204 |
|
| 9205 |
``` cpp
|
| 9206 |
+
const filesystem::path& path() const noexcept;
|
| 9207 |
+
operator const filesystem::path&() const noexcept;
|
| 9208 |
```
|
| 9209 |
|
| 9210 |
*Returns:* `pathobject`.
|
| 9211 |
|
| 9212 |
``` cpp
|
| 9213 |
bool exists() const;
|
| 9214 |
bool exists(error_code& ec) const noexcept;
|
| 9215 |
```
|
| 9216 |
|
| 9217 |
+
*Returns:* `exists(this->status())` or `exists(this->status(ec))`,
|
| 9218 |
respectively.
|
| 9219 |
|
| 9220 |
*Throws:* As specified in [[fs.err.report]].
|
| 9221 |
|
| 9222 |
``` cpp
|
| 9223 |
bool is_block_file() const;
|
| 9224 |
bool is_block_file(error_code& ec) const noexcept;
|
| 9225 |
```
|
| 9226 |
|
| 9227 |
*Returns:* `is_block_file(this->status())` or
|
| 9228 |
+
`is_block_file(this->status(ec))`, respectively.
|
| 9229 |
|
| 9230 |
*Throws:* As specified in [[fs.err.report]].
|
| 9231 |
|
| 9232 |
``` cpp
|
| 9233 |
bool is_character_file() const;
|
| 9234 |
bool is_character_file(error_code& ec) const noexcept;
|
| 9235 |
```
|
| 9236 |
|
| 9237 |
*Returns:* `is_character_file(this->status())` or
|
| 9238 |
+
`is_character_file(this->status(ec))`, respectively.
|
| 9239 |
|
| 9240 |
*Throws:* As specified in [[fs.err.report]].
|
| 9241 |
|
| 9242 |
``` cpp
|
| 9243 |
bool is_directory() const;
|
| 9244 |
bool is_directory(error_code& ec) const noexcept;
|
| 9245 |
```
|
| 9246 |
|
| 9247 |
*Returns:* `is_directory(this->status())` or
|
| 9248 |
+
`is_directory(this->status(ec))`, respectively.
|
| 9249 |
|
| 9250 |
*Throws:* As specified in [[fs.err.report]].
|
| 9251 |
|
| 9252 |
``` cpp
|
| 9253 |
bool is_fifo() const;
|
| 9254 |
bool is_fifo(error_code& ec) const noexcept;
|
| 9255 |
```
|
| 9256 |
|
| 9257 |
+
*Returns:* `is_fifo(this->status())` or `is_fifo(this->status(ec))`,
|
| 9258 |
respectively.
|
| 9259 |
|
| 9260 |
*Throws:* As specified in [[fs.err.report]].
|
| 9261 |
|
| 9262 |
``` cpp
|
| 9263 |
bool is_other() const;
|
| 9264 |
bool is_other(error_code& ec) const noexcept;
|
| 9265 |
```
|
| 9266 |
|
| 9267 |
+
*Returns:* `is_other(this->status())` or `is_other(this->status(ec))`,
|
| 9268 |
respectively.
|
| 9269 |
|
| 9270 |
*Throws:* As specified in [[fs.err.report]].
|
| 9271 |
|
| 9272 |
``` cpp
|
| 9273 |
bool is_regular_file() const;
|
| 9274 |
bool is_regular_file(error_code& ec) const noexcept;
|
| 9275 |
```
|
| 9276 |
|
| 9277 |
*Returns:* `is_regular_file(this->status())` or
|
| 9278 |
+
`is_regular_file(this->status(ec))`, respectively.
|
| 9279 |
|
| 9280 |
*Throws:* As specified in [[fs.err.report]].
|
| 9281 |
|
| 9282 |
``` cpp
|
| 9283 |
bool is_socket() const;
|
| 9284 |
bool is_socket(error_code& ec) const noexcept;
|
| 9285 |
```
|
| 9286 |
|
| 9287 |
+
*Returns:* `is_socket(this->status())` or `is_socket(this->status(ec))`,
|
| 9288 |
+
respectively.
|
| 9289 |
|
| 9290 |
*Throws:* As specified in [[fs.err.report]].
|
| 9291 |
|
| 9292 |
``` cpp
|
| 9293 |
bool is_symlink() const;
|
| 9294 |
bool is_symlink(error_code& ec) const noexcept;
|
| 9295 |
```
|
| 9296 |
|
| 9297 |
*Returns:* `is_symlink(this->symlink_status())` or
|
| 9298 |
+
`is_symlink(this->symlink_status(ec))`, respectively.
|
| 9299 |
|
| 9300 |
*Throws:* As specified in [[fs.err.report]].
|
| 9301 |
|
| 9302 |
``` cpp
|
| 9303 |
uintmax_t file_size() const;
|
|
|
|
| 9356 |
```
|
| 9357 |
|
| 9358 |
*Returns:* `pathobject == rhs.pathobject`.
|
| 9359 |
|
| 9360 |
``` cpp
|
| 9361 |
+
strong_ordering operator<=>(const directory_entry& rhs) const noexcept;
|
| 9362 |
```
|
| 9363 |
|
| 9364 |
+
*Returns:* `pathobject <=> rhs.pathobject`.
|
| 9365 |
|
| 9366 |
+
### Class `directory_iterator` <a id="fs.class.directory.iterator">[[fs.class.directory.iterator]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9367 |
|
| 9368 |
An object of type `directory_iterator` provides an iterator for a
|
| 9369 |
sequence of `directory_entry` elements representing the path and any
|
| 9370 |
+
cached attribute values [[fs.class.directory.entry]] for each file in a
|
| 9371 |
+
directory or in an *implementation-defined* directory-like file type.
|
| 9372 |
|
| 9373 |
[*Note 1*: For iteration into sub-directories, see class
|
| 9374 |
+
`recursive_directory_iterator` [[fs.class.rec.dir.itr]]. — *end note*]
|
|
|
|
| 9375 |
|
| 9376 |
``` cpp
|
| 9377 |
namespace std::filesystem {
|
| 9378 |
class directory_iterator {
|
| 9379 |
public:
|
|
|
|
| 9385 |
|
| 9386 |
// [fs.dir.itr.members], member functions
|
| 9387 |
directory_iterator() noexcept;
|
| 9388 |
explicit directory_iterator(const path& p);
|
| 9389 |
directory_iterator(const path& p, directory_options options);
|
| 9390 |
+
directory_iterator(const path& p, error_code& ec);
|
| 9391 |
directory_iterator(const path& p, directory_options options,
|
| 9392 |
+
error_code& ec);
|
| 9393 |
directory_iterator(const directory_iterator& rhs);
|
| 9394 |
directory_iterator(directory_iterator&& rhs) noexcept;
|
| 9395 |
~directory_iterator();
|
| 9396 |
|
| 9397 |
directory_iterator& operator=(const directory_iterator& rhs);
|
| 9398 |
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
|
| 9399 |
|
| 9400 |
const directory_entry& operator*() const;
|
| 9401 |
const directory_entry* operator->() const;
|
| 9402 |
directory_iterator& operator++();
|
| 9403 |
+
directory_iterator& increment(error_code& ec);
|
| 9404 |
|
| 9405 |
// other members as required by [input.iterators], input iterators
|
| 9406 |
};
|
| 9407 |
}
|
| 9408 |
```
|
| 9409 |
|
| 9410 |
+
`directory_iterator` meets the *Cpp17InputIterator* requirements
|
| 9411 |
+
[[input.iterators]].
|
| 9412 |
|
| 9413 |
If an iterator of type `directory_iterator` reports an error or is
|
| 9414 |
advanced past the last directory element, that iterator shall become
|
| 9415 |
equal to the end iterator value. The `directory_iterator` default
|
| 9416 |
constructor shall create an iterator equal to the end iterator value,
|
|
|
|
| 9426 |
to a `path` object composed of the directory argument from which the
|
| 9427 |
iterator was constructed with filename of the directory entry appended
|
| 9428 |
as if by `operator/=`.
|
| 9429 |
|
| 9430 |
Directory iteration shall not yield directory entries for the current
|
| 9431 |
+
(dot) and parent (dot-dot) directories.
|
| 9432 |
|
| 9433 |
The order of directory entries obtained by dereferencing successive
|
| 9434 |
increments of a `directory_iterator` is unspecified.
|
| 9435 |
|
| 9436 |
Constructors and non-const `directory_iterator` member functions store
|
| 9437 |
+
the values of any cached attributes [[fs.class.directory.entry]] in the
|
| 9438 |
+
`directory_entry` element returned by `operator*()`.
|
| 9439 |
`directory_iterator` member functions shall not directly or indirectly
|
| 9440 |
call any `directory_entry` `refresh` function.
|
| 9441 |
|
| 9442 |
[*Note 2*: The exact mechanism for storing cached attribute values is
|
| 9443 |
not exposed to users. For exposition, class `directory_iterator` is
|
| 9444 |
+
shown in [[fs.class.directory.entry]] as a friend of class
|
| 9445 |
`directory_entry`. — *end note*]
|
| 9446 |
|
| 9447 |
[*Note 3*: Programs performing directory iteration may wish to test if
|
| 9448 |
the path obtained by dereferencing a directory iterator actually exists.
|
| 9449 |
It could be a symbolic link to a non-existent file. Programs recursively
|
|
|
|
| 9454 |
construction of a `directory_iterator` for the directory, it is
|
| 9455 |
unspecified whether or not subsequently incrementing the iterator will
|
| 9456 |
ever result in an iterator referencing the removed or added directory
|
| 9457 |
entry. See POSIX `readdir_r`. — *end note*]
|
| 9458 |
|
| 9459 |
+
#### Members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
|
| 9460 |
|
| 9461 |
``` cpp
|
| 9462 |
directory_iterator() noexcept;
|
| 9463 |
```
|
| 9464 |
|
| 9465 |
*Effects:* Constructs the end iterator.
|
| 9466 |
|
| 9467 |
``` cpp
|
| 9468 |
explicit directory_iterator(const path& p);
|
| 9469 |
directory_iterator(const path& p, directory_options options);
|
| 9470 |
+
directory_iterator(const path& p, error_code& ec);
|
| 9471 |
+
directory_iterator(const path& p, directory_options options, error_code& ec);
|
| 9472 |
```
|
| 9473 |
|
| 9474 |
*Effects:* For the directory that `p` resolves to, constructs an
|
| 9475 |
iterator for the first element in a sequence of `directory_entry`
|
| 9476 |
elements representing the files in the directory, if any; otherwise the
|
|
|
|
| 9493 |
``` cpp
|
| 9494 |
directory_iterator(const directory_iterator& rhs);
|
| 9495 |
directory_iterator(directory_iterator&& rhs) noexcept;
|
| 9496 |
```
|
| 9497 |
|
| 9498 |
+
*Ensures:* `*this` has the original value of `rhs`.
|
|
|
|
|
|
|
| 9499 |
|
| 9500 |
``` cpp
|
| 9501 |
directory_iterator& operator=(const directory_iterator& rhs);
|
| 9502 |
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
|
| 9503 |
```
|
| 9504 |
|
| 9505 |
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 9506 |
effect.
|
| 9507 |
|
| 9508 |
+
*Ensures:* `*this` has the original value of `rhs`.
|
| 9509 |
|
| 9510 |
*Returns:* `*this`.
|
| 9511 |
|
| 9512 |
``` cpp
|
| 9513 |
directory_iterator& operator++();
|
| 9514 |
+
directory_iterator& increment(error_code& ec);
|
| 9515 |
```
|
| 9516 |
|
| 9517 |
*Effects:* As specified for the prefix increment operation of Input
|
| 9518 |
+
iterators [[input.iterators]].
|
| 9519 |
|
| 9520 |
*Returns:* `*this`.
|
| 9521 |
|
| 9522 |
*Throws:* As specified in [[fs.err.report]].
|
| 9523 |
|
| 9524 |
+
#### Non-member functions <a id="fs.dir.itr.nonmembers">[[fs.dir.itr.nonmembers]]</a>
|
| 9525 |
|
| 9526 |
These functions enable range access for `directory_iterator`.
|
| 9527 |
|
| 9528 |
``` cpp
|
| 9529 |
directory_iterator begin(directory_iterator iter) noexcept;
|
|
|
|
| 9557 |
// [fs.rec.dir.itr.members], constructors and destructor
|
| 9558 |
recursive_directory_iterator() noexcept;
|
| 9559 |
explicit recursive_directory_iterator(const path& p);
|
| 9560 |
recursive_directory_iterator(const path& p, directory_options options);
|
| 9561 |
recursive_directory_iterator(const path& p, directory_options options,
|
| 9562 |
+
error_code& ec);
|
| 9563 |
+
recursive_directory_iterator(const path& p, error_code& ec);
|
| 9564 |
recursive_directory_iterator(const recursive_directory_iterator& rhs);
|
| 9565 |
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
|
| 9566 |
~recursive_directory_iterator();
|
| 9567 |
|
| 9568 |
// [fs.rec.dir.itr.members], observers
|
|
|
|
| 9578 |
operator=(const recursive_directory_iterator& rhs);
|
| 9579 |
recursive_directory_iterator&
|
| 9580 |
operator=(recursive_directory_iterator&& rhs) noexcept;
|
| 9581 |
|
| 9582 |
recursive_directory_iterator& operator++();
|
| 9583 |
+
recursive_directory_iterator& increment(error_code& ec);
|
| 9584 |
|
| 9585 |
void pop();
|
| 9586 |
void pop(error_code& ec);
|
| 9587 |
void disable_recursion_pending();
|
| 9588 |
|
|
|
|
| 9599 |
`directory_iterator` unless otherwise specified.
|
| 9600 |
|
| 9601 |
[*Note 1*: If the directory structure being iterated over contains
|
| 9602 |
cycles then the end iterator may be unreachable. — *end note*]
|
| 9603 |
|
| 9604 |
+
#### Members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
|
| 9605 |
|
| 9606 |
``` cpp
|
| 9607 |
recursive_directory_iterator() noexcept;
|
| 9608 |
```
|
| 9609 |
|
| 9610 |
*Effects:* Constructs the end iterator.
|
| 9611 |
|
| 9612 |
``` cpp
|
| 9613 |
explicit recursive_directory_iterator(const path& p);
|
| 9614 |
recursive_directory_iterator(const path& p, directory_options options);
|
| 9615 |
+
recursive_directory_iterator(const path& p, directory_options options, error_code& ec);
|
| 9616 |
+
recursive_directory_iterator(const path& p, error_code& ec);
|
| 9617 |
```
|
| 9618 |
|
| 9619 |
+
*Effects:* Constructs an iterator representing the first entry in the
|
| 9620 |
+
directory to which `p` resolves, if any; otherwise, the end iterator.
|
| 9621 |
+
However, if
|
| 9622 |
|
| 9623 |
``` cpp
|
| 9624 |
(options & directory_options::skip_permission_denied) != directory_options::none
|
| 9625 |
```
|
| 9626 |
|
| 9627 |
and construction encounters an error indicating that permission to
|
| 9628 |
access `p` is denied, constructs the end iterator and does not report an
|
| 9629 |
error.
|
| 9630 |
|
| 9631 |
+
*Ensures:* `options() == options` for the signatures with a
|
| 9632 |
`directory_options` argument, otherwise
|
| 9633 |
`options() == directory_options::none`.
|
| 9634 |
|
| 9635 |
*Throws:* As specified in [[fs.err.report]].
|
| 9636 |
|
|
|
|
| 9638 |
`recursive_directory_iterator(".")` rather than
|
| 9639 |
`recursive_directory_iterator("")`. — *end note*]
|
| 9640 |
|
| 9641 |
[*Note 2*: By default, `recursive_directory_iterator` does not follow
|
| 9642 |
directory symlinks. To follow directory symlinks, specify `options` as
|
| 9643 |
+
`directory_options::follow_directory_symlink`. — *end note*]
|
| 9644 |
|
| 9645 |
``` cpp
|
| 9646 |
recursive_directory_iterator(const recursive_directory_iterator& rhs);
|
| 9647 |
```
|
| 9648 |
|
| 9649 |
+
*Ensures:*
|
|
|
|
|
|
|
| 9650 |
|
| 9651 |
- `options() == rhs.options()`
|
| 9652 |
- `depth() == rhs.depth()`
|
| 9653 |
- `recursion_pending() == rhs.recursion_pending()`
|
| 9654 |
|
| 9655 |
``` cpp
|
| 9656 |
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
|
| 9657 |
```
|
| 9658 |
|
| 9659 |
+
*Ensures:* `options()`, `depth()`, and `recursion_pending()` have the
|
| 9660 |
+
values that `rhs.options()`, `rhs.depth()`, and
|
|
|
|
|
|
|
| 9661 |
`rhs.recursion_pending()`, respectively, had before the function call.
|
| 9662 |
|
| 9663 |
``` cpp
|
| 9664 |
recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
|
| 9665 |
```
|
| 9666 |
|
| 9667 |
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 9668 |
effect.
|
| 9669 |
|
| 9670 |
+
*Ensures:*
|
| 9671 |
|
| 9672 |
- `options() == rhs.options()`
|
| 9673 |
- `depth() == rhs.depth()`
|
| 9674 |
- `recursion_pending() == rhs.recursion_pending()`
|
| 9675 |
|
|
|
|
| 9680 |
```
|
| 9681 |
|
| 9682 |
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 9683 |
effect.
|
| 9684 |
|
| 9685 |
+
*Ensures:* `options()`, `depth()`, and `recursion_pending()` have the
|
| 9686 |
+
values that `rhs.options()`, `rhs.depth()`, and
|
| 9687 |
`rhs.recursion_pending()`, respectively, had before the function call.
|
| 9688 |
|
| 9689 |
*Returns:* `*this`.
|
| 9690 |
|
| 9691 |
``` cpp
|
|
|
|
| 9718 |
|
| 9719 |
*Throws:* Nothing.
|
| 9720 |
|
| 9721 |
``` cpp
|
| 9722 |
recursive_directory_iterator& operator++();
|
| 9723 |
+
recursive_directory_iterator& increment(error_code& ec);
|
| 9724 |
```
|
| 9725 |
|
| 9726 |
*Effects:* As specified for the prefix increment operation of Input
|
| 9727 |
+
iterators [[input.iterators]], except that:
|
| 9728 |
|
| 9729 |
- If there are no more entries at the current depth, then if
|
| 9730 |
`depth() != 0` iteration over the parent directory resumes; otherwise
|
| 9731 |
`*this = recursive_directory_iterator()`.
|
| 9732 |
- Otherwise if
|
|
|
|
| 9760 |
directory currently being iterated over, and continue iteration over the
|
| 9761 |
parent directory.
|
| 9762 |
|
| 9763 |
*Throws:* As specified in [[fs.err.report]].
|
| 9764 |
|
| 9765 |
+
*Remarks:* Any copies of the previous value of `*this` are no longer
|
| 9766 |
+
required to be dereferenceable nor to be in the domain of `==`.
|
| 9767 |
+
|
| 9768 |
``` cpp
|
| 9769 |
void disable_recursion_pending();
|
| 9770 |
```
|
| 9771 |
|
| 9772 |
+
*Ensures:* `recursion_pending() == false`.
|
| 9773 |
|
| 9774 |
[*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
|
| 9775 |
recursion into a directory. — *end note*]
|
| 9776 |
|
| 9777 |
+
#### Non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
|
| 9778 |
|
| 9779 |
These functions enable use of `recursive_directory_iterator` with
|
| 9780 |
range-based for statements.
|
| 9781 |
|
| 9782 |
``` cpp
|
|
|
|
| 9795 |
|
| 9796 |
Filesystem operation functions query or modify files, including
|
| 9797 |
directories, in external storage.
|
| 9798 |
|
| 9799 |
[*Note 1*: Because hardware failures, network failures, file system
|
| 9800 |
+
races [[fs.race.behavior]], and many other kinds of errors occur
|
| 9801 |
frequently in file system operations, users should be aware that any
|
| 9802 |
filesystem operation function, no matter how apparently innocuous, may
|
| 9803 |
encounter an error; see [[fs.err.report]]. — *end note*]
|
| 9804 |
|
| 9805 |
#### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
|
|
|
|
| 9808 |
path absolute(const path& p);
|
| 9809 |
path absolute(const path& p, error_code& ec);
|
| 9810 |
```
|
| 9811 |
|
| 9812 |
*Effects:* Composes an absolute path referencing the same file system
|
| 9813 |
+
location as `p` according to the operating system [[fs.conform.os]].
|
| 9814 |
|
| 9815 |
*Returns:* The composed path. The signature with argument `ec` returns
|
| 9816 |
`path()` if an error occurs.
|
| 9817 |
|
| 9818 |
[*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
|
|
|
|
| 9820 |
|
| 9821 |
*Throws:* As specified in [[fs.err.report]].
|
| 9822 |
|
| 9823 |
[*Note 2*: To resolve symlinks, or perform other sanitization which
|
| 9824 |
might require queries to secondary storage, such as hard disks, consider
|
| 9825 |
+
`canonical` [[fs.op.canonical]]. — *end note*]
|
| 9826 |
|
| 9827 |
[*Note 3*: Implementations are strongly encouraged to not query
|
| 9828 |
secondary storage, and not consider `!exists(p)` an
|
| 9829 |
error. — *end note*]
|
| 9830 |
|
|
|
|
| 9834 |
`GetFullPathNameW`. — *end example*]
|
| 9835 |
|
| 9836 |
#### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
|
| 9837 |
|
| 9838 |
``` cpp
|
| 9839 |
+
path canonical(const path& p);
|
| 9840 |
path canonical(const path& p, error_code& ec);
|
|
|
|
| 9841 |
```
|
| 9842 |
|
| 9843 |
+
*Effects:* Converts `p` to an absolute path that has no symbolic link,
|
| 9844 |
+
dot, or dot-dot elements in its pathname in the generic format.
|
|
|
|
| 9845 |
|
| 9846 |
*Returns:* A path that refers to the same file system object as
|
| 9847 |
+
`absolute(p)`. The signature with argument `ec` returns `path()` if an
|
|
|
|
| 9848 |
error occurs.
|
| 9849 |
|
| 9850 |
*Throws:* As specified in [[fs.err.report]].
|
| 9851 |
|
| 9852 |
*Remarks:* `!exists(p)` is an error.
|
|
|
|
| 9858 |
```
|
| 9859 |
|
| 9860 |
*Effects:* Equivalent to `copy(from, to, copy_options::none)`.
|
| 9861 |
|
| 9862 |
``` cpp
|
| 9863 |
+
void copy(const path& from, const path& to, error_code& ec);
|
| 9864 |
```
|
| 9865 |
|
| 9866 |
*Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
|
| 9867 |
|
| 9868 |
``` cpp
|
| 9869 |
void copy(const path& from, const path& to, copy_options options);
|
| 9870 |
void copy(const path& from, const path& to, copy_options options,
|
| 9871 |
+
error_code& ec);
|
| 9872 |
```
|
| 9873 |
|
| 9874 |
+
*Preconditions:* At most one element from each option
|
| 9875 |
+
group [[fs.enum.copy.opts]] is set in `options`.
|
| 9876 |
|
| 9877 |
*Effects:* Before the first use of `f` and `t`:
|
| 9878 |
|
| 9879 |
- If
|
| 9880 |
``` cpp
|
|
|
|
| 9895 |
`auto t = status(to)`.
|
| 9896 |
|
| 9897 |
Effects are then as follows:
|
| 9898 |
|
| 9899 |
- If `f.type()` or `t.type()` is an implementation-defined file
|
| 9900 |
+
type [[fs.enum.file.type]], then the effects are
|
| 9901 |
*implementation-defined*.
|
| 9902 |
- Otherwise, an error is reported as specified in [[fs.err.report]] if:
|
| 9903 |
+
- `exists(f)` is `false`, or
|
| 9904 |
+
- `equivalent(from, to)` is `true`, or
|
| 9905 |
+
- `is_other(f) || is_other(t)` is `true`, or
|
| 9906 |
+
- `is_directory(f) && is_regular_file(t)` is `true`.
|
| 9907 |
- Otherwise, if `is_symlink(f)`, then:
|
| 9908 |
- If `(options & copy_options::skip_symlinks) != copy_options::none`
|
| 9909 |
then return.
|
| 9910 |
- Otherwise if
|
| 9911 |
``` cpp
|
|
|
|
| 9925 |
`(options & copy_options::create_hard_links) != copy_options::none`,
|
| 9926 |
then create a hard link to the source file.
|
| 9927 |
- Otherwise, if `is_directory(t)`, then
|
| 9928 |
`copy_file(from, to/from.filename(), options)`.
|
| 9929 |
- Otherwise, `copy_file(from, to, options)`.
|
| 9930 |
+
- Otherwise, if
|
| 9931 |
+
``` cpp
|
| 9932 |
+
is_directory(f) &&
|
| 9933 |
+
(options & copy_options::create_symlinks) != copy_options::none
|
| 9934 |
+
```
|
| 9935 |
+
|
| 9936 |
+
then report an error with an `error_code` argument equal to
|
| 9937 |
+
`make_error_code(errc::is_a_directory)`.
|
| 9938 |
- Otherwise, if
|
| 9939 |
``` cpp
|
| 9940 |
is_directory(f) &&
|
| 9941 |
((options & copy_options::recursive) != copy_options::none ||
|
| 9942 |
options == copy_options::none)
|
| 9943 |
```
|
| 9944 |
|
| 9945 |
then:
|
| 9946 |
+
- If `exists(t)` is `false`, then `create_directory(to, from)`.
|
| 9947 |
- Then, iterate over the files in `from`, as if by
|
| 9948 |
``` cpp
|
| 9949 |
for (const directory_entry& x : directory_iterator(from))
|
| 9950 |
+
copy(x.path(), to/x.path().filename(),
|
| 9951 |
+
options | copy_options::in-recursive-copy);
|
| 9952 |
```
|
| 9953 |
+
|
| 9954 |
+
where *`in-recursive-copy`* is a bitmask element of `copy_options`
|
| 9955 |
+
that is not one of the elements in [[fs.enum.copy.opts]].
|
| 9956 |
- Otherwise, for the signature with argument `ec`, `ec.clear()`.
|
| 9957 |
- Otherwise, no effects.
|
| 9958 |
|
| 9959 |
*Throws:* As specified in [[fs.err.report]].
|
| 9960 |
|
|
|
|
| 10003 |
file3
|
| 10004 |
```
|
| 10005 |
|
| 10006 |
— *end example*]
|
| 10007 |
|
| 10008 |
+
#### Copy file <a id="fs.op.copy.file">[[fs.op.copy.file]]</a>
|
| 10009 |
|
| 10010 |
``` cpp
|
| 10011 |
bool copy_file(const path& from, const path& to);
|
| 10012 |
+
bool copy_file(const path& from, const path& to, error_code& ec);
|
| 10013 |
```
|
| 10014 |
|
| 10015 |
*Returns:* `copy_file(from, to, copy_options::none)` or
|
| 10016 |
`copy_file(from, to, copy_options::none, ec)`, respectively.
|
| 10017 |
|
| 10018 |
*Throws:* As specified in [[fs.err.report]].
|
| 10019 |
|
| 10020 |
``` cpp
|
| 10021 |
bool copy_file(const path& from, const path& to, copy_options options);
|
| 10022 |
bool copy_file(const path& from, const path& to, copy_options options,
|
| 10023 |
+
error_code& ec);
|
| 10024 |
```
|
| 10025 |
|
| 10026 |
+
*Preconditions:* At most one element from each option
|
| 10027 |
+
group [[fs.enum.copy.opts]] is set in `options`.
|
| 10028 |
|
| 10029 |
*Effects:* As follows:
|
| 10030 |
|
| 10031 |
+
- Report an error as specified in [[fs.err.report]] if:
|
| 10032 |
+
- `is_regular_file(from)` is `false`, or
|
| 10033 |
+
- `exists(to)` is `true` and `is_regular_file(to)` is `false`, or
|
| 10034 |
+
- `exists(to)` is `true` and `equivalent(from, to)` is `true`, or
|
| 10035 |
+
- `exists(to)` is `true` and
|
|
|
|
| 10036 |
``` cpp
|
| 10037 |
(options & (copy_options::skip_existing |
|
| 10038 |
copy_options::overwrite_existing |
|
| 10039 |
copy_options::update_existing)) == copy_options::none
|
| 10040 |
```
|
| 10041 |
- Otherwise, copy the contents and attributes of the file `from`
|
| 10042 |
resolves to, to the file `to` resolves to, if:
|
| 10043 |
+
- `exists(to)` is `false`, or
|
| 10044 |
- `(options & copy_options::overwrite_existing) != copy_options::none`,
|
| 10045 |
or
|
| 10046 |
- `(options & copy_options::update_existing) `` `` != copy_options::none`
|
| 10047 |
and `from` is more recent than `to`, determined as if by use of the
|
| 10048 |
+
`last_write_time` function [[fs.op.last.write.time]].
|
| 10049 |
- Otherwise, no effects.
|
| 10050 |
|
| 10051 |
*Returns:* `true` if the `from` file was copied, otherwise `false`. The
|
| 10052 |
signature with argument `ec` returns `false` if an error occurs.
|
| 10053 |
|
| 10054 |
*Throws:* As specified in [[fs.err.report]].
|
| 10055 |
|
| 10056 |
*Complexity:* At most one direct or indirect invocation of `status(to)`.
|
| 10057 |
|
| 10058 |
+
#### Copy symlink <a id="fs.op.copy.symlink">[[fs.op.copy.symlink]]</a>
|
| 10059 |
|
| 10060 |
``` cpp
|
| 10061 |
void copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 10062 |
void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 10063 |
error_code& ec) noexcept;
|
|
|
|
| 10069 |
respectively, where in each case *`function`* is `create_symlink` or
|
| 10070 |
`create_directory_symlink` as appropriate.
|
| 10071 |
|
| 10072 |
*Throws:* As specified in [[fs.err.report]].
|
| 10073 |
|
| 10074 |
+
#### Create directories <a id="fs.op.create.directories">[[fs.op.create.directories]]</a>
|
| 10075 |
|
| 10076 |
``` cpp
|
| 10077 |
bool create_directories(const path& p);
|
| 10078 |
+
bool create_directories(const path& p, error_code& ec);
|
| 10079 |
```
|
| 10080 |
|
| 10081 |
+
*Effects:* Calls `create_directory()` for each element of `p` that does
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 10082 |
not exist.
|
| 10083 |
|
| 10084 |
+
*Returns:* `true` if a new directory was created for the directory `p`
|
| 10085 |
+
resolves to, otherwise `false`.
|
| 10086 |
+
|
| 10087 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 10088 |
+
|
| 10089 |
+
*Complexity:* 𝑂(n) where *n* is the number of elements of `p`.
|
| 10090 |
+
|
| 10091 |
+
#### Create directory <a id="fs.op.create.directory">[[fs.op.create.directory]]</a>
|
| 10092 |
|
| 10093 |
``` cpp
|
| 10094 |
bool create_directory(const path& p);
|
| 10095 |
bool create_directory(const path& p, error_code& ec) noexcept;
|
| 10096 |
```
|
| 10097 |
|
| 10098 |
+
*Effects:* Creates the directory `p` resolves to, as if by POSIX `mkdir`
|
| 10099 |
+
with a second argument of `static_cast<int>(perms::all)`. If `mkdir`
|
| 10100 |
+
fails because `p` resolves to an existing directory, no error is
|
| 10101 |
+
reported. Otherwise on failure an error is reported.
|
| 10102 |
|
| 10103 |
+
*Returns:* `true` if a new directory was created, otherwise `false`.
|
|
|
|
|
|
|
|
|
|
| 10104 |
|
| 10105 |
*Throws:* As specified in [[fs.err.report]].
|
| 10106 |
|
| 10107 |
``` cpp
|
| 10108 |
bool create_directory(const path& p, const path& existing_p);
|
| 10109 |
bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
|
| 10110 |
```
|
| 10111 |
|
| 10112 |
+
*Effects:* Creates the directory `p` resolves to, with attributes copied
|
| 10113 |
+
from directory `existing_p`. The set of attributes copied is operating
|
| 10114 |
+
system dependent. If `mkdir` fails because `p` resolves to an existing
|
| 10115 |
+
directory, no error is reported. Otherwise on failure an error is
|
| 10116 |
+
reported.
|
| 10117 |
|
| 10118 |
[*Note 1*: For POSIX-based operating systems, the attributes are those
|
| 10119 |
copied by native API `stat(existing_p.c_str(), &attributes_stat)`
|
| 10120 |
followed by `mkdir(p.c_str(), attributes_stat.st_mode)`. For
|
| 10121 |
Windows-based operating systems, the attributes are those copied by
|
| 10122 |
native API
|
| 10123 |
`CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0)`. — *end note*]
|
| 10124 |
|
| 10125 |
+
*Returns:* `true` if a new directory was created with attributes copied
|
| 10126 |
+
from directory `existing_p`, otherwise `false`.
|
|
|
|
|
|
|
| 10127 |
|
| 10128 |
*Throws:* As specified in [[fs.err.report]].
|
| 10129 |
|
| 10130 |
+
#### Create directory symlink <a id="fs.op.create.dir.symlk">[[fs.op.create.dir.symlk]]</a>
|
| 10131 |
|
| 10132 |
``` cpp
|
| 10133 |
void create_directory_symlink(const path& to, const path& new_symlink);
|
| 10134 |
void create_directory_symlink(const path& to, const path& new_symlink,
|
| 10135 |
error_code& ec) noexcept;
|
| 10136 |
```
|
| 10137 |
|
| 10138 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 10139 |
|
| 10140 |
+
*Ensures:* `new_symlink` resolves to a symbolic link file that contains
|
| 10141 |
+
an unspecified representation of `to`.
|
| 10142 |
|
| 10143 |
*Throws:* As specified in [[fs.err.report]].
|
| 10144 |
|
| 10145 |
[*Note 1*: Some operating systems require symlink creation to identify
|
| 10146 |
that the link is to a directory. Portable code should use
|
|
|
|
| 10150 |
[*Note 2*: Some operating systems do not support symbolic links at all
|
| 10151 |
or support them only for regular files. Some file systems (such as the
|
| 10152 |
FAT file system) do not support symbolic links regardless of the
|
| 10153 |
operating system. — *end note*]
|
| 10154 |
|
| 10155 |
+
#### Create hard link <a id="fs.op.create.hard.lk">[[fs.op.create.hard.lk]]</a>
|
| 10156 |
|
| 10157 |
``` cpp
|
| 10158 |
void create_hard_link(const path& to, const path& new_hard_link);
|
| 10159 |
void create_hard_link(const path& to, const path& new_hard_link,
|
| 10160 |
error_code& ec) noexcept;
|
| 10161 |
```
|
| 10162 |
|
| 10163 |
*Effects:* Establishes the postcondition, as if by POSIX `link()`.
|
| 10164 |
|
| 10165 |
+
*Ensures:*
|
| 10166 |
|
| 10167 |
- `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
|
| 10168 |
- The contents of the file or directory `to` resolves to are unchanged.
|
| 10169 |
|
| 10170 |
*Throws:* As specified in [[fs.err.report]].
|
|
|
|
| 10173 |
support them only for regular files. Some file systems (such as the FAT
|
| 10174 |
file system) do not support hard links regardless of the operating
|
| 10175 |
system. Some file systems limit the number of links per
|
| 10176 |
file. — *end note*]
|
| 10177 |
|
| 10178 |
+
#### Create symlink <a id="fs.op.create.symlink">[[fs.op.create.symlink]]</a>
|
| 10179 |
|
| 10180 |
``` cpp
|
| 10181 |
void create_symlink(const path& to, const path& new_symlink);
|
| 10182 |
void create_symlink(const path& to, const path& new_symlink,
|
| 10183 |
error_code& ec) noexcept;
|
| 10184 |
```
|
| 10185 |
|
| 10186 |
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 10187 |
|
| 10188 |
+
*Ensures:* `new_symlink` resolves to a symbolic link file that contains
|
| 10189 |
+
an unspecified representation of `to`.
|
| 10190 |
|
| 10191 |
*Throws:* As specified in [[fs.err.report]].
|
| 10192 |
|
| 10193 |
[*Note 1*: Some operating systems do not support symbolic links at all
|
| 10194 |
or support them only for regular files. Some file systems (such as the
|
| 10195 |
FAT file system) do not support symbolic links regardless of the
|
| 10196 |
operating system. — *end note*]
|
| 10197 |
|
| 10198 |
+
#### Current path <a id="fs.op.current.path">[[fs.op.current.path]]</a>
|
| 10199 |
|
| 10200 |
``` cpp
|
| 10201 |
path current_path();
|
| 10202 |
path current_path(error_code& ec);
|
| 10203 |
```
|
|
|
|
| 10215 |
[*Note 1*: The `current_path()` name was chosen to emphasize that the
|
| 10216 |
returned value is a path, not just a single directory
|
| 10217 |
name. — *end note*]
|
| 10218 |
|
| 10219 |
[*Note 2*: The current path as returned by many operating systems is a
|
| 10220 |
+
dangerous global variable. It may be changed unexpectedly by third-party
|
| 10221 |
+
or system library functions, or by another thread. — *end note*]
|
|
|
|
| 10222 |
|
| 10223 |
``` cpp
|
| 10224 |
void current_path(const path& p);
|
| 10225 |
void current_path(const path& p, error_code& ec) noexcept;
|
| 10226 |
```
|
| 10227 |
|
| 10228 |
*Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
|
| 10229 |
|
| 10230 |
+
*Ensures:* `equivalent(p, current_path())`.
|
| 10231 |
|
| 10232 |
*Throws:* As specified in [[fs.err.report]].
|
| 10233 |
|
| 10234 |
[*Note 3*: The current path for many operating systems is a dangerous
|
| 10235 |
global state. It may be changed unexpectedly by a third-party or system
|
|
|
|
| 10240 |
``` cpp
|
| 10241 |
bool equivalent(const path& p1, const path& p2);
|
| 10242 |
bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 10243 |
```
|
| 10244 |
|
| 10245 |
+
*Returns:* `true`, if `p1` and `p2` resolve to the same file system
|
| 10246 |
+
entity, otherwise `false`. The signature with argument `ec` returns
|
| 10247 |
+
`false` if an error occurs.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 10248 |
|
| 10249 |
Two paths are considered to resolve to the same file system entity if
|
| 10250 |
two candidate entities reside on the same device at the same location.
|
| 10251 |
+
|
| 10252 |
+
[*Note 1*: On POSIX platforms, this is determined as if by the values
|
| 10253 |
+
of the POSIX `stat` class, obtained as if by `stat()` for the two paths,
|
| 10254 |
+
having equal `st_dev` values and equal `st_ino` values. — *end note*]
|
| 10255 |
+
|
| 10256 |
+
*Remarks:* `!exists(p1) || !exists(p2)` is an error.
|
| 10257 |
|
| 10258 |
*Throws:* As specified in [[fs.err.report]].
|
| 10259 |
|
| 10260 |
#### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
|
| 10261 |
|
|
|
|
| 10278 |
|
| 10279 |
*Returns:* `exists(s)`.
|
| 10280 |
|
| 10281 |
*Throws:* As specified in [[fs.err.report]].
|
| 10282 |
|
| 10283 |
+
#### File size <a id="fs.op.file.size">[[fs.op.file.size]]</a>
|
| 10284 |
|
| 10285 |
``` cpp
|
| 10286 |
uintmax_t file_size(const path& p);
|
| 10287 |
uintmax_t file_size(const path& p, error_code& ec) noexcept;
|
| 10288 |
```
|
| 10289 |
|
| 10290 |
+
*Effects:* If `exists(p)` is `false`, an error is
|
| 10291 |
+
reported [[fs.err.report]].
|
| 10292 |
+
|
| 10293 |
*Returns:*
|
| 10294 |
|
| 10295 |
+
- If `is_regular_file(p)`, the size in bytes of the file `p` resolves
|
| 10296 |
+
to, determined as if by the value of the POSIX `stat` class member
|
| 10297 |
+
`st_size` obtained as if by POSIX `stat()`.
|
|
|
|
| 10298 |
- Otherwise, the result is *implementation-defined*.
|
| 10299 |
|
| 10300 |
The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
|
| 10301 |
an error occurs.
|
| 10302 |
|
| 10303 |
*Throws:* As specified in [[fs.err.report]].
|
| 10304 |
|
| 10305 |
+
#### Hard link count <a id="fs.op.hard.lk.ct">[[fs.op.hard.lk.ct]]</a>
|
| 10306 |
|
| 10307 |
``` cpp
|
| 10308 |
uintmax_t hard_link_count(const path& p);
|
| 10309 |
uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
| 10310 |
```
|
|
|
|
| 10312 |
*Returns:* The number of hard links for `p`. The signature with argument
|
| 10313 |
`ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
|
| 10314 |
|
| 10315 |
*Throws:* As specified in [[fs.err.report]].
|
| 10316 |
|
| 10317 |
+
#### Is block file <a id="fs.op.is.block.file">[[fs.op.is.block.file]]</a>
|
| 10318 |
|
| 10319 |
``` cpp
|
| 10320 |
bool is_block_file(file_status s) noexcept;
|
| 10321 |
```
|
| 10322 |
|
|
|
|
| 10331 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10332 |
error occurs.
|
| 10333 |
|
| 10334 |
*Throws:* As specified in [[fs.err.report]].
|
| 10335 |
|
| 10336 |
+
#### Is character file <a id="fs.op.is.char.file">[[fs.op.is.char.file]]</a>
|
| 10337 |
|
| 10338 |
``` cpp
|
| 10339 |
bool is_character_file(file_status s) noexcept;
|
| 10340 |
```
|
| 10341 |
|
|
|
|
| 10350 |
`is_character_file(status(p, ec))`, respectively.
|
| 10351 |
The signature with argument `ec` returns `false` if an error occurs.
|
| 10352 |
|
| 10353 |
*Throws:* As specified in [[fs.err.report]].
|
| 10354 |
|
| 10355 |
+
#### Is directory <a id="fs.op.is.directory">[[fs.op.is.directory]]</a>
|
| 10356 |
|
| 10357 |
``` cpp
|
| 10358 |
bool is_directory(file_status s) noexcept;
|
| 10359 |
```
|
| 10360 |
|
|
|
|
| 10369 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10370 |
error occurs.
|
| 10371 |
|
| 10372 |
*Throws:* As specified in [[fs.err.report]].
|
| 10373 |
|
| 10374 |
+
#### Is empty <a id="fs.op.is.empty">[[fs.op.is.empty]]</a>
|
| 10375 |
|
| 10376 |
``` cpp
|
| 10377 |
bool is_empty(const path& p);
|
| 10378 |
+
bool is_empty(const path& p, error_code& ec);
|
| 10379 |
```
|
| 10380 |
|
| 10381 |
*Effects:*
|
| 10382 |
|
| 10383 |
- Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
|
|
|
|
| 10397 |
occurred.
|
| 10398 |
- Otherwise, return `sz == 0`.
|
| 10399 |
|
| 10400 |
*Throws:* As specified in [[fs.err.report]].
|
| 10401 |
|
| 10402 |
+
#### Is fifo <a id="fs.op.is.fifo">[[fs.op.is.fifo]]</a>
|
| 10403 |
|
| 10404 |
``` cpp
|
| 10405 |
bool is_fifo(file_status s) noexcept;
|
| 10406 |
```
|
| 10407 |
|
|
|
|
| 10416 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10417 |
error occurs.
|
| 10418 |
|
| 10419 |
*Throws:* As specified in [[fs.err.report]].
|
| 10420 |
|
| 10421 |
+
#### Is other <a id="fs.op.is.other">[[fs.op.is.other]]</a>
|
| 10422 |
|
| 10423 |
``` cpp
|
| 10424 |
bool is_other(file_status s) noexcept;
|
| 10425 |
```
|
| 10426 |
|
|
|
|
| 10436 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10437 |
error occurs.
|
| 10438 |
|
| 10439 |
*Throws:* As specified in [[fs.err.report]].
|
| 10440 |
|
| 10441 |
+
#### Is regular file <a id="fs.op.is.regular.file">[[fs.op.is.regular.file]]</a>
|
| 10442 |
|
| 10443 |
``` cpp
|
| 10444 |
bool is_regular_file(file_status s) noexcept;
|
| 10445 |
```
|
| 10446 |
|
|
|
|
| 10451 |
```
|
| 10452 |
|
| 10453 |
*Returns:* `is_regular_file(status(p))`.
|
| 10454 |
|
| 10455 |
*Throws:* `filesystem_error` if `status(p)` would throw
|
| 10456 |
+
`filesystem_error`.
|
| 10457 |
|
| 10458 |
``` cpp
|
| 10459 |
bool is_regular_file(const path& p, error_code& ec) noexcept;
|
| 10460 |
```
|
| 10461 |
|
|
|
|
| 10466 |
between cases, call the `status` function directly. — *end note*]
|
| 10467 |
|
| 10468 |
*Returns:* `is_regular_file(status(p, ec))`. Returns `false` if an error
|
| 10469 |
occurs.
|
| 10470 |
|
| 10471 |
+
#### Is socket <a id="fs.op.is.socket">[[fs.op.is.socket]]</a>
|
| 10472 |
|
| 10473 |
``` cpp
|
| 10474 |
bool is_socket(file_status s) noexcept;
|
| 10475 |
```
|
| 10476 |
|
|
|
|
| 10485 |
respectively. The signature with argument `ec` returns `false` if an
|
| 10486 |
error occurs.
|
| 10487 |
|
| 10488 |
*Throws:* As specified in [[fs.err.report]].
|
| 10489 |
|
| 10490 |
+
#### Is symlink <a id="fs.op.is.symlink">[[fs.op.is.symlink]]</a>
|
| 10491 |
|
| 10492 |
``` cpp
|
| 10493 |
bool is_symlink(file_status s) noexcept;
|
| 10494 |
```
|
| 10495 |
|
|
|
|
| 10504 |
`is_symlink(symlink_status(p, ec))`, respectively. The signature with
|
| 10505 |
argument `ec` returns `false` if an error occurs.
|
| 10506 |
|
| 10507 |
*Throws:* As specified in [[fs.err.report]].
|
| 10508 |
|
| 10509 |
+
#### Last write time <a id="fs.op.last.write.time">[[fs.op.last.write.time]]</a>
|
| 10510 |
|
| 10511 |
``` cpp
|
| 10512 |
file_time_type last_write_time(const path& p);
|
| 10513 |
file_time_type last_write_time(const path& p, error_code& ec) noexcept;
|
| 10514 |
```
|
| 10515 |
|
| 10516 |
*Returns:* The time of last data modification of `p`, determined as if
|
| 10517 |
+
by the value of the POSIX `stat` class member `st_mtime` obtained as if
|
| 10518 |
+
by POSIX `stat()`. The signature with argument `ec` returns
|
| 10519 |
`file_time_type::min()` if an error occurs.
|
| 10520 |
|
| 10521 |
*Throws:* As specified in [[fs.err.report]].
|
| 10522 |
|
| 10523 |
``` cpp
|
|
|
|
| 10541 |
void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
|
| 10542 |
void permissions(const path& p, perms prms, error_code& ec) noexcept;
|
| 10543 |
void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
|
| 10544 |
```
|
| 10545 |
|
| 10546 |
+
*Preconditions:* Exactly one of the `perm_options` constants `replace`,
|
| 10547 |
`add`, or `remove` is present in `opts`.
|
| 10548 |
|
| 10549 |
*Remarks:* The second signature behaves as if it had an additional
|
| 10550 |
parameter `perm_options` `opts` with an argument of
|
| 10551 |
`perm_options::replace`.
|
|
|
|
| 10589 |
|
| 10590 |
or `path()` at the first error occurrence, if any.
|
| 10591 |
|
| 10592 |
*Throws:* As specified in [[fs.err.report]].
|
| 10593 |
|
| 10594 |
+
#### Read symlink <a id="fs.op.read.symlink">[[fs.op.read.symlink]]</a>
|
| 10595 |
|
| 10596 |
``` cpp
|
| 10597 |
path read_symlink(const path& p);
|
| 10598 |
path read_symlink(const path& p, error_code& ec);
|
| 10599 |
```
|
|
|
|
| 10649 |
as if by POSIX `remove()`.
|
| 10650 |
|
| 10651 |
[*Note 1*: A symbolic link is itself removed, rather than the file it
|
| 10652 |
resolves to. — *end note*]
|
| 10653 |
|
| 10654 |
+
*Ensures:* `exists(symlink_status(p))` is `false`.
|
| 10655 |
|
| 10656 |
*Returns:* `false` if `p` did not exist, otherwise `true`. The signature
|
| 10657 |
with argument `ec` returns `false` if an error occurs.
|
| 10658 |
|
| 10659 |
*Throws:* As specified in [[fs.err.report]].
|
| 10660 |
|
| 10661 |
+
#### Remove all <a id="fs.op.remove.all">[[fs.op.remove.all]]</a>
|
| 10662 |
|
| 10663 |
``` cpp
|
| 10664 |
uintmax_t remove_all(const path& p);
|
| 10665 |
+
uintmax_t remove_all(const path& p, error_code& ec);
|
| 10666 |
```
|
| 10667 |
|
| 10668 |
*Effects:* Recursively deletes the contents of `p` if it exists, then
|
| 10669 |
deletes file `p` itself, as if by POSIX `remove()`.
|
| 10670 |
|
| 10671 |
[*Note 1*: A symbolic link is itself removed, rather than the file it
|
| 10672 |
resolves to. — *end note*]
|
| 10673 |
|
| 10674 |
+
*Ensures:* `exists(symlink_status(p))` is `false`.
|
| 10675 |
|
| 10676 |
*Returns:* The number of files removed. The signature with argument `ec`
|
| 10677 |
returns `static_cast< uintmax_t>(-1)` if an error occurs.
|
| 10678 |
|
| 10679 |
*Throws:* As specified in [[fs.err.report]].
|
|
|
|
| 10702 |
|
| 10703 |
— *end note*]
|
| 10704 |
|
| 10705 |
*Throws:* As specified in [[fs.err.report]].
|
| 10706 |
|
| 10707 |
+
#### Resize file <a id="fs.op.resize.file">[[fs.op.resize.file]]</a>
|
| 10708 |
|
| 10709 |
``` cpp
|
| 10710 |
void resize_file(const path& p, uintmax_t new_size);
|
| 10711 |
void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
|
| 10712 |
```
|
| 10713 |
|
| 10714 |
+
*Effects:* Causes the size that would be returned by `file_size(p)` to
|
| 10715 |
+
be equal to `new_size`, as if by POSIX `truncate()`.
|
| 10716 |
|
| 10717 |
*Throws:* As specified in [[fs.err.report]].
|
| 10718 |
|
|
|
|
|
|
|
| 10719 |
#### Space <a id="fs.op.space">[[fs.op.space]]</a>
|
| 10720 |
|
| 10721 |
``` cpp
|
| 10722 |
space_info space(const path& p);
|
| 10723 |
space_info space(const path& p, error_code& ec) noexcept;
|
|
|
|
| 10816 |
- Otherwise, if the attributes indicate a fifo or pipe file, as if by
|
| 10817 |
POSIX `S_ISFIFO`, returns `file_status(file_type::fifo, prms)`.
|
| 10818 |
- Otherwise, if the attributes indicate a socket, as if by POSIX
|
| 10819 |
`S_ISSOCK`, returns `file_status(file_type::socket, prms)`.
|
| 10820 |
- Otherwise, if the attributes indicate an implementation-defined file
|
| 10821 |
+
type [[fs.enum.file.type]], returns
|
| 10822 |
`file_status(file_type::`*`A`*`, prms)`, where *A* is the constant
|
| 10823 |
for the *implementation-defined* file type.
|
| 10824 |
- Otherwise, returns `file_status(file_type::unknown, prms)`.
|
| 10825 |
|
| 10826 |
*Remarks:* If a symbolic link is encountered during pathname resolution,
|
| 10827 |
pathname resolution continues using the contents of the symbolic link.
|
| 10828 |
|
| 10829 |
+
#### Status known <a id="fs.op.status.known">[[fs.op.status.known]]</a>
|
| 10830 |
|
| 10831 |
``` cpp
|
| 10832 |
bool status_known(file_status s) noexcept;
|
| 10833 |
```
|
| 10834 |
|
| 10835 |
*Returns:* `s.type() != file_type::none`.
|
| 10836 |
|
| 10837 |
+
#### Symlink status <a id="fs.op.symlink.status">[[fs.op.symlink.status]]</a>
|
| 10838 |
|
| 10839 |
``` cpp
|
| 10840 |
file_status symlink_status(const path& p);
|
| 10841 |
file_status symlink_status(const path& p, error_code& ec) noexcept;
|
| 10842 |
```
|
|
|
|
| 10856 |
|
| 10857 |
*Remarks:* Pathname resolution terminates if `p` names a symbolic link.
|
| 10858 |
|
| 10859 |
*Throws:* As specified in [[fs.err.report]].
|
| 10860 |
|
| 10861 |
+
#### Temporary directory path <a id="fs.op.temp.dir.path">[[fs.op.temp.dir.path]]</a>
|
| 10862 |
|
| 10863 |
``` cpp
|
| 10864 |
path temp_directory_path();
|
| 10865 |
path temp_directory_path(error_code& ec);
|
| 10866 |
```
|
| 10867 |
|
| 10868 |
+
Let `p` be an unspecified directory path suitable for temporary files.
|
| 10869 |
+
|
| 10870 |
+
*Effects:* If `exists(p)` is `false` or `is_directory(p)` is `false`, an
|
| 10871 |
+
error is reported [[fs.err.report]].
|
| 10872 |
+
|
| 10873 |
+
*Returns:* The path `p`. The signature with argument `ec` returns
|
| 10874 |
`path()` if an error occurs.
|
| 10875 |
|
| 10876 |
*Throws:* As specified in [[fs.err.report]].
|
| 10877 |
|
| 10878 |
[*Example 1*: For POSIX-based operating systems, an implementation
|
|
|
|
| 10880 |
in the list TMPDIR, TMP, TEMP, TEMPDIR, or if none of these are found,
|
| 10881 |
`"/tmp"`. For Windows-based operating systems, an implementation might
|
| 10882 |
return the path reported by the Windows `GetTempPath` API
|
| 10883 |
function. — *end example*]
|
| 10884 |
|
| 10885 |
+
#### Weakly canonical <a id="fs.op.weakly.canonical">[[fs.op.weakly.canonical]]</a>
|
| 10886 |
|
| 10887 |
``` cpp
|
| 10888 |
path weakly_canonical(const path& p);
|
| 10889 |
path weakly_canonical(const path& p, error_code& ec);
|
| 10890 |
```
|
| 10891 |
|
| 10892 |
*Returns:* `p` with symlinks resolved and the result
|
| 10893 |
+
normalized [[fs.path.generic]].
|
| 10894 |
|
| 10895 |
*Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
|
| 10896 |
determine existence, return a path composed by `operator/=` from the
|
| 10897 |
+
result of calling `canonical()` with a path argument composed of the
|
| 10898 |
+
leading elements of `p` that exist, if any, followed by the elements of
|
| 10899 |
+
`p` that do not exist, if any. For the first form, `canonical()` is
|
| 10900 |
+
called without an `error_code` argument. For the second form,
|
| 10901 |
+
`canonical()` is called with `ec` as an `error_code` argument, and
|
| 10902 |
+
`path()` is returned at the first error occurrence, if any.
|
|
|
|
| 10903 |
|
| 10904 |
+
*Ensures:* The returned path is in normal form [[fs.path.generic]].
|
|
|
|
| 10905 |
|
| 10906 |
+
*Remarks:* Implementations should avoid unnecessary normalization such
|
| 10907 |
+
as when `canonical` has already been called on the entirety of `p`.
|
|
|
|
| 10908 |
|
| 10909 |
*Throws:* As specified in [[fs.err.report]].
|
| 10910 |
|
| 10911 |
## C library files <a id="c.files">[[c.files]]</a>
|
| 10912 |
|
|
|
|
| 10936 |
#define stdin see below
|
| 10937 |
#define stdout see below
|
| 10938 |
|
| 10939 |
namespace std {
|
| 10940 |
int remove(const char* filename);
|
| 10941 |
+
int rename(const char* old_p, const char* new_p);
|
| 10942 |
FILE* tmpfile();
|
| 10943 |
char* tmpnam(char* s);
|
| 10944 |
int fclose(FILE* stream);
|
| 10945 |
int fflush(FILE* stream);
|
| 10946 |
FILE* fopen(const char* filename, const char* mode);
|
|
|
|
| 10987 |
|
| 10988 |
The contents and meaning of the header `<cstdio>` are the same as the C
|
| 10989 |
standard library header `<stdio.h>`.
|
| 10990 |
|
| 10991 |
Calls to the function `tmpnam` with an argument that is a null pointer
|
| 10992 |
+
value may introduce a data race [[res.on.data.races]] with other calls
|
| 10993 |
+
to `tmpnam` with an argument that is a null pointer value.
|
| 10994 |
|
| 10995 |
+
See also: ISO C 7.21
|
| 10996 |
|
| 10997 |
### Header `<cinttypes>` synopsis <a id="cinttypes.syn">[[cinttypes.syn]]</a>
|
| 10998 |
|
| 10999 |
``` cpp
|
| 11000 |
#include <cstdint> // see [cstdint.syn]
|
|
|
|
| 11073 |
The contents and meaning of the header `<cinttypes>` are the same as the
|
| 11074 |
C standard library header `<inttypes.h>`, with the following changes:
|
| 11075 |
|
| 11076 |
- The header `<cinttypes>` includes the header `<cstdint>` instead of
|
| 11077 |
`<stdint.h>`, and
|
| 11078 |
+
- if and only if the type `intmax_t` designates an extended integer type
|
| 11079 |
+
[[basic.fundamental]], the following function signatures are added:
|
|
|
|
| 11080 |
``` cpp
|
| 11081 |
intmax_t abs(intmax_t);
|
| 11082 |
imaxdiv_t div(intmax_t, intmax_t);
|
| 11083 |
```
|
| 11084 |
|
| 11085 |
which shall have the same semantics as the function signatures
|
| 11086 |
`intmax_t imaxabs(intmax_t)` and
|
| 11087 |
`imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
|
| 11088 |
|
| 11089 |
+
See also: ISO C 7.8
|
| 11090 |
|
| 11091 |
<!-- Link reference definitions -->
|
| 11092 |
[adjustfield.manip]: #adjustfield.manip
|
|
|
|
| 11093 |
[basefield.manip]: #basefield.manip
|
| 11094 |
[basic.fundamental]: basic.md#basic.fundamental
|
| 11095 |
[basic.ios.cons]: #basic.ios.cons
|
| 11096 |
+
[basic.ios.copyfmt]: #basic.ios.copyfmt
|
| 11097 |
[basic.ios.members]: #basic.ios.members
|
| 11098 |
[basic.start.main]: basic.md#basic.start.main
|
| 11099 |
[bidirectional.iterators]: iterators.md#bidirectional.iterators
|
| 11100 |
[bitmask.types]: library.md#bitmask.types
|
| 11101 |
[c.files]: #c.files
|
| 11102 |
+
[char.traits]: strings.md#char.traits
|
| 11103 |
[cinttypes.syn]: #cinttypes.syn
|
| 11104 |
+
[container.requirements.general]: containers.md#container.requirements.general
|
| 11105 |
+
[cpp17.allocator]: #cpp17.allocator
|
| 11106 |
+
[cpp17.copyassignable]: #cpp17.copyassignable
|
| 11107 |
+
[cpp17.copyconstructible]: #cpp17.copyconstructible
|
| 11108 |
+
[cpp17.defaultconstructible]: #cpp17.defaultconstructible
|
| 11109 |
+
[cpp17.destructible]: #cpp17.destructible
|
| 11110 |
+
[cpp17.equalitycomparable]: #cpp17.equalitycomparable
|
| 11111 |
[cstdio.syn]: #cstdio.syn
|
| 11112 |
[defns.ntcts]: library.md#defns.ntcts
|
| 11113 |
[enumerated.types]: library.md#enumerated.types
|
| 11114 |
[error.reporting]: #error.reporting
|
| 11115 |
[ext.manip]: #ext.manip
|
|
|
|
| 11116 |
[file.streams]: #file.streams
|
| 11117 |
[filebuf]: #filebuf
|
| 11118 |
[filebuf.assign]: #filebuf.assign
|
| 11119 |
[filebuf.cons]: #filebuf.cons
|
| 11120 |
[filebuf.members]: #filebuf.members
|
| 11121 |
+
[filebuf.open.modes]: #filebuf.open.modes
|
| 11122 |
+
[filebuf.seekoff]: #filebuf.seekoff
|
| 11123 |
[filebuf.virtuals]: #filebuf.virtuals
|
|
|
|
| 11124 |
[filesystems]: #filesystems
|
| 11125 |
[floatfield.manip]: #floatfield.manip
|
| 11126 |
[fmtflags.manip]: #fmtflags.manip
|
| 11127 |
[fmtflags.state]: #fmtflags.state
|
| 11128 |
[fpos]: #fpos
|
| 11129 |
[fpos.members]: #fpos.members
|
| 11130 |
[fpos.operations]: #fpos.operations
|
| 11131 |
+
[fs.class.directory.entry]: #fs.class.directory.entry
|
| 11132 |
+
[fs.class.directory.iterator]: #fs.class.directory.iterator
|
| 11133 |
+
[fs.class.file.status]: #fs.class.file.status
|
| 11134 |
+
[fs.class.filesystem.error]: #fs.class.filesystem.error
|
| 11135 |
[fs.class.path]: #fs.class.path
|
| 11136 |
[fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
|
| 11137 |
[fs.conform.9945]: #fs.conform.9945
|
| 11138 |
[fs.conform.os]: #fs.conform.os
|
| 11139 |
[fs.conformance]: #fs.conformance
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11140 |
[fs.dir.entry.cons]: #fs.dir.entry.cons
|
| 11141 |
[fs.dir.entry.mods]: #fs.dir.entry.mods
|
| 11142 |
[fs.dir.entry.obs]: #fs.dir.entry.obs
|
| 11143 |
[fs.dir.itr.members]: #fs.dir.itr.members
|
| 11144 |
[fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
|
| 11145 |
[fs.enum]: #fs.enum
|
| 11146 |
[fs.enum.copy.opts]: #fs.enum.copy.opts
|
| 11147 |
[fs.enum.dir.opts]: #fs.enum.dir.opts
|
| 11148 |
+
[fs.enum.file.type]: #fs.enum.file.type
|
| 11149 |
[fs.enum.path.format]: #fs.enum.path.format
|
| 11150 |
[fs.enum.perm.opts]: #fs.enum.perm.opts
|
| 11151 |
[fs.enum.perms]: #fs.enum.perms
|
| 11152 |
[fs.err.report]: #fs.err.report
|
| 11153 |
+
[fs.file.status.cons]: #fs.file.status.cons
|
| 11154 |
+
[fs.file.status.mods]: #fs.file.status.mods
|
| 11155 |
+
[fs.file.status.obs]: #fs.file.status.obs
|
| 11156 |
+
[fs.filesystem.error.members]: #fs.filesystem.error.members
|
| 11157 |
[fs.filesystem.syn]: #fs.filesystem.syn
|
| 11158 |
[fs.general]: #fs.general
|
| 11159 |
[fs.norm.ref]: #fs.norm.ref
|
| 11160 |
[fs.op.absolute]: #fs.op.absolute
|
| 11161 |
[fs.op.canonical]: #fs.op.canonical
|
| 11162 |
[fs.op.copy]: #fs.op.copy
|
| 11163 |
+
[fs.op.copy.file]: #fs.op.copy.file
|
| 11164 |
+
[fs.op.copy.symlink]: #fs.op.copy.symlink
|
| 11165 |
+
[fs.op.create.dir.symlk]: #fs.op.create.dir.symlk
|
| 11166 |
+
[fs.op.create.directories]: #fs.op.create.directories
|
| 11167 |
+
[fs.op.create.directory]: #fs.op.create.directory
|
| 11168 |
+
[fs.op.create.hard.lk]: #fs.op.create.hard.lk
|
| 11169 |
+
[fs.op.create.symlink]: #fs.op.create.symlink
|
| 11170 |
+
[fs.op.current.path]: #fs.op.current.path
|
| 11171 |
[fs.op.equivalent]: #fs.op.equivalent
|
| 11172 |
[fs.op.exists]: #fs.op.exists
|
| 11173 |
+
[fs.op.file.size]: #fs.op.file.size
|
| 11174 |
[fs.op.funcs]: #fs.op.funcs
|
| 11175 |
+
[fs.op.hard.lk.ct]: #fs.op.hard.lk.ct
|
| 11176 |
+
[fs.op.is.block.file]: #fs.op.is.block.file
|
| 11177 |
+
[fs.op.is.char.file]: #fs.op.is.char.file
|
| 11178 |
+
[fs.op.is.directory]: #fs.op.is.directory
|
| 11179 |
+
[fs.op.is.empty]: #fs.op.is.empty
|
| 11180 |
+
[fs.op.is.fifo]: #fs.op.is.fifo
|
| 11181 |
+
[fs.op.is.other]: #fs.op.is.other
|
| 11182 |
+
[fs.op.is.regular.file]: #fs.op.is.regular.file
|
| 11183 |
+
[fs.op.is.socket]: #fs.op.is.socket
|
| 11184 |
+
[fs.op.is.symlink]: #fs.op.is.symlink
|
| 11185 |
+
[fs.op.last.write.time]: #fs.op.last.write.time
|
| 11186 |
[fs.op.permissions]: #fs.op.permissions
|
| 11187 |
[fs.op.proximate]: #fs.op.proximate
|
| 11188 |
+
[fs.op.read.symlink]: #fs.op.read.symlink
|
| 11189 |
[fs.op.relative]: #fs.op.relative
|
| 11190 |
[fs.op.remove]: #fs.op.remove
|
| 11191 |
+
[fs.op.remove.all]: #fs.op.remove.all
|
| 11192 |
[fs.op.rename]: #fs.op.rename
|
| 11193 |
+
[fs.op.resize.file]: #fs.op.resize.file
|
| 11194 |
[fs.op.space]: #fs.op.space
|
| 11195 |
[fs.op.status]: #fs.op.status
|
| 11196 |
+
[fs.op.status.known]: #fs.op.status.known
|
| 11197 |
+
[fs.op.symlink.status]: #fs.op.symlink.status
|
| 11198 |
+
[fs.op.temp.dir.path]: #fs.op.temp.dir.path
|
| 11199 |
+
[fs.op.weakly.canonical]: #fs.op.weakly.canonical
|
| 11200 |
[fs.path.append]: #fs.path.append
|
| 11201 |
[fs.path.assign]: #fs.path.assign
|
| 11202 |
[fs.path.compare]: #fs.path.compare
|
| 11203 |
[fs.path.concat]: #fs.path.concat
|
| 11204 |
[fs.path.construct]: #fs.path.construct
|
| 11205 |
[fs.path.cvt]: #fs.path.cvt
|
| 11206 |
[fs.path.decompose]: #fs.path.decompose
|
|
|
|
| 11207 |
[fs.path.fmt.cvt]: #fs.path.fmt.cvt
|
| 11208 |
[fs.path.gen]: #fs.path.gen
|
| 11209 |
[fs.path.generic]: #fs.path.generic
|
| 11210 |
[fs.path.generic.obs]: #fs.path.generic.obs
|
| 11211 |
[fs.path.io]: #fs.path.io
|
|
|
|
| 11233 |
[ifstream.members]: #ifstream.members
|
| 11234 |
[input.iterators]: iterators.md#input.iterators
|
| 11235 |
[input.output]: #input.output
|
| 11236 |
[input.output.general]: #input.output.general
|
| 11237 |
[input.streams]: #input.streams
|
| 11238 |
+
[intro.multithread]: basic.md#intro.multithread
|
| 11239 |
+
[intro.races]: basic.md#intro.races
|
| 11240 |
[iomanip.syn]: #iomanip.syn
|
| 11241 |
[ios]: #ios
|
| 11242 |
[ios.base]: #ios.base
|
| 11243 |
[ios.base.callback]: #ios.base.callback
|
| 11244 |
[ios.base.cons]: #ios.base.cons
|
| 11245 |
[ios.base.locales]: #ios.base.locales
|
| 11246 |
[ios.base.storage]: #ios.base.storage
|
| 11247 |
+
[ios.failure]: #ios.failure
|
| 11248 |
+
[ios.fmtflags]: #ios.fmtflags
|
| 11249 |
+
[ios.fmtflags.const]: #ios.fmtflags.const
|
| 11250 |
+
[ios.init]: #ios.init
|
| 11251 |
+
[ios.iostate]: #ios.iostate
|
| 11252 |
[ios.members.static]: #ios.members.static
|
| 11253 |
+
[ios.openmode]: #ios.openmode
|
| 11254 |
[ios.overview]: #ios.overview
|
| 11255 |
+
[ios.seekdir]: #ios.seekdir
|
| 11256 |
[ios.syn]: #ios.syn
|
| 11257 |
[ios.types]: #ios.types
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11258 |
[iosfwd.syn]: #iosfwd.syn
|
| 11259 |
[iostate.flags]: #iostate.flags
|
| 11260 |
[iostream.assign]: #iostream.assign
|
| 11261 |
[iostream.cons]: #iostream.cons
|
| 11262 |
[iostream.dest]: #iostream.dest
|
|
|
|
| 11269 |
[iostream.syn]: #iostream.syn
|
| 11270 |
[iostreamclass]: #iostreamclass
|
| 11271 |
[iostreams.base]: #iostreams.base
|
| 11272 |
[iostreams.limits.pos]: #iostreams.limits.pos
|
| 11273 |
[iostreams.requirements]: #iostreams.requirements
|
| 11274 |
+
[iostreams.summary]: #iostreams.summary
|
| 11275 |
[iostreams.threadsafety]: #iostreams.threadsafety
|
| 11276 |
[istream]: #istream
|
| 11277 |
[istream.assign]: #istream.assign
|
| 11278 |
[istream.cons]: #istream.cons
|
| 11279 |
[istream.extractors]: #istream.extractors
|
| 11280 |
[istream.formatted]: #istream.formatted
|
| 11281 |
[istream.formatted.arithmetic]: #istream.formatted.arithmetic
|
| 11282 |
[istream.formatted.reqmts]: #istream.formatted.reqmts
|
| 11283 |
[istream.manip]: #istream.manip
|
| 11284 |
[istream.rvalue]: #istream.rvalue
|
| 11285 |
+
[istream.sentry]: #istream.sentry
|
| 11286 |
[istream.syn]: #istream.syn
|
| 11287 |
[istream.unformatted]: #istream.unformatted
|
|
|
|
| 11288 |
[istringstream]: #istringstream
|
| 11289 |
[istringstream.assign]: #istringstream.assign
|
| 11290 |
[istringstream.cons]: #istringstream.cons
|
| 11291 |
[istringstream.members]: #istringstream.members
|
| 11292 |
[lex.charset]: lex.md#lex.charset
|
| 11293 |
[locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
|
| 11294 |
[locale.num.get]: localization.md#locale.num.get
|
| 11295 |
+
[namespace.std]: library.md#namespace.std
|
| 11296 |
[narrow.stream.objects]: #narrow.stream.objects
|
| 11297 |
+
[numeric.limits]: support.md#numeric.limits
|
| 11298 |
[ofstream]: #ofstream
|
| 11299 |
[ofstream.assign]: #ofstream.assign
|
| 11300 |
[ofstream.cons]: #ofstream.cons
|
| 11301 |
[ofstream.members]: #ofstream.members
|
| 11302 |
[ostream]: #ostream
|
|
|
|
| 11308 |
[ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
|
| 11309 |
[ostream.inserters.character]: #ostream.inserters.character
|
| 11310 |
[ostream.manip]: #ostream.manip
|
| 11311 |
[ostream.rvalue]: #ostream.rvalue
|
| 11312 |
[ostream.seeks]: #ostream.seeks
|
| 11313 |
+
[ostream.sentry]: #ostream.sentry
|
| 11314 |
[ostream.syn]: #ostream.syn
|
| 11315 |
[ostream.unformatted]: #ostream.unformatted
|
|
|
|
| 11316 |
[ostringstream]: #ostringstream
|
| 11317 |
[ostringstream.assign]: #ostringstream.assign
|
| 11318 |
[ostringstream.cons]: #ostringstream.cons
|
| 11319 |
[ostringstream.members]: #ostringstream.members
|
| 11320 |
[output.streams]: #output.streams
|
|
|
|
| 11350 |
[string.streams]: #string.streams
|
| 11351 |
[stringbuf]: #stringbuf
|
| 11352 |
[stringbuf.assign]: #stringbuf.assign
|
| 11353 |
[stringbuf.cons]: #stringbuf.cons
|
| 11354 |
[stringbuf.members]: #stringbuf.members
|
| 11355 |
+
[stringbuf.seekoff.newoff]: #stringbuf.seekoff.newoff
|
| 11356 |
+
[stringbuf.seekoff.pos]: #stringbuf.seekoff.pos
|
| 11357 |
[stringbuf.virtuals]: #stringbuf.virtuals
|
| 11358 |
[strings]: strings.md#strings
|
| 11359 |
[stringstream]: #stringstream
|
| 11360 |
[stringstream.assign]: #stringstream.assign
|
| 11361 |
[stringstream.cons]: #stringstream.cons
|
| 11362 |
[stringstream.members]: #stringstream.members
|
| 11363 |
+
[syncstream]: #syncstream
|
| 11364 |
+
[syncstream.osyncstream]: #syncstream.osyncstream
|
| 11365 |
+
[syncstream.osyncstream.cons]: #syncstream.osyncstream.cons
|
| 11366 |
+
[syncstream.osyncstream.members]: #syncstream.osyncstream.members
|
| 11367 |
+
[syncstream.osyncstream.overview]: #syncstream.osyncstream.overview
|
| 11368 |
+
[syncstream.syn]: #syncstream.syn
|
| 11369 |
+
[syncstream.syncbuf]: #syncstream.syncbuf
|
| 11370 |
+
[syncstream.syncbuf.assign]: #syncstream.syncbuf.assign
|
| 11371 |
+
[syncstream.syncbuf.cons]: #syncstream.syncbuf.cons
|
| 11372 |
+
[syncstream.syncbuf.members]: #syncstream.syncbuf.members
|
| 11373 |
+
[syncstream.syncbuf.overview]: #syncstream.syncbuf.overview
|
| 11374 |
+
[syncstream.syncbuf.special]: #syncstream.syncbuf.special
|
| 11375 |
+
[syncstream.syncbuf.virtuals]: #syncstream.syncbuf.virtuals
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11376 |
[temp.deduct]: temp.md#temp.deduct
|
|
|
|
| 11377 |
[wide.stream.objects]: #wide.stream.objects
|
| 11378 |
|
| 11379 |
[^1]: It is the implementation’s responsibility to implement headers so
|
| 11380 |
that including `<iosfwd>` and other headers does not violate the
|
| 11381 |
rules about multiple occurrences of default arguments.
|
| 11382 |
|
| 11383 |
+
[^2]: If it is possible for them to do so, implementations should
|
| 11384 |
+
initialize the objects earlier than required.
|
| 11385 |
|
| 11386 |
+
[^3]: Constructors and destructors for objects with static storage
|
| 11387 |
+
duration can access these objects to read input from `stdin` or
|
| 11388 |
+
write output to `stdout` or `stderr`.
|
| 11389 |
|
| 11390 |
[^4]: Typically `long long`.
|
| 11391 |
|
| 11392 |
[^5]: `streamsize` is used in most places where ISO C would use
|
| 11393 |
+
`size_t`.
|
|
|
|
|
|
|
|
|
|
| 11394 |
|
| 11395 |
[^6]: This implies that operations on a standard iostream object can be
|
| 11396 |
mixed arbitrarily with operations on the corresponding stdio stream.
|
| 11397 |
In practical terms, synchronization usually means that a standard
|
| 11398 |
iostream object and a standard stdio object share a buffer.
|
|
|
|
| 11400 |
[^7]: An implementation is free to implement both the integer array
|
| 11401 |
pointed at by `iarray` and the pointer array pointed at by `parray`
|
| 11402 |
as sparse data structures, possibly with a one-element cache for
|
| 11403 |
each.
|
| 11404 |
|
| 11405 |
+
[^8]: For example, because it cannot allocate space.
|
| 11406 |
|
| 11407 |
+
[^9]: For example, because it cannot allocate space.
|
| 11408 |
|
| 11409 |
[^10]: This suggests an infinite amount of copying, but the
|
| 11410 |
implementation can keep track of the maximum element of the arrays
|
| 11411 |
that is nonzero.
|
| 11412 |
|
|
|
|
| 11442 |
|
| 11443 |
[^18]: This will be possible only in functions that are part of the
|
| 11444 |
library. The semantics of the constructor used in user code is as
|
| 11445 |
specified.
|
| 11446 |
|
| 11447 |
+
[^19]: The `sentry` constructor and destructor can also perform
|
| 11448 |
+
additional implementation-dependent operations.
|
| 11449 |
|
| 11450 |
+
[^20]: This is done without causing an `ios_base::failure` to be thrown.
|
| 11451 |
|
| 11452 |
[^21]: See, for example, the function signature
|
| 11453 |
+
`ws(basic_istream&)`[[istream.manip]].
|
| 11454 |
|
| 11455 |
[^22]: See, for example, the function signature
|
| 11456 |
+
`dec(ios_base&)`[[basefield.manip]].
|
| 11457 |
|
| 11458 |
+
[^23]: This is done without causing an `ios_base::failure` to be thrown.
|
| 11459 |
|
| 11460 |
[^24]: Note that this function is not overloaded on types `signed char`
|
| 11461 |
and `unsigned char`.
|
| 11462 |
|
| 11463 |
[^25]: Note that this function is not overloaded on types `signed char`
|
|
|
|
| 11483 |
function can determine that no synchronization is necessary.
|
| 11484 |
|
| 11485 |
[^32]: The `sentry` constructor and destructor can also perform
|
| 11486 |
additional implementation-dependent operations.
|
| 11487 |
|
| 11488 |
+
[^33]: without causing an `ios_base::failure` to be thrown.
|
| 11489 |
|
| 11490 |
[^34]: See, for example, the function signature
|
| 11491 |
+
`endl(basic_ostream&)`[[ostream.manip]].
|
| 11492 |
|
| 11493 |
[^35]: See, for example, the function signature
|
| 11494 |
+
`dec(ios_base&)`[[basefield.manip]].
|
| 11495 |
|
| 11496 |
+
[^36]: without causing an `ios_base::failure` to be thrown.
|
| 11497 |
|
| 11498 |
[^37]: Note that this function is not overloaded on types `signed char`
|
| 11499 |
and `unsigned char`.
|
| 11500 |
|
| 11501 |
[^38]: Note that this function is not overloaded on types `signed char`
|
|
|
|
| 11510 |
`basic_ostream<charT, traits>` object `cout` (the same as
|
| 11511 |
`cout << noshowbase`).
|
| 11512 |
|
| 11513 |
[^40]: The macro `SEEK_END` is defined, and the function signatures
|
| 11514 |
`fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
|
| 11515 |
+
declared, in `<cstdio>`.
|
| 11516 |
|
| 11517 |
[^41]: POSIX® is a registered trademark of The IEEE. Windows® is a
|
| 11518 |
registered trademark of Microsoft Corporation. This information is
|
| 11519 |
given for the convenience of users of this document and does not
|
| 11520 |
constitute an endorsement by ISO or IEC of these products.
|