- tmp/tmphmnuuow9/{from.md → to.md} +5440 -964
tmp/tmphmnuuow9/{from.md → to.md}
RENAMED
|
@@ -12,22 +12,23 @@ formatting and manipulators, string streams, and file streams, as
|
|
| 12 |
summarized in Table [[tab:iostreams.lib.summary]].
|
| 13 |
|
| 14 |
**Table: Input/output library summary** <a id="tab:iostreams.lib.summary">[tab:iostreams.lib.summary]</a>
|
| 15 |
|
| 16 |
| Subclause | | Header |
|
| 17 |
-
| -------------------------- | --------------------------- | ------------- |
|
| 18 |
| [[iostreams.requirements]] | Requirements | |
|
| 19 |
| [[iostream.forward]] | Forward declarations | `<iosfwd>` |
|
| 20 |
| [[iostream.objects]] | Standard iostream objects | `<iostream>` |
|
| 21 |
| [[iostreams.base]] | Iostreams base classes | `<ios>` |
|
| 22 |
| [[stream.buffers]] | Stream buffers | `<streambuf>` |
|
| 23 |
| [[iostream.format]] | Formatting and manipulators | `<istream>` |
|
| 24 |
| | | `<ostream>` |
|
| 25 |
| | | `<iomanip>` |
|
| 26 |
| [[string.streams]] | String streams | `<sstream>` |
|
| 27 |
| [[file.streams]] | File streams | `<fstream>` |
|
| 28 |
-
|
|
|
|
|
| 29 |
| | | `<cinttypes>` |
|
| 30 |
|
| 31 |
|
| 32 |
Figure [[fig:streampos]] illustrates relationships among various types
|
| 33 |
described in this clause. A line from **A** to **B** indicates that
|
|
@@ -57,30 +58,34 @@ and `traits` behave as described if `traits::pos_type` and
|
|
| 57 |
as noted explicitly below, their behavior when `traits::pos_type` and
|
| 58 |
`traits::off_type` are other types is *implementation-defined*.
|
| 59 |
|
| 60 |
In the classes of Clause [[input.output]], a template parameter with
|
| 61 |
name `charT` represents a member of the set of types containing `char`,
|
| 62 |
-
`wchar_t`, and any other implementation-defined character types that
|
| 63 |
satisfy the requirements for a character on which any of the iostream
|
| 64 |
components can be instantiated.
|
| 65 |
|
| 66 |
### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
|
| 67 |
|
| 68 |
Concurrent access to a stream object ([[string.streams]],
|
| 69 |
[[file.streams]]), stream buffer object ([[stream.buffers]]), or C
|
| 70 |
Library stream ([[c.files]]) by multiple threads may result in a data
|
| 71 |
race ([[intro.multithread]]) unless otherwise specified (
|
| 72 |
-
[[iostream.objects]]).
|
| 73 |
-
|
|
|
|
|
|
|
| 74 |
|
| 75 |
If one thread makes a library call *a* that writes a value to a stream
|
| 76 |
and, as a result, another thread reads this value from the stream
|
| 77 |
through a library call *b* such that this does not result in a data
|
| 78 |
race, then *a*’s write synchronizes with *b*’s read.
|
| 79 |
|
| 80 |
## Forward declarations <a id="iostream.forward">[[iostream.forward]]</a>
|
| 81 |
|
|
|
|
|
|
|
| 82 |
``` cpp
|
| 83 |
namespace std {
|
| 84 |
template<class charT> class char_traits;
|
| 85 |
template<> class char_traits<char>;
|
| 86 |
template<> class char_traits<char16_t>;
|
|
@@ -125,61 +130,63 @@ namespace std {
|
|
| 125 |
template <class charT, class traits = char_traits<charT>>
|
| 126 |
class istreambuf_iterator;
|
| 127 |
template <class charT, class traits = char_traits<charT>>
|
| 128 |
class ostreambuf_iterator;
|
| 129 |
|
| 130 |
-
|
| 131 |
-
|
| 132 |
|
| 133 |
-
|
| 134 |
-
|
| 135 |
-
|
| 136 |
-
|
| 137 |
|
| 138 |
-
|
| 139 |
-
|
| 140 |
-
|
| 141 |
-
|
| 142 |
|
| 143 |
-
|
| 144 |
-
|
| 145 |
-
|
| 146 |
-
|
| 147 |
|
| 148 |
-
|
| 149 |
-
|
| 150 |
-
|
| 151 |
-
|
| 152 |
|
| 153 |
-
|
| 154 |
-
|
| 155 |
-
|
| 156 |
-
|
| 157 |
|
| 158 |
-
|
| 159 |
-
|
| 160 |
-
|
| 161 |
-
|
| 162 |
|
| 163 |
template <class state> class fpos;
|
| 164 |
-
|
| 165 |
-
|
| 166 |
}
|
| 167 |
```
|
| 168 |
|
| 169 |
Default template arguments are described as appearing both in `<iosfwd>`
|
| 170 |
and in the synopsis of other headers but it is well-formed to include
|
| 171 |
both `<iosfwd>` and one or more of the other headers.[^1]
|
| 172 |
|
|
|
|
|
|
|
| 173 |
The class template specialization `basic_ios<charT, traits>` serves as a
|
| 174 |
virtual base class for the class templates `basic_istream`,
|
| 175 |
`basic_ostream`, and class templates derived from them. `basic_iostream`
|
| 176 |
is a class template derived from both `basic_istream<charT, traits>` and
|
| 177 |
`basic_ostream<charT, traits>`.
|
| 178 |
|
| 179 |
-
The class template specialization `basic_streambuf<charT,traits>`
|
| 180 |
-
as a base class for class templates `basic_stringbuf` and
|
| 181 |
`basic_filebuf`.
|
| 182 |
|
| 183 |
The class template specialization `basic_istream<charT, traits>` serves
|
| 184 |
as a base class for class templates `basic_istringstream` and
|
| 185 |
`basic_ifstream`.
|
|
@@ -190,44 +197,47 @@ as a base class for class templates `basic_ostringstream` and
|
|
| 190 |
|
| 191 |
The class template specialization `basic_iostream<charT, traits>` serves
|
| 192 |
as a base class for class templates `basic_stringstream` and
|
| 193 |
`basic_fstream`.
|
| 194 |
|
| 195 |
-
Other
|
| 196 |
-
`char` or `wchar_t` types.
|
| 197 |
|
| 198 |
Specializations of the class template `fpos` are used for specifying
|
| 199 |
file position information.
|
| 200 |
|
| 201 |
The types `streampos` and `wstreampos` are used for positioning streams
|
| 202 |
specialized on `char` and `wchar_t` respectively.
|
| 203 |
|
|
|
|
|
|
|
| 204 |
This synopsis suggests a circularity between `streampos` and
|
| 205 |
`char_traits<char>`. An implementation can avoid this circularity by
|
| 206 |
substituting equivalent types. One way to do this might be
|
| 207 |
|
| 208 |
``` cpp
|
| 209 |
template<class stateT> class fpos { ... }; // depends on nothing
|
| 210 |
-
|
| 211 |
|
| 212 |
-
|
| 213 |
|
| 214 |
template<> struct char_traits<char> {
|
| 215 |
-
|
| 216 |
-
pos_type;
|
| 217 |
}
|
| 218 |
```
|
| 219 |
|
|
|
|
|
|
|
| 220 |
## Standard iostream objects <a id="iostream.objects">[[iostream.objects]]</a>
|
| 221 |
|
| 222 |
-
###
|
| 223 |
|
| 224 |
``` cpp
|
| 225 |
-
#include <ios>
|
| 226 |
-
#include <streambuf>
|
| 227 |
-
#include <istream>
|
| 228 |
-
#include <ostream>
|
| 229 |
|
| 230 |
namespace std {
|
| 231 |
extern istream cin;
|
| 232 |
extern ostream cout;
|
| 233 |
extern ostream cerr;
|
|
@@ -238,129 +248,136 @@ namespace std {
|
|
| 238 |
extern wostream wcerr;
|
| 239 |
extern wostream wclog;
|
| 240 |
}
|
| 241 |
```
|
| 242 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 243 |
The header `<iostream>` declares objects that associate objects with the
|
| 244 |
standard C streams provided for by the functions declared in
|
| 245 |
`<cstdio>` ([[c.files]]), and includes all the headers necessary to use
|
| 246 |
these objects.
|
| 247 |
|
| 248 |
The objects are constructed and the associations are established at some
|
| 249 |
time prior to or during the first time an object of class
|
| 250 |
`ios_base::Init` is constructed, and in any case before the body of
|
| 251 |
-
`main` begins execution.[^2] The objects are not
|
| 252 |
-
program execution.[^3] The results of including
|
| 253 |
-
translation unit shall be as if `<iostream>` defined
|
| 254 |
-
`ios_base::Init` with static storage duration.
|
| 255 |
-
program shall behave as if there were at least one instance of
|
| 256 |
-
`ios_base::Init` with static storage duration.
|
| 257 |
|
| 258 |
Mixing operations on corresponding wide- and narrow-character streams
|
| 259 |
follows the same semantics as mixing such operations on `FILE`s, as
|
| 260 |
-
specified in
|
| 261 |
|
| 262 |
Concurrent access to a synchronized ([[ios.members.static]]) standard
|
| 263 |
iostream object’s formatted and unformatted input ([[istream]]) and
|
| 264 |
output ([[ostream]]) functions or a standard C stream by multiple
|
| 265 |
-
threads shall not result in a data race ([[intro.multithread]]).
|
| 266 |
-
|
| 267 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 268 |
|
| 269 |
### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
|
| 270 |
|
| 271 |
``` cpp
|
| 272 |
istream cin;
|
| 273 |
```
|
| 274 |
|
| 275 |
The object `cin` controls input from a stream buffer associated with the
|
| 276 |
-
object `stdin`, declared in `<cstdio>`.
|
| 277 |
|
| 278 |
After the object `cin` is initialized, `cin.tie()` returns `&cout`. Its
|
| 279 |
state is otherwise the same as required for
|
| 280 |
`basic_ios<char>::init` ([[basic.ios.cons]]).
|
| 281 |
|
| 282 |
``` cpp
|
| 283 |
ostream cout;
|
| 284 |
```
|
| 285 |
|
| 286 |
The object `cout` controls output to a stream buffer associated with the
|
| 287 |
-
object `stdout`, declared in `<cstdio>` ([[
|
| 288 |
|
| 289 |
``` cpp
|
| 290 |
ostream cerr;
|
| 291 |
```
|
| 292 |
|
| 293 |
The object `cerr` controls output to a stream buffer associated with the
|
| 294 |
-
object `stderr`, declared in `<cstdio>` ([[
|
| 295 |
|
| 296 |
After the object `cerr` is initialized, `cerr.flags() & unitbuf` is
|
| 297 |
nonzero and `cerr.tie()` returns `&cout`. Its state is otherwise the
|
| 298 |
same as required for `basic_ios<char>::init` ([[basic.ios.cons]]).
|
| 299 |
|
| 300 |
``` cpp
|
| 301 |
ostream clog;
|
| 302 |
```
|
| 303 |
|
| 304 |
The object `clog` controls output to a stream buffer associated with the
|
| 305 |
-
object `stderr`, declared in `<cstdio>` ([[
|
| 306 |
|
| 307 |
### Wide stream objects <a id="wide.stream.objects">[[wide.stream.objects]]</a>
|
| 308 |
|
| 309 |
``` cpp
|
| 310 |
wistream wcin;
|
| 311 |
```
|
| 312 |
|
| 313 |
The object `wcin` controls input from a stream buffer associated with
|
| 314 |
-
the object `stdin`, declared in `<cstdio>`.
|
| 315 |
|
| 316 |
After the object `wcin` is initialized, `wcin.tie()` returns `&wcout`.
|
| 317 |
Its state is otherwise the same as required for
|
| 318 |
`basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
|
| 319 |
|
| 320 |
``` cpp
|
| 321 |
wostream wcout;
|
| 322 |
```
|
| 323 |
|
| 324 |
The object `wcout` controls output to a stream buffer associated with
|
| 325 |
-
the object `stdout`, declared in `<cstdio>` ([[
|
| 326 |
|
| 327 |
``` cpp
|
| 328 |
wostream wcerr;
|
| 329 |
```
|
| 330 |
|
| 331 |
The object `wcerr` controls output to a stream buffer associated with
|
| 332 |
-
the object `stderr`, declared in `<cstdio>` ([[
|
| 333 |
|
| 334 |
After the object `wcerr` is initialized, `wcerr.flags() & unitbuf` is
|
| 335 |
nonzero and `wcerr.tie()` returns `&wcout`. Its state is otherwise the
|
| 336 |
same as required for `basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
|
| 337 |
|
| 338 |
``` cpp
|
| 339 |
wostream wclog;
|
| 340 |
```
|
| 341 |
|
| 342 |
The object `wclog` controls output to a stream buffer associated with
|
| 343 |
-
the object `stderr`, declared in `<cstdio>` ([[
|
| 344 |
|
| 345 |
## Iostreams base classes <a id="iostreams.base">[[iostreams.base]]</a>
|
| 346 |
|
| 347 |
-
###
|
| 348 |
|
| 349 |
``` cpp
|
| 350 |
-
#include <iosfwd>
|
| 351 |
|
| 352 |
namespace std {
|
| 353 |
-
|
| 354 |
-
|
| 355 |
template <class stateT> class fpos;
|
| 356 |
|
| 357 |
class ios_base;
|
| 358 |
template <class charT, class traits = char_traits<charT>>
|
| 359 |
class basic_ios;
|
| 360 |
|
| 361 |
-
// [std.ios.manip], manipulators
|
| 362 |
ios_base& boolalpha (ios_base& str);
|
| 363 |
ios_base& noboolalpha(ios_base& str);
|
| 364 |
|
| 365 |
ios_base& showbase (ios_base& str);
|
| 366 |
ios_base& noshowbase (ios_base& str);
|
|
@@ -378,27 +395,27 @@ namespace std {
|
|
| 378 |
ios_base& nouppercase(ios_base& str);
|
| 379 |
|
| 380 |
ios_base& unitbuf (ios_base& str);
|
| 381 |
ios_base& nounitbuf (ios_base& str);
|
| 382 |
|
| 383 |
-
// [adjustfield.manip] adjustfield
|
| 384 |
ios_base& internal (ios_base& str);
|
| 385 |
ios_base& left (ios_base& str);
|
| 386 |
ios_base& right (ios_base& str);
|
| 387 |
|
| 388 |
-
// [basefield.manip] basefield
|
| 389 |
ios_base& dec (ios_base& str);
|
| 390 |
ios_base& hex (ios_base& str);
|
| 391 |
ios_base& oct (ios_base& str);
|
| 392 |
|
| 393 |
-
// [floatfield.manip] floatfield
|
| 394 |
ios_base& fixed (ios_base& str);
|
| 395 |
ios_base& scientific (ios_base& str);
|
| 396 |
ios_base& hexfloat (ios_base& str);
|
| 397 |
ios_base& defaultfloat(ios_base& str);
|
| 398 |
|
| 399 |
-
// [error.reporting] error reporting
|
| 400 |
enum class io_errc {
|
| 401 |
stream = 1
|
| 402 |
};
|
| 403 |
|
| 404 |
template <> struct is_error_code_enum<io_errc> : public true_type { };
|
|
@@ -409,19 +426,19 @@ namespace std {
|
|
| 409 |
```
|
| 410 |
|
| 411 |
### Types <a id="stream.types">[[stream.types]]</a>
|
| 412 |
|
| 413 |
``` cpp
|
| 414 |
-
|
| 415 |
```
|
| 416 |
|
| 417 |
The type `streamoff` is a synonym for one of the signed basic integral
|
| 418 |
types of sufficient size to represent the maximum possible file size for
|
| 419 |
the operating system.[^4]
|
| 420 |
|
| 421 |
``` cpp
|
| 422 |
-
|
| 423 |
```
|
| 424 |
|
| 425 |
The type `streamsize` is a synonym for one of the signed basic integral
|
| 426 |
types. It is used to represent the number of characters transferred in
|
| 427 |
an I/O operation, or the size of I/O buffers.[^5]
|
|
@@ -430,14 +447,14 @@ an I/O operation, or the size of I/O buffers.[^5]
|
|
| 430 |
|
| 431 |
``` cpp
|
| 432 |
namespace std {
|
| 433 |
class ios_base {
|
| 434 |
public:
|
| 435 |
-
class failure;
|
| 436 |
|
| 437 |
-
// [ios::fmtflags] fmtflags
|
| 438 |
-
|
| 439 |
static constexpr fmtflags boolalpha = unspecified;
|
| 440 |
static constexpr fmtflags dec = unspecified;
|
| 441 |
static constexpr fmtflags fixed = unspecified;
|
| 442 |
static constexpr fmtflags hex = unspecified;
|
| 443 |
static constexpr fmtflags internal = unspecified;
|
|
@@ -453,35 +470,35 @@ namespace std {
|
|
| 453 |
static constexpr fmtflags uppercase = unspecified;
|
| 454 |
static constexpr fmtflags adjustfield = see below;
|
| 455 |
static constexpr fmtflags basefield = see below;
|
| 456 |
static constexpr fmtflags floatfield = see below;
|
| 457 |
|
| 458 |
-
// [ios::iostate] iostate
|
| 459 |
-
|
| 460 |
static constexpr iostate badbit = unspecified;
|
| 461 |
static constexpr iostate eofbit = unspecified;
|
| 462 |
static constexpr iostate failbit = unspecified;
|
| 463 |
static constexpr iostate goodbit = see below;
|
| 464 |
|
| 465 |
-
// [ios::openmode] openmode
|
| 466 |
-
|
| 467 |
static constexpr openmode app = unspecified;
|
| 468 |
static constexpr openmode ate = unspecified;
|
| 469 |
static constexpr openmode binary = unspecified;
|
| 470 |
static constexpr openmode in = unspecified;
|
| 471 |
static constexpr openmode out = unspecified;
|
| 472 |
static constexpr openmode trunc = unspecified;
|
| 473 |
|
| 474 |
-
// [ios::seekdir] seekdir
|
| 475 |
-
|
| 476 |
static constexpr seekdir beg = unspecified;
|
| 477 |
static constexpr seekdir cur = unspecified;
|
| 478 |
static constexpr seekdir end = unspecified;
|
| 479 |
|
| 480 |
class Init;
|
| 481 |
|
| 482 |
-
// [fmtflags.state] fmtflags state
|
| 483 |
fmtflags flags() const;
|
| 484 |
fmtflags flags(fmtflags fmtfl);
|
| 485 |
fmtflags setf(fmtflags fmtfl);
|
| 486 |
fmtflags setf(fmtflags fmtfl, fmtflags mask);
|
| 487 |
void unsetf(fmtflags mask);
|
|
@@ -489,25 +506,25 @@ namespace std {
|
|
| 489 |
streamsize precision() const;
|
| 490 |
streamsize precision(streamsize prec);
|
| 491 |
streamsize width() const;
|
| 492 |
streamsize width(streamsize wide);
|
| 493 |
|
| 494 |
-
// [ios.base.locales] locales
|
| 495 |
locale imbue(const locale& loc);
|
| 496 |
locale getloc() const;
|
| 497 |
|
| 498 |
-
// [ios.base.storage] storage
|
| 499 |
static int xalloc();
|
| 500 |
long& iword(int index);
|
| 501 |
void*& pword(int index);
|
| 502 |
|
| 503 |
-
// destructor
|
| 504 |
virtual ~ios_base();
|
| 505 |
|
| 506 |
-
// [ios.base.callback] callbacks;
|
| 507 |
enum event { erase_event, imbue_event, copyfmt_event };
|
| 508 |
-
|
| 509 |
void register_callback(event_callback fn, int index);
|
| 510 |
|
| 511 |
ios_base(const ios_base&) = delete;
|
| 512 |
ios_base& operator=(const ios_base&) = delete;
|
| 513 |
|
|
@@ -526,11 +543,12 @@ namespace std {
|
|
| 526 |
|
| 527 |
`ios_base`
|
| 528 |
|
| 529 |
defines several member types:
|
| 530 |
|
| 531 |
-
- a
|
|
|
|
| 532 |
- a class `Init`;
|
| 533 |
- three bitmask types, `fmtflags`, `iostate`, and `openmode`;
|
| 534 |
- an enumerated type, `seekdir`.
|
| 535 |
|
| 536 |
It maintains several kinds of data:
|
|
@@ -539,20 +557,24 @@ It maintains several kinds of data:
|
|
| 539 |
- control information that influences how to interpret (format) input
|
| 540 |
sequences and how to generate (format) output sequences;
|
| 541 |
- additional information that is stored by the program for its private
|
| 542 |
use.
|
| 543 |
|
|
|
|
|
|
|
| 544 |
For the sake of exposition, the maintained data is presented here as:
|
| 545 |
|
| 546 |
- `static int index`, specifies the next available unique index for the
|
| 547 |
integer or pointer arrays maintained for the private use of the
|
| 548 |
program, initialized to an unspecified value;
|
| 549 |
- `long* iarray`, points to the first element of an arbitrary-length
|
| 550 |
`long` array maintained for the private use of the program;
|
| 551 |
- `void** parray`, points to the first element of an arbitrary-length
|
| 552 |
pointer array maintained for the private use of the program.
|
| 553 |
|
|
|
|
|
|
|
| 554 |
#### Types <a id="ios.types">[[ios.types]]</a>
|
| 555 |
|
| 556 |
##### Class `ios_base::failure` <a id="ios::failure">[[ios::failure]]</a>
|
| 557 |
|
| 558 |
``` cpp
|
|
@@ -563,22 +585,32 @@ namespace std {
|
|
| 563 |
explicit failure(const char* msg, const error_code& ec = io_errc::stream);
|
| 564 |
};
|
| 565 |
}
|
| 566 |
```
|
| 567 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 568 |
The class `failure` defines the base class for the types of all objects
|
| 569 |
thrown as exceptions, by functions in the iostreams library, to report
|
| 570 |
errors detected during stream buffer operations.
|
| 571 |
|
| 572 |
When throwing `ios_base::failure` exceptions, implementations should
|
| 573 |
provide values of `ec` that identify the specific reason for the
|
| 574 |
-
failure.
|
|
|
|
|
|
|
| 575 |
reported as `system_category()` errors with an error value of the error
|
| 576 |
number reported by the operating system. Errors arising from within the
|
| 577 |
stream library would typically be reported as
|
| 578 |
`error_code(io_errc::stream,
|
| 579 |
-
iostream_category())`.
|
| 580 |
|
| 581 |
``` cpp
|
| 582 |
explicit failure(const string& msg, const error_code& ec = io_errc::stream);
|
| 583 |
```
|
| 584 |
|
|
@@ -593,11 +625,11 @@ explicit failure(const char* msg, const error_code& ec = io_errc::stream);
|
|
| 593 |
base class with `msg` and `ec`.
|
| 594 |
|
| 595 |
##### Type `ios_base::fmtflags` <a id="ios::fmtflags">[[ios::fmtflags]]</a>
|
| 596 |
|
| 597 |
``` cpp
|
| 598 |
-
|
| 599 |
```
|
| 600 |
|
| 601 |
The type `fmtflags` is a bitmask type ([[bitmask.types]]). Setting its
|
| 602 |
elements has the effects indicated in
|
| 603 |
Table [[tab:iostreams.fmtflags.effects]].
|
|
@@ -636,11 +668,11 @@ Table [[tab:iostreams.fmtflags.constants]].
|
|
| 636 |
|
| 637 |
|
| 638 |
##### Type `ios_base::iostate` <a id="ios::iostate">[[ios::iostate]]</a>
|
| 639 |
|
| 640 |
``` cpp
|
| 641 |
-
|
| 642 |
```
|
| 643 |
|
| 644 |
The type `iostate` is a bitmask type ([[bitmask.types]]) that contains
|
| 645 |
the elements indicated in Table [[tab:iostreams.iostate.effects]].
|
| 646 |
|
|
@@ -658,11 +690,11 @@ Type `iostate` also defines the constant:
|
|
| 658 |
- `goodbit`, the value zero.
|
| 659 |
|
| 660 |
##### Type `ios_base::openmode` <a id="ios::openmode">[[ios::openmode]]</a>
|
| 661 |
|
| 662 |
``` cpp
|
| 663 |
-
|
| 664 |
```
|
| 665 |
|
| 666 |
The type `openmode` is a bitmask type ([[bitmask.types]]). It contains
|
| 667 |
the elements indicated in Table [[tab:iostreams.openmode.effects]].
|
| 668 |
|
|
@@ -679,11 +711,11 @@ the elements indicated in Table [[tab:iostreams.openmode.effects]].
|
|
| 679 |
|
| 680 |
|
| 681 |
##### Type `ios_base::seekdir` <a id="ios::seekdir">[[ios::seekdir]]</a>
|
| 682 |
|
| 683 |
``` cpp
|
| 684 |
-
|
| 685 |
```
|
| 686 |
|
| 687 |
The type `seekdir` is an enumerated type ([[enumerated.types]]) that
|
| 688 |
contains the elements indicated in
|
| 689 |
Table [[tab:iostreams.seekdir.effects]].
|
|
@@ -713,11 +745,11 @@ namespace std {
|
|
| 713 |
|
| 714 |
The class `Init` describes an object whose construction ensures the
|
| 715 |
construction of the eight objects declared in `<iostream>` (
|
| 716 |
[[iostream.objects]]) that associate file stream buffers with the
|
| 717 |
standard C streams provided for by the functions declared in
|
| 718 |
-
`<cstdio>` ([[
|
| 719 |
|
| 720 |
For the sake of exposition, the maintained data is presented here as:
|
| 721 |
|
| 722 |
- `static int init_cnt`, counts the number of constructor and destructor
|
| 723 |
calls for class `Init`, initialized to zero.
|
|
@@ -750,11 +782,11 @@ fmtflags flags() const;
|
|
| 750 |
|
| 751 |
``` cpp
|
| 752 |
fmtflags flags(fmtflags fmtfl);
|
| 753 |
```
|
| 754 |
|
| 755 |
-
`fmtfl == flags()`.
|
| 756 |
|
| 757 |
*Returns:* The previous value of `flags()`.
|
| 758 |
|
| 759 |
``` cpp
|
| 760 |
fmtflags setf(fmtflags fmtfl);
|
|
@@ -786,11 +818,11 @@ streamsize precision() const;
|
|
| 786 |
|
| 787 |
``` cpp
|
| 788 |
streamsize precision(streamsize prec);
|
| 789 |
```
|
| 790 |
|
| 791 |
-
`prec == precision()`.
|
| 792 |
|
| 793 |
*Returns:* The previous value of `precision()`.
|
| 794 |
|
| 795 |
``` cpp
|
| 796 |
streamsize width() const;
|
|
@@ -801,11 +833,11 @@ certain output conversions.
|
|
| 801 |
|
| 802 |
``` cpp
|
| 803 |
streamsize width(streamsize wide);
|
| 804 |
```
|
| 805 |
|
| 806 |
-
`wide == width()`.
|
| 807 |
|
| 808 |
*Returns:* The previous value of `width()`.
|
| 809 |
|
| 810 |
#### `ios_base` functions <a id="ios.base.locales">[[ios.base.locales]]</a>
|
| 811 |
|
|
@@ -819,11 +851,11 @@ locale imbue(const locale& loc);
|
|
| 819 |
`ios_base::getloc()` from within `fn` returns the new locale value
|
| 820 |
`loc`.
|
| 821 |
|
| 822 |
*Returns:* The previous value of `getloc()`.
|
| 823 |
|
| 824 |
-
`loc == getloc()`.
|
| 825 |
|
| 826 |
``` cpp
|
| 827 |
locale getloc() const;
|
| 828 |
```
|
| 829 |
|
|
@@ -842,11 +874,11 @@ bool sync_with_stdio(bool sync = true);
|
|
| 842 |
objects ([[iostream.objects]]) was synchronized and otherwise returns
|
| 843 |
`false`. The first time it is called, the function returns `true`.
|
| 844 |
|
| 845 |
*Effects:* If any input or output operation has occurred using the
|
| 846 |
standard streams prior to the call, the effect is
|
| 847 |
-
*implementation-defined*. Otherwise, called with a false argument, it
|
| 848 |
allows the standard streams to operate independently of the standard C
|
| 849 |
streams.
|
| 850 |
|
| 851 |
When a standard iostream object `str` is *synchronized* with a standard
|
| 852 |
stdio stream `f`, the effect of inserting a character `c` by
|
|
@@ -910,11 +942,11 @@ of unspecified size and stores a pointer to its first element in
|
|
| 910 |
necessary to include the element `iarray[idx]`. Each newly allocated
|
| 911 |
element of the array is initialized to zero. The reference returned is
|
| 912 |
invalid after any other operations on the object.[^7] However, the value
|
| 913 |
of the storage referred to is retained, so that until the next call to
|
| 914 |
`copyfmt`, calling `iword` with the same index yields another reference
|
| 915 |
-
to the same value. If the function fails[^8] and `*this` is a base
|
| 916 |
subobject of a `basic_ios<>` object or subobject, the effect is
|
| 917 |
equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
|
| 918 |
object (which may throw `failure`).
|
| 919 |
|
| 920 |
*Returns:* On success `iarray[idx]`. On failure, a valid `long&`
|
|
@@ -931,12 +963,12 @@ as necessary to include the element `parray[idx]`. Each newly allocated
|
|
| 931 |
element of the array is initialized to a null pointer. The reference
|
| 932 |
returned is invalid after any other operations on the object. However,
|
| 933 |
the value of the storage referred to is retained, so that until the next
|
| 934 |
call to `copyfmt`, calling `pword` with the same index yields another
|
| 935 |
reference to the same value. If the function fails[^9] and `*this` is a
|
| 936 |
-
base subobject of a `basic_ios<>` object or subobject, the effect
|
| 937 |
-
equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
|
| 938 |
object (which may throw `failure`).
|
| 939 |
|
| 940 |
*Returns:* On success `parray[idx]`. On failure a valid `void*&`
|
| 941 |
initialized to 0.
|
| 942 |
|
|
@@ -985,11 +1017,11 @@ member function called from within `fn` has well defined results.
|
|
| 985 |
|
| 986 |
``` cpp
|
| 987 |
namespace std {
|
| 988 |
template <class stateT> class fpos {
|
| 989 |
public:
|
| 990 |
-
// [fpos.members]
|
| 991 |
stateT state() const;
|
| 992 |
void state(stateT);
|
| 993 |
private;
|
| 994 |
stateT st; // exposition only
|
| 995 |
};
|
|
@@ -1000,11 +1032,11 @@ namespace std {
|
|
| 1000 |
|
| 1001 |
``` cpp
|
| 1002 |
void state(stateT s);
|
| 1003 |
```
|
| 1004 |
|
| 1005 |
-
*Effects:*
|
| 1006 |
|
| 1007 |
``` cpp
|
| 1008 |
stateT state() const;
|
| 1009 |
```
|
| 1010 |
|
|
@@ -1020,14 +1052,15 @@ are permitted. In that table,
|
|
| 1020 |
- `O` refers to type `streamoff`,
|
| 1021 |
- `o` refers to a value of type `streamoff`,
|
| 1022 |
- `sz` refers to a value of type `streamsize` and
|
| 1023 |
- `i` refers to a value of type `int`.
|
| 1024 |
|
| 1025 |
-
Every implementation is required to supply overloaded
|
| 1026 |
-
`fpos` objects to satisfy the requirements of
|
| 1027 |
-
is unspecified whether these operators are
|
| 1028 |
-
operators, or provided in some other
|
|
|
|
| 1029 |
|
| 1030 |
Stream operations that return a value of type `traits::pos_type` return
|
| 1031 |
`P(O(-1))` as an invalid value to signal an error. If this value is used
|
| 1032 |
as an argument to any `istream`, `ostream`, or `streambuf` member that
|
| 1033 |
accepts a value of type `traits::pos_type` then the behavior of that
|
|
@@ -1040,18 +1073,17 @@ function is undefined.
|
|
| 1040 |
``` cpp
|
| 1041 |
namespace std {
|
| 1042 |
template <class charT, class traits = char_traits<charT>>
|
| 1043 |
class basic_ios : public ios_base {
|
| 1044 |
public:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1045 |
|
| 1046 |
-
//
|
| 1047 |
-
typedef charT char_type;
|
| 1048 |
-
typedef typename traits::int_type int_type;
|
| 1049 |
-
typedef typename traits::pos_type pos_type;
|
| 1050 |
-
typedef typename traits::off_type off_type;
|
| 1051 |
-
typedef traits traits_type;
|
| 1052 |
-
|
| 1053 |
explicit operator bool() const;
|
| 1054 |
bool operator!() const;
|
| 1055 |
iostate rdstate() const;
|
| 1056 |
void clear(iostate state = goodbit);
|
| 1057 |
void setstate(iostate state);
|
|
@@ -1061,15 +1093,15 @@ namespace std {
|
|
| 1061 |
bool bad() const;
|
| 1062 |
|
| 1063 |
iostate exceptions() const;
|
| 1064 |
void exceptions(iostate except);
|
| 1065 |
|
| 1066 |
-
// [basic.ios.cons]
|
| 1067 |
explicit basic_ios(basic_streambuf<charT, traits>* sb);
|
| 1068 |
virtual ~basic_ios();
|
| 1069 |
|
| 1070 |
-
// [basic.ios.members]
|
| 1071 |
basic_ostream<charT, traits>* tie() const;
|
| 1072 |
basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
|
| 1073 |
|
| 1074 |
basic_streambuf<charT, traits>* rdbuf() const;
|
| 1075 |
basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
|
|
@@ -1140,11 +1172,11 @@ Table [[tab:iostreams.basicios.init.effects]].
|
|
| 1140 |
| `rdstate()` | `goodbit` if `sb` is not a null pointer, otherwise `badbit`. |
|
| 1141 |
| `exceptions()` | `goodbit` |
|
| 1142 |
| `flags()` | `skipws | dec` |
|
| 1143 |
| `width()` | `0` |
|
| 1144 |
| `precision()` | `6` |
|
| 1145 |
-
| `fill()` | `widen(' ')
|
| 1146 |
| `getloc()` | a copy of the value returned by `locale()` |
|
| 1147 |
| `iarray` | a null pointer |
|
| 1148 |
| `parray` | a null pointer |
|
| 1149 |
|
| 1150 |
|
|
@@ -1163,11 +1195,11 @@ basic_ostream<charT,traits>* tie(basic_ostream<charT,traits>* tiestr);
|
|
| 1163 |
|
| 1164 |
*Requires:* If `tiestr` is not null, `tiestr` must not be reachable by
|
| 1165 |
traversing the linked list of tied stream objects starting from
|
| 1166 |
`tiestr->tie()`.
|
| 1167 |
|
| 1168 |
-
`tiestr == tie()`.
|
| 1169 |
|
| 1170 |
*Returns:* The previous value of `tie()`.
|
| 1171 |
|
| 1172 |
``` cpp
|
| 1173 |
basic_streambuf<charT, traits>* rdbuf() const;
|
|
@@ -1177,11 +1209,11 @@ basic_streambuf<charT,traits>* rdbuf() const;
|
|
| 1177 |
|
| 1178 |
``` cpp
|
| 1179 |
basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
|
| 1180 |
```
|
| 1181 |
|
| 1182 |
-
`sb == rdbuf()`.
|
| 1183 |
|
| 1184 |
*Effects:* Calls `clear()`.
|
| 1185 |
|
| 1186 |
*Returns:* The previous value of `rdbuf()`.
|
| 1187 |
|
|
@@ -1215,11 +1247,11 @@ specified field width.
|
|
| 1215 |
|
| 1216 |
``` cpp
|
| 1217 |
char_type fill(char_type fillch);
|
| 1218 |
```
|
| 1219 |
|
| 1220 |
-
`traits::eq(fillch, fill())`
|
| 1221 |
|
| 1222 |
*Returns:* The previous value of `fill()`.
|
| 1223 |
|
| 1224 |
``` cpp
|
| 1225 |
basic_ios& copyfmt(const basic_ios& rhs);
|
|
@@ -1240,15 +1272,15 @@ follows:
|
|
| 1240 |
stored outside the object `rhs` and those objects are destroyed
|
| 1241 |
when `rhs` is destroyed, the newly stored pointer values are
|
| 1242 |
altered to point at newly constructed copies of the objects;
|
| 1243 |
3. calls each callback pair that was copied from `rhs` as
|
| 1244 |
`(*fn)(copyfmt_event, *this, index)`;
|
| 1245 |
-
4. calls `exceptions(rhs.
|
| 1246 |
|
| 1247 |
-
*Note
|
| 1248 |
`pword` value to be zeroed, or to have its referent deep copied or
|
| 1249 |
-
reference counted, or to have other special action taken.
|
| 1250 |
|
| 1251 |
*Postconditions:* The postconditions of this function are indicated in
|
| 1252 |
Table [[tab:iostreams.copyfmt.effects]].
|
| 1253 |
|
| 1254 |
**Table: `basic_ios::copyfmt()` effects** <a id="tab:iostreams.copyfmt.effects">[tab:iostreams.copyfmt.effects]</a>
|
|
@@ -1323,16 +1355,16 @@ iostate rdstate() const;
|
|
| 1323 |
|
| 1324 |
``` cpp
|
| 1325 |
void clear(iostate state = goodbit);
|
| 1326 |
```
|
| 1327 |
|
| 1328 |
-
If `rdbuf()!=0` then `state == rdstate()`; otherwise
|
| 1329 |
`rdstate() == (state | ios_base::badbit)`.
|
| 1330 |
|
| 1331 |
*Effects:* If
|
| 1332 |
`((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
|
| 1333 |
-
Otherwise, the function throws an object
|
| 1334 |
`basic_ios::failure` ([[ios::failure]]), constructed with
|
| 1335 |
*implementation-defined* argument values.
|
| 1336 |
|
| 1337 |
``` cpp
|
| 1338 |
void setstate(iostate state);
|
|
@@ -1374,11 +1406,11 @@ exceptions to be thrown.
|
|
| 1374 |
|
| 1375 |
``` cpp
|
| 1376 |
void exceptions(iostate except);
|
| 1377 |
```
|
| 1378 |
|
| 1379 |
-
`except == exceptions()`.
|
| 1380 |
|
| 1381 |
*Effects:* Calls `clear(rdstate())`.
|
| 1382 |
|
| 1383 |
### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
|
| 1384 |
|
|
@@ -1573,14 +1605,14 @@ ios_base& hexfloat(ios_base& str);
|
|
| 1573 |
*Effects:* Calls
|
| 1574 |
`str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
|
| 1575 |
|
| 1576 |
*Returns:* `str`.
|
| 1577 |
|
| 1578 |
-
The more obvious use of `ios_base::hex` to specify
|
| 1579 |
-
floating-point format would change the meaning of existing
|
| 1580 |
-
programs. C++
|
| 1581 |
-
`scientific`.
|
| 1582 |
|
| 1583 |
``` cpp
|
| 1584 |
ios_base& defaultfloat(ios_base& str);
|
| 1585 |
```
|
| 1586 |
|
|
@@ -1614,18 +1646,18 @@ functions shall behave as specified for the class `error_category`. The
|
|
| 1614 |
object’s `name` virtual function shall return a pointer to the string
|
| 1615 |
`"iostream"`.
|
| 1616 |
|
| 1617 |
## Stream buffers <a id="stream.buffers">[[stream.buffers]]</a>
|
| 1618 |
|
| 1619 |
-
###
|
| 1620 |
|
| 1621 |
``` cpp
|
| 1622 |
namespace std {
|
| 1623 |
template <class charT, class traits = char_traits<charT>>
|
| 1624 |
class basic_streambuf;
|
| 1625 |
-
|
| 1626 |
-
|
| 1627 |
}
|
| 1628 |
```
|
| 1629 |
|
| 1630 |
The header `<streambuf>` defines types that control input from and
|
| 1631 |
output to *character* sequences.
|
|
@@ -1679,123 +1711,121 @@ above:
|
|
| 1679 |
- If `xnext` is not a null pointer and `xnext < xend` for an input
|
| 1680 |
sequence, then a *read position* is available. In this case, `*xnext`
|
| 1681 |
shall have a defined value and is the next element to read (to get, or
|
| 1682 |
to obtain a character value, from the sequence).
|
| 1683 |
|
| 1684 |
-
### Class template `basic_streambuf
|
| 1685 |
|
| 1686 |
``` cpp
|
| 1687 |
namespace std {
|
| 1688 |
template <class charT, class traits = char_traits<charT>>
|
| 1689 |
class basic_streambuf {
|
| 1690 |
public:
|
| 1691 |
-
|
| 1692 |
-
|
| 1693 |
-
|
| 1694 |
-
|
| 1695 |
-
|
| 1696 |
-
typedef typename traits::off_type off_type;
|
| 1697 |
-
typedef traits traits_type;
|
| 1698 |
|
| 1699 |
virtual ~basic_streambuf();
|
| 1700 |
|
| 1701 |
-
// [streambuf.locales] locales
|
| 1702 |
locale pubimbue(const locale& loc);
|
| 1703 |
locale getloc() const;
|
| 1704 |
|
| 1705 |
-
// [streambuf.buffer] buffer and positioning
|
| 1706 |
-
basic_streambuf
|
| 1707 |
-
pubsetbuf(char_type* s, streamsize n);
|
| 1708 |
pos_type pubseekoff(off_type off, ios_base::seekdir way,
|
| 1709 |
-
|
| 1710 |
-
|
| 1711 |
pos_type pubseekpos(pos_type sp,
|
| 1712 |
-
|
| 1713 |
-
|
| 1714 |
int pubsync();
|
| 1715 |
|
| 1716 |
-
// Get and put areas
|
| 1717 |
-
// [streambuf.pub.get]
|
| 1718 |
streamsize in_avail();
|
| 1719 |
int_type snextc();
|
| 1720 |
int_type sbumpc();
|
| 1721 |
int_type sgetc();
|
| 1722 |
streamsize sgetn(char_type* s, streamsize n);
|
| 1723 |
|
| 1724 |
-
// [streambuf.pub.pback]
|
| 1725 |
int_type sputbackc(char_type c);
|
| 1726 |
int_type sungetc();
|
| 1727 |
|
| 1728 |
-
// [streambuf.pub.put]
|
| 1729 |
int_type sputc(char_type c);
|
| 1730 |
streamsize sputn(const char_type* s, streamsize n);
|
| 1731 |
|
| 1732 |
protected:
|
| 1733 |
basic_streambuf();
|
| 1734 |
basic_streambuf(const basic_streambuf& rhs);
|
| 1735 |
basic_streambuf& operator=(const basic_streambuf& rhs);
|
| 1736 |
|
| 1737 |
void swap(basic_streambuf& rhs);
|
| 1738 |
|
| 1739 |
-
// [streambuf.get.area]
|
| 1740 |
char_type* eback() const;
|
| 1741 |
char_type* gptr() const;
|
| 1742 |
char_type* egptr() const;
|
| 1743 |
void gbump(int n);
|
| 1744 |
void setg(char_type* gbeg, char_type* gnext, char_type* gend);
|
| 1745 |
|
| 1746 |
-
// [streambuf.put.area]
|
| 1747 |
char_type* pbase() const;
|
| 1748 |
char_type* pptr() const;
|
| 1749 |
char_type* epptr() const;
|
| 1750 |
void pbump(int n);
|
| 1751 |
void setp(char_type* pbeg, char_type* pend);
|
| 1752 |
|
| 1753 |
-
// [streambuf.virtuals] virtual functions
|
| 1754 |
-
// [streambuf.virt.locales]
|
| 1755 |
virtual void imbue(const locale& loc);
|
| 1756 |
|
| 1757 |
-
// [streambuf.virt.buffer]
|
| 1758 |
-
virtual basic_streambuf
|
| 1759 |
-
setbuf(char_type* s, streamsize n);
|
| 1760 |
virtual pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 1761 |
-
|
|
|
|
| 1762 |
virtual pos_type seekpos(pos_type sp,
|
| 1763 |
-
|
|
|
|
| 1764 |
virtual int sync();
|
| 1765 |
|
| 1766 |
-
// [streambuf.virt.get]
|
| 1767 |
virtual streamsize showmanyc();
|
| 1768 |
virtual streamsize xsgetn(char_type* s, streamsize n);
|
| 1769 |
virtual int_type underflow();
|
| 1770 |
virtual int_type uflow();
|
| 1771 |
|
| 1772 |
-
// [streambuf.virt.pback]
|
| 1773 |
virtual int_type pbackfail(int_type c = traits::eof());
|
| 1774 |
|
| 1775 |
-
// [streambuf.virt.put]
|
| 1776 |
virtual streamsize xsputn(const char_type* s, streamsize n);
|
| 1777 |
virtual int_type overflow(int_type c = traits::eof());
|
| 1778 |
};
|
| 1779 |
}
|
| 1780 |
```
|
| 1781 |
|
| 1782 |
-
The class template `basic_streambuf
|
| 1783 |
-
|
| 1784 |
-
|
| 1785 |
|
| 1786 |
- a character *input sequence*;
|
| 1787 |
- a character *output sequence*.
|
| 1788 |
|
| 1789 |
#### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
|
| 1790 |
|
| 1791 |
``` cpp
|
| 1792 |
basic_streambuf();
|
| 1793 |
```
|
| 1794 |
|
| 1795 |
-
*Effects:* Constructs an object of class
|
| 1796 |
-
and initializes:[^13]
|
| 1797 |
|
| 1798 |
- all its pointer member objects to null pointers,
|
| 1799 |
- the `getloc()` member to a copy the global locale, `locale()`, at the
|
| 1800 |
time of construction.
|
| 1801 |
|
|
@@ -1831,11 +1861,11 @@ basic_streambuf(const basic_streambuf& rhs);
|
|
| 1831 |
|
| 1832 |
``` cpp
|
| 1833 |
locale pubimbue(const locale& loc);
|
| 1834 |
```
|
| 1835 |
|
| 1836 |
-
`loc == getloc()`.
|
| 1837 |
|
| 1838 |
*Effects:* Calls `imbue(loc)`.
|
| 1839 |
|
| 1840 |
*Returns:* Previous value of `getloc()`.
|
| 1841 |
|
|
@@ -1850,25 +1880,27 @@ been called but before `pubimbue` has returned (i.e., from within the
|
|
| 1850 |
call of `imbue()`) then it returns the previous value.
|
| 1851 |
|
| 1852 |
##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
|
| 1853 |
|
| 1854 |
``` cpp
|
| 1855 |
-
basic_streambuf
|
| 1856 |
```
|
| 1857 |
|
| 1858 |
*Returns:* `setbuf(s, n)`.
|
| 1859 |
|
| 1860 |
``` cpp
|
| 1861 |
pos_type pubseekoff(off_type off, ios_base::seekdir way,
|
| 1862 |
-
|
|
|
|
| 1863 |
```
|
| 1864 |
|
| 1865 |
*Returns:* `seekoff(off, way, which)`.
|
| 1866 |
|
| 1867 |
``` cpp
|
| 1868 |
pos_type pubseekpos(pos_type sp,
|
| 1869 |
-
|
|
|
|
| 1870 |
```
|
| 1871 |
|
| 1872 |
*Returns:* `seekpos(sp, which)`.
|
| 1873 |
|
| 1874 |
``` cpp
|
|
@@ -1921,11 +1953,11 @@ streamsize sgetn(char_type* s, streamsize n);
|
|
| 1921 |
``` cpp
|
| 1922 |
int_type sputbackc(char_type c);
|
| 1923 |
```
|
| 1924 |
|
| 1925 |
*Returns:* If the input sequence putback position is not available, or
|
| 1926 |
-
if `traits::eq(c,gptr()[-1])` is false, returns
|
| 1927 |
`pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
|
| 1928 |
pointer for the input sequence and returns
|
| 1929 |
`traits::to_int_type(*gptr())`.
|
| 1930 |
|
| 1931 |
``` cpp
|
|
@@ -2109,12 +2141,12 @@ int sync();
|
|
| 2109 |
*Effects:* Synchronizes the controlled sequences with the arrays. That
|
| 2110 |
is, if `pbase()` is non-null the characters between `pbase()` and
|
| 2111 |
`pptr()` are written to the controlled sequence. The pointers may then
|
| 2112 |
be reset as appropriate.
|
| 2113 |
|
| 2114 |
-
*Returns:* -1 on failure. What constitutes failure is determined by
|
| 2115 |
-
derived class ([[filebuf.virtuals]]).
|
| 2116 |
|
| 2117 |
*Default behavior:* Returns zero.
|
| 2118 |
|
| 2119 |
##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
|
| 2120 |
|
|
@@ -2158,22 +2190,38 @@ function only if `gptr()` is null or `gptr() >= egptr()`
|
|
| 2158 |
*Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
|
| 2159 |
of the *pending sequence*, without moving the input sequence position
|
| 2160 |
past it. If the pending sequence is null then the function returns
|
| 2161 |
`traits::eof()` to indicate failure.
|
| 2162 |
|
| 2163 |
-
The *pending sequence* of characters is defined as the concatenation of
|
| 2164 |
|
| 2165 |
-
|
|
|
|
|
|
|
|
|
|
| 2166 |
|
| 2167 |
-
The *
|
|
|
|
|
|
|
| 2168 |
|
| 2169 |
-
|
| 2170 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2171 |
|
| 2172 |
If `eback()` and `gptr()` are non-null then the function is not
|
| 2173 |
constrained as to their contents, but the “usual backup condition” is
|
| 2174 |
-
that either
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2175 |
|
| 2176 |
*Default behavior:* Returns `traits::eof()`.
|
| 2177 |
|
| 2178 |
``` cpp
|
| 2179 |
int_type uflow();
|
|
@@ -2206,16 +2254,16 @@ The *pending sequence* is defined as for `underflow()`, with the
|
|
| 2206 |
modifications that
|
| 2207 |
|
| 2208 |
- If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
|
| 2209 |
input sequence is backed up one character before the pending sequence
|
| 2210 |
is determined.
|
| 2211 |
-
- If `traits::eq_int_type(c,traits::eof())` returns `false`, then `c`
|
| 2212 |
-
prepended. Whether the input sequence is backed up or modified in
|
| 2213 |
-
other way is unspecified.
|
| 2214 |
|
| 2215 |
-
On return, the constraints of `gptr()`, `eback()`, and
|
| 2216 |
-
same as for `underflow()`.
|
| 2217 |
|
| 2218 |
*Returns:* `traits::eof()` to indicate failure. Failure may occur
|
| 2219 |
because the input sequence could not be backed up, or if for some other
|
| 2220 |
reason the pointers could not be set consistent with the constraints.
|
| 2221 |
`pbackfail()` is called only when put back has really failed.
|
|
@@ -2232,13 +2280,13 @@ streamsize xsputn(const char_type* s, streamsize n);
|
|
| 2232 |
|
| 2233 |
*Effects:* Writes up to `n` characters to the output sequence as if by
|
| 2234 |
repeated calls to `sputc(c)`. The characters written are obtained from
|
| 2235 |
successive elements of the array whose first element is designated by
|
| 2236 |
`s`. Writing stops when either `n` characters have been written or a
|
| 2237 |
-
call to `sputc(c)` would return `traits::eof()`.
|
| 2238 |
whether the function calls `overflow()` when `pptr() == epptr()` becomes
|
| 2239 |
-
true or whether it achieves the same effects by other means.
|
| 2240 |
|
| 2241 |
*Returns:* The number of characters written.
|
| 2242 |
|
| 2243 |
``` cpp
|
| 2244 |
int_type overflow(int_type c = traits::eof());
|
|
@@ -2246,71 +2294,92 @@ int_type overflow(int_type c = traits::eof());
|
|
| 2246 |
|
| 2247 |
*Effects:* Consumes some initial subsequence of the characters of the
|
| 2248 |
*pending sequence*. The pending sequence is defined as the concatenation
|
| 2249 |
of
|
| 2250 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2251 |
*Remarks:* The member functions `sputc()` and `sputn()` call this
|
| 2252 |
function in case that no room can be found in the put buffer enough to
|
| 2253 |
accommodate the argument character sequence.
|
| 2254 |
|
| 2255 |
*Requires:* Every overriding definition of this virtual function shall
|
| 2256 |
obey the following constraints:
|
| 2257 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2258 |
*Returns:* `traits::eof()` or throws an exception if the function fails.
|
| 2259 |
|
| 2260 |
Otherwise, returns some value other than `traits::eof()` to indicate
|
| 2261 |
-
success.[^
|
| 2262 |
|
| 2263 |
*Default behavior:* Returns `traits::eof()`.
|
| 2264 |
|
| 2265 |
## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
|
| 2266 |
|
| 2267 |
-
###
|
| 2268 |
-
|
| 2269 |
-
\synopsis{Header \texttt{\<istream\>} synopsis}
|
| 2270 |
|
| 2271 |
``` cpp
|
| 2272 |
namespace std {
|
| 2273 |
template <class charT, class traits = char_traits<charT>>
|
| 2274 |
class basic_istream;
|
| 2275 |
-
|
| 2276 |
-
|
|
|
|
| 2277 |
|
| 2278 |
template <class charT, class traits = char_traits<charT>>
|
| 2279 |
class basic_iostream;
|
| 2280 |
-
|
| 2281 |
-
|
|
|
|
| 2282 |
|
| 2283 |
template <class charT, class traits>
|
| 2284 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 2285 |
|
| 2286 |
template <class charT, class traits, class T>
|
| 2287 |
-
basic_istream<charT, traits>&
|
| 2288 |
-
operator>>(basic_istream<charT, traits>&& is, T& x);
|
| 2289 |
}
|
| 2290 |
```
|
| 2291 |
|
|
|
|
|
|
|
| 2292 |
``` cpp
|
| 2293 |
namespace std {
|
| 2294 |
template <class charT, class traits = char_traits<charT>>
|
| 2295 |
class basic_ostream;
|
| 2296 |
-
|
| 2297 |
-
|
|
|
|
| 2298 |
|
| 2299 |
template <class charT, class traits>
|
| 2300 |
basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
|
| 2301 |
template <class charT, class traits>
|
| 2302 |
basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
|
| 2303 |
template <class charT, class traits>
|
| 2304 |
basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
|
| 2305 |
|
| 2306 |
template <class charT, class traits, class T>
|
| 2307 |
-
basic_ostream<charT, traits>&
|
| 2308 |
-
operator<<(basic_ostream<charT, traits>&& os, const T& x);
|
| 2309 |
}
|
| 2310 |
```
|
| 2311 |
|
|
|
|
|
|
|
| 2312 |
``` cpp
|
| 2313 |
namespace std {
|
| 2314 |
// types T1, T2, ... are unspecified implementation types
|
| 2315 |
T1 resetiosflags(ios_base::fmtflags mask);
|
| 2316 |
T2 setiosflags (ios_base::fmtflags mask);
|
|
@@ -2326,15 +2395,19 @@ namespace std {
|
|
| 2326 |
template <class charT>
|
| 2327 |
T11 quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
|
| 2328 |
|
| 2329 |
template <class charT, class traits, class Allocator>
|
| 2330 |
T12 quoted(const basic_string<charT, traits, Allocator>& s,
|
| 2331 |
-
|
| 2332 |
|
| 2333 |
template <class charT, class traits, class Allocator>
|
| 2334 |
T13 quoted(basic_string<charT, traits, Allocator>& s,
|
| 2335 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2336 |
}
|
| 2337 |
```
|
| 2338 |
|
| 2339 |
### Input streams <a id="input.streams">[[input.streams]]</a>
|
| 2340 |
|
|
@@ -2348,30 +2421,30 @@ extracts from stream rvalues.
|
|
| 2348 |
namespace std {
|
| 2349 |
template <class charT, class traits = char_traits<charT>>
|
| 2350 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 2351 |
public:
|
| 2352 |
// types (inherited from basic_ios ([ios])):
|
| 2353 |
-
|
| 2354 |
-
|
| 2355 |
-
|
| 2356 |
-
|
| 2357 |
-
|
| 2358 |
|
| 2359 |
-
// [istream.cons]
|
| 2360 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2361 |
virtual ~basic_istream();
|
| 2362 |
|
| 2363 |
-
// [istream::sentry]
|
| 2364 |
class sentry;
|
| 2365 |
|
| 2366 |
-
// [istream.formatted]
|
| 2367 |
-
basic_istream<charT,traits>&
|
| 2368 |
-
basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&));
|
| 2369 |
-
basic_istream<charT,traits>&
|
| 2370 |
-
|
| 2371 |
-
basic_istream<charT,traits>&
|
| 2372 |
-
ios_base& (*pf)(ios_base&));
|
| 2373 |
|
| 2374 |
basic_istream<charT, traits>& operator>>(bool& n);
|
| 2375 |
basic_istream<charT, traits>& operator>>(short& n);
|
| 2376 |
basic_istream<charT, traits>& operator>>(unsigned short& n);
|
| 2377 |
basic_istream<charT, traits>& operator>>(int& n);
|
|
@@ -2383,30 +2456,25 @@ namespace std {
|
|
| 2383 |
basic_istream<charT, traits>& operator>>(float& f);
|
| 2384 |
basic_istream<charT, traits>& operator>>(double& f);
|
| 2385 |
basic_istream<charT, traits>& operator>>(long double& f);
|
| 2386 |
|
| 2387 |
basic_istream<charT, traits>& operator>>(void*& p);
|
| 2388 |
-
basic_istream<charT,traits>& operator>>(
|
| 2389 |
-
basic_streambuf<char_type,traits>* sb);
|
| 2390 |
|
| 2391 |
-
// [istream.unformatted]
|
| 2392 |
streamsize gcount() const;
|
| 2393 |
int_type get();
|
| 2394 |
basic_istream<charT, traits>& get(char_type& c);
|
| 2395 |
basic_istream<charT, traits>& get(char_type* s, streamsize n);
|
| 2396 |
-
basic_istream<charT,traits>& get(char_type* s, streamsize n,
|
| 2397 |
-
char_type delim);
|
| 2398 |
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
|
| 2399 |
-
basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb,
|
| 2400 |
-
char_type delim);
|
| 2401 |
|
| 2402 |
basic_istream<charT, traits>& getline(char_type* s, streamsize n);
|
| 2403 |
-
basic_istream<charT,traits>& getline(char_type* s, streamsize n,
|
| 2404 |
-
char_type delim);
|
| 2405 |
|
| 2406 |
-
basic_istream<charT,traits>& ignore(
|
| 2407 |
-
streamsize n = 1, int_type delim = traits::eof());
|
| 2408 |
int_type peek();
|
| 2409 |
basic_istream<charT, traits>& read (char_type* s, streamsize n);
|
| 2410 |
streamsize readsome(char_type* s, streamsize n);
|
| 2411 |
|
| 2412 |
basic_istream<charT, traits>& putback(char_type c);
|
|
@@ -2416,45 +2484,40 @@ namespace std {
|
|
| 2416 |
pos_type tellg();
|
| 2417 |
basic_istream<charT, traits>& seekg(pos_type);
|
| 2418 |
basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
|
| 2419 |
|
| 2420 |
protected:
|
|
|
|
| 2421 |
basic_istream(const basic_istream& rhs) = delete;
|
| 2422 |
basic_istream(basic_istream&& rhs);
|
| 2423 |
|
| 2424 |
-
// [istream.assign]
|
| 2425 |
basic_istream& operator=(const basic_istream& rhs) = delete;
|
| 2426 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2427 |
void swap(basic_istream& rhs);
|
| 2428 |
};
|
| 2429 |
|
| 2430 |
-
// [istream
|
| 2431 |
template<class charT, class traits>
|
| 2432 |
-
basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&,
|
| 2433 |
-
charT&);
|
| 2434 |
template<class traits>
|
| 2435 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
|
| 2436 |
-
unsigned char&);
|
| 2437 |
template<class traits>
|
| 2438 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
|
| 2439 |
-
signed char&);
|
| 2440 |
|
| 2441 |
template<class charT, class traits>
|
| 2442 |
-
basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&,
|
| 2443 |
-
charT*);
|
| 2444 |
template<class traits>
|
| 2445 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
|
| 2446 |
-
unsigned char*);
|
| 2447 |
template<class traits>
|
| 2448 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
|
| 2449 |
-
signed char*);
|
| 2450 |
}
|
| 2451 |
```
|
| 2452 |
|
| 2453 |
-
The class `basic_istream` defines a number of member function
|
| 2454 |
-
that assist in reading and interpreting input from sequences
|
| 2455 |
-
by a stream buffer.
|
| 2456 |
|
| 2457 |
Two groups of member function signatures share common properties: the
|
| 2458 |
*formatted input functions* (or *extractors*) and the *unformatted input
|
| 2459 |
functions.* Both groups of input functions are described as if they
|
| 2460 |
obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
|
|
@@ -2476,15 +2539,15 @@ failure indication.
|
|
| 2476 |
|
| 2477 |
``` cpp
|
| 2478 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2479 |
```
|
| 2480 |
|
| 2481 |
-
*Effects:* Constructs an object of class `basic_istream`,
|
| 2482 |
-
|
| 2483 |
`basic_ios::init(sb)` ([[basic.ios.cons]]).
|
| 2484 |
|
| 2485 |
-
`gcount() == 0`
|
| 2486 |
|
| 2487 |
``` cpp
|
| 2488 |
basic_istream(basic_istream&& rhs);
|
| 2489 |
```
|
| 2490 |
|
|
@@ -2505,11 +2568,11 @@ virtual ~basic_istream();
|
|
| 2505 |
|
| 2506 |
``` cpp
|
| 2507 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2508 |
```
|
| 2509 |
|
| 2510 |
-
*Effects:* `swap(rhs)
|
| 2511 |
|
| 2512 |
*Returns:* `*this`.
|
| 2513 |
|
| 2514 |
``` cpp
|
| 2515 |
void swap(basic_istream& rhs);
|
|
@@ -2522,11 +2585,11 @@ values returned by `gcount()` and `rhs.gcount()`.
|
|
| 2522 |
|
| 2523 |
``` cpp
|
| 2524 |
namespace std {
|
| 2525 |
template <class charT, class traits = char_traits<charT>>
|
| 2526 |
class basic_istream<charT, traits>::sentry {
|
| 2527 |
-
|
| 2528 |
bool ok_; // exposition only
|
| 2529 |
public:
|
| 2530 |
explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
|
| 2531 |
~sentry();
|
| 2532 |
explicit operator bool() const { return ok_; }
|
|
@@ -2549,19 +2612,23 @@ Otherwise, prepares for formatted or unformatted input. First, if
|
|
| 2549 |
to synchronize the output sequence with any associated external C
|
| 2550 |
stream. Except that this call can be suppressed if the put area of
|
| 2551 |
`is.tie()` is empty. Further an implementation is allowed to defer the
|
| 2552 |
call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
|
| 2553 |
such call occurs before the `sentry` object is destroyed, the call to
|
| 2554 |
-
`flush` may be eliminated entirely.[^
|
| 2555 |
`is.flags() & ios_base::skipws` is nonzero, the function extracts and
|
| 2556 |
discards each character as long as the next available input character
|
| 2557 |
`c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
|
| 2558 |
`is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
|
| 2559 |
`setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
|
| 2560 |
|
| 2561 |
*Remarks:* The constructor
|
| 2562 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2563 |
uses the currently imbued locale in `is`, to determine whether the next
|
| 2564 |
input character is whitespace or not.
|
| 2565 |
|
| 2566 |
To decide if the character `c` is a whitespace character, the
|
| 2567 |
constructor performs as if it executes the following code fragment:
|
|
@@ -2573,11 +2640,11 @@ if (ctype.is(ctype.space,c)!=0)
|
|
| 2573 |
```
|
| 2574 |
|
| 2575 |
If, after any preparation is completed, `is.good()` is `true`,
|
| 2576 |
`ok_ != false` otherwise, `ok_ == false`. During preparation, the
|
| 2577 |
constructor may call `setstate(failbit)` (which may throw
|
| 2578 |
-
`ios_base::failure` ([[iostate.flags]]))[^
|
| 2579 |
|
| 2580 |
``` cpp
|
| 2581 |
~sentry();
|
| 2582 |
```
|
| 2583 |
|
|
@@ -2595,11 +2662,11 @@ explicit operator bool() const;
|
|
| 2595 |
|
| 2596 |
Each formatted input function begins execution by constructing an object
|
| 2597 |
of class `sentry` with the `noskipws` (second) argument `false`. If the
|
| 2598 |
`sentry` object returns `true`, when converted to a value of type
|
| 2599 |
`bool`, the function endeavors to obtain the requested input. If an
|
| 2600 |
-
exception is thrown during input then `ios::badbit` is turned on[^
|
| 2601 |
`*this`’s error state. If `(exceptions()&badbit) != 0` then the
|
| 2602 |
exception is rethrown. In any case, the formatted input function
|
| 2603 |
destroys the `sentry` object. If no exception has been thrown, it
|
| 2604 |
returns `*this`.
|
| 2605 |
|
|
@@ -2625,32 +2692,36 @@ stream data. These extractors behave as formatted input functions (as
|
|
| 2625 |
described in [[istream.formatted.reqmts]]). After a sentry object is
|
| 2626 |
constructed, the conversion occurs as if performed by the following code
|
| 2627 |
fragment:
|
| 2628 |
|
| 2629 |
``` cpp
|
| 2630 |
-
|
| 2631 |
iostate err = iostate::goodbit;
|
| 2632 |
use_facet<numget>(loc).get(*this, 0, *this, err, val);
|
| 2633 |
setstate(err);
|
| 2634 |
```
|
| 2635 |
|
| 2636 |
In the above fragment, `loc` stands for the private member of the
|
| 2637 |
-
`basic_ios` class.
|
|
|
|
|
|
|
| 2638 |
`istreambuf_iterator` class which is an iterator pointed to an input
|
| 2639 |
-
stream. It bypasses istreams and uses streambufs
|
| 2640 |
-
|
| 2641 |
-
|
|
|
|
|
|
|
| 2642 |
|
| 2643 |
``` cpp
|
| 2644 |
operator>>(short& val);
|
| 2645 |
```
|
| 2646 |
|
| 2647 |
The conversion occurs as if performed by the following code fragment
|
| 2648 |
(using the same notation as for the preceding code fragment):
|
| 2649 |
|
| 2650 |
``` cpp
|
| 2651 |
-
|
| 2652 |
iostate err = ios_base::goodbit;
|
| 2653 |
long lval;
|
| 2654 |
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
|
| 2655 |
if (lval < numeric_limits<short>::min()) {
|
| 2656 |
err |= ios_base::failbit;
|
|
@@ -2669,11 +2740,11 @@ operator>>(int& val);
|
|
| 2669 |
|
| 2670 |
The conversion occurs as if performed by the following code fragment
|
| 2671 |
(using the same notation as for the preceding code fragment):
|
| 2672 |
|
| 2673 |
``` cpp
|
| 2674 |
-
|
| 2675 |
iostate err = ios_base::goodbit;
|
| 2676 |
long lval;
|
| 2677 |
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
|
| 2678 |
if (lval < numeric_limits<int>::min()) {
|
| 2679 |
err |= ios_base::failbit;
|
|
@@ -2684,54 +2755,50 @@ if (lval < numeric_limits<int>::min()) {
|
|
| 2684 |
} else
|
| 2685 |
val = static_cast<int>(lval);
|
| 2686 |
setstate(err);
|
| 2687 |
```
|
| 2688 |
|
| 2689 |
-
##### `basic_istream::operator>>` <a id="istream
|
| 2690 |
|
| 2691 |
``` cpp
|
| 2692 |
-
basic_istream<charT,traits>&
|
| 2693 |
-
|
| 2694 |
```
|
| 2695 |
|
| 2696 |
*Effects:* None. This extractor does not behave as a formatted input
|
| 2697 |
-
function (as described in [[istream.formatted.reqmts]]
|
| 2698 |
|
| 2699 |
-
*Returns:* `pf(*this)`.[^
|
| 2700 |
|
| 2701 |
``` cpp
|
| 2702 |
-
basic_istream<charT,traits>&
|
| 2703 |
-
|
| 2704 |
```
|
| 2705 |
|
| 2706 |
*Effects:* Calls `pf(*this)`. This extractor does not behave as a
|
| 2707 |
formatted input function (as described
|
| 2708 |
in [[istream.formatted.reqmts]]).
|
| 2709 |
|
| 2710 |
*Returns:* `*this`.
|
| 2711 |
|
| 2712 |
``` cpp
|
| 2713 |
-
basic_istream<charT,traits>& operator>>
|
| 2714 |
-
(ios_base& (*pf)(ios_base&));
|
| 2715 |
```
|
| 2716 |
|
| 2717 |
-
*Effects:* Calls `pf(*this)`.[^
|
| 2718 |
formatted input function (as described
|
| 2719 |
in [[istream.formatted.reqmts]]).
|
| 2720 |
|
| 2721 |
*Returns:* `*this`.
|
| 2722 |
|
| 2723 |
``` cpp
|
| 2724 |
template<class charT, class traits>
|
| 2725 |
-
basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>& in,
|
| 2726 |
-
charT* s);
|
| 2727 |
template<class traits>
|
| 2728 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
|
| 2729 |
-
unsigned char* s);
|
| 2730 |
template<class traits>
|
| 2731 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
|
| 2732 |
-
signed char* s);
|
| 2733 |
```
|
| 2734 |
|
| 2735 |
*Effects:* Behaves like a formatted input member (as described
|
| 2736 |
in [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
|
| 2737 |
constructed, `operator>>` extracts characters and stores them into
|
|
@@ -2743,12 +2810,12 @@ stored.
|
|
| 2743 |
|
| 2744 |
Characters are extracted and stored until any of the following occurs:
|
| 2745 |
|
| 2746 |
- `n-1` characters are stored;
|
| 2747 |
- end of file occurs on the input sequence;
|
| 2748 |
-
- `ct
|
| 2749 |
-
`
|
| 2750 |
|
| 2751 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 2752 |
which may be the first position if no characters were extracted.
|
| 2753 |
`operator>>` then calls `width(0)`.
|
| 2754 |
|
|
@@ -2757,38 +2824,33 @@ which may throw `ios_base::failure` ([[iostate.flags]]).
|
|
| 2757 |
|
| 2758 |
*Returns:* `in`.
|
| 2759 |
|
| 2760 |
``` cpp
|
| 2761 |
template<class charT, class traits>
|
| 2762 |
-
basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>& in,
|
| 2763 |
-
charT& c);
|
| 2764 |
template<class traits>
|
| 2765 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
|
| 2766 |
-
unsigned char& c);
|
| 2767 |
template<class traits>
|
| 2768 |
-
basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
|
| 2769 |
-
signed char& c);
|
| 2770 |
```
|
| 2771 |
|
| 2772 |
*Effects:* Behaves like a formatted input member (as described
|
| 2773 |
in [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
|
| 2774 |
constructed a character is extracted from `in`, if one is available, and
|
| 2775 |
stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
|
| 2776 |
|
| 2777 |
*Returns:* `in`.
|
| 2778 |
|
| 2779 |
``` cpp
|
| 2780 |
-
basic_istream<charT,traits>& operator>>
|
| 2781 |
-
(basic_streambuf<charT,traits>* sb);
|
| 2782 |
```
|
| 2783 |
|
| 2784 |
-
*Effects:* Behaves as an unformatted input function
|
| 2785 |
-
|
| 2786 |
-
`
|
| 2787 |
-
|
| 2788 |
-
|
| 2789 |
-
output sequence controlled by `sb`. Characters are extracted and
|
| 2790 |
inserted until any of the following occurs:
|
| 2791 |
|
| 2792 |
- end-of-file occurs on the input sequence;
|
| 2793 |
- inserting in the output sequence fails (in which case the character to
|
| 2794 |
be inserted is not extracted);
|
|
@@ -2808,18 +2870,18 @@ rethrown.
|
|
| 2808 |
Each unformatted input function begins execution by constructing an
|
| 2809 |
object of class `sentry` with the default argument `noskipws` (second)
|
| 2810 |
argument `true`. If the `sentry` object returns `true`, when converted
|
| 2811 |
to a value of type `bool`, the function endeavors to obtain the
|
| 2812 |
requested input. Otherwise, if the sentry constructor exits by throwing
|
| 2813 |
-
an exception or if the sentry object returns false, when converted to
|
| 2814 |
-
value of type `bool`, the function returns without attempting to
|
| 2815 |
-
any input. In either case the number of extracted characters is
|
| 2816 |
-
0; unformatted input functions taking a character array of
|
| 2817 |
-
as an argument shall also store a null character (using
|
| 2818 |
-
the first location of the array. If an exception is thrown
|
| 2819 |
-
then `ios::badbit` is turned on[^
|
| 2820 |
-
(Exceptions thrown from `basic_ios<>::clear()` are not caught or
|
| 2821 |
rethrown.) If `(exceptions()&badbit) != 0` then the exception is
|
| 2822 |
rethrown. It also counts the number of characters extracted. If no
|
| 2823 |
exception has been thrown it ends by storing the count in a member
|
| 2824 |
object and returning the value specified. In any event the `sentry`
|
| 2825 |
object is destroyed before leaving the unformatted input function.
|
|
@@ -2827,49 +2889,47 @@ object is destroyed before leaving the unformatted input function.
|
|
| 2827 |
``` cpp
|
| 2828 |
streamsize gcount() const;
|
| 2829 |
```
|
| 2830 |
|
| 2831 |
*Effects:* None. This member function does not behave as an unformatted
|
| 2832 |
-
input function (as described
|
| 2833 |
|
| 2834 |
*Returns:* The number of characters extracted by the last unformatted
|
| 2835 |
input member function called for the object.
|
| 2836 |
|
| 2837 |
``` cpp
|
| 2838 |
int_type get();
|
| 2839 |
```
|
| 2840 |
|
| 2841 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2842 |
-
|
| 2843 |
-
|
| 2844 |
-
|
| 2845 |
-
`ios_base::failure` ([[iostate.flags]]),
|
| 2846 |
|
| 2847 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 2848 |
|
| 2849 |
``` cpp
|
| 2850 |
basic_istream<charT, traits>& get(char_type& c);
|
| 2851 |
```
|
| 2852 |
|
| 2853 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2854 |
-
|
| 2855 |
-
|
| 2856 |
-
`
|
| 2857 |
-
|
| 2858 |
|
| 2859 |
*Returns:* `*this`.
|
| 2860 |
|
| 2861 |
``` cpp
|
| 2862 |
-
basic_istream<charT,traits>& get(char_type* s, streamsize n,
|
| 2863 |
-
char_type delim );
|
| 2864 |
```
|
| 2865 |
|
| 2866 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2867 |
-
|
| 2868 |
-
|
| 2869 |
-
|
| 2870 |
-
|
| 2871 |
|
| 2872 |
- `n` is less than one or `n - 1` characters are stored;
|
| 2873 |
- end-of-file occurs on the input sequence (in which case the function
|
| 2874 |
calls `setstate(eofbit)`);
|
| 2875 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
|
@@ -2884,24 +2944,22 @@ next successive location of the array.
|
|
| 2884 |
|
| 2885 |
``` cpp
|
| 2886 |
basic_istream<charT, traits>& get(char_type* s, streamsize n);
|
| 2887 |
```
|
| 2888 |
|
| 2889 |
-
*Effects:* Calls `get(s,n,widen(’\n’))`
|
| 2890 |
|
| 2891 |
*Returns:* Value returned by the call.
|
| 2892 |
|
| 2893 |
``` cpp
|
| 2894 |
-
basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb,
|
| 2895 |
-
char_type delim );
|
| 2896 |
```
|
| 2897 |
|
| 2898 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2899 |
-
|
| 2900 |
-
|
| 2901 |
-
|
| 2902 |
-
the following occurs:
|
| 2903 |
|
| 2904 |
- end-of-file occurs on the input sequence;
|
| 2905 |
- inserting in the output sequence fails (in which case the character to
|
| 2906 |
be inserted is not extracted);
|
| 2907 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
|
@@ -2916,44 +2974,45 @@ which may throw `ios_base::failure` ([[iostate.flags]]).
|
|
| 2916 |
|
| 2917 |
``` cpp
|
| 2918 |
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
|
| 2919 |
```
|
| 2920 |
|
| 2921 |
-
*Effects:* Calls `get(sb, widen(’\n’))`
|
| 2922 |
|
| 2923 |
*Returns:* Value returned by the call.
|
| 2924 |
|
| 2925 |
``` cpp
|
| 2926 |
-
basic_istream<charT,traits>& getline(char_type* s, streamsize n,
|
| 2927 |
-
char_type delim);
|
| 2928 |
```
|
| 2929 |
|
| 2930 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2931 |
-
|
| 2932 |
-
|
| 2933 |
-
|
| 2934 |
-
|
| 2935 |
|
| 2936 |
1. end-of-file occurs on the input sequence (in which case the function
|
| 2937 |
calls `setstate(eofbit)`);
|
| 2938 |
2. `traits::eq(c, delim)` for the next available input character `c`
|
| 2939 |
(in which case the input character is extracted but not
|
| 2940 |
-
stored);[^
|
| 2941 |
3. `n` is less than one or `n - 1` characters are stored (in which case
|
| 2942 |
the function calls `setstate(failbit)`).
|
| 2943 |
|
| 2944 |
-
These conditions are tested in the order shown.[^
|
| 2945 |
|
| 2946 |
If the function extracts no characters, it calls `setstate(failbit)`
|
| 2947 |
-
(which may throw `ios_base::failure` ([[iostate.flags]])).[^
|
| 2948 |
|
| 2949 |
In any case, if `n` is greater than zero, it then stores a null
|
| 2950 |
character (using `charT()`) into the next successive location of the
|
| 2951 |
array.
|
| 2952 |
|
| 2953 |
*Returns:* `*this`.
|
| 2954 |
|
|
|
|
|
|
|
| 2955 |
``` cpp
|
| 2956 |
#include <iostream>
|
| 2957 |
|
| 2958 |
int main() {
|
| 2959 |
using namespace std;
|
|
@@ -2975,27 +3034,28 @@ int main() {
|
|
| 2975 |
cout << " (" << count << " chars): " << buffer << endl;
|
| 2976 |
}
|
| 2977 |
}
|
| 2978 |
```
|
| 2979 |
|
|
|
|
|
|
|
| 2980 |
``` cpp
|
| 2981 |
basic_istream<charT, traits>& getline(char_type* s, streamsize n);
|
| 2982 |
```
|
| 2983 |
|
| 2984 |
*Returns:* `getline(s, n, widen(’\n’))`
|
| 2985 |
|
| 2986 |
``` cpp
|
| 2987 |
-
basic_istream<charT,traits>&
|
| 2988 |
-
ignore(streamsize n = 1, int_type delim = traits::eof());
|
| 2989 |
```
|
| 2990 |
|
| 2991 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2992 |
-
|
| 2993 |
-
|
| 2994 |
-
|
| 2995 |
|
| 2996 |
-
- `n != numeric_limits<streamsize>::max()` ([[limits]]) and `n`
|
| 2997 |
characters have been extracted so far
|
| 2998 |
- end-of-file occurs on the input sequence (in which case the function
|
| 2999 |
calls `setstate(eofbit)`, which may throw
|
| 3000 |
`ios_base::failure` ([[iostate.flags]]));
|
| 3001 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
|
@@ -3009,27 +3069,26 @@ until any of the following occurs:
|
|
| 3009 |
``` cpp
|
| 3010 |
int_type peek();
|
| 3011 |
```
|
| 3012 |
|
| 3013 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3014 |
-
|
| 3015 |
-
|
| 3016 |
|
| 3017 |
*Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
|
| 3018 |
`rdbuf()->sgetc()`.
|
| 3019 |
|
| 3020 |
``` cpp
|
| 3021 |
basic_istream<charT, traits>& read(char_type* s, streamsize n);
|
| 3022 |
```
|
| 3023 |
|
| 3024 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3025 |
-
|
| 3026 |
-
|
| 3027 |
-
|
| 3028 |
-
|
| 3029 |
-
|
| 3030 |
-
following occurs:
|
| 3031 |
|
| 3032 |
- `n` characters are stored;
|
| 3033 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3034 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 3035 |
`ios_base::failure` ([[iostate.flags]])).
|
|
@@ -3039,17 +3098,16 @@ following occurs:
|
|
| 3039 |
``` cpp
|
| 3040 |
streamsize readsome(char_type* s, streamsize n);
|
| 3041 |
```
|
| 3042 |
|
| 3043 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3044 |
-
|
| 3045 |
-
|
| 3046 |
-
|
| 3047 |
-
|
| 3048 |
-
|
| 3049 |
-
|
| 3050 |
-
characters;
|
| 3051 |
|
| 3052 |
- If `rdbuf()->in_avail() == 0`, extracts no characters
|
| 3053 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 3054 |
|
| 3055 |
*Returns:* The number of characters extracted.
|
|
@@ -3057,86 +3115,87 @@ characters;
|
|
| 3057 |
``` cpp
|
| 3058 |
basic_istream<charT, traits>& putback(char_type c);
|
| 3059 |
```
|
| 3060 |
|
| 3061 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3062 |
-
|
| 3063 |
-
|
| 3064 |
-
|
| 3065 |
-
|
| 3066 |
-
|
| 3067 |
-
|
| 3068 |
-
|
| 3069 |
-
|
|
|
|
| 3070 |
|
| 3071 |
*Returns:* `*this`.
|
| 3072 |
|
| 3073 |
``` cpp
|
| 3074 |
basic_istream<charT, traits>& unget();
|
| 3075 |
```
|
| 3076 |
|
| 3077 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3078 |
-
|
| 3079 |
-
|
| 3080 |
-
|
| 3081 |
-
|
| 3082 |
-
|
| 3083 |
-
|
| 3084 |
-
|
| 3085 |
-
|
|
|
|
| 3086 |
|
| 3087 |
*Returns:* `*this`.
|
| 3088 |
|
| 3089 |
``` cpp
|
| 3090 |
int sync();
|
| 3091 |
```
|
| 3092 |
|
| 3093 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3094 |
-
|
| 3095 |
-
|
| 3096 |
-
|
| 3097 |
-
|
| 3098 |
-
|
| 3099 |
-
`setstate(badbit)` (which may throw
|
| 3100 |
`ios_base::failure` ([[iostate.flags]]), and returns `-1`. Otherwise,
|
| 3101 |
returns zero.
|
| 3102 |
|
| 3103 |
``` cpp
|
| 3104 |
pos_type tellg();
|
| 3105 |
```
|
| 3106 |
|
| 3107 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3108 |
-
|
| 3109 |
-
|
| 3110 |
-
|
| 3111 |
|
| 3112 |
*Returns:* After constructing a sentry object, if `fail() != false`,
|
| 3113 |
returns `pos_type(-1)` to indicate failure. Otherwise, returns
|
| 3114 |
`rdbuf()->pubseekoff(0, cur, in)`.
|
| 3115 |
|
| 3116 |
``` cpp
|
| 3117 |
basic_istream<charT, traits>& seekg(pos_type pos);
|
| 3118 |
```
|
| 3119 |
|
| 3120 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3121 |
-
|
| 3122 |
-
|
| 3123 |
-
|
| 3124 |
-
|
| 3125 |
-
|
| 3126 |
-
|
| 3127 |
`ios_base::failure`).
|
| 3128 |
|
| 3129 |
*Returns:* `*this`.
|
| 3130 |
|
| 3131 |
``` cpp
|
| 3132 |
basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
|
| 3133 |
```
|
| 3134 |
|
| 3135 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3136 |
-
|
| 3137 |
-
the number of characters extracted and does not affect the value
|
| 3138 |
returned by subsequent calls to `gcount()`. After constructing a sentry
|
| 3139 |
object, if `fail() != true`, executes
|
| 3140 |
`rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
|
| 3141 |
function calls `setstate(failbit)` (which may throw
|
| 3142 |
`ios_base::failure`).
|
|
@@ -3144,77 +3203,94 @@ function calls `setstate(failbit)` (which may throw
|
|
| 3144 |
*Returns:* `*this`.
|
| 3145 |
|
| 3146 |
#### Standard `basic_istream` manipulators <a id="istream.manip">[[istream.manip]]</a>
|
| 3147 |
|
| 3148 |
``` cpp
|
| 3149 |
-
namespace std {
|
| 3150 |
template <class charT, class traits>
|
| 3151 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 3152 |
-
}
|
| 3153 |
```
|
| 3154 |
|
| 3155 |
-
*Effects:* Behaves as an unformatted input function
|
| 3156 |
-
|
| 3157 |
-
|
| 3158 |
-
|
| 3159 |
-
|
| 3160 |
-
|
| 3161 |
Whitespace characters are distinguished with the same criterion as used
|
| 3162 |
by `sentry::sentry` ([[istream::sentry]]). If `ws` stops extracting
|
| 3163 |
characters because there are no more available it sets `eofbit`, but not
|
| 3164 |
`failbit`.
|
| 3165 |
|
| 3166 |
*Returns:* `is`.
|
| 3167 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3168 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 3169 |
|
| 3170 |
``` cpp
|
| 3171 |
namespace std {
|
| 3172 |
template <class charT, class traits = char_traits<charT>>
|
| 3173 |
-
class basic_iostream
|
| 3174 |
-
public basic_istream<charT,traits>,
|
| 3175 |
public basic_ostream<charT, traits> {
|
| 3176 |
public:
|
| 3177 |
-
|
| 3178 |
-
|
| 3179 |
-
|
| 3180 |
-
|
| 3181 |
-
|
| 3182 |
-
typedef traits traits_type;
|
| 3183 |
|
| 3184 |
-
// constructor
|
| 3185 |
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
|
|
|
|
|
|
| 3186 |
virtual ~basic_iostream();
|
| 3187 |
|
| 3188 |
protected:
|
|
|
|
| 3189 |
basic_iostream(const basic_iostream& rhs) = delete;
|
| 3190 |
basic_iostream(basic_iostream&& rhs);
|
| 3191 |
|
| 3192 |
-
// assign
|
| 3193 |
basic_iostream& operator=(const basic_iostream& rhs) = delete;
|
| 3194 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3195 |
void swap(basic_iostream& rhs);
|
| 3196 |
};
|
| 3197 |
}
|
| 3198 |
```
|
| 3199 |
|
| 3200 |
-
The class `basic_iostream` inherits a number of functions that
|
| 3201 |
-
reading input and writing output to sequences controlled by a
|
| 3202 |
-
buffer.
|
| 3203 |
|
| 3204 |
##### `basic_iostream` constructors <a id="iostream.cons">[[iostream.cons]]</a>
|
| 3205 |
|
| 3206 |
``` cpp
|
| 3207 |
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
| 3208 |
```
|
| 3209 |
|
| 3210 |
-
*Effects:* Constructs an object of class `basic_iostream`,
|
| 3211 |
-
|
| 3212 |
`basic_istream<charT, traits>(sb)` ([[istream]]) and
|
| 3213 |
-
`basic_ostream<charT,traits>(sb)`
|
| 3214 |
|
| 3215 |
-
`rdbuf()==sb` and `gcount()==0`.
|
| 3216 |
|
| 3217 |
``` cpp
|
| 3218 |
basic_iostream(basic_iostream&& rhs);
|
| 3219 |
```
|
| 3220 |
|
|
@@ -3235,30 +3311,18 @@ virtual ~basic_iostream();
|
|
| 3235 |
|
| 3236 |
``` cpp
|
| 3237 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3238 |
```
|
| 3239 |
|
| 3240 |
-
*Effects:* `swap(rhs)`.
|
| 3241 |
|
| 3242 |
``` cpp
|
| 3243 |
void swap(basic_iostream& rhs);
|
| 3244 |
```
|
| 3245 |
|
| 3246 |
*Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
|
| 3247 |
|
| 3248 |
-
#### Rvalue stream extraction <a id="istream.rvalue">[[istream.rvalue]]</a>
|
| 3249 |
-
|
| 3250 |
-
``` cpp
|
| 3251 |
-
template <class charT, class traits, class T>
|
| 3252 |
-
basic_istream<charT, traits>&
|
| 3253 |
-
operator>>(basic_istream<charT, traits>&& is, T& x);
|
| 3254 |
-
```
|
| 3255 |
-
|
| 3256 |
-
*Effects:* `is >>x`
|
| 3257 |
-
|
| 3258 |
-
*Returns:* `is`
|
| 3259 |
-
|
| 3260 |
### Output streams <a id="output.streams">[[output.streams]]</a>
|
| 3261 |
|
| 3262 |
The header `<ostream>` defines a type and several function signatures
|
| 3263 |
that control output to a stream buffer along with a function template
|
| 3264 |
that inserts into stream rvalues.
|
|
@@ -3269,30 +3333,30 @@ that inserts into stream rvalues.
|
|
| 3269 |
namespace std {
|
| 3270 |
template <class charT, class traits = char_traits<charT>>
|
| 3271 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 3272 |
public:
|
| 3273 |
// types (inherited from basic_ios ([ios])):
|
| 3274 |
-
|
| 3275 |
-
|
| 3276 |
-
|
| 3277 |
-
|
| 3278 |
-
|
| 3279 |
|
| 3280 |
-
// [ostream.cons]
|
| 3281 |
explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
|
| 3282 |
virtual ~basic_ostream();
|
| 3283 |
|
| 3284 |
-
// [ostream::sentry]
|
| 3285 |
class sentry;
|
| 3286 |
|
| 3287 |
-
// [ostream.formatted]
|
| 3288 |
-
basic_ostream<charT,traits>&
|
| 3289 |
-
basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&));
|
| 3290 |
-
basic_ostream<charT,traits>&
|
| 3291 |
-
basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
|
| 3292 |
-
basic_ostream<charT,traits>&
|
| 3293 |
-
ios_base& (*pf)(ios_base&));
|
| 3294 |
|
| 3295 |
basic_ostream<charT, traits>& operator<<(bool n);
|
| 3296 |
basic_ostream<charT, traits>& operator<<(short n);
|
| 3297 |
basic_ostream<charT, traits>& operator<<(unsigned short n);
|
| 3298 |
basic_ostream<charT, traits>& operator<<(int n);
|
|
@@ -3304,75 +3368,65 @@ namespace std {
|
|
| 3304 |
basic_ostream<charT, traits>& operator<<(float f);
|
| 3305 |
basic_ostream<charT, traits>& operator<<(double f);
|
| 3306 |
basic_ostream<charT, traits>& operator<<(long double f);
|
| 3307 |
|
| 3308 |
basic_ostream<charT, traits>& operator<<(const void* p);
|
| 3309 |
-
basic_ostream<charT,traits>& operator<<(
|
| 3310 |
-
|
| 3311 |
|
| 3312 |
-
// [ostream.unformatted]
|
| 3313 |
basic_ostream<charT, traits>& put(char_type c);
|
| 3314 |
basic_ostream<charT, traits>& write(const char_type* s, streamsize n);
|
| 3315 |
|
| 3316 |
basic_ostream<charT, traits>& flush();
|
| 3317 |
|
| 3318 |
-
// [ostream.seeks] seeks
|
| 3319 |
pos_type tellp();
|
| 3320 |
basic_ostream<charT, traits>& seekp(pos_type);
|
| 3321 |
basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
|
|
|
|
| 3322 |
protected:
|
|
|
|
| 3323 |
basic_ostream(const basic_ostream& rhs) = delete;
|
| 3324 |
basic_ostream(basic_ostream&& rhs);
|
| 3325 |
|
| 3326 |
-
// [ostream.assign]
|
| 3327 |
basic_ostream& operator=(const basic_ostream& rhs) = delete;
|
| 3328 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3329 |
void swap(basic_ostream& rhs);
|
| 3330 |
};
|
| 3331 |
|
| 3332 |
-
// [ostream.inserters.character] character inserters
|
| 3333 |
template<class charT, class traits>
|
| 3334 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
|
| 3335 |
-
charT);
|
| 3336 |
template<class charT, class traits>
|
| 3337 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
|
| 3338 |
-
char);
|
| 3339 |
template<class traits>
|
| 3340 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
|
| 3341 |
-
char);
|
| 3342 |
|
| 3343 |
-
// signed and unsigned
|
| 3344 |
template<class traits>
|
| 3345 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
|
| 3346 |
-
signed char);
|
| 3347 |
template<class traits>
|
| 3348 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
|
| 3349 |
-
unsigned char);
|
| 3350 |
|
| 3351 |
template<class charT, class traits>
|
| 3352 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
|
| 3353 |
-
const charT*);
|
| 3354 |
template<class charT, class traits>
|
| 3355 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
|
| 3356 |
-
const char*);
|
| 3357 |
template<class traits>
|
| 3358 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
|
| 3359 |
-
const char*);
|
| 3360 |
|
| 3361 |
-
// signed and unsigned
|
| 3362 |
template<class traits>
|
| 3363 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
|
| 3364 |
-
const signed char*);
|
| 3365 |
template<class traits>
|
| 3366 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
|
| 3367 |
-
const unsigned char*);
|
| 3368 |
}
|
| 3369 |
```
|
| 3370 |
|
| 3371 |
-
The class `basic_ostream` defines a number of member function
|
| 3372 |
-
that assist in formatting and writing output to output
|
| 3373 |
-
controlled by a stream buffer.
|
| 3374 |
|
| 3375 |
Two groups of member function signatures share common properties: the
|
| 3376 |
*formatted output functions* (or *inserters*) and the *unformatted
|
| 3377 |
output functions.* Both groups of output functions generate (or
|
| 3378 |
*insert*) output *characters* by actions equivalent to calling
|
|
@@ -3384,45 +3438,55 @@ If one of these called functions throws an exception, then unless
|
|
| 3384 |
explicitly noted otherwise the output function sets `badbit` in error
|
| 3385 |
state. If `badbit` is on in `exceptions()`, the output function rethrows
|
| 3386 |
the exception without completing its actions, otherwise it does not
|
| 3387 |
throw anything and treat as an error.
|
| 3388 |
|
| 3389 |
-
#### `basic_ostream` constructors <a id="ostream.cons">[[ostream.cons]]</a>
|
| 3390 |
|
| 3391 |
``` cpp
|
| 3392 |
explicit basic_ostream(basic_streambuf<charT, traits>* sb);
|
| 3393 |
```
|
| 3394 |
|
| 3395 |
-
``
|
| 3396 |
-
|
| 3397 |
-
``
|
|
|
|
|
|
|
| 3398 |
|
| 3399 |
``` cpp
|
| 3400 |
basic_ostream(basic_ostream&& rhs);
|
| 3401 |
```
|
| 3402 |
|
| 3403 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 3404 |
by default constructing the base class and calling
|
| 3405 |
`basic_ios<charT, traits>::move(rhs)` to initialize the base class.
|
| 3406 |
|
| 3407 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3408 |
|
| 3409 |
``` cpp
|
| 3410 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3411 |
```
|
| 3412 |
|
| 3413 |
-
*Effects:* `swap(rhs)`.
|
| 3414 |
|
| 3415 |
*Returns:* `*this`.
|
| 3416 |
|
| 3417 |
``` cpp
|
| 3418 |
void swap(basic_ostream& rhs);
|
| 3419 |
```
|
| 3420 |
|
| 3421 |
*Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`.
|
| 3422 |
|
| 3423 |
-
#### Class `basic_ostream::sentry` <a id="ostream::sentry">[[ostream::sentry]]</a>
|
| 3424 |
|
| 3425 |
``` cpp
|
| 3426 |
namespace std {
|
| 3427 |
template <class charT, class traits = char_traits<charT>>
|
| 3428 |
class basic_ostream<charT, traits>::sentry {
|
|
@@ -3444,45 +3508,55 @@ exception safe prefix and suffix operations.
|
|
| 3444 |
``` cpp
|
| 3445 |
explicit sentry(basic_ostream<charT, traits>& os);
|
| 3446 |
```
|
| 3447 |
|
| 3448 |
If `os.good()` is nonzero, prepares for formatted or unformatted output.
|
| 3449 |
-
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^
|
| 3450 |
|
| 3451 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 3452 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 3453 |
constructor may call `setstate(failbit)` (which may throw
|
| 3454 |
-
`ios_base::failure` ([[iostate.flags]]))[^
|
| 3455 |
|
| 3456 |
``` cpp
|
| 3457 |
~sentry();
|
| 3458 |
```
|
| 3459 |
|
| 3460 |
If
|
| 3461 |
-
`(
|
| 3462 |
is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1,
|
| 3463 |
sets `badbit` in `os.rdstate()` without propagating an exception.
|
| 3464 |
|
| 3465 |
``` cpp
|
| 3466 |
explicit operator bool() const;
|
| 3467 |
```
|
| 3468 |
|
| 3469 |
*Effects:* Returns `ok_`.
|
| 3470 |
|
| 3471 |
-
#### `basic_ostream` seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
|
| 3472 |
|
| 3473 |
Each seek member function begins execution by constructing an object of
|
| 3474 |
class `sentry`. It returns by destroying the `sentry` object.
|
| 3475 |
|
| 3476 |
``` cpp
|
| 3477 |
pos_type tellp();
|
| 3478 |
```
|
| 3479 |
|
|
|
|
|
|
|
|
|
|
| 3480 |
``` cpp
|
| 3481 |
basic_ostream<charT, traits>& seekp(pos_type pos);
|
| 3482 |
```
|
| 3483 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3484 |
``` cpp
|
| 3485 |
basic_ostream<charT, traits>& seekp(off_type off, ios_base::seekdir dir);
|
| 3486 |
```
|
| 3487 |
|
| 3488 |
*Effects:* If `fail() != true`, executes
|
|
@@ -3500,11 +3574,11 @@ Each formatted output function begins execution by constructing an
|
|
| 3500 |
object of class `sentry`. If this object returns `true` when converted
|
| 3501 |
to a value of type `bool`, the function endeavors to generate the
|
| 3502 |
requested output. If the generation fails, then the formatted output
|
| 3503 |
function does `setstate(ios_base::failbit)`, which might throw an
|
| 3504 |
exception. If an exception is thrown during output, then `ios::badbit`
|
| 3505 |
-
is turned on[^
|
| 3506 |
`(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
|
| 3507 |
not an exception is thrown, the `sentry` object is destroyed before
|
| 3508 |
leaving the formatted output function. If no exception is thrown, the
|
| 3509 |
result of the formatted output function is `*this`.
|
| 3510 |
|
|
@@ -3601,59 +3675,57 @@ bool failed = use_facet<
|
|
| 3601 |
The first argument provides an object of the `ostreambuf_iterator<>`
|
| 3602 |
class which is an iterator for class `basic_ostream<>`. It bypasses
|
| 3603 |
`ostream`s and uses `streambuf`s directly. Class `locale` relies on
|
| 3604 |
these types as its interface to iostreams, since for flexibility it has
|
| 3605 |
been abstracted away from direct dependence on `ostream`. The second
|
| 3606 |
-
parameter is a reference to the base subobject of type `ios_base`.
|
| 3607 |
-
provides formatting specifications such as field width, and a locale
|
| 3608 |
from which to obtain other facets. If `failed` is `true` then does
|
| 3609 |
`setstate(badbit)`, which may throw an exception, and returns.
|
| 3610 |
|
| 3611 |
*Returns:* `*this`.
|
| 3612 |
|
| 3613 |
##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
|
| 3614 |
|
| 3615 |
``` cpp
|
| 3616 |
-
basic_ostream<charT,traits>&
|
| 3617 |
-
|
| 3618 |
```
|
| 3619 |
|
| 3620 |
*Effects:* None. Does not behave as a formatted output function (as
|
| 3621 |
described in [[ostream.formatted.reqmts]]).
|
| 3622 |
|
| 3623 |
-
*Returns:* `pf(*this)`.[^
|
| 3624 |
|
| 3625 |
``` cpp
|
| 3626 |
-
basic_ostream<charT,traits>&
|
| 3627 |
-
|
| 3628 |
```
|
| 3629 |
|
| 3630 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3631 |
formatted output function (as described
|
| 3632 |
in [[ostream.formatted.reqmts]]).
|
| 3633 |
|
| 3634 |
-
*Returns:* `*this`.[^
|
| 3635 |
|
| 3636 |
``` cpp
|
| 3637 |
-
basic_ostream<charT,traits>& operator<<
|
| 3638 |
-
(ios_base& (*pf)(ios_base&));
|
| 3639 |
```
|
| 3640 |
|
| 3641 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3642 |
formatted output function (as described
|
| 3643 |
in [[ostream.formatted.reqmts]]).
|
| 3644 |
|
| 3645 |
*Returns:* `*this`.
|
| 3646 |
|
| 3647 |
``` cpp
|
| 3648 |
-
basic_ostream<charT,traits>& operator<<
|
| 3649 |
-
(basic_streambuf<charT,traits>* sb);
|
| 3650 |
```
|
| 3651 |
|
| 3652 |
-
*Effects:* Behaves as an unformatted output function
|
| 3653 |
-
|
| 3654 |
-
|
| 3655 |
`ios_base::failure`).
|
| 3656 |
|
| 3657 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 3658 |
read from `sb` and inserted until any of the following occurs:
|
| 3659 |
|
|
@@ -3668,55 +3740,58 @@ exception was thrown while extracting a character, the function sets
|
|
| 3668 |
`failbit` in error state, and if `failbit` is on in `exceptions()` the
|
| 3669 |
caught exception is rethrown.
|
| 3670 |
|
| 3671 |
*Returns:* `*this`.
|
| 3672 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3673 |
##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
|
| 3674 |
|
| 3675 |
``` cpp
|
| 3676 |
template<class charT, class traits>
|
| 3677 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
|
| 3678 |
-
charT c);
|
| 3679 |
template<class charT, class traits>
|
| 3680 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
|
| 3681 |
-
char c);
|
| 3682 |
// specialization
|
| 3683 |
template<class traits>
|
| 3684 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
|
| 3685 |
-
char c);
|
| 3686 |
// signed and unsigned
|
| 3687 |
template<class traits>
|
| 3688 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
|
| 3689 |
-
signed char c);
|
| 3690 |
template<class traits>
|
| 3691 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
|
| 3692 |
-
unsigned char c);
|
| 3693 |
```
|
| 3694 |
|
| 3695 |
-
*Effects:* Behaves as a formatted output
|
| 3696 |
-
(
|
| 3697 |
-
sequence `seq`. If `c` has type `char` and the character type
|
| 3698 |
-
stream is not `char`, then `seq` consists of `out.widen(c)`;
|
| 3699 |
-
`seq` consists of `c`. Determines padding for `seq` as
|
| 3700 |
-
in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`.
|
| 3701 |
-
`os.width(0)`.
|
| 3702 |
|
| 3703 |
*Returns:* `out`.
|
| 3704 |
|
| 3705 |
``` cpp
|
| 3706 |
template<class charT, class traits>
|
| 3707 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
|
| 3708 |
-
const charT* s);
|
| 3709 |
template<class charT, class traits>
|
| 3710 |
-
basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
|
| 3711 |
-
const char* s);
|
| 3712 |
template<class traits>
|
| 3713 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
|
| 3714 |
-
const char* s);
|
| 3715 |
template<class traits>
|
| 3716 |
-
basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
|
| 3717 |
-
const signed char* s);
|
| 3718 |
template<class traits>
|
| 3719 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
|
| 3720 |
const unsigned char* s);
|
| 3721 |
```
|
| 3722 |
|
|
@@ -3731,11 +3806,11 @@ would be computed as if by:
|
|
| 3731 |
- `traits::length(s)` for the overload where the first argument is of
|
| 3732 |
type `basic_ostream<charT, traits>&` and the second is of type
|
| 3733 |
`const charT*`, and also for the overload where the first argument is
|
| 3734 |
of type `basic_ostream<char, traits>&` and the second is of type
|
| 3735 |
`const char*`,
|
| 3736 |
-
- `
|
| 3737 |
argument is of type `basic_ostream<charT, traits>&` and the second is
|
| 3738 |
of type `const char*`,
|
| 3739 |
- `traits::length(reinterpret_cast<const char*>(s))` for the other two
|
| 3740 |
overloads.
|
| 3741 |
|
|
@@ -3749,23 +3824,23 @@ in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
|
|
| 3749 |
|
| 3750 |
Each unformatted output function begins execution by constructing an
|
| 3751 |
object of class `sentry`. If this object returns `true`, while
|
| 3752 |
converting to a value of type `bool`, the function endeavors to generate
|
| 3753 |
the requested output. If an exception is thrown during output, then
|
| 3754 |
-
`ios::badbit` is turned on[^
|
| 3755 |
`(exceptions() & badbit) != 0` then the exception is rethrown. In any
|
| 3756 |
case, the unformatted output function ends by destroying the sentry
|
| 3757 |
object, then, if no exception was thrown, returning the value specified
|
| 3758 |
for the unformatted output function.
|
| 3759 |
|
| 3760 |
``` cpp
|
| 3761 |
basic_ostream<charT, traits>& put(char_type c);
|
| 3762 |
```
|
| 3763 |
|
| 3764 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3765 |
-
|
| 3766 |
-
|
| 3767 |
|
| 3768 |
Otherwise, calls `setstate(badbit)` (which may throw
|
| 3769 |
`ios_base::failure` ([[iostate.flags]])).
|
| 3770 |
|
| 3771 |
*Returns:* `*this`.
|
|
@@ -3773,14 +3848,14 @@ Otherwise, calls `setstate(badbit)` (which may throw
|
|
| 3773 |
``` cpp
|
| 3774 |
basic_ostream& write(const char_type* s, streamsize n);
|
| 3775 |
```
|
| 3776 |
|
| 3777 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3778 |
-
|
| 3779 |
-
|
| 3780 |
-
|
| 3781 |
-
|
| 3782 |
|
| 3783 |
- `n` characters are inserted;
|
| 3784 |
- inserting in the output sequence fails (in which case the function
|
| 3785 |
calls `setstate(badbit)`, which may throw
|
| 3786 |
`ios_base::failure` ([[iostate.flags]])).
|
|
@@ -3790,67 +3865,62 @@ inserted until either of the following occurs:
|
|
| 3790 |
``` cpp
|
| 3791 |
basic_ostream& flush();
|
| 3792 |
```
|
| 3793 |
|
| 3794 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3795 |
-
|
| 3796 |
-
|
| 3797 |
-
|
| 3798 |
-
`
|
| 3799 |
-
`setstate(badbit)` (which may throw
|
| 3800 |
`ios_base::failure` ([[iostate.flags]])). Otherwise, if the sentry
|
| 3801 |
object returns `false`, does nothing.
|
| 3802 |
|
| 3803 |
*Returns:* `*this`.
|
| 3804 |
|
| 3805 |
#### Standard `basic_ostream` manipulators <a id="ostream.manip">[[ostream.manip]]</a>
|
| 3806 |
|
| 3807 |
``` cpp
|
| 3808 |
-
namespace std {
|
| 3809 |
template <class charT, class traits>
|
| 3810 |
basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
|
| 3811 |
-
}
|
| 3812 |
```
|
| 3813 |
|
| 3814 |
*Effects:* Calls `os.put(os.widen(’\n’))`, then `os.flush()`.
|
| 3815 |
|
| 3816 |
*Returns:* `os`.
|
| 3817 |
|
| 3818 |
``` cpp
|
| 3819 |
-
namespace std {
|
| 3820 |
template <class charT, class traits>
|
| 3821 |
basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
|
| 3822 |
-
}
|
| 3823 |
```
|
| 3824 |
|
| 3825 |
*Effects:* Inserts a null character into the output sequence: calls
|
| 3826 |
`os.put(charT())`.
|
| 3827 |
|
| 3828 |
*Returns:* `os`.
|
| 3829 |
|
| 3830 |
``` cpp
|
| 3831 |
-
namespace std {
|
| 3832 |
template <class charT, class traits>
|
| 3833 |
basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
|
| 3834 |
-
}
|
| 3835 |
```
|
| 3836 |
|
| 3837 |
*Effects:* Calls `os.flush()`.
|
| 3838 |
|
| 3839 |
*Returns:* `os`.
|
| 3840 |
|
| 3841 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 3842 |
|
| 3843 |
``` cpp
|
| 3844 |
template <class charT, class traits, class T>
|
| 3845 |
-
basic_ostream<charT, traits>&
|
| 3846 |
-
operator<<(basic_ostream<charT, traits>&& os, const T& x);
|
| 3847 |
```
|
| 3848 |
|
| 3849 |
-
*Effects:* `os << x`
|
| 3850 |
|
| 3851 |
-
*Returns:* `os`
|
|
|
|
|
|
|
|
|
|
| 3852 |
|
| 3853 |
### Standard manipulators <a id="std.manip">[[std.manip]]</a>
|
| 3854 |
|
| 3855 |
The header `<iomanip>` defines several functions that support extractors
|
| 3856 |
and inserters that alter information maintained by class `ios_base` and
|
|
@@ -3860,59 +3930,59 @@ its derived classes.
|
|
| 3860 |
unspecified resetiosflags(ios_base::fmtflags mask);
|
| 3861 |
```
|
| 3862 |
|
| 3863 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3864 |
of type `basic_ostream<charT, traits>` then the expression
|
| 3865 |
-
`out <<
|
| 3866 |
if `in` is an object of type `basic_istream<charT, traits>` then the
|
| 3867 |
-
expression `in >>
|
| 3868 |
-
`f(in, mask)`, where the function `f` is defined as:[^
|
| 3869 |
|
| 3870 |
``` cpp
|
| 3871 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 3872 |
// reset specified flags
|
| 3873 |
str.setf(ios_base::fmtflags(0), mask);
|
| 3874 |
}
|
| 3875 |
```
|
| 3876 |
|
| 3877 |
-
The expression `out <<
|
| 3878 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3879 |
-
`in >>
|
| 3880 |
`basic_istream<charT, traits>&` and value `in`.
|
| 3881 |
|
| 3882 |
``` cpp
|
| 3883 |
unspecified setiosflags(ios_base::fmtflags mask);
|
| 3884 |
```
|
| 3885 |
|
| 3886 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3887 |
of type `basic_ostream<charT, traits>` then the expression
|
| 3888 |
-
`out <<
|
| 3889 |
`in` is an object of type `basic_istream<charT, traits>` then the
|
| 3890 |
-
expression `in >>
|
| 3891 |
`f(in, mask)`, where the function `f` is defined as:
|
| 3892 |
|
| 3893 |
``` cpp
|
| 3894 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 3895 |
// set specified flags
|
| 3896 |
str.setf(mask);
|
| 3897 |
}
|
| 3898 |
```
|
| 3899 |
|
| 3900 |
-
The expression `out <<
|
| 3901 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3902 |
-
`in >>
|
| 3903 |
`traits>&` and value `in`.
|
| 3904 |
|
| 3905 |
``` cpp
|
| 3906 |
unspecified setbase(int base);
|
| 3907 |
```
|
| 3908 |
|
| 3909 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3910 |
of type `basic_ostream<charT, traits>` then the expression
|
| 3911 |
-
`out <<
|
| 3912 |
`in` is an object of type `basic_istream<charT, traits>` then the
|
| 3913 |
-
expression `in >>
|
| 3914 |
where the function `f` is defined as:
|
| 3915 |
|
| 3916 |
``` cpp
|
| 3917 |
void f(ios_base& str, int base) {
|
| 3918 |
// set basefield
|
|
@@ -3921,79 +3991,79 @@ void f(ios_base& str, int base) {
|
|
| 3921 |
base == 16 ? ios_base::hex :
|
| 3922 |
ios_base::fmtflags(0), ios_base::basefield);
|
| 3923 |
}
|
| 3924 |
```
|
| 3925 |
|
| 3926 |
-
The expression `out <<
|
| 3927 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3928 |
-
`in >>
|
| 3929 |
and value `in`.
|
| 3930 |
|
| 3931 |
``` cpp
|
| 3932 |
unspecified setfill(char_type c);
|
| 3933 |
```
|
| 3934 |
|
| 3935 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3936 |
of type `basic_ostream<charT, traits>` and `c` has type `charT` then the
|
| 3937 |
-
expression `out <<
|
| 3938 |
where the function `f` is defined as:
|
| 3939 |
|
| 3940 |
``` cpp
|
| 3941 |
template<class charT, class traits>
|
| 3942 |
void f(basic_ios<charT, traits>& str, charT c) {
|
| 3943 |
// set fill character
|
| 3944 |
str.fill(c);
|
| 3945 |
}
|
| 3946 |
```
|
| 3947 |
|
| 3948 |
-
The expression `out <<
|
| 3949 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 3950 |
|
| 3951 |
``` cpp
|
| 3952 |
unspecified setprecision(int n);
|
| 3953 |
```
|
| 3954 |
|
| 3955 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3956 |
of type `basic_ostream<charT, traits>` then the expression
|
| 3957 |
-
`out <<
|
| 3958 |
is an object of type `basic_istream<charT, traits>` then the expression
|
| 3959 |
-
`in >>
|
| 3960 |
function `f` is defined as:
|
| 3961 |
|
| 3962 |
``` cpp
|
| 3963 |
void f(ios_base& str, int n) {
|
| 3964 |
// set precision
|
| 3965 |
str.precision(n);
|
| 3966 |
}
|
| 3967 |
```
|
| 3968 |
|
| 3969 |
-
The expression `out <<
|
| 3970 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3971 |
-
`in >>
|
| 3972 |
and value `in`.
|
| 3973 |
|
| 3974 |
``` cpp
|
| 3975 |
unspecified setw(int n);
|
| 3976 |
```
|
| 3977 |
|
| 3978 |
*Returns:* An object of unspecified type such that if `out` is an
|
| 3979 |
instance of `basic_ostream<charT, traits>` then the expression
|
| 3980 |
-
`out <<
|
| 3981 |
object of type `basic_istream<charT, traits>` then the expression
|
| 3982 |
-
`in >>
|
| 3983 |
`f` is defined as:
|
| 3984 |
|
| 3985 |
``` cpp
|
| 3986 |
void f(ios_base& str, int n) {
|
| 3987 |
// set width
|
| 3988 |
str.width(n);
|
| 3989 |
}
|
| 3990 |
```
|
| 3991 |
|
| 3992 |
-
The expression `out <<
|
| 3993 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3994 |
-
`in >>
|
| 3995 |
value `in`.
|
| 3996 |
|
| 3997 |
### Extended manipulators <a id="ext.manip">[[ext.manip]]</a>
|
| 3998 |
|
| 3999 |
The header `<iomanip>` defines several functions that support extractors
|
|
@@ -4010,18 +4080,18 @@ specialization of the `basic_string` template (Clause [[strings]]).
|
|
| 4010 |
*Effects:* The expression `in >> get_money(mon, intl)` described below
|
| 4011 |
behaves as a formatted input function ([[istream.formatted.reqmts]]).
|
| 4012 |
|
| 4013 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4014 |
of type `basic_istream<charT, traits>` then the expression
|
| 4015 |
-
`in >>
|
| 4016 |
where the function `f` is defined as:
|
| 4017 |
|
| 4018 |
``` cpp
|
| 4019 |
template <class charT, class traits, class moneyT>
|
| 4020 |
void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
|
| 4021 |
-
|
| 4022 |
-
|
| 4023 |
|
| 4024 |
ios_base::iostate err = ios_base::goodbit;
|
| 4025 |
const MoneyGet& mg = use_facet<MoneyGet>(str.getloc());
|
| 4026 |
|
| 4027 |
mg.get(Iter(str.rdbuf()), Iter(), intl, str, err, mon);
|
|
@@ -4029,11 +4099,11 @@ void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
|
|
| 4029 |
if (ios_base::goodbit != err)
|
| 4030 |
str.setstate(err);
|
| 4031 |
}
|
| 4032 |
```
|
| 4033 |
|
| 4034 |
-
The expression `in >>
|
| 4035 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4036 |
|
| 4037 |
``` cpp
|
| 4038 |
template <class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
|
| 4039 |
```
|
|
@@ -4041,62 +4111,63 @@ template <class moneyT> unspecified put_money(const moneyT& mon, bool intl = fal
|
|
| 4041 |
*Requires:* The type `moneyT` shall be either `long double` or a
|
| 4042 |
specialization of the `basic_string` template (Clause [[strings]]).
|
| 4043 |
|
| 4044 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4045 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4046 |
-
`out <<
|
| 4047 |
-
calls `f(out, mon, intl)`,
|
|
|
|
| 4048 |
|
| 4049 |
``` cpp
|
| 4050 |
template <class charT, class traits, class moneyT>
|
| 4051 |
void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
|
| 4052 |
-
|
| 4053 |
-
|
| 4054 |
|
| 4055 |
const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
|
| 4056 |
const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);
|
| 4057 |
|
| 4058 |
if (end.failed())
|
| 4059 |
str.setstate(ios::badbit);
|
| 4060 |
}
|
| 4061 |
```
|
| 4062 |
|
| 4063 |
-
The expression `out <<
|
| 4064 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4065 |
|
| 4066 |
``` cpp
|
| 4067 |
template <class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
|
| 4068 |
```
|
| 4069 |
|
| 4070 |
*Requires:* The argument `tmb` shall be a valid pointer to an object of
|
| 4071 |
-
type `struct tm`
|
| 4072 |
array of objects of type `charT` with `char_traits<charT>::length(fmt)`
|
| 4073 |
elements.
|
| 4074 |
|
| 4075 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4076 |
of type `basic_istream<charT, traits>` then the expression
|
| 4077 |
-
`in >>
|
| 4078 |
where the function `f` is defined as:
|
| 4079 |
|
| 4080 |
``` cpp
|
| 4081 |
template <class charT, class traits>
|
| 4082 |
void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
|
| 4083 |
-
|
| 4084 |
-
|
| 4085 |
|
| 4086 |
ios_base::iostate err = ios_base::goodbit;
|
| 4087 |
const TimeGet& tg = use_facet<TimeGet>(str.getloc());
|
| 4088 |
|
| 4089 |
tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
|
| 4090 |
fmt, fmt + traits::length(fmt));
|
| 4091 |
|
| 4092 |
if (err != ios_base::goodbit)
|
| 4093 |
-
str.setstate(err)
|
| 4094 |
}
|
| 4095 |
```
|
| 4096 |
|
| 4097 |
-
The expression `in >>
|
| 4098 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4099 |
|
| 4100 |
``` cpp
|
| 4101 |
template <class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
|
| 4102 |
```
|
|
@@ -4106,51 +4177,55 @@ type `struct tm`, and the argument `fmt` shall be a valid pointer to an
|
|
| 4106 |
array of objects of type `charT` with `char_traits<charT>::length(fmt)`
|
| 4107 |
elements.
|
| 4108 |
|
| 4109 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4110 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4111 |
-
`out <<
|
| 4112 |
where the function `f` is defined as:
|
| 4113 |
|
| 4114 |
``` cpp
|
| 4115 |
template <class charT, class traits>
|
| 4116 |
void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
|
| 4117 |
-
|
| 4118 |
-
|
| 4119 |
|
| 4120 |
const TimePut& tp = use_facet<TimePut>(str.getloc());
|
| 4121 |
const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
|
| 4122 |
fmt, fmt + traits::length(fmt));
|
| 4123 |
|
| 4124 |
if (end.failed())
|
| 4125 |
str.setstate(ios_base::badbit);
|
| 4126 |
}
|
| 4127 |
```
|
| 4128 |
|
| 4129 |
-
The expression `out <<
|
| 4130 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4131 |
|
| 4132 |
### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
|
| 4133 |
|
| 4134 |
-
Quoted manipulators provide string insertion and extraction
|
| 4135 |
-
strings (for example, XML and CSV formats). Quoted
|
| 4136 |
-
useful in ensuring that the content of a string with
|
| 4137 |
-
remains unchanged if inserted and then extracted via
|
|
|
|
| 4138 |
|
| 4139 |
``` cpp
|
| 4140 |
template <class charT>
|
| 4141 |
unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
|
| 4142 |
template <class charT, class traits, class Allocator>
|
| 4143 |
unspecified quoted(const basic_string<charT, traits, Allocator>& s,
|
| 4144 |
-
|
|
|
|
|
|
|
|
|
|
| 4145 |
```
|
| 4146 |
|
| 4147 |
*Returns:* An object of unspecified type such that if `out` is an
|
| 4148 |
instance of `basic_ostream` with member type `char_type` the same as
|
| 4149 |
-
`charT` and with member type `traits_type`, which in the second
|
| 4150 |
-
the same as `traits`, then the expression
|
| 4151 |
-
`out <<
|
| 4152 |
function ([[ostream.formatted.reqmts]]) of `out`. This forms a
|
| 4153 |
character sequence `seq`, initially consisting of the following
|
| 4154 |
elements:
|
| 4155 |
|
| 4156 |
- `delim`.
|
|
@@ -4161,135 +4236,134 @@ elements:
|
|
| 4161 |
|
| 4162 |
Let `x` be the number of elements initially in `seq`. Then padding is
|
| 4163 |
determined for `seq` as described in [[ostream.formatted.reqmts]],
|
| 4164 |
`seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
|
| 4165 |
`n` is the larger of `out.width()` and `x`, and `out.width(0)` is
|
| 4166 |
-
called. The expression `out <<
|
| 4167 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4168 |
|
| 4169 |
``` cpp
|
| 4170 |
template <class charT, class traits, class Allocator>
|
| 4171 |
unspecified quoted(basic_string<charT, traits, Allocator>& s,
|
| 4172 |
-
|
| 4173 |
```
|
| 4174 |
|
| 4175 |
*Returns:* An object of unspecified type such that:
|
| 4176 |
|
| 4177 |
- If `in` is an instance of `basic_istream` with member types
|
| 4178 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4179 |
-
respectively, then the expression `in >>
|
| 4180 |
behaves as if it extracts the following characters from `in` using
|
| 4181 |
-
`
|
| 4182 |
-
`ios_base::failure` ([[ios::failure]]):
|
| 4183 |
- If the first character extracted is equal to `delim`, as determined
|
| 4184 |
by `traits_type::eq`, then:
|
| 4185 |
- Turn off the `skipws` flag.
|
| 4186 |
- `s.clear()`
|
| 4187 |
- Until an unescaped `delim` character is reached or `!in`, extract
|
| 4188 |
characters from `in` and append them to `s`, except that if an
|
| 4189 |
`escape` is reached, ignore it and append the next character to
|
| 4190 |
`s`.
|
| 4191 |
- Discard the final `delim` character.
|
| 4192 |
- Restore the `skipws` flag to its original value.
|
| 4193 |
-
- Otherwise, `in >>
|
| 4194 |
- If `out` is an instance of `basic_ostream` with member types
|
| 4195 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4196 |
-
respectively, then the expression `out <<
|
| 4197 |
behaves as specified for the
|
| 4198 |
`const basic_string<charT, traits, Allocator>&` overload of the
|
| 4199 |
`quoted` function.
|
| 4200 |
|
| 4201 |
-
The expression `in >>
|
| 4202 |
`basic_istream<charT, traits>&` and value `in`. The expression
|
| 4203 |
-
`out <<
|
| 4204 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4205 |
|
| 4206 |
## String-based streams <a id="string.streams">[[string.streams]]</a>
|
| 4207 |
|
| 4208 |
-
###
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4209 |
|
| 4210 |
The header `<sstream>` defines four class templates and eight types that
|
| 4211 |
associate stream buffers with objects of class `basic_string`, as
|
| 4212 |
described in [[string.classes]].
|
| 4213 |
|
| 4214 |
-
``` cpp
|
| 4215 |
-
namespace std {
|
| 4216 |
-
template <class charT, class traits = char_traits<charT>,
|
| 4217 |
-
class Allocator = allocator<charT> >
|
| 4218 |
-
class basic_stringbuf;
|
| 4219 |
-
|
| 4220 |
-
typedef basic_stringbuf<char> stringbuf;
|
| 4221 |
-
typedef basic_stringbuf<wchar_t> wstringbuf;
|
| 4222 |
-
|
| 4223 |
-
template <class charT, class traits = char_traits<charT>,
|
| 4224 |
-
class Allocator = allocator<charT> >
|
| 4225 |
-
class basic_istringstream;
|
| 4226 |
-
|
| 4227 |
-
typedef basic_istringstream<char> istringstream;
|
| 4228 |
-
typedef basic_istringstream<wchar_t> wistringstream;
|
| 4229 |
-
|
| 4230 |
-
template <class charT, class traits = char_traits<charT>,
|
| 4231 |
-
class Allocator = allocator<charT> >
|
| 4232 |
-
class basic_ostringstream;
|
| 4233 |
-
typedef basic_ostringstream<char> ostringstream;
|
| 4234 |
-
typedef basic_ostringstream<wchar_t> wostringstream;
|
| 4235 |
-
|
| 4236 |
-
template <class charT, class traits = char_traits<charT>,
|
| 4237 |
-
class Allocator = allocator<charT> >
|
| 4238 |
-
class basic_stringstream;
|
| 4239 |
-
typedef basic_stringstream<char> stringstream;
|
| 4240 |
-
typedef basic_stringstream<wchar_t> wstringstream;
|
| 4241 |
-
}
|
| 4242 |
-
```
|
| 4243 |
-
|
| 4244 |
### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
|
| 4245 |
|
| 4246 |
``` cpp
|
| 4247 |
namespace std {
|
| 4248 |
template <class charT, class traits = char_traits<charT>,
|
| 4249 |
class Allocator = allocator<charT>>
|
| 4250 |
class basic_stringbuf : public basic_streambuf<charT, traits> {
|
| 4251 |
public:
|
| 4252 |
-
|
| 4253 |
-
|
| 4254 |
-
|
| 4255 |
-
|
| 4256 |
-
|
| 4257 |
-
|
| 4258 |
|
| 4259 |
-
// [stringbuf.cons]
|
| 4260 |
-
explicit basic_stringbuf(
|
| 4261 |
-
|
| 4262 |
-
explicit basic_stringbuf
|
| 4263 |
-
|
| 4264 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4265 |
basic_stringbuf(const basic_stringbuf& rhs) = delete;
|
| 4266 |
basic_stringbuf(basic_stringbuf&& rhs);
|
| 4267 |
|
| 4268 |
-
// [stringbuf.assign]
|
| 4269 |
basic_stringbuf& operator=(const basic_stringbuf& rhs) = delete;
|
| 4270 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4271 |
void swap(basic_stringbuf& rhs);
|
| 4272 |
|
| 4273 |
-
// [stringbuf.members]
|
| 4274 |
basic_string<charT, traits, Allocator> str() const;
|
| 4275 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4276 |
|
| 4277 |
protected:
|
| 4278 |
-
// [stringbuf.virtuals]
|
| 4279 |
-
|
| 4280 |
-
|
| 4281 |
-
|
| 4282 |
-
|
| 4283 |
|
| 4284 |
-
|
| 4285 |
-
virtual pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 4286 |
ios_base::openmode which
|
| 4287 |
-
|
| 4288 |
-
|
| 4289 |
ios_base::openmode which
|
| 4290 |
-
|
| 4291 |
|
| 4292 |
private:
|
| 4293 |
ios_base::openmode mode; // exposition only
|
| 4294 |
};
|
| 4295 |
|
|
@@ -4311,22 +4385,23 @@ For the sake of exposition, the maintained data is presented here as:
|
|
| 4311 |
read, and `out` set if the output sequence can be written.
|
| 4312 |
|
| 4313 |
#### `basic_stringbuf` constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
|
| 4314 |
|
| 4315 |
``` cpp
|
| 4316 |
-
explicit basic_stringbuf(
|
| 4317 |
-
|
| 4318 |
```
|
| 4319 |
|
| 4320 |
*Effects:* Constructs an object of class `basic_stringbuf`, initializing
|
| 4321 |
the base class with `basic_streambuf()` ([[streambuf.cons]]), and
|
| 4322 |
initializing `mode` with `which`.
|
| 4323 |
|
| 4324 |
-
`str() == ""`.
|
| 4325 |
|
| 4326 |
``` cpp
|
| 4327 |
-
explicit basic_stringbuf(
|
|
|
|
| 4328 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4329 |
```
|
| 4330 |
|
| 4331 |
*Effects:* Constructs an object of class `basic_stringbuf`, initializing
|
| 4332 |
the base class with `basic_streambuf()` ([[streambuf.cons]]), and
|
|
@@ -4381,11 +4456,11 @@ void swap(basic_stringbuf& rhs);
|
|
| 4381 |
template <class charT, class traits, class Allocator>
|
| 4382 |
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4383 |
basic_stringbuf<charT, traits, Allocator>& y);
|
| 4384 |
```
|
| 4385 |
|
| 4386 |
-
*Effects:* `x.swap(y)`.
|
| 4387 |
|
| 4388 |
#### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
|
| 4389 |
|
| 4390 |
``` cpp
|
| 4391 |
basic_string<charT, traits, Allocator> str() const;
|
|
@@ -4394,11 +4469,11 @@ basic_string<charT,traits,Allocator> str() const;
|
|
| 4394 |
*Returns:* A `basic_string` object whose content is equal to the
|
| 4395 |
`basic_stringbuf` underlying character sequence. If the
|
| 4396 |
`basic_stringbuf` was created only in input mode, the resultant
|
| 4397 |
`basic_string` contains the character sequence in the range \[`eback()`,
|
| 4398 |
`egptr()`). If the `basic_stringbuf` was created with
|
| 4399 |
-
`which & ios_base::out` being
|
| 4400 |
contains the character sequence in the range \[`pbase()`, `high_mark`),
|
| 4401 |
where `high_mark` represents the position one past the highest
|
| 4402 |
initialized character in the buffer. Characters can be initialized by
|
| 4403 |
writing to the stream, by constructing the `basic_stringbuf` with a
|
| 4404 |
`basic_string`, or by calling the `str(basic_string)` member function.
|
|
@@ -4415,31 +4490,31 @@ void str(const basic_string<charT,traits,Allocator>& s);
|
|
| 4415 |
|
| 4416 |
*Effects:* Copies the content of `s` into the `basic_stringbuf`
|
| 4417 |
underlying character sequence and initializes the input and output
|
| 4418 |
sequences according to `mode`.
|
| 4419 |
|
| 4420 |
-
*Postconditions:* If `mode & ios_base::out` is
|
| 4421 |
-
the first underlying character and `epptr()` `>= pbase() + s.size()`
|
| 4422 |
-
holds; in addition, if `mode & ios_base::ate` is
|
| 4423 |
`pptr() == pbase() + s.size()` holds, otherwise `pptr() == pbase()` is
|
| 4424 |
-
true. If `mode & ios_base::in` is
|
| 4425 |
-
underlying character, and both `gptr() == eback()` and
|
| 4426 |
`egptr() == eback() + s.size()` hold.
|
| 4427 |
|
| 4428 |
#### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
|
| 4429 |
|
| 4430 |
``` cpp
|
| 4431 |
-
int_type underflow();
|
| 4432 |
```
|
| 4433 |
|
| 4434 |
*Returns:* If the input sequence has a read position available, returns
|
| 4435 |
`traits::to_int_type(*gptr())`. Otherwise, returns `traits::eof()`. Any
|
| 4436 |
character in the underlying buffer which has been initialized is
|
| 4437 |
considered to be part of the input sequence.
|
| 4438 |
|
| 4439 |
``` cpp
|
| 4440 |
-
int_type pbackfail(int_type c = traits::eof());
|
| 4441 |
```
|
| 4442 |
|
| 4443 |
*Effects:* Puts back the character designated by `c` to the input
|
| 4444 |
sequence, if possible, in one of three ways:
|
| 4445 |
|
|
@@ -4458,11 +4533,11 @@ sequence, if possible, in one of three ways:
|
|
| 4458 |
|
| 4459 |
*Remarks:* If the function can succeed in more than one of these ways,
|
| 4460 |
it is unspecified which way is chosen.
|
| 4461 |
|
| 4462 |
``` cpp
|
| 4463 |
-
int_type overflow(int_type c = traits::eof());
|
| 4464 |
```
|
| 4465 |
|
| 4466 |
*Effects:* Appends the character designated by `c` to the output
|
| 4467 |
sequence, if possible, in one of two ways:
|
| 4468 |
|
|
@@ -4488,11 +4563,11 @@ plus at least one additional write position. If
|
|
| 4488 |
`egptr()` to point just past the new write position.
|
| 4489 |
|
| 4490 |
``` cpp
|
| 4491 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 4492 |
ios_base::openmode which
|
| 4493 |
-
= ios_base::in | ios_base::out);
|
| 4494 |
```
|
| 4495 |
|
| 4496 |
*Effects:* Alters the stream position within one of the controlled
|
| 4497 |
sequences, if possible, as indicated in
|
| 4498 |
Table [[tab:iostreams.seekoff.positioning]].
|
|
@@ -4520,23 +4595,24 @@ as indicated in Table [[tab:iostreams.newoff.values]].
|
|
| 4520 |
| `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
|
| 4521 |
| `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
|
| 4522 |
|
| 4523 |
|
| 4524 |
If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
|
| 4525 |
-
character (
|
| 4526 |
-
|
| 4527 |
-
|
| 4528 |
|
| 4529 |
*Returns:* `pos_type(newoff)`, constructed from the resultant offset
|
| 4530 |
`newoff` (of type `off_type`), that stores the resultant stream
|
| 4531 |
position, if possible. If the positioning operation fails, or if the
|
| 4532 |
constructed object cannot represent the resultant stream position, the
|
| 4533 |
return value is `pos_type(off_type(-1))`.
|
| 4534 |
|
| 4535 |
``` cpp
|
| 4536 |
-
pos_type seekpos(pos_type sp,
|
| 4537 |
-
|
|
|
|
| 4538 |
```
|
| 4539 |
|
| 4540 |
*Effects:* Equivalent to `seekoff(off_type(sp), ios_base::beg, which)`.
|
| 4541 |
|
| 4542 |
*Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
|
|
@@ -4557,31 +4633,32 @@ effect.
|
|
| 4557 |
namespace std {
|
| 4558 |
template <class charT, class traits = char_traits<charT>,
|
| 4559 |
class Allocator = allocator<charT>>
|
| 4560 |
class basic_istringstream : public basic_istream<charT, traits> {
|
| 4561 |
public:
|
| 4562 |
-
|
| 4563 |
-
|
| 4564 |
-
|
| 4565 |
-
|
| 4566 |
-
|
| 4567 |
-
|
| 4568 |
|
| 4569 |
-
// [istringstream.cons]
|
| 4570 |
-
explicit basic_istringstream(
|
|
|
|
| 4571 |
explicit basic_istringstream(
|
| 4572 |
const basic_string<charT, traits, Allocator>& str,
|
| 4573 |
ios_base::openmode which = ios_base::in);
|
| 4574 |
basic_istringstream(const basic_istringstream& rhs) = delete;
|
| 4575 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4576 |
|
| 4577 |
-
// [istringstream.assign]
|
| 4578 |
basic_istringstream& operator=(const basic_istringstream& rhs) = delete;
|
| 4579 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
| 4580 |
void swap(basic_istringstream& rhs);
|
| 4581 |
|
| 4582 |
-
// [istringstream.members]
|
| 4583 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4584 |
|
| 4585 |
basic_string<charT, traits, Allocator> str() const;
|
| 4586 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4587 |
private:
|
|
@@ -4628,12 +4705,12 @@ explicit basic_istringstream(
|
|
| 4628 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4629 |
```
|
| 4630 |
|
| 4631 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4632 |
by move constructing the base class, and the contained
|
| 4633 |
-
`basic_stringbuf`. Next `basic_istream<charT,traits>::set_rdbuf(&sb)`
|
| 4634 |
-
called to install the contained `basic_stringbuf`.
|
| 4635 |
|
| 4636 |
#### Assign and swap <a id="istringstream.assign">[[istringstream.assign]]</a>
|
| 4637 |
|
| 4638 |
``` cpp
|
| 4639 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
|
@@ -4655,19 +4732,20 @@ void swap(basic_istringstream& rhs);
|
|
| 4655 |
template <class charT, class traits, class Allocator>
|
| 4656 |
void swap(basic_istringstream<charT, traits, Allocator>& x,
|
| 4657 |
basic_istringstream<charT, traits, Allocator>& y);
|
| 4658 |
```
|
| 4659 |
|
| 4660 |
-
*Effects:* `x.swap(y)`.
|
| 4661 |
|
| 4662 |
#### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
|
| 4663 |
|
| 4664 |
``` cpp
|
| 4665 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4666 |
```
|
| 4667 |
|
| 4668 |
-
*Returns:*
|
|
|
|
| 4669 |
|
| 4670 |
``` cpp
|
| 4671 |
basic_string<charT, traits, Allocator> str() const;
|
| 4672 |
```
|
| 4673 |
|
|
@@ -4685,33 +4763,32 @@ void str(const basic_string<charT,traits,Allocator>& s);
|
|
| 4685 |
namespace std {
|
| 4686 |
template <class charT, class traits = char_traits<charT>,
|
| 4687 |
class Allocator = allocator<charT>>
|
| 4688 |
class basic_ostringstream : public basic_ostream<charT, traits> {
|
| 4689 |
public:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4690 |
|
| 4691 |
-
//
|
| 4692 |
-
|
| 4693 |
-
|
| 4694 |
-
typedef typename traits::pos_type pos_type;
|
| 4695 |
-
typedef typename traits::off_type off_type;
|
| 4696 |
-
typedef traits traits_type;
|
| 4697 |
-
typedef Allocator allocator_type;
|
| 4698 |
-
|
| 4699 |
-
// [ostringstream.cons] Constructors/destructor:
|
| 4700 |
-
explicit basic_ostringstream(ios_base::openmode which = ios_base::out);
|
| 4701 |
explicit basic_ostringstream(
|
| 4702 |
const basic_string<charT, traits, Allocator>& str,
|
| 4703 |
ios_base::openmode which = ios_base::out);
|
| 4704 |
basic_ostringstream(const basic_ostringstream& rhs) = delete;
|
| 4705 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 4706 |
|
| 4707 |
-
// [ostringstream.assign]
|
| 4708 |
basic_ostringstream& operator=(const basic_ostringstream& rhs) = delete;
|
| 4709 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
| 4710 |
void swap(basic_ostringstream& rhs);
|
| 4711 |
|
| 4712 |
-
// [ostringstream.members]
|
| 4713 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4714 |
|
| 4715 |
basic_string<charT, traits, Allocator> str() const;
|
| 4716 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4717 |
private:
|
|
@@ -4732,11 +4809,12 @@ the sake of exposition, the maintained data is presented here as:
|
|
| 4732 |
- `sb`, the `stringbuf` object.
|
| 4733 |
|
| 4734 |
#### `basic_ostringstream` constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
|
| 4735 |
|
| 4736 |
``` cpp
|
| 4737 |
-
explicit basic_ostringstream(
|
|
|
|
| 4738 |
```
|
| 4739 |
|
| 4740 |
*Effects:* Constructs an object of class `basic_ostringstream`,
|
| 4741 |
initializing the base class with `basic_ostream(&sb)` and initializing
|
| 4742 |
`sb` with
|
|
@@ -4757,12 +4835,12 @@ explicit basic_ostringstream(
|
|
| 4757 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 4758 |
```
|
| 4759 |
|
| 4760 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4761 |
by move constructing the base class, and the contained
|
| 4762 |
-
`basic_stringbuf`. Next `basic_ostream<charT,traits>::set_rdbuf(&sb)`
|
| 4763 |
-
called to install the contained `basic_stringbuf`.
|
| 4764 |
|
| 4765 |
#### Assign and swap <a id="ostringstream.assign">[[ostringstream.assign]]</a>
|
| 4766 |
|
| 4767 |
``` cpp
|
| 4768 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
|
@@ -4784,19 +4862,20 @@ void swap(basic_ostringstream& rhs);
|
|
| 4784 |
template <class charT, class traits, class Allocator>
|
| 4785 |
void swap(basic_ostringstream<charT, traits, Allocator>& x,
|
| 4786 |
basic_ostringstream<charT, traits, Allocator>& y);
|
| 4787 |
```
|
| 4788 |
|
| 4789 |
-
*Effects:* `x.swap(y)`.
|
| 4790 |
|
| 4791 |
#### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
|
| 4792 |
|
| 4793 |
``` cpp
|
| 4794 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4795 |
```
|
| 4796 |
|
| 4797 |
-
*Returns:*
|
|
|
|
| 4798 |
|
| 4799 |
``` cpp
|
| 4800 |
basic_string<charT, traits, Allocator> str() const;
|
| 4801 |
```
|
| 4802 |
|
|
@@ -4812,37 +4891,34 @@ void str(const basic_string<charT,traits,Allocator>& s);
|
|
| 4812 |
|
| 4813 |
``` cpp
|
| 4814 |
namespace std {
|
| 4815 |
template <class charT, class traits = char_traits<charT>,
|
| 4816 |
class Allocator = allocator<charT>>
|
| 4817 |
-
class basic_stringstream
|
| 4818 |
-
: public basic_iostream<charT,traits> {
|
| 4819 |
public:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4820 |
|
| 4821 |
-
//
|
| 4822 |
-
typedef charT char_type;
|
| 4823 |
-
typedef typename traits::int_type int_type;
|
| 4824 |
-
typedef typename traits::pos_type pos_type;
|
| 4825 |
-
typedef typename traits::off_type off_type;
|
| 4826 |
-
typedef traits traits_type;
|
| 4827 |
-
typedef Allocator allocator_type;
|
| 4828 |
-
|
| 4829 |
-
// constructors/destructor
|
| 4830 |
explicit basic_stringstream(
|
| 4831 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4832 |
explicit basic_stringstream(
|
| 4833 |
const basic_string<charT, traits, Allocator>& str,
|
| 4834 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4835 |
basic_stringstream(const basic_stringstream& rhs) = delete;
|
| 4836 |
basic_stringstream(basic_stringstream&& rhs);
|
| 4837 |
|
| 4838 |
-
// [stringstream.assign]
|
| 4839 |
basic_stringstream& operator=(const basic_stringstream& rhs) = delete;
|
| 4840 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
| 4841 |
void swap(basic_stringstream& rhs);
|
| 4842 |
|
| 4843 |
-
//
|
| 4844 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4845 |
basic_string<charT, traits, Allocator> str() const;
|
| 4846 |
void str(const basic_string<charT, traits, Allocator>& str);
|
| 4847 |
|
| 4848 |
private:
|
|
@@ -4862,11 +4938,11 @@ and writing from objects of class
|
|
| 4862 |
associated sequence. For the sake of exposition, the maintained data is
|
| 4863 |
presented here as
|
| 4864 |
|
| 4865 |
- `sb`, the `stringbuf` object.
|
| 4866 |
|
| 4867 |
-
#### basic_stringstream constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
|
| 4868 |
|
| 4869 |
``` cpp
|
| 4870 |
explicit basic_stringstream(
|
| 4871 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4872 |
```
|
|
@@ -4891,12 +4967,12 @@ explicit basic_stringstream(
|
|
| 4891 |
basic_stringstream(basic_stringstream&& rhs);
|
| 4892 |
```
|
| 4893 |
|
| 4894 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4895 |
by move constructing the base class, and the contained
|
| 4896 |
-
`basic_stringbuf`. Next `basic_istream<charT,traits>::set_rdbuf(&sb)`
|
| 4897 |
-
called to install the contained `basic_stringbuf`.
|
| 4898 |
|
| 4899 |
#### Assign and swap <a id="stringstream.assign">[[stringstream.assign]]</a>
|
| 4900 |
|
| 4901 |
``` cpp
|
| 4902 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
|
@@ -4918,11 +4994,11 @@ void swap(basic_stringstream& rhs);
|
|
| 4918 |
template <class charT, class traits, class Allocator>
|
| 4919 |
void swap(basic_stringstream<charT, traits, Allocator>& x,
|
| 4920 |
basic_stringstream<charT, traits, Allocator>& y);
|
| 4921 |
```
|
| 4922 |
|
| 4923 |
-
*Effects:* `x.swap(y)`.
|
| 4924 |
|
| 4925 |
#### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
|
| 4926 |
|
| 4927 |
``` cpp
|
| 4928 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
|
@@ -4942,96 +5018,106 @@ void str(const basic_string<charT,traits,Allocator>& str);
|
|
| 4942 |
|
| 4943 |
*Effects:* Calls `rdbuf()->str(str)`.
|
| 4944 |
|
| 4945 |
## File-based streams <a id="file.streams">[[file.streams]]</a>
|
| 4946 |
|
| 4947 |
-
###
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4948 |
|
| 4949 |
The header `<fstream>` defines four class templates and eight types that
|
| 4950 |
associate stream buffers with files and assist reading and writing
|
| 4951 |
files.
|
| 4952 |
|
| 4953 |
-
``
|
| 4954 |
-
|
| 4955 |
-
|
| 4956 |
-
|
| 4957 |
-
|
| 4958 |
-
typedef basic_filebuf<wchar_t> wfilebuf;
|
| 4959 |
|
| 4960 |
-
|
| 4961 |
-
|
| 4962 |
-
|
| 4963 |
-
typedef basic_ifstream<wchar_t> wifstream;
|
| 4964 |
|
| 4965 |
-
|
| 4966 |
-
|
| 4967 |
-
typedef basic_ofstream<char> ofstream;
|
| 4968 |
-
typedef basic_ofstream<wchar_t> wofstream;
|
| 4969 |
|
| 4970 |
-
|
| 4971 |
-
class basic_fstream;
|
| 4972 |
-
typedef basic_fstream<char> fstream;
|
| 4973 |
-
typedef basic_fstream<wchar_t> wfstream;
|
| 4974 |
-
}
|
| 4975 |
-
```
|
| 4976 |
-
|
| 4977 |
-
In this subclause, the type name `FILE` refers to the type `FILE`
|
| 4978 |
-
declared in `<cstdio>` ([[c.files]]).
|
| 4979 |
-
|
| 4980 |
-
The class template `basic_filebuf` treats a file as a source or sink of
|
| 4981 |
-
bytes. In an environment that uses a large character set, the file
|
| 4982 |
-
typically holds multibyte character sequences and the `basic_filebuf`
|
| 4983 |
-
object converts those multibyte sequences into wide character sequences.
|
| 4984 |
-
|
| 4985 |
-
#### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
|
| 4986 |
|
| 4987 |
``` cpp
|
| 4988 |
namespace std {
|
| 4989 |
template <class charT, class traits = char_traits<charT>>
|
| 4990 |
class basic_filebuf : public basic_streambuf<charT, traits> {
|
| 4991 |
public:
|
| 4992 |
-
|
| 4993 |
-
|
| 4994 |
-
|
| 4995 |
-
|
| 4996 |
-
|
| 4997 |
|
| 4998 |
-
// [filebuf.cons]
|
| 4999 |
basic_filebuf();
|
| 5000 |
basic_filebuf(const basic_filebuf& rhs) = delete;
|
| 5001 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5002 |
virtual ~basic_filebuf();
|
| 5003 |
|
| 5004 |
-
// [filebuf.assign]
|
| 5005 |
basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
|
| 5006 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5007 |
void swap(basic_filebuf& rhs);
|
| 5008 |
|
| 5009 |
-
|
| 5010 |
bool is_open() const;
|
| 5011 |
-
basic_filebuf
|
|
|
|
|
|
|
|
|
|
| 5012 |
ios_base::openmode mode);
|
| 5013 |
-
basic_filebuf
|
| 5014 |
ios_base::openmode mode);
|
| 5015 |
-
basic_filebuf
|
| 5016 |
|
| 5017 |
protected:
|
| 5018 |
-
// [filebuf.virtuals]
|
| 5019 |
-
|
| 5020 |
-
|
| 5021 |
-
|
| 5022 |
-
|
| 5023 |
-
|
| 5024 |
|
| 5025 |
-
|
| 5026 |
-
|
| 5027 |
-
|
| 5028 |
-
|
| 5029 |
-
|
| 5030 |
-
|
| 5031 |
-
|
| 5032 |
-
|
|
|
|
|
|
|
| 5033 |
};
|
| 5034 |
|
| 5035 |
template <class charT, class traits>
|
| 5036 |
void swap(basic_filebuf<charT, traits>& x,
|
| 5037 |
basic_filebuf<charT, traits>& y);
|
|
@@ -5041,23 +5127,23 @@ namespace std {
|
|
| 5041 |
The class `basic_filebuf<charT, traits>` associates both the input
|
| 5042 |
sequence and the output sequence with a file.
|
| 5043 |
|
| 5044 |
The restrictions on reading and writing a sequence controlled by an
|
| 5045 |
object of class `basic_filebuf<charT, traits>` are the same as for
|
| 5046 |
-
reading and writing with the
|
| 5047 |
|
| 5048 |
In particular:
|
| 5049 |
|
| 5050 |
- If the file is not open for reading the input sequence cannot be read.
|
| 5051 |
- If the file is not open for writing the output sequence cannot be
|
| 5052 |
written.
|
| 5053 |
- A joint file position is maintained for both the input sequence and
|
| 5054 |
the output sequence.
|
| 5055 |
|
| 5056 |
An instance of `basic_filebuf` behaves as described in [[filebuf]]
|
| 5057 |
-
provided `traits::pos_type` is `fpos<traits::state_type>`. Otherwise
|
| 5058 |
-
behavior is undefined.
|
| 5059 |
|
| 5060 |
In order to support file I/O and multibyte/wide character conversion,
|
| 5061 |
conversions are performed using members of a facet, referred to as
|
| 5062 |
`a_codecvt` in following sections, obtained as if by
|
| 5063 |
|
|
@@ -5074,11 +5160,11 @@ basic_filebuf();
|
|
| 5074 |
|
| 5075 |
*Effects:* Constructs an object of class `basic_filebuf<charT, traits>`,
|
| 5076 |
initializing the base class with
|
| 5077 |
`basic_streambuf<charT, traits>()` ([[streambuf.cons]]).
|
| 5078 |
|
| 5079 |
-
`is_open() == false`.
|
| 5080 |
|
| 5081 |
``` cpp
|
| 5082 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5083 |
```
|
| 5084 |
|
|
@@ -5121,13 +5207,13 @@ rethrown (see [[res.on.exception.handling]]).
|
|
| 5121 |
|
| 5122 |
``` cpp
|
| 5123 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5124 |
```
|
| 5125 |
|
| 5126 |
-
*Effects:* Calls `
|
| 5127 |
-
|
| 5128 |
-
|
| 5129 |
|
| 5130 |
*Returns:* `*this`.
|
| 5131 |
|
| 5132 |
``` cpp
|
| 5133 |
void swap(basic_filebuf& rhs);
|
|
@@ -5139,11 +5225,11 @@ void swap(basic_filebuf& rhs);
|
|
| 5139 |
template <class charT, class traits>
|
| 5140 |
void swap(basic_filebuf<charT, traits>& x,
|
| 5141 |
basic_filebuf<charT, traits>& y);
|
| 5142 |
```
|
| 5143 |
|
| 5144 |
-
*Effects:* `x.swap(y)`.
|
| 5145 |
|
| 5146 |
#### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
|
| 5147 |
|
| 5148 |
``` cpp
|
| 5149 |
bool is_open() const;
|
|
@@ -5151,18 +5237,19 @@ bool is_open() const;
|
|
| 5151 |
|
| 5152 |
*Returns:* `true` if a previous call to `open` succeeded (returned a
|
| 5153 |
non-null value) and there has been no intervening call to close.
|
| 5154 |
|
| 5155 |
``` cpp
|
| 5156 |
-
basic_filebuf
|
| 5157 |
-
|
|
|
|
| 5158 |
```
|
| 5159 |
|
| 5160 |
*Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
|
| 5161 |
initializes the `filebuf` as required. It then opens a file, if
|
| 5162 |
possible, whose name is the NTBS`s` (as if by calling
|
| 5163 |
-
`
|
| 5164 |
`mode & ~ios_base::ate` as indicated in
|
| 5165 |
Table [[tab:iostreams.file.open.modes]]. If `mode` is not some
|
| 5166 |
combination of flags shown in the table then the open fails.
|
| 5167 |
|
| 5168 |
**Table: File open modes** <a id="tab:iostreams.file.open.modes">[tab:iostreams.file.open.modes]</a>
|
|
@@ -5188,67 +5275,67 @@ combination of flags shown in the table then the open fails.
|
|
| 5188 |
| + | + | | | + | `"a+b"` |
|
| 5189 |
|
| 5190 |
|
| 5191 |
If the open operation succeeds and `(mode & ios_base::ate) != 0`,
|
| 5192 |
positions the file to the end (as if by calling
|
| 5193 |
-
`
|
| 5194 |
|
| 5195 |
If the repositioning operation fails, calls `close()` and returns a null
|
| 5196 |
pointer to indicate failure.
|
| 5197 |
|
| 5198 |
*Returns:* `this` if successful, a null pointer otherwise.
|
| 5199 |
|
| 5200 |
``` cpp
|
| 5201 |
-
basic_filebuf
|
| 5202 |
-
|
| 5203 |
```
|
| 5204 |
|
| 5205 |
*Returns:* `open(s.c_str(), mode);`
|
| 5206 |
|
| 5207 |
``` cpp
|
| 5208 |
-
basic_filebuf
|
| 5209 |
```
|
| 5210 |
|
| 5211 |
*Effects:* If `is_open() == false`, returns a null pointer. If a put
|
| 5212 |
area exists, calls `overflow(traits::eof())` to flush characters. If the
|
| 5213 |
last virtual member function called on `*this` (between `underflow`,
|
| 5214 |
`overflow`, `seekoff`, and `seekpos`) was `overflow` then calls
|
| 5215 |
`a_codecvt.unshift` (possibly several times) to determine a termination
|
| 5216 |
sequence, inserts those characters and calls `overflow(traits::eof())`
|
| 5217 |
again. Finally, regardless of whether any of the preceding calls fails
|
| 5218 |
or throws an exception, the function closes the file (as if by calling
|
| 5219 |
-
`
|
| 5220 |
-
|
| 5221 |
-
|
| 5222 |
-
|
| 5223 |
|
| 5224 |
*Returns:* `this` on success, a null pointer otherwise.
|
| 5225 |
|
| 5226 |
-
`is_open() == false`.
|
| 5227 |
|
| 5228 |
#### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
|
| 5229 |
|
| 5230 |
``` cpp
|
| 5231 |
-
streamsize showmanyc();
|
| 5232 |
```
|
| 5233 |
|
| 5234 |
*Effects:* Behaves the same as
|
| 5235 |
`basic_streambuf::showmanyc()` ([[streambuf.virtuals]]).
|
| 5236 |
|
| 5237 |
*Remarks:* An implementation might well provide an overriding definition
|
| 5238 |
for this function signature if it can determine that more characters can
|
| 5239 |
be read from the input sequence.
|
| 5240 |
|
| 5241 |
``` cpp
|
| 5242 |
-
int_type underflow();
|
| 5243 |
```
|
| 5244 |
|
| 5245 |
*Effects:* Behaves according to the description of
|
| 5246 |
`basic_streambuf<charT, traits>::underflow()`, with the specialization
|
| 5247 |
that a sequence of characters is read from the input sequence as if by
|
| 5248 |
reading from the associated file into an internal buffer (`extern_buf`)
|
| 5249 |
-
and then as if by doing
|
| 5250 |
|
| 5251 |
``` cpp
|
| 5252 |
char extern_buf[XSIZE];
|
| 5253 |
char* extern_end;
|
| 5254 |
charT intern_buf[ISIZE];
|
|
@@ -5262,20 +5349,20 @@ This shall be done in such a way that the class can recover the position
|
|
| 5262 |
(`fpos_t`) corresponding to each character between `intern_buf` and
|
| 5263 |
`intern_end`. If the value of `r` indicates that `a_codecvt.in()` ran
|
| 5264 |
out of space in `intern_buf`, retry with a larger `intern_buf`.
|
| 5265 |
|
| 5266 |
``` cpp
|
| 5267 |
-
int_type uflow();
|
| 5268 |
```
|
| 5269 |
|
| 5270 |
*Effects:* Behaves according to the description of
|
| 5271 |
-
`basic_streambuf<charT,traits>::uflow()`, with the specialization that
|
| 5272 |
-
sequence of characters is read from the input with the same method as
|
| 5273 |
used by `underflow`.
|
| 5274 |
|
| 5275 |
``` cpp
|
| 5276 |
-
int_type pbackfail(int_type c = traits::eof());
|
| 5277 |
```
|
| 5278 |
|
| 5279 |
*Effects:* Puts back the character designated by `c` to the input
|
| 5280 |
sequence, if possible, in one of three ways:
|
| 5281 |
|
|
@@ -5303,11 +5390,11 @@ sequence.
|
|
| 5303 |
If the function can succeed in more than one of these ways, it is
|
| 5304 |
unspecified which way is chosen. The function can alter the number of
|
| 5305 |
putback positions available as a result of any call.
|
| 5306 |
|
| 5307 |
``` cpp
|
| 5308 |
-
int_type overflow(int_type c = traits::eof());
|
| 5309 |
```
|
| 5310 |
|
| 5311 |
*Effects:* Behaves according to the description of
|
| 5312 |
`basic_streambuf<charT, traits>::overflow(c)`, except that the behavior
|
| 5313 |
of “consuming characters” is performed by first converting as if by:
|
|
@@ -5336,31 +5423,32 @@ and then
|
|
| 5336 |
|
| 5337 |
*Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
|
| 5338 |
to indicate failure. If `is_open() == false`, the function always fails.
|
| 5339 |
|
| 5340 |
``` cpp
|
| 5341 |
-
basic_streambuf* setbuf(char_type* s, streamsize n);
|
| 5342 |
```
|
| 5343 |
|
| 5344 |
*Effects:* If `setbuf(0, 0)` is called on a stream before any I/O has
|
| 5345 |
occurred on that stream, the stream becomes unbuffered. Otherwise the
|
| 5346 |
results are *implementation-defined*. “Unbuffered” means that `pbase()`
|
| 5347 |
and `pptr()` always return null and output to the file should appear as
|
| 5348 |
soon as possible.
|
| 5349 |
|
| 5350 |
``` cpp
|
| 5351 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 5352 |
-
|
|
|
|
| 5353 |
```
|
| 5354 |
|
| 5355 |
*Effects:* Let `width` denote `a_codecvt.encoding()`. If
|
| 5356 |
`is_open() == false`, or `off != 0 && width <= 0`, then the positioning
|
| 5357 |
operation fails. Otherwise, if `way != basic_ios::cur` or `off != 0`,
|
| 5358 |
and if the last operation was output, then update the output sequence
|
| 5359 |
and write any unshift sequence. Next, seek to the new position: if
|
| 5360 |
-
`width > 0`, call `
|
| 5361 |
-
|
| 5362 |
|
| 5363 |
*Remarks:* “The last operation was output” means either the last virtual
|
| 5364 |
operation was overflow or the put buffer is non-empty. “Write any
|
| 5365 |
unshift sequence” means, if `width` if less than zero then call
|
| 5366 |
`a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
|
|
@@ -5382,90 +5470,99 @@ resultant stream position, if possible. If the positioning operation
|
|
| 5382 |
fails, or if the object cannot represent the resultant stream position,
|
| 5383 |
returns `pos_type(off_type(-1))`.
|
| 5384 |
|
| 5385 |
``` cpp
|
| 5386 |
pos_type seekpos(pos_type sp,
|
| 5387 |
-
|
|
|
|
| 5388 |
```
|
| 5389 |
|
| 5390 |
Alters the file position, if possible, to correspond to the position
|
| 5391 |
stored in `sp` (as described below). Altering the file position performs
|
| 5392 |
as follows:
|
| 5393 |
|
| 5394 |
1. if `(om & ios_base::out) != 0`, then update the output sequence and
|
| 5395 |
write any unshift sequence;
|
| 5396 |
-
2. set the file position to `sp`;
|
| 5397 |
3. if `(om & ios_base::in) != 0`, then update the input sequence;
|
| 5398 |
|
| 5399 |
where `om` is the open mode passed to the last call to `open()`. The
|
| 5400 |
-
operation fails if `is_open()` returns false.
|
| 5401 |
|
| 5402 |
If `sp` is an invalid stream position, or if the function positions
|
| 5403 |
neither sequence, the positioning operation fails. If `sp` has not been
|
| 5404 |
obtained by a previous successful call to one of the positioning
|
| 5405 |
functions (`seekoff` or `seekpos`) on the same file the effects are
|
| 5406 |
undefined.
|
| 5407 |
|
| 5408 |
*Returns:* `sp` on success. Otherwise returns `pos_type(off_type(-1))`.
|
| 5409 |
|
| 5410 |
``` cpp
|
| 5411 |
-
int sync();
|
| 5412 |
```
|
| 5413 |
|
| 5414 |
*Effects:* If a put area exists, calls `filebuf::overflow` to write the
|
| 5415 |
-
characters to the file
|
|
|
|
| 5416 |
*implementation-defined*.
|
| 5417 |
|
| 5418 |
``` cpp
|
| 5419 |
-
void imbue(const locale& loc);
|
| 5420 |
```
|
| 5421 |
|
| 5422 |
-
If the file is not positioned at its beginning and the
|
| 5423 |
-
current locale as determined by `a_codecvt.encoding()`
|
| 5424 |
-
state-dependent ([[locale.codecvt.virtuals]]) then that facet is the
|
| 5425 |
same as the corresponding facet of `loc`.
|
| 5426 |
|
| 5427 |
*Effects:* Causes characters inserted or extracted after this call to be
|
| 5428 |
converted according to `loc` until another call of `imbue`.
|
| 5429 |
|
| 5430 |
-
This may require reconversion of previously converted
|
| 5431 |
-
in turn may require the implementation to be able to
|
| 5432 |
-
original contents of the file.
|
| 5433 |
|
| 5434 |
-
###
|
| 5435 |
|
| 5436 |
``` cpp
|
| 5437 |
namespace std {
|
| 5438 |
template <class charT, class traits = char_traits<charT>>
|
| 5439 |
class basic_ifstream : public basic_istream<charT, traits> {
|
| 5440 |
public:
|
| 5441 |
-
|
| 5442 |
-
|
| 5443 |
-
|
| 5444 |
-
|
| 5445 |
-
|
| 5446 |
|
| 5447 |
-
// [ifstream.cons]
|
| 5448 |
basic_ifstream();
|
| 5449 |
explicit basic_ifstream(const char* s,
|
| 5450 |
ios_base::openmode mode = ios_base::in);
|
|
|
|
|
|
|
| 5451 |
explicit basic_ifstream(const string& s,
|
| 5452 |
ios_base::openmode mode = ios_base::in);
|
|
|
|
|
|
|
| 5453 |
basic_ifstream(const basic_ifstream& rhs) = delete;
|
| 5454 |
basic_ifstream(basic_ifstream&& rhs);
|
| 5455 |
|
| 5456 |
-
// [ifstream.assign]
|
| 5457 |
basic_ifstream& operator=(const basic_ifstream& rhs) = delete;
|
| 5458 |
basic_ifstream& operator=(basic_ifstream&& rhs);
|
| 5459 |
void swap(basic_ifstream& rhs);
|
| 5460 |
|
| 5461 |
-
// [ifstream.members]
|
| 5462 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5463 |
|
| 5464 |
bool is_open() const;
|
| 5465 |
void open(const char* s, ios_base::openmode mode = ios_base::in);
|
|
|
|
|
|
|
| 5466 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
|
|
|
| 5467 |
void close();
|
| 5468 |
private:
|
| 5469 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 5470 |
};
|
| 5471 |
|
|
@@ -5486,18 +5583,20 @@ presented here as:
|
|
| 5486 |
|
| 5487 |
``` cpp
|
| 5488 |
basic_ifstream();
|
| 5489 |
```
|
| 5490 |
|
| 5491 |
-
*Effects:* Constructs an object of class
|
| 5492 |
-
initializing the base class with
|
| 5493 |
-
`sb`
|
| 5494 |
-
[[filebuf.cons]]).
|
| 5495 |
|
| 5496 |
``` cpp
|
| 5497 |
explicit basic_ifstream(const char* s,
|
| 5498 |
ios_base::openmode mode = ios_base::in);
|
|
|
|
|
|
|
| 5499 |
```
|
| 5500 |
|
| 5501 |
*Effects:* Constructs an object of class `basic_ifstream`, initializing
|
| 5502 |
the base class with `basic_istream(&sb)` and initializing `sb` with
|
| 5503 |
`basic_filebuf<charT, traits>())` ([[istream.cons]], [[filebuf.cons]]),
|
|
@@ -5505,13 +5604,15 @@ then calls `rdbuf()->open(s, mode | ios_base::in)`. If that function
|
|
| 5505 |
returns a null pointer, calls `setstate(failbit)`.
|
| 5506 |
|
| 5507 |
``` cpp
|
| 5508 |
explicit basic_ifstream(const string& s,
|
| 5509 |
ios_base::openmode mode = ios_base::in);
|
|
|
|
|
|
|
| 5510 |
```
|
| 5511 |
|
| 5512 |
-
*Effects:*
|
| 5513 |
|
| 5514 |
``` cpp
|
| 5515 |
basic_ifstream(basic_ifstream&& rhs);
|
| 5516 |
```
|
| 5517 |
|
|
@@ -5542,11 +5643,11 @@ void swap(basic_ifstream& rhs);
|
|
| 5542 |
template <class charT, class traits>
|
| 5543 |
void swap(basic_ifstream<charT, traits>& x,
|
| 5544 |
basic_ifstream<charT, traits>& y);
|
| 5545 |
```
|
| 5546 |
|
| 5547 |
-
*Effects:* `x.swap(y)`.
|
| 5548 |
|
| 5549 |
#### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
|
| 5550 |
|
| 5551 |
``` cpp
|
| 5552 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
@@ -5560,64 +5661,74 @@ bool is_open() const;
|
|
| 5560 |
|
| 5561 |
*Returns:* `rdbuf()->is_open()`.
|
| 5562 |
|
| 5563 |
``` cpp
|
| 5564 |
void open(const char* s, ios_base::openmode mode = ios_base::in);
|
|
|
|
|
|
|
| 5565 |
```
|
| 5566 |
|
| 5567 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::in)`. If that
|
| 5568 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 5569 |
-
`setstate(failbit)` (which may throw `ios_base::failure`
|
| 5570 |
-
([[iostate.flags]])
|
| 5571 |
|
| 5572 |
``` cpp
|
| 5573 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
|
|
|
| 5574 |
```
|
| 5575 |
|
| 5576 |
-
*Effects:*
|
| 5577 |
|
| 5578 |
``` cpp
|
| 5579 |
void close();
|
| 5580 |
```
|
| 5581 |
|
| 5582 |
*Effects:* Calls `rdbuf()->close()` and, if that function returns a null
|
| 5583 |
pointer, calls `setstate(failbit)` (which may throw
|
| 5584 |
-
`ios_base::failure` ([[iostate.flags]])
|
| 5585 |
|
| 5586 |
-
###
|
| 5587 |
|
| 5588 |
``` cpp
|
| 5589 |
namespace std {
|
| 5590 |
template <class charT, class traits = char_traits<charT>>
|
| 5591 |
class basic_ofstream : public basic_ostream<charT, traits> {
|
| 5592 |
public:
|
| 5593 |
-
|
| 5594 |
-
|
| 5595 |
-
|
| 5596 |
-
|
| 5597 |
-
|
| 5598 |
|
| 5599 |
-
// [ofstream.cons]
|
| 5600 |
basic_ofstream();
|
| 5601 |
explicit basic_ofstream(const char* s,
|
| 5602 |
ios_base::openmode mode = ios_base::out);
|
|
|
|
|
|
|
| 5603 |
explicit basic_ofstream(const string& s,
|
| 5604 |
ios_base::openmode mode = ios_base::out);
|
|
|
|
|
|
|
| 5605 |
basic_ofstream(const basic_ofstream& rhs) = delete;
|
| 5606 |
basic_ofstream(basic_ofstream&& rhs);
|
| 5607 |
|
| 5608 |
-
// [ofstream.assign]
|
| 5609 |
basic_ofstream& operator=(const basic_ofstream& rhs) = delete;
|
| 5610 |
basic_ofstream& operator=(basic_ofstream&& rhs);
|
| 5611 |
void swap(basic_ofstream& rhs);
|
| 5612 |
|
| 5613 |
-
// [ofstream.members]
|
| 5614 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5615 |
|
| 5616 |
bool is_open() const;
|
| 5617 |
void open(const char* s, ios_base::openmode mode = ios_base::out);
|
|
|
|
|
|
|
| 5618 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
|
|
|
| 5619 |
void close();
|
| 5620 |
private:
|
| 5621 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 5622 |
};
|
| 5623 |
|
|
@@ -5638,32 +5749,37 @@ presented here as:
|
|
| 5638 |
|
| 5639 |
``` cpp
|
| 5640 |
basic_ofstream();
|
| 5641 |
```
|
| 5642 |
|
| 5643 |
-
*Effects:* Constructs an object of class
|
| 5644 |
-
initializing the base class with
|
| 5645 |
-
`sb`
|
| 5646 |
-
[[filebuf.cons]]).
|
| 5647 |
|
| 5648 |
``` cpp
|
| 5649 |
explicit basic_ofstream(const char* s,
|
| 5650 |
ios_base::openmode mode = ios_base::out);
|
|
|
|
|
|
|
| 5651 |
```
|
| 5652 |
|
| 5653 |
-
*Effects:* Constructs an object of class
|
| 5654 |
-
initializing the base class with
|
| 5655 |
-
`sb`
|
| 5656 |
-
[[
|
| 5657 |
-
|
|
|
|
| 5658 |
|
| 5659 |
``` cpp
|
| 5660 |
explicit basic_ofstream(const string& s,
|
| 5661 |
ios_base::openmode mode = ios_base::out);
|
|
|
|
|
|
|
| 5662 |
```
|
| 5663 |
|
| 5664 |
-
*Effects:*
|
| 5665 |
|
| 5666 |
``` cpp
|
| 5667 |
basic_ofstream(basic_ofstream&& rhs);
|
| 5668 |
```
|
| 5669 |
|
|
@@ -5694,11 +5810,11 @@ void swap(basic_ofstream& rhs);
|
|
| 5694 |
template <class charT, class traits>
|
| 5695 |
void swap(basic_ofstream<charT, traits>& x,
|
| 5696 |
basic_ofstream<charT, traits>& y);
|
| 5697 |
```
|
| 5698 |
|
| 5699 |
-
*Effects:* `x.swap(y)`.
|
| 5700 |
|
| 5701 |
#### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
|
| 5702 |
|
| 5703 |
``` cpp
|
| 5704 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
@@ -5712,66 +5828,83 @@ bool is_open() const;
|
|
| 5712 |
|
| 5713 |
*Returns:* `rdbuf()->is_open()`.
|
| 5714 |
|
| 5715 |
``` cpp
|
| 5716 |
void open(const char* s, ios_base::openmode mode = ios_base::out);
|
|
|
|
|
|
|
| 5717 |
```
|
| 5718 |
|
| 5719 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::out)`. If that
|
| 5720 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 5721 |
-
`setstate(failbit)` (which may throw `ios_base::failure`
|
| 5722 |
-
([[iostate.flags]])
|
| 5723 |
|
| 5724 |
``` cpp
|
| 5725 |
void close();
|
| 5726 |
```
|
| 5727 |
|
| 5728 |
*Effects:* Calls `rdbuf()->close()` and, if that function fails (returns
|
| 5729 |
a null pointer), calls `setstate(failbit)` (which may throw
|
| 5730 |
-
`ios_base::failure` ([[iostate.flags]])
|
| 5731 |
|
| 5732 |
``` cpp
|
| 5733 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
|
|
|
| 5734 |
```
|
| 5735 |
|
| 5736 |
-
*Effects:*
|
| 5737 |
|
| 5738 |
-
###
|
| 5739 |
|
| 5740 |
``` cpp
|
| 5741 |
namespace std {
|
| 5742 |
template <class charT, class traits = char_traits<charT>>
|
| 5743 |
-
class basic_fstream
|
| 5744 |
-
: public basic_iostream<charT,traits> {
|
| 5745 |
-
|
| 5746 |
public:
|
| 5747 |
-
|
| 5748 |
-
|
| 5749 |
-
|
| 5750 |
-
|
| 5751 |
-
|
| 5752 |
|
| 5753 |
-
// constructors
|
| 5754 |
basic_fstream();
|
| 5755 |
-
explicit basic_fstream(
|
|
|
|
| 5756 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5757 |
-
explicit basic_fstream(
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5758 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5759 |
basic_fstream(const basic_fstream& rhs) = delete;
|
| 5760 |
basic_fstream(basic_fstream&& rhs);
|
| 5761 |
|
| 5762 |
-
// [fstream.assign]
|
| 5763 |
basic_fstream& operator=(const basic_fstream& rhs) = delete;
|
| 5764 |
basic_fstream& operator=(basic_fstream&& rhs);
|
| 5765 |
void swap(basic_fstream& rhs);
|
| 5766 |
|
| 5767 |
-
//
|
| 5768 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5769 |
bool is_open() const;
|
| 5770 |
-
void open(
|
|
|
|
| 5771 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5772 |
-
void open(
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5773 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5774 |
void close();
|
| 5775 |
|
| 5776 |
private:
|
| 5777 |
basic_filebuf<charT, traits> sb; // exposition only
|
|
@@ -5782,13 +5915,13 @@ namespace std {
|
|
| 5782 |
basic_fstream<charT, traits>& y);
|
| 5783 |
}
|
| 5784 |
```
|
| 5785 |
|
| 5786 |
The class template `basic_fstream<charT, traits>` supports reading and
|
| 5787 |
-
writing from named files. It uses a `basic_filebuf<charT,traits>`
|
| 5788 |
-
to control the associated sequences. For the sake of exposition,
|
| 5789 |
-
maintained data is presented here as:
|
| 5790 |
|
| 5791 |
- `sb`, the `basic_filebuf` object.
|
| 5792 |
|
| 5793 |
#### `basic_fstream` constructors <a id="fstream.cons">[[fstream.cons]]</a>
|
| 5794 |
|
|
@@ -5799,26 +5932,34 @@ basic_fstream();
|
|
| 5799 |
*Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
|
| 5800 |
initializing the base class with `basic_iostream(&sb)` and initializing
|
| 5801 |
`sb` with `basic_filebuf<charT, traits>()`.
|
| 5802 |
|
| 5803 |
``` cpp
|
| 5804 |
-
explicit basic_fstream(
|
|
|
|
| 5805 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
|
|
|
|
|
|
|
|
|
| 5806 |
```
|
| 5807 |
|
| 5808 |
*Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
|
| 5809 |
initializing the base class with `basic_iostream(&sb)` and initializing
|
| 5810 |
`sb` with `basic_filebuf<charT, traits>()`. Then calls
|
| 5811 |
`rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
|
| 5812 |
`setstate(failbit)`.
|
| 5813 |
|
| 5814 |
``` cpp
|
| 5815 |
-
explicit basic_fstream(
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5816 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5817 |
```
|
| 5818 |
|
| 5819 |
-
*Effects:*
|
| 5820 |
|
| 5821 |
``` cpp
|
| 5822 |
basic_fstream(basic_fstream&& rhs);
|
| 5823 |
```
|
| 5824 |
|
|
@@ -5849,11 +5990,11 @@ void swap(basic_fstream& rhs);
|
|
| 5849 |
template <class charT, class traits>
|
| 5850 |
void swap(basic_fstream<charT, traits>& x,
|
| 5851 |
basic_fstream<charT, traits>& y);
|
| 5852 |
```
|
| 5853 |
|
| 5854 |
-
*Effects:* `x.swap(y)`.
|
| 5855 |
|
| 5856 |
#### Member functions <a id="fstream.members">[[fstream.members]]</a>
|
| 5857 |
|
| 5858 |
``` cpp
|
| 5859 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
@@ -5866,54 +6007,4248 @@ bool is_open() const;
|
|
| 5866 |
```
|
| 5867 |
|
| 5868 |
*Returns:* `rdbuf()->is_open()`.
|
| 5869 |
|
| 5870 |
``` cpp
|
| 5871 |
-
void open(
|
|
|
|
| 5872 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
|
|
|
|
|
|
|
|
|
| 5873 |
```
|
| 5874 |
|
| 5875 |
*Effects:* Calls `rdbuf()->open(s, mode)`. If that function does not
|
| 5876 |
return a null pointer calls `clear()`, otherwise calls
|
| 5877 |
-
`setstate(failbit)`
|
| 5878 |
`ios_base::failure`) ([[iostate.flags]]).
|
| 5879 |
|
| 5880 |
``` cpp
|
| 5881 |
-
void open(
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5882 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5883 |
```
|
| 5884 |
|
| 5885 |
-
*Effects:*
|
| 5886 |
|
| 5887 |
``` cpp
|
| 5888 |
void close();
|
| 5889 |
```
|
| 5890 |
|
| 5891 |
-
*Effects:* Calls `rdbuf()->close()` and, if that function returns
|
| 5892 |
-
|
| 5893 |
-
|
| 5894 |
|
| 5895 |
-
##
|
| 5896 |
|
| 5897 |
-
|
| 5898 |
-
not define the function `gets`.
|
| 5899 |
|
| 5900 |
-
|
| 5901 |
-
|
| 5902 |
-
an argument of `NULL`.
|
| 5903 |
|
| 5904 |
-
|
| 5905 |
|
| 5906 |
-
|
| 5907 |
-
|
| 5908 |
-
|
| 5909 |
-
of the C standard, plays no role in C++.
|
| 5910 |
|
| 5911 |
-
|
| 5912 |
-
Library header `<inttypes.h>`, with the following changes:
|
| 5913 |
|
| 5914 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5915 |
`<stdint.h>`, and
|
| 5916 |
- if and only if the type `intmax_t` designates an extended integer
|
| 5917 |
type ([[basic.fundamental]]), the following function signatures are
|
| 5918 |
added:
|
| 5919 |
``` cpp
|
|
@@ -5923,97 +10258,220 @@ Library header `<inttypes.h>`, with the following changes:
|
|
| 5923 |
|
| 5924 |
which shall have the same semantics as the function signatures
|
| 5925 |
`intmax_t imaxabs(intmax_t)` and
|
| 5926 |
`imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
|
| 5927 |
|
|
|
|
|
|
|
| 5928 |
<!-- Link reference definitions -->
|
| 5929 |
[adjustfield.manip]: #adjustfield.manip
|
|
|
|
| 5930 |
[basefield.manip]: #basefield.manip
|
| 5931 |
[basic.fundamental]: basic.md#basic.fundamental
|
| 5932 |
[basic.ios.cons]: #basic.ios.cons
|
| 5933 |
[basic.ios.members]: #basic.ios.members
|
|
|
|
|
|
|
| 5934 |
[bitmask.types]: library.md#bitmask.types
|
| 5935 |
[c.files]: #c.files
|
|
|
|
|
|
|
|
|
|
| 5936 |
[enumerated.types]: library.md#enumerated.types
|
| 5937 |
[error.reporting]: #error.reporting
|
| 5938 |
[ext.manip]: #ext.manip
|
| 5939 |
[fig:streampos]: #fig:streampos
|
| 5940 |
[file.streams]: #file.streams
|
| 5941 |
[filebuf]: #filebuf
|
| 5942 |
[filebuf.assign]: #filebuf.assign
|
| 5943 |
[filebuf.cons]: #filebuf.cons
|
| 5944 |
[filebuf.members]: #filebuf.members
|
| 5945 |
[filebuf.virtuals]: #filebuf.virtuals
|
|
|
|
|
|
|
| 5946 |
[floatfield.manip]: #floatfield.manip
|
| 5947 |
[fmtflags.manip]: #fmtflags.manip
|
| 5948 |
[fmtflags.state]: #fmtflags.state
|
| 5949 |
[fpos]: #fpos
|
| 5950 |
[fpos.members]: #fpos.members
|
| 5951 |
[fpos.operations]: #fpos.operations
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5952 |
[fstream]: #fstream
|
| 5953 |
[fstream.assign]: #fstream.assign
|
| 5954 |
[fstream.cons]: #fstream.cons
|
| 5955 |
[fstream.members]: #fstream.members
|
| 5956 |
-
[
|
| 5957 |
[ifstream]: #ifstream
|
| 5958 |
[ifstream.assign]: #ifstream.assign
|
| 5959 |
[ifstream.cons]: #ifstream.cons
|
| 5960 |
[ifstream.members]: #ifstream.members
|
|
|
|
| 5961 |
[input.output]: #input.output
|
| 5962 |
[input.output.general]: #input.output.general
|
| 5963 |
[input.streams]: #input.streams
|
| 5964 |
[intro.multithread]: intro.md#intro.multithread
|
|
|
|
| 5965 |
[ios]: #ios
|
| 5966 |
[ios.base]: #ios.base
|
| 5967 |
[ios.base.callback]: #ios.base.callback
|
| 5968 |
[ios.base.cons]: #ios.base.cons
|
| 5969 |
[ios.base.locales]: #ios.base.locales
|
| 5970 |
[ios.base.storage]: #ios.base.storage
|
| 5971 |
[ios.members.static]: #ios.members.static
|
| 5972 |
[ios.overview]: #ios.overview
|
|
|
|
| 5973 |
[ios.types]: #ios.types
|
| 5974 |
[ios::Init]: #ios::Init
|
| 5975 |
[ios::failure]: #ios::failure
|
| 5976 |
[ios::fmtflags]: #ios::fmtflags
|
| 5977 |
[ios::iostate]: #ios::iostate
|
| 5978 |
[ios::openmode]: #ios::openmode
|
| 5979 |
[ios::seekdir]: #ios::seekdir
|
|
|
|
| 5980 |
[iostate.flags]: #iostate.flags
|
| 5981 |
[iostream.assign]: #iostream.assign
|
| 5982 |
[iostream.cons]: #iostream.cons
|
| 5983 |
[iostream.dest]: #iostream.dest
|
| 5984 |
[iostream.format]: #iostream.format
|
| 5985 |
-
[iostream.format.overview]: #iostream.format.overview
|
| 5986 |
[iostream.forward]: #iostream.forward
|
|
|
|
| 5987 |
[iostream.limits.imbue]: #iostream.limits.imbue
|
| 5988 |
[iostream.objects]: #iostream.objects
|
| 5989 |
[iostream.objects.overview]: #iostream.objects.overview
|
|
|
|
| 5990 |
[iostreamclass]: #iostreamclass
|
| 5991 |
[iostreams.base]: #iostreams.base
|
| 5992 |
-
[iostreams.base.overview]: #iostreams.base.overview
|
| 5993 |
[iostreams.limits.pos]: #iostreams.limits.pos
|
| 5994 |
[iostreams.requirements]: #iostreams.requirements
|
| 5995 |
[iostreams.threadsafety]: #iostreams.threadsafety
|
| 5996 |
[istream]: #istream
|
| 5997 |
[istream.assign]: #istream.assign
|
| 5998 |
[istream.cons]: #istream.cons
|
|
|
|
| 5999 |
[istream.formatted]: #istream.formatted
|
| 6000 |
[istream.formatted.arithmetic]: #istream.formatted.arithmetic
|
| 6001 |
[istream.formatted.reqmts]: #istream.formatted.reqmts
|
| 6002 |
[istream.manip]: #istream.manip
|
| 6003 |
[istream.rvalue]: #istream.rvalue
|
|
|
|
| 6004 |
[istream.unformatted]: #istream.unformatted
|
| 6005 |
-
[istream::extractors]: #istream::extractors
|
| 6006 |
[istream::sentry]: #istream::sentry
|
| 6007 |
[istringstream]: #istringstream
|
| 6008 |
[istringstream.assign]: #istringstream.assign
|
| 6009 |
[istringstream.cons]: #istringstream.cons
|
| 6010 |
[istringstream.members]: #istringstream.members
|
| 6011 |
-
[
|
| 6012 |
[locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
|
| 6013 |
[locale.num.get]: localization.md#locale.num.get
|
| 6014 |
[narrow.stream.objects]: #narrow.stream.objects
|
|
|
|
| 6015 |
[ofstream]: #ofstream
|
| 6016 |
[ofstream.assign]: #ofstream.assign
|
| 6017 |
[ofstream.cons]: #ofstream.cons
|
| 6018 |
[ofstream.members]: #ofstream.members
|
| 6019 |
[ostream]: #ostream
|
|
@@ -6025,24 +10483,25 @@ Library header `<inttypes.h>`, with the following changes:
|
|
| 6025 |
[ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
|
| 6026 |
[ostream.inserters.character]: #ostream.inserters.character
|
| 6027 |
[ostream.manip]: #ostream.manip
|
| 6028 |
[ostream.rvalue]: #ostream.rvalue
|
| 6029 |
[ostream.seeks]: #ostream.seeks
|
|
|
|
| 6030 |
[ostream.unformatted]: #ostream.unformatted
|
| 6031 |
[ostream::sentry]: #ostream::sentry
|
| 6032 |
[ostringstream]: #ostringstream
|
| 6033 |
[ostringstream.assign]: #ostringstream.assign
|
| 6034 |
[ostringstream.cons]: #ostringstream.cons
|
| 6035 |
[ostringstream.members]: #ostringstream.members
|
| 6036 |
[output.streams]: #output.streams
|
| 6037 |
[quoted.manip]: #quoted.manip
|
| 6038 |
[res.on.data.races]: library.md#res.on.data.races
|
| 6039 |
[res.on.exception.handling]: library.md#res.on.exception.handling
|
|
|
|
| 6040 |
[std.ios.manip]: #std.ios.manip
|
| 6041 |
[std.manip]: #std.manip
|
| 6042 |
[stream.buffers]: #stream.buffers
|
| 6043 |
-
[stream.buffers.overview]: #stream.buffers.overview
|
| 6044 |
[stream.types]: #stream.types
|
| 6045 |
[streambuf]: #streambuf
|
| 6046 |
[streambuf.assign]: #streambuf.assign
|
| 6047 |
[streambuf.buffer]: #streambuf.buffer
|
| 6048 |
[streambuf.cons]: #streambuf.cons
|
|
@@ -6053,44 +10512,53 @@ Library header `<inttypes.h>`, with the following changes:
|
|
| 6053 |
[streambuf.pub.get]: #streambuf.pub.get
|
| 6054 |
[streambuf.pub.pback]: #streambuf.pub.pback
|
| 6055 |
[streambuf.pub.put]: #streambuf.pub.put
|
| 6056 |
[streambuf.put.area]: #streambuf.put.area
|
| 6057 |
[streambuf.reqts]: #streambuf.reqts
|
|
|
|
| 6058 |
[streambuf.virt.buffer]: #streambuf.virt.buffer
|
| 6059 |
[streambuf.virt.get]: #streambuf.virt.get
|
| 6060 |
[streambuf.virt.locales]: #streambuf.virt.locales
|
| 6061 |
[streambuf.virt.pback]: #streambuf.virt.pback
|
| 6062 |
[streambuf.virt.put]: #streambuf.virt.put
|
| 6063 |
[streambuf.virtuals]: #streambuf.virtuals
|
| 6064 |
[string.classes]: strings.md#string.classes
|
| 6065 |
[string.streams]: #string.streams
|
| 6066 |
-
[string.streams.overview]: #string.streams.overview
|
| 6067 |
[stringbuf]: #stringbuf
|
| 6068 |
[stringbuf.assign]: #stringbuf.assign
|
| 6069 |
[stringbuf.cons]: #stringbuf.cons
|
| 6070 |
[stringbuf.members]: #stringbuf.members
|
| 6071 |
[stringbuf.virtuals]: #stringbuf.virtuals
|
| 6072 |
[strings]: strings.md#strings
|
| 6073 |
[stringstream]: #stringstream
|
| 6074 |
[stringstream.assign]: #stringstream.assign
|
| 6075 |
[stringstream.cons]: #stringstream.cons
|
| 6076 |
[stringstream.members]: #stringstream.members
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6077 |
[tab:iostreams.basicios.init.effects]: #tab:iostreams.basicios.init.effects
|
| 6078 |
[tab:iostreams.copyfmt.effects]: #tab:iostreams.copyfmt.effects
|
| 6079 |
[tab:iostreams.file.open.modes]: #tab:iostreams.file.open.modes
|
| 6080 |
[tab:iostreams.fmtflags.constants]: #tab:iostreams.fmtflags.constants
|
| 6081 |
[tab:iostreams.fmtflags.effects]: #tab:iostreams.fmtflags.effects
|
| 6082 |
-
[tab:iostreams.hdr.cinttypes]: #tab:iostreams.hdr.cinttypes
|
| 6083 |
-
[tab:iostreams.hdr.cstdio]: #tab:iostreams.hdr.cstdio
|
| 6084 |
[tab:iostreams.iostate.effects]: #tab:iostreams.iostate.effects
|
| 6085 |
[tab:iostreams.lib.summary]: #tab:iostreams.lib.summary
|
| 6086 |
[tab:iostreams.newoff.values]: #tab:iostreams.newoff.values
|
| 6087 |
[tab:iostreams.openmode.effects]: #tab:iostreams.openmode.effects
|
| 6088 |
[tab:iostreams.position.requirements]: #tab:iostreams.position.requirements
|
| 6089 |
[tab:iostreams.seekdir.effects]: #tab:iostreams.seekdir.effects
|
| 6090 |
[tab:iostreams.seekoff.effects]: #tab:iostreams.seekoff.effects
|
| 6091 |
[tab:iostreams.seekoff.positioning]: #tab:iostreams.seekoff.positioning
|
|
|
|
|
|
|
| 6092 |
[wide.stream.objects]: #wide.stream.objects
|
| 6093 |
|
| 6094 |
[^1]: It is the implementation’s responsibility to implement headers so
|
| 6095 |
that including `<iosfwd>` and other headers does not violate the
|
| 6096 |
rules about multiple occurrences of default arguments.
|
|
@@ -6124,11 +10592,11 @@ Library header `<inttypes.h>`, with the following changes:
|
|
| 6124 |
|
| 6125 |
[^9]: for example, because it cannot allocate space.
|
| 6126 |
|
| 6127 |
[^10]: This suggests an infinite amount of copying, but the
|
| 6128 |
implementation can keep track of the maximum element of the arrays
|
| 6129 |
-
that is
|
| 6130 |
|
| 6131 |
[^11]: Checking `badbit` also for `fail()` is historical practice.
|
| 6132 |
|
| 6133 |
[^12]: The function signature `dec(ios_base&)` can be called by the
|
| 6134 |
function signature
|
|
@@ -6140,91 +10608,99 @@ Library header `<inttypes.h>`, with the following changes:
|
|
| 6140 |
to assure that only objects for classes derived from this class may
|
| 6141 |
be constructed.
|
| 6142 |
|
| 6143 |
[^14]: `underflow` or `uflow` might fail by throwing an exception
|
| 6144 |
prematurely. The intention is not only that the calls will not
|
| 6145 |
-
return `eof()` but that they will return “immediately
|
| 6146 |
|
| 6147 |
[^15]: Classes derived from `basic_streambuf` can provide more efficient
|
| 6148 |
ways to implement `xsgetn()` and `xsputn()` by overriding these
|
| 6149 |
definitions from the base class.
|
| 6150 |
|
| 6151 |
-
[^16]:
|
| 6152 |
-
|
| 6153 |
-
|
|
|
|
|
|
|
| 6154 |
|
| 6155 |
-
[^17]:
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6156 |
library. The semantics of the constructor used in user code is as
|
| 6157 |
specified.
|
| 6158 |
|
| 6159 |
-
[^
|
| 6160 |
implementation-dependent operations.
|
| 6161 |
|
| 6162 |
-
[^
|
| 6163 |
-
|
| 6164 |
-
[^20]: See, for example, the function signature
|
| 6165 |
-
`ws(basic_istream&)` ([[istream.manip]]).
|
| 6166 |
|
| 6167 |
[^21]: See, for example, the function signature
|
|
|
|
|
|
|
|
|
|
| 6168 |
`dec(ios_base&)` ([[basefield.manip]]).
|
| 6169 |
|
| 6170 |
-
[^
|
| 6171 |
-
|
| 6172 |
-
[^23]: Note that this function is not overloaded on types `signed char`
|
| 6173 |
-
and `unsigned char`.
|
| 6174 |
|
| 6175 |
[^24]: Note that this function is not overloaded on types `signed char`
|
| 6176 |
and `unsigned char`.
|
| 6177 |
|
| 6178 |
[^25]: Note that this function is not overloaded on types `signed char`
|
| 6179 |
and `unsigned char`.
|
| 6180 |
|
| 6181 |
-
[^26]:
|
|
|
|
|
|
|
|
|
|
| 6182 |
the `gcount()`, even though it is not stored.
|
| 6183 |
|
| 6184 |
-
[^
|
| 6185 |
setting `failbit`. This is different behavior than the historical
|
| 6186 |
AT&T implementation.
|
| 6187 |
|
| 6188 |
-
[^
|
| 6189 |
set.
|
| 6190 |
|
| 6191 |
-
[^
|
| 6192 |
and `unsigned char`.
|
| 6193 |
|
| 6194 |
-
[^
|
| 6195 |
function can determine that no synchronization is necessary.
|
| 6196 |
|
| 6197 |
-
[^
|
| 6198 |
additional implementation-dependent operations.
|
| 6199 |
|
| 6200 |
-
[^
|
| 6201 |
-
|
| 6202 |
-
[^33]: See, for example, the function signature
|
| 6203 |
-
`endl(basic_ostream&)` ([[ostream.manip]]).
|
| 6204 |
|
| 6205 |
[^34]: See, for example, the function signature
|
|
|
|
|
|
|
|
|
|
| 6206 |
`dec(ios_base&)` ([[basefield.manip]]).
|
| 6207 |
|
| 6208 |
-
[^
|
| 6209 |
-
|
| 6210 |
-
[^36]: Note that this function is not overloaded on types `signed char`
|
| 6211 |
-
and `unsigned char`.
|
| 6212 |
|
| 6213 |
[^37]: Note that this function is not overloaded on types `signed char`
|
| 6214 |
and `unsigned char`.
|
| 6215 |
|
| 6216 |
-
[^38]:
|
|
|
|
|
|
|
|
|
|
| 6217 |
`ios_base::skipws` in the format flags stored in the
|
| 6218 |
`basic_istream<charT, traits>` object `cin` (the same as
|
| 6219 |
`cin >> noskipws`), and the expression
|
| 6220 |
`cout << resetiosflags(ios_base::showbase)` clears
|
| 6221 |
`ios_base::showbase` in the format flags stored in the
|
| 6222 |
`basic_ostream<charT, traits>` object `cout` (the same as
|
| 6223 |
`cout << noshowbase`).
|
| 6224 |
|
| 6225 |
-
[^
|
| 6226 |
`fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
|
| 6227 |
-
declared, in `<cstdio>` ([[
|
| 6228 |
|
| 6229 |
-
[^
|
| 6230 |
-
|
|
|
|
|
|
|
|
|
| 12 |
summarized in Table [[tab:iostreams.lib.summary]].
|
| 13 |
|
| 14 |
**Table: Input/output library summary** <a id="tab:iostreams.lib.summary">[tab:iostreams.lib.summary]</a>
|
| 15 |
|
| 16 |
| Subclause | | Header |
|
| 17 |
+
| -------------------------- | --------------------------- | -------------- |
|
| 18 |
| [[iostreams.requirements]] | Requirements | |
|
| 19 |
| [[iostream.forward]] | Forward declarations | `<iosfwd>` |
|
| 20 |
| [[iostream.objects]] | Standard iostream objects | `<iostream>` |
|
| 21 |
| [[iostreams.base]] | Iostreams base classes | `<ios>` |
|
| 22 |
| [[stream.buffers]] | Stream buffers | `<streambuf>` |
|
| 23 |
| [[iostream.format]] | Formatting and manipulators | `<istream>` |
|
| 24 |
| | | `<ostream>` |
|
| 25 |
| | | `<iomanip>` |
|
| 26 |
| [[string.streams]] | String streams | `<sstream>` |
|
| 27 |
| [[file.streams]] | File streams | `<fstream>` |
|
| 28 |
+
| [[filesystems]] | File systems | `<filesystem>` |
|
| 29 |
+
| [[c.files]] | C library files | `<cstdio>` |
|
| 30 |
| | | `<cinttypes>` |
|
| 31 |
|
| 32 |
|
| 33 |
Figure [[fig:streampos]] illustrates relationships among various types
|
| 34 |
described in this clause. A line from **A** to **B** indicates that
|
|
|
|
| 58 |
as noted explicitly below, their behavior when `traits::pos_type` and
|
| 59 |
`traits::off_type` are other types is *implementation-defined*.
|
| 60 |
|
| 61 |
In the classes of Clause [[input.output]], a template parameter with
|
| 62 |
name `charT` represents a member of the set of types containing `char`,
|
| 63 |
+
`wchar_t`, and any other *implementation-defined* character types that
|
| 64 |
satisfy the requirements for a character on which any of the iostream
|
| 65 |
components can be instantiated.
|
| 66 |
|
| 67 |
### Thread safety <a id="iostreams.threadsafety">[[iostreams.threadsafety]]</a>
|
| 68 |
|
| 69 |
Concurrent access to a stream object ([[string.streams]],
|
| 70 |
[[file.streams]]), stream buffer object ([[stream.buffers]]), or C
|
| 71 |
Library stream ([[c.files]]) by multiple threads may result in a data
|
| 72 |
race ([[intro.multithread]]) unless otherwise specified (
|
| 73 |
+
[[iostream.objects]]).
|
| 74 |
+
|
| 75 |
+
[*Note 1*: Data races result in undefined behavior (
|
| 76 |
+
[[intro.multithread]]). — *end note*]
|
| 77 |
|
| 78 |
If one thread makes a library call *a* that writes a value to a stream
|
| 79 |
and, as a result, another thread reads this value from the stream
|
| 80 |
through a library call *b* such that this does not result in a data
|
| 81 |
race, then *a*’s write synchronizes with *b*’s read.
|
| 82 |
|
| 83 |
## Forward declarations <a id="iostream.forward">[[iostream.forward]]</a>
|
| 84 |
|
| 85 |
+
### Header `<iosfwd>` synopsis <a id="iosfwd.syn">[[iosfwd.syn]]</a>
|
| 86 |
+
|
| 87 |
``` cpp
|
| 88 |
namespace std {
|
| 89 |
template<class charT> class char_traits;
|
| 90 |
template<> class char_traits<char>;
|
| 91 |
template<> class char_traits<char16_t>;
|
|
|
|
| 130 |
template <class charT, class traits = char_traits<charT>>
|
| 131 |
class istreambuf_iterator;
|
| 132 |
template <class charT, class traits = char_traits<charT>>
|
| 133 |
class ostreambuf_iterator;
|
| 134 |
|
| 135 |
+
using ios = basic_ios<char>;
|
| 136 |
+
using wios = basic_ios<wchar_t>;
|
| 137 |
|
| 138 |
+
using streambuf = basic_streambuf<char>;
|
| 139 |
+
using istream = basic_istream<char>;
|
| 140 |
+
using ostream = basic_ostream<char>;
|
| 141 |
+
using iostream = basic_iostream<char>;
|
| 142 |
|
| 143 |
+
using stringbuf = basic_stringbuf<char>;
|
| 144 |
+
using istringstream = basic_istringstream<char>;
|
| 145 |
+
using ostringstream = basic_ostringstream<char>;
|
| 146 |
+
using stringstream = basic_stringstream<char>;
|
| 147 |
|
| 148 |
+
using filebuf = basic_filebuf<char>;
|
| 149 |
+
using ifstream = basic_ifstream<char>;
|
| 150 |
+
using ofstream = basic_ofstream<char>;
|
| 151 |
+
using fstream = basic_fstream<char>;
|
| 152 |
|
| 153 |
+
using wstreambuf = basic_streambuf<wchar_t>;
|
| 154 |
+
using wistream = basic_istream<wchar_t>;
|
| 155 |
+
using wostream = basic_ostream<wchar_t>;
|
| 156 |
+
using wiostream = basic_iostream<wchar_t>;
|
| 157 |
|
| 158 |
+
using wstringbuf = basic_stringbuf<wchar_t>;
|
| 159 |
+
using wistringstream = basic_istringstream<wchar_t>;
|
| 160 |
+
using wostringstream = basic_ostringstream<wchar_t>;
|
| 161 |
+
using wstringstream = basic_stringstream<wchar_t>;
|
| 162 |
|
| 163 |
+
using wfilebuf = basic_filebuf<wchar_t>;
|
| 164 |
+
using wifstream = basic_ifstream<wchar_t>;
|
| 165 |
+
using wofstream = basic_ofstream<wchar_t>;
|
| 166 |
+
using wfstream = basic_fstream<wchar_t>;
|
| 167 |
|
| 168 |
template <class state> class fpos;
|
| 169 |
+
using streampos = fpos<char_traits<char>::state_type>;
|
| 170 |
+
using wstreampos = fpos<char_traits<wchar_t>::state_type>;
|
| 171 |
}
|
| 172 |
```
|
| 173 |
|
| 174 |
Default template arguments are described as appearing both in `<iosfwd>`
|
| 175 |
and in the synopsis of other headers but it is well-formed to include
|
| 176 |
both `<iosfwd>` and one or more of the other headers.[^1]
|
| 177 |
|
| 178 |
+
### Overview <a id="iostream.forward.overview">[[iostream.forward.overview]]</a>
|
| 179 |
+
|
| 180 |
The class template specialization `basic_ios<charT, traits>` serves as a
|
| 181 |
virtual base class for the class templates `basic_istream`,
|
| 182 |
`basic_ostream`, and class templates derived from them. `basic_iostream`
|
| 183 |
is a class template derived from both `basic_istream<charT, traits>` and
|
| 184 |
`basic_ostream<charT, traits>`.
|
| 185 |
|
| 186 |
+
The class template specialization `basic_streambuf<charT, traits>`
|
| 187 |
+
serves as a base class for class templates `basic_stringbuf` and
|
| 188 |
`basic_filebuf`.
|
| 189 |
|
| 190 |
The class template specialization `basic_istream<charT, traits>` serves
|
| 191 |
as a base class for class templates `basic_istringstream` and
|
| 192 |
`basic_ifstream`.
|
|
|
|
| 197 |
|
| 198 |
The class template specialization `basic_iostream<charT, traits>` serves
|
| 199 |
as a base class for class templates `basic_stringstream` and
|
| 200 |
`basic_fstream`.
|
| 201 |
|
| 202 |
+
Other *typedef-name*s define instances of class templates specialized
|
| 203 |
+
for `char` or `wchar_t` types.
|
| 204 |
|
| 205 |
Specializations of the class template `fpos` are used for specifying
|
| 206 |
file position information.
|
| 207 |
|
| 208 |
The types `streampos` and `wstreampos` are used for positioning streams
|
| 209 |
specialized on `char` and `wchar_t` respectively.
|
| 210 |
|
| 211 |
+
[*Note 1*:
|
| 212 |
+
|
| 213 |
This synopsis suggests a circularity between `streampos` and
|
| 214 |
`char_traits<char>`. An implementation can avoid this circularity by
|
| 215 |
substituting equivalent types. One way to do this might be
|
| 216 |
|
| 217 |
``` cpp
|
| 218 |
template<class stateT> class fpos { ... }; // depends on nothing
|
| 219 |
+
using _STATE = ... ; // implementation private declaration of stateT
|
| 220 |
|
| 221 |
+
using streampos = fpos<_STATE>;
|
| 222 |
|
| 223 |
template<> struct char_traits<char> {
|
| 224 |
+
using pos_type = streampos;
|
|
|
|
| 225 |
}
|
| 226 |
```
|
| 227 |
|
| 228 |
+
— *end note*]
|
| 229 |
+
|
| 230 |
## Standard iostream objects <a id="iostream.objects">[[iostream.objects]]</a>
|
| 231 |
|
| 232 |
+
### Header `<iostream>` synopsis <a id="iostream.syn">[[iostream.syn]]</a>
|
| 233 |
|
| 234 |
``` cpp
|
| 235 |
+
#include <ios> // see [ios.syn]
|
| 236 |
+
#include <streambuf> // see [streambuf.syn]
|
| 237 |
+
#include <istream> // see [istream.syn]
|
| 238 |
+
#include <ostream> // see [ostream.syn]
|
| 239 |
|
| 240 |
namespace std {
|
| 241 |
extern istream cin;
|
| 242 |
extern ostream cout;
|
| 243 |
extern ostream cerr;
|
|
|
|
| 248 |
extern wostream wcerr;
|
| 249 |
extern wostream wclog;
|
| 250 |
}
|
| 251 |
```
|
| 252 |
|
| 253 |
+
### Overview <a id="iostream.objects.overview">[[iostream.objects.overview]]</a>
|
| 254 |
+
|
| 255 |
+
In this Clause, the type name `FILE` refers to the type `FILE` declared
|
| 256 |
+
in `<cstdio>` ([[cstdio.syn]]).
|
| 257 |
+
|
| 258 |
The header `<iostream>` declares objects that associate objects with the
|
| 259 |
standard C streams provided for by the functions declared in
|
| 260 |
`<cstdio>` ([[c.files]]), and includes all the headers necessary to use
|
| 261 |
these objects.
|
| 262 |
|
| 263 |
The objects are constructed and the associations are established at some
|
| 264 |
time prior to or during the first time an object of class
|
| 265 |
`ios_base::Init` is constructed, and in any case before the body of
|
| 266 |
+
`main` ([[basic.start.main]]) begins execution.[^2] The objects are not
|
| 267 |
+
destroyed during program execution.[^3] The results of including
|
| 268 |
+
`<iostream>` in a translation unit shall be as if `<iostream>` defined
|
| 269 |
+
an instance of `ios_base::Init` with static storage duration.
|
|
|
|
|
|
|
| 270 |
|
| 271 |
Mixing operations on corresponding wide- and narrow-character streams
|
| 272 |
follows the same semantics as mixing such operations on `FILE`s, as
|
| 273 |
+
specified in the C standard library.
|
| 274 |
|
| 275 |
Concurrent access to a synchronized ([[ios.members.static]]) standard
|
| 276 |
iostream object’s formatted and unformatted input ([[istream]]) and
|
| 277 |
output ([[ostream]]) functions or a standard C stream by multiple
|
| 278 |
+
threads shall not result in a data race ([[intro.multithread]]).
|
| 279 |
+
|
| 280 |
+
[*Note 1*: Users must still synchronize concurrent use of these objects
|
| 281 |
+
and streams by multiple threads if they wish to avoid interleaved
|
| 282 |
+
characters. — *end note*]
|
| 283 |
+
|
| 284 |
+
ISO C 7.21.2.
|
| 285 |
|
| 286 |
### Narrow stream objects <a id="narrow.stream.objects">[[narrow.stream.objects]]</a>
|
| 287 |
|
| 288 |
``` cpp
|
| 289 |
istream cin;
|
| 290 |
```
|
| 291 |
|
| 292 |
The object `cin` controls input from a stream buffer associated with the
|
| 293 |
+
object `stdin`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 294 |
|
| 295 |
After the object `cin` is initialized, `cin.tie()` returns `&cout`. Its
|
| 296 |
state is otherwise the same as required for
|
| 297 |
`basic_ios<char>::init` ([[basic.ios.cons]]).
|
| 298 |
|
| 299 |
``` cpp
|
| 300 |
ostream cout;
|
| 301 |
```
|
| 302 |
|
| 303 |
The object `cout` controls output to a stream buffer associated with the
|
| 304 |
+
object `stdout`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 305 |
|
| 306 |
``` cpp
|
| 307 |
ostream cerr;
|
| 308 |
```
|
| 309 |
|
| 310 |
The object `cerr` controls output to a stream buffer associated with the
|
| 311 |
+
object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 312 |
|
| 313 |
After the object `cerr` is initialized, `cerr.flags() & unitbuf` is
|
| 314 |
nonzero and `cerr.tie()` returns `&cout`. Its state is otherwise the
|
| 315 |
same as required for `basic_ios<char>::init` ([[basic.ios.cons]]).
|
| 316 |
|
| 317 |
``` cpp
|
| 318 |
ostream clog;
|
| 319 |
```
|
| 320 |
|
| 321 |
The object `clog` controls output to a stream buffer associated with the
|
| 322 |
+
object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 323 |
|
| 324 |
### Wide stream objects <a id="wide.stream.objects">[[wide.stream.objects]]</a>
|
| 325 |
|
| 326 |
``` cpp
|
| 327 |
wistream wcin;
|
| 328 |
```
|
| 329 |
|
| 330 |
The object `wcin` controls input from a stream buffer associated with
|
| 331 |
+
the object `stdin`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 332 |
|
| 333 |
After the object `wcin` is initialized, `wcin.tie()` returns `&wcout`.
|
| 334 |
Its state is otherwise the same as required for
|
| 335 |
`basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
|
| 336 |
|
| 337 |
``` cpp
|
| 338 |
wostream wcout;
|
| 339 |
```
|
| 340 |
|
| 341 |
The object `wcout` controls output to a stream buffer associated with
|
| 342 |
+
the object `stdout`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 343 |
|
| 344 |
``` cpp
|
| 345 |
wostream wcerr;
|
| 346 |
```
|
| 347 |
|
| 348 |
The object `wcerr` controls output to a stream buffer associated with
|
| 349 |
+
the object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 350 |
|
| 351 |
After the object `wcerr` is initialized, `wcerr.flags() & unitbuf` is
|
| 352 |
nonzero and `wcerr.tie()` returns `&wcout`. Its state is otherwise the
|
| 353 |
same as required for `basic_ios<wchar_t>::init` ([[basic.ios.cons]]).
|
| 354 |
|
| 355 |
``` cpp
|
| 356 |
wostream wclog;
|
| 357 |
```
|
| 358 |
|
| 359 |
The object `wclog` controls output to a stream buffer associated with
|
| 360 |
+
the object `stderr`, declared in `<cstdio>` ([[cstdio.syn]]).
|
| 361 |
|
| 362 |
## Iostreams base classes <a id="iostreams.base">[[iostreams.base]]</a>
|
| 363 |
|
| 364 |
+
### Header `<ios>` synopsis <a id="ios.syn">[[ios.syn]]</a>
|
| 365 |
|
| 366 |
``` cpp
|
| 367 |
+
#include <iosfwd> // see [iosfwd.syn]
|
| 368 |
|
| 369 |
namespace std {
|
| 370 |
+
using streamoff = implementation-defined;
|
| 371 |
+
using streamsize = implementation-defined;
|
| 372 |
template <class stateT> class fpos;
|
| 373 |
|
| 374 |
class ios_base;
|
| 375 |
template <class charT, class traits = char_traits<charT>>
|
| 376 |
class basic_ios;
|
| 377 |
|
| 378 |
+
// [std.ios.manip], manipulators
|
| 379 |
ios_base& boolalpha (ios_base& str);
|
| 380 |
ios_base& noboolalpha(ios_base& str);
|
| 381 |
|
| 382 |
ios_base& showbase (ios_base& str);
|
| 383 |
ios_base& noshowbase (ios_base& str);
|
|
|
|
| 395 |
ios_base& nouppercase(ios_base& str);
|
| 396 |
|
| 397 |
ios_base& unitbuf (ios_base& str);
|
| 398 |
ios_base& nounitbuf (ios_base& str);
|
| 399 |
|
| 400 |
+
// [adjustfield.manip], adjustfield
|
| 401 |
ios_base& internal (ios_base& str);
|
| 402 |
ios_base& left (ios_base& str);
|
| 403 |
ios_base& right (ios_base& str);
|
| 404 |
|
| 405 |
+
// [basefield.manip], basefield
|
| 406 |
ios_base& dec (ios_base& str);
|
| 407 |
ios_base& hex (ios_base& str);
|
| 408 |
ios_base& oct (ios_base& str);
|
| 409 |
|
| 410 |
+
// [floatfield.manip], floatfield
|
| 411 |
ios_base& fixed (ios_base& str);
|
| 412 |
ios_base& scientific (ios_base& str);
|
| 413 |
ios_base& hexfloat (ios_base& str);
|
| 414 |
ios_base& defaultfloat(ios_base& str);
|
| 415 |
|
| 416 |
+
// [error.reporting], error reporting
|
| 417 |
enum class io_errc {
|
| 418 |
stream = 1
|
| 419 |
};
|
| 420 |
|
| 421 |
template <> struct is_error_code_enum<io_errc> : public true_type { };
|
|
|
|
| 426 |
```
|
| 427 |
|
| 428 |
### Types <a id="stream.types">[[stream.types]]</a>
|
| 429 |
|
| 430 |
``` cpp
|
| 431 |
+
using streamoff = implementation-defined;
|
| 432 |
```
|
| 433 |
|
| 434 |
The type `streamoff` is a synonym for one of the signed basic integral
|
| 435 |
types of sufficient size to represent the maximum possible file size for
|
| 436 |
the operating system.[^4]
|
| 437 |
|
| 438 |
``` cpp
|
| 439 |
+
using streamsize = implementation-defined;
|
| 440 |
```
|
| 441 |
|
| 442 |
The type `streamsize` is a synonym for one of the signed basic integral
|
| 443 |
types. It is used to represent the number of characters transferred in
|
| 444 |
an I/O operation, or the size of I/O buffers.[^5]
|
|
|
|
| 447 |
|
| 448 |
``` cpp
|
| 449 |
namespace std {
|
| 450 |
class ios_base {
|
| 451 |
public:
|
| 452 |
+
class failure; // see below
|
| 453 |
|
| 454 |
+
// [ios::fmtflags], fmtflags
|
| 455 |
+
using fmtflags = T1;
|
| 456 |
static constexpr fmtflags boolalpha = unspecified;
|
| 457 |
static constexpr fmtflags dec = unspecified;
|
| 458 |
static constexpr fmtflags fixed = unspecified;
|
| 459 |
static constexpr fmtflags hex = unspecified;
|
| 460 |
static constexpr fmtflags internal = unspecified;
|
|
|
|
| 470 |
static constexpr fmtflags uppercase = unspecified;
|
| 471 |
static constexpr fmtflags adjustfield = see below;
|
| 472 |
static constexpr fmtflags basefield = see below;
|
| 473 |
static constexpr fmtflags floatfield = see below;
|
| 474 |
|
| 475 |
+
// [ios::iostate], iostate
|
| 476 |
+
using iostate = T2;
|
| 477 |
static constexpr iostate badbit = unspecified;
|
| 478 |
static constexpr iostate eofbit = unspecified;
|
| 479 |
static constexpr iostate failbit = unspecified;
|
| 480 |
static constexpr iostate goodbit = see below;
|
| 481 |
|
| 482 |
+
// [ios::openmode], openmode
|
| 483 |
+
using openmode = T3;
|
| 484 |
static constexpr openmode app = unspecified;
|
| 485 |
static constexpr openmode ate = unspecified;
|
| 486 |
static constexpr openmode binary = unspecified;
|
| 487 |
static constexpr openmode in = unspecified;
|
| 488 |
static constexpr openmode out = unspecified;
|
| 489 |
static constexpr openmode trunc = unspecified;
|
| 490 |
|
| 491 |
+
// [ios::seekdir], seekdir
|
| 492 |
+
using seekdir = T4;
|
| 493 |
static constexpr seekdir beg = unspecified;
|
| 494 |
static constexpr seekdir cur = unspecified;
|
| 495 |
static constexpr seekdir end = unspecified;
|
| 496 |
|
| 497 |
class Init;
|
| 498 |
|
| 499 |
+
// [fmtflags.state], fmtflags state
|
| 500 |
fmtflags flags() const;
|
| 501 |
fmtflags flags(fmtflags fmtfl);
|
| 502 |
fmtflags setf(fmtflags fmtfl);
|
| 503 |
fmtflags setf(fmtflags fmtfl, fmtflags mask);
|
| 504 |
void unsetf(fmtflags mask);
|
|
|
|
| 506 |
streamsize precision() const;
|
| 507 |
streamsize precision(streamsize prec);
|
| 508 |
streamsize width() const;
|
| 509 |
streamsize width(streamsize wide);
|
| 510 |
|
| 511 |
+
// [ios.base.locales], locales
|
| 512 |
locale imbue(const locale& loc);
|
| 513 |
locale getloc() const;
|
| 514 |
|
| 515 |
+
// [ios.base.storage], storage
|
| 516 |
static int xalloc();
|
| 517 |
long& iword(int index);
|
| 518 |
void*& pword(int index);
|
| 519 |
|
| 520 |
+
// destructor:
|
| 521 |
virtual ~ios_base();
|
| 522 |
|
| 523 |
+
// [ios.base.callback], callbacks;
|
| 524 |
enum event { erase_event, imbue_event, copyfmt_event };
|
| 525 |
+
using event_callback = void (*)(event, ios_base&, int index);
|
| 526 |
void register_callback(event_callback fn, int index);
|
| 527 |
|
| 528 |
ios_base(const ios_base&) = delete;
|
| 529 |
ios_base& operator=(const ios_base&) = delete;
|
| 530 |
|
|
|
|
| 543 |
|
| 544 |
`ios_base`
|
| 545 |
|
| 546 |
defines several member types:
|
| 547 |
|
| 548 |
+
- a type `failure`, defined as either a class derived from
|
| 549 |
+
`system_error` or a synonym for a class derived from `system_error`;
|
| 550 |
- a class `Init`;
|
| 551 |
- three bitmask types, `fmtflags`, `iostate`, and `openmode`;
|
| 552 |
- an enumerated type, `seekdir`.
|
| 553 |
|
| 554 |
It maintains several kinds of data:
|
|
|
|
| 557 |
- control information that influences how to interpret (format) input
|
| 558 |
sequences and how to generate (format) output sequences;
|
| 559 |
- additional information that is stored by the program for its private
|
| 560 |
use.
|
| 561 |
|
| 562 |
+
[*Note 1*:
|
| 563 |
+
|
| 564 |
For the sake of exposition, the maintained data is presented here as:
|
| 565 |
|
| 566 |
- `static int index`, specifies the next available unique index for the
|
| 567 |
integer or pointer arrays maintained for the private use of the
|
| 568 |
program, initialized to an unspecified value;
|
| 569 |
- `long* iarray`, points to the first element of an arbitrary-length
|
| 570 |
`long` array maintained for the private use of the program;
|
| 571 |
- `void** parray`, points to the first element of an arbitrary-length
|
| 572 |
pointer array maintained for the private use of the program.
|
| 573 |
|
| 574 |
+
— *end note*]
|
| 575 |
+
|
| 576 |
#### Types <a id="ios.types">[[ios.types]]</a>
|
| 577 |
|
| 578 |
##### Class `ios_base::failure` <a id="ios::failure">[[ios::failure]]</a>
|
| 579 |
|
| 580 |
``` cpp
|
|
|
|
| 585 |
explicit failure(const char* msg, const error_code& ec = io_errc::stream);
|
| 586 |
};
|
| 587 |
}
|
| 588 |
```
|
| 589 |
|
| 590 |
+
An implementation is permitted to define `ios_base::failure` as a
|
| 591 |
+
synonym for a class with equivalent functionality to class
|
| 592 |
+
`ios_base::failure` shown in this subclause.
|
| 593 |
+
|
| 594 |
+
[*Note 1*: When `ios_base::failure` is a synonym for another type it
|
| 595 |
+
shall provide a nested type `failure`, to emulate the injected class
|
| 596 |
+
name. — *end note*]
|
| 597 |
+
|
| 598 |
The class `failure` defines the base class for the types of all objects
|
| 599 |
thrown as exceptions, by functions in the iostreams library, to report
|
| 600 |
errors detected during stream buffer operations.
|
| 601 |
|
| 602 |
When throwing `ios_base::failure` exceptions, implementations should
|
| 603 |
provide values of `ec` that identify the specific reason for the
|
| 604 |
+
failure.
|
| 605 |
+
|
| 606 |
+
[*Note 2*: Errors arising from the operating system would typically be
|
| 607 |
reported as `system_category()` errors with an error value of the error
|
| 608 |
number reported by the operating system. Errors arising from within the
|
| 609 |
stream library would typically be reported as
|
| 610 |
`error_code(io_errc::stream,
|
| 611 |
+
iostream_category())`. — *end note*]
|
| 612 |
|
| 613 |
``` cpp
|
| 614 |
explicit failure(const string& msg, const error_code& ec = io_errc::stream);
|
| 615 |
```
|
| 616 |
|
|
|
|
| 625 |
base class with `msg` and `ec`.
|
| 626 |
|
| 627 |
##### Type `ios_base::fmtflags` <a id="ios::fmtflags">[[ios::fmtflags]]</a>
|
| 628 |
|
| 629 |
``` cpp
|
| 630 |
+
using fmtflags = T1;
|
| 631 |
```
|
| 632 |
|
| 633 |
The type `fmtflags` is a bitmask type ([[bitmask.types]]). Setting its
|
| 634 |
elements has the effects indicated in
|
| 635 |
Table [[tab:iostreams.fmtflags.effects]].
|
|
|
|
| 668 |
|
| 669 |
|
| 670 |
##### Type `ios_base::iostate` <a id="ios::iostate">[[ios::iostate]]</a>
|
| 671 |
|
| 672 |
``` cpp
|
| 673 |
+
using iostate = T2;
|
| 674 |
```
|
| 675 |
|
| 676 |
The type `iostate` is a bitmask type ([[bitmask.types]]) that contains
|
| 677 |
the elements indicated in Table [[tab:iostreams.iostate.effects]].
|
| 678 |
|
|
|
|
| 690 |
- `goodbit`, the value zero.
|
| 691 |
|
| 692 |
##### Type `ios_base::openmode` <a id="ios::openmode">[[ios::openmode]]</a>
|
| 693 |
|
| 694 |
``` cpp
|
| 695 |
+
using openmode = T3;
|
| 696 |
```
|
| 697 |
|
| 698 |
The type `openmode` is a bitmask type ([[bitmask.types]]). It contains
|
| 699 |
the elements indicated in Table [[tab:iostreams.openmode.effects]].
|
| 700 |
|
|
|
|
| 711 |
|
| 712 |
|
| 713 |
##### Type `ios_base::seekdir` <a id="ios::seekdir">[[ios::seekdir]]</a>
|
| 714 |
|
| 715 |
``` cpp
|
| 716 |
+
using seekdir = T4;
|
| 717 |
```
|
| 718 |
|
| 719 |
The type `seekdir` is an enumerated type ([[enumerated.types]]) that
|
| 720 |
contains the elements indicated in
|
| 721 |
Table [[tab:iostreams.seekdir.effects]].
|
|
|
|
| 745 |
|
| 746 |
The class `Init` describes an object whose construction ensures the
|
| 747 |
construction of the eight objects declared in `<iostream>` (
|
| 748 |
[[iostream.objects]]) that associate file stream buffers with the
|
| 749 |
standard C streams provided for by the functions declared in
|
| 750 |
+
`<cstdio>` ([[cstdio.syn]]).
|
| 751 |
|
| 752 |
For the sake of exposition, the maintained data is presented here as:
|
| 753 |
|
| 754 |
- `static int init_cnt`, counts the number of constructor and destructor
|
| 755 |
calls for class `Init`, initialized to zero.
|
|
|
|
| 782 |
|
| 783 |
``` cpp
|
| 784 |
fmtflags flags(fmtflags fmtfl);
|
| 785 |
```
|
| 786 |
|
| 787 |
+
*Postconditions:* `fmtfl == flags()`.
|
| 788 |
|
| 789 |
*Returns:* The previous value of `flags()`.
|
| 790 |
|
| 791 |
``` cpp
|
| 792 |
fmtflags setf(fmtflags fmtfl);
|
|
|
|
| 818 |
|
| 819 |
``` cpp
|
| 820 |
streamsize precision(streamsize prec);
|
| 821 |
```
|
| 822 |
|
| 823 |
+
*Postconditions:* `prec == precision()`.
|
| 824 |
|
| 825 |
*Returns:* The previous value of `precision()`.
|
| 826 |
|
| 827 |
``` cpp
|
| 828 |
streamsize width() const;
|
|
|
|
| 833 |
|
| 834 |
``` cpp
|
| 835 |
streamsize width(streamsize wide);
|
| 836 |
```
|
| 837 |
|
| 838 |
+
*Postconditions:* `wide == width()`.
|
| 839 |
|
| 840 |
*Returns:* The previous value of `width()`.
|
| 841 |
|
| 842 |
#### `ios_base` functions <a id="ios.base.locales">[[ios.base.locales]]</a>
|
| 843 |
|
|
|
|
| 851 |
`ios_base::getloc()` from within `fn` returns the new locale value
|
| 852 |
`loc`.
|
| 853 |
|
| 854 |
*Returns:* The previous value of `getloc()`.
|
| 855 |
|
| 856 |
+
*Postconditions:* `loc == getloc()`.
|
| 857 |
|
| 858 |
``` cpp
|
| 859 |
locale getloc() const;
|
| 860 |
```
|
| 861 |
|
|
|
|
| 874 |
objects ([[iostream.objects]]) was synchronized and otherwise returns
|
| 875 |
`false`. The first time it is called, the function returns `true`.
|
| 876 |
|
| 877 |
*Effects:* If any input or output operation has occurred using the
|
| 878 |
standard streams prior to the call, the effect is
|
| 879 |
+
*implementation-defined*. Otherwise, called with a `false` argument, it
|
| 880 |
allows the standard streams to operate independently of the standard C
|
| 881 |
streams.
|
| 882 |
|
| 883 |
When a standard iostream object `str` is *synchronized* with a standard
|
| 884 |
stdio stream `f`, the effect of inserting a character `c` by
|
|
|
|
| 942 |
necessary to include the element `iarray[idx]`. Each newly allocated
|
| 943 |
element of the array is initialized to zero. The reference returned is
|
| 944 |
invalid after any other operations on the object.[^7] However, the value
|
| 945 |
of the storage referred to is retained, so that until the next call to
|
| 946 |
`copyfmt`, calling `iword` with the same index yields another reference
|
| 947 |
+
to the same value. If the function fails[^8] and `*this` is a base class
|
| 948 |
subobject of a `basic_ios<>` object or subobject, the effect is
|
| 949 |
equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
|
| 950 |
object (which may throw `failure`).
|
| 951 |
|
| 952 |
*Returns:* On success `iarray[idx]`. On failure, a valid `long&`
|
|
|
|
| 963 |
element of the array is initialized to a null pointer. The reference
|
| 964 |
returned is invalid after any other operations on the object. However,
|
| 965 |
the value of the storage referred to is retained, so that until the next
|
| 966 |
call to `copyfmt`, calling `pword` with the same index yields another
|
| 967 |
reference to the same value. If the function fails[^9] and `*this` is a
|
| 968 |
+
base class subobject of a `basic_ios<>` object or subobject, the effect
|
| 969 |
+
is equivalent to calling `basic_ios<>::setstate(badbit)` on the derived
|
| 970 |
object (which may throw `failure`).
|
| 971 |
|
| 972 |
*Returns:* On success `parray[idx]`. On failure a valid `void*&`
|
| 973 |
initialized to 0.
|
| 974 |
|
|
|
|
| 1017 |
|
| 1018 |
``` cpp
|
| 1019 |
namespace std {
|
| 1020 |
template <class stateT> class fpos {
|
| 1021 |
public:
|
| 1022 |
+
// [fpos.members], members
|
| 1023 |
stateT state() const;
|
| 1024 |
void state(stateT);
|
| 1025 |
private;
|
| 1026 |
stateT st; // exposition only
|
| 1027 |
};
|
|
|
|
| 1032 |
|
| 1033 |
``` cpp
|
| 1034 |
void state(stateT s);
|
| 1035 |
```
|
| 1036 |
|
| 1037 |
+
*Effects:* Assigns `s` to `st`.
|
| 1038 |
|
| 1039 |
``` cpp
|
| 1040 |
stateT state() const;
|
| 1041 |
```
|
| 1042 |
|
|
|
|
| 1052 |
- `O` refers to type `streamoff`,
|
| 1053 |
- `o` refers to a value of type `streamoff`,
|
| 1054 |
- `sz` refers to a value of type `streamsize` and
|
| 1055 |
- `i` refers to a value of type `int`.
|
| 1056 |
|
| 1057 |
+
[*Note 1*: Every implementation is required to supply overloaded
|
| 1058 |
+
operators on `fpos` objects to satisfy the requirements of
|
| 1059 |
+
[[fpos.operations]]. It is unspecified whether these operators are
|
| 1060 |
+
members of `fpos`, global operators, or provided in some other
|
| 1061 |
+
way. — *end note*]
|
| 1062 |
|
| 1063 |
Stream operations that return a value of type `traits::pos_type` return
|
| 1064 |
`P(O(-1))` as an invalid value to signal an error. If this value is used
|
| 1065 |
as an argument to any `istream`, `ostream`, or `streambuf` member that
|
| 1066 |
accepts a value of type `traits::pos_type` then the behavior of that
|
|
|
|
| 1073 |
``` cpp
|
| 1074 |
namespace std {
|
| 1075 |
template <class charT, class traits = char_traits<charT>>
|
| 1076 |
class basic_ios : public ios_base {
|
| 1077 |
public:
|
| 1078 |
+
using char_type = charT;
|
| 1079 |
+
using int_type = typename traits::int_type;
|
| 1080 |
+
using pos_type = typename traits::pos_type;
|
| 1081 |
+
using off_type = typename traits::off_type;
|
| 1082 |
+
using traits_type = traits;
|
| 1083 |
|
| 1084 |
+
// [iostate.flags], flags functions
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1085 |
explicit operator bool() const;
|
| 1086 |
bool operator!() const;
|
| 1087 |
iostate rdstate() const;
|
| 1088 |
void clear(iostate state = goodbit);
|
| 1089 |
void setstate(iostate state);
|
|
|
|
| 1093 |
bool bad() const;
|
| 1094 |
|
| 1095 |
iostate exceptions() const;
|
| 1096 |
void exceptions(iostate except);
|
| 1097 |
|
| 1098 |
+
// [basic.ios.cons], constructor/destructor
|
| 1099 |
explicit basic_ios(basic_streambuf<charT, traits>* sb);
|
| 1100 |
virtual ~basic_ios();
|
| 1101 |
|
| 1102 |
+
// [basic.ios.members], members
|
| 1103 |
basic_ostream<charT, traits>* tie() const;
|
| 1104 |
basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
|
| 1105 |
|
| 1106 |
basic_streambuf<charT, traits>* rdbuf() const;
|
| 1107 |
basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
|
|
|
|
| 1172 |
| `rdstate()` | `goodbit` if `sb` is not a null pointer, otherwise `badbit`. |
|
| 1173 |
| `exceptions()` | `goodbit` |
|
| 1174 |
| `flags()` | `skipws | dec` |
|
| 1175 |
| `width()` | `0` |
|
| 1176 |
| `precision()` | `6` |
|
| 1177 |
+
| `fill()` | `widen(' ')` |
|
| 1178 |
| `getloc()` | a copy of the value returned by `locale()` |
|
| 1179 |
| `iarray` | a null pointer |
|
| 1180 |
| `parray` | a null pointer |
|
| 1181 |
|
| 1182 |
|
|
|
|
| 1195 |
|
| 1196 |
*Requires:* If `tiestr` is not null, `tiestr` must not be reachable by
|
| 1197 |
traversing the linked list of tied stream objects starting from
|
| 1198 |
`tiestr->tie()`.
|
| 1199 |
|
| 1200 |
+
*Postconditions:* `tiestr == tie()`.
|
| 1201 |
|
| 1202 |
*Returns:* The previous value of `tie()`.
|
| 1203 |
|
| 1204 |
``` cpp
|
| 1205 |
basic_streambuf<charT, traits>* rdbuf() const;
|
|
|
|
| 1209 |
|
| 1210 |
``` cpp
|
| 1211 |
basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
|
| 1212 |
```
|
| 1213 |
|
| 1214 |
+
*Postconditions:* `sb == rdbuf()`.
|
| 1215 |
|
| 1216 |
*Effects:* Calls `clear()`.
|
| 1217 |
|
| 1218 |
*Returns:* The previous value of `rdbuf()`.
|
| 1219 |
|
|
|
|
| 1247 |
|
| 1248 |
``` cpp
|
| 1249 |
char_type fill(char_type fillch);
|
| 1250 |
```
|
| 1251 |
|
| 1252 |
+
*Postconditions:* `traits::eq(fillch, fill())`.
|
| 1253 |
|
| 1254 |
*Returns:* The previous value of `fill()`.
|
| 1255 |
|
| 1256 |
``` cpp
|
| 1257 |
basic_ios& copyfmt(const basic_ios& rhs);
|
|
|
|
| 1272 |
stored outside the object `rhs` and those objects are destroyed
|
| 1273 |
when `rhs` is destroyed, the newly stored pointer values are
|
| 1274 |
altered to point at newly constructed copies of the objects;
|
| 1275 |
3. calls each callback pair that was copied from `rhs` as
|
| 1276 |
`(*fn)(copyfmt_event, *this, index)`;
|
| 1277 |
+
4. calls `exceptions(rhs.exceptions())`.
|
| 1278 |
|
| 1279 |
+
[*Note 1*: The second pass through the callback pairs permits a copied
|
| 1280 |
`pword` value to be zeroed, or to have its referent deep copied or
|
| 1281 |
+
reference counted, or to have other special action taken. — *end note*]
|
| 1282 |
|
| 1283 |
*Postconditions:* The postconditions of this function are indicated in
|
| 1284 |
Table [[tab:iostreams.copyfmt.effects]].
|
| 1285 |
|
| 1286 |
**Table: `basic_ios::copyfmt()` effects** <a id="tab:iostreams.copyfmt.effects">[tab:iostreams.copyfmt.effects]</a>
|
|
|
|
| 1355 |
|
| 1356 |
``` cpp
|
| 1357 |
void clear(iostate state = goodbit);
|
| 1358 |
```
|
| 1359 |
|
| 1360 |
+
*Postconditions:* If `rdbuf() != 0` then `state == rdstate()`; otherwise
|
| 1361 |
`rdstate() == (state | ios_base::badbit)`.
|
| 1362 |
|
| 1363 |
*Effects:* If
|
| 1364 |
`((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0`, returns.
|
| 1365 |
+
Otherwise, the function throws an object of class
|
| 1366 |
`basic_ios::failure` ([[ios::failure]]), constructed with
|
| 1367 |
*implementation-defined* argument values.
|
| 1368 |
|
| 1369 |
``` cpp
|
| 1370 |
void setstate(iostate state);
|
|
|
|
| 1406 |
|
| 1407 |
``` cpp
|
| 1408 |
void exceptions(iostate except);
|
| 1409 |
```
|
| 1410 |
|
| 1411 |
+
*Postconditions:* `except == exceptions()`.
|
| 1412 |
|
| 1413 |
*Effects:* Calls `clear(rdstate())`.
|
| 1414 |
|
| 1415 |
### `ios_base` manipulators <a id="std.ios.manip">[[std.ios.manip]]</a>
|
| 1416 |
|
|
|
|
| 1605 |
*Effects:* Calls
|
| 1606 |
`str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield)`.
|
| 1607 |
|
| 1608 |
*Returns:* `str`.
|
| 1609 |
|
| 1610 |
+
[*Note 1*: The more obvious use of `ios_base::hex` to specify
|
| 1611 |
+
hexadecimal floating-point format would change the meaning of existing
|
| 1612 |
+
well defined programs. C++03 gives no meaning to the combination of
|
| 1613 |
+
`fixed` and `scientific`. — *end note*]
|
| 1614 |
|
| 1615 |
``` cpp
|
| 1616 |
ios_base& defaultfloat(ios_base& str);
|
| 1617 |
```
|
| 1618 |
|
|
|
|
| 1646 |
object’s `name` virtual function shall return a pointer to the string
|
| 1647 |
`"iostream"`.
|
| 1648 |
|
| 1649 |
## Stream buffers <a id="stream.buffers">[[stream.buffers]]</a>
|
| 1650 |
|
| 1651 |
+
### Header `<streambuf>` synopsis <a id="streambuf.syn">[[streambuf.syn]]</a>
|
| 1652 |
|
| 1653 |
``` cpp
|
| 1654 |
namespace std {
|
| 1655 |
template <class charT, class traits = char_traits<charT>>
|
| 1656 |
class basic_streambuf;
|
| 1657 |
+
using streambuf = basic_streambuf<char>;
|
| 1658 |
+
using wstreambuf = basic_streambuf<wchar_t>;
|
| 1659 |
}
|
| 1660 |
```
|
| 1661 |
|
| 1662 |
The header `<streambuf>` defines types that control input from and
|
| 1663 |
output to *character* sequences.
|
|
|
|
| 1711 |
- If `xnext` is not a null pointer and `xnext < xend` for an input
|
| 1712 |
sequence, then a *read position* is available. In this case, `*xnext`
|
| 1713 |
shall have a defined value and is the next element to read (to get, or
|
| 1714 |
to obtain a character value, from the sequence).
|
| 1715 |
|
| 1716 |
+
### Class template `basic_streambuf` <a id="streambuf">[[streambuf]]</a>
|
| 1717 |
|
| 1718 |
``` cpp
|
| 1719 |
namespace std {
|
| 1720 |
template <class charT, class traits = char_traits<charT>>
|
| 1721 |
class basic_streambuf {
|
| 1722 |
public:
|
| 1723 |
+
using char_type = charT;
|
| 1724 |
+
using int_type = typename traits::int_type;
|
| 1725 |
+
using pos_type = typename traits::pos_type;
|
| 1726 |
+
using off_type = typename traits::off_type;
|
| 1727 |
+
using traits_type = traits;
|
|
|
|
|
|
|
| 1728 |
|
| 1729 |
virtual ~basic_streambuf();
|
| 1730 |
|
| 1731 |
+
// [streambuf.locales], locales
|
| 1732 |
locale pubimbue(const locale& loc);
|
| 1733 |
locale getloc() const;
|
| 1734 |
|
| 1735 |
+
// [streambuf.buffer], buffer and positioning
|
| 1736 |
+
basic_streambuf* pubsetbuf(char_type* s, streamsize n);
|
|
|
|
| 1737 |
pos_type pubseekoff(off_type off, ios_base::seekdir way,
|
| 1738 |
+
ios_base::openmode which
|
| 1739 |
+
= ios_base::in | ios_base::out);
|
| 1740 |
pos_type pubseekpos(pos_type sp,
|
| 1741 |
+
ios_base::openmode which
|
| 1742 |
+
= ios_base::in | ios_base::out);
|
| 1743 |
int pubsync();
|
| 1744 |
|
| 1745 |
+
// Get and put areas
|
| 1746 |
+
// [streambuf.pub.get], get area
|
| 1747 |
streamsize in_avail();
|
| 1748 |
int_type snextc();
|
| 1749 |
int_type sbumpc();
|
| 1750 |
int_type sgetc();
|
| 1751 |
streamsize sgetn(char_type* s, streamsize n);
|
| 1752 |
|
| 1753 |
+
// [streambuf.pub.pback], putback
|
| 1754 |
int_type sputbackc(char_type c);
|
| 1755 |
int_type sungetc();
|
| 1756 |
|
| 1757 |
+
// [streambuf.pub.put], put area
|
| 1758 |
int_type sputc(char_type c);
|
| 1759 |
streamsize sputn(const char_type* s, streamsize n);
|
| 1760 |
|
| 1761 |
protected:
|
| 1762 |
basic_streambuf();
|
| 1763 |
basic_streambuf(const basic_streambuf& rhs);
|
| 1764 |
basic_streambuf& operator=(const basic_streambuf& rhs);
|
| 1765 |
|
| 1766 |
void swap(basic_streambuf& rhs);
|
| 1767 |
|
| 1768 |
+
// [streambuf.get.area], get area access
|
| 1769 |
char_type* eback() const;
|
| 1770 |
char_type* gptr() const;
|
| 1771 |
char_type* egptr() const;
|
| 1772 |
void gbump(int n);
|
| 1773 |
void setg(char_type* gbeg, char_type* gnext, char_type* gend);
|
| 1774 |
|
| 1775 |
+
// [streambuf.put.area], put area access
|
| 1776 |
char_type* pbase() const;
|
| 1777 |
char_type* pptr() const;
|
| 1778 |
char_type* epptr() const;
|
| 1779 |
void pbump(int n);
|
| 1780 |
void setp(char_type* pbeg, char_type* pend);
|
| 1781 |
|
| 1782 |
+
// [streambuf.virtuals], virtual functions
|
| 1783 |
+
// [streambuf.virt.locales], locales
|
| 1784 |
virtual void imbue(const locale& loc);
|
| 1785 |
|
| 1786 |
+
// [streambuf.virt.buffer], buffer management and positioning
|
| 1787 |
+
virtual basic_streambuf* setbuf(char_type* s, streamsize n);
|
|
|
|
| 1788 |
virtual pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 1789 |
+
ios_base::openmode which
|
| 1790 |
+
= ios_base::in | ios_base::out);
|
| 1791 |
virtual pos_type seekpos(pos_type sp,
|
| 1792 |
+
ios_base::openmode which
|
| 1793 |
+
= ios_base::in | ios_base::out);
|
| 1794 |
virtual int sync();
|
| 1795 |
|
| 1796 |
+
// [streambuf.virt.get], get area
|
| 1797 |
virtual streamsize showmanyc();
|
| 1798 |
virtual streamsize xsgetn(char_type* s, streamsize n);
|
| 1799 |
virtual int_type underflow();
|
| 1800 |
virtual int_type uflow();
|
| 1801 |
|
| 1802 |
+
// [streambuf.virt.pback], putback
|
| 1803 |
virtual int_type pbackfail(int_type c = traits::eof());
|
| 1804 |
|
| 1805 |
+
// [streambuf.virt.put], put area
|
| 1806 |
virtual streamsize xsputn(const char_type* s, streamsize n);
|
| 1807 |
virtual int_type overflow(int_type c = traits::eof());
|
| 1808 |
};
|
| 1809 |
}
|
| 1810 |
```
|
| 1811 |
|
| 1812 |
+
The class template `basic_streambuf` serves as an abstract base class
|
| 1813 |
+
for deriving various *stream buffers* whose objects each control two
|
| 1814 |
+
*character sequences*:
|
| 1815 |
|
| 1816 |
- a character *input sequence*;
|
| 1817 |
- a character *output sequence*.
|
| 1818 |
|
| 1819 |
#### `basic_streambuf` constructors <a id="streambuf.cons">[[streambuf.cons]]</a>
|
| 1820 |
|
| 1821 |
``` cpp
|
| 1822 |
basic_streambuf();
|
| 1823 |
```
|
| 1824 |
|
| 1825 |
+
*Effects:* Constructs an object of class
|
| 1826 |
+
`basic_streambuf<charT, traits>` and initializes:[^13]
|
| 1827 |
|
| 1828 |
- all its pointer member objects to null pointers,
|
| 1829 |
- the `getloc()` member to a copy the global locale, `locale()`, at the
|
| 1830 |
time of construction.
|
| 1831 |
|
|
|
|
| 1861 |
|
| 1862 |
``` cpp
|
| 1863 |
locale pubimbue(const locale& loc);
|
| 1864 |
```
|
| 1865 |
|
| 1866 |
+
*Postconditions:* `loc == getloc()`.
|
| 1867 |
|
| 1868 |
*Effects:* Calls `imbue(loc)`.
|
| 1869 |
|
| 1870 |
*Returns:* Previous value of `getloc()`.
|
| 1871 |
|
|
|
|
| 1880 |
call of `imbue()`) then it returns the previous value.
|
| 1881 |
|
| 1882 |
##### Buffer management and positioning <a id="streambuf.buffer">[[streambuf.buffer]]</a>
|
| 1883 |
|
| 1884 |
``` cpp
|
| 1885 |
+
basic_streambuf* pubsetbuf(char_type* s, streamsize n);
|
| 1886 |
```
|
| 1887 |
|
| 1888 |
*Returns:* `setbuf(s, n)`.
|
| 1889 |
|
| 1890 |
``` cpp
|
| 1891 |
pos_type pubseekoff(off_type off, ios_base::seekdir way,
|
| 1892 |
+
ios_base::openmode which
|
| 1893 |
+
= ios_base::in | ios_base::out);
|
| 1894 |
```
|
| 1895 |
|
| 1896 |
*Returns:* `seekoff(off, way, which)`.
|
| 1897 |
|
| 1898 |
``` cpp
|
| 1899 |
pos_type pubseekpos(pos_type sp,
|
| 1900 |
+
ios_base::openmode which
|
| 1901 |
+
= ios_base::in | ios_base::out);
|
| 1902 |
```
|
| 1903 |
|
| 1904 |
*Returns:* `seekpos(sp, which)`.
|
| 1905 |
|
| 1906 |
``` cpp
|
|
|
|
| 1953 |
``` cpp
|
| 1954 |
int_type sputbackc(char_type c);
|
| 1955 |
```
|
| 1956 |
|
| 1957 |
*Returns:* If the input sequence putback position is not available, or
|
| 1958 |
+
if `traits::eq(c, gptr()[-1])` is `false`, returns
|
| 1959 |
`pbackfail(traits::to_int_type(c))`. Otherwise, decrements the next
|
| 1960 |
pointer for the input sequence and returns
|
| 1961 |
`traits::to_int_type(*gptr())`.
|
| 1962 |
|
| 1963 |
``` cpp
|
|
|
|
| 2141 |
*Effects:* Synchronizes the controlled sequences with the arrays. That
|
| 2142 |
is, if `pbase()` is non-null the characters between `pbase()` and
|
| 2143 |
`pptr()` are written to the controlled sequence. The pointers may then
|
| 2144 |
be reset as appropriate.
|
| 2145 |
|
| 2146 |
+
*Returns:* `-1` on failure. What constitutes failure is determined by
|
| 2147 |
+
each derived class ([[filebuf.virtuals]]).
|
| 2148 |
|
| 2149 |
*Default behavior:* Returns zero.
|
| 2150 |
|
| 2151 |
##### Get area <a id="streambuf.virt.get">[[streambuf.virt.get]]</a>
|
| 2152 |
|
|
|
|
| 2190 |
*Returns:* `traits::to_int_type(c)`, where `c` is the first *character*
|
| 2191 |
of the *pending sequence*, without moving the input sequence position
|
| 2192 |
past it. If the pending sequence is null then the function returns
|
| 2193 |
`traits::eof()` to indicate failure.
|
| 2194 |
|
| 2195 |
+
The *pending sequence* of characters is defined as the concatenation of
|
| 2196 |
|
| 2197 |
+
- the empty sequence if `gptr()` is null, otherwise the characters in
|
| 2198 |
+
\[`gptr()`, `egptr()`), followed by
|
| 2199 |
+
- some (possibly empty) sequence of characters read from the input
|
| 2200 |
+
sequence.
|
| 2201 |
|
| 2202 |
+
The *result character* is the first character of the pending sequence if
|
| 2203 |
+
it is non-empty, otherwise the next character that would be read from
|
| 2204 |
+
the input sequence.
|
| 2205 |
|
| 2206 |
+
The *backup sequence* is the empty sequence if `eback()` is null,
|
| 2207 |
+
otherwise the characters in \[`eback()`, `gptr()`).
|
| 2208 |
+
|
| 2209 |
+
*Effects:* The function sets up the `gptr()` and `egptr()` such that if
|
| 2210 |
+
the pending sequence is non-empty, then `egptr()` is non-null and the
|
| 2211 |
+
characters in \[`gptr()`, `egptr()`) are the characters in the pending
|
| 2212 |
+
sequence, otherwise either `gptr()` is null or `gptr() == egptr()`.
|
| 2213 |
|
| 2214 |
If `eback()` and `gptr()` are non-null then the function is not
|
| 2215 |
constrained as to their contents, but the “usual backup condition” is
|
| 2216 |
+
that either
|
| 2217 |
+
|
| 2218 |
+
- the backup sequence contains at least `gptr() - eback()` characters,
|
| 2219 |
+
in which case the characters in \[`eback()`, `gptr()`) agree with the
|
| 2220 |
+
last `gptr() - eback()` characters of the backup sequence, or
|
| 2221 |
+
- the characters in \[`gptr() - n`, `gptr()`) agree with the backup
|
| 2222 |
+
sequence (where `n` is the length of the backup sequence).
|
| 2223 |
|
| 2224 |
*Default behavior:* Returns `traits::eof()`.
|
| 2225 |
|
| 2226 |
``` cpp
|
| 2227 |
int_type uflow();
|
|
|
|
| 2254 |
modifications that
|
| 2255 |
|
| 2256 |
- If `traits::eq_int_type(c, traits::eof())` returns `true`, then the
|
| 2257 |
input sequence is backed up one character before the pending sequence
|
| 2258 |
is determined.
|
| 2259 |
+
- If `traits::eq_int_type(c, traits::eof())` returns `false`, then `c`
|
| 2260 |
+
is prepended. Whether the input sequence is backed up or modified in
|
| 2261 |
+
any other way is unspecified.
|
| 2262 |
|
| 2263 |
+
*Postconditions:* On return, the constraints of `gptr()`, `eback()`, and
|
| 2264 |
+
`pptr()` are the same as for `underflow()`.
|
| 2265 |
|
| 2266 |
*Returns:* `traits::eof()` to indicate failure. Failure may occur
|
| 2267 |
because the input sequence could not be backed up, or if for some other
|
| 2268 |
reason the pointers could not be set consistent with the constraints.
|
| 2269 |
`pbackfail()` is called only when put back has really failed.
|
|
|
|
| 2280 |
|
| 2281 |
*Effects:* Writes up to `n` characters to the output sequence as if by
|
| 2282 |
repeated calls to `sputc(c)`. The characters written are obtained from
|
| 2283 |
successive elements of the array whose first element is designated by
|
| 2284 |
`s`. Writing stops when either `n` characters have been written or a
|
| 2285 |
+
call to `sputc(c)` would return `traits::eof()`. It is unspecified
|
| 2286 |
whether the function calls `overflow()` when `pptr() == epptr()` becomes
|
| 2287 |
+
`true` or whether it achieves the same effects by other means.
|
| 2288 |
|
| 2289 |
*Returns:* The number of characters written.
|
| 2290 |
|
| 2291 |
``` cpp
|
| 2292 |
int_type overflow(int_type c = traits::eof());
|
|
|
|
| 2294 |
|
| 2295 |
*Effects:* Consumes some initial subsequence of the characters of the
|
| 2296 |
*pending sequence*. The pending sequence is defined as the concatenation
|
| 2297 |
of
|
| 2298 |
|
| 2299 |
+
- the empty sequence if `pbase()` is not null, otherwise the
|
| 2300 |
+
`pptr() - pbase()` characters beginning at `pbase()`, followed by
|
| 2301 |
+
- the empty sequence if `traits::eq_int_type(c, traits::eof())` returns
|
| 2302 |
+
`true`, otherwise the sequence consisting of `c`.
|
| 2303 |
+
|
| 2304 |
*Remarks:* The member functions `sputc()` and `sputn()` call this
|
| 2305 |
function in case that no room can be found in the put buffer enough to
|
| 2306 |
accommodate the argument character sequence.
|
| 2307 |
|
| 2308 |
*Requires:* Every overriding definition of this virtual function shall
|
| 2309 |
obey the following constraints:
|
| 2310 |
|
| 2311 |
+
1. The effect of consuming a character on the associated output
|
| 2312 |
+
sequence is specified[^16]
|
| 2313 |
+
2. Let `r` be the number of characters in the pending sequence not
|
| 2314 |
+
consumed. If `r` is nonzero then `pbase()` and `pptr()` shall be set
|
| 2315 |
+
so that: `pptr() - pbase() == r` and the `r` characters starting at
|
| 2316 |
+
`pbase()` are the associated output stream. In case `r` is zero (all
|
| 2317 |
+
characters of the pending sequence have been consumed) then either
|
| 2318 |
+
`pbase()` is set to `nullptr`, or `pbase()` and `pptr()` are both
|
| 2319 |
+
set to the same non-null value.
|
| 2320 |
+
3. The function may fail if either appending some character to the
|
| 2321 |
+
associated output stream fails or if it is unable to establish
|
| 2322 |
+
`pbase()` and `pptr()` according to the above rules.
|
| 2323 |
+
|
| 2324 |
*Returns:* `traits::eof()` or throws an exception if the function fails.
|
| 2325 |
|
| 2326 |
Otherwise, returns some value other than `traits::eof()` to indicate
|
| 2327 |
+
success.[^17]
|
| 2328 |
|
| 2329 |
*Default behavior:* Returns `traits::eof()`.
|
| 2330 |
|
| 2331 |
## Formatting and manipulators <a id="iostream.format">[[iostream.format]]</a>
|
| 2332 |
|
| 2333 |
+
### Header `<istream>` synopsis <a id="istream.syn">[[istream.syn]]</a>
|
|
|
|
|
|
|
| 2334 |
|
| 2335 |
``` cpp
|
| 2336 |
namespace std {
|
| 2337 |
template <class charT, class traits = char_traits<charT>>
|
| 2338 |
class basic_istream;
|
| 2339 |
+
|
| 2340 |
+
using istream = basic_istream<char>;
|
| 2341 |
+
using wistream = basic_istream<wchar_t>;
|
| 2342 |
|
| 2343 |
template <class charT, class traits = char_traits<charT>>
|
| 2344 |
class basic_iostream;
|
| 2345 |
+
|
| 2346 |
+
using iostream = basic_iostream<char>;
|
| 2347 |
+
using wiostream = basic_iostream<wchar_t>;
|
| 2348 |
|
| 2349 |
template <class charT, class traits>
|
| 2350 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 2351 |
|
| 2352 |
template <class charT, class traits, class T>
|
| 2353 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);
|
|
|
|
| 2354 |
}
|
| 2355 |
```
|
| 2356 |
|
| 2357 |
+
### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
|
| 2358 |
+
|
| 2359 |
``` cpp
|
| 2360 |
namespace std {
|
| 2361 |
template <class charT, class traits = char_traits<charT>>
|
| 2362 |
class basic_ostream;
|
| 2363 |
+
|
| 2364 |
+
using ostream = basic_ostream<char>;
|
| 2365 |
+
using wostream = basic_ostream<wchar_t>;
|
| 2366 |
|
| 2367 |
template <class charT, class traits>
|
| 2368 |
basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
|
| 2369 |
template <class charT, class traits>
|
| 2370 |
basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
|
| 2371 |
template <class charT, class traits>
|
| 2372 |
basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
|
| 2373 |
|
| 2374 |
template <class charT, class traits, class T>
|
| 2375 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
|
|
|
|
| 2376 |
}
|
| 2377 |
```
|
| 2378 |
|
| 2379 |
+
### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
|
| 2380 |
+
|
| 2381 |
``` cpp
|
| 2382 |
namespace std {
|
| 2383 |
// types T1, T2, ... are unspecified implementation types
|
| 2384 |
T1 resetiosflags(ios_base::fmtflags mask);
|
| 2385 |
T2 setiosflags (ios_base::fmtflags mask);
|
|
|
|
| 2395 |
template <class charT>
|
| 2396 |
T11 quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
|
| 2397 |
|
| 2398 |
template <class charT, class traits, class Allocator>
|
| 2399 |
T12 quoted(const basic_string<charT, traits, Allocator>& s,
|
| 2400 |
+
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2401 |
|
| 2402 |
template <class charT, class traits, class Allocator>
|
| 2403 |
T13 quoted(basic_string<charT, traits, Allocator>& s,
|
| 2404 |
+
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2405 |
+
|
| 2406 |
+
template <class charT, class traits>
|
| 2407 |
+
T14 quoted(basic_string_view<charT, traits> s,
|
| 2408 |
+
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 2409 |
}
|
| 2410 |
```
|
| 2411 |
|
| 2412 |
### Input streams <a id="input.streams">[[input.streams]]</a>
|
| 2413 |
|
|
|
|
| 2421 |
namespace std {
|
| 2422 |
template <class charT, class traits = char_traits<charT>>
|
| 2423 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 2424 |
public:
|
| 2425 |
// types (inherited from basic_ios ([ios])):
|
| 2426 |
+
using char_type = charT;
|
| 2427 |
+
using int_type = typename traits::int_type;
|
| 2428 |
+
using pos_type = typename traits::pos_type;
|
| 2429 |
+
using off_type = typename traits::off_type;
|
| 2430 |
+
using traits_type = traits;
|
| 2431 |
|
| 2432 |
+
// [istream.cons], constructor/destructor
|
| 2433 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2434 |
virtual ~basic_istream();
|
| 2435 |
|
| 2436 |
+
// [istream::sentry], prefix/suffix
|
| 2437 |
class sentry;
|
| 2438 |
|
| 2439 |
+
// [istream.formatted], formatted input
|
| 2440 |
+
basic_istream<charT, traits>&
|
| 2441 |
+
operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
|
| 2442 |
+
basic_istream<charT, traits>&
|
| 2443 |
+
operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 2444 |
+
basic_istream<charT, traits>&
|
| 2445 |
+
operator>>(ios_base& (*pf)(ios_base&));
|
| 2446 |
|
| 2447 |
basic_istream<charT, traits>& operator>>(bool& n);
|
| 2448 |
basic_istream<charT, traits>& operator>>(short& n);
|
| 2449 |
basic_istream<charT, traits>& operator>>(unsigned short& n);
|
| 2450 |
basic_istream<charT, traits>& operator>>(int& n);
|
|
|
|
| 2456 |
basic_istream<charT, traits>& operator>>(float& f);
|
| 2457 |
basic_istream<charT, traits>& operator>>(double& f);
|
| 2458 |
basic_istream<charT, traits>& operator>>(long double& f);
|
| 2459 |
|
| 2460 |
basic_istream<charT, traits>& operator>>(void*& p);
|
| 2461 |
+
basic_istream<charT, traits>& operator>>(basic_streambuf<char_type, traits>* sb);
|
|
|
|
| 2462 |
|
| 2463 |
+
// [istream.unformatted], unformatted input
|
| 2464 |
streamsize gcount() const;
|
| 2465 |
int_type get();
|
| 2466 |
basic_istream<charT, traits>& get(char_type& c);
|
| 2467 |
basic_istream<charT, traits>& get(char_type* s, streamsize n);
|
| 2468 |
+
basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
|
|
|
|
| 2469 |
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
|
| 2470 |
+
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
|
|
|
|
| 2471 |
|
| 2472 |
basic_istream<charT, traits>& getline(char_type* s, streamsize n);
|
| 2473 |
+
basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
|
|
|
|
| 2474 |
|
| 2475 |
+
basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
|
|
|
|
| 2476 |
int_type peek();
|
| 2477 |
basic_istream<charT, traits>& read (char_type* s, streamsize n);
|
| 2478 |
streamsize readsome(char_type* s, streamsize n);
|
| 2479 |
|
| 2480 |
basic_istream<charT, traits>& putback(char_type c);
|
|
|
|
| 2484 |
pos_type tellg();
|
| 2485 |
basic_istream<charT, traits>& seekg(pos_type);
|
| 2486 |
basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
|
| 2487 |
|
| 2488 |
protected:
|
| 2489 |
+
// [istream.cons], copy/move constructor
|
| 2490 |
basic_istream(const basic_istream& rhs) = delete;
|
| 2491 |
basic_istream(basic_istream&& rhs);
|
| 2492 |
|
| 2493 |
+
// [istream.assign], assign and swap
|
| 2494 |
basic_istream& operator=(const basic_istream& rhs) = delete;
|
| 2495 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2496 |
void swap(basic_istream& rhs);
|
| 2497 |
};
|
| 2498 |
|
| 2499 |
+
// [istream.extractors], character extraction templates
|
| 2500 |
template<class charT, class traits>
|
| 2501 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT&);
|
|
|
|
| 2502 |
template<class traits>
|
| 2503 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char&);
|
|
|
|
| 2504 |
template<class traits>
|
| 2505 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char&);
|
|
|
|
| 2506 |
|
| 2507 |
template<class charT, class traits>
|
| 2508 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT*);
|
|
|
|
| 2509 |
template<class traits>
|
| 2510 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char*);
|
|
|
|
| 2511 |
template<class traits>
|
| 2512 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char*);
|
|
|
|
| 2513 |
}
|
| 2514 |
```
|
| 2515 |
|
| 2516 |
+
The class template `basic_istream` defines a number of member function
|
| 2517 |
+
signatures that assist in reading and interpreting input from sequences
|
| 2518 |
+
controlled by a stream buffer.
|
| 2519 |
|
| 2520 |
Two groups of member function signatures share common properties: the
|
| 2521 |
*formatted input functions* (or *extractors*) and the *unformatted input
|
| 2522 |
functions.* Both groups of input functions are described as if they
|
| 2523 |
obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
|
|
|
|
| 2539 |
|
| 2540 |
``` cpp
|
| 2541 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 2542 |
```
|
| 2543 |
|
| 2544 |
+
*Effects:* Constructs an object of class `basic_istream`, initializing
|
| 2545 |
+
the base class subobject with
|
| 2546 |
`basic_ios::init(sb)` ([[basic.ios.cons]]).
|
| 2547 |
|
| 2548 |
+
*Postconditions:* `gcount() == 0`.
|
| 2549 |
|
| 2550 |
``` cpp
|
| 2551 |
basic_istream(basic_istream&& rhs);
|
| 2552 |
```
|
| 2553 |
|
|
|
|
| 2568 |
|
| 2569 |
``` cpp
|
| 2570 |
basic_istream& operator=(basic_istream&& rhs);
|
| 2571 |
```
|
| 2572 |
|
| 2573 |
+
*Effects:* As if by `swap(rhs)`.
|
| 2574 |
|
| 2575 |
*Returns:* `*this`.
|
| 2576 |
|
| 2577 |
``` cpp
|
| 2578 |
void swap(basic_istream& rhs);
|
|
|
|
| 2585 |
|
| 2586 |
``` cpp
|
| 2587 |
namespace std {
|
| 2588 |
template <class charT, class traits = char_traits<charT>>
|
| 2589 |
class basic_istream<charT, traits>::sentry {
|
| 2590 |
+
using traits_type = traits;
|
| 2591 |
bool ok_; // exposition only
|
| 2592 |
public:
|
| 2593 |
explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
|
| 2594 |
~sentry();
|
| 2595 |
explicit operator bool() const { return ok_; }
|
|
|
|
| 2612 |
to synchronize the output sequence with any associated external C
|
| 2613 |
stream. Except that this call can be suppressed if the put area of
|
| 2614 |
`is.tie()` is empty. Further an implementation is allowed to defer the
|
| 2615 |
call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
|
| 2616 |
such call occurs before the `sentry` object is destroyed, the call to
|
| 2617 |
+
`flush` may be eliminated entirely.[^18] If `noskipws` is zero and
|
| 2618 |
`is.flags() & ios_base::skipws` is nonzero, the function extracts and
|
| 2619 |
discards each character as long as the next available input character
|
| 2620 |
`c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
|
| 2621 |
`is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
|
| 2622 |
`setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
|
| 2623 |
|
| 2624 |
*Remarks:* The constructor
|
| 2625 |
+
|
| 2626 |
+
``` cpp
|
| 2627 |
+
explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false)
|
| 2628 |
+
```
|
| 2629 |
+
|
| 2630 |
uses the currently imbued locale in `is`, to determine whether the next
|
| 2631 |
input character is whitespace or not.
|
| 2632 |
|
| 2633 |
To decide if the character `c` is a whitespace character, the
|
| 2634 |
constructor performs as if it executes the following code fragment:
|
|
|
|
| 2640 |
```
|
| 2641 |
|
| 2642 |
If, after any preparation is completed, `is.good()` is `true`,
|
| 2643 |
`ok_ != false` otherwise, `ok_ == false`. During preparation, the
|
| 2644 |
constructor may call `setstate(failbit)` (which may throw
|
| 2645 |
+
`ios_base::failure` ([[iostate.flags]]))[^19]
|
| 2646 |
|
| 2647 |
``` cpp
|
| 2648 |
~sentry();
|
| 2649 |
```
|
| 2650 |
|
|
|
|
| 2662 |
|
| 2663 |
Each formatted input function begins execution by constructing an object
|
| 2664 |
of class `sentry` with the `noskipws` (second) argument `false`. If the
|
| 2665 |
`sentry` object returns `true`, when converted to a value of type
|
| 2666 |
`bool`, the function endeavors to obtain the requested input. If an
|
| 2667 |
+
exception is thrown during input then `ios::badbit` is turned on[^20] in
|
| 2668 |
`*this`’s error state. If `(exceptions()&badbit) != 0` then the
|
| 2669 |
exception is rethrown. In any case, the formatted input function
|
| 2670 |
destroys the `sentry` object. If no exception has been thrown, it
|
| 2671 |
returns `*this`.
|
| 2672 |
|
|
|
|
| 2692 |
described in [[istream.formatted.reqmts]]). After a sentry object is
|
| 2693 |
constructed, the conversion occurs as if performed by the following code
|
| 2694 |
fragment:
|
| 2695 |
|
| 2696 |
``` cpp
|
| 2697 |
+
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2698 |
iostate err = iostate::goodbit;
|
| 2699 |
use_facet<numget>(loc).get(*this, 0, *this, err, val);
|
| 2700 |
setstate(err);
|
| 2701 |
```
|
| 2702 |
|
| 2703 |
In the above fragment, `loc` stands for the private member of the
|
| 2704 |
+
`basic_ios` class.
|
| 2705 |
+
|
| 2706 |
+
[*Note 1*: The first argument provides an object of the
|
| 2707 |
`istreambuf_iterator` class which is an iterator pointed to an input
|
| 2708 |
+
stream. It bypasses istreams and uses streambufs
|
| 2709 |
+
directly. — *end note*]
|
| 2710 |
+
|
| 2711 |
+
Class `locale` relies on this type as its interface to `istream`, so
|
| 2712 |
+
that it does not need to depend directly on `istream`.
|
| 2713 |
|
| 2714 |
``` cpp
|
| 2715 |
operator>>(short& val);
|
| 2716 |
```
|
| 2717 |
|
| 2718 |
The conversion occurs as if performed by the following code fragment
|
| 2719 |
(using the same notation as for the preceding code fragment):
|
| 2720 |
|
| 2721 |
``` cpp
|
| 2722 |
+
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2723 |
iostate err = ios_base::goodbit;
|
| 2724 |
long lval;
|
| 2725 |
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
|
| 2726 |
if (lval < numeric_limits<short>::min()) {
|
| 2727 |
err |= ios_base::failbit;
|
|
|
|
| 2740 |
|
| 2741 |
The conversion occurs as if performed by the following code fragment
|
| 2742 |
(using the same notation as for the preceding code fragment):
|
| 2743 |
|
| 2744 |
``` cpp
|
| 2745 |
+
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 2746 |
iostate err = ios_base::goodbit;
|
| 2747 |
long lval;
|
| 2748 |
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
|
| 2749 |
if (lval < numeric_limits<int>::min()) {
|
| 2750 |
err |= ios_base::failbit;
|
|
|
|
| 2755 |
} else
|
| 2756 |
val = static_cast<int>(lval);
|
| 2757 |
setstate(err);
|
| 2758 |
```
|
| 2759 |
|
| 2760 |
+
##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
|
| 2761 |
|
| 2762 |
``` cpp
|
| 2763 |
+
basic_istream<charT, traits>&
|
| 2764 |
+
operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
|
| 2765 |
```
|
| 2766 |
|
| 2767 |
*Effects:* None. This extractor does not behave as a formatted input
|
| 2768 |
+
function (as described in [[istream.formatted.reqmts]]).
|
| 2769 |
|
| 2770 |
+
*Returns:* `pf(*this)`.[^21]
|
| 2771 |
|
| 2772 |
``` cpp
|
| 2773 |
+
basic_istream<charT, traits>&
|
| 2774 |
+
operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 2775 |
```
|
| 2776 |
|
| 2777 |
*Effects:* Calls `pf(*this)`. This extractor does not behave as a
|
| 2778 |
formatted input function (as described
|
| 2779 |
in [[istream.formatted.reqmts]]).
|
| 2780 |
|
| 2781 |
*Returns:* `*this`.
|
| 2782 |
|
| 2783 |
``` cpp
|
| 2784 |
+
basic_istream<charT, traits>& operator>>(ios_base& (*pf)(ios_base&));
|
|
|
|
| 2785 |
```
|
| 2786 |
|
| 2787 |
+
*Effects:* Calls `pf(*this)`.[^22] This extractor does not behave as a
|
| 2788 |
formatted input function (as described
|
| 2789 |
in [[istream.formatted.reqmts]]).
|
| 2790 |
|
| 2791 |
*Returns:* `*this`.
|
| 2792 |
|
| 2793 |
``` cpp
|
| 2794 |
template<class charT, class traits>
|
| 2795 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT* s);
|
|
|
|
| 2796 |
template<class traits>
|
| 2797 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char* s);
|
|
|
|
| 2798 |
template<class traits>
|
| 2799 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char* s);
|
|
|
|
| 2800 |
```
|
| 2801 |
|
| 2802 |
*Effects:* Behaves like a formatted input member (as described
|
| 2803 |
in [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
|
| 2804 |
constructed, `operator>>` extracts characters and stores them into
|
|
|
|
| 2810 |
|
| 2811 |
Characters are extracted and stored until any of the following occurs:
|
| 2812 |
|
| 2813 |
- `n-1` characters are stored;
|
| 2814 |
- end of file occurs on the input sequence;
|
| 2815 |
+
- letting `ct` be `use_facet<ctype<charT>>(in.getloc())`,
|
| 2816 |
+
`ct.is(ct.space, c)` is `true`.
|
| 2817 |
|
| 2818 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 2819 |
which may be the first position if no characters were extracted.
|
| 2820 |
`operator>>` then calls `width(0)`.
|
| 2821 |
|
|
|
|
| 2824 |
|
| 2825 |
*Returns:* `in`.
|
| 2826 |
|
| 2827 |
``` cpp
|
| 2828 |
template<class charT, class traits>
|
| 2829 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT& c);
|
|
|
|
| 2830 |
template<class traits>
|
| 2831 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char& c);
|
|
|
|
| 2832 |
template<class traits>
|
| 2833 |
+
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
|
|
|
|
| 2834 |
```
|
| 2835 |
|
| 2836 |
*Effects:* Behaves like a formatted input member (as described
|
| 2837 |
in [[istream.formatted.reqmts]]) of `in`. After a `sentry` object is
|
| 2838 |
constructed a character is extracted from `in`, if one is available, and
|
| 2839 |
stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
|
| 2840 |
|
| 2841 |
*Returns:* `in`.
|
| 2842 |
|
| 2843 |
``` cpp
|
| 2844 |
+
basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
|
|
|
|
| 2845 |
```
|
| 2846 |
|
| 2847 |
+
*Effects:* Behaves as an unformatted input function
|
| 2848 |
+
([[istream.unformatted]]). If `sb` is null, calls `setstate(failbit)`,
|
| 2849 |
+
which may throw `ios_base::failure` ([[iostate.flags]]). After a sentry
|
| 2850 |
+
object is constructed, extracts characters from `*this` and inserts them
|
| 2851 |
+
in the output sequence controlled by `sb`. Characters are extracted and
|
|
|
|
| 2852 |
inserted until any of the following occurs:
|
| 2853 |
|
| 2854 |
- end-of-file occurs on the input sequence;
|
| 2855 |
- inserting in the output sequence fails (in which case the character to
|
| 2856 |
be inserted is not extracted);
|
|
|
|
| 2870 |
Each unformatted input function begins execution by constructing an
|
| 2871 |
object of class `sentry` with the default argument `noskipws` (second)
|
| 2872 |
argument `true`. If the `sentry` object returns `true`, when converted
|
| 2873 |
to a value of type `bool`, the function endeavors to obtain the
|
| 2874 |
requested input. Otherwise, if the sentry constructor exits by throwing
|
| 2875 |
+
an exception or if the sentry object returns `false`, when converted to
|
| 2876 |
+
a value of type `bool`, the function returns without attempting to
|
| 2877 |
+
obtain any input. In either case the number of extracted characters is
|
| 2878 |
+
set to 0; unformatted input functions taking a character array of
|
| 2879 |
+
nonzero size as an argument shall also store a null character (using
|
| 2880 |
+
`charT()`) in the first location of the array. If an exception is thrown
|
| 2881 |
+
during input then `ios::badbit` is turned on[^23] in `*this`’s error
|
| 2882 |
+
state. (Exceptions thrown from `basic_ios<>::clear()` are not caught or
|
| 2883 |
rethrown.) If `(exceptions()&badbit) != 0` then the exception is
|
| 2884 |
rethrown. It also counts the number of characters extracted. If no
|
| 2885 |
exception has been thrown it ends by storing the count in a member
|
| 2886 |
object and returning the value specified. In any event the `sentry`
|
| 2887 |
object is destroyed before leaving the unformatted input function.
|
|
|
|
| 2889 |
``` cpp
|
| 2890 |
streamsize gcount() const;
|
| 2891 |
```
|
| 2892 |
|
| 2893 |
*Effects:* None. This member function does not behave as an unformatted
|
| 2894 |
+
input function (as described above).
|
| 2895 |
|
| 2896 |
*Returns:* The number of characters extracted by the last unformatted
|
| 2897 |
input member function called for the object.
|
| 2898 |
|
| 2899 |
``` cpp
|
| 2900 |
int_type get();
|
| 2901 |
```
|
| 2902 |
|
| 2903 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2904 |
+
above). After constructing a sentry object, extracts a character `c`, if
|
| 2905 |
+
one is available. Otherwise, the function calls `setstate(failbit)`,
|
| 2906 |
+
which may throw `ios_base::failure` ([[iostate.flags]]),
|
|
|
|
| 2907 |
|
| 2908 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 2909 |
|
| 2910 |
``` cpp
|
| 2911 |
basic_istream<charT, traits>& get(char_type& c);
|
| 2912 |
```
|
| 2913 |
|
| 2914 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2915 |
+
above). After constructing a sentry object, extracts a character, if one
|
| 2916 |
+
is available, and assigns it to `c`.[^24] Otherwise, the function calls
|
| 2917 |
+
`setstate(failbit)` (which may throw
|
| 2918 |
+
`ios_base::failure` ([[iostate.flags]])).
|
| 2919 |
|
| 2920 |
*Returns:* `*this`.
|
| 2921 |
|
| 2922 |
``` cpp
|
| 2923 |
+
basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
|
|
|
|
| 2924 |
```
|
| 2925 |
|
| 2926 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2927 |
+
above). After constructing a sentry object, extracts characters and
|
| 2928 |
+
stores them into successive locations of an array whose first element is
|
| 2929 |
+
designated by `s`.[^25] Characters are extracted and stored until any of
|
| 2930 |
+
the following occurs:
|
| 2931 |
|
| 2932 |
- `n` is less than one or `n - 1` characters are stored;
|
| 2933 |
- end-of-file occurs on the input sequence (in which case the function
|
| 2934 |
calls `setstate(eofbit)`);
|
| 2935 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
|
|
|
| 2944 |
|
| 2945 |
``` cpp
|
| 2946 |
basic_istream<charT, traits>& get(char_type* s, streamsize n);
|
| 2947 |
```
|
| 2948 |
|
| 2949 |
+
*Effects:* Calls `get(s, n, widen(’\n’))`.
|
| 2950 |
|
| 2951 |
*Returns:* Value returned by the call.
|
| 2952 |
|
| 2953 |
``` cpp
|
| 2954 |
+
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
|
|
|
|
| 2955 |
```
|
| 2956 |
|
| 2957 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2958 |
+
above). After constructing a sentry object, extracts characters and
|
| 2959 |
+
inserts them in the output sequence controlled by `sb`. Characters are
|
| 2960 |
+
extracted and inserted until any of the following occurs:
|
|
|
|
| 2961 |
|
| 2962 |
- end-of-file occurs on the input sequence;
|
| 2963 |
- inserting in the output sequence fails (in which case the character to
|
| 2964 |
be inserted is not extracted);
|
| 2965 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
|
|
|
| 2974 |
|
| 2975 |
``` cpp
|
| 2976 |
basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
|
| 2977 |
```
|
| 2978 |
|
| 2979 |
+
*Effects:* Calls `get(sb, widen(’\n’))`.
|
| 2980 |
|
| 2981 |
*Returns:* Value returned by the call.
|
| 2982 |
|
| 2983 |
``` cpp
|
| 2984 |
+
basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
|
|
|
|
| 2985 |
```
|
| 2986 |
|
| 2987 |
*Effects:* Behaves as an unformatted input function (as described
|
| 2988 |
+
above). After constructing a sentry object, extracts characters and
|
| 2989 |
+
stores them into successive locations of an array whose first element is
|
| 2990 |
+
designated by `s`.[^26] Characters are extracted and stored until one of
|
| 2991 |
+
the following occurs:
|
| 2992 |
|
| 2993 |
1. end-of-file occurs on the input sequence (in which case the function
|
| 2994 |
calls `setstate(eofbit)`);
|
| 2995 |
2. `traits::eq(c, delim)` for the next available input character `c`
|
| 2996 |
(in which case the input character is extracted but not
|
| 2997 |
+
stored);[^27]
|
| 2998 |
3. `n` is less than one or `n - 1` characters are stored (in which case
|
| 2999 |
the function calls `setstate(failbit)`).
|
| 3000 |
|
| 3001 |
+
These conditions are tested in the order shown.[^28]
|
| 3002 |
|
| 3003 |
If the function extracts no characters, it calls `setstate(failbit)`
|
| 3004 |
+
(which may throw `ios_base::failure` ([[iostate.flags]])).[^29]
|
| 3005 |
|
| 3006 |
In any case, if `n` is greater than zero, it then stores a null
|
| 3007 |
character (using `charT()`) into the next successive location of the
|
| 3008 |
array.
|
| 3009 |
|
| 3010 |
*Returns:* `*this`.
|
| 3011 |
|
| 3012 |
+
[*Example 1*:
|
| 3013 |
+
|
| 3014 |
``` cpp
|
| 3015 |
#include <iostream>
|
| 3016 |
|
| 3017 |
int main() {
|
| 3018 |
using namespace std;
|
|
|
|
| 3034 |
cout << " (" << count << " chars): " << buffer << endl;
|
| 3035 |
}
|
| 3036 |
}
|
| 3037 |
```
|
| 3038 |
|
| 3039 |
+
— *end example*]
|
| 3040 |
+
|
| 3041 |
``` cpp
|
| 3042 |
basic_istream<charT, traits>& getline(char_type* s, streamsize n);
|
| 3043 |
```
|
| 3044 |
|
| 3045 |
*Returns:* `getline(s, n, widen(’\n’))`
|
| 3046 |
|
| 3047 |
``` cpp
|
| 3048 |
+
basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
|
|
|
|
| 3049 |
```
|
| 3050 |
|
| 3051 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3052 |
+
above). After constructing a sentry object, extracts characters and
|
| 3053 |
+
discards them. Characters are extracted until any of the following
|
| 3054 |
+
occurs:
|
| 3055 |
|
| 3056 |
+
- `n != numeric_limits<streamsize>::max()` ([[numeric.limits]]) and `n`
|
| 3057 |
characters have been extracted so far
|
| 3058 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3059 |
calls `setstate(eofbit)`, which may throw
|
| 3060 |
`ios_base::failure` ([[iostate.flags]]));
|
| 3061 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
|
|
|
| 3069 |
``` cpp
|
| 3070 |
int_type peek();
|
| 3071 |
```
|
| 3072 |
|
| 3073 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3074 |
+
above). After constructing a sentry object, reads but does not extract
|
| 3075 |
+
the current input character.
|
| 3076 |
|
| 3077 |
*Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
|
| 3078 |
`rdbuf()->sgetc()`.
|
| 3079 |
|
| 3080 |
``` cpp
|
| 3081 |
basic_istream<charT, traits>& read(char_type* s, streamsize n);
|
| 3082 |
```
|
| 3083 |
|
| 3084 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3085 |
+
above). After constructing a sentry object, if `!good()` calls
|
| 3086 |
+
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3087 |
+
extracts characters and stores them into successive locations of an
|
| 3088 |
+
array whose first element is designated by `s`.[^30] Characters are
|
| 3089 |
+
extracted and stored until either of the following occurs:
|
|
|
|
| 3090 |
|
| 3091 |
- `n` characters are stored;
|
| 3092 |
- end-of-file occurs on the input sequence (in which case the function
|
| 3093 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 3094 |
`ios_base::failure` ([[iostate.flags]])).
|
|
|
|
| 3098 |
``` cpp
|
| 3099 |
streamsize readsome(char_type* s, streamsize n);
|
| 3100 |
```
|
| 3101 |
|
| 3102 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3103 |
+
above). After constructing a sentry object, if `!good()` calls
|
| 3104 |
+
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 3105 |
+
extracts characters and stores them into successive locations of an
|
| 3106 |
+
array whose first element is designated by `s`. If
|
| 3107 |
+
`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
|
| 3108 |
+
`ios_base::failure` ([[iostate.flags]])), and extracts no characters;
|
|
|
|
| 3109 |
|
| 3110 |
- If `rdbuf()->in_avail() == 0`, extracts no characters
|
| 3111 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 3112 |
|
| 3113 |
*Returns:* The number of characters extracted.
|
|
|
|
| 3115 |
``` cpp
|
| 3116 |
basic_istream<charT, traits>& putback(char_type c);
|
| 3117 |
```
|
| 3118 |
|
| 3119 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3120 |
+
above), except that the function first clears `eofbit`. After
|
| 3121 |
+
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3122 |
+
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3123 |
+
calls `rdbuf->sputbackc()`. If `rdbuf()` is null, or if `sputbackc()`
|
| 3124 |
+
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3125 |
+
`ios_base::failure` ([[iostate.flags]])).
|
| 3126 |
+
|
| 3127 |
+
[*Note 1*: This function extracts no characters, so the value returned
|
| 3128 |
+
by the next call to `gcount()` is 0. — *end note*]
|
| 3129 |
|
| 3130 |
*Returns:* `*this`.
|
| 3131 |
|
| 3132 |
``` cpp
|
| 3133 |
basic_istream<charT, traits>& unget();
|
| 3134 |
```
|
| 3135 |
|
| 3136 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3137 |
+
above), except that the function first clears `eofbit`. After
|
| 3138 |
+
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 3139 |
+
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 3140 |
+
calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc()`
|
| 3141 |
+
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 3142 |
+
`ios_base::failure` ([[iostate.flags]])).
|
| 3143 |
+
|
| 3144 |
+
[*Note 2*: This function extracts no characters, so the value returned
|
| 3145 |
+
by the next call to `gcount()` is 0. — *end note*]
|
| 3146 |
|
| 3147 |
*Returns:* `*this`.
|
| 3148 |
|
| 3149 |
``` cpp
|
| 3150 |
int sync();
|
| 3151 |
```
|
| 3152 |
|
| 3153 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3154 |
+
above), except that it does not count the number of characters extracted
|
| 3155 |
+
and does not affect the value returned by subsequent calls to
|
| 3156 |
+
`gcount()`. After constructing a sentry object, if `rdbuf()` is a null
|
| 3157 |
+
pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
|
| 3158 |
+
that function returns `-1` calls `setstate(badbit)` (which may throw
|
|
|
|
| 3159 |
`ios_base::failure` ([[iostate.flags]]), and returns `-1`. Otherwise,
|
| 3160 |
returns zero.
|
| 3161 |
|
| 3162 |
``` cpp
|
| 3163 |
pos_type tellg();
|
| 3164 |
```
|
| 3165 |
|
| 3166 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3167 |
+
above), except that it does not count the number of characters extracted
|
| 3168 |
+
and does not affect the value returned by subsequent calls to
|
| 3169 |
+
`gcount()`.
|
| 3170 |
|
| 3171 |
*Returns:* After constructing a sentry object, if `fail() != false`,
|
| 3172 |
returns `pos_type(-1)` to indicate failure. Otherwise, returns
|
| 3173 |
`rdbuf()->pubseekoff(0, cur, in)`.
|
| 3174 |
|
| 3175 |
``` cpp
|
| 3176 |
basic_istream<charT, traits>& seekg(pos_type pos);
|
| 3177 |
```
|
| 3178 |
|
| 3179 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3180 |
+
above), except that the function first clears `eofbit`, it does not
|
| 3181 |
+
count the number of characters extracted, and it does not affect the
|
| 3182 |
+
value returned by subsequent calls to `gcount()`. After constructing a
|
| 3183 |
+
sentry object, if `fail() != true`, executes
|
| 3184 |
+
`rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
|
| 3185 |
+
function calls `setstate(failbit)` (which may throw
|
| 3186 |
`ios_base::failure`).
|
| 3187 |
|
| 3188 |
*Returns:* `*this`.
|
| 3189 |
|
| 3190 |
``` cpp
|
| 3191 |
basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
|
| 3192 |
```
|
| 3193 |
|
| 3194 |
*Effects:* Behaves as an unformatted input function (as described
|
| 3195 |
+
above), except that the function first clears `eofbit`, does not count
|
| 3196 |
+
the number of characters extracted, and does not affect the value
|
| 3197 |
returned by subsequent calls to `gcount()`. After constructing a sentry
|
| 3198 |
object, if `fail() != true`, executes
|
| 3199 |
`rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
|
| 3200 |
function calls `setstate(failbit)` (which may throw
|
| 3201 |
`ios_base::failure`).
|
|
|
|
| 3203 |
*Returns:* `*this`.
|
| 3204 |
|
| 3205 |
#### Standard `basic_istream` manipulators <a id="istream.manip">[[istream.manip]]</a>
|
| 3206 |
|
| 3207 |
``` cpp
|
|
|
|
| 3208 |
template <class charT, class traits>
|
| 3209 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
|
|
|
| 3210 |
```
|
| 3211 |
|
| 3212 |
+
*Effects:* Behaves as an unformatted input function
|
| 3213 |
+
([[istream.unformatted]]), except that it does not count the number of
|
| 3214 |
+
characters extracted and does not affect the value returned by
|
| 3215 |
+
subsequent calls to is.gcount(). After constructing a sentry object
|
| 3216 |
+
extracts characters as long as the next available character `c` is
|
| 3217 |
+
whitespace or until there are no more characters in the sequence.
|
| 3218 |
Whitespace characters are distinguished with the same criterion as used
|
| 3219 |
by `sentry::sentry` ([[istream::sentry]]). If `ws` stops extracting
|
| 3220 |
characters because there are no more available it sets `eofbit`, but not
|
| 3221 |
`failbit`.
|
| 3222 |
|
| 3223 |
*Returns:* `is`.
|
| 3224 |
|
| 3225 |
+
#### Rvalue stream extraction <a id="istream.rvalue">[[istream.rvalue]]</a>
|
| 3226 |
+
|
| 3227 |
+
``` cpp
|
| 3228 |
+
template <class charT, class traits, class T>
|
| 3229 |
+
basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);
|
| 3230 |
+
```
|
| 3231 |
+
|
| 3232 |
+
*Effects:* Equivalent to:
|
| 3233 |
+
|
| 3234 |
+
``` cpp
|
| 3235 |
+
is >> std::forward<T>(x);
|
| 3236 |
+
return is;
|
| 3237 |
+
```
|
| 3238 |
+
|
| 3239 |
+
*Remarks:* This function shall not participate in overload resolution
|
| 3240 |
+
unless the expression `is >> std::forward<T>(x)` is well-formed.
|
| 3241 |
+
|
| 3242 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 3243 |
|
| 3244 |
``` cpp
|
| 3245 |
namespace std {
|
| 3246 |
template <class charT, class traits = char_traits<charT>>
|
| 3247 |
+
class basic_iostream
|
| 3248 |
+
: public basic_istream<charT, traits>,
|
| 3249 |
public basic_ostream<charT, traits> {
|
| 3250 |
public:
|
| 3251 |
+
using char_type = charT;
|
| 3252 |
+
using int_type = typename traits::int_type;
|
| 3253 |
+
using pos_type = typename traits::pos_type;
|
| 3254 |
+
using off_type = typename traits::off_type;
|
| 3255 |
+
using traits_type = traits;
|
|
|
|
| 3256 |
|
| 3257 |
+
// [iostream.cons], constructor
|
| 3258 |
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
| 3259 |
+
|
| 3260 |
+
// [iostream.dest], destructor
|
| 3261 |
virtual ~basic_iostream();
|
| 3262 |
|
| 3263 |
protected:
|
| 3264 |
+
// [iostream.cons], constructor
|
| 3265 |
basic_iostream(const basic_iostream& rhs) = delete;
|
| 3266 |
basic_iostream(basic_iostream&& rhs);
|
| 3267 |
|
| 3268 |
+
// [iostream.assign], assign and swap
|
| 3269 |
basic_iostream& operator=(const basic_iostream& rhs) = delete;
|
| 3270 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3271 |
void swap(basic_iostream& rhs);
|
| 3272 |
};
|
| 3273 |
}
|
| 3274 |
```
|
| 3275 |
|
| 3276 |
+
The class template `basic_iostream` inherits a number of functions that
|
| 3277 |
+
allow reading input and writing output to sequences controlled by a
|
| 3278 |
+
stream buffer.
|
| 3279 |
|
| 3280 |
##### `basic_iostream` constructors <a id="iostream.cons">[[iostream.cons]]</a>
|
| 3281 |
|
| 3282 |
``` cpp
|
| 3283 |
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
| 3284 |
```
|
| 3285 |
|
| 3286 |
+
*Effects:* Constructs an object of class `basic_iostream`, initializing
|
| 3287 |
+
the base class subobjects with
|
| 3288 |
`basic_istream<charT, traits>(sb)` ([[istream]]) and
|
| 3289 |
+
`basic_ostream<charT, traits>(sb)` ([[ostream]]).
|
| 3290 |
|
| 3291 |
+
*Postconditions:* `rdbuf() == sb` and `gcount() == 0`.
|
| 3292 |
|
| 3293 |
``` cpp
|
| 3294 |
basic_iostream(basic_iostream&& rhs);
|
| 3295 |
```
|
| 3296 |
|
|
|
|
| 3311 |
|
| 3312 |
``` cpp
|
| 3313 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 3314 |
```
|
| 3315 |
|
| 3316 |
+
*Effects:* As if by `swap(rhs)`.
|
| 3317 |
|
| 3318 |
``` cpp
|
| 3319 |
void swap(basic_iostream& rhs);
|
| 3320 |
```
|
| 3321 |
|
| 3322 |
*Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
|
| 3323 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3324 |
### Output streams <a id="output.streams">[[output.streams]]</a>
|
| 3325 |
|
| 3326 |
The header `<ostream>` defines a type and several function signatures
|
| 3327 |
that control output to a stream buffer along with a function template
|
| 3328 |
that inserts into stream rvalues.
|
|
|
|
| 3333 |
namespace std {
|
| 3334 |
template <class charT, class traits = char_traits<charT>>
|
| 3335 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 3336 |
public:
|
| 3337 |
// types (inherited from basic_ios ([ios])):
|
| 3338 |
+
using char_type = charT;
|
| 3339 |
+
using int_type = typename traits::int_type;
|
| 3340 |
+
using pos_type = typename traits::pos_type;
|
| 3341 |
+
using off_type = typename traits::off_type;
|
| 3342 |
+
using traits_type = traits;
|
| 3343 |
|
| 3344 |
+
// [ostream.cons], constructor/destructor
|
| 3345 |
explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
|
| 3346 |
virtual ~basic_ostream();
|
| 3347 |
|
| 3348 |
+
// [ostream::sentry], prefix/suffix
|
| 3349 |
class sentry;
|
| 3350 |
|
| 3351 |
+
// [ostream.formatted], formatted output
|
| 3352 |
+
basic_ostream<charT, traits>&
|
| 3353 |
+
operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
|
| 3354 |
+
basic_ostream<charT, traits>&
|
| 3355 |
+
operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 3356 |
+
basic_ostream<charT, traits>&
|
| 3357 |
+
operator<<(ios_base& (*pf)(ios_base&));
|
| 3358 |
|
| 3359 |
basic_ostream<charT, traits>& operator<<(bool n);
|
| 3360 |
basic_ostream<charT, traits>& operator<<(short n);
|
| 3361 |
basic_ostream<charT, traits>& operator<<(unsigned short n);
|
| 3362 |
basic_ostream<charT, traits>& operator<<(int n);
|
|
|
|
| 3368 |
basic_ostream<charT, traits>& operator<<(float f);
|
| 3369 |
basic_ostream<charT, traits>& operator<<(double f);
|
| 3370 |
basic_ostream<charT, traits>& operator<<(long double f);
|
| 3371 |
|
| 3372 |
basic_ostream<charT, traits>& operator<<(const void* p);
|
| 3373 |
+
basic_ostream<charT, traits>& operator<<(nullptr_t);
|
| 3374 |
+
basic_ostream<charT, traits>& operator<<(basic_streambuf<char_type, traits>* sb);
|
| 3375 |
|
| 3376 |
+
// [ostream.unformatted], unformatted output
|
| 3377 |
basic_ostream<charT, traits>& put(char_type c);
|
| 3378 |
basic_ostream<charT, traits>& write(const char_type* s, streamsize n);
|
| 3379 |
|
| 3380 |
basic_ostream<charT, traits>& flush();
|
| 3381 |
|
| 3382 |
+
// [ostream.seeks], seeks
|
| 3383 |
pos_type tellp();
|
| 3384 |
basic_ostream<charT, traits>& seekp(pos_type);
|
| 3385 |
basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
|
| 3386 |
+
|
| 3387 |
protected:
|
| 3388 |
+
// [ostream.cons], copy/move constructor
|
| 3389 |
basic_ostream(const basic_ostream& rhs) = delete;
|
| 3390 |
basic_ostream(basic_ostream&& rhs);
|
| 3391 |
|
| 3392 |
+
// [ostream.assign], assign and swap
|
| 3393 |
basic_ostream& operator=(const basic_ostream& rhs) = delete;
|
| 3394 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3395 |
void swap(basic_ostream& rhs);
|
| 3396 |
};
|
| 3397 |
|
| 3398 |
+
// [ostream.inserters.character], character inserters
|
| 3399 |
template<class charT, class traits>
|
| 3400 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, charT);
|
|
|
|
| 3401 |
template<class charT, class traits>
|
| 3402 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, char);
|
|
|
|
| 3403 |
template<class traits>
|
| 3404 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char);
|
|
|
|
| 3405 |
|
|
|
|
| 3406 |
template<class traits>
|
| 3407 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, signed char);
|
|
|
|
| 3408 |
template<class traits>
|
| 3409 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, unsigned char);
|
|
|
|
| 3410 |
|
| 3411 |
template<class charT, class traits>
|
| 3412 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const charT*);
|
|
|
|
| 3413 |
template<class charT, class traits>
|
| 3414 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const char*);
|
|
|
|
| 3415 |
template<class traits>
|
| 3416 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const char*);
|
|
|
|
| 3417 |
|
|
|
|
| 3418 |
template<class traits>
|
| 3419 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const signed char*);
|
|
|
|
| 3420 |
template<class traits>
|
| 3421 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const unsigned char*);
|
|
|
|
| 3422 |
}
|
| 3423 |
```
|
| 3424 |
|
| 3425 |
+
The class template `basic_ostream` defines a number of member function
|
| 3426 |
+
signatures that assist in formatting and writing output to output
|
| 3427 |
+
sequences controlled by a stream buffer.
|
| 3428 |
|
| 3429 |
Two groups of member function signatures share common properties: the
|
| 3430 |
*formatted output functions* (or *inserters*) and the *unformatted
|
| 3431 |
output functions.* Both groups of output functions generate (or
|
| 3432 |
*insert*) output *characters* by actions equivalent to calling
|
|
|
|
| 3438 |
explicitly noted otherwise the output function sets `badbit` in error
|
| 3439 |
state. If `badbit` is on in `exceptions()`, the output function rethrows
|
| 3440 |
the exception without completing its actions, otherwise it does not
|
| 3441 |
throw anything and treat as an error.
|
| 3442 |
|
| 3443 |
+
##### `basic_ostream` constructors <a id="ostream.cons">[[ostream.cons]]</a>
|
| 3444 |
|
| 3445 |
``` cpp
|
| 3446 |
explicit basic_ostream(basic_streambuf<charT, traits>* sb);
|
| 3447 |
```
|
| 3448 |
|
| 3449 |
+
*Effects:* Constructs an object of class `basic_ostream`, initializing
|
| 3450 |
+
the base class subobject with
|
| 3451 |
+
`basic_ios<charT, traits>::init(sb)` ([[basic.ios.cons]]).
|
| 3452 |
+
|
| 3453 |
+
*Postconditions:* `rdbuf() == sb`.
|
| 3454 |
|
| 3455 |
``` cpp
|
| 3456 |
basic_ostream(basic_ostream&& rhs);
|
| 3457 |
```
|
| 3458 |
|
| 3459 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 3460 |
by default constructing the base class and calling
|
| 3461 |
`basic_ios<charT, traits>::move(rhs)` to initialize the base class.
|
| 3462 |
|
| 3463 |
+
``` cpp
|
| 3464 |
+
virtual ~basic_ostream();
|
| 3465 |
+
```
|
| 3466 |
+
|
| 3467 |
+
*Effects:* Destroys an object of class `basic_ostream`.
|
| 3468 |
+
|
| 3469 |
+
*Remarks:* Does not perform any operations on `rdbuf()`.
|
| 3470 |
+
|
| 3471 |
+
##### Class `basic_ostream` assign and swap <a id="ostream.assign">[[ostream.assign]]</a>
|
| 3472 |
|
| 3473 |
``` cpp
|
| 3474 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 3475 |
```
|
| 3476 |
|
| 3477 |
+
*Effects:* As if by `swap(rhs)`.
|
| 3478 |
|
| 3479 |
*Returns:* `*this`.
|
| 3480 |
|
| 3481 |
``` cpp
|
| 3482 |
void swap(basic_ostream& rhs);
|
| 3483 |
```
|
| 3484 |
|
| 3485 |
*Effects:* Calls `basic_ios<charT, traits>::swap(rhs)`.
|
| 3486 |
|
| 3487 |
+
##### Class `basic_ostream::sentry` <a id="ostream::sentry">[[ostream::sentry]]</a>
|
| 3488 |
|
| 3489 |
``` cpp
|
| 3490 |
namespace std {
|
| 3491 |
template <class charT, class traits = char_traits<charT>>
|
| 3492 |
class basic_ostream<charT, traits>::sentry {
|
|
|
|
| 3508 |
``` cpp
|
| 3509 |
explicit sentry(basic_ostream<charT, traits>& os);
|
| 3510 |
```
|
| 3511 |
|
| 3512 |
If `os.good()` is nonzero, prepares for formatted or unformatted output.
|
| 3513 |
+
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^31]
|
| 3514 |
|
| 3515 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 3516 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 3517 |
constructor may call `setstate(failbit)` (which may throw
|
| 3518 |
+
`ios_base::failure` ([[iostate.flags]]))[^32]
|
| 3519 |
|
| 3520 |
``` cpp
|
| 3521 |
~sentry();
|
| 3522 |
```
|
| 3523 |
|
| 3524 |
If
|
| 3525 |
+
`(os.flags() & ios_base::unitbuf) && !uncaught_exceptions() && os.good()`
|
| 3526 |
is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1,
|
| 3527 |
sets `badbit` in `os.rdstate()` without propagating an exception.
|
| 3528 |
|
| 3529 |
``` cpp
|
| 3530 |
explicit operator bool() const;
|
| 3531 |
```
|
| 3532 |
|
| 3533 |
*Effects:* Returns `ok_`.
|
| 3534 |
|
| 3535 |
+
##### `basic_ostream` seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
|
| 3536 |
|
| 3537 |
Each seek member function begins execution by constructing an object of
|
| 3538 |
class `sentry`. It returns by destroying the `sentry` object.
|
| 3539 |
|
| 3540 |
``` cpp
|
| 3541 |
pos_type tellp();
|
| 3542 |
```
|
| 3543 |
|
| 3544 |
+
*Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
|
| 3545 |
+
failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
|
| 3546 |
+
|
| 3547 |
``` cpp
|
| 3548 |
basic_ostream<charT, traits>& seekp(pos_type pos);
|
| 3549 |
```
|
| 3550 |
|
| 3551 |
+
*Effects:* If `fail() != true`, executes
|
| 3552 |
+
`rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
|
| 3553 |
+
function calls `setstate(failbit)` (which may throw
|
| 3554 |
+
`ios_base::failure`).
|
| 3555 |
+
|
| 3556 |
+
*Returns:* `*this`.
|
| 3557 |
+
|
| 3558 |
``` cpp
|
| 3559 |
basic_ostream<charT, traits>& seekp(off_type off, ios_base::seekdir dir);
|
| 3560 |
```
|
| 3561 |
|
| 3562 |
*Effects:* If `fail() != true`, executes
|
|
|
|
| 3574 |
object of class `sentry`. If this object returns `true` when converted
|
| 3575 |
to a value of type `bool`, the function endeavors to generate the
|
| 3576 |
requested output. If the generation fails, then the formatted output
|
| 3577 |
function does `setstate(ios_base::failbit)`, which might throw an
|
| 3578 |
exception. If an exception is thrown during output, then `ios::badbit`
|
| 3579 |
+
is turned on[^33] in `*this`’s error state. If
|
| 3580 |
`(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
|
| 3581 |
not an exception is thrown, the `sentry` object is destroyed before
|
| 3582 |
leaving the formatted output function. If no exception is thrown, the
|
| 3583 |
result of the formatted output function is `*this`.
|
| 3584 |
|
|
|
|
| 3675 |
The first argument provides an object of the `ostreambuf_iterator<>`
|
| 3676 |
class which is an iterator for class `basic_ostream<>`. It bypasses
|
| 3677 |
`ostream`s and uses `streambuf`s directly. Class `locale` relies on
|
| 3678 |
these types as its interface to iostreams, since for flexibility it has
|
| 3679 |
been abstracted away from direct dependence on `ostream`. The second
|
| 3680 |
+
parameter is a reference to the base class subobject of type `ios_base`.
|
| 3681 |
+
It provides formatting specifications such as field width, and a locale
|
| 3682 |
from which to obtain other facets. If `failed` is `true` then does
|
| 3683 |
`setstate(badbit)`, which may throw an exception, and returns.
|
| 3684 |
|
| 3685 |
*Returns:* `*this`.
|
| 3686 |
|
| 3687 |
##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
|
| 3688 |
|
| 3689 |
``` cpp
|
| 3690 |
+
basic_ostream<charT, traits>&
|
| 3691 |
+
operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
|
| 3692 |
```
|
| 3693 |
|
| 3694 |
*Effects:* None. Does not behave as a formatted output function (as
|
| 3695 |
described in [[ostream.formatted.reqmts]]).
|
| 3696 |
|
| 3697 |
+
*Returns:* `pf(*this)`.[^34]
|
| 3698 |
|
| 3699 |
``` cpp
|
| 3700 |
+
basic_ostream<charT, traits>&
|
| 3701 |
+
operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 3702 |
```
|
| 3703 |
|
| 3704 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3705 |
formatted output function (as described
|
| 3706 |
in [[ostream.formatted.reqmts]]).
|
| 3707 |
|
| 3708 |
+
*Returns:* `*this`.[^35]
|
| 3709 |
|
| 3710 |
``` cpp
|
| 3711 |
+
basic_ostream<charT, traits>& operator<<(ios_base& (*pf)(ios_base&));
|
|
|
|
| 3712 |
```
|
| 3713 |
|
| 3714 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 3715 |
formatted output function (as described
|
| 3716 |
in [[ostream.formatted.reqmts]]).
|
| 3717 |
|
| 3718 |
*Returns:* `*this`.
|
| 3719 |
|
| 3720 |
``` cpp
|
| 3721 |
+
basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
|
|
|
|
| 3722 |
```
|
| 3723 |
|
| 3724 |
+
*Effects:* Behaves as an unformatted output function
|
| 3725 |
+
([[ostream.unformatted]]). After the sentry object is constructed, if
|
| 3726 |
+
`sb` is null calls `setstate(badbit)` (which may throw
|
| 3727 |
`ios_base::failure`).
|
| 3728 |
|
| 3729 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 3730 |
read from `sb` and inserted until any of the following occurs:
|
| 3731 |
|
|
|
|
| 3740 |
`failbit` in error state, and if `failbit` is on in `exceptions()` the
|
| 3741 |
caught exception is rethrown.
|
| 3742 |
|
| 3743 |
*Returns:* `*this`.
|
| 3744 |
|
| 3745 |
+
``` cpp
|
| 3746 |
+
basic_ostream<charT, traits>& operator<<(nullptr_t);
|
| 3747 |
+
```
|
| 3748 |
+
|
| 3749 |
+
*Effects:* Equivalent to:
|
| 3750 |
+
|
| 3751 |
+
``` cpp
|
| 3752 |
+
return *this << s;
|
| 3753 |
+
```
|
| 3754 |
+
|
| 3755 |
+
where `s` is an *implementation-defined* NTCTS ([[defns.ntcts]]).
|
| 3756 |
+
|
| 3757 |
##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
|
| 3758 |
|
| 3759 |
``` cpp
|
| 3760 |
template<class charT, class traits>
|
| 3761 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, charT c);
|
|
|
|
| 3762 |
template<class charT, class traits>
|
| 3763 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, char c);
|
|
|
|
| 3764 |
// specialization
|
| 3765 |
template<class traits>
|
| 3766 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, char c);
|
|
|
|
| 3767 |
// signed and unsigned
|
| 3768 |
template<class traits>
|
| 3769 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, signed char c);
|
|
|
|
| 3770 |
template<class traits>
|
| 3771 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
|
|
|
|
| 3772 |
```
|
| 3773 |
|
| 3774 |
+
*Effects:* Behaves as a formatted output
|
| 3775 |
+
function ([[ostream.formatted.reqmts]]) of `out`. Constructs a
|
| 3776 |
+
character sequence `seq`. If `c` has type `char` and the character type
|
| 3777 |
+
of the stream is not `char`, then `seq` consists of `out.widen(c)`;
|
| 3778 |
+
otherwise `seq` consists of `c`. Determines padding for `seq` as
|
| 3779 |
+
described in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`.
|
| 3780 |
+
Calls `os.width(0)`.
|
| 3781 |
|
| 3782 |
*Returns:* `out`.
|
| 3783 |
|
| 3784 |
``` cpp
|
| 3785 |
template<class charT, class traits>
|
| 3786 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, const charT* s);
|
|
|
|
| 3787 |
template<class charT, class traits>
|
| 3788 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, const char* s);
|
|
|
|
| 3789 |
template<class traits>
|
| 3790 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, const char* s);
|
|
|
|
| 3791 |
template<class traits>
|
| 3792 |
+
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, const signed char* s);
|
|
|
|
| 3793 |
template<class traits>
|
| 3794 |
basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out,
|
| 3795 |
const unsigned char* s);
|
| 3796 |
```
|
| 3797 |
|
|
|
|
| 3806 |
- `traits::length(s)` for the overload where the first argument is of
|
| 3807 |
type `basic_ostream<charT, traits>&` and the second is of type
|
| 3808 |
`const charT*`, and also for the overload where the first argument is
|
| 3809 |
of type `basic_ostream<char, traits>&` and the second is of type
|
| 3810 |
`const char*`,
|
| 3811 |
+
- `char_traits<char>::length(s)` for the overload where the first
|
| 3812 |
argument is of type `basic_ostream<charT, traits>&` and the second is
|
| 3813 |
of type `const char*`,
|
| 3814 |
- `traits::length(reinterpret_cast<const char*>(s))` for the other two
|
| 3815 |
overloads.
|
| 3816 |
|
|
|
|
| 3824 |
|
| 3825 |
Each unformatted output function begins execution by constructing an
|
| 3826 |
object of class `sentry`. If this object returns `true`, while
|
| 3827 |
converting to a value of type `bool`, the function endeavors to generate
|
| 3828 |
the requested output. If an exception is thrown during output, then
|
| 3829 |
+
`ios::badbit` is turned on[^36] in `*this`’s error state. If
|
| 3830 |
`(exceptions() & badbit) != 0` then the exception is rethrown. In any
|
| 3831 |
case, the unformatted output function ends by destroying the sentry
|
| 3832 |
object, then, if no exception was thrown, returning the value specified
|
| 3833 |
for the unformatted output function.
|
| 3834 |
|
| 3835 |
``` cpp
|
| 3836 |
basic_ostream<charT, traits>& put(char_type c);
|
| 3837 |
```
|
| 3838 |
|
| 3839 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3840 |
+
above). After constructing a sentry object, inserts the character `c`,
|
| 3841 |
+
if possible.[^37]
|
| 3842 |
|
| 3843 |
Otherwise, calls `setstate(badbit)` (which may throw
|
| 3844 |
`ios_base::failure` ([[iostate.flags]])).
|
| 3845 |
|
| 3846 |
*Returns:* `*this`.
|
|
|
|
| 3848 |
``` cpp
|
| 3849 |
basic_ostream& write(const char_type* s, streamsize n);
|
| 3850 |
```
|
| 3851 |
|
| 3852 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3853 |
+
above). After constructing a sentry object, obtains characters to insert
|
| 3854 |
+
from successive locations of an array whose first element is designated
|
| 3855 |
+
by `s`.[^38] Characters are inserted until either of the following
|
| 3856 |
+
occurs:
|
| 3857 |
|
| 3858 |
- `n` characters are inserted;
|
| 3859 |
- inserting in the output sequence fails (in which case the function
|
| 3860 |
calls `setstate(badbit)`, which may throw
|
| 3861 |
`ios_base::failure` ([[iostate.flags]])).
|
|
|
|
| 3865 |
``` cpp
|
| 3866 |
basic_ostream& flush();
|
| 3867 |
```
|
| 3868 |
|
| 3869 |
*Effects:* Behaves as an unformatted output function (as described
|
| 3870 |
+
above). If `rdbuf()` is not a null pointer, constructs a sentry object.
|
| 3871 |
+
If this object returns `true` when converted to a value of type `bool`
|
| 3872 |
+
the function calls `rdbuf()->pubsync()`. If that function returns -1
|
| 3873 |
+
calls `setstate(badbit)` (which may throw
|
|
|
|
| 3874 |
`ios_base::failure` ([[iostate.flags]])). Otherwise, if the sentry
|
| 3875 |
object returns `false`, does nothing.
|
| 3876 |
|
| 3877 |
*Returns:* `*this`.
|
| 3878 |
|
| 3879 |
#### Standard `basic_ostream` manipulators <a id="ostream.manip">[[ostream.manip]]</a>
|
| 3880 |
|
| 3881 |
``` cpp
|
|
|
|
| 3882 |
template <class charT, class traits>
|
| 3883 |
basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);
|
|
|
|
| 3884 |
```
|
| 3885 |
|
| 3886 |
*Effects:* Calls `os.put(os.widen(’\n’))`, then `os.flush()`.
|
| 3887 |
|
| 3888 |
*Returns:* `os`.
|
| 3889 |
|
| 3890 |
``` cpp
|
|
|
|
| 3891 |
template <class charT, class traits>
|
| 3892 |
basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);
|
|
|
|
| 3893 |
```
|
| 3894 |
|
| 3895 |
*Effects:* Inserts a null character into the output sequence: calls
|
| 3896 |
`os.put(charT())`.
|
| 3897 |
|
| 3898 |
*Returns:* `os`.
|
| 3899 |
|
| 3900 |
``` cpp
|
|
|
|
| 3901 |
template <class charT, class traits>
|
| 3902 |
basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);
|
|
|
|
| 3903 |
```
|
| 3904 |
|
| 3905 |
*Effects:* Calls `os.flush()`.
|
| 3906 |
|
| 3907 |
*Returns:* `os`.
|
| 3908 |
|
| 3909 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 3910 |
|
| 3911 |
``` cpp
|
| 3912 |
template <class charT, class traits, class T>
|
| 3913 |
+
basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
|
|
|
|
| 3914 |
```
|
| 3915 |
|
| 3916 |
+
*Effects:* As if by: `os << x;`
|
| 3917 |
|
| 3918 |
+
*Returns:* `os`.
|
| 3919 |
+
|
| 3920 |
+
*Remarks:* This function shall not participate in overload resolution
|
| 3921 |
+
unless the expression `os << x` is well-formed.
|
| 3922 |
|
| 3923 |
### Standard manipulators <a id="std.manip">[[std.manip]]</a>
|
| 3924 |
|
| 3925 |
The header `<iomanip>` defines several functions that support extractors
|
| 3926 |
and inserters that alter information maintained by class `ios_base` and
|
|
|
|
| 3930 |
unspecified resetiosflags(ios_base::fmtflags mask);
|
| 3931 |
```
|
| 3932 |
|
| 3933 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3934 |
of type `basic_ostream<charT, traits>` then the expression
|
| 3935 |
+
`out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
|
| 3936 |
if `in` is an object of type `basic_istream<charT, traits>` then the
|
| 3937 |
+
expression `in >> resetiosflags(mask)` behaves as if it called
|
| 3938 |
+
`f(in, mask)`, where the function `f` is defined as:[^39]
|
| 3939 |
|
| 3940 |
``` cpp
|
| 3941 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 3942 |
// reset specified flags
|
| 3943 |
str.setf(ios_base::fmtflags(0), mask);
|
| 3944 |
}
|
| 3945 |
```
|
| 3946 |
|
| 3947 |
+
The expression `out << resetiosflags(mask)` shall have type
|
| 3948 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3949 |
+
`in >> resetiosflags(mask)` shall have type
|
| 3950 |
`basic_istream<charT, traits>&` and value `in`.
|
| 3951 |
|
| 3952 |
``` cpp
|
| 3953 |
unspecified setiosflags(ios_base::fmtflags mask);
|
| 3954 |
```
|
| 3955 |
|
| 3956 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3957 |
of type `basic_ostream<charT, traits>` then the expression
|
| 3958 |
+
`out << setiosflags(mask)` behaves as if it called `f(out, mask)`, or if
|
| 3959 |
`in` is an object of type `basic_istream<charT, traits>` then the
|
| 3960 |
+
expression `in >> setiosflags(mask)` behaves as if it called
|
| 3961 |
`f(in, mask)`, where the function `f` is defined as:
|
| 3962 |
|
| 3963 |
``` cpp
|
| 3964 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 3965 |
// set specified flags
|
| 3966 |
str.setf(mask);
|
| 3967 |
}
|
| 3968 |
```
|
| 3969 |
|
| 3970 |
+
The expression `out << setiosflags(mask)` shall have type
|
| 3971 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3972 |
+
`in >> setiosflags(mask)` shall have type `basic_istream<charT,`
|
| 3973 |
`traits>&` and value `in`.
|
| 3974 |
|
| 3975 |
``` cpp
|
| 3976 |
unspecified setbase(int base);
|
| 3977 |
```
|
| 3978 |
|
| 3979 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 3980 |
of type `basic_ostream<charT, traits>` then the expression
|
| 3981 |
+
`out << setbase(base)` behaves as if it called `f(out, base)`, or if
|
| 3982 |
`in` is an object of type `basic_istream<charT, traits>` then the
|
| 3983 |
+
expression `in >> setbase(base)` behaves as if it called `f(in, base)`,
|
| 3984 |
where the function `f` is defined as:
|
| 3985 |
|
| 3986 |
``` cpp
|
| 3987 |
void f(ios_base& str, int base) {
|
| 3988 |
// set basefield
|
|
|
|
| 3991 |
base == 16 ? ios_base::hex :
|
| 3992 |
ios_base::fmtflags(0), ios_base::basefield);
|
| 3993 |
}
|
| 3994 |
```
|
| 3995 |
|
| 3996 |
+
The expression `out << setbase(base)` shall have type
|
| 3997 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 3998 |
+
`in >> setbase(base)` shall have type `basic_istream<charT, traits>&`
|
| 3999 |
and value `in`.
|
| 4000 |
|
| 4001 |
``` cpp
|
| 4002 |
unspecified setfill(char_type c);
|
| 4003 |
```
|
| 4004 |
|
| 4005 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4006 |
of type `basic_ostream<charT, traits>` and `c` has type `charT` then the
|
| 4007 |
+
expression `out << setfill(c)` behaves as if it called `f(out, c)`,
|
| 4008 |
where the function `f` is defined as:
|
| 4009 |
|
| 4010 |
``` cpp
|
| 4011 |
template<class charT, class traits>
|
| 4012 |
void f(basic_ios<charT, traits>& str, charT c) {
|
| 4013 |
// set fill character
|
| 4014 |
str.fill(c);
|
| 4015 |
}
|
| 4016 |
```
|
| 4017 |
|
| 4018 |
+
The expression `out << setfill(c)` shall have type
|
| 4019 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4020 |
|
| 4021 |
``` cpp
|
| 4022 |
unspecified setprecision(int n);
|
| 4023 |
```
|
| 4024 |
|
| 4025 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4026 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4027 |
+
`out << setprecision(n)` behaves as if it called `f(out, n)`, or if `in`
|
| 4028 |
is an object of type `basic_istream<charT, traits>` then the expression
|
| 4029 |
+
`in >> setprecision(n)` behaves as if it called `f(in, n)`, where the
|
| 4030 |
function `f` is defined as:
|
| 4031 |
|
| 4032 |
``` cpp
|
| 4033 |
void f(ios_base& str, int n) {
|
| 4034 |
// set precision
|
| 4035 |
str.precision(n);
|
| 4036 |
}
|
| 4037 |
```
|
| 4038 |
|
| 4039 |
+
The expression `out << setprecision(n)` shall have type
|
| 4040 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 4041 |
+
`in >> setprecision(n)` shall have type `basic_istream<charT, traits>&`
|
| 4042 |
and value `in`.
|
| 4043 |
|
| 4044 |
``` cpp
|
| 4045 |
unspecified setw(int n);
|
| 4046 |
```
|
| 4047 |
|
| 4048 |
*Returns:* An object of unspecified type such that if `out` is an
|
| 4049 |
instance of `basic_ostream<charT, traits>` then the expression
|
| 4050 |
+
`out << setw(n)` behaves as if it called `f(out, n)`, or if `in` is an
|
| 4051 |
object of type `basic_istream<charT, traits>` then the expression
|
| 4052 |
+
`in >> setw(n)` behaves as if it called `f(in, n)`, where the function
|
| 4053 |
`f` is defined as:
|
| 4054 |
|
| 4055 |
``` cpp
|
| 4056 |
void f(ios_base& str, int n) {
|
| 4057 |
// set width
|
| 4058 |
str.width(n);
|
| 4059 |
}
|
| 4060 |
```
|
| 4061 |
|
| 4062 |
+
The expression `out << setw(n)` shall have type
|
| 4063 |
`basic_ostream<charT, traits>&` and value `out`. The expression
|
| 4064 |
+
`in >> setw(n)` shall have type `basic_istream<charT, traits>&` and
|
| 4065 |
value `in`.
|
| 4066 |
|
| 4067 |
### Extended manipulators <a id="ext.manip">[[ext.manip]]</a>
|
| 4068 |
|
| 4069 |
The header `<iomanip>` defines several functions that support extractors
|
|
|
|
| 4080 |
*Effects:* The expression `in >> get_money(mon, intl)` described below
|
| 4081 |
behaves as a formatted input function ([[istream.formatted.reqmts]]).
|
| 4082 |
|
| 4083 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4084 |
of type `basic_istream<charT, traits>` then the expression
|
| 4085 |
+
`in >> get_money(mon, intl)` behaves as if it called `f(in, mon, intl)`,
|
| 4086 |
where the function `f` is defined as:
|
| 4087 |
|
| 4088 |
``` cpp
|
| 4089 |
template <class charT, class traits, class moneyT>
|
| 4090 |
void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
|
| 4091 |
+
using Iter = istreambuf_iterator<charT, traits>;
|
| 4092 |
+
using MoneyGet = money_get<charT, Iter>;
|
| 4093 |
|
| 4094 |
ios_base::iostate err = ios_base::goodbit;
|
| 4095 |
const MoneyGet& mg = use_facet<MoneyGet>(str.getloc());
|
| 4096 |
|
| 4097 |
mg.get(Iter(str.rdbuf()), Iter(), intl, str, err, mon);
|
|
|
|
| 4099 |
if (ios_base::goodbit != err)
|
| 4100 |
str.setstate(err);
|
| 4101 |
}
|
| 4102 |
```
|
| 4103 |
|
| 4104 |
+
The expression `in >> get_money(mon, intl)` shall have type
|
| 4105 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4106 |
|
| 4107 |
``` cpp
|
| 4108 |
template <class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
|
| 4109 |
```
|
|
|
|
| 4111 |
*Requires:* The type `moneyT` shall be either `long double` or a
|
| 4112 |
specialization of the `basic_string` template (Clause [[strings]]).
|
| 4113 |
|
| 4114 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4115 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4116 |
+
`out << put_money(mon, intl)` behaves as a formatted output
|
| 4117 |
+
function ([[ostream.formatted.reqmts]]) that calls `f(out, mon, intl)`,
|
| 4118 |
+
where the function `f` is defined as:
|
| 4119 |
|
| 4120 |
``` cpp
|
| 4121 |
template <class charT, class traits, class moneyT>
|
| 4122 |
void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
|
| 4123 |
+
using Iter = ostreambuf_iterator<charT, traits>;
|
| 4124 |
+
using MoneyPut = money_put<charT, Iter>;
|
| 4125 |
|
| 4126 |
const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
|
| 4127 |
const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);
|
| 4128 |
|
| 4129 |
if (end.failed())
|
| 4130 |
str.setstate(ios::badbit);
|
| 4131 |
}
|
| 4132 |
```
|
| 4133 |
|
| 4134 |
+
The expression `out << put_money(mon, intl)` shall have type
|
| 4135 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4136 |
|
| 4137 |
``` cpp
|
| 4138 |
template <class charT> unspecified get_time(struct tm* tmb, const charT* fmt);
|
| 4139 |
```
|
| 4140 |
|
| 4141 |
*Requires:* The argument `tmb` shall be a valid pointer to an object of
|
| 4142 |
+
type `struct tm`. The argument `fmt` shall be a valid pointer to an
|
| 4143 |
array of objects of type `charT` with `char_traits<charT>::length(fmt)`
|
| 4144 |
elements.
|
| 4145 |
|
| 4146 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 4147 |
of type `basic_istream<charT, traits>` then the expression
|
| 4148 |
+
`in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
|
| 4149 |
where the function `f` is defined as:
|
| 4150 |
|
| 4151 |
``` cpp
|
| 4152 |
template <class charT, class traits>
|
| 4153 |
void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
|
| 4154 |
+
using Iter = istreambuf_iterator<charT, traits>;
|
| 4155 |
+
using TimeGet = time_get<charT, Iter>;
|
| 4156 |
|
| 4157 |
ios_base::iostate err = ios_base::goodbit;
|
| 4158 |
const TimeGet& tg = use_facet<TimeGet>(str.getloc());
|
| 4159 |
|
| 4160 |
tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
|
| 4161 |
fmt, fmt + traits::length(fmt));
|
| 4162 |
|
| 4163 |
if (err != ios_base::goodbit)
|
| 4164 |
+
str.setstate(err);
|
| 4165 |
}
|
| 4166 |
```
|
| 4167 |
|
| 4168 |
+
The expression `in >> get_time(tmb, fmt)` shall have type
|
| 4169 |
`basic_istream<charT, traits>&` and value `in`.
|
| 4170 |
|
| 4171 |
``` cpp
|
| 4172 |
template <class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);
|
| 4173 |
```
|
|
|
|
| 4177 |
array of objects of type `charT` with `char_traits<charT>::length(fmt)`
|
| 4178 |
elements.
|
| 4179 |
|
| 4180 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 4181 |
of type `basic_ostream<charT, traits>` then the expression
|
| 4182 |
+
`out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
|
| 4183 |
where the function `f` is defined as:
|
| 4184 |
|
| 4185 |
``` cpp
|
| 4186 |
template <class charT, class traits>
|
| 4187 |
void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
|
| 4188 |
+
using Iter = ostreambuf_iterator<charT, traits>;
|
| 4189 |
+
using TimePut = time_put<charT, Iter>;
|
| 4190 |
|
| 4191 |
const TimePut& tp = use_facet<TimePut>(str.getloc());
|
| 4192 |
const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
|
| 4193 |
fmt, fmt + traits::length(fmt));
|
| 4194 |
|
| 4195 |
if (end.failed())
|
| 4196 |
str.setstate(ios_base::badbit);
|
| 4197 |
}
|
| 4198 |
```
|
| 4199 |
|
| 4200 |
+
The expression `out << put_time(tmb, fmt)` shall have type
|
| 4201 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4202 |
|
| 4203 |
### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
|
| 4204 |
|
| 4205 |
+
[*Note 1*: Quoted manipulators provide string insertion and extraction
|
| 4206 |
+
of quoted strings (for example, XML and CSV formats). Quoted
|
| 4207 |
+
manipulators are useful in ensuring that the content of a string with
|
| 4208 |
+
embedded spaces remains unchanged if inserted and then extracted via
|
| 4209 |
+
stream I/O. — *end note*]
|
| 4210 |
|
| 4211 |
``` cpp
|
| 4212 |
template <class charT>
|
| 4213 |
unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
|
| 4214 |
template <class charT, class traits, class Allocator>
|
| 4215 |
unspecified quoted(const basic_string<charT, traits, Allocator>& s,
|
| 4216 |
+
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 4217 |
+
template <class charT, class traits>
|
| 4218 |
+
unspecified quoted(basic_string_view<charT, traits> s,
|
| 4219 |
+
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 4220 |
```
|
| 4221 |
|
| 4222 |
*Returns:* An object of unspecified type such that if `out` is an
|
| 4223 |
instance of `basic_ostream` with member type `char_type` the same as
|
| 4224 |
+
`charT` and with member type `traits_type`, which in the second and
|
| 4225 |
+
third forms is the same as `traits`, then the expression
|
| 4226 |
+
`out << quoted(s, delim, escape)` behaves as a formatted output
|
| 4227 |
function ([[ostream.formatted.reqmts]]) of `out`. This forms a
|
| 4228 |
character sequence `seq`, initially consisting of the following
|
| 4229 |
elements:
|
| 4230 |
|
| 4231 |
- `delim`.
|
|
|
|
| 4236 |
|
| 4237 |
Let `x` be the number of elements initially in `seq`. Then padding is
|
| 4238 |
determined for `seq` as described in [[ostream.formatted.reqmts]],
|
| 4239 |
`seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
|
| 4240 |
`n` is the larger of `out.width()` and `x`, and `out.width(0)` is
|
| 4241 |
+
called. The expression `out << quoted(s, delim, escape)` shall have type
|
| 4242 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4243 |
|
| 4244 |
``` cpp
|
| 4245 |
template <class charT, class traits, class Allocator>
|
| 4246 |
unspecified quoted(basic_string<charT, traits, Allocator>& s,
|
| 4247 |
+
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 4248 |
```
|
| 4249 |
|
| 4250 |
*Returns:* An object of unspecified type such that:
|
| 4251 |
|
| 4252 |
- If `in` is an instance of `basic_istream` with member types
|
| 4253 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4254 |
+
respectively, then the expression `in >> quoted(s, delim, escape)`
|
| 4255 |
behaves as if it extracts the following characters from `in` using
|
| 4256 |
+
`operator>>(basic_istream<charT, traits>&, charT&)` ([[istream.extractors]])
|
| 4257 |
+
which may throw `ios_base::failure` ([[ios::failure]]):
|
| 4258 |
- If the first character extracted is equal to `delim`, as determined
|
| 4259 |
by `traits_type::eq`, then:
|
| 4260 |
- Turn off the `skipws` flag.
|
| 4261 |
- `s.clear()`
|
| 4262 |
- Until an unescaped `delim` character is reached or `!in`, extract
|
| 4263 |
characters from `in` and append them to `s`, except that if an
|
| 4264 |
`escape` is reached, ignore it and append the next character to
|
| 4265 |
`s`.
|
| 4266 |
- Discard the final `delim` character.
|
| 4267 |
- Restore the `skipws` flag to its original value.
|
| 4268 |
+
- Otherwise, `in >> s`.
|
| 4269 |
- If `out` is an instance of `basic_ostream` with member types
|
| 4270 |
`char_type` and `traits_type` the same as `charT` and `traits`,
|
| 4271 |
+
respectively, then the expression `out << quoted(s, delim, escape)`
|
| 4272 |
behaves as specified for the
|
| 4273 |
`const basic_string<charT, traits, Allocator>&` overload of the
|
| 4274 |
`quoted` function.
|
| 4275 |
|
| 4276 |
+
The expression `in >> quoted(s, delim, escape)` shall have type
|
| 4277 |
`basic_istream<charT, traits>&` and value `in`. The expression
|
| 4278 |
+
`out << quoted(s, delim, escape)` shall have type
|
| 4279 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 4280 |
|
| 4281 |
## String-based streams <a id="string.streams">[[string.streams]]</a>
|
| 4282 |
|
| 4283 |
+
### Header `<sstream>` synopsis <a id="sstream.syn">[[sstream.syn]]</a>
|
| 4284 |
+
|
| 4285 |
+
``` cpp
|
| 4286 |
+
namespace std {
|
| 4287 |
+
template <class charT, class traits = char_traits<charT>,
|
| 4288 |
+
class Allocator = allocator<charT>>
|
| 4289 |
+
class basic_stringbuf;
|
| 4290 |
+
|
| 4291 |
+
using stringbuf = basic_stringbuf<char>;
|
| 4292 |
+
using wstringbuf = basic_stringbuf<wchar_t>;
|
| 4293 |
+
|
| 4294 |
+
template <class charT, class traits = char_traits<charT>,
|
| 4295 |
+
class Allocator = allocator<charT>>
|
| 4296 |
+
class basic_istringstream;
|
| 4297 |
+
|
| 4298 |
+
using istringstream = basic_istringstream<char>;
|
| 4299 |
+
using wistringstream = basic_istringstream<wchar_t>;
|
| 4300 |
+
|
| 4301 |
+
template <class charT, class traits = char_traits<charT>,
|
| 4302 |
+
class Allocator = allocator<charT>>
|
| 4303 |
+
class basic_ostringstream;
|
| 4304 |
+
using ostringstream = basic_ostringstream<char>;
|
| 4305 |
+
using wostringstream = basic_ostringstream<wchar_t>;
|
| 4306 |
+
|
| 4307 |
+
template <class charT, class traits = char_traits<charT>,
|
| 4308 |
+
class Allocator = allocator<charT>>
|
| 4309 |
+
class basic_stringstream;
|
| 4310 |
+
using stringstream = basic_stringstream<char>;
|
| 4311 |
+
using wstringstream = basic_stringstream<wchar_t>;
|
| 4312 |
+
}
|
| 4313 |
+
```
|
| 4314 |
|
| 4315 |
The header `<sstream>` defines four class templates and eight types that
|
| 4316 |
associate stream buffers with objects of class `basic_string`, as
|
| 4317 |
described in [[string.classes]].
|
| 4318 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4319 |
### Class template `basic_stringbuf` <a id="stringbuf">[[stringbuf]]</a>
|
| 4320 |
|
| 4321 |
``` cpp
|
| 4322 |
namespace std {
|
| 4323 |
template <class charT, class traits = char_traits<charT>,
|
| 4324 |
class Allocator = allocator<charT>>
|
| 4325 |
class basic_stringbuf : public basic_streambuf<charT, traits> {
|
| 4326 |
public:
|
| 4327 |
+
using char_type = charT;
|
| 4328 |
+
using int_type = typename traits::int_type;
|
| 4329 |
+
using pos_type = typename traits::pos_type;
|
| 4330 |
+
using off_type = typename traits::off_type;
|
| 4331 |
+
using traits_type = traits;
|
| 4332 |
+
using allocator_type = Allocator;
|
| 4333 |
|
| 4334 |
+
// [stringbuf.cons], constructors
|
| 4335 |
+
explicit basic_stringbuf(
|
| 4336 |
+
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4337 |
+
explicit basic_stringbuf(
|
| 4338 |
+
const basic_string<charT, traits, Allocator>& str,
|
| 4339 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4340 |
basic_stringbuf(const basic_stringbuf& rhs) = delete;
|
| 4341 |
basic_stringbuf(basic_stringbuf&& rhs);
|
| 4342 |
|
| 4343 |
+
// [stringbuf.assign], assign and swap
|
| 4344 |
basic_stringbuf& operator=(const basic_stringbuf& rhs) = delete;
|
| 4345 |
basic_stringbuf& operator=(basic_stringbuf&& rhs);
|
| 4346 |
void swap(basic_stringbuf& rhs);
|
| 4347 |
|
| 4348 |
+
// [stringbuf.members], get and set
|
| 4349 |
basic_string<charT, traits, Allocator> str() const;
|
| 4350 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4351 |
|
| 4352 |
protected:
|
| 4353 |
+
// [stringbuf.virtuals], overridden virtual functions
|
| 4354 |
+
int_type underflow() override;
|
| 4355 |
+
int_type pbackfail(int_type c = traits::eof()) override;
|
| 4356 |
+
int_type overflow (int_type c = traits::eof()) override;
|
| 4357 |
+
basic_streambuf<charT, traits>* setbuf(charT*, streamsize) override;
|
| 4358 |
|
| 4359 |
+
pos_type seekoff(off_type off, ios_base::seekdir way,
|
|
|
|
| 4360 |
ios_base::openmode which
|
| 4361 |
+
= ios_base::in | ios_base::out) override;
|
| 4362 |
+
pos_type seekpos(pos_type sp,
|
| 4363 |
ios_base::openmode which
|
| 4364 |
+
= ios_base::in | ios_base::out) override;
|
| 4365 |
|
| 4366 |
private:
|
| 4367 |
ios_base::openmode mode; // exposition only
|
| 4368 |
};
|
| 4369 |
|
|
|
|
| 4385 |
read, and `out` set if the output sequence can be written.
|
| 4386 |
|
| 4387 |
#### `basic_stringbuf` constructors <a id="stringbuf.cons">[[stringbuf.cons]]</a>
|
| 4388 |
|
| 4389 |
``` cpp
|
| 4390 |
+
explicit basic_stringbuf(
|
| 4391 |
+
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4392 |
```
|
| 4393 |
|
| 4394 |
*Effects:* Constructs an object of class `basic_stringbuf`, initializing
|
| 4395 |
the base class with `basic_streambuf()` ([[streambuf.cons]]), and
|
| 4396 |
initializing `mode` with `which`.
|
| 4397 |
|
| 4398 |
+
*Postconditions:* `str() == ""`.
|
| 4399 |
|
| 4400 |
``` cpp
|
| 4401 |
+
explicit basic_stringbuf(
|
| 4402 |
+
const basic_string<charT, traits, Allocator>& s,
|
| 4403 |
ios_base::openmode which = ios_base::in | ios_base::out);
|
| 4404 |
```
|
| 4405 |
|
| 4406 |
*Effects:* Constructs an object of class `basic_stringbuf`, initializing
|
| 4407 |
the base class with `basic_streambuf()` ([[streambuf.cons]]), and
|
|
|
|
| 4456 |
template <class charT, class traits, class Allocator>
|
| 4457 |
void swap(basic_stringbuf<charT, traits, Allocator>& x,
|
| 4458 |
basic_stringbuf<charT, traits, Allocator>& y);
|
| 4459 |
```
|
| 4460 |
|
| 4461 |
+
*Effects:* As if by `x.swap(y)`.
|
| 4462 |
|
| 4463 |
#### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
|
| 4464 |
|
| 4465 |
``` cpp
|
| 4466 |
basic_string<charT, traits, Allocator> str() const;
|
|
|
|
| 4469 |
*Returns:* A `basic_string` object whose content is equal to the
|
| 4470 |
`basic_stringbuf` underlying character sequence. If the
|
| 4471 |
`basic_stringbuf` was created only in input mode, the resultant
|
| 4472 |
`basic_string` contains the character sequence in the range \[`eback()`,
|
| 4473 |
`egptr()`). If the `basic_stringbuf` was created with
|
| 4474 |
+
`which & ios_base::out` being nonzero then the resultant `basic_string`
|
| 4475 |
contains the character sequence in the range \[`pbase()`, `high_mark`),
|
| 4476 |
where `high_mark` represents the position one past the highest
|
| 4477 |
initialized character in the buffer. Characters can be initialized by
|
| 4478 |
writing to the stream, by constructing the `basic_stringbuf` with a
|
| 4479 |
`basic_string`, or by calling the `str(basic_string)` member function.
|
|
|
|
| 4490 |
|
| 4491 |
*Effects:* Copies the content of `s` into the `basic_stringbuf`
|
| 4492 |
underlying character sequence and initializes the input and output
|
| 4493 |
sequences according to `mode`.
|
| 4494 |
|
| 4495 |
+
*Postconditions:* If `mode & ios_base::out` is nonzero, `pbase()` points
|
| 4496 |
+
to the first underlying character and `epptr()` `>= pbase() + s.size()`
|
| 4497 |
+
holds; in addition, if `mode & ios_base::ate` is nonzero,
|
| 4498 |
`pptr() == pbase() + s.size()` holds, otherwise `pptr() == pbase()` is
|
| 4499 |
+
`true`. If `mode & ios_base::in` is nonzero, `eback()` points to the
|
| 4500 |
+
first underlying character, and both `gptr() == eback()` and
|
| 4501 |
`egptr() == eback() + s.size()` hold.
|
| 4502 |
|
| 4503 |
#### Overridden virtual functions <a id="stringbuf.virtuals">[[stringbuf.virtuals]]</a>
|
| 4504 |
|
| 4505 |
``` cpp
|
| 4506 |
+
int_type underflow() override;
|
| 4507 |
```
|
| 4508 |
|
| 4509 |
*Returns:* If the input sequence has a read position available, returns
|
| 4510 |
`traits::to_int_type(*gptr())`. Otherwise, returns `traits::eof()`. Any
|
| 4511 |
character in the underlying buffer which has been initialized is
|
| 4512 |
considered to be part of the input sequence.
|
| 4513 |
|
| 4514 |
``` cpp
|
| 4515 |
+
int_type pbackfail(int_type c = traits::eof()) override;
|
| 4516 |
```
|
| 4517 |
|
| 4518 |
*Effects:* Puts back the character designated by `c` to the input
|
| 4519 |
sequence, if possible, in one of three ways:
|
| 4520 |
|
|
|
|
| 4533 |
|
| 4534 |
*Remarks:* If the function can succeed in more than one of these ways,
|
| 4535 |
it is unspecified which way is chosen.
|
| 4536 |
|
| 4537 |
``` cpp
|
| 4538 |
+
int_type overflow(int_type c = traits::eof()) override;
|
| 4539 |
```
|
| 4540 |
|
| 4541 |
*Effects:* Appends the character designated by `c` to the output
|
| 4542 |
sequence, if possible, in one of two ways:
|
| 4543 |
|
|
|
|
| 4563 |
`egptr()` to point just past the new write position.
|
| 4564 |
|
| 4565 |
``` cpp
|
| 4566 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 4567 |
ios_base::openmode which
|
| 4568 |
+
= ios_base::in | ios_base::out) override;
|
| 4569 |
```
|
| 4570 |
|
| 4571 |
*Effects:* Alters the stream position within one of the controlled
|
| 4572 |
sequences, if possible, as indicated in
|
| 4573 |
Table [[tab:iostreams.seekoff.positioning]].
|
|
|
|
| 4595 |
| `way == ios_base::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
|
| 4596 |
| `way == ios_base::end` | the high mark pointer minus the beginning pointer (`high_mark - xbeg`). |
|
| 4597 |
|
| 4598 |
|
| 4599 |
If `(newoff + off) < 0`, or if `newoff + off` refers to an uninitialized
|
| 4600 |
+
character ([[stringbuf.members]]), the positioning operation fails.
|
| 4601 |
+
Otherwise, the function assigns `xbeg + newoff + off` to the next
|
| 4602 |
+
pointer `xnext`.
|
| 4603 |
|
| 4604 |
*Returns:* `pos_type(newoff)`, constructed from the resultant offset
|
| 4605 |
`newoff` (of type `off_type`), that stores the resultant stream
|
| 4606 |
position, if possible. If the positioning operation fails, or if the
|
| 4607 |
constructed object cannot represent the resultant stream position, the
|
| 4608 |
return value is `pos_type(off_type(-1))`.
|
| 4609 |
|
| 4610 |
``` cpp
|
| 4611 |
+
pos_type seekpos(pos_type sp,
|
| 4612 |
+
ios_base::openmode which
|
| 4613 |
+
= ios_base::in | ios_base::out) override;
|
| 4614 |
```
|
| 4615 |
|
| 4616 |
*Effects:* Equivalent to `seekoff(off_type(sp), ios_base::beg, which)`.
|
| 4617 |
|
| 4618 |
*Returns:* `sp` to indicate success, or `pos_type(off_type(-1))` to
|
|
|
|
| 4633 |
namespace std {
|
| 4634 |
template <class charT, class traits = char_traits<charT>,
|
| 4635 |
class Allocator = allocator<charT>>
|
| 4636 |
class basic_istringstream : public basic_istream<charT, traits> {
|
| 4637 |
public:
|
| 4638 |
+
using char_type = charT;
|
| 4639 |
+
using int_type = typename traits::int_type;
|
| 4640 |
+
using pos_type = typename traits::pos_type;
|
| 4641 |
+
using off_type = typename traits::off_type;
|
| 4642 |
+
using traits_type = traits;
|
| 4643 |
+
using allocator_type = Allocator;
|
| 4644 |
|
| 4645 |
+
// [istringstream.cons], constructors
|
| 4646 |
+
explicit basic_istringstream(
|
| 4647 |
+
ios_base::openmode which = ios_base::in);
|
| 4648 |
explicit basic_istringstream(
|
| 4649 |
const basic_string<charT, traits, Allocator>& str,
|
| 4650 |
ios_base::openmode which = ios_base::in);
|
| 4651 |
basic_istringstream(const basic_istringstream& rhs) = delete;
|
| 4652 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4653 |
|
| 4654 |
+
// [istringstream.assign], assign and swap
|
| 4655 |
basic_istringstream& operator=(const basic_istringstream& rhs) = delete;
|
| 4656 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
| 4657 |
void swap(basic_istringstream& rhs);
|
| 4658 |
|
| 4659 |
+
// [istringstream.members], members
|
| 4660 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4661 |
|
| 4662 |
basic_string<charT, traits, Allocator> str() const;
|
| 4663 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4664 |
private:
|
|
|
|
| 4705 |
basic_istringstream(basic_istringstream&& rhs);
|
| 4706 |
```
|
| 4707 |
|
| 4708 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4709 |
by move constructing the base class, and the contained
|
| 4710 |
+
`basic_stringbuf`. Next `basic_istream<charT, traits>::set_rdbuf(&sb)`
|
| 4711 |
+
is called to install the contained `basic_stringbuf`.
|
| 4712 |
|
| 4713 |
#### Assign and swap <a id="istringstream.assign">[[istringstream.assign]]</a>
|
| 4714 |
|
| 4715 |
``` cpp
|
| 4716 |
basic_istringstream& operator=(basic_istringstream&& rhs);
|
|
|
|
| 4732 |
template <class charT, class traits, class Allocator>
|
| 4733 |
void swap(basic_istringstream<charT, traits, Allocator>& x,
|
| 4734 |
basic_istringstream<charT, traits, Allocator>& y);
|
| 4735 |
```
|
| 4736 |
|
| 4737 |
+
*Effects:* As if by `x.swap(y)`.
|
| 4738 |
|
| 4739 |
#### Member functions <a id="istringstream.members">[[istringstream.members]]</a>
|
| 4740 |
|
| 4741 |
``` cpp
|
| 4742 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4743 |
```
|
| 4744 |
|
| 4745 |
+
*Returns:*
|
| 4746 |
+
`const_cast<basic_stringbuf<charT, traits, Allocator>*>(&sb)`.
|
| 4747 |
|
| 4748 |
``` cpp
|
| 4749 |
basic_string<charT, traits, Allocator> str() const;
|
| 4750 |
```
|
| 4751 |
|
|
|
|
| 4763 |
namespace std {
|
| 4764 |
template <class charT, class traits = char_traits<charT>,
|
| 4765 |
class Allocator = allocator<charT>>
|
| 4766 |
class basic_ostringstream : public basic_ostream<charT, traits> {
|
| 4767 |
public:
|
| 4768 |
+
using char_type = charT;
|
| 4769 |
+
using int_type = typename traits::int_type;
|
| 4770 |
+
using pos_type = typename traits::pos_type;
|
| 4771 |
+
using off_type = typename traits::off_type;
|
| 4772 |
+
using traits_type = traits;
|
| 4773 |
+
using allocator_type = Allocator;
|
| 4774 |
|
| 4775 |
+
// [ostringstream.cons], constructors
|
| 4776 |
+
explicit basic_ostringstream(
|
| 4777 |
+
ios_base::openmode which = ios_base::out);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4778 |
explicit basic_ostringstream(
|
| 4779 |
const basic_string<charT, traits, Allocator>& str,
|
| 4780 |
ios_base::openmode which = ios_base::out);
|
| 4781 |
basic_ostringstream(const basic_ostringstream& rhs) = delete;
|
| 4782 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 4783 |
|
| 4784 |
+
// [ostringstream.assign], assign and swap
|
| 4785 |
basic_ostringstream& operator=(const basic_ostringstream& rhs) = delete;
|
| 4786 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
| 4787 |
void swap(basic_ostringstream& rhs);
|
| 4788 |
|
| 4789 |
+
// [ostringstream.members], members
|
| 4790 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4791 |
|
| 4792 |
basic_string<charT, traits, Allocator> str() const;
|
| 4793 |
void str(const basic_string<charT, traits, Allocator>& s);
|
| 4794 |
private:
|
|
|
|
| 4809 |
- `sb`, the `stringbuf` object.
|
| 4810 |
|
| 4811 |
#### `basic_ostringstream` constructors <a id="ostringstream.cons">[[ostringstream.cons]]</a>
|
| 4812 |
|
| 4813 |
``` cpp
|
| 4814 |
+
explicit basic_ostringstream(
|
| 4815 |
+
ios_base::openmode which = ios_base::out);
|
| 4816 |
```
|
| 4817 |
|
| 4818 |
*Effects:* Constructs an object of class `basic_ostringstream`,
|
| 4819 |
initializing the base class with `basic_ostream(&sb)` and initializing
|
| 4820 |
`sb` with
|
|
|
|
| 4835 |
basic_ostringstream(basic_ostringstream&& rhs);
|
| 4836 |
```
|
| 4837 |
|
| 4838 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4839 |
by move constructing the base class, and the contained
|
| 4840 |
+
`basic_stringbuf`. Next `basic_ostream<charT, traits>::set_rdbuf(&sb)`
|
| 4841 |
+
is called to install the contained `basic_stringbuf`.
|
| 4842 |
|
| 4843 |
#### Assign and swap <a id="ostringstream.assign">[[ostringstream.assign]]</a>
|
| 4844 |
|
| 4845 |
``` cpp
|
| 4846 |
basic_ostringstream& operator=(basic_ostringstream&& rhs);
|
|
|
|
| 4862 |
template <class charT, class traits, class Allocator>
|
| 4863 |
void swap(basic_ostringstream<charT, traits, Allocator>& x,
|
| 4864 |
basic_ostringstream<charT, traits, Allocator>& y);
|
| 4865 |
```
|
| 4866 |
|
| 4867 |
+
*Effects:* As if by `x.swap(y)`.
|
| 4868 |
|
| 4869 |
#### Member functions <a id="ostringstream.members">[[ostringstream.members]]</a>
|
| 4870 |
|
| 4871 |
``` cpp
|
| 4872 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4873 |
```
|
| 4874 |
|
| 4875 |
+
*Returns:*
|
| 4876 |
+
`const_cast<basic_stringbuf<charT, traits, Allocator>*>(&sb)`.
|
| 4877 |
|
| 4878 |
``` cpp
|
| 4879 |
basic_string<charT, traits, Allocator> str() const;
|
| 4880 |
```
|
| 4881 |
|
|
|
|
| 4891 |
|
| 4892 |
``` cpp
|
| 4893 |
namespace std {
|
| 4894 |
template <class charT, class traits = char_traits<charT>,
|
| 4895 |
class Allocator = allocator<charT>>
|
| 4896 |
+
class basic_stringstream : public basic_iostream<charT, traits> {
|
|
|
|
| 4897 |
public:
|
| 4898 |
+
using char_type = charT;
|
| 4899 |
+
using int_type = typename traits::int_type;
|
| 4900 |
+
using pos_type = typename traits::pos_type;
|
| 4901 |
+
using off_type = typename traits::off_type;
|
| 4902 |
+
using traits_type = traits;
|
| 4903 |
+
using allocator_type = Allocator;
|
| 4904 |
|
| 4905 |
+
// [stringstream.cons], constructors
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4906 |
explicit basic_stringstream(
|
| 4907 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4908 |
explicit basic_stringstream(
|
| 4909 |
const basic_string<charT, traits, Allocator>& str,
|
| 4910 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4911 |
basic_stringstream(const basic_stringstream& rhs) = delete;
|
| 4912 |
basic_stringstream(basic_stringstream&& rhs);
|
| 4913 |
|
| 4914 |
+
// [stringstream.assign], assign and swap
|
| 4915 |
basic_stringstream& operator=(const basic_stringstream& rhs) = delete;
|
| 4916 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
| 4917 |
void swap(basic_stringstream& rhs);
|
| 4918 |
|
| 4919 |
+
// [stringstream.members], members
|
| 4920 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
| 4921 |
basic_string<charT, traits, Allocator> str() const;
|
| 4922 |
void str(const basic_string<charT, traits, Allocator>& str);
|
| 4923 |
|
| 4924 |
private:
|
|
|
|
| 4938 |
associated sequence. For the sake of exposition, the maintained data is
|
| 4939 |
presented here as
|
| 4940 |
|
| 4941 |
- `sb`, the `stringbuf` object.
|
| 4942 |
|
| 4943 |
+
#### `basic_stringstream` constructors <a id="stringstream.cons">[[stringstream.cons]]</a>
|
| 4944 |
|
| 4945 |
``` cpp
|
| 4946 |
explicit basic_stringstream(
|
| 4947 |
ios_base::openmode which = ios_base::out | ios_base::in);
|
| 4948 |
```
|
|
|
|
| 4967 |
basic_stringstream(basic_stringstream&& rhs);
|
| 4968 |
```
|
| 4969 |
|
| 4970 |
*Effects:* Move constructs from the rvalue `rhs`. This is accomplished
|
| 4971 |
by move constructing the base class, and the contained
|
| 4972 |
+
`basic_stringbuf`. Next `basic_istream<charT, traits>::set_rdbuf(&sb)`
|
| 4973 |
+
is called to install the contained `basic_stringbuf`.
|
| 4974 |
|
| 4975 |
#### Assign and swap <a id="stringstream.assign">[[stringstream.assign]]</a>
|
| 4976 |
|
| 4977 |
``` cpp
|
| 4978 |
basic_stringstream& operator=(basic_stringstream&& rhs);
|
|
|
|
| 4994 |
template <class charT, class traits, class Allocator>
|
| 4995 |
void swap(basic_stringstream<charT, traits, Allocator>& x,
|
| 4996 |
basic_stringstream<charT, traits, Allocator>& y);
|
| 4997 |
```
|
| 4998 |
|
| 4999 |
+
*Effects:* As if by `x.swap(y)`.
|
| 5000 |
|
| 5001 |
#### Member functions <a id="stringstream.members">[[stringstream.members]]</a>
|
| 5002 |
|
| 5003 |
``` cpp
|
| 5004 |
basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
|
|
|
|
| 5018 |
|
| 5019 |
*Effects:* Calls `rdbuf()->str(str)`.
|
| 5020 |
|
| 5021 |
## File-based streams <a id="file.streams">[[file.streams]]</a>
|
| 5022 |
|
| 5023 |
+
### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
|
| 5024 |
+
|
| 5025 |
+
``` cpp
|
| 5026 |
+
namespace std {
|
| 5027 |
+
template <class charT, class traits = char_traits<charT>>
|
| 5028 |
+
class basic_filebuf;
|
| 5029 |
+
using filebuf = basic_filebuf<char>;
|
| 5030 |
+
using wfilebuf = basic_filebuf<wchar_t>;
|
| 5031 |
+
|
| 5032 |
+
template <class charT, class traits = char_traits<charT>>
|
| 5033 |
+
class basic_ifstream;
|
| 5034 |
+
using ifstream = basic_ifstream<char>;
|
| 5035 |
+
using wifstream = basic_ifstream<wchar_t>;
|
| 5036 |
+
|
| 5037 |
+
template <class charT, class traits = char_traits<charT>>
|
| 5038 |
+
class basic_ofstream;
|
| 5039 |
+
using ofstream = basic_ofstream<char>;
|
| 5040 |
+
using wofstream = basic_ofstream<wchar_t>;
|
| 5041 |
+
|
| 5042 |
+
template <class charT, class traits = char_traits<charT>>
|
| 5043 |
+
class basic_fstream;
|
| 5044 |
+
using fstream = basic_fstream<char>;
|
| 5045 |
+
using wfstream = basic_fstream<wchar_t>;
|
| 5046 |
+
}
|
| 5047 |
+
```
|
| 5048 |
|
| 5049 |
The header `<fstream>` defines four class templates and eight types that
|
| 5050 |
associate stream buffers with files and assist reading and writing
|
| 5051 |
files.
|
| 5052 |
|
| 5053 |
+
[*Note 1*: The class template `basic_filebuf` treats a file as a source
|
| 5054 |
+
or sink of bytes. In an environment that uses a large character set, the
|
| 5055 |
+
file typically holds multibyte character sequences and the
|
| 5056 |
+
`basic_filebuf` object converts those multibyte sequences into wide
|
| 5057 |
+
character sequences. — *end note*]
|
|
|
|
| 5058 |
|
| 5059 |
+
In this subclause, member functions taking arguments of
|
| 5060 |
+
`const filesystem::path::value_type*` are only be provided on systems
|
| 5061 |
+
where `filesystem::path::value_type` ([[fs.class.path]]) is not `char`.
|
|
|
|
| 5062 |
|
| 5063 |
+
[*Note 2*: These functions enable class `path` support for systems with
|
| 5064 |
+
a wide native path character type, such as `wchar_t`. — *end note*]
|
|
|
|
|
|
|
| 5065 |
|
| 5066 |
+
### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 5067 |
|
| 5068 |
``` cpp
|
| 5069 |
namespace std {
|
| 5070 |
template <class charT, class traits = char_traits<charT>>
|
| 5071 |
class basic_filebuf : public basic_streambuf<charT, traits> {
|
| 5072 |
public:
|
| 5073 |
+
using char_type = charT;
|
| 5074 |
+
using int_type = typename traits::int_type;
|
| 5075 |
+
using pos_type = typename traits::pos_type;
|
| 5076 |
+
using off_type = typename traits::off_type;
|
| 5077 |
+
using traits_type = traits;
|
| 5078 |
|
| 5079 |
+
// [filebuf.cons], constructors/destructor
|
| 5080 |
basic_filebuf();
|
| 5081 |
basic_filebuf(const basic_filebuf& rhs) = delete;
|
| 5082 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5083 |
virtual ~basic_filebuf();
|
| 5084 |
|
| 5085 |
+
// [filebuf.assign], assign and swap
|
| 5086 |
basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
|
| 5087 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5088 |
void swap(basic_filebuf& rhs);
|
| 5089 |
|
| 5090 |
+
// [filebuf.members], members
|
| 5091 |
bool is_open() const;
|
| 5092 |
+
basic_filebuf* open(const char* s, ios_base::openmode mode);
|
| 5093 |
+
basic_filebuf* open(const filesystem::path::value_type* s,
|
| 5094 |
+
ios_base::openmode mode); // wide systems only; see [fstream.syn]
|
| 5095 |
+
basic_filebuf* open(const string& s,
|
| 5096 |
ios_base::openmode mode);
|
| 5097 |
+
basic_filebuf* open(const filesystem::path& s,
|
| 5098 |
ios_base::openmode mode);
|
| 5099 |
+
basic_filebuf* close();
|
| 5100 |
|
| 5101 |
protected:
|
| 5102 |
+
// [filebuf.virtuals], overridden virtual functions
|
| 5103 |
+
streamsize showmanyc() override;
|
| 5104 |
+
int_type underflow() override;
|
| 5105 |
+
int_type uflow() override;
|
| 5106 |
+
int_type pbackfail(int_type c = traits::eof()) override;
|
| 5107 |
+
int_type overflow (int_type c = traits::eof()) override;
|
| 5108 |
|
| 5109 |
+
basic_streambuf<charT, traits>* setbuf(char_type* s,
|
| 5110 |
+
streamsize n) override;
|
| 5111 |
+
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 5112 |
+
ios_base::openmode which
|
| 5113 |
+
= ios_base::in | ios_base::out) override;
|
| 5114 |
+
pos_type seekpos(pos_type sp,
|
| 5115 |
+
ios_base::openmode which
|
| 5116 |
+
= ios_base::in | ios_base::out) override;
|
| 5117 |
+
int sync() override;
|
| 5118 |
+
void imbue(const locale& loc) override;
|
| 5119 |
};
|
| 5120 |
|
| 5121 |
template <class charT, class traits>
|
| 5122 |
void swap(basic_filebuf<charT, traits>& x,
|
| 5123 |
basic_filebuf<charT, traits>& y);
|
|
|
|
| 5127 |
The class `basic_filebuf<charT, traits>` associates both the input
|
| 5128 |
sequence and the output sequence with a file.
|
| 5129 |
|
| 5130 |
The restrictions on reading and writing a sequence controlled by an
|
| 5131 |
object of class `basic_filebuf<charT, traits>` are the same as for
|
| 5132 |
+
reading and writing with the C standard library `FILE`s.
|
| 5133 |
|
| 5134 |
In particular:
|
| 5135 |
|
| 5136 |
- If the file is not open for reading the input sequence cannot be read.
|
| 5137 |
- If the file is not open for writing the output sequence cannot be
|
| 5138 |
written.
|
| 5139 |
- A joint file position is maintained for both the input sequence and
|
| 5140 |
the output sequence.
|
| 5141 |
|
| 5142 |
An instance of `basic_filebuf` behaves as described in [[filebuf]]
|
| 5143 |
+
provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
|
| 5144 |
+
the behavior is undefined.
|
| 5145 |
|
| 5146 |
In order to support file I/O and multibyte/wide character conversion,
|
| 5147 |
conversions are performed using members of a facet, referred to as
|
| 5148 |
`a_codecvt` in following sections, obtained as if by
|
| 5149 |
|
|
|
|
| 5160 |
|
| 5161 |
*Effects:* Constructs an object of class `basic_filebuf<charT, traits>`,
|
| 5162 |
initializing the base class with
|
| 5163 |
`basic_streambuf<charT, traits>()` ([[streambuf.cons]]).
|
| 5164 |
|
| 5165 |
+
*Postconditions:* `is_open() == false`.
|
| 5166 |
|
| 5167 |
``` cpp
|
| 5168 |
basic_filebuf(basic_filebuf&& rhs);
|
| 5169 |
```
|
| 5170 |
|
|
|
|
| 5207 |
|
| 5208 |
``` cpp
|
| 5209 |
basic_filebuf& operator=(basic_filebuf&& rhs);
|
| 5210 |
```
|
| 5211 |
|
| 5212 |
+
*Effects:* Calls `close()` then move assigns from `rhs`. After the move
|
| 5213 |
+
assignment `*this` has the observable state it would have had if it had
|
| 5214 |
+
been move constructed from `rhs` (see [[filebuf.cons]]).
|
| 5215 |
|
| 5216 |
*Returns:* `*this`.
|
| 5217 |
|
| 5218 |
``` cpp
|
| 5219 |
void swap(basic_filebuf& rhs);
|
|
|
|
| 5225 |
template <class charT, class traits>
|
| 5226 |
void swap(basic_filebuf<charT, traits>& x,
|
| 5227 |
basic_filebuf<charT, traits>& y);
|
| 5228 |
```
|
| 5229 |
|
| 5230 |
+
*Effects:* As if by `x.swap(y)`.
|
| 5231 |
|
| 5232 |
#### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
|
| 5233 |
|
| 5234 |
``` cpp
|
| 5235 |
bool is_open() const;
|
|
|
|
| 5237 |
|
| 5238 |
*Returns:* `true` if a previous call to `open` succeeded (returned a
|
| 5239 |
non-null value) and there has been no intervening call to close.
|
| 5240 |
|
| 5241 |
``` cpp
|
| 5242 |
+
basic_filebuf* open(const char* s, ios_base::openmode mode);
|
| 5243 |
+
basic_filebuf* open(const filesystem::path::value_type* s,
|
| 5244 |
+
ios_base::openmode mode); // wide systems only; see [fstream.syn]
|
| 5245 |
```
|
| 5246 |
|
| 5247 |
*Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
|
| 5248 |
initializes the `filebuf` as required. It then opens a file, if
|
| 5249 |
possible, whose name is the NTBS`s` (as if by calling
|
| 5250 |
+
`fopen(s, modstr)`). The NTBS`modstr` is determined from
|
| 5251 |
`mode & ~ios_base::ate` as indicated in
|
| 5252 |
Table [[tab:iostreams.file.open.modes]]. If `mode` is not some
|
| 5253 |
combination of flags shown in the table then the open fails.
|
| 5254 |
|
| 5255 |
**Table: File open modes** <a id="tab:iostreams.file.open.modes">[tab:iostreams.file.open.modes]</a>
|
|
|
|
| 5275 |
| + | + | | | + | `"a+b"` |
|
| 5276 |
|
| 5277 |
|
| 5278 |
If the open operation succeeds and `(mode & ios_base::ate) != 0`,
|
| 5279 |
positions the file to the end (as if by calling
|
| 5280 |
+
`fseek(file, 0, SEEK_END)`).[^40]
|
| 5281 |
|
| 5282 |
If the repositioning operation fails, calls `close()` and returns a null
|
| 5283 |
pointer to indicate failure.
|
| 5284 |
|
| 5285 |
*Returns:* `this` if successful, a null pointer otherwise.
|
| 5286 |
|
| 5287 |
``` cpp
|
| 5288 |
+
basic_filebuf* open(const string& s, ios_base::openmode mode);
|
| 5289 |
+
basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
|
| 5290 |
```
|
| 5291 |
|
| 5292 |
*Returns:* `open(s.c_str(), mode);`
|
| 5293 |
|
| 5294 |
``` cpp
|
| 5295 |
+
basic_filebuf* close();
|
| 5296 |
```
|
| 5297 |
|
| 5298 |
*Effects:* If `is_open() == false`, returns a null pointer. If a put
|
| 5299 |
area exists, calls `overflow(traits::eof())` to flush characters. If the
|
| 5300 |
last virtual member function called on `*this` (between `underflow`,
|
| 5301 |
`overflow`, `seekoff`, and `seekpos`) was `overflow` then calls
|
| 5302 |
`a_codecvt.unshift` (possibly several times) to determine a termination
|
| 5303 |
sequence, inserts those characters and calls `overflow(traits::eof())`
|
| 5304 |
again. Finally, regardless of whether any of the preceding calls fails
|
| 5305 |
or throws an exception, the function closes the file (as if by calling
|
| 5306 |
+
`fclose(file)`). If any of the calls made by the function, including
|
| 5307 |
+
`fclose`, fails, `close` fails by returning a null pointer. If one of
|
| 5308 |
+
these calls throws an exception, the exception is caught and rethrown
|
| 5309 |
+
after closing the file.
|
| 5310 |
|
| 5311 |
*Returns:* `this` on success, a null pointer otherwise.
|
| 5312 |
|
| 5313 |
+
*Postconditions:* `is_open() == false`.
|
| 5314 |
|
| 5315 |
#### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
|
| 5316 |
|
| 5317 |
``` cpp
|
| 5318 |
+
streamsize showmanyc() override;
|
| 5319 |
```
|
| 5320 |
|
| 5321 |
*Effects:* Behaves the same as
|
| 5322 |
`basic_streambuf::showmanyc()` ([[streambuf.virtuals]]).
|
| 5323 |
|
| 5324 |
*Remarks:* An implementation might well provide an overriding definition
|
| 5325 |
for this function signature if it can determine that more characters can
|
| 5326 |
be read from the input sequence.
|
| 5327 |
|
| 5328 |
``` cpp
|
| 5329 |
+
int_type underflow() override;
|
| 5330 |
```
|
| 5331 |
|
| 5332 |
*Effects:* Behaves according to the description of
|
| 5333 |
`basic_streambuf<charT, traits>::underflow()`, with the specialization
|
| 5334 |
that a sequence of characters is read from the input sequence as if by
|
| 5335 |
reading from the associated file into an internal buffer (`extern_buf`)
|
| 5336 |
+
and then as if by doing:
|
| 5337 |
|
| 5338 |
``` cpp
|
| 5339 |
char extern_buf[XSIZE];
|
| 5340 |
char* extern_end;
|
| 5341 |
charT intern_buf[ISIZE];
|
|
|
|
| 5349 |
(`fpos_t`) corresponding to each character between `intern_buf` and
|
| 5350 |
`intern_end`. If the value of `r` indicates that `a_codecvt.in()` ran
|
| 5351 |
out of space in `intern_buf`, retry with a larger `intern_buf`.
|
| 5352 |
|
| 5353 |
``` cpp
|
| 5354 |
+
int_type uflow() override;
|
| 5355 |
```
|
| 5356 |
|
| 5357 |
*Effects:* Behaves according to the description of
|
| 5358 |
+
`basic_streambuf<charT, traits>::uflow()`, with the specialization that
|
| 5359 |
+
a sequence of characters is read from the input with the same method as
|
| 5360 |
used by `underflow`.
|
| 5361 |
|
| 5362 |
``` cpp
|
| 5363 |
+
int_type pbackfail(int_type c = traits::eof()) override;
|
| 5364 |
```
|
| 5365 |
|
| 5366 |
*Effects:* Puts back the character designated by `c` to the input
|
| 5367 |
sequence, if possible, in one of three ways:
|
| 5368 |
|
|
|
|
| 5390 |
If the function can succeed in more than one of these ways, it is
|
| 5391 |
unspecified which way is chosen. The function can alter the number of
|
| 5392 |
putback positions available as a result of any call.
|
| 5393 |
|
| 5394 |
``` cpp
|
| 5395 |
+
int_type overflow(int_type c = traits::eof()) override;
|
| 5396 |
```
|
| 5397 |
|
| 5398 |
*Effects:* Behaves according to the description of
|
| 5399 |
`basic_streambuf<charT, traits>::overflow(c)`, except that the behavior
|
| 5400 |
of “consuming characters” is performed by first converting as if by:
|
|
|
|
| 5423 |
|
| 5424 |
*Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
|
| 5425 |
to indicate failure. If `is_open() == false`, the function always fails.
|
| 5426 |
|
| 5427 |
``` cpp
|
| 5428 |
+
basic_streambuf* setbuf(char_type* s, streamsize n) override;
|
| 5429 |
```
|
| 5430 |
|
| 5431 |
*Effects:* If `setbuf(0, 0)` is called on a stream before any I/O has
|
| 5432 |
occurred on that stream, the stream becomes unbuffered. Otherwise the
|
| 5433 |
results are *implementation-defined*. “Unbuffered” means that `pbase()`
|
| 5434 |
and `pptr()` always return null and output to the file should appear as
|
| 5435 |
soon as possible.
|
| 5436 |
|
| 5437 |
``` cpp
|
| 5438 |
pos_type seekoff(off_type off, ios_base::seekdir way,
|
| 5439 |
+
ios_base::openmode which
|
| 5440 |
+
= ios_base::in | ios_base::out) override;
|
| 5441 |
```
|
| 5442 |
|
| 5443 |
*Effects:* Let `width` denote `a_codecvt.encoding()`. If
|
| 5444 |
`is_open() == false`, or `off != 0 && width <= 0`, then the positioning
|
| 5445 |
operation fails. Otherwise, if `way != basic_ios::cur` or `off != 0`,
|
| 5446 |
and if the last operation was output, then update the output sequence
|
| 5447 |
and write any unshift sequence. Next, seek to the new position: if
|
| 5448 |
+
`width > 0`, call `fseek(file, width * off, whence)`, otherwise call
|
| 5449 |
+
`fseek(file, 0, whence)`.
|
| 5450 |
|
| 5451 |
*Remarks:* “The last operation was output” means either the last virtual
|
| 5452 |
operation was overflow or the put buffer is non-empty. “Write any
|
| 5453 |
unshift sequence” means, if `width` if less than zero then call
|
| 5454 |
`a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
|
|
|
|
| 5470 |
fails, or if the object cannot represent the resultant stream position,
|
| 5471 |
returns `pos_type(off_type(-1))`.
|
| 5472 |
|
| 5473 |
``` cpp
|
| 5474 |
pos_type seekpos(pos_type sp,
|
| 5475 |
+
ios_base::openmode which
|
| 5476 |
+
= ios_base::in | ios_base::out) override;
|
| 5477 |
```
|
| 5478 |
|
| 5479 |
Alters the file position, if possible, to correspond to the position
|
| 5480 |
stored in `sp` (as described below). Altering the file position performs
|
| 5481 |
as follows:
|
| 5482 |
|
| 5483 |
1. if `(om & ios_base::out) != 0`, then update the output sequence and
|
| 5484 |
write any unshift sequence;
|
| 5485 |
+
2. set the file position to `sp` as if by a call to `fsetpos`;
|
| 5486 |
3. if `(om & ios_base::in) != 0`, then update the input sequence;
|
| 5487 |
|
| 5488 |
where `om` is the open mode passed to the last call to `open()`. The
|
| 5489 |
+
operation fails if `is_open()` returns `false`.
|
| 5490 |
|
| 5491 |
If `sp` is an invalid stream position, or if the function positions
|
| 5492 |
neither sequence, the positioning operation fails. If `sp` has not been
|
| 5493 |
obtained by a previous successful call to one of the positioning
|
| 5494 |
functions (`seekoff` or `seekpos`) on the same file the effects are
|
| 5495 |
undefined.
|
| 5496 |
|
| 5497 |
*Returns:* `sp` on success. Otherwise returns `pos_type(off_type(-1))`.
|
| 5498 |
|
| 5499 |
``` cpp
|
| 5500 |
+
int sync() override;
|
| 5501 |
```
|
| 5502 |
|
| 5503 |
*Effects:* If a put area exists, calls `filebuf::overflow` to write the
|
| 5504 |
+
characters to the file, then flushes the file as if by calling
|
| 5505 |
+
`fflush(file)`. If a get area exists, the effect is
|
| 5506 |
*implementation-defined*.
|
| 5507 |
|
| 5508 |
``` cpp
|
| 5509 |
+
void imbue(const locale& loc) override;
|
| 5510 |
```
|
| 5511 |
|
| 5512 |
+
*Requires:* If the file is not positioned at its beginning and the
|
| 5513 |
+
encoding of the current locale as determined by `a_codecvt.encoding()`
|
| 5514 |
+
is state-dependent ([[locale.codecvt.virtuals]]) then that facet is the
|
| 5515 |
same as the corresponding facet of `loc`.
|
| 5516 |
|
| 5517 |
*Effects:* Causes characters inserted or extracted after this call to be
|
| 5518 |
converted according to `loc` until another call of `imbue`.
|
| 5519 |
|
| 5520 |
+
*Remarks:* This may require reconversion of previously converted
|
| 5521 |
+
characters. This in turn may require the implementation to be able to
|
| 5522 |
+
reconstruct the original contents of the file.
|
| 5523 |
|
| 5524 |
+
### Class template `basic_ifstream` <a id="ifstream">[[ifstream]]</a>
|
| 5525 |
|
| 5526 |
``` cpp
|
| 5527 |
namespace std {
|
| 5528 |
template <class charT, class traits = char_traits<charT>>
|
| 5529 |
class basic_ifstream : public basic_istream<charT, traits> {
|
| 5530 |
public:
|
| 5531 |
+
using char_type = charT;
|
| 5532 |
+
using int_type = typename traits::int_type;
|
| 5533 |
+
using pos_type = typename traits::pos_type;
|
| 5534 |
+
using off_type = typename traits::off_type;
|
| 5535 |
+
using traits_type = traits;
|
| 5536 |
|
| 5537 |
+
// [ifstream.cons], constructors
|
| 5538 |
basic_ifstream();
|
| 5539 |
explicit basic_ifstream(const char* s,
|
| 5540 |
ios_base::openmode mode = ios_base::in);
|
| 5541 |
+
explicit basic_ifstream(const filesystem::path::value_type* s,
|
| 5542 |
+
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 5543 |
explicit basic_ifstream(const string& s,
|
| 5544 |
ios_base::openmode mode = ios_base::in);
|
| 5545 |
+
explicit basic_ifstream(const filesystem::path& s,
|
| 5546 |
+
ios_base::openmode mode = ios_base::in);
|
| 5547 |
basic_ifstream(const basic_ifstream& rhs) = delete;
|
| 5548 |
basic_ifstream(basic_ifstream&& rhs);
|
| 5549 |
|
| 5550 |
+
// [ifstream.assign], assign and swap
|
| 5551 |
basic_ifstream& operator=(const basic_ifstream& rhs) = delete;
|
| 5552 |
basic_ifstream& operator=(basic_ifstream&& rhs);
|
| 5553 |
void swap(basic_ifstream& rhs);
|
| 5554 |
|
| 5555 |
+
// [ifstream.members], members
|
| 5556 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5557 |
|
| 5558 |
bool is_open() const;
|
| 5559 |
void open(const char* s, ios_base::openmode mode = ios_base::in);
|
| 5560 |
+
void open(const filesystem::path::value_type* s,
|
| 5561 |
+
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 5562 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
| 5563 |
+
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
|
| 5564 |
void close();
|
| 5565 |
private:
|
| 5566 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 5567 |
};
|
| 5568 |
|
|
|
|
| 5583 |
|
| 5584 |
``` cpp
|
| 5585 |
basic_ifstream();
|
| 5586 |
```
|
| 5587 |
|
| 5588 |
+
*Effects:* Constructs an object of class
|
| 5589 |
+
`basic_ifstream<charT, traits>`, initializing the base class with
|
| 5590 |
+
`basic_istream(&sb)` and initializing `sb` with
|
| 5591 |
+
`basic_filebuf<charT, traits>())` ([[istream.cons]], [[filebuf.cons]]).
|
| 5592 |
|
| 5593 |
``` cpp
|
| 5594 |
explicit basic_ifstream(const char* s,
|
| 5595 |
ios_base::openmode mode = ios_base::in);
|
| 5596 |
+
explicit basic_ifstream(const filesystem::path::value_type* s,
|
| 5597 |
+
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 5598 |
```
|
| 5599 |
|
| 5600 |
*Effects:* Constructs an object of class `basic_ifstream`, initializing
|
| 5601 |
the base class with `basic_istream(&sb)` and initializing `sb` with
|
| 5602 |
`basic_filebuf<charT, traits>())` ([[istream.cons]], [[filebuf.cons]]),
|
|
|
|
| 5604 |
returns a null pointer, calls `setstate(failbit)`.
|
| 5605 |
|
| 5606 |
``` cpp
|
| 5607 |
explicit basic_ifstream(const string& s,
|
| 5608 |
ios_base::openmode mode = ios_base::in);
|
| 5609 |
+
explicit basic_ifstream(const filesystem::path& s,
|
| 5610 |
+
ios_base::openmode mode = ios_base::in);
|
| 5611 |
```
|
| 5612 |
|
| 5613 |
+
*Effects:* The same as `basic_ifstream(s.c_str(), mode)`.
|
| 5614 |
|
| 5615 |
``` cpp
|
| 5616 |
basic_ifstream(basic_ifstream&& rhs);
|
| 5617 |
```
|
| 5618 |
|
|
|
|
| 5643 |
template <class charT, class traits>
|
| 5644 |
void swap(basic_ifstream<charT, traits>& x,
|
| 5645 |
basic_ifstream<charT, traits>& y);
|
| 5646 |
```
|
| 5647 |
|
| 5648 |
+
*Effects:* As if by `x.swap(y)`.
|
| 5649 |
|
| 5650 |
#### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
|
| 5651 |
|
| 5652 |
``` cpp
|
| 5653 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
|
|
| 5661 |
|
| 5662 |
*Returns:* `rdbuf()->is_open()`.
|
| 5663 |
|
| 5664 |
``` cpp
|
| 5665 |
void open(const char* s, ios_base::openmode mode = ios_base::in);
|
| 5666 |
+
void open(const filesystem::path::value_type* s,
|
| 5667 |
+
ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
|
| 5668 |
```
|
| 5669 |
|
| 5670 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::in)`. If that
|
| 5671 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 5672 |
+
`setstate(failbit)` (which may throw `ios_base::failure`)
|
| 5673 |
+
([[iostate.flags]]).
|
| 5674 |
|
| 5675 |
``` cpp
|
| 5676 |
void open(const string& s, ios_base::openmode mode = ios_base::in);
|
| 5677 |
+
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
|
| 5678 |
```
|
| 5679 |
|
| 5680 |
+
*Effects:* Calls `open(s.c_str(), mode)`.
|
| 5681 |
|
| 5682 |
``` cpp
|
| 5683 |
void close();
|
| 5684 |
```
|
| 5685 |
|
| 5686 |
*Effects:* Calls `rdbuf()->close()` and, if that function returns a null
|
| 5687 |
pointer, calls `setstate(failbit)` (which may throw
|
| 5688 |
+
`ios_base::failure`) ([[iostate.flags]]).
|
| 5689 |
|
| 5690 |
+
### Class template `basic_ofstream` <a id="ofstream">[[ofstream]]</a>
|
| 5691 |
|
| 5692 |
``` cpp
|
| 5693 |
namespace std {
|
| 5694 |
template <class charT, class traits = char_traits<charT>>
|
| 5695 |
class basic_ofstream : public basic_ostream<charT, traits> {
|
| 5696 |
public:
|
| 5697 |
+
using char_type = charT;
|
| 5698 |
+
using int_type = typename traits::int_type;
|
| 5699 |
+
using pos_type = typename traits::pos_type;
|
| 5700 |
+
using off_type = typename traits::off_type;
|
| 5701 |
+
using traits_type = traits;
|
| 5702 |
|
| 5703 |
+
// [ofstream.cons], constructors
|
| 5704 |
basic_ofstream();
|
| 5705 |
explicit basic_ofstream(const char* s,
|
| 5706 |
ios_base::openmode mode = ios_base::out);
|
| 5707 |
+
explicit basic_ofstream(const filesystem::path::value_type* s,
|
| 5708 |
+
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 5709 |
explicit basic_ofstream(const string& s,
|
| 5710 |
ios_base::openmode mode = ios_base::out);
|
| 5711 |
+
explicit basic_ofstream(const filesystem::path& s,
|
| 5712 |
+
ios_base::openmode mode = ios_base::out);
|
| 5713 |
basic_ofstream(const basic_ofstream& rhs) = delete;
|
| 5714 |
basic_ofstream(basic_ofstream&& rhs);
|
| 5715 |
|
| 5716 |
+
// [ofstream.assign], assign and swap
|
| 5717 |
basic_ofstream& operator=(const basic_ofstream& rhs) = delete;
|
| 5718 |
basic_ofstream& operator=(basic_ofstream&& rhs);
|
| 5719 |
void swap(basic_ofstream& rhs);
|
| 5720 |
|
| 5721 |
+
// [ofstream.members], members
|
| 5722 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5723 |
|
| 5724 |
bool is_open() const;
|
| 5725 |
void open(const char* s, ios_base::openmode mode = ios_base::out);
|
| 5726 |
+
void open(const filesystem::path::value_type* s,
|
| 5727 |
+
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 5728 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
| 5729 |
+
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
|
| 5730 |
void close();
|
| 5731 |
private:
|
| 5732 |
basic_filebuf<charT, traits> sb; // exposition only
|
| 5733 |
};
|
| 5734 |
|
|
|
|
| 5749 |
|
| 5750 |
``` cpp
|
| 5751 |
basic_ofstream();
|
| 5752 |
```
|
| 5753 |
|
| 5754 |
+
*Effects:* Constructs an object of class
|
| 5755 |
+
`basic_ofstream<charT, traits>`, initializing the base class with
|
| 5756 |
+
`basic_ostream(&sb)` and initializing `sb` with
|
| 5757 |
+
`basic_filebuf<charT, traits>())` ([[ostream.cons]], [[filebuf.cons]]).
|
| 5758 |
|
| 5759 |
``` cpp
|
| 5760 |
explicit basic_ofstream(const char* s,
|
| 5761 |
ios_base::openmode mode = ios_base::out);
|
| 5762 |
+
explicit basic_ofstream(const filesystem::path::value_type* s,
|
| 5763 |
+
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 5764 |
```
|
| 5765 |
|
| 5766 |
+
*Effects:* Constructs an object of class
|
| 5767 |
+
`basic_ofstream<charT, traits>`, initializing the base class with
|
| 5768 |
+
`basic_ostream(&sb)` and initializing `sb` with
|
| 5769 |
+
`basic_filebuf<charT, traits>())` ([[ostream.cons]], [[filebuf.cons]]),
|
| 5770 |
+
then calls `rdbuf()->open(s, mode | ios_base::out)`. If that function
|
| 5771 |
+
returns a null pointer, calls `setstate(failbit)`.
|
| 5772 |
|
| 5773 |
``` cpp
|
| 5774 |
explicit basic_ofstream(const string& s,
|
| 5775 |
ios_base::openmode mode = ios_base::out);
|
| 5776 |
+
explicit basic_ofstream(const filesystem::path& s,
|
| 5777 |
+
ios_base::openmode mode = ios_base::out);
|
| 5778 |
```
|
| 5779 |
|
| 5780 |
+
*Effects:* The same as `basic_ofstream(s.c_str(), mode)`.
|
| 5781 |
|
| 5782 |
``` cpp
|
| 5783 |
basic_ofstream(basic_ofstream&& rhs);
|
| 5784 |
```
|
| 5785 |
|
|
|
|
| 5810 |
template <class charT, class traits>
|
| 5811 |
void swap(basic_ofstream<charT, traits>& x,
|
| 5812 |
basic_ofstream<charT, traits>& y);
|
| 5813 |
```
|
| 5814 |
|
| 5815 |
+
*Effects:* As if by `x.swap(y)`.
|
| 5816 |
|
| 5817 |
#### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
|
| 5818 |
|
| 5819 |
``` cpp
|
| 5820 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
|
|
| 5828 |
|
| 5829 |
*Returns:* `rdbuf()->is_open()`.
|
| 5830 |
|
| 5831 |
``` cpp
|
| 5832 |
void open(const char* s, ios_base::openmode mode = ios_base::out);
|
| 5833 |
+
void open(const filesystem::path::value_type* s,
|
| 5834 |
+
ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
|
| 5835 |
```
|
| 5836 |
|
| 5837 |
*Effects:* Calls `rdbuf()->open(s, mode | ios_base::out)`. If that
|
| 5838 |
function does not return a null pointer calls `clear()`, otherwise calls
|
| 5839 |
+
`setstate(failbit)` (which may throw `ios_base::failure`)
|
| 5840 |
+
([[iostate.flags]]).
|
| 5841 |
|
| 5842 |
``` cpp
|
| 5843 |
void close();
|
| 5844 |
```
|
| 5845 |
|
| 5846 |
*Effects:* Calls `rdbuf()->close()` and, if that function fails (returns
|
| 5847 |
a null pointer), calls `setstate(failbit)` (which may throw
|
| 5848 |
+
`ios_base::failure`) ([[iostate.flags]]).
|
| 5849 |
|
| 5850 |
``` cpp
|
| 5851 |
void open(const string& s, ios_base::openmode mode = ios_base::out);
|
| 5852 |
+
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
|
| 5853 |
```
|
| 5854 |
|
| 5855 |
+
*Effects:* Calls `open(s.c_str(), mode)`.
|
| 5856 |
|
| 5857 |
+
### Class template `basic_fstream` <a id="fstream">[[fstream]]</a>
|
| 5858 |
|
| 5859 |
``` cpp
|
| 5860 |
namespace std {
|
| 5861 |
template <class charT, class traits = char_traits<charT>>
|
| 5862 |
+
class basic_fstream : public basic_iostream<charT, traits> {
|
|
|
|
|
|
|
| 5863 |
public:
|
| 5864 |
+
using char_type = charT;
|
| 5865 |
+
using int_type = typename traits::int_type;
|
| 5866 |
+
using pos_type = typename traits::pos_type;
|
| 5867 |
+
using off_type = typename traits::off_type;
|
| 5868 |
+
using traits_type = traits;
|
| 5869 |
|
| 5870 |
+
// [fstream.cons], constructors
|
| 5871 |
basic_fstream();
|
| 5872 |
+
explicit basic_fstream(
|
| 5873 |
+
const char* s,
|
| 5874 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5875 |
+
explicit basic_fstream(
|
| 5876 |
+
const std::filesystem::path::value_type* s,
|
| 5877 |
+
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 5878 |
+
explicit basic_fstream(
|
| 5879 |
+
const string& s,
|
| 5880 |
+
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5881 |
+
explicit basic_fstream(
|
| 5882 |
+
const filesystem::path& s,
|
| 5883 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5884 |
basic_fstream(const basic_fstream& rhs) = delete;
|
| 5885 |
basic_fstream(basic_fstream&& rhs);
|
| 5886 |
|
| 5887 |
+
// [fstream.assign], assign and swap
|
| 5888 |
basic_fstream& operator=(const basic_fstream& rhs) = delete;
|
| 5889 |
basic_fstream& operator=(basic_fstream&& rhs);
|
| 5890 |
void swap(basic_fstream& rhs);
|
| 5891 |
|
| 5892 |
+
// [fstream.members], members
|
| 5893 |
basic_filebuf<charT, traits>* rdbuf() const;
|
| 5894 |
bool is_open() const;
|
| 5895 |
+
void open(
|
| 5896 |
+
const char* s,
|
| 5897 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5898 |
+
void open(
|
| 5899 |
+
const std::filesystem::path::value_type* s,
|
| 5900 |
+
ios_base::openmode mode = ios_base::in|ios_base::out); // wide systems only; see [fstream.syn]
|
| 5901 |
+
void open(
|
| 5902 |
+
const string& s,
|
| 5903 |
+
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5904 |
+
void open(
|
| 5905 |
+
const filesystem::path& s,
|
| 5906 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5907 |
void close();
|
| 5908 |
|
| 5909 |
private:
|
| 5910 |
basic_filebuf<charT, traits> sb; // exposition only
|
|
|
|
| 5915 |
basic_fstream<charT, traits>& y);
|
| 5916 |
}
|
| 5917 |
```
|
| 5918 |
|
| 5919 |
The class template `basic_fstream<charT, traits>` supports reading and
|
| 5920 |
+
writing from named files. It uses a `basic_filebuf<charT, traits>`
|
| 5921 |
+
object to control the associated sequences. For the sake of exposition,
|
| 5922 |
+
the maintained data is presented here as:
|
| 5923 |
|
| 5924 |
- `sb`, the `basic_filebuf` object.
|
| 5925 |
|
| 5926 |
#### `basic_fstream` constructors <a id="fstream.cons">[[fstream.cons]]</a>
|
| 5927 |
|
|
|
|
| 5932 |
*Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
|
| 5933 |
initializing the base class with `basic_iostream(&sb)` and initializing
|
| 5934 |
`sb` with `basic_filebuf<charT, traits>()`.
|
| 5935 |
|
| 5936 |
``` cpp
|
| 5937 |
+
explicit basic_fstream(
|
| 5938 |
+
const char* s,
|
| 5939 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5940 |
+
explicit basic_fstream(
|
| 5941 |
+
const filesystem::path::value_type* s,
|
| 5942 |
+
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
|
| 5943 |
```
|
| 5944 |
|
| 5945 |
*Effects:* Constructs an object of class `basic_fstream<charT, traits>`,
|
| 5946 |
initializing the base class with `basic_iostream(&sb)` and initializing
|
| 5947 |
`sb` with `basic_filebuf<charT, traits>()`. Then calls
|
| 5948 |
`rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
|
| 5949 |
`setstate(failbit)`.
|
| 5950 |
|
| 5951 |
``` cpp
|
| 5952 |
+
explicit basic_fstream(
|
| 5953 |
+
const string& s,
|
| 5954 |
+
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5955 |
+
explicit basic_fstream(
|
| 5956 |
+
const filesystem::path& s,
|
| 5957 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 5958 |
```
|
| 5959 |
|
| 5960 |
+
*Effects:* The same as `basic_fstream(s.c_str(), mode)`.
|
| 5961 |
|
| 5962 |
``` cpp
|
| 5963 |
basic_fstream(basic_fstream&& rhs);
|
| 5964 |
```
|
| 5965 |
|
|
|
|
| 5990 |
template <class charT, class traits>
|
| 5991 |
void swap(basic_fstream<charT, traits>& x,
|
| 5992 |
basic_fstream<charT, traits>& y);
|
| 5993 |
```
|
| 5994 |
|
| 5995 |
+
*Effects:* As if by `x.swap(y)`.
|
| 5996 |
|
| 5997 |
#### Member functions <a id="fstream.members">[[fstream.members]]</a>
|
| 5998 |
|
| 5999 |
``` cpp
|
| 6000 |
basic_filebuf<charT, traits>* rdbuf() const;
|
|
|
|
| 6007 |
```
|
| 6008 |
|
| 6009 |
*Returns:* `rdbuf()->is_open()`.
|
| 6010 |
|
| 6011 |
``` cpp
|
| 6012 |
+
void open(
|
| 6013 |
+
const char* s,
|
| 6014 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6015 |
+
void open(
|
| 6016 |
+
const filesystem::path::value_type* s,
|
| 6017 |
+
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
|
| 6018 |
```
|
| 6019 |
|
| 6020 |
*Effects:* Calls `rdbuf()->open(s, mode)`. If that function does not
|
| 6021 |
return a null pointer calls `clear()`, otherwise calls
|
| 6022 |
+
`setstate(failbit)` (which may throw
|
| 6023 |
`ios_base::failure`) ([[iostate.flags]]).
|
| 6024 |
|
| 6025 |
``` cpp
|
| 6026 |
+
void open(
|
| 6027 |
+
const string& s,
|
| 6028 |
+
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6029 |
+
void open(
|
| 6030 |
+
const filesystem::path& s,
|
| 6031 |
ios_base::openmode mode = ios_base::in | ios_base::out);
|
| 6032 |
```
|
| 6033 |
|
| 6034 |
+
*Effects:* Calls `open(s.c_str(), mode)`.
|
| 6035 |
|
| 6036 |
``` cpp
|
| 6037 |
void close();
|
| 6038 |
```
|
| 6039 |
|
| 6040 |
+
*Effects:* Calls `rdbuf()->close()` and, if that function returns a null
|
| 6041 |
+
pointer, calls `setstate(failbit)` (which may throw
|
| 6042 |
+
`ios_base::failure`) ([[iostate.flags]]).
|
| 6043 |
|
| 6044 |
+
## File systems <a id="filesystems">[[filesystems]]</a>
|
| 6045 |
|
| 6046 |
+
### General <a id="fs.general">[[fs.general]]</a>
|
|
|
|
| 6047 |
|
| 6048 |
+
This subclause describes operations on file systems and their
|
| 6049 |
+
components, such as paths, regular files, and directories.
|
|
|
|
| 6050 |
|
| 6051 |
+
### Conformance <a id="fs.conformance">[[fs.conformance]]</a>
|
| 6052 |
|
| 6053 |
+
Conformance is specified in terms of behavior. Ideal behavior is not
|
| 6054 |
+
always implementable, so the conformance subclauses take that into
|
| 6055 |
+
account.
|
|
|
|
| 6056 |
|
| 6057 |
+
#### POSIX conformance <a id="fs.conform.9945">[[fs.conform.9945]]</a>
|
|
|
|
| 6058 |
|
| 6059 |
+
Some behavior is specified by reference to POSIX ([[fs.norm.ref]]). How
|
| 6060 |
+
such behavior is actually implemented is unspecified.
|
| 6061 |
+
|
| 6062 |
+
[*Note 1*: This constitutes an “as if” rule allowing implementations to
|
| 6063 |
+
call native operating system or other APIs. — *end note*]
|
| 6064 |
+
|
| 6065 |
+
Implementations are encouraged to provide such behavior as it is defined
|
| 6066 |
+
by POSIX. Implementations shall document any behavior that differs from
|
| 6067 |
+
the behavior defined by POSIX. Implementations that do not support exact
|
| 6068 |
+
POSIX behavior are encouraged to provide behavior as close to POSIX
|
| 6069 |
+
behavior as is reasonable given the limitations of actual operating
|
| 6070 |
+
systems and file systems. If an implementation cannot provide any
|
| 6071 |
+
reasonable behavior, the implementation shall report an error as
|
| 6072 |
+
specified in [[fs.err.report]].
|
| 6073 |
+
|
| 6074 |
+
[*Note 2*: This allows users to rely on an exception being thrown or an
|
| 6075 |
+
error code being set when an implementation cannot provide any
|
| 6076 |
+
reasonable behavior. — *end note*]
|
| 6077 |
+
|
| 6078 |
+
Implementations are not required to provide behavior that is not
|
| 6079 |
+
supported by a particular file system.
|
| 6080 |
+
|
| 6081 |
+
[*Example 1*: The FAT file system used by some memory cards, camera
|
| 6082 |
+
memory, and floppy disks does not support hard links, symlinks, and many
|
| 6083 |
+
other features of more capable file systems, so implementations are not
|
| 6084 |
+
required to support those features on the FAT file system but instead
|
| 6085 |
+
are required to report an error as described above. — *end example*]
|
| 6086 |
+
|
| 6087 |
+
#### Operating system dependent behavior conformance <a id="fs.conform.os">[[fs.conform.os]]</a>
|
| 6088 |
+
|
| 6089 |
+
Some behavior is specified as being operating system dependent (
|
| 6090 |
+
[[fs.def.osdep]]). The operating system an implementation is dependent
|
| 6091 |
+
upon is *implementation-defined*.
|
| 6092 |
+
|
| 6093 |
+
It is permissible for an implementation to be dependent upon an
|
| 6094 |
+
operating system emulator rather than the actual underlying operating
|
| 6095 |
+
system.
|
| 6096 |
+
|
| 6097 |
+
#### File system race behavior <a id="fs.race.behavior">[[fs.race.behavior]]</a>
|
| 6098 |
+
|
| 6099 |
+
Behavior is undefined if calls to functions provided by this subclause
|
| 6100 |
+
introduce a file system race ([[fs.def.race]]).
|
| 6101 |
+
|
| 6102 |
+
If the possibility of a file system race would make it unreliable for a
|
| 6103 |
+
program to test for a precondition before calling a function described
|
| 6104 |
+
herein, *Requires:* is not specified for the function.
|
| 6105 |
+
|
| 6106 |
+
[*Note 1*: As a design practice, preconditions are not specified when
|
| 6107 |
+
it is unreasonable for a program to detect them prior to calling the
|
| 6108 |
+
function. — *end note*]
|
| 6109 |
+
|
| 6110 |
+
### Normative references <a id="fs.norm.ref">[[fs.norm.ref]]</a>
|
| 6111 |
+
|
| 6112 |
+
This subclause mentions commercially available operating systems for
|
| 6113 |
+
purposes of exposition.[^41]
|
| 6114 |
+
|
| 6115 |
+
### Terms and definitions <a id="fs.definitions">[[fs.definitions]]</a>
|
| 6116 |
+
|
| 6117 |
+
A path that unambiguously identifies the location of a file without
|
| 6118 |
+
reference to an additional starting location. The elements of a path
|
| 6119 |
+
that determine if it is absolute are operating system dependent.
|
| 6120 |
+
|
| 6121 |
+
A file within a file system that acts as a container of directory
|
| 6122 |
+
entries that contain information about other files, possibly including
|
| 6123 |
+
other directory files.
|
| 6124 |
+
|
| 6125 |
+
An object within a file system that holds user or system data. Files can
|
| 6126 |
+
be written to, or read from, or both. A file has certain attributes,
|
| 6127 |
+
including type. File types include regular files and directories. Other
|
| 6128 |
+
types of files, such as symbolic links ([[fs.def.symlink]]), may be
|
| 6129 |
+
supported by the implementation.
|
| 6130 |
+
|
| 6131 |
+
A collection of files and their attributes.
|
| 6132 |
+
|
| 6133 |
+
The condition that occurs when multiple threads, processes, or computers
|
| 6134 |
+
interleave access and modification of the same object within a file
|
| 6135 |
+
system.
|
| 6136 |
+
|
| 6137 |
+
The name of a file. Filenames *dot* and *dot-dot*, consisting solely of
|
| 6138 |
+
one and two period characters respectively, have special meaning. The
|
| 6139 |
+
following characteristics of filenames are operating system dependent:
|
| 6140 |
+
|
| 6141 |
+
- The permitted characters. \[*Example 1*: Some operating systems
|
| 6142 |
+
prohibit the ASCII control characters (0x00 – 0x1F) in
|
| 6143 |
+
filenames. — *end example*]
|
| 6144 |
+
- The maximum permitted length.
|
| 6145 |
+
- Filenames that are not permitted.
|
| 6146 |
+
- Filenames that have special meaning.
|
| 6147 |
+
- Case awareness and sensitivity during path resolution.
|
| 6148 |
+
- Special rules that may apply to file types other than regular files,
|
| 6149 |
+
such as directories.
|
| 6150 |
+
|
| 6151 |
+
A link ([[fs.def.link]]) to an existing file. Some file systems support
|
| 6152 |
+
multiple hard links to a file. If the last hard link to a file is
|
| 6153 |
+
removed, the file itself is removed.
|
| 6154 |
+
|
| 6155 |
+
[*Note 1*: A hard link can be thought of as a shared-ownership smart
|
| 6156 |
+
pointer to a file. — *end note*]
|
| 6157 |
+
|
| 6158 |
+
An object that associates a filename with a file. Several links can
|
| 6159 |
+
associate names with the same file.
|
| 6160 |
+
|
| 6161 |
+
For narrow character strings, the operating system dependent current
|
| 6162 |
+
encoding for pathnames ([[fs.def.pathname]]). For wide character
|
| 6163 |
+
strings, the implementation-defined execution wide-character set
|
| 6164 |
+
encoding ([[lex.charset]]).
|
| 6165 |
+
|
| 6166 |
+
The operating system dependent pathname format accepted by the host
|
| 6167 |
+
operating system.
|
| 6168 |
+
|
| 6169 |
+
A path in normal form is said to be *normalized*. The process of
|
| 6170 |
+
obtaining a normalized path from a path that is not in normal form is
|
| 6171 |
+
called *normalization*.
|
| 6172 |
+
|
| 6173 |
+
Normalization of a generic format pathname means:
|
| 6174 |
+
|
| 6175 |
+
1. If the path is empty, stop.
|
| 6176 |
+
2. Replace each slash character in the *root-name* with a
|
| 6177 |
+
*preferred-separator*.
|
| 6178 |
+
3. Replace each *directory-separator* with a *preferred-separator*.
|
| 6179 |
+
\[*Note 2*: The generic pathname grammar ([[fs.path.generic]])
|
| 6180 |
+
defines *directory-separator* as one or more slashes and
|
| 6181 |
+
*preferred-separator*s. — *end note*]
|
| 6182 |
+
4. Remove each *dot* filename and any immediately following
|
| 6183 |
+
*directory-separator*.
|
| 6184 |
+
5. As long as any appear, remove a non-*dot-dot* filename immediately
|
| 6185 |
+
followed by a *directory-separator* and a *dot-dot* filename, along
|
| 6186 |
+
with any immediately following *directory-separator*.
|
| 6187 |
+
6. If there is a *root-directory*, remove all *dot-dot* filenames and
|
| 6188 |
+
any *directory-separator*s immediately following them.
|
| 6189 |
+
\[*Note 3*: These *dot-dot* filenames attempt to refer to
|
| 6190 |
+
nonexistent parent directories. — *end note*]
|
| 6191 |
+
7. If the last filename is *dot-dot*, remove any trailing
|
| 6192 |
+
*directory-separator*.
|
| 6193 |
+
8. If the path is empty, add a *dot*.
|
| 6194 |
+
|
| 6195 |
+
Behavior that is dependent upon the behavior and characteristics of an
|
| 6196 |
+
operating system. See [[fs.conform.os]].
|
| 6197 |
+
|
| 6198 |
+
the directory that both contains a directory entry for the given
|
| 6199 |
+
directory and is represented by the filename *dot-dot* in the given
|
| 6200 |
+
directory.
|
| 6201 |
+
|
| 6202 |
+
a directory containing a directory entry for the file under discussion.
|
| 6203 |
+
|
| 6204 |
+
A sequence of elements that identify the location of a file within a
|
| 6205 |
+
filesystem. The elements are the *root-name*ₒₚₜ , *root-directory*ₒₚₜ ,
|
| 6206 |
+
and an optional sequence of filenames. The maximum number of elements in
|
| 6207 |
+
the sequence is operating system dependent.
|
| 6208 |
+
|
| 6209 |
+
A character string that represents the name of a path. Pathnames are
|
| 6210 |
+
formatted according to the generic pathname format grammar (
|
| 6211 |
+
[[fs.path.generic]]) or an operating system dependent native pathname
|
| 6212 |
+
format.
|
| 6213 |
+
|
| 6214 |
+
Pathname resolution is the operating system dependent mechanism for
|
| 6215 |
+
resolving a pathname to a particular file in a file hierarchy. There may
|
| 6216 |
+
be multiple pathnames that resolve to the same file.
|
| 6217 |
+
|
| 6218 |
+
[*Example 2*: POSIX specifies the mechanism in section 4.11, Pathname
|
| 6219 |
+
resolution. — *end example*]
|
| 6220 |
+
|
| 6221 |
+
A path that is not absolute, and as such, only unambiguously identifies
|
| 6222 |
+
the location of a file when resolved ([[fs.def.pathres]]) relative to
|
| 6223 |
+
an implied starting location. The elements of a path that determine if
|
| 6224 |
+
it is relative are operating system dependent.
|
| 6225 |
+
|
| 6226 |
+
[*Note 4*: Pathnames “.” and “..” are relative paths. — *end note*]
|
| 6227 |
+
|
| 6228 |
+
A type of file with the property that when the file is encountered
|
| 6229 |
+
during pathname resolution, a string stored by the file is used to
|
| 6230 |
+
modify the pathname resolution.
|
| 6231 |
+
|
| 6232 |
+
[*Note 5*: Symbolic links are often called symlinks. A symbolic link
|
| 6233 |
+
can be thought of as a raw pointer to a file. If the file pointed to
|
| 6234 |
+
does not exist, the symbolic link is said to be a “dangling” symbolic
|
| 6235 |
+
link. — *end note*]
|
| 6236 |
+
|
| 6237 |
+
### Requirements <a id="fs.req">[[fs.req]]</a>
|
| 6238 |
+
|
| 6239 |
+
Throughout this subclause, `char`, `wchar_t`, `char16_t`, and `char32_t`
|
| 6240 |
+
are collectively called *encoded character types*.
|
| 6241 |
+
|
| 6242 |
+
Functions with template parameters named `EcharT` shall not participate
|
| 6243 |
+
in overload resolution unless `EcharT` is one of the encoded character
|
| 6244 |
+
types.
|
| 6245 |
+
|
| 6246 |
+
Template parameters named `InputIterator` shall meet the input iterator
|
| 6247 |
+
requirements ([[input.iterators]]) and shall have a value type that is
|
| 6248 |
+
one of the encoded character types.
|
| 6249 |
+
|
| 6250 |
+
[*Note 1*: Use of an encoded character type implies an associated
|
| 6251 |
+
character set and encoding. Since `signed char` and `unsigned char` have
|
| 6252 |
+
no implied character set and encoding, they are not included as
|
| 6253 |
+
permitted types. — *end note*]
|
| 6254 |
+
|
| 6255 |
+
Template parameters named `Allocator` shall meet the Allocator
|
| 6256 |
+
requirements ([[allocator.requirements]]).
|
| 6257 |
+
|
| 6258 |
+
#### Namespaces and headers <a id="fs.req.namespace">[[fs.req.namespace]]</a>
|
| 6259 |
+
|
| 6260 |
+
Unless otherwise specified, references to entities described in this
|
| 6261 |
+
subclause are assumed to be qualified with `::std::filesystem::`.
|
| 6262 |
+
|
| 6263 |
+
### Header `<filesystem>` synopsis <a id="fs.filesystem.syn">[[fs.filesystem.syn]]</a>
|
| 6264 |
+
|
| 6265 |
+
``` cpp
|
| 6266 |
+
namespace std::filesystem {
|
| 6267 |
+
// [fs.class.path], paths
|
| 6268 |
+
class path;
|
| 6269 |
+
|
| 6270 |
+
// [fs.path.nonmember], path non-member functions
|
| 6271 |
+
void swap(path& lhs, path& rhs) noexcept;
|
| 6272 |
+
size_t hash_value(const path& p) noexcept;
|
| 6273 |
+
|
| 6274 |
+
bool operator==(const path& lhs, const path& rhs) noexcept;
|
| 6275 |
+
bool operator!=(const path& lhs, const path& rhs) noexcept;
|
| 6276 |
+
bool operator< (const path& lhs, const path& rhs) noexcept;
|
| 6277 |
+
bool operator<=(const path& lhs, const path& rhs) noexcept;
|
| 6278 |
+
bool operator> (const path& lhs, const path& rhs) noexcept;
|
| 6279 |
+
bool operator>=(const path& lhs, const path& rhs) noexcept;
|
| 6280 |
+
|
| 6281 |
+
path operator/ (const path& lhs, const path& rhs);
|
| 6282 |
+
|
| 6283 |
+
// [fs.path.io], path inserter and extractor
|
| 6284 |
+
template <class charT, class traits>
|
| 6285 |
+
basic_ostream<charT, traits>&
|
| 6286 |
+
operator<<(basic_ostream<charT, traits>& os, const path& p);
|
| 6287 |
+
template <class charT, class traits>
|
| 6288 |
+
basic_istream<charT, traits>&
|
| 6289 |
+
operator>>(basic_istream<charT, traits>& is, path& p);
|
| 6290 |
+
|
| 6291 |
+
// [fs.path.factory], path factory functions
|
| 6292 |
+
template <class Source>
|
| 6293 |
+
path u8path(const Source& source);
|
| 6294 |
+
template <class InputIterator>
|
| 6295 |
+
path u8path(InputIterator first, InputIterator last);
|
| 6296 |
+
|
| 6297 |
+
// [fs.class.filesystem_error], filesystem errors
|
| 6298 |
+
class filesystem_error;
|
| 6299 |
+
|
| 6300 |
+
// [fs.class.directory_entry], directory entries
|
| 6301 |
+
class directory_entry;
|
| 6302 |
+
|
| 6303 |
+
// [fs.class.directory_iterator], directory iterators
|
| 6304 |
+
class directory_iterator;
|
| 6305 |
+
|
| 6306 |
+
// [fs.dir.itr.nonmembers], range access for directory iterators
|
| 6307 |
+
directory_iterator begin(directory_iterator iter) noexcept;
|
| 6308 |
+
directory_iterator end(const directory_iterator&) noexcept;
|
| 6309 |
+
|
| 6310 |
+
// [fs.class.rec.dir.itr], recursive directory iterators
|
| 6311 |
+
class recursive_directory_iterator;
|
| 6312 |
+
|
| 6313 |
+
// [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
|
| 6314 |
+
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 6315 |
+
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
|
| 6316 |
+
|
| 6317 |
+
// [fs.class.file_status], file status
|
| 6318 |
+
class file_status;
|
| 6319 |
+
|
| 6320 |
+
struct space_info {
|
| 6321 |
+
uintmax_t capacity;
|
| 6322 |
+
uintmax_t free;
|
| 6323 |
+
uintmax_t available;
|
| 6324 |
+
};
|
| 6325 |
+
|
| 6326 |
+
// [fs.enum], enumerations
|
| 6327 |
+
enum class file_type;
|
| 6328 |
+
enum class perms;
|
| 6329 |
+
enum class perm_options;
|
| 6330 |
+
enum class copy_options;
|
| 6331 |
+
enum class directory_options;
|
| 6332 |
+
|
| 6333 |
+
using file_time_type = chrono::time_point<trivial-clock>;
|
| 6334 |
+
|
| 6335 |
+
// [fs.op.funcs], filesystem operations
|
| 6336 |
+
path absolute(const path& p, const path& base = current_path());
|
| 6337 |
+
|
| 6338 |
+
path canonical(const path& p, const path& base = current_path());
|
| 6339 |
+
path canonical(const path& p, error_code& ec);
|
| 6340 |
+
path canonical(const path& p, const path& base, error_code& ec);
|
| 6341 |
+
|
| 6342 |
+
void copy(const path& from, const path& to);
|
| 6343 |
+
void copy(const path& from, const path& to, error_code& ec) noexcept;
|
| 6344 |
+
void copy(const path& from, const path& to, copy_options options);
|
| 6345 |
+
void copy(const path& from, const path& to, copy_options options,
|
| 6346 |
+
error_code& ec) noexcept;
|
| 6347 |
+
|
| 6348 |
+
bool copy_file(const path& from, const path& to);
|
| 6349 |
+
bool copy_file(const path& from, const path& to, error_code& ec) noexcept;
|
| 6350 |
+
bool copy_file(const path& from, const path& to, copy_options option);
|
| 6351 |
+
bool copy_file(const path& from, const path& to, copy_options option,
|
| 6352 |
+
error_code& ec) noexcept;
|
| 6353 |
+
|
| 6354 |
+
void copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 6355 |
+
void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 6356 |
+
error_code& ec) noexcept;
|
| 6357 |
+
|
| 6358 |
+
bool create_directories(const path& p);
|
| 6359 |
+
bool create_directories(const path& p, error_code& ec) noexcept;
|
| 6360 |
+
|
| 6361 |
+
bool create_directory(const path& p);
|
| 6362 |
+
bool create_directory(const path& p, error_code& ec) noexcept;
|
| 6363 |
+
|
| 6364 |
+
bool create_directory(const path& p, const path& attributes);
|
| 6365 |
+
bool create_directory(const path& p, const path& attributes,
|
| 6366 |
+
error_code& ec) noexcept;
|
| 6367 |
+
|
| 6368 |
+
void create_directory_symlink(const path& to, const path& new_symlink);
|
| 6369 |
+
void create_directory_symlink(const path& to, const path& new_symlink,
|
| 6370 |
+
error_code& ec) noexcept;
|
| 6371 |
+
|
| 6372 |
+
void create_hard_link(const path& to, const path& new_hard_link);
|
| 6373 |
+
void create_hard_link(const path& to, const path& new_hard_link,
|
| 6374 |
+
error_code& ec) noexcept;
|
| 6375 |
+
|
| 6376 |
+
void create_symlink(const path& to, const path& new_symlink);
|
| 6377 |
+
void create_symlink(const path& to, const path& new_symlink,
|
| 6378 |
+
error_code& ec) noexcept;
|
| 6379 |
+
|
| 6380 |
+
path current_path();
|
| 6381 |
+
path current_path(error_code& ec);
|
| 6382 |
+
void current_path(const path& p);
|
| 6383 |
+
void current_path(const path& p, error_code& ec) noexcept;
|
| 6384 |
+
|
| 6385 |
+
bool exists(file_status s) noexcept;
|
| 6386 |
+
bool exists(const path& p);
|
| 6387 |
+
bool exists(const path& p, error_code& ec) noexcept;
|
| 6388 |
+
|
| 6389 |
+
bool equivalent(const path& p1, const path& p2);
|
| 6390 |
+
bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 6391 |
+
|
| 6392 |
+
uintmax_t file_size(const path& p);
|
| 6393 |
+
uintmax_t file_size(const path& p, error_code& ec) noexcept;
|
| 6394 |
+
|
| 6395 |
+
uintmax_t hard_link_count(const path& p);
|
| 6396 |
+
uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
| 6397 |
+
|
| 6398 |
+
bool is_block_file(file_status s) noexcept;
|
| 6399 |
+
bool is_block_file(const path& p);
|
| 6400 |
+
bool is_block_file(const path& p, error_code& ec) noexcept;
|
| 6401 |
+
|
| 6402 |
+
bool is_character_file(file_status s) noexcept;
|
| 6403 |
+
bool is_character_file(const path& p);
|
| 6404 |
+
bool is_character_file(const path& p, error_code& ec) noexcept;
|
| 6405 |
+
|
| 6406 |
+
bool is_directory(file_status s) noexcept;
|
| 6407 |
+
bool is_directory(const path& p);
|
| 6408 |
+
bool is_directory(const path& p, error_code& ec) noexcept;
|
| 6409 |
+
|
| 6410 |
+
bool is_empty(const path& p);
|
| 6411 |
+
bool is_empty(const path& p, error_code& ec) noexcept;
|
| 6412 |
+
|
| 6413 |
+
bool is_fifo(file_status s) noexcept;
|
| 6414 |
+
bool is_fifo(const path& p);
|
| 6415 |
+
bool is_fifo(const path& p, error_code& ec) noexcept;
|
| 6416 |
+
|
| 6417 |
+
bool is_other(file_status s) noexcept;
|
| 6418 |
+
bool is_other(const path& p);
|
| 6419 |
+
bool is_other(const path& p, error_code& ec) noexcept;
|
| 6420 |
+
|
| 6421 |
+
bool is_regular_file(file_status s) noexcept;
|
| 6422 |
+
bool is_regular_file(const path& p);
|
| 6423 |
+
bool is_regular_file(const path& p, error_code& ec) noexcept;
|
| 6424 |
+
|
| 6425 |
+
bool is_socket(file_status s) noexcept;
|
| 6426 |
+
bool is_socket(const path& p);
|
| 6427 |
+
bool is_socket(const path& p, error_code& ec) noexcept;
|
| 6428 |
+
|
| 6429 |
+
bool is_symlink(file_status s) noexcept;
|
| 6430 |
+
bool is_symlink(const path& p);
|
| 6431 |
+
bool is_symlink(const path& p, error_code& ec) noexcept;
|
| 6432 |
+
|
| 6433 |
+
file_time_type last_write_time(const path& p);
|
| 6434 |
+
file_time_type last_write_time(const path& p, error_code& ec) noexcept;
|
| 6435 |
+
void last_write_time(const path& p, file_time_type new_time);
|
| 6436 |
+
void last_write_time(const path& p, file_time_type new_time,
|
| 6437 |
+
error_code& ec) noexcept;
|
| 6438 |
+
|
| 6439 |
+
void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
|
| 6440 |
+
void permissions(const path& p, perms prms, error_code& ec) noexcept;
|
| 6441 |
+
void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
|
| 6442 |
+
|
| 6443 |
+
path proximate(const path& p, error_code& ec);
|
| 6444 |
+
path proximate(const path& p, const path& base = current_path());
|
| 6445 |
+
path proximate(const path& p, const path& base, error_code& ec);
|
| 6446 |
+
|
| 6447 |
+
path read_symlink(const path& p);
|
| 6448 |
+
path read_symlink(const path& p, error_code& ec);
|
| 6449 |
+
|
| 6450 |
+
path relative(const path& p, error_code& ec);
|
| 6451 |
+
path relative(const path& p, const path& base = current_path());
|
| 6452 |
+
path relative(const path& p, const path& base, error_code& ec);
|
| 6453 |
+
|
| 6454 |
+
bool remove(const path& p);
|
| 6455 |
+
bool remove(const path& p, error_code& ec) noexcept;
|
| 6456 |
+
|
| 6457 |
+
uintmax_t remove_all(const path& p);
|
| 6458 |
+
uintmax_t remove_all(const path& p, error_code& ec) noexcept;
|
| 6459 |
+
|
| 6460 |
+
void rename(const path& from, const path& to);
|
| 6461 |
+
void rename(const path& from, const path& to, error_code& ec) noexcept;
|
| 6462 |
+
|
| 6463 |
+
void resize_file(const path& p, uintmax_t size);
|
| 6464 |
+
void resize_file(const path& p, uintmax_t size, error_code& ec) noexcept;
|
| 6465 |
+
|
| 6466 |
+
space_info space(const path& p);
|
| 6467 |
+
space_info space(const path& p, error_code& ec) noexcept;
|
| 6468 |
+
|
| 6469 |
+
file_status status(const path& p);
|
| 6470 |
+
file_status status(const path& p, error_code& ec) noexcept;
|
| 6471 |
+
|
| 6472 |
+
bool status_known(file_status s) noexcept;
|
| 6473 |
+
|
| 6474 |
+
file_status symlink_status(const path& p);
|
| 6475 |
+
file_status symlink_status(const path& p, error_code& ec) noexcept;
|
| 6476 |
+
|
| 6477 |
+
path temp_directory_path();
|
| 6478 |
+
path temp_directory_path(error_code& ec);
|
| 6479 |
+
|
| 6480 |
+
path weakly_canonical(const path& p);
|
| 6481 |
+
path weakly_canonical(const path& p, error_code& ec);
|
| 6482 |
+
}
|
| 6483 |
+
```
|
| 6484 |
+
|
| 6485 |
+
`trivial-clock` is an *implementation-defined* type that satisfies the
|
| 6486 |
+
`TrivialClock` requirements ([[time.clock.req]]) and that is capable of
|
| 6487 |
+
representing and measuring file time values. Implementations should
|
| 6488 |
+
ensure that the resolution and range of `file_time_type` reflect the
|
| 6489 |
+
operating system dependent resolution and range of file time values.
|
| 6490 |
+
|
| 6491 |
+
### Error reporting <a id="fs.err.report">[[fs.err.report]]</a>
|
| 6492 |
+
|
| 6493 |
+
Filesystem library functions often provide two overloads, one that
|
| 6494 |
+
throws an exception to report file system errors, and another that sets
|
| 6495 |
+
an `error_code`.
|
| 6496 |
+
|
| 6497 |
+
[*Note 1*:
|
| 6498 |
+
|
| 6499 |
+
This supports two common use cases:
|
| 6500 |
+
|
| 6501 |
+
- Uses where file system errors are truly exceptional and indicate a
|
| 6502 |
+
serious failure. Throwing an exception is an appropriate response.
|
| 6503 |
+
- Uses where file system errors are routine and do not necessarily
|
| 6504 |
+
represent failure. Returning an error code is the most appropriate
|
| 6505 |
+
response. This allows application specific error handling, including
|
| 6506 |
+
simply ignoring the error.
|
| 6507 |
+
|
| 6508 |
+
— *end note*]
|
| 6509 |
+
|
| 6510 |
+
Functions not having an argument of type `error_code&` handle errors as
|
| 6511 |
+
follows, unless otherwise specified:
|
| 6512 |
+
|
| 6513 |
+
- When a call by the implementation to an operating system or other
|
| 6514 |
+
underlying API results in an error that prevents the function from
|
| 6515 |
+
meeting its specifications, an exception of type `filesystem_error`
|
| 6516 |
+
shall be thrown. For functions with a single path argument, that
|
| 6517 |
+
argument shall be passed to the `filesystem_error` constructor with a
|
| 6518 |
+
single path argument. For functions with two path arguments, the first
|
| 6519 |
+
of these arguments shall be passed to the `filesystem_error`
|
| 6520 |
+
constructor as the `path1` argument, and the second shall be passed as
|
| 6521 |
+
the `path2` argument. The `filesystem_error` constructor’s
|
| 6522 |
+
`error_code` argument is set as appropriate for the specific operating
|
| 6523 |
+
system dependent error.
|
| 6524 |
+
- Failure to allocate storage is reported by throwing an exception as
|
| 6525 |
+
described in [[res.on.exception.handling]].
|
| 6526 |
+
- Destructors throw nothing.
|
| 6527 |
+
|
| 6528 |
+
Functions having an argument of type `error_code&` handle errors as
|
| 6529 |
+
follows, unless otherwise specified:
|
| 6530 |
+
|
| 6531 |
+
- If a call by the implementation to an operating system or other
|
| 6532 |
+
underlying API results in an error that prevents the function from
|
| 6533 |
+
meeting its specifications, the `error_code&` argument is set as
|
| 6534 |
+
appropriate for the specific operating system dependent error.
|
| 6535 |
+
Otherwise, `clear()` is called on the `error_code&` argument.
|
| 6536 |
+
|
| 6537 |
+
### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
|
| 6538 |
+
|
| 6539 |
+
An object of class `path` represents a path ([[fs.def.path]]) and
|
| 6540 |
+
contains a pathname ([[fs.def.pathname]]). Such an object is concerned
|
| 6541 |
+
only with the lexical and syntactic aspects of a path. The path does not
|
| 6542 |
+
necessarily exist in external storage, and the pathname is not
|
| 6543 |
+
necessarily valid for the current operating system or for a particular
|
| 6544 |
+
file system.
|
| 6545 |
+
|
| 6546 |
+
[*Note 1*: Class `path` is used to support the differences between the
|
| 6547 |
+
string types used by different operating systems to represent pathnames,
|
| 6548 |
+
and to perform conversions between encodings when
|
| 6549 |
+
necessary. — *end note*]
|
| 6550 |
+
|
| 6551 |
+
``` cpp
|
| 6552 |
+
namespace std::filesystem {
|
| 6553 |
+
class path {
|
| 6554 |
+
public:
|
| 6555 |
+
using value_type = see below;
|
| 6556 |
+
using string_type = basic_string<value_type>;
|
| 6557 |
+
static constexpr value_type preferred_separator = see below;
|
| 6558 |
+
|
| 6559 |
+
// [fs.enum.path.format], enumeration format
|
| 6560 |
+
enum format;
|
| 6561 |
+
|
| 6562 |
+
// [fs.path.construct], constructors and destructor
|
| 6563 |
+
path() noexcept;
|
| 6564 |
+
path(const path& p);
|
| 6565 |
+
path(path&& p) noexcept;
|
| 6566 |
+
path(string_type&& source, format fmt = auto_format);
|
| 6567 |
+
template <class Source>
|
| 6568 |
+
path(const Source& source, format fmt = auto_format);
|
| 6569 |
+
template <class InputIterator>
|
| 6570 |
+
path(InputIterator first, InputIterator last, format fmt = auto_format);
|
| 6571 |
+
template <class Source>
|
| 6572 |
+
path(const Source& source, const locale& loc, format fmt = auto_format);
|
| 6573 |
+
template <class InputIterator>
|
| 6574 |
+
path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
|
| 6575 |
+
~path();
|
| 6576 |
+
|
| 6577 |
+
// [fs.path.assign], assignments
|
| 6578 |
+
path& operator=(const path& p);
|
| 6579 |
+
path& operator=(path&& p) noexcept;
|
| 6580 |
+
path& operator=(string_type&& source);
|
| 6581 |
+
path& assign(string_type&& source);
|
| 6582 |
+
template <class Source>
|
| 6583 |
+
path& operator=(const Source& source);
|
| 6584 |
+
template <class Source>
|
| 6585 |
+
path& assign(const Source& source)
|
| 6586 |
+
template <class InputIterator>
|
| 6587 |
+
path& assign(InputIterator first, InputIterator last);
|
| 6588 |
+
|
| 6589 |
+
// [fs.path.append], appends
|
| 6590 |
+
path& operator/=(const path& p);
|
| 6591 |
+
template <class Source>
|
| 6592 |
+
path& operator/=(const Source& source);
|
| 6593 |
+
template <class Source>
|
| 6594 |
+
path& append(const Source& source);
|
| 6595 |
+
template <class InputIterator>
|
| 6596 |
+
path& append(InputIterator first, InputIterator last);
|
| 6597 |
+
|
| 6598 |
+
// [fs.path.concat], concatenation
|
| 6599 |
+
path& operator+=(const path& x);
|
| 6600 |
+
path& operator+=(const string_type& x);
|
| 6601 |
+
path& operator+=(basic_string_view<value_type> x);
|
| 6602 |
+
path& operator+=(const value_type* x);
|
| 6603 |
+
path& operator+=(value_type x);
|
| 6604 |
+
template <class Source>
|
| 6605 |
+
path& operator+=(const Source& x);
|
| 6606 |
+
template <class EcharT>
|
| 6607 |
+
path& operator+=(EcharT x);
|
| 6608 |
+
template <class Source>
|
| 6609 |
+
path& concat(const Source& x);
|
| 6610 |
+
template <class InputIterator>
|
| 6611 |
+
path& concat(InputIterator first, InputIterator last);
|
| 6612 |
+
|
| 6613 |
+
// [fs.path.modifiers], modifiers
|
| 6614 |
+
void clear() noexcept;
|
| 6615 |
+
path& make_preferred();
|
| 6616 |
+
path& remove_filename();
|
| 6617 |
+
path& replace_filename(const path& replacement);
|
| 6618 |
+
path& replace_extension(const path& replacement = path());
|
| 6619 |
+
void swap(path& rhs) noexcept;
|
| 6620 |
+
|
| 6621 |
+
// [fs.path.native.obs], native format observers
|
| 6622 |
+
const string_type& native() const noexcept;
|
| 6623 |
+
const value_type* c_str() const noexcept;
|
| 6624 |
+
operator string_type() const;
|
| 6625 |
+
|
| 6626 |
+
template <class EcharT, class traits = char_traits<EcharT>,
|
| 6627 |
+
class Allocator = allocator<EcharT>>
|
| 6628 |
+
basic_string<EcharT, traits, Allocator>
|
| 6629 |
+
string(const Allocator& a = Allocator()) const;
|
| 6630 |
+
std::string string() const;
|
| 6631 |
+
std::wstring wstring() const;
|
| 6632 |
+
std::string u8string() const;
|
| 6633 |
+
std::u16string u16string() const;
|
| 6634 |
+
std::u32string u32string() const;
|
| 6635 |
+
|
| 6636 |
+
// [fs.path.generic.obs], generic format observers
|
| 6637 |
+
template <class EcharT, class traits = char_traits<EcharT>,
|
| 6638 |
+
class Allocator = allocator<EcharT>>
|
| 6639 |
+
basic_string<EcharT, traits, Allocator>
|
| 6640 |
+
generic_string(const Allocator& a = Allocator()) const;
|
| 6641 |
+
std::string generic_string() const;
|
| 6642 |
+
std::wstring generic_wstring() const;
|
| 6643 |
+
std::string generic_u8string() const;
|
| 6644 |
+
std::u16string generic_u16string() const;
|
| 6645 |
+
std::u32string generic_u32string() const;
|
| 6646 |
+
|
| 6647 |
+
// [fs.path.compare], compare
|
| 6648 |
+
int compare(const path& p) const noexcept;
|
| 6649 |
+
int compare(const string_type& s) const;
|
| 6650 |
+
int compare(basic_string_view<value_type> s) const;
|
| 6651 |
+
int compare(const value_type* s) const;
|
| 6652 |
+
|
| 6653 |
+
// [fs.path.decompose], decomposition
|
| 6654 |
+
path root_name() const;
|
| 6655 |
+
path root_directory() const;
|
| 6656 |
+
path root_path() const;
|
| 6657 |
+
path relative_path() const;
|
| 6658 |
+
path parent_path() const;
|
| 6659 |
+
path filename() const;
|
| 6660 |
+
path stem() const;
|
| 6661 |
+
path extension() const;
|
| 6662 |
+
|
| 6663 |
+
// [fs.path.query], query
|
| 6664 |
+
bool empty() const noexcept;
|
| 6665 |
+
bool has_root_name() const;
|
| 6666 |
+
bool has_root_directory() const;
|
| 6667 |
+
bool has_root_path() const;
|
| 6668 |
+
bool has_relative_path() const;
|
| 6669 |
+
bool has_parent_path() const;
|
| 6670 |
+
bool has_filename() const;
|
| 6671 |
+
bool has_stem() const;
|
| 6672 |
+
bool has_extension() const;
|
| 6673 |
+
bool is_absolute() const;
|
| 6674 |
+
bool is_relative() const;
|
| 6675 |
+
|
| 6676 |
+
// [fs.path.gen], generation
|
| 6677 |
+
path lexically_normal() const;
|
| 6678 |
+
path lexically_relative(const path& base) const;
|
| 6679 |
+
path lexically_proximate(const path& base) const;
|
| 6680 |
+
|
| 6681 |
+
// [fs.path.itr], iterators
|
| 6682 |
+
class iterator;
|
| 6683 |
+
using const_iterator = iterator;
|
| 6684 |
+
|
| 6685 |
+
iterator begin() const;
|
| 6686 |
+
iterator end() const;
|
| 6687 |
+
};
|
| 6688 |
+
}
|
| 6689 |
+
```
|
| 6690 |
+
|
| 6691 |
+
`value_type` is a `typedef` for the operating system dependent encoded
|
| 6692 |
+
character type used to represent pathnames.
|
| 6693 |
+
|
| 6694 |
+
The value of the `preferred_separator` member is the operating system
|
| 6695 |
+
dependent *preferred-separator* character ([[fs.path.generic]]).
|
| 6696 |
+
|
| 6697 |
+
[*Example 1*: For POSIX-based operating systems, `value_type` is `char`
|
| 6698 |
+
and `preferred_separator` is the slash character (`'/'`). For
|
| 6699 |
+
Windows-based operating systems, `value_type` is `wchar_t` and
|
| 6700 |
+
`preferred_separator` is the backslash character
|
| 6701 |
+
(`L'\\'`). — *end example*]
|
| 6702 |
+
|
| 6703 |
+
#### Generic pathname format <a id="fs.path.generic">[[fs.path.generic]]</a>
|
| 6704 |
+
|
| 6705 |
+
``` bnf
|
| 6706 |
+
pathname:
|
| 6707 |
+
root-nameₒₚₜ root-directoryₒₚₜ relative-path
|
| 6708 |
+
```
|
| 6709 |
+
|
| 6710 |
+
``` bnf
|
| 6711 |
+
root-name:
|
| 6712 |
+
operating system dependent sequences of characters
|
| 6713 |
+
implementation-defined sequences of characters
|
| 6714 |
+
```
|
| 6715 |
+
|
| 6716 |
+
``` bnf
|
| 6717 |
+
root-directory:
|
| 6718 |
+
directory-separator
|
| 6719 |
+
```
|
| 6720 |
+
|
| 6721 |
+
``` bnf
|
| 6722 |
+
relative-path:
|
| 6723 |
+
filename
|
| 6724 |
+
filename directory-separator relative-path
|
| 6725 |
+
an empty path
|
| 6726 |
+
```
|
| 6727 |
+
|
| 6728 |
+
``` bnf
|
| 6729 |
+
filename:
|
| 6730 |
+
non-empty sequence of characters other than *directory-separator* characters
|
| 6731 |
+
```
|
| 6732 |
+
|
| 6733 |
+
``` bnf
|
| 6734 |
+
directory-separator:
|
| 6735 |
+
preferred-separator directory-separatorₒₚₜ
|
| 6736 |
+
fallback-separator directory-separatorₒₚₜ
|
| 6737 |
+
```
|
| 6738 |
+
|
| 6739 |
+
``` bnf
|
| 6740 |
+
preferred-separator:
|
| 6741 |
+
operating system dependent directory separator character
|
| 6742 |
+
```
|
| 6743 |
+
|
| 6744 |
+
``` bnf
|
| 6745 |
+
fallback-separator:
|
| 6746 |
+
/, if *preferred-separator* is not /
|
| 6747 |
+
```
|
| 6748 |
+
|
| 6749 |
+
[*Note 1*: Operating systems often place restrictions on the characters
|
| 6750 |
+
that may be used in a *filename*. For wide portability, users may wish
|
| 6751 |
+
to limit *filename* characters to the POSIX Portable Filename Character
|
| 6752 |
+
Set:
|
| 6753 |
+
`A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
|
| 6754 |
+
`a b c d e f g h i j k l m n o p q r s t u v w x y z`
|
| 6755 |
+
`0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
|
| 6756 |
+
|
| 6757 |
+
Except in a *root-name*, multiple successive *directory-separator*
|
| 6758 |
+
characters are considered to be the same as one *directory-separator*
|
| 6759 |
+
character.
|
| 6760 |
+
|
| 6761 |
+
The filename *dot* ([[fs.def.filename]]) is treated as a reference to
|
| 6762 |
+
the current directory. The filename *dot-dot* ([[fs.def.filename]]) is
|
| 6763 |
+
treated as a reference to the parent directory. What the filename
|
| 6764 |
+
*dot-dot* refers to relative to *root-directory* is
|
| 6765 |
+
*implementation-defined*. Specific filenames may have special meanings
|
| 6766 |
+
for a particular operating system.
|
| 6767 |
+
|
| 6768 |
+
A *root-name* identifies the starting location for pathname resolution (
|
| 6769 |
+
[[fs.def.pathres]]). If there are no operating system dependent
|
| 6770 |
+
*root-name*s, at least one *implementation-defined* *root-name* is
|
| 6771 |
+
required.
|
| 6772 |
+
|
| 6773 |
+
[*Note 2*: Many operating systems define a name beginning with two
|
| 6774 |
+
*directory-separator* characters as a *root-name* that identifies
|
| 6775 |
+
network or other resource locations. Some operating systems define a
|
| 6776 |
+
single letter followed by a colon as a drive specifier – a *root-name*
|
| 6777 |
+
identifying a specific device such as a disk drive. — *end note*]
|
| 6778 |
+
|
| 6779 |
+
If a *root-name* is otherwise ambiguous, the possibility with the
|
| 6780 |
+
longest sequence of characters is chosen.
|
| 6781 |
+
|
| 6782 |
+
[*Note 3*: On a POSIX-like operating system, it is impossible to have a
|
| 6783 |
+
*root-name* and a *relative-path* without an intervening
|
| 6784 |
+
*root-directory* element. — *end note*]
|
| 6785 |
+
|
| 6786 |
+
#### `path` conversions <a id="fs.path.cvt">[[fs.path.cvt]]</a>
|
| 6787 |
+
|
| 6788 |
+
##### `path` argument format conversions <a id="fs.path.fmt.cvt">[[fs.path.fmt.cvt]]</a>
|
| 6789 |
+
|
| 6790 |
+
[*Note 1*:
|
| 6791 |
+
|
| 6792 |
+
The format conversions described in this section are not applied on
|
| 6793 |
+
POSIX-based operating systems because on these systems:
|
| 6794 |
+
|
| 6795 |
+
- The generic format is acceptable as a native path.
|
| 6796 |
+
- There is no need to distinguish between native format and generic
|
| 6797 |
+
format in function arguments.
|
| 6798 |
+
- Paths for regular files and paths for directories share the same
|
| 6799 |
+
syntax.
|
| 6800 |
+
|
| 6801 |
+
— *end note*]
|
| 6802 |
+
|
| 6803 |
+
Several functions are defined to accept *detected-format* arguments,
|
| 6804 |
+
which are character sequences. A detected-format argument represents a
|
| 6805 |
+
path using either a pathname in the generic format (
|
| 6806 |
+
[[fs.path.generic]]) or a pathname in the native format (
|
| 6807 |
+
[[fs.def.native]]). Such an argument is taken to be in the generic
|
| 6808 |
+
format if and only if it matches the generic format and is not
|
| 6809 |
+
acceptable to the operating system as a native path.
|
| 6810 |
+
|
| 6811 |
+
[*Note 2*: Some operating systems may have no unambiguous way to
|
| 6812 |
+
distinguish between native format and generic format arguments. This is
|
| 6813 |
+
by design as it simplifies use for operating systems that do not require
|
| 6814 |
+
disambiguation. An implementation for an operating system where
|
| 6815 |
+
disambiguation is required is permitted to distinguish between the
|
| 6816 |
+
formats. — *end note*]
|
| 6817 |
+
|
| 6818 |
+
Pathnames are converted as needed between the generic and native formats
|
| 6819 |
+
in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
|
| 6820 |
+
mathematical sense be the implementation’s functions that convert
|
| 6821 |
+
native-to-generic and generic-to-native formats respectively. If
|
| 6822 |
+
*g=G(n)* for some *n*, then *G(N(g))=g*; if *n=N(g)* for some *g*, then
|
| 6823 |
+
*N(G(n))=n*.
|
| 6824 |
+
|
| 6825 |
+
[*Note 3*: Neither *G* nor *N* need be invertible. — *end note*]
|
| 6826 |
+
|
| 6827 |
+
If the native format requires paths for regular files to be formatted
|
| 6828 |
+
differently from paths for directories, the path shall be treated as a
|
| 6829 |
+
directory path if its last element is a *directory-separator*, otherwise
|
| 6830 |
+
it shall be treated as a path to a regular file.
|
| 6831 |
+
|
| 6832 |
+
[*Note 4*: A path stores a native format pathname (
|
| 6833 |
+
[[fs.path.native.obs]]) and acts as if it also stores a generic format
|
| 6834 |
+
pathname, related as given below. The implementation may generate the
|
| 6835 |
+
generic format pathname based on the native format pathname (and
|
| 6836 |
+
possibly other information) when requested. — *end note*]
|
| 6837 |
+
|
| 6838 |
+
When a path is constructed from or is assigned a single representation
|
| 6839 |
+
separate from any path, the other representation is selected by the
|
| 6840 |
+
appropriate conversion function (*G* or *N*).
|
| 6841 |
+
|
| 6842 |
+
When the (new) value *p* of one representation of a path is derived from
|
| 6843 |
+
the representation of that or another path, a value *q* is chosen for
|
| 6844 |
+
the other representation. The value *q* converts to *p* (by *G* or *N*
|
| 6845 |
+
as appropriate) if any such value does so; *q* is otherwise unspecified.
|
| 6846 |
+
|
| 6847 |
+
[*Note 5*: If *q* is the result of converting any path at all, it is
|
| 6848 |
+
the result of converting *p*. — *end note*]
|
| 6849 |
+
|
| 6850 |
+
##### `path` type and encoding conversions <a id="fs.path.type.cvt">[[fs.path.type.cvt]]</a>
|
| 6851 |
+
|
| 6852 |
+
For member function arguments that take character sequences representing
|
| 6853 |
+
paths and for member functions returning strings, value type and
|
| 6854 |
+
encoding conversion is performed if the value type of the argument or
|
| 6855 |
+
return value differs from `path::value_type`. For the argument or return
|
| 6856 |
+
value, the method of conversion and the encoding to be converted to is
|
| 6857 |
+
determined by its value type:
|
| 6858 |
+
|
| 6859 |
+
- `char`: The encoding is the native narrow encoding (
|
| 6860 |
+
[[fs.def.native.encode]]). The method of conversion, if any, is
|
| 6861 |
+
operating system dependent. \[*Note 6*: For POSIX-based operating
|
| 6862 |
+
systems `path::value_type` is `char` so no conversion from `char`
|
| 6863 |
+
value type arguments or to `char` value type return values is
|
| 6864 |
+
performed. For Windows-based operating systems, the native narrow
|
| 6865 |
+
encoding is determined by calling a Windows API
|
| 6866 |
+
function. — *end note*] \[*Note 7*: This results in behavior
|
| 6867 |
+
identical to other C and C++ standard library functions that perform
|
| 6868 |
+
file operations using narrow character strings to identify paths.
|
| 6869 |
+
Changing this behavior would be surprising and error
|
| 6870 |
+
prone. — *end note*]
|
| 6871 |
+
- `wchar_t`: The encoding is the native wide encoding (
|
| 6872 |
+
[[fs.def.native.encode]]). The method of conversion is unspecified.
|
| 6873 |
+
\[*Note 8*: For Windows-based operating systems `path::value_type` is
|
| 6874 |
+
`wchar_t` so no conversion from `wchar_t` value type arguments or to
|
| 6875 |
+
`wchar_t` value type return values is performed. — *end note*]
|
| 6876 |
+
- `char16_t`: The encoding is UTF-16. The method of conversion is
|
| 6877 |
+
unspecified.
|
| 6878 |
+
- `char32_t`: The encoding is UTF-32. The method of conversion is
|
| 6879 |
+
unspecified.
|
| 6880 |
+
|
| 6881 |
+
If the encoding being converted to has no representation for source
|
| 6882 |
+
characters, the resulting converted characters, if any, are unspecified.
|
| 6883 |
+
Implementations should not modify member function arguments if already
|
| 6884 |
+
of type `path::value_type`.
|
| 6885 |
+
|
| 6886 |
+
#### `path` requirements <a id="fs.path.req">[[fs.path.req]]</a>
|
| 6887 |
+
|
| 6888 |
+
In addition to the requirements ([[fs.req]]), function template
|
| 6889 |
+
parameters named `Source` shall be one of:
|
| 6890 |
+
|
| 6891 |
+
- `basic_string<EcharT, traits, Allocator>`. A function argument
|
| 6892 |
+
`const Source&` `source` shall have an effective range
|
| 6893 |
+
\[`source.begin()`, `source.end()`).
|
| 6894 |
+
- `basic_string_view<EcharT, traits>`. A function argument
|
| 6895 |
+
`const Source&` `source` shall have an effective range
|
| 6896 |
+
\[`source.begin()`, `source.end()`).
|
| 6897 |
+
- A type meeting the input iterator requirements that iterates over a
|
| 6898 |
+
NTCTS. The value type shall be an encoded character type. A function
|
| 6899 |
+
argument `const Source&` `source` shall have an effective range
|
| 6900 |
+
\[`source`, `end`) where `end` is the first iterator value with an
|
| 6901 |
+
element value equal to `iterator_traits<Source>::value_type()`.
|
| 6902 |
+
- A character array that after array-to-pointer decay results in a
|
| 6903 |
+
pointer to the start of a NTCTS. The value type shall be an encoded
|
| 6904 |
+
character type. A function argument `const Source&` `source` shall
|
| 6905 |
+
have an effective range \[`source`, `end`) where `end` is the first
|
| 6906 |
+
iterator value with an element value equal to
|
| 6907 |
+
`iterator_traits<decay_t<Source>>::value_type()`.
|
| 6908 |
+
|
| 6909 |
+
Functions taking template parameters named `Source` shall not
|
| 6910 |
+
participate in overload resolution unless either
|
| 6911 |
+
|
| 6912 |
+
- `Source` is a specialization of `basic_string` or `basic_string_view`,
|
| 6913 |
+
or
|
| 6914 |
+
- the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
|
| 6915 |
+
valid and denotes a possibly `const` encoded character type (
|
| 6916 |
+
[[temp.deduct]]).
|
| 6917 |
+
|
| 6918 |
+
[*Note 1*: See path conversions ([[fs.path.cvt]]) for how the value
|
| 6919 |
+
types above and their encodings convert to `path::value_type` and its
|
| 6920 |
+
encoding. — *end note*]
|
| 6921 |
+
|
| 6922 |
+
Arguments of type `Source` shall not be null pointers.
|
| 6923 |
+
|
| 6924 |
+
#### `path` members <a id="fs.path.member">[[fs.path.member]]</a>
|
| 6925 |
+
|
| 6926 |
+
##### `path` constructors <a id="fs.path.construct">[[fs.path.construct]]</a>
|
| 6927 |
+
|
| 6928 |
+
``` cpp
|
| 6929 |
+
path() noexcept;
|
| 6930 |
+
```
|
| 6931 |
+
|
| 6932 |
+
*Effects:* Constructs an object of class `path`.
|
| 6933 |
+
|
| 6934 |
+
*Postconditions:* `empty() == true`.
|
| 6935 |
+
|
| 6936 |
+
``` cpp
|
| 6937 |
+
path(const path& p);
|
| 6938 |
+
path(path&& p) noexcept;
|
| 6939 |
+
```
|
| 6940 |
+
|
| 6941 |
+
*Effects:* Constructs an object of class `path` having the same pathname
|
| 6942 |
+
in the native and generic formats, respectively, as the original value
|
| 6943 |
+
of `p`. In the second form, `p` is left in a valid but unspecified
|
| 6944 |
+
state.
|
| 6945 |
+
|
| 6946 |
+
``` cpp
|
| 6947 |
+
path(string_type&& source, format fmt = auto_format);
|
| 6948 |
+
```
|
| 6949 |
+
|
| 6950 |
+
*Effects:* Constructs an object of class `path` for which the pathname
|
| 6951 |
+
in the detected-format of `source` has the original value of
|
| 6952 |
+
`source` ([[fs.path.fmt.cvt]]), converting format if
|
| 6953 |
+
required ([[fs.path.fmt.cvt]]). `source` is left in a valid but
|
| 6954 |
+
unspecified state.
|
| 6955 |
+
|
| 6956 |
+
``` cpp
|
| 6957 |
+
template <class Source>
|
| 6958 |
+
path(const Source& source, format fmt = auto_format);
|
| 6959 |
+
template <class InputIterator>
|
| 6960 |
+
path(InputIterator first, InputIterator last, format fmt = auto_format);
|
| 6961 |
+
```
|
| 6962 |
+
|
| 6963 |
+
*Effects:* Let `s` be the effective range of `source` ([[fs.path.req]])
|
| 6964 |
+
or the range \[`first`, `last`), with the encoding converted if
|
| 6965 |
+
required ([[fs.path.cvt]]). Finds the detected-format of
|
| 6966 |
+
`s` ([[fs.path.fmt.cvt]]) and constructs an object of class `path` for
|
| 6967 |
+
which the pathname in that format is `s`.
|
| 6968 |
+
|
| 6969 |
+
``` cpp
|
| 6970 |
+
template <class Source>
|
| 6971 |
+
path(const Source& source, const locale& loc, format fmt = auto_format);
|
| 6972 |
+
template <class InputIterator>
|
| 6973 |
+
path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
|
| 6974 |
+
```
|
| 6975 |
+
|
| 6976 |
+
*Requires:* The value type of `Source` and `InputIterator` is `char`.
|
| 6977 |
+
|
| 6978 |
+
*Effects:* Let `s` be the effective range of `source` or the range
|
| 6979 |
+
\[`first`, `last`), after converting the encoding as follows:
|
| 6980 |
+
|
| 6981 |
+
- If `value_type` is `wchar_t`, converts to the native wide
|
| 6982 |
+
encoding ([[fs.def.native.encode]]) using the
|
| 6983 |
+
`codecvt<wchar_t, char, mbstate_t>` facet of `loc`.
|
| 6984 |
+
- Otherwise a conversion is performed using the
|
| 6985 |
+
`codecvt<wchar_t, char, mbstate_t>` facet of `loc`, and then a second
|
| 6986 |
+
conversion to the current narrow encoding.
|
| 6987 |
+
|
| 6988 |
+
Finds the detected-format of `s` ([[fs.path.fmt.cvt]]) and constructs
|
| 6989 |
+
an object of class `path` for which the pathname in that format is `s`.
|
| 6990 |
+
|
| 6991 |
+
[*Example 1*:
|
| 6992 |
+
|
| 6993 |
+
A string is to be read from a database that is encoded in ISO/IEC
|
| 6994 |
+
8859-1, and used to create a directory:
|
| 6995 |
+
|
| 6996 |
+
``` cpp
|
| 6997 |
+
namespace fs = std::filesystem;
|
| 6998 |
+
std::string latin1_string = read_latin1_data();
|
| 6999 |
+
codecvt_8859_1<wchar_t> latin1_facet;
|
| 7000 |
+
std::locale latin1_locale(std::locale(), latin1_facet);
|
| 7001 |
+
fs::create_directory(fs::path(latin1_string, latin1_locale));
|
| 7002 |
+
```
|
| 7003 |
+
|
| 7004 |
+
For POSIX-based operating systems, the path is constructed by first
|
| 7005 |
+
using `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string`
|
| 7006 |
+
to a wide character string in the native wide
|
| 7007 |
+
encoding ([[fs.def.native.encode]]). The resulting wide string is then
|
| 7008 |
+
converted to a narrow character pathname string in the current native
|
| 7009 |
+
narrow encoding. If the native wide encoding is UTF-16 or UTF-32, and
|
| 7010 |
+
the current native narrow encoding is UTF-8, all of the characters in
|
| 7011 |
+
the ISO/IEC 8859-1 character set will be converted to their Unicode
|
| 7012 |
+
representation, but for other native narrow encodings some characters
|
| 7013 |
+
may have no representation.
|
| 7014 |
+
|
| 7015 |
+
For Windows-based operating systems, the path is constructed by using
|
| 7016 |
+
`latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string` to a
|
| 7017 |
+
UTF-16 encoded wide character pathname string. All of the characters in
|
| 7018 |
+
the ISO/IEC 8859-1 character set will be converted to their Unicode
|
| 7019 |
+
representation.
|
| 7020 |
+
|
| 7021 |
+
— *end example*]
|
| 7022 |
+
|
| 7023 |
+
##### `path` assignments <a id="fs.path.assign">[[fs.path.assign]]</a>
|
| 7024 |
+
|
| 7025 |
+
``` cpp
|
| 7026 |
+
path& operator=(const path& p);
|
| 7027 |
+
```
|
| 7028 |
+
|
| 7029 |
+
*Effects:* If `*this` and `p` are the same object, has no effect.
|
| 7030 |
+
Otherwise, sets both respective pathnames of `*this` to the respective
|
| 7031 |
+
pathnames of `p`.
|
| 7032 |
+
|
| 7033 |
+
*Returns:* `*this`.
|
| 7034 |
+
|
| 7035 |
+
``` cpp
|
| 7036 |
+
path& operator=(path&& p) noexcept;
|
| 7037 |
+
```
|
| 7038 |
+
|
| 7039 |
+
*Effects:* If `*this` and `p` are the same object, has no effect.
|
| 7040 |
+
Otherwise, sets both respective pathnames of `*this` to the respective
|
| 7041 |
+
pathnames of `p`. `p` is left in a valid but unspecified state.
|
| 7042 |
+
|
| 7043 |
+
[*Note 1*: A valid implementation is `swap(p)`. — *end note*]
|
| 7044 |
+
|
| 7045 |
+
*Returns:* `*this`.
|
| 7046 |
+
|
| 7047 |
+
``` cpp
|
| 7048 |
+
path& operator=(string_type&& source);
|
| 7049 |
+
path& assign(string_type&& source);
|
| 7050 |
+
```
|
| 7051 |
+
|
| 7052 |
+
*Effects:* Sets the pathname in the detected-format of `source` to the
|
| 7053 |
+
original value of `source`. `source` is left in a valid but unspecified
|
| 7054 |
+
state.
|
| 7055 |
+
|
| 7056 |
+
*Returns:* `*this`.
|
| 7057 |
+
|
| 7058 |
+
``` cpp
|
| 7059 |
+
template <class Source>
|
| 7060 |
+
path& operator=(const Source& source);
|
| 7061 |
+
template <class Source>
|
| 7062 |
+
path& assign(const Source& source);
|
| 7063 |
+
template <class InputIterator>
|
| 7064 |
+
path& assign(InputIterator first, InputIterator last);
|
| 7065 |
+
```
|
| 7066 |
+
|
| 7067 |
+
*Effects:* Let `s` be the effective range of `source` ([[fs.path.req]])
|
| 7068 |
+
or the range \[`first`, `last`), with the encoding converted if
|
| 7069 |
+
required ([[fs.path.cvt]]). Finds the detected-format of
|
| 7070 |
+
`s` ([[fs.path.fmt.cvt]]) and sets the pathname in that format to `s`.
|
| 7071 |
+
|
| 7072 |
+
*Returns:* `*this`.
|
| 7073 |
+
|
| 7074 |
+
##### `path` appends <a id="fs.path.append">[[fs.path.append]]</a>
|
| 7075 |
+
|
| 7076 |
+
The append operations use `operator/=` to denote their semantic effect
|
| 7077 |
+
of appending *preferred-separator* when needed.
|
| 7078 |
+
|
| 7079 |
+
``` cpp
|
| 7080 |
+
path& operator/=(const path& p);
|
| 7081 |
+
```
|
| 7082 |
+
|
| 7083 |
+
*Effects:* If
|
| 7084 |
+
`p.is_absolute() || (p.has_root_name() && p.root_name() != root_name())`,
|
| 7085 |
+
then `operator=(p)`.
|
| 7086 |
+
|
| 7087 |
+
Otherwise, modifies `*this` as if by these steps:
|
| 7088 |
+
|
| 7089 |
+
- If `p.has_root_directory()`, then removes any root directory and
|
| 7090 |
+
relative path from the generic format pathname. Otherwise, if
|
| 7091 |
+
`!has_root_directory() && is_absolute()` is `true` or if
|
| 7092 |
+
`has_filename()` is `true`, then appends `path::preferred_separator`
|
| 7093 |
+
to the generic format pathname.
|
| 7094 |
+
- Then appends the native format pathname of `p`, omitting any
|
| 7095 |
+
*root-name* from its generic format pathname, to the native format
|
| 7096 |
+
pathname.
|
| 7097 |
+
|
| 7098 |
+
[*Example 2*:
|
| 7099 |
+
|
| 7100 |
+
Even if `//host` is interpreted as a *root-name*, both of the paths
|
| 7101 |
+
`path("//host")/"foo"` and `path("//host/")/"foo"` equal `"//host/foo"`.
|
| 7102 |
+
|
| 7103 |
+
Expression examples:
|
| 7104 |
+
|
| 7105 |
+
``` cpp
|
| 7106 |
+
// On POSIX,
|
| 7107 |
+
path("foo") / ""; // yields "foo/"
|
| 7108 |
+
path("foo") / "/bar"; // yields "/bar"
|
| 7109 |
+
// On Windows, backslashes replace slashes in the above yields
|
| 7110 |
+
|
| 7111 |
+
// On Windows,
|
| 7112 |
+
path("foo") / "c:/bar"; // yields "c:/bar"
|
| 7113 |
+
path("foo") / "c:"; // yields "c:"
|
| 7114 |
+
path("c:") / ""; // yields "c:"
|
| 7115 |
+
path("c:foo") / "/bar"; // yields "c:/bar"
|
| 7116 |
+
path("c:foo") / "c:bar"; // yields "c:foo/bar"
|
| 7117 |
+
```
|
| 7118 |
+
|
| 7119 |
+
— *end example*]
|
| 7120 |
+
|
| 7121 |
+
*Returns:* `*this`.
|
| 7122 |
+
|
| 7123 |
+
``` cpp
|
| 7124 |
+
template <class Source>
|
| 7125 |
+
path& operator/=(const Source& source);
|
| 7126 |
+
template <class Source>
|
| 7127 |
+
path& append(const Source& source);
|
| 7128 |
+
```
|
| 7129 |
+
|
| 7130 |
+
*Effects:* Equivalent to: `return operator/=(path(source));`
|
| 7131 |
+
|
| 7132 |
+
``` cpp
|
| 7133 |
+
template <class InputIterator>
|
| 7134 |
+
path& append(InputIterator first, InputIterator last);
|
| 7135 |
+
```
|
| 7136 |
+
|
| 7137 |
+
*Effects:* Equivalent to: `return operator/=(path(first, last));`
|
| 7138 |
+
|
| 7139 |
+
##### `path` concatenation <a id="fs.path.concat">[[fs.path.concat]]</a>
|
| 7140 |
+
|
| 7141 |
+
``` cpp
|
| 7142 |
+
path& operator+=(const path& x);
|
| 7143 |
+
path& operator+=(const string_type& x);
|
| 7144 |
+
path& operator+=(basic_string_view<value_type> x);
|
| 7145 |
+
path& operator+=(const value_type* x);
|
| 7146 |
+
path& operator+=(value_type x);
|
| 7147 |
+
template <class Source>
|
| 7148 |
+
path& operator+=(const Source& x);
|
| 7149 |
+
template <class EcharT>
|
| 7150 |
+
path& operator+=(EcharT x);
|
| 7151 |
+
template <class Source>
|
| 7152 |
+
path& concat(const Source& x);
|
| 7153 |
+
```
|
| 7154 |
+
|
| 7155 |
+
*Effects:* Appends `path(x).native()` to the pathname in the native
|
| 7156 |
+
format.
|
| 7157 |
+
|
| 7158 |
+
[*Note 2*: This directly manipulates the value of `native()` and may
|
| 7159 |
+
not be portable between operating systems. — *end note*]
|
| 7160 |
+
|
| 7161 |
+
*Returns:* `*this`.
|
| 7162 |
+
|
| 7163 |
+
``` cpp
|
| 7164 |
+
template <class InputIterator>
|
| 7165 |
+
path& concat(InputIterator first, InputIterator last);
|
| 7166 |
+
```
|
| 7167 |
+
|
| 7168 |
+
*Effects:* Equivalent to `return *this += path(first, last)`.
|
| 7169 |
+
|
| 7170 |
+
##### `path` modifiers <a id="fs.path.modifiers">[[fs.path.modifiers]]</a>
|
| 7171 |
+
|
| 7172 |
+
``` cpp
|
| 7173 |
+
void clear() noexcept;
|
| 7174 |
+
```
|
| 7175 |
+
|
| 7176 |
+
*Postconditions:* `empty() == true`.
|
| 7177 |
+
|
| 7178 |
+
``` cpp
|
| 7179 |
+
path& make_preferred();
|
| 7180 |
+
```
|
| 7181 |
+
|
| 7182 |
+
*Effects:* Each *directory-separator* of the pathname in the generic
|
| 7183 |
+
format is converted to *preferred-separator*.
|
| 7184 |
+
|
| 7185 |
+
*Returns:* `*this`.
|
| 7186 |
+
|
| 7187 |
+
[*Example 3*:
|
| 7188 |
+
|
| 7189 |
+
``` cpp
|
| 7190 |
+
path p("foo/bar");
|
| 7191 |
+
std::cout << p << '\n';
|
| 7192 |
+
p.make_preferred();
|
| 7193 |
+
std::cout << p << '\n';
|
| 7194 |
+
```
|
| 7195 |
+
|
| 7196 |
+
On an operating system where *preferred-separator* is a slash, the
|
| 7197 |
+
output is:
|
| 7198 |
+
|
| 7199 |
+
``` cpp
|
| 7200 |
+
"foo/bar"
|
| 7201 |
+
"foo/bar"
|
| 7202 |
+
```
|
| 7203 |
+
|
| 7204 |
+
On an operating system where *preferred-separator* is a backslash, the
|
| 7205 |
+
output is:
|
| 7206 |
+
|
| 7207 |
+
``` cpp
|
| 7208 |
+
"foo/bar"
|
| 7209 |
+
"foo\bar"
|
| 7210 |
+
```
|
| 7211 |
+
|
| 7212 |
+
— *end example*]
|
| 7213 |
+
|
| 7214 |
+
``` cpp
|
| 7215 |
+
path& remove_filename();
|
| 7216 |
+
```
|
| 7217 |
+
|
| 7218 |
+
*Postconditions:* `!has_filename()`.
|
| 7219 |
+
|
| 7220 |
+
*Effects:* Remove the generic format pathname of `filename()` from the
|
| 7221 |
+
generic format pathname.
|
| 7222 |
+
|
| 7223 |
+
*Returns:* `*this`.
|
| 7224 |
+
|
| 7225 |
+
[*Example 4*:
|
| 7226 |
+
|
| 7227 |
+
``` cpp
|
| 7228 |
+
path("foo/bar").remove_filename(); // yields "foo/"
|
| 7229 |
+
path("foo/").remove_filename(); // yields "foo/"
|
| 7230 |
+
path("/foo").remove_filename(); // yields "/"
|
| 7231 |
+
path("/").remove_filename(); // yields "/"
|
| 7232 |
+
```
|
| 7233 |
+
|
| 7234 |
+
— *end example*]
|
| 7235 |
+
|
| 7236 |
+
``` cpp
|
| 7237 |
+
path& replace_filename(const path& replacement);
|
| 7238 |
+
```
|
| 7239 |
+
|
| 7240 |
+
*Effects:* Equivalent to:
|
| 7241 |
+
|
| 7242 |
+
``` cpp
|
| 7243 |
+
remove_filename();
|
| 7244 |
+
operator/=(replacement);
|
| 7245 |
+
```
|
| 7246 |
+
|
| 7247 |
+
*Returns:* `*this`.
|
| 7248 |
+
|
| 7249 |
+
[*Example 5*:
|
| 7250 |
+
|
| 7251 |
+
``` cpp
|
| 7252 |
+
path("/foo").replace_filename("bar"); // yields "/bar" on POSIX
|
| 7253 |
+
path("/").replace_filename("bar"); // yields "/bar" on POSIX
|
| 7254 |
+
```
|
| 7255 |
+
|
| 7256 |
+
— *end example*]
|
| 7257 |
+
|
| 7258 |
+
``` cpp
|
| 7259 |
+
path& replace_extension(const path& replacement = path());
|
| 7260 |
+
```
|
| 7261 |
+
|
| 7262 |
+
*Effects:*
|
| 7263 |
+
|
| 7264 |
+
- Any existing `extension()(` [[fs.path.decompose]]`)` is removed from
|
| 7265 |
+
the pathname in the generic format, then
|
| 7266 |
+
- If `replacement` is not empty and does not begin with a dot character,
|
| 7267 |
+
a dot character is appended to the pathname in the generic format,
|
| 7268 |
+
then
|
| 7269 |
+
- `operator+=(replacement);`.
|
| 7270 |
+
|
| 7271 |
+
*Returns:* `*this`.
|
| 7272 |
+
|
| 7273 |
+
``` cpp
|
| 7274 |
+
void swap(path& rhs) noexcept;
|
| 7275 |
+
```
|
| 7276 |
+
|
| 7277 |
+
*Effects:* Swaps the contents (in all formats) of the two paths.
|
| 7278 |
+
|
| 7279 |
+
*Complexity:* Constant time.
|
| 7280 |
+
|
| 7281 |
+
##### `path` native format observers <a id="fs.path.native.obs">[[fs.path.native.obs]]</a>
|
| 7282 |
+
|
| 7283 |
+
The string returned by all native format observers is in the native
|
| 7284 |
+
pathname format ([[fs.def.native]]).
|
| 7285 |
+
|
| 7286 |
+
``` cpp
|
| 7287 |
+
const string_type& native() const noexcept;
|
| 7288 |
+
```
|
| 7289 |
+
|
| 7290 |
+
*Returns:* The pathname in the native format.
|
| 7291 |
+
|
| 7292 |
+
``` cpp
|
| 7293 |
+
const value_type* c_str() const noexcept;
|
| 7294 |
+
```
|
| 7295 |
+
|
| 7296 |
+
*Returns:* Equivalent to `native().c_str()`.
|
| 7297 |
+
|
| 7298 |
+
``` cpp
|
| 7299 |
+
operator string_type() const;
|
| 7300 |
+
```
|
| 7301 |
+
|
| 7302 |
+
*Returns:* `native()`.
|
| 7303 |
+
|
| 7304 |
+
[*Note 3*: Conversion to `string_type` is provided so that an object of
|
| 7305 |
+
class `path` can be given as an argument to existing standard library
|
| 7306 |
+
file stream constructors and open functions. — *end note*]
|
| 7307 |
+
|
| 7308 |
+
``` cpp
|
| 7309 |
+
template <class EcharT, class traits = char_traits<EcharT>,
|
| 7310 |
+
class Allocator = allocator<EcharT>>
|
| 7311 |
+
basic_string<EcharT, traits, Allocator>
|
| 7312 |
+
string(const Allocator& a = Allocator()) const;
|
| 7313 |
+
```
|
| 7314 |
+
|
| 7315 |
+
*Returns:* `native()`.
|
| 7316 |
+
|
| 7317 |
+
*Remarks:* All memory allocation, including for the return value, shall
|
| 7318 |
+
be performed by `a`. Conversion, if any, is specified by
|
| 7319 |
+
[[fs.path.cvt]].
|
| 7320 |
+
|
| 7321 |
+
``` cpp
|
| 7322 |
+
std::string string() const;
|
| 7323 |
+
std::wstring wstring() const;
|
| 7324 |
+
std::string u8string() const;
|
| 7325 |
+
std::u16string u16string() const;
|
| 7326 |
+
std::u32string u32string() const;
|
| 7327 |
+
```
|
| 7328 |
+
|
| 7329 |
+
*Returns:* `pathstring`.
|
| 7330 |
+
|
| 7331 |
+
*Remarks:* Conversion, if any, is performed as specified by
|
| 7332 |
+
[[fs.path.cvt]]. The encoding of the string returned by `u8string()` is
|
| 7333 |
+
always UTF-8.
|
| 7334 |
+
|
| 7335 |
+
##### `path` generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
|
| 7336 |
+
|
| 7337 |
+
Generic format observer functions return strings formatted according to
|
| 7338 |
+
the generic pathname format ([[fs.path.generic]]). A single slash
|
| 7339 |
+
(`'/'`) character is used as the *directory-separator*.
|
| 7340 |
+
|
| 7341 |
+
[*Example 1*:
|
| 7342 |
+
|
| 7343 |
+
On an operating system that uses backslash as its *preferred-separator*,
|
| 7344 |
+
|
| 7345 |
+
``` cpp
|
| 7346 |
+
path("foo\\bar").generic_string()
|
| 7347 |
+
```
|
| 7348 |
+
|
| 7349 |
+
returns `"foo/bar"`.
|
| 7350 |
+
|
| 7351 |
+
— *end example*]
|
| 7352 |
+
|
| 7353 |
+
``` cpp
|
| 7354 |
+
template <class EcharT, class traits = char_traits<EcharT>,
|
| 7355 |
+
class Allocator = allocator<EcharT>>
|
| 7356 |
+
basic_string<EcharT, traits, Allocator>
|
| 7357 |
+
generic_string(const Allocator& a = Allocator()) const;
|
| 7358 |
+
```
|
| 7359 |
+
|
| 7360 |
+
*Returns:* The pathname in the generic format.
|
| 7361 |
+
|
| 7362 |
+
*Remarks:* All memory allocation, including for the return value, shall
|
| 7363 |
+
be performed by `a`. Conversion, if any, is specified by
|
| 7364 |
+
[[fs.path.cvt]].
|
| 7365 |
+
|
| 7366 |
+
``` cpp
|
| 7367 |
+
std::string generic_string() const;
|
| 7368 |
+
std::wstring generic_wstring() const;
|
| 7369 |
+
std::string generic_u8string() const;
|
| 7370 |
+
std::u16string generic_u16string() const;
|
| 7371 |
+
std::u32string generic_u32string() const;
|
| 7372 |
+
```
|
| 7373 |
+
|
| 7374 |
+
*Returns:* The pathname in the generic format.
|
| 7375 |
+
|
| 7376 |
+
*Remarks:* Conversion, if any, is specified by [[fs.path.cvt]]. The
|
| 7377 |
+
encoding of the string returned by `generic_u8string()` is always UTF-8.
|
| 7378 |
+
|
| 7379 |
+
##### `path` compare <a id="fs.path.compare">[[fs.path.compare]]</a>
|
| 7380 |
+
|
| 7381 |
+
``` cpp
|
| 7382 |
+
int compare(const path& p) const noexcept;
|
| 7383 |
+
```
|
| 7384 |
+
|
| 7385 |
+
*Returns:*
|
| 7386 |
+
|
| 7387 |
+
- A value less than `0`, if `native()` for the elements of `*this` are
|
| 7388 |
+
lexicographically less than `native()` for the elements of `p`;
|
| 7389 |
+
otherwise,
|
| 7390 |
+
- a value greater than `0`, if `native()` for the elements of `*this`
|
| 7391 |
+
are lexicographically greater than `native()` for the elements of `p`;
|
| 7392 |
+
otherwise,
|
| 7393 |
+
- `0`.
|
| 7394 |
+
|
| 7395 |
+
*Remarks:* The elements are determined as if by iteration over the
|
| 7396 |
+
half-open range \[`begin()`, `end()`) for `*this` and `p`.
|
| 7397 |
+
|
| 7398 |
+
``` cpp
|
| 7399 |
+
int compare(const string_type& s) const
|
| 7400 |
+
int compare(basic_string_view<value_type> s) const;
|
| 7401 |
+
```
|
| 7402 |
+
|
| 7403 |
+
*Returns:* `compare(path(s))`.
|
| 7404 |
+
|
| 7405 |
+
``` cpp
|
| 7406 |
+
int compare(const value_type* s) const
|
| 7407 |
+
```
|
| 7408 |
+
|
| 7409 |
+
*Returns:* `compare(path(s))`.
|
| 7410 |
+
|
| 7411 |
+
##### `path` decomposition <a id="fs.path.decompose">[[fs.path.decompose]]</a>
|
| 7412 |
+
|
| 7413 |
+
``` cpp
|
| 7414 |
+
path root_name() const;
|
| 7415 |
+
```
|
| 7416 |
+
|
| 7417 |
+
*Returns:* *root-name*, if the pathname in the generic format includes
|
| 7418 |
+
*root-name*, otherwise `path()`.
|
| 7419 |
+
|
| 7420 |
+
``` cpp
|
| 7421 |
+
path root_directory() const;
|
| 7422 |
+
```
|
| 7423 |
+
|
| 7424 |
+
*Returns:* *root-directory*, if the pathname in the generic format
|
| 7425 |
+
includes *root-directory*, otherwise `path()`.
|
| 7426 |
+
|
| 7427 |
+
``` cpp
|
| 7428 |
+
path root_path() const;
|
| 7429 |
+
```
|
| 7430 |
+
|
| 7431 |
+
*Returns:* `root_name() / root_directory()`.
|
| 7432 |
+
|
| 7433 |
+
``` cpp
|
| 7434 |
+
path relative_path() const;
|
| 7435 |
+
```
|
| 7436 |
+
|
| 7437 |
+
*Returns:* A `path` composed from the pathname in the generic format, if
|
| 7438 |
+
`!empty()`, beginning with the first *filename* after *root-path*.
|
| 7439 |
+
Otherwise, `path()`.
|
| 7440 |
+
|
| 7441 |
+
``` cpp
|
| 7442 |
+
path parent_path() const;
|
| 7443 |
+
```
|
| 7444 |
+
|
| 7445 |
+
*Returns:* `*this` if `!has_relative_path()`, otherwise a path whose
|
| 7446 |
+
generic format pathname is the longest prefix of the generic format
|
| 7447 |
+
pathname of `*this` that produces one fewer element in its iteration.
|
| 7448 |
+
|
| 7449 |
+
``` cpp
|
| 7450 |
+
path filename() const;
|
| 7451 |
+
```
|
| 7452 |
+
|
| 7453 |
+
*Returns:* `relative_path().empty() ? path() : *–end()`.
|
| 7454 |
+
|
| 7455 |
+
[*Example 6*:
|
| 7456 |
+
|
| 7457 |
+
``` cpp
|
| 7458 |
+
path("/foo/bar.txt").filename(); // yields "bar.txt"
|
| 7459 |
+
path("/foo/bar").filename(); // yields "bar"
|
| 7460 |
+
path("/foo/bar/").filename(); // yields ""
|
| 7461 |
+
path("/").filename(); // yields ""
|
| 7462 |
+
path("//host").filename(); // yields ""
|
| 7463 |
+
path(".").filename(); // yields "."
|
| 7464 |
+
path("..").filename(); // yields ".."
|
| 7465 |
+
```
|
| 7466 |
+
|
| 7467 |
+
— *end example*]
|
| 7468 |
+
|
| 7469 |
+
``` cpp
|
| 7470 |
+
path stem() const;
|
| 7471 |
+
```
|
| 7472 |
+
|
| 7473 |
+
*Returns:* Let `f` be the generic format pathname of `filename()`.
|
| 7474 |
+
Returns a path whose pathname in the generic format is
|
| 7475 |
+
|
| 7476 |
+
- `f`, if it contains no periods other than a leading period or consists
|
| 7477 |
+
solely of one or two periods;
|
| 7478 |
+
- otherwise, the prefix of `f` ending before its last period.
|
| 7479 |
+
|
| 7480 |
+
[*Example 7*:
|
| 7481 |
+
|
| 7482 |
+
``` cpp
|
| 7483 |
+
std::cout << path("/foo/bar.txt").stem(); // outputs "bar"
|
| 7484 |
+
path p = "foo.bar.baz.tar";
|
| 7485 |
+
for (; !p.extension().empty(); p = p.stem())
|
| 7486 |
+
std::cout << p.extension() << '\n';
|
| 7487 |
+
// outputs: .tar
|
| 7488 |
+
// .baz
|
| 7489 |
+
// .bar
|
| 7490 |
+
```
|
| 7491 |
+
|
| 7492 |
+
— *end example*]
|
| 7493 |
+
|
| 7494 |
+
``` cpp
|
| 7495 |
+
path extension() const;
|
| 7496 |
+
```
|
| 7497 |
+
|
| 7498 |
+
*Returns:* a path whose pathname in the generic format is the suffix of
|
| 7499 |
+
`filename()` not included in `stem()`.
|
| 7500 |
+
|
| 7501 |
+
[*Example 8*:
|
| 7502 |
+
|
| 7503 |
+
``` cpp
|
| 7504 |
+
path("/foo/bar.txt").extension(); // yields ".txt" and stem() is "bar"
|
| 7505 |
+
path("/foo/bar").extension(); // yields "" and stem() is "bar"
|
| 7506 |
+
path("/foo/.profile").extension(); // yields "" and stem() is ".profile"
|
| 7507 |
+
path(".bar").extension(); // yields "" and stem() is ".bar"
|
| 7508 |
+
path("..bar").extension(); // yields ".bar" and stem() is "."
|
| 7509 |
+
```
|
| 7510 |
+
|
| 7511 |
+
— *end example*]
|
| 7512 |
+
|
| 7513 |
+
[*Note 4*: The period is included in the return value so that it is
|
| 7514 |
+
possible to distinguish between no extension and an empty
|
| 7515 |
+
extension. — *end note*]
|
| 7516 |
+
|
| 7517 |
+
[*Note 5*: On non-POSIX operating systems, for a path `p`, it may not
|
| 7518 |
+
be the case that `p.stem() + p.extension() == p.filename()`, even though
|
| 7519 |
+
the generic format pathnames are the same. — *end note*]
|
| 7520 |
+
|
| 7521 |
+
##### `path` query <a id="fs.path.query">[[fs.path.query]]</a>
|
| 7522 |
+
|
| 7523 |
+
``` cpp
|
| 7524 |
+
bool empty() const noexcept;
|
| 7525 |
+
```
|
| 7526 |
+
|
| 7527 |
+
*Returns:* `true` if the pathname in the generic format is empty, else
|
| 7528 |
+
`false`.
|
| 7529 |
+
|
| 7530 |
+
``` cpp
|
| 7531 |
+
bool has_root_path() const;
|
| 7532 |
+
```
|
| 7533 |
+
|
| 7534 |
+
*Returns:* `!root_path().empty()`.
|
| 7535 |
+
|
| 7536 |
+
``` cpp
|
| 7537 |
+
bool has_root_name() const;
|
| 7538 |
+
```
|
| 7539 |
+
|
| 7540 |
+
*Returns:* `!root_name().empty()`.
|
| 7541 |
+
|
| 7542 |
+
``` cpp
|
| 7543 |
+
bool has_root_directory() const;
|
| 7544 |
+
```
|
| 7545 |
+
|
| 7546 |
+
*Returns:* `!root_directory().empty()`.
|
| 7547 |
+
|
| 7548 |
+
``` cpp
|
| 7549 |
+
bool has_relative_path() const;
|
| 7550 |
+
```
|
| 7551 |
+
|
| 7552 |
+
*Returns:* `!relative_path().empty()`.
|
| 7553 |
+
|
| 7554 |
+
``` cpp
|
| 7555 |
+
bool has_parent_path() const;
|
| 7556 |
+
```
|
| 7557 |
+
|
| 7558 |
+
*Returns:* `!parent_path().empty()`.
|
| 7559 |
+
|
| 7560 |
+
``` cpp
|
| 7561 |
+
bool has_filename() const;
|
| 7562 |
+
```
|
| 7563 |
+
|
| 7564 |
+
*Returns:* `!filename().empty()`.
|
| 7565 |
+
|
| 7566 |
+
``` cpp
|
| 7567 |
+
bool has_stem() const;
|
| 7568 |
+
```
|
| 7569 |
+
|
| 7570 |
+
*Returns:* `!stem().empty()`.
|
| 7571 |
+
|
| 7572 |
+
``` cpp
|
| 7573 |
+
bool has_extension() const;
|
| 7574 |
+
```
|
| 7575 |
+
|
| 7576 |
+
*Returns:* `!extension().empty()`.
|
| 7577 |
+
|
| 7578 |
+
``` cpp
|
| 7579 |
+
bool is_absolute() const;
|
| 7580 |
+
```
|
| 7581 |
+
|
| 7582 |
+
*Returns:* `true` if the pathname in the native format contains an
|
| 7583 |
+
absolute path ([[fs.def.absolute.path]]), else `false`.
|
| 7584 |
+
|
| 7585 |
+
[*Example 9*: `path("/").is_absolute()` is `true` for POSIX-based
|
| 7586 |
+
operating systems, and `false` for Windows-based operating
|
| 7587 |
+
systems. — *end example*]
|
| 7588 |
+
|
| 7589 |
+
``` cpp
|
| 7590 |
+
bool is_relative() const;
|
| 7591 |
+
```
|
| 7592 |
+
|
| 7593 |
+
*Returns:* `!is_absolute()`.
|
| 7594 |
+
|
| 7595 |
+
##### `path` generation <a id="fs.path.gen">[[fs.path.gen]]</a>
|
| 7596 |
+
|
| 7597 |
+
``` cpp
|
| 7598 |
+
path lexically_normal() const;
|
| 7599 |
+
```
|
| 7600 |
+
|
| 7601 |
+
*Returns:* A path whose pathname in the generic format is the normal
|
| 7602 |
+
form ([[fs.def.normal.form]]) of the pathname in the generic format of
|
| 7603 |
+
`*this`.
|
| 7604 |
+
|
| 7605 |
+
[*Example 10*:
|
| 7606 |
+
|
| 7607 |
+
``` cpp
|
| 7608 |
+
assert(path("foo/./bar/..").lexically_normal() == "foo/");
|
| 7609 |
+
assert(path("foo/.///bar/../").lexically_normal() == "foo/");
|
| 7610 |
+
```
|
| 7611 |
+
|
| 7612 |
+
The above assertions will succeed. On Windows, the returned path’s
|
| 7613 |
+
*directory-separator* characters will be backslashes rather than
|
| 7614 |
+
slashes, but that does not affect `path` equality.
|
| 7615 |
+
|
| 7616 |
+
— *end example*]
|
| 7617 |
+
|
| 7618 |
+
``` cpp
|
| 7619 |
+
path lexically_relative(const path& base) const;
|
| 7620 |
+
```
|
| 7621 |
+
|
| 7622 |
+
*Returns:* `*this` made relative to `base`. Does not
|
| 7623 |
+
resolve ([[fs.def.pathres]]) symlinks. Does not first
|
| 7624 |
+
normalize ([[fs.def.normal.form]]) `*this` or `base`.
|
| 7625 |
+
|
| 7626 |
+
*Effects:* If `root_name() != base.root_name()` is `true` or
|
| 7627 |
+
`is_absolute() != base.is_absolute()` is `true` or
|
| 7628 |
+
`!has_root_directory() && base.has_root_directory()` is `true`, returns
|
| 7629 |
+
`path()`. Determines the first mismatched element of `*this` and `base`
|
| 7630 |
+
as if by:
|
| 7631 |
+
|
| 7632 |
+
``` cpp
|
| 7633 |
+
auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
|
| 7634 |
+
```
|
| 7635 |
+
|
| 7636 |
+
Then,
|
| 7637 |
+
|
| 7638 |
+
- if `a == end()` and `b == base.end()`, returns `path(".")`; otherwise
|
| 7639 |
+
- let `n` be the number of *filename* elements in \[`b`, `base.end()`)
|
| 7640 |
+
that are not *dot* or *dot-dot* minus the number that are *dot-dot*.
|
| 7641 |
+
If `n<0,` returns `path()`; otherwise
|
| 7642 |
+
- returns an object of class `path` that is default-constructed,
|
| 7643 |
+
followed by
|
| 7644 |
+
- application of `operator/=(path(".."))` `n` times, and then
|
| 7645 |
+
- application of `operator/=` for each element in \[`a`, `end()`).
|
| 7646 |
+
|
| 7647 |
+
[*Example 11*:
|
| 7648 |
+
|
| 7649 |
+
``` cpp
|
| 7650 |
+
assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
|
| 7651 |
+
assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
|
| 7652 |
+
assert(path("a/b/c").lexically_relative("a") == "b/c");
|
| 7653 |
+
assert(path("a/b/c").lexically_relative("a/b/c/x/y") == "../..");
|
| 7654 |
+
assert(path("a/b/c").lexically_relative("a/b/c") == ".");
|
| 7655 |
+
assert(path("a/b").lexically_relative("c/d") == "../../a/b");
|
| 7656 |
+
```
|
| 7657 |
+
|
| 7658 |
+
The above assertions will succeed. On Windows, the returned path’s
|
| 7659 |
+
*directory-separator* characters will be backslashes rather than
|
| 7660 |
+
slashes, but that does not affect `path` equality.
|
| 7661 |
+
|
| 7662 |
+
— *end example*]
|
| 7663 |
+
|
| 7664 |
+
[*Note 6*: If symlink following semantics are desired, use the
|
| 7665 |
+
operational function `relative()`. — *end note*]
|
| 7666 |
+
|
| 7667 |
+
[*Note 7*: If normalization ([[fs.def.normal.form]]) is needed to
|
| 7668 |
+
ensure consistent matching of elements, apply `lexically_normal()` to
|
| 7669 |
+
`*this`, `base`, or both. — *end note*]
|
| 7670 |
+
|
| 7671 |
+
``` cpp
|
| 7672 |
+
path lexically_proximate(const path& base) const;
|
| 7673 |
+
```
|
| 7674 |
+
|
| 7675 |
+
*Returns:* If the value of `lexically_relative(base)` is not an empty
|
| 7676 |
+
path, return it. Otherwise return `*this`.
|
| 7677 |
+
|
| 7678 |
+
[*Note 8*: If symlink following semantics are desired, use the
|
| 7679 |
+
operational function `proximate()`. — *end note*]
|
| 7680 |
+
|
| 7681 |
+
[*Note 9*: If normalization ([[fs.def.normal.form]]) is needed to
|
| 7682 |
+
ensure consistent matching of elements, apply `lexically_normal()` to
|
| 7683 |
+
`*this`, `base`, or both. — *end note*]
|
| 7684 |
+
|
| 7685 |
+
#### `path` iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
|
| 7686 |
+
|
| 7687 |
+
Path iterators iterate over the elements of the pathname in the generic
|
| 7688 |
+
format ([[fs.path.generic]]).
|
| 7689 |
+
|
| 7690 |
+
A `path::iterator` is a constant iterator satisfying all the
|
| 7691 |
+
requirements of a bidirectional iterator ([[bidirectional.iterators]])
|
| 7692 |
+
except that, for dereferenceable iterators `a` and `b` of type
|
| 7693 |
+
`path::iterator` with `a == b`, there is no requirement that `*a` and
|
| 7694 |
+
`*b` are bound to the same object. Its `value_type` is `path`.
|
| 7695 |
+
|
| 7696 |
+
Calling any non-const member function of a `path` object invalidates all
|
| 7697 |
+
iterators referring to elements of that object.
|
| 7698 |
+
|
| 7699 |
+
For the elements of the pathname in the generic format, the forward
|
| 7700 |
+
traversal order is as follows:
|
| 7701 |
+
|
| 7702 |
+
- The *root-name* element, if present.
|
| 7703 |
+
- The *root-directory* element, if present. \[*Note 1*: The generic
|
| 7704 |
+
format is required to ensure lexicographical comparison works
|
| 7705 |
+
correctly. — *end note*]
|
| 7706 |
+
- Each successive *filename* element, if present.
|
| 7707 |
+
- An empty element, if a trailing non-root *directory-separator* is
|
| 7708 |
+
present.
|
| 7709 |
+
|
| 7710 |
+
The backward traversal order is the reverse of forward traversal.
|
| 7711 |
+
|
| 7712 |
+
``` cpp
|
| 7713 |
+
iterator begin() const;
|
| 7714 |
+
```
|
| 7715 |
+
|
| 7716 |
+
*Returns:* An iterator for the first present element in the traversal
|
| 7717 |
+
list above. If no elements are present, the end iterator.
|
| 7718 |
+
|
| 7719 |
+
``` cpp
|
| 7720 |
+
iterator end() const;
|
| 7721 |
+
```
|
| 7722 |
+
|
| 7723 |
+
*Returns:* The end iterator.
|
| 7724 |
+
|
| 7725 |
+
#### `path` non-member functions <a id="fs.path.nonmember">[[fs.path.nonmember]]</a>
|
| 7726 |
+
|
| 7727 |
+
``` cpp
|
| 7728 |
+
void swap(path& lhs, path& rhs) noexcept;
|
| 7729 |
+
```
|
| 7730 |
+
|
| 7731 |
+
*Effects:* Equivalent to: `lhs.swap(rhs);`
|
| 7732 |
+
|
| 7733 |
+
``` cpp
|
| 7734 |
+
size_t hash_value (const path& p) noexcept;
|
| 7735 |
+
```
|
| 7736 |
+
|
| 7737 |
+
*Returns:* A hash value for the path `p`. If for two paths, `p1 == p2`
|
| 7738 |
+
then `hash_value(p1) == hash_value(p2)`.
|
| 7739 |
+
|
| 7740 |
+
``` cpp
|
| 7741 |
+
bool operator< (const path& lhs, const path& rhs) noexcept;
|
| 7742 |
+
```
|
| 7743 |
+
|
| 7744 |
+
*Returns:* `lhs.compare(rhs) < 0`.
|
| 7745 |
+
|
| 7746 |
+
``` cpp
|
| 7747 |
+
bool operator<=(const path& lhs, const path& rhs) noexcept;
|
| 7748 |
+
```
|
| 7749 |
+
|
| 7750 |
+
*Returns:* `!(rhs < lhs)`.
|
| 7751 |
+
|
| 7752 |
+
``` cpp
|
| 7753 |
+
bool operator> (const path& lhs, const path& rhs) noexcept;
|
| 7754 |
+
```
|
| 7755 |
+
|
| 7756 |
+
*Returns:* `rhs < lhs`.
|
| 7757 |
+
|
| 7758 |
+
``` cpp
|
| 7759 |
+
bool operator>=(const path& lhs, const path& rhs) noexcept;
|
| 7760 |
+
```
|
| 7761 |
+
|
| 7762 |
+
*Returns:* `!(lhs < rhs)`.
|
| 7763 |
+
|
| 7764 |
+
``` cpp
|
| 7765 |
+
bool operator==(const path& lhs, const path& rhs) noexcept;
|
| 7766 |
+
```
|
| 7767 |
+
|
| 7768 |
+
*Returns:* `!(lhs < rhs) && !(rhs < lhs)`.
|
| 7769 |
+
|
| 7770 |
+
[*Note 1*:
|
| 7771 |
+
|
| 7772 |
+
Path equality and path equivalence have different semantics.
|
| 7773 |
+
|
| 7774 |
+
- Equality is determined by the `path` non-member `operator==`, which
|
| 7775 |
+
considers the two path’s lexical representations only.
|
| 7776 |
+
\[*Example 1*: `path("foo") == "bar"` is never
|
| 7777 |
+
`true`. — *end example*]
|
| 7778 |
+
- Equivalence is determined by the `equivalent()` non-member function,
|
| 7779 |
+
which determines if two paths resolve ([[fs.def.pathres]]) to the
|
| 7780 |
+
same file system entity. \[*Example 2*: `equivalent("foo", "bar")`
|
| 7781 |
+
will be `true` when both paths resolve to the same
|
| 7782 |
+
file. — *end example*]
|
| 7783 |
+
|
| 7784 |
+
Programmers wishing to determine if two paths are “the same” must decide
|
| 7785 |
+
if “the same” means “the same representation” or “resolve to the same
|
| 7786 |
+
actual file”, and choose the appropriate function accordingly.
|
| 7787 |
+
|
| 7788 |
+
— *end note*]
|
| 7789 |
+
|
| 7790 |
+
``` cpp
|
| 7791 |
+
bool operator!=(const path& lhs, const path& rhs) noexcept;
|
| 7792 |
+
```
|
| 7793 |
+
|
| 7794 |
+
*Returns:* `!(lhs == rhs)`.
|
| 7795 |
+
|
| 7796 |
+
``` cpp
|
| 7797 |
+
path operator/ (const path& lhs, const path& rhs);
|
| 7798 |
+
```
|
| 7799 |
+
|
| 7800 |
+
*Effects:* Equivalent to: `return path(lhs) /= rhs;`
|
| 7801 |
+
|
| 7802 |
+
##### `path` inserter and extractor <a id="fs.path.io">[[fs.path.io]]</a>
|
| 7803 |
+
|
| 7804 |
+
``` cpp
|
| 7805 |
+
template <class charT, class traits>
|
| 7806 |
+
basic_ostream<charT, traits>&
|
| 7807 |
+
operator<<(basic_ostream<charT, traits>& os, const path& p);
|
| 7808 |
+
```
|
| 7809 |
+
|
| 7810 |
+
*Effects:* Equivalent to: `os << quoted(p.string<charT, traits>());`
|
| 7811 |
+
|
| 7812 |
+
[*Note 2*: The `quoted` function is described
|
| 7813 |
+
in [[quoted.manip]]. — *end note*]
|
| 7814 |
+
|
| 7815 |
+
*Returns:* `os`.
|
| 7816 |
+
|
| 7817 |
+
``` cpp
|
| 7818 |
+
template <class charT, class traits>
|
| 7819 |
+
basic_istream<charT, traits>&
|
| 7820 |
+
operator>>(basic_istream<charT, traits>& is, path& p);
|
| 7821 |
+
```
|
| 7822 |
+
|
| 7823 |
+
*Effects:* Equivalent to:
|
| 7824 |
+
|
| 7825 |
+
``` cpp
|
| 7826 |
+
basic_string<charT, traits> tmp;
|
| 7827 |
+
is >> quoted(tmp);
|
| 7828 |
+
p = tmp;
|
| 7829 |
+
```
|
| 7830 |
+
|
| 7831 |
+
*Returns:* `is`.
|
| 7832 |
+
|
| 7833 |
+
##### `path` factory functions <a id="fs.path.factory">[[fs.path.factory]]</a>
|
| 7834 |
+
|
| 7835 |
+
``` cpp
|
| 7836 |
+
template <class Source>
|
| 7837 |
+
path u8path(const Source& source);
|
| 7838 |
+
template <class InputIterator>
|
| 7839 |
+
path u8path(InputIterator first, InputIterator last);
|
| 7840 |
+
```
|
| 7841 |
+
|
| 7842 |
+
*Requires:* The `source` and \[`first`, `last`) sequences are UTF-8
|
| 7843 |
+
encoded. The value type of `Source` and `InputIterator` is `char`.
|
| 7844 |
+
|
| 7845 |
+
*Returns:*
|
| 7846 |
+
|
| 7847 |
+
- If `value_type` is `char` and the current native narrow
|
| 7848 |
+
encoding ([[fs.def.native.encode]]) is UTF-8, return `path(source)`
|
| 7849 |
+
or `path(first, last)`; otherwise,
|
| 7850 |
+
- if `value_type` is `wchar_t` and the native wide encoding is UTF-16,
|
| 7851 |
+
or if `value_type` is `char16_t` or `char32_t`, convert `source` or
|
| 7852 |
+
\[`first`, `last`) to a temporary, `tmp`, of type `string_type` and
|
| 7853 |
+
return `path(tmp)`; otherwise,
|
| 7854 |
+
- convert `source` or \[`first`, `last`) to a temporary, `tmp`, of type
|
| 7855 |
+
`u32string` and return `path(tmp)`.
|
| 7856 |
+
|
| 7857 |
+
*Remarks:* Argument format conversion ([[fs.path.fmt.cvt]]) applies to
|
| 7858 |
+
the arguments for these functions. How Unicode encoding conversions are
|
| 7859 |
+
performed is unspecified.
|
| 7860 |
+
|
| 7861 |
+
[*Example 1*:
|
| 7862 |
+
|
| 7863 |
+
A string is to be read from a database that is encoded in UTF-8, and
|
| 7864 |
+
used to create a directory using the native encoding for filenames:
|
| 7865 |
+
|
| 7866 |
+
``` cpp
|
| 7867 |
+
namespace fs = std::filesystem;
|
| 7868 |
+
std::string utf8_string = read_utf8_data();
|
| 7869 |
+
fs::create_directory(fs::u8path(utf8_string));
|
| 7870 |
+
```
|
| 7871 |
+
|
| 7872 |
+
For POSIX-based operating systems with the native narrow encoding set to
|
| 7873 |
+
UTF-8, no encoding or type conversion occurs.
|
| 7874 |
+
|
| 7875 |
+
For POSIX-based operating systems with the native narrow encoding not
|
| 7876 |
+
set to UTF-8, a conversion to UTF-32 occurs, followed by a conversion to
|
| 7877 |
+
the current native narrow encoding. Some Unicode characters may have no
|
| 7878 |
+
native character set representation.
|
| 7879 |
+
|
| 7880 |
+
For Windows-based operating systems a conversion from UTF-8 to UTF-16
|
| 7881 |
+
occurs.
|
| 7882 |
+
|
| 7883 |
+
— *end example*]
|
| 7884 |
+
|
| 7885 |
+
### Class `filesystem_error` <a id="fs.class.filesystem_error">[[fs.class.filesystem_error]]</a>
|
| 7886 |
+
|
| 7887 |
+
``` cpp
|
| 7888 |
+
namespace std::filesystem {
|
| 7889 |
+
class filesystem_error : public system_error {
|
| 7890 |
+
public:
|
| 7891 |
+
filesystem_error(const string& what_arg, error_code ec);
|
| 7892 |
+
filesystem_error(const string& what_arg,
|
| 7893 |
+
const path& p1, error_code ec);
|
| 7894 |
+
filesystem_error(const string& what_arg,
|
| 7895 |
+
const path& p1, const path& p2, error_code ec);
|
| 7896 |
+
|
| 7897 |
+
const path& path1() const noexcept;
|
| 7898 |
+
const path& path2() const noexcept;
|
| 7899 |
+
const char* what() const noexcept override;
|
| 7900 |
+
};
|
| 7901 |
+
}
|
| 7902 |
+
```
|
| 7903 |
+
|
| 7904 |
+
The class `filesystem_error` defines the type of objects thrown as
|
| 7905 |
+
exceptions to report file system errors from functions described in this
|
| 7906 |
+
subclause.
|
| 7907 |
+
|
| 7908 |
+
#### `filesystem_error` members <a id="filesystem_error.members">[[filesystem_error.members]]</a>
|
| 7909 |
+
|
| 7910 |
+
Constructors are provided that store zero, one, or two paths associated
|
| 7911 |
+
with an error.
|
| 7912 |
+
|
| 7913 |
+
``` cpp
|
| 7914 |
+
filesystem_error(const string& what_arg, error_code ec);
|
| 7915 |
+
```
|
| 7916 |
+
|
| 7917 |
+
*Postconditions:* The postconditions of this function are indicated in
|
| 7918 |
+
Table [[tab:filesystem_error.1]].
|
| 7919 |
+
|
| 7920 |
+
**Table: `filesystem_error(const string&, error_code)` effects** <a id="tab:filesystem_error.1">[tab:filesystem_error.1]</a>
|
| 7921 |
+
|
| 7922 |
+
| Expression | Value |
|
| 7923 |
+
| ----------------------- | ------------------ |
|
| 7924 |
+
| `runtime_error::what()` | `what_arg.c_str()` |
|
| 7925 |
+
| `code()` | `ec` |
|
| 7926 |
+
| `path1().empty()` | `true` |
|
| 7927 |
+
| `path2().empty()` | `true` |
|
| 7928 |
+
|
| 7929 |
+
``` cpp
|
| 7930 |
+
filesystem_error(const string& what_arg, const path& p1, error_code ec);
|
| 7931 |
+
```
|
| 7932 |
+
|
| 7933 |
+
*Postconditions:* The postconditions of this function are indicated in
|
| 7934 |
+
Table [[tab:filesystem_error.2]].
|
| 7935 |
+
|
| 7936 |
+
**Table: `filesystem_error(const string&, const path&, error_code)` effects** <a id="tab:filesystem_error.2">[tab:filesystem_error.2]</a>
|
| 7937 |
+
|
| 7938 |
+
| Expression | Value |
|
| 7939 |
+
| ----------------------- | -------------------------------- |
|
| 7940 |
+
| `runtime_error::what()` | `what_arg.c_str()` |
|
| 7941 |
+
| `code()` | `ec` |
|
| 7942 |
+
| `path1()` | Reference to stored copy of `p1` |
|
| 7943 |
+
| `path2().empty()` | `true` |
|
| 7944 |
+
|
| 7945 |
+
``` cpp
|
| 7946 |
+
filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);
|
| 7947 |
+
```
|
| 7948 |
+
|
| 7949 |
+
*Postconditions:* The postconditions of this function are indicated in
|
| 7950 |
+
Table [[tab:filesystem_error.3]].
|
| 7951 |
+
|
| 7952 |
+
**Table: `filesystem_error(const string&, const path&, const path&, error_code)` effects** <a id="tab:filesystem_error.3">[tab:filesystem_error.3]</a>
|
| 7953 |
+
|
| 7954 |
+
| Expression | Value |
|
| 7955 |
+
| ----------------------- | -------------------------------- |
|
| 7956 |
+
| `runtime_error::what()` | `what_arg.c_str()` |
|
| 7957 |
+
| `code()` | `ec` |
|
| 7958 |
+
| `path1()` | Reference to stored copy of `p1` |
|
| 7959 |
+
| `path2()` | Reference to stored copy of `p2` |
|
| 7960 |
+
|
| 7961 |
+
``` cpp
|
| 7962 |
+
const path& path1() const noexcept;
|
| 7963 |
+
```
|
| 7964 |
+
|
| 7965 |
+
*Returns:* A reference to the copy of `p1` stored by the constructor,
|
| 7966 |
+
or, if none, an empty path.
|
| 7967 |
+
|
| 7968 |
+
``` cpp
|
| 7969 |
+
const path& path2() const noexcept;
|
| 7970 |
+
```
|
| 7971 |
+
|
| 7972 |
+
*Returns:* A reference to the copy of `p2` stored by the constructor,
|
| 7973 |
+
or, if none, an empty path.
|
| 7974 |
+
|
| 7975 |
+
``` cpp
|
| 7976 |
+
const char* what() const noexcept override;
|
| 7977 |
+
```
|
| 7978 |
+
|
| 7979 |
+
*Returns:* A string containing `runtime_error::what()`. The exact format
|
| 7980 |
+
is unspecified. Implementations are encouraged but not required to
|
| 7981 |
+
include `path1.native_string()` if not empty, `path2.native_string()` if
|
| 7982 |
+
not empty, and `system_error::what()` strings in the returned string.
|
| 7983 |
+
|
| 7984 |
+
### Enumerations <a id="fs.enum">[[fs.enum]]</a>
|
| 7985 |
+
|
| 7986 |
+
#### Enum `path::format` <a id="fs.enum.path.format">[[fs.enum.path.format]]</a>
|
| 7987 |
+
|
| 7988 |
+
This enum specifies constants used to identify the format of the
|
| 7989 |
+
character sequence, with the meanings listed in Table
|
| 7990 |
+
[[tab:enum.path.format]].
|
| 7991 |
+
|
| 7992 |
+
[*Note 1*: For POSIX-based systems, native and generic formats are
|
| 7993 |
+
equivalent and the character sequence should always be interpreted in
|
| 7994 |
+
the same way. — *end note*]
|
| 7995 |
+
|
| 7996 |
+
#### Enum class `file_type` <a id="fs.enum.file_type">[[fs.enum.file_type]]</a>
|
| 7997 |
+
|
| 7998 |
+
This enum class specifies constants used to identify file types, with
|
| 7999 |
+
the meanings listed in Table [[tab:fs.enum.file_type]].
|
| 8000 |
+
|
| 8001 |
+
[*Note 1*: The file not being found is not considered an error while
|
| 8002 |
+
determining the type of a file. — *end note*]
|
| 8003 |
+
|
| 8004 |
+
#### Enum class `copy_options` <a id="fs.enum.copy.opts">[[fs.enum.copy.opts]]</a>
|
| 8005 |
+
|
| 8006 |
+
The `enum class` type `copy_options` is a bitmask type (
|
| 8007 |
+
[[bitmask.types]]) that specifies bitmask constants used to control the
|
| 8008 |
+
semantics of copy operations. The constants are specified in option
|
| 8009 |
+
groups with the meanings listed in Table [[tab:fs.enum.copy_options]].
|
| 8010 |
+
Constant `none` is shown in each option group for purposes of
|
| 8011 |
+
exposition; implementations shall provide only a single definition.
|
| 8012 |
+
|
| 8013 |
+
**Table: Enum class `copy_options`** <a id="tab:fs.enum.copy_options">[tab:fs.enum.copy_options]</a>
|
| 8014 |
+
|
| 8015 |
+
| Constant | Meaning |
|
| 8016 |
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 8017 |
+
| `none` | (Default) Error; file already exists. |
|
| 8018 |
+
| `skip_existing` | Do not overwrite existing file, do not report an error. |
|
| 8019 |
+
| `overwrite_existing` | Overwrite the existing file. |
|
| 8020 |
+
| `update_existing` | Overwrite the existing file if it is older than the replacement file. \ohdrx{2}{Option group controlling `copy` function effects for sub-directories} |
|
| 8021 |
+
| `recursive` | Recursively copy sub-directories and their contents. \ohdrx{2}{Option group controlling `copy` function effects for symbolic links} |
|
| 8022 |
+
| `copy_symlinks` | Copy symbolic links as symbolic links rather than copying the files that they point to. |
|
| 8023 |
+
| `skip_symlinks` | Ignore symbolic links. \ohdrx{2}{Option group controlling `copy` function effects for choosing the form of copying} |
|
| 8024 |
+
| `directories_only` | Copy directory structure only, do not copy non-directory files. |
|
| 8025 |
+
| `create_symlinks` | Make symbolic links instead of copies of files. The source path shall be an absolute path unless the destination path is in the current directory. |
|
| 8026 |
+
| `create_hard_links` | Make hard links instead of copies of files. |
|
| 8027 |
+
|
| 8028 |
+
|
| 8029 |
+
#### Enum class `perms` <a id="fs.enum.perms">[[fs.enum.perms]]</a>
|
| 8030 |
+
|
| 8031 |
+
The `enum class` type `perms` is a bitmask type ([[bitmask.types]])
|
| 8032 |
+
that specifies bitmask constants used to identify file permissions, with
|
| 8033 |
+
the meanings listed in Table [[tab:fs.enum.perms]].
|
| 8034 |
+
|
| 8035 |
+
**Table: Enum class `perms`** <a id="tab:fs.enum.perms">[tab:fs.enum.perms]</a>
|
| 8036 |
+
|
| 8037 |
+
| Name | Value (octal) | POSIX macro | Definition or notes |
|
| 8038 |
+
| -------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
|
| 8039 |
+
| `none` | `0` | | There are no permissions set for the file. |
|
| 8040 |
+
| `owner_read` | `0400` | `S_IRUSR` | Read permission, owner |
|
| 8041 |
+
| `owner_write` | `0200` | `S_IWUSR` | Write permission, owner |
|
| 8042 |
+
| `owner_exec` | `0100` | `S_IXUSR` | Execute/search permission, owner |
|
| 8043 |
+
| `owner_all` | `0700` | `S_IRWXU` | Read, write, execute/search by owner;<br> `owner_read | owner_write | owner_exec` |
|
| 8044 |
+
| `group_read` | `040` | `S_IRGRP` | Read permission, group |
|
| 8045 |
+
| `group_write` | `020` | `S_IWGRP` | Write permission, group |
|
| 8046 |
+
| `group_exec` | `010` | `S_IXGRP` | Execute/search permission, group |
|
| 8047 |
+
| `group_all` | `070` | `S_IRWXG` | Read, write, execute/search by group;<br> `group_read | group_write | group_exec` |
|
| 8048 |
+
| `others_read` | `04` | `S_IROTH` | Read permission, others |
|
| 8049 |
+
| `others_write` | `02` | `S_IWOTH` | Write permission, others |
|
| 8050 |
+
| `others_exec` | `01` | `S_IXOTH` | Execute/search permission, others |
|
| 8051 |
+
| `others_all` | `07` | `S_IRWXO` | Read, write, execute/search by others;<br> `others_read | others_write | others_exec` |
|
| 8052 |
+
| `all` | `0777` | | `owner_all | group_all | others_all` |
|
| 8053 |
+
| `set_uid` | `04000` | `S_ISUID` | Set-user-ID on execution |
|
| 8054 |
+
| `set_gid` | `02000` | `S_ISGID` | Set-group-ID on execution |
|
| 8055 |
+
| `sticky_bit` | `01000` | `S_ISVTX` | Operating system dependent. |
|
| 8056 |
+
| `mask` | `07777` | | `all | set_uid | set_gid | sticky_bit` |
|
| 8057 |
+
| `unknown` | `0xFFFF` | | The permissions are not known, such as when a `file_status` object is created without specifying the permissions |
|
| 8058 |
+
|
| 8059 |
+
|
| 8060 |
+
#### Enum class `perm_options` <a id="fs.enum.perm.opts">[[fs.enum.perm.opts]]</a>
|
| 8061 |
+
|
| 8062 |
+
The `enum class` type `perm_options` is a bitmask type (
|
| 8063 |
+
[[bitmask.types]]) that specifies bitmask constants used to control the
|
| 8064 |
+
semantics of permissions operations, with the meanings listed in Table
|
| 8065 |
+
[[tab:enum.perm_options]]. The bitmask constants are bitmask elements.
|
| 8066 |
+
In Table [[tab:enum.perm_options]] `perm` denotes a value of type
|
| 8067 |
+
`perms` passed to `permissions`.
|
| 8068 |
+
|
| 8069 |
+
**Table: Enum class `perm_options`** <a id="tab:enum.perm_options">[tab:enum.perm_options]</a>
|
| 8070 |
+
|
| 8071 |
+
| Name | Meaning |
|
| 8072 |
+
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 8073 |
+
| `replace` | `permissions` shall replace the file's permission bits with `perm` |
|
| 8074 |
+
| `add` | `permissions` shall replace the file's permission bits with the bitwise OR of `perm` and the file's current permission bits. |
|
| 8075 |
+
| `remove` | `permissions` shall replace the file's permission bits with the bitwise AND of the complement of `perm` and the file's current permission bits. |
|
| 8076 |
+
| `nofollow` | `permissions` shall change the permissions of a symbolic link itself rather than the permissions of the file the link resolves to. |
|
| 8077 |
+
|
| 8078 |
+
|
| 8079 |
+
#### Enum class `directory_options` <a id="fs.enum.dir.opts">[[fs.enum.dir.opts]]</a>
|
| 8080 |
+
|
| 8081 |
+
The `enum class` type `directory_options` is a bitmask type (
|
| 8082 |
+
[[bitmask.types]]) that specifies bitmask constants used to identify
|
| 8083 |
+
directory traversal options, with the meanings listed in Table
|
| 8084 |
+
[[tab:fs.enum.directory_options]].
|
| 8085 |
+
|
| 8086 |
+
**Table: Enum class `directory_options`** <a id="tab:fs.enum.directory_options">[tab:fs.enum.directory_options]</a>
|
| 8087 |
+
|
| 8088 |
+
| Name | Meaning |
|
| 8089 |
+
| -------------------------- | ------------------------------------------------------------------ |
|
| 8090 |
+
| `none` | (Default) Skip directory symlinks, permission denied is an error. |
|
| 8091 |
+
| `follow_directory_symlink` | Follow rather than skip directory symlinks. |
|
| 8092 |
+
| `skip_permission_denied` | Skip directories that would otherwise result in permission denied. |
|
| 8093 |
+
|
| 8094 |
+
|
| 8095 |
+
### Class `file_status` <a id="fs.class.file_status">[[fs.class.file_status]]</a>
|
| 8096 |
+
|
| 8097 |
+
``` cpp
|
| 8098 |
+
namespace std::filesystem {
|
| 8099 |
+
class file_status {
|
| 8100 |
+
public:
|
| 8101 |
+
// [fs.file_status.cons], constructors and destructor
|
| 8102 |
+
file_status() noexcept : file_status(file_type::none) {}
|
| 8103 |
+
explicit file_status(file_type ft,
|
| 8104 |
+
perms prms = perms::unknown) noexcept;
|
| 8105 |
+
file_status(const file_status&) noexcept = default;
|
| 8106 |
+
file_status(file_status&&) noexcept = default;
|
| 8107 |
+
~file_status();
|
| 8108 |
+
|
| 8109 |
+
// assignments:
|
| 8110 |
+
file_status& operator=(const file_status&) noexcept = default;
|
| 8111 |
+
file_status& operator=(file_status&&) noexcept = default;
|
| 8112 |
+
|
| 8113 |
+
// [fs.file_status.mods], modifiers
|
| 8114 |
+
void type(file_type ft) noexcept;
|
| 8115 |
+
void permissions(perms prms) noexcept;
|
| 8116 |
+
|
| 8117 |
+
// [fs.file_status.obs], observers
|
| 8118 |
+
file_type type() const noexcept;
|
| 8119 |
+
perms permissions() const noexcept;
|
| 8120 |
+
};
|
| 8121 |
+
}
|
| 8122 |
+
```
|
| 8123 |
+
|
| 8124 |
+
#### `file_status` constructors <a id="fs.file_status.cons">[[fs.file_status.cons]]</a>
|
| 8125 |
+
|
| 8126 |
+
``` cpp
|
| 8127 |
+
explicit file_status(file_type ft, perms prms = perms::unknown) noexcept;
|
| 8128 |
+
```
|
| 8129 |
+
|
| 8130 |
+
*Postconditions:* `type() == ft` and `permissions() == prms`.
|
| 8131 |
+
|
| 8132 |
+
#### `file_status` observers <a id="fs.file_status.obs">[[fs.file_status.obs]]</a>
|
| 8133 |
+
|
| 8134 |
+
``` cpp
|
| 8135 |
+
file_type type() const noexcept;
|
| 8136 |
+
```
|
| 8137 |
+
|
| 8138 |
+
*Returns:* The value of `type()` specified by the postconditions of the
|
| 8139 |
+
most recent call to a constructor, `operator=`, or `type(file_type)`
|
| 8140 |
+
function.
|
| 8141 |
+
|
| 8142 |
+
``` cpp
|
| 8143 |
+
perms permissions() const noexcept;
|
| 8144 |
+
```
|
| 8145 |
+
|
| 8146 |
+
*Returns:* The value of `permissions()` specified by the postconditions
|
| 8147 |
+
of the most recent call to a constructor, `operator=`, or
|
| 8148 |
+
`permissions(perms)` function.
|
| 8149 |
+
|
| 8150 |
+
#### `file_status` modifiers <a id="fs.file_status.mods">[[fs.file_status.mods]]</a>
|
| 8151 |
+
|
| 8152 |
+
``` cpp
|
| 8153 |
+
void type(file_type ft) noexcept;
|
| 8154 |
+
```
|
| 8155 |
+
|
| 8156 |
+
*Postconditions:* `type() == ft`.
|
| 8157 |
+
|
| 8158 |
+
``` cpp
|
| 8159 |
+
void permissions(perms prms) noexcept;
|
| 8160 |
+
```
|
| 8161 |
+
|
| 8162 |
+
*Postconditions:* `permissions() == prms`.
|
| 8163 |
+
|
| 8164 |
+
### Class `directory_entry` <a id="fs.class.directory_entry">[[fs.class.directory_entry]]</a>
|
| 8165 |
+
|
| 8166 |
+
``` cpp
|
| 8167 |
+
namespace std::filesystem {
|
| 8168 |
+
class directory_entry {
|
| 8169 |
+
public:
|
| 8170 |
+
// [fs.dir.entry.cons], constructors and destructor
|
| 8171 |
+
directory_entry() noexcept = default;
|
| 8172 |
+
directory_entry(const directory_entry&) = default;
|
| 8173 |
+
directory_entry(directory_entry&&) noexcept = default;
|
| 8174 |
+
explicit directory_entry(const path& p);
|
| 8175 |
+
directory_entry(const path& p, error_code& ec);
|
| 8176 |
+
~directory_entry();
|
| 8177 |
+
|
| 8178 |
+
// assignments:
|
| 8179 |
+
directory_entry& operator=(const directory_entry&) = default;
|
| 8180 |
+
directory_entry& operator=(directory_entry&&) noexcept = default;
|
| 8181 |
+
|
| 8182 |
+
// [fs.dir.entry.mods], modifiers
|
| 8183 |
+
void assign(const path& p);
|
| 8184 |
+
void assign(const path& p, error_code& ec);
|
| 8185 |
+
void replace_filename(const path& p);
|
| 8186 |
+
void replace_filename(const path& p, error_code& ec);
|
| 8187 |
+
void refresh();
|
| 8188 |
+
void refresh(error_code& ec) noexcept;
|
| 8189 |
+
|
| 8190 |
+
// [fs.dir.entry.obs], observers
|
| 8191 |
+
const path& path() const noexcept;
|
| 8192 |
+
operator const path&() const noexcept;
|
| 8193 |
+
bool exists() const;
|
| 8194 |
+
bool exists(error_code& ec) const noexcept;
|
| 8195 |
+
bool is_block_file() const;
|
| 8196 |
+
bool is_block_file(error_code& ec) const noexcept;
|
| 8197 |
+
bool is_character_file() const;
|
| 8198 |
+
bool is_character_file(error_code& ec) const noexcept;
|
| 8199 |
+
bool is_directory() const;
|
| 8200 |
+
bool is_directory(error_code& ec) const noexcept;
|
| 8201 |
+
bool is_fifo() const;
|
| 8202 |
+
bool is_fifo(error_code& ec) const noexcept;
|
| 8203 |
+
bool is_other() const;
|
| 8204 |
+
bool is_other(error_code& ec) const noexcept;
|
| 8205 |
+
bool is_regular_file() const;
|
| 8206 |
+
bool is_regular_file(error_code& ec) const noexcept;
|
| 8207 |
+
bool is_socket() const;
|
| 8208 |
+
bool is_socket(error_code& ec) const noexcept;
|
| 8209 |
+
bool is_symlink() const;
|
| 8210 |
+
bool is_symlink(error_code& ec) const noexcept;
|
| 8211 |
+
uintmax_t file_size() const;
|
| 8212 |
+
uintmax_t file_size(error_code& ec) const noexcept;
|
| 8213 |
+
uintmax_t hard_link_count() const;
|
| 8214 |
+
uintmax_t hard_link_count(error_code& ec) const noexcept;
|
| 8215 |
+
file_time_type last_write_time() const;
|
| 8216 |
+
file_time_type last_write_time(error_code& ec) const noexcept;
|
| 8217 |
+
file_status status() const;
|
| 8218 |
+
file_status status(error_code& ec) const noexcept;
|
| 8219 |
+
file_status symlink_status() const;
|
| 8220 |
+
file_status symlink_status(error_code& ec) const noexcept;
|
| 8221 |
+
|
| 8222 |
+
bool operator< (const directory_entry& rhs) const noexcept;
|
| 8223 |
+
bool operator==(const directory_entry& rhs) const noexcept;
|
| 8224 |
+
bool operator!=(const directory_entry& rhs) const noexcept;
|
| 8225 |
+
bool operator<=(const directory_entry& rhs) const noexcept;
|
| 8226 |
+
bool operator> (const directory_entry& rhs) const noexcept;
|
| 8227 |
+
bool operator>=(const directory_entry& rhs) const noexcept;
|
| 8228 |
+
|
| 8229 |
+
private:
|
| 8230 |
+
path pathobject; // exposition only
|
| 8231 |
+
friend class directory_iterator; // exposition only
|
| 8232 |
+
};
|
| 8233 |
+
}
|
| 8234 |
+
```
|
| 8235 |
+
|
| 8236 |
+
A `directory_entry` object stores a `path` object and may store
|
| 8237 |
+
additional objects for file attributes such as hard link count, status,
|
| 8238 |
+
symlink status, file size, and last write time.
|
| 8239 |
+
|
| 8240 |
+
Implementations are encouraged to store such additional file attributes
|
| 8241 |
+
during directory iteration if their values are available and storing the
|
| 8242 |
+
values would allow the implementation to eliminate file system accesses
|
| 8243 |
+
by `directory_entry` observer functions ([[fs.op.funcs]]). Such stored
|
| 8244 |
+
file attribute values are said to be *cached*.
|
| 8245 |
+
|
| 8246 |
+
[*Note 1*: For purposes of exposition, class `directory_iterator` (
|
| 8247 |
+
[[fs.class.directory_iterator]]) is shown above as a friend of class
|
| 8248 |
+
`directory_entry`. Friendship allows the `directory_iterator`
|
| 8249 |
+
implementation to cache already available attribute values directly into
|
| 8250 |
+
a `directory_entry` object without the cost of an unneeded call to
|
| 8251 |
+
`refresh()`. — *end note*]
|
| 8252 |
+
|
| 8253 |
+
[*Example 1*:
|
| 8254 |
+
|
| 8255 |
+
``` cpp
|
| 8256 |
+
using namespace std::filesystem;
|
| 8257 |
+
|
| 8258 |
+
// use possibly cached last write time to minimize disk accesses
|
| 8259 |
+
for (auto&& x : directory_iterator("."))
|
| 8260 |
+
{
|
| 8261 |
+
std::cout << x.path() << " " << x.last_write_time() << std::endl;
|
| 8262 |
+
}
|
| 8263 |
+
|
| 8264 |
+
// call refresh() to refresh a stale cache
|
| 8265 |
+
for (auto&& x : directory_iterator("."))
|
| 8266 |
+
{
|
| 8267 |
+
lengthy_function(x.path()); // cache becomes stale
|
| 8268 |
+
x.refresh();
|
| 8269 |
+
std::cout << x.path() << " " << x.last_write_time() << std::endl;
|
| 8270 |
+
}
|
| 8271 |
+
```
|
| 8272 |
+
|
| 8273 |
+
On implementations that do not cache the last write time, both loops
|
| 8274 |
+
will result in a potentially expensive call to the
|
| 8275 |
+
`std::filesystem::last_write_time` function. On implementations that do
|
| 8276 |
+
cache the last write time, the first loop will use the cached value and
|
| 8277 |
+
so will not result in a potentially expensive call to the
|
| 8278 |
+
`std::filesystem::last_write_time` function. The code is portable to any
|
| 8279 |
+
implementation, regardless of whether or not it employs caching.
|
| 8280 |
+
|
| 8281 |
+
— *end example*]
|
| 8282 |
+
|
| 8283 |
+
#### `directory_entry` constructors <a id="fs.dir.entry.cons">[[fs.dir.entry.cons]]</a>
|
| 8284 |
+
|
| 8285 |
+
``` cpp
|
| 8286 |
+
explicit directory_entry(const path& p);
|
| 8287 |
+
directory_entry(const path& p, error_code& ec);
|
| 8288 |
+
```
|
| 8289 |
+
|
| 8290 |
+
*Effects:* Constructs an object of type `directory_entry`, then
|
| 8291 |
+
`refresh()` or `refresh(ec)`, respectively.
|
| 8292 |
+
|
| 8293 |
+
*Postconditions:* `path() == p` if no error occurs, otherwise
|
| 8294 |
+
`path() == std::filesystem::path()`.
|
| 8295 |
+
|
| 8296 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8297 |
+
|
| 8298 |
+
#### `directory_entry` modifiers <a id="fs.dir.entry.mods">[[fs.dir.entry.mods]]</a>
|
| 8299 |
+
|
| 8300 |
+
``` cpp
|
| 8301 |
+
void assign(const path& p);
|
| 8302 |
+
void assign(const path& p, error_code& ec);
|
| 8303 |
+
```
|
| 8304 |
+
|
| 8305 |
+
*Effects:* Equivalent to `pathobject = p`, then `refresh()` or
|
| 8306 |
+
`refresh(ec)`, respectively. If an error occurs, the values of any
|
| 8307 |
+
cached attributes are unspecified.
|
| 8308 |
+
|
| 8309 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8310 |
+
|
| 8311 |
+
``` cpp
|
| 8312 |
+
void replace_filename(const path& p);
|
| 8313 |
+
void replace_filename(const path& p, error_code& ec);
|
| 8314 |
+
```
|
| 8315 |
+
|
| 8316 |
+
*Effects:* Equivalent to `pathobject.replace_filename(p)`, then
|
| 8317 |
+
`refresh()` or `refresh(ec)`, respectively. If an error occurs, the
|
| 8318 |
+
values of any cached attributes are unspecified.
|
| 8319 |
+
|
| 8320 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8321 |
+
|
| 8322 |
+
``` cpp
|
| 8323 |
+
void refresh();
|
| 8324 |
+
void refresh(error_code& ec) noexcept;
|
| 8325 |
+
```
|
| 8326 |
+
|
| 8327 |
+
*Effects:* Stores the current values of any cached attributes of the
|
| 8328 |
+
file `p` resolves to. If an error occurs, an error is
|
| 8329 |
+
reported ([[fs.err.report]]) and the values of any cached attributes
|
| 8330 |
+
are unspecified.
|
| 8331 |
+
|
| 8332 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8333 |
+
|
| 8334 |
+
[*Note 1*: Implementations of
|
| 8335 |
+
`directory_iterator` ([[fs.class.directory_iterator]]) are prohibited
|
| 8336 |
+
from directly or indirectly calling the `refresh` function since it must
|
| 8337 |
+
access the external file system, and the objective of caching is to
|
| 8338 |
+
avoid unnecessary file system accesses. — *end note*]
|
| 8339 |
+
|
| 8340 |
+
#### `directory_entry` observers <a id="fs.dir.entry.obs">[[fs.dir.entry.obs]]</a>
|
| 8341 |
+
|
| 8342 |
+
Unqualified function names in the *Returns:* elements of the
|
| 8343 |
+
`directory_entry` observers described below refer to members of the
|
| 8344 |
+
`std::filesystem` namespace.
|
| 8345 |
+
|
| 8346 |
+
``` cpp
|
| 8347 |
+
const path& path() const noexcept;
|
| 8348 |
+
operator const path&() const noexcept;
|
| 8349 |
+
```
|
| 8350 |
+
|
| 8351 |
+
*Returns:* `pathobject`.
|
| 8352 |
+
|
| 8353 |
+
``` cpp
|
| 8354 |
+
bool exists() const;
|
| 8355 |
+
bool exists(error_code& ec) const noexcept;
|
| 8356 |
+
```
|
| 8357 |
+
|
| 8358 |
+
*Returns:* `exists(this->status())` or `exists(this->status(), ec)`,
|
| 8359 |
+
respectively.
|
| 8360 |
+
|
| 8361 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8362 |
+
|
| 8363 |
+
``` cpp
|
| 8364 |
+
bool is_block_file() const;
|
| 8365 |
+
bool is_block_file(error_code& ec) const noexcept;
|
| 8366 |
+
```
|
| 8367 |
+
|
| 8368 |
+
*Returns:* `is_block_file(this->status())` or
|
| 8369 |
+
`is_block_file(this->status(), ec)`, respectively.
|
| 8370 |
+
|
| 8371 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8372 |
+
|
| 8373 |
+
``` cpp
|
| 8374 |
+
bool is_character_file() const;
|
| 8375 |
+
bool is_character_file(error_code& ec) const noexcept;
|
| 8376 |
+
```
|
| 8377 |
+
|
| 8378 |
+
*Returns:* `is_character_file(this->status())` or
|
| 8379 |
+
`is_character_file(this->status(), ec)`, respectively.
|
| 8380 |
+
|
| 8381 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8382 |
+
|
| 8383 |
+
``` cpp
|
| 8384 |
+
bool is_directory() const;
|
| 8385 |
+
bool is_directory(error_code& ec) const noexcept;
|
| 8386 |
+
```
|
| 8387 |
+
|
| 8388 |
+
*Returns:* `is_directory(this->status())` or
|
| 8389 |
+
`is_directory(this->status(), ec)`, respectively.
|
| 8390 |
+
|
| 8391 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8392 |
+
|
| 8393 |
+
``` cpp
|
| 8394 |
+
bool is_fifo() const;
|
| 8395 |
+
bool is_fifo(error_code& ec) const noexcept;
|
| 8396 |
+
```
|
| 8397 |
+
|
| 8398 |
+
*Returns:* `is_fifo(this->status())` or `is_fifo(this->status(), ec)`,
|
| 8399 |
+
respectively.
|
| 8400 |
+
|
| 8401 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8402 |
+
|
| 8403 |
+
``` cpp
|
| 8404 |
+
bool is_other() const;
|
| 8405 |
+
bool is_other(error_code& ec) const noexcept;
|
| 8406 |
+
```
|
| 8407 |
+
|
| 8408 |
+
*Returns:* `is_other(this->status())` or `is_other(this->status(), ec)`,
|
| 8409 |
+
respectively.
|
| 8410 |
+
|
| 8411 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8412 |
+
|
| 8413 |
+
``` cpp
|
| 8414 |
+
bool is_regular_file() const;
|
| 8415 |
+
bool is_regular_file(error_code& ec) const noexcept;
|
| 8416 |
+
```
|
| 8417 |
+
|
| 8418 |
+
*Returns:* `is_regular_file(this->status())` or
|
| 8419 |
+
`is_regular_file(this->status(), ec)`, respectively.
|
| 8420 |
+
|
| 8421 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8422 |
+
|
| 8423 |
+
``` cpp
|
| 8424 |
+
bool is_socket() const;
|
| 8425 |
+
bool is_socket(error_code& ec) const noexcept;
|
| 8426 |
+
```
|
| 8427 |
+
|
| 8428 |
+
*Returns:* `is_socket(this->status())` or
|
| 8429 |
+
`is_socket(this->status(), ec)`, respectively.
|
| 8430 |
+
|
| 8431 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8432 |
+
|
| 8433 |
+
``` cpp
|
| 8434 |
+
bool is_symlink() const;
|
| 8435 |
+
bool is_symlink(error_code& ec) const noexcept;
|
| 8436 |
+
```
|
| 8437 |
+
|
| 8438 |
+
*Returns:* `is_symlink(this->symlink_status())` or
|
| 8439 |
+
`is_symlink(this->symlink_status(), ec)`, respectively.
|
| 8440 |
+
|
| 8441 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8442 |
+
|
| 8443 |
+
``` cpp
|
| 8444 |
+
uintmax_t file_size() const;
|
| 8445 |
+
uintmax_t file_size(error_code& ec) const noexcept;
|
| 8446 |
+
```
|
| 8447 |
+
|
| 8448 |
+
*Returns:* If cached, the file size attribute value. Otherwise,
|
| 8449 |
+
`file_size(path())` or `file_size(path(), ec)`, respectively.
|
| 8450 |
+
|
| 8451 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8452 |
+
|
| 8453 |
+
``` cpp
|
| 8454 |
+
uintmax_t hard_link_count() const;
|
| 8455 |
+
uintmax_t hard_link_count(error_code& ec) const noexcept;
|
| 8456 |
+
```
|
| 8457 |
+
|
| 8458 |
+
*Returns:* If cached, the hard link count attribute value. Otherwise,
|
| 8459 |
+
`hard_link_count(path())` or `hard_link_count(path(), ec)`,
|
| 8460 |
+
respectively.
|
| 8461 |
+
|
| 8462 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8463 |
+
|
| 8464 |
+
``` cpp
|
| 8465 |
+
file_time_type last_write_time() const;
|
| 8466 |
+
file_time_type last_write_time(error_code& ec) const noexcept;
|
| 8467 |
+
```
|
| 8468 |
+
|
| 8469 |
+
*Returns:* If cached, the last write time attribute value. Otherwise,
|
| 8470 |
+
`last_write_time(path())` or `last_write_time(path(), ec)`,
|
| 8471 |
+
respectively.
|
| 8472 |
+
|
| 8473 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8474 |
+
|
| 8475 |
+
``` cpp
|
| 8476 |
+
file_status status() const;
|
| 8477 |
+
file_status status(error_code& ec) const noexcept;
|
| 8478 |
+
```
|
| 8479 |
+
|
| 8480 |
+
*Returns:* If cached, the status attribute value. Otherwise,
|
| 8481 |
+
`status(path())` or `status(path(), ec)`, respectively.
|
| 8482 |
+
|
| 8483 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8484 |
+
|
| 8485 |
+
``` cpp
|
| 8486 |
+
file_status symlink_status() const;
|
| 8487 |
+
file_status symlink_status(error_code& ec) const noexcept;
|
| 8488 |
+
```
|
| 8489 |
+
|
| 8490 |
+
*Returns:* If cached, the symlink status attribute value. Otherwise,
|
| 8491 |
+
`symlink_status(path())` or `symlink_status(path(), ec)`, respectively.
|
| 8492 |
+
|
| 8493 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8494 |
+
|
| 8495 |
+
``` cpp
|
| 8496 |
+
bool operator==(const directory_entry& rhs) const noexcept;
|
| 8497 |
+
```
|
| 8498 |
+
|
| 8499 |
+
*Returns:* `pathobject == rhs.pathobject`.
|
| 8500 |
+
|
| 8501 |
+
``` cpp
|
| 8502 |
+
bool operator!=(const directory_entry& rhs) const noexcept;
|
| 8503 |
+
```
|
| 8504 |
+
|
| 8505 |
+
*Returns:* `pathobject != rhs.pathobject`.
|
| 8506 |
+
|
| 8507 |
+
``` cpp
|
| 8508 |
+
bool operator< (const directory_entry& rhs) const noexcept;
|
| 8509 |
+
```
|
| 8510 |
+
|
| 8511 |
+
*Returns:* `pathobject < rhs.pathobject`.
|
| 8512 |
+
|
| 8513 |
+
``` cpp
|
| 8514 |
+
bool operator<=(const directory_entry& rhs) const noexcept;
|
| 8515 |
+
```
|
| 8516 |
+
|
| 8517 |
+
*Returns:* `pathobject <= rhs.pathobject`.
|
| 8518 |
+
|
| 8519 |
+
``` cpp
|
| 8520 |
+
bool operator> (const directory_entry& rhs) const noexcept;
|
| 8521 |
+
```
|
| 8522 |
+
|
| 8523 |
+
*Returns:* `pathobject > rhs.pathobject`.
|
| 8524 |
+
|
| 8525 |
+
``` cpp
|
| 8526 |
+
bool operator>=(const directory_entry& rhs) const noexcept;
|
| 8527 |
+
```
|
| 8528 |
+
|
| 8529 |
+
*Returns:* `pathobject >= rhs.pathobject`.
|
| 8530 |
+
|
| 8531 |
+
### Class `directory_iterator` <a id="fs.class.directory_iterator">[[fs.class.directory_iterator]]</a>
|
| 8532 |
+
|
| 8533 |
+
An object of type `directory_iterator` provides an iterator for a
|
| 8534 |
+
sequence of `directory_entry` elements representing the path and any
|
| 8535 |
+
cached attribute values ([[fs.class.directory_entry]]) for each file in
|
| 8536 |
+
a directory or in an *implementation-defined* directory-like file type.
|
| 8537 |
+
|
| 8538 |
+
[*Note 1*: For iteration into sub-directories, see class
|
| 8539 |
+
`recursive_directory_iterator` (
|
| 8540 |
+
[[fs.class.rec.dir.itr]]). — *end note*]
|
| 8541 |
+
|
| 8542 |
+
``` cpp
|
| 8543 |
+
namespace std::filesystem {
|
| 8544 |
+
class directory_iterator {
|
| 8545 |
+
public:
|
| 8546 |
+
using iterator_category = input_iterator_tag;
|
| 8547 |
+
using value_type = directory_entry;
|
| 8548 |
+
using difference_type = ptrdiff_t;
|
| 8549 |
+
using pointer = const directory_entry*;
|
| 8550 |
+
using reference = const directory_entry&;
|
| 8551 |
+
|
| 8552 |
+
// [fs.dir.itr.members], member functions
|
| 8553 |
+
directory_iterator() noexcept;
|
| 8554 |
+
explicit directory_iterator(const path& p);
|
| 8555 |
+
directory_iterator(const path& p, directory_options options);
|
| 8556 |
+
directory_iterator(const path& p, error_code& ec) noexcept;
|
| 8557 |
+
directory_iterator(const path& p, directory_options options,
|
| 8558 |
+
error_code& ec) noexcept;
|
| 8559 |
+
directory_iterator(const directory_iterator& rhs);
|
| 8560 |
+
directory_iterator(directory_iterator&& rhs) noexcept;
|
| 8561 |
+
~directory_iterator();
|
| 8562 |
+
|
| 8563 |
+
directory_iterator& operator=(const directory_iterator& rhs);
|
| 8564 |
+
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
|
| 8565 |
+
|
| 8566 |
+
const directory_entry& operator*() const;
|
| 8567 |
+
const directory_entry* operator->() const;
|
| 8568 |
+
directory_iterator& operator++();
|
| 8569 |
+
directory_iterator& increment(error_code& ec) noexcept;
|
| 8570 |
+
|
| 8571 |
+
// other members as required by [input.iterators], input iterators
|
| 8572 |
+
};
|
| 8573 |
+
}
|
| 8574 |
+
```
|
| 8575 |
+
|
| 8576 |
+
`directory_iterator` satisfies the requirements of an input iterator (
|
| 8577 |
+
[[input.iterators]]).
|
| 8578 |
+
|
| 8579 |
+
If an iterator of type `directory_iterator` reports an error or is
|
| 8580 |
+
advanced past the last directory element, that iterator shall become
|
| 8581 |
+
equal to the end iterator value. The `directory_iterator` default
|
| 8582 |
+
constructor shall create an iterator equal to the end iterator value,
|
| 8583 |
+
and this shall be the only valid iterator for the end condition.
|
| 8584 |
+
|
| 8585 |
+
The end iterator is not dereferenceable.
|
| 8586 |
+
|
| 8587 |
+
Two end iterators are always equal. An end iterator shall not be equal
|
| 8588 |
+
to a non-end iterator.
|
| 8589 |
+
|
| 8590 |
+
The result of calling the `path()` member of the `directory_entry`
|
| 8591 |
+
object obtained by dereferencing a `directory_iterator` is a reference
|
| 8592 |
+
to a `path` object composed of the directory argument from which the
|
| 8593 |
+
iterator was constructed with filename of the directory entry appended
|
| 8594 |
+
as if by `operator/=`.
|
| 8595 |
+
|
| 8596 |
+
Directory iteration shall not yield directory entries for the current
|
| 8597 |
+
(*dot*) and parent (*dot-dot*) directories.
|
| 8598 |
+
|
| 8599 |
+
The order of directory entries obtained by dereferencing successive
|
| 8600 |
+
increments of a `directory_iterator` is unspecified.
|
| 8601 |
+
|
| 8602 |
+
Constructors and non-const `directory_iterator` member functions store
|
| 8603 |
+
the values of any cached attributes ([[fs.class.directory_entry]]) in
|
| 8604 |
+
the `directory_entry` element returned by `operator*()`.
|
| 8605 |
+
`directory_iterator` member functions shall not directly or indirectly
|
| 8606 |
+
call any `directory_entry` `refresh` function.
|
| 8607 |
+
|
| 8608 |
+
[*Note 2*: The exact mechanism for storing cached attribute values is
|
| 8609 |
+
not exposed to users. For exposition, class `directory_iterator` is
|
| 8610 |
+
shown in [[fs.class.directory_entry]] as a friend of class
|
| 8611 |
+
`directory_entry`. — *end note*]
|
| 8612 |
+
|
| 8613 |
+
[*Note 3*: Programs performing directory iteration may wish to test if
|
| 8614 |
+
the path obtained by dereferencing a directory iterator actually exists.
|
| 8615 |
+
It could be a symbolic link to a non-existent file. Programs recursively
|
| 8616 |
+
walking directory trees for purposes of removing and renaming entries
|
| 8617 |
+
may wish to avoid following symbolic links. — *end note*]
|
| 8618 |
+
|
| 8619 |
+
[*Note 4*: If a file is removed from or added to a directory after the
|
| 8620 |
+
construction of a `directory_iterator` for the directory, it is
|
| 8621 |
+
unspecified whether or not subsequently incrementing the iterator will
|
| 8622 |
+
ever result in an iterator referencing the removed or added directory
|
| 8623 |
+
entry. See POSIX `readdir_r`. — *end note*]
|
| 8624 |
+
|
| 8625 |
+
#### `directory_iterator` members <a id="fs.dir.itr.members">[[fs.dir.itr.members]]</a>
|
| 8626 |
+
|
| 8627 |
+
``` cpp
|
| 8628 |
+
directory_iterator() noexcept;
|
| 8629 |
+
```
|
| 8630 |
+
|
| 8631 |
+
*Effects:* Constructs the end iterator.
|
| 8632 |
+
|
| 8633 |
+
``` cpp
|
| 8634 |
+
explicit directory_iterator(const path& p);
|
| 8635 |
+
directory_iterator(const path& p, directory_options options);
|
| 8636 |
+
directory_iterator(const path& p, error_code& ec) noexcept;
|
| 8637 |
+
directory_iterator(const path& p, directory_options options, error_code& ec) noexcept;
|
| 8638 |
+
```
|
| 8639 |
+
|
| 8640 |
+
*Effects:* For the directory that `p` resolves to, constructs an
|
| 8641 |
+
iterator for the first element in a sequence of `directory_entry`
|
| 8642 |
+
elements representing the files in the directory, if any; otherwise the
|
| 8643 |
+
end iterator. However, if
|
| 8644 |
+
|
| 8645 |
+
``` cpp
|
| 8646 |
+
(options & directory_options::skip_permission_denied) != directory_options::none
|
| 8647 |
+
```
|
| 8648 |
+
|
| 8649 |
+
and construction encounters an error indicating that permission to
|
| 8650 |
+
access `p` is denied, constructs the end iterator and does not report an
|
| 8651 |
+
error.
|
| 8652 |
+
|
| 8653 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8654 |
+
|
| 8655 |
+
[*Note 1*: To iterate over the current directory, use
|
| 8656 |
+
`directory_iterator(".")` rather than
|
| 8657 |
+
`directory_iterator("")`. — *end note*]
|
| 8658 |
+
|
| 8659 |
+
``` cpp
|
| 8660 |
+
directory_iterator(const directory_iterator& rhs);
|
| 8661 |
+
directory_iterator(directory_iterator&& rhs) noexcept;
|
| 8662 |
+
```
|
| 8663 |
+
|
| 8664 |
+
*Effects:* Constructs an object of class `directory_iterator`.
|
| 8665 |
+
|
| 8666 |
+
*Postconditions:* `*this` has the original value of `rhs`.
|
| 8667 |
+
|
| 8668 |
+
``` cpp
|
| 8669 |
+
directory_iterator& operator=(const directory_iterator& rhs);
|
| 8670 |
+
directory_iterator& operator=(directory_iterator&& rhs) noexcept;
|
| 8671 |
+
```
|
| 8672 |
+
|
| 8673 |
+
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 8674 |
+
effect.
|
| 8675 |
+
|
| 8676 |
+
*Postconditions:* `*this` has the original value of `rhs`.
|
| 8677 |
+
|
| 8678 |
+
*Returns:* `*this`.
|
| 8679 |
+
|
| 8680 |
+
``` cpp
|
| 8681 |
+
directory_iterator& operator++();
|
| 8682 |
+
directory_iterator& increment(error_code& ec) noexcept;
|
| 8683 |
+
```
|
| 8684 |
+
|
| 8685 |
+
*Effects:* As specified for the prefix increment operation of Input
|
| 8686 |
+
iterators ([[input.iterators]]).
|
| 8687 |
+
|
| 8688 |
+
*Returns:* `*this`.
|
| 8689 |
+
|
| 8690 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8691 |
+
|
| 8692 |
+
#### `directory_iterator` non-member functions <a id="fs.dir.itr.nonmembers">[[fs.dir.itr.nonmembers]]</a>
|
| 8693 |
+
|
| 8694 |
+
These functions enable range access for `directory_iterator`.
|
| 8695 |
+
|
| 8696 |
+
``` cpp
|
| 8697 |
+
directory_iterator begin(directory_iterator iter) noexcept;
|
| 8698 |
+
```
|
| 8699 |
+
|
| 8700 |
+
*Returns:* `iter`.
|
| 8701 |
+
|
| 8702 |
+
``` cpp
|
| 8703 |
+
directory_iterator end(const directory_iterator&) noexcept;
|
| 8704 |
+
```
|
| 8705 |
+
|
| 8706 |
+
*Returns:* `directory_iterator()`.
|
| 8707 |
+
|
| 8708 |
+
### Class `recursive_directory_iterator` <a id="fs.class.rec.dir.itr">[[fs.class.rec.dir.itr]]</a>
|
| 8709 |
+
|
| 8710 |
+
An object of type `recursive_directory_iterator` provides an iterator
|
| 8711 |
+
for a sequence of `directory_entry` elements representing the files in a
|
| 8712 |
+
directory or in an *implementation-defined* directory-like file type,
|
| 8713 |
+
and its sub-directories.
|
| 8714 |
+
|
| 8715 |
+
``` cpp
|
| 8716 |
+
namespace std::filesystem {
|
| 8717 |
+
class recursive_directory_iterator {
|
| 8718 |
+
public:
|
| 8719 |
+
using iterator_category = input_iterator_tag;
|
| 8720 |
+
using value_type = directory_entry;
|
| 8721 |
+
using difference_type = ptrdiff_t;
|
| 8722 |
+
using pointer = const directory_entry*;
|
| 8723 |
+
using reference = const directory_entry&;
|
| 8724 |
+
|
| 8725 |
+
// [fs.rec.dir.itr.members], constructors and destructor
|
| 8726 |
+
recursive_directory_iterator() noexcept;
|
| 8727 |
+
explicit recursive_directory_iterator(const path& p);
|
| 8728 |
+
recursive_directory_iterator(const path& p, directory_options options);
|
| 8729 |
+
recursive_directory_iterator(const path& p, directory_options options,
|
| 8730 |
+
error_code& ec) noexcept;
|
| 8731 |
+
recursive_directory_iterator(const path& p, error_code& ec) noexcept;
|
| 8732 |
+
recursive_directory_iterator(const recursive_directory_iterator& rhs);
|
| 8733 |
+
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
|
| 8734 |
+
~recursive_directory_iterator();
|
| 8735 |
+
|
| 8736 |
+
// [fs.rec.dir.itr.members], observers
|
| 8737 |
+
directory_options options() const;
|
| 8738 |
+
int depth() const;
|
| 8739 |
+
bool recursion_pending() const;
|
| 8740 |
+
|
| 8741 |
+
const directory_entry& operator*() const;
|
| 8742 |
+
const directory_entry* operator->() const;
|
| 8743 |
+
|
| 8744 |
+
// [fs.rec.dir.itr.members], modifiers
|
| 8745 |
+
recursive_directory_iterator&
|
| 8746 |
+
operator=(const recursive_directory_iterator& rhs);
|
| 8747 |
+
recursive_directory_iterator&
|
| 8748 |
+
operator=(recursive_directory_iterator&& rhs) noexcept;
|
| 8749 |
+
|
| 8750 |
+
recursive_directory_iterator& operator++();
|
| 8751 |
+
recursive_directory_iterator& increment(error_code& ec) noexcept;
|
| 8752 |
+
|
| 8753 |
+
void pop();
|
| 8754 |
+
void pop(error_code& ec);
|
| 8755 |
+
void disable_recursion_pending();
|
| 8756 |
+
|
| 8757 |
+
// other members as required by [input.iterators], input iterators
|
| 8758 |
+
};
|
| 8759 |
+
}
|
| 8760 |
+
```
|
| 8761 |
+
|
| 8762 |
+
Calling `options`, `depth`, `recursion_pending`, `pop` or
|
| 8763 |
+
`disable_recursion_pending` on an iterator that is not dereferenceable
|
| 8764 |
+
results in undefined behavior.
|
| 8765 |
+
|
| 8766 |
+
The behavior of a `recursive_directory_iterator` is the same as a
|
| 8767 |
+
`directory_iterator` unless otherwise specified.
|
| 8768 |
+
|
| 8769 |
+
[*Note 1*: If the directory structure being iterated over contains
|
| 8770 |
+
cycles then the end iterator may be unreachable. — *end note*]
|
| 8771 |
+
|
| 8772 |
+
#### `recursive_directory_iterator` members <a id="fs.rec.dir.itr.members">[[fs.rec.dir.itr.members]]</a>
|
| 8773 |
+
|
| 8774 |
+
``` cpp
|
| 8775 |
+
recursive_directory_iterator() noexcept;
|
| 8776 |
+
```
|
| 8777 |
+
|
| 8778 |
+
*Effects:* Constructs the end iterator.
|
| 8779 |
+
|
| 8780 |
+
``` cpp
|
| 8781 |
+
explicit recursive_directory_iterator(const path& p);
|
| 8782 |
+
recursive_directory_iterator(const path& p, directory_options options);
|
| 8783 |
+
recursive_directory_iterator(const path& p, directory_options options, error_code& ec) noexcept;
|
| 8784 |
+
recursive_directory_iterator(const path& p, error_code& ec) noexcept;
|
| 8785 |
+
```
|
| 8786 |
+
|
| 8787 |
+
*Effects:* Constructs a iterator representing the first entry in the
|
| 8788 |
+
directory `p` resolves to, if any; otherwise, the end iterator. However,
|
| 8789 |
+
if
|
| 8790 |
+
|
| 8791 |
+
``` cpp
|
| 8792 |
+
(options & directory_options::skip_permission_denied) != directory_options::none
|
| 8793 |
+
```
|
| 8794 |
+
|
| 8795 |
+
and construction encounters an error indicating that permission to
|
| 8796 |
+
access `p` is denied, constructs the end iterator and does not report an
|
| 8797 |
+
error.
|
| 8798 |
+
|
| 8799 |
+
*Postconditions:* `options() == options` for the signatures with a
|
| 8800 |
+
`directory_options` argument, otherwise
|
| 8801 |
+
`options() == directory_options::none`.
|
| 8802 |
+
|
| 8803 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8804 |
+
|
| 8805 |
+
[*Note 1*: To iterate over the current directory, use
|
| 8806 |
+
`recursive_directory_iterator(".")` rather than
|
| 8807 |
+
`recursive_directory_iterator("")`. — *end note*]
|
| 8808 |
+
|
| 8809 |
+
[*Note 2*: By default, `recursive_directory_iterator` does not follow
|
| 8810 |
+
directory symlinks. To follow directory symlinks, specify `options` as
|
| 8811 |
+
`directory_options::follow_directory_symlink` — *end note*]
|
| 8812 |
+
|
| 8813 |
+
``` cpp
|
| 8814 |
+
recursive_directory_iterator(const recursive_directory_iterator& rhs);
|
| 8815 |
+
```
|
| 8816 |
+
|
| 8817 |
+
*Effects:* Constructs an object of class `recursive_directory_iterator`.
|
| 8818 |
+
|
| 8819 |
+
*Postconditions:*
|
| 8820 |
+
|
| 8821 |
+
- `options() == rhs.options()`
|
| 8822 |
+
- `depth() == rhs.depth()`
|
| 8823 |
+
- `recursion_pending() == rhs.recursion_pending()`
|
| 8824 |
+
|
| 8825 |
+
``` cpp
|
| 8826 |
+
recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
|
| 8827 |
+
```
|
| 8828 |
+
|
| 8829 |
+
*Effects:* Constructs an object of class `recursive_directory_iterator`.
|
| 8830 |
+
|
| 8831 |
+
*Postconditions:* `options()`, `depth()`, and `recursion_pending()` have
|
| 8832 |
+
the values that `rhs.options()`, `rhs.depth()`, and
|
| 8833 |
+
`rhs.recursion_pending()`, respectively, had before the function call.
|
| 8834 |
+
|
| 8835 |
+
``` cpp
|
| 8836 |
+
recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);
|
| 8837 |
+
```
|
| 8838 |
+
|
| 8839 |
+
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 8840 |
+
effect.
|
| 8841 |
+
|
| 8842 |
+
*Postconditions:*
|
| 8843 |
+
|
| 8844 |
+
- `options() == rhs.options()`
|
| 8845 |
+
- `depth() == rhs.depth()`
|
| 8846 |
+
- `recursion_pending() == rhs.recursion_pending()`
|
| 8847 |
+
|
| 8848 |
+
*Returns:* `*this`.
|
| 8849 |
+
|
| 8850 |
+
``` cpp
|
| 8851 |
+
recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;
|
| 8852 |
+
```
|
| 8853 |
+
|
| 8854 |
+
*Effects:* If `*this` and `rhs` are the same object, the member has no
|
| 8855 |
+
effect.
|
| 8856 |
+
|
| 8857 |
+
*Postconditions:* `options()`, `depth()`, and `recursion_pending()` have
|
| 8858 |
+
the values that `rhs.options()`, `rhs.depth()`, and
|
| 8859 |
+
`rhs.recursion_pending()`, respectively, had before the function call.
|
| 8860 |
+
|
| 8861 |
+
*Returns:* `*this`.
|
| 8862 |
+
|
| 8863 |
+
``` cpp
|
| 8864 |
+
directory_options options() const;
|
| 8865 |
+
```
|
| 8866 |
+
|
| 8867 |
+
*Returns:* The value of the argument passed to the constructor for the
|
| 8868 |
+
`options` parameter, if present, otherwise `directory_options::none`.
|
| 8869 |
+
|
| 8870 |
+
*Throws:* Nothing.
|
| 8871 |
+
|
| 8872 |
+
``` cpp
|
| 8873 |
+
int depth() const;
|
| 8874 |
+
```
|
| 8875 |
+
|
| 8876 |
+
*Returns:* The current depth of the directory tree being traversed.
|
| 8877 |
+
|
| 8878 |
+
[*Note 3*: The initial directory is depth `0`, its immediate
|
| 8879 |
+
subdirectories are depth `1`, and so forth. — *end note*]
|
| 8880 |
+
|
| 8881 |
+
*Throws:* Nothing.
|
| 8882 |
+
|
| 8883 |
+
``` cpp
|
| 8884 |
+
bool recursion_pending() const;
|
| 8885 |
+
```
|
| 8886 |
+
|
| 8887 |
+
*Returns:* `true` if `disable_recursion_pending()` has not been called
|
| 8888 |
+
subsequent to the prior construction or increment operation, otherwise
|
| 8889 |
+
`false`.
|
| 8890 |
+
|
| 8891 |
+
*Throws:* Nothing.
|
| 8892 |
+
|
| 8893 |
+
``` cpp
|
| 8894 |
+
recursive_directory_iterator& operator++();
|
| 8895 |
+
recursive_directory_iterator& increment(error_code& ec) noexcept;
|
| 8896 |
+
```
|
| 8897 |
+
|
| 8898 |
+
*Effects:* As specified for the prefix increment operation of Input
|
| 8899 |
+
iterators ([[input.iterators]]), except that:
|
| 8900 |
+
|
| 8901 |
+
- If there are no more entries at the current depth, then if
|
| 8902 |
+
`depth() != 0` iteration over the parent directory resumes; otherwise
|
| 8903 |
+
`*this = recursive_directory_iterator()`.
|
| 8904 |
+
- Otherwise if
|
| 8905 |
+
``` cpp
|
| 8906 |
+
recursion_pending() && is_directory((*this)->status()) &&
|
| 8907 |
+
(!is_symlink((*this)->symlink_status()) ||
|
| 8908 |
+
(options() & directory_options::follow_directory_symlink) != directory_options::none)
|
| 8909 |
+
```
|
| 8910 |
+
|
| 8911 |
+
then either directory `(*this)->path()` is recursively iterated into
|
| 8912 |
+
or, if
|
| 8913 |
+
``` cpp
|
| 8914 |
+
(options() & directory_options::skip_permission_denied) != directory_options::none
|
| 8915 |
+
```
|
| 8916 |
+
|
| 8917 |
+
and an error occurs indicating that permission to access directory
|
| 8918 |
+
`(*this)->path()` is denied, then directory `(*this)->path()` is
|
| 8919 |
+
treated as an empty directory and no error is reported.
|
| 8920 |
+
|
| 8921 |
+
*Returns:* `*this`.
|
| 8922 |
+
|
| 8923 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8924 |
+
|
| 8925 |
+
``` cpp
|
| 8926 |
+
void pop();
|
| 8927 |
+
void pop(error_code& ec);
|
| 8928 |
+
```
|
| 8929 |
+
|
| 8930 |
+
*Effects:* If `depth() == 0`, set `*this` to
|
| 8931 |
+
`recursive_directory_iterator()`. Otherwise, cease iteration of the
|
| 8932 |
+
directory currently being iterated over, and continue iteration over the
|
| 8933 |
+
parent directory.
|
| 8934 |
+
|
| 8935 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8936 |
+
|
| 8937 |
+
``` cpp
|
| 8938 |
+
void disable_recursion_pending();
|
| 8939 |
+
```
|
| 8940 |
+
|
| 8941 |
+
*Postconditions:* `recursion_pending() == false`.
|
| 8942 |
+
|
| 8943 |
+
[*Note 4*: `disable_recursion_pending``()` is used to prevent unwanted
|
| 8944 |
+
recursion into a directory. — *end note*]
|
| 8945 |
+
|
| 8946 |
+
#### `recursive_directory_iterator` non-member functions <a id="fs.rec.dir.itr.nonmembers">[[fs.rec.dir.itr.nonmembers]]</a>
|
| 8947 |
+
|
| 8948 |
+
These functions enable use of `recursive_directory_iterator` with
|
| 8949 |
+
range-based for statements.
|
| 8950 |
+
|
| 8951 |
+
``` cpp
|
| 8952 |
+
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
|
| 8953 |
+
```
|
| 8954 |
+
|
| 8955 |
+
*Returns:* `iter`.
|
| 8956 |
+
|
| 8957 |
+
``` cpp
|
| 8958 |
+
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
|
| 8959 |
+
```
|
| 8960 |
+
|
| 8961 |
+
*Returns:* `recursive_directory_iterator()`.
|
| 8962 |
+
|
| 8963 |
+
### Filesystem operation functions <a id="fs.op.funcs">[[fs.op.funcs]]</a>
|
| 8964 |
+
|
| 8965 |
+
Filesystem operation functions query or modify files, including
|
| 8966 |
+
directories, in external storage.
|
| 8967 |
+
|
| 8968 |
+
[*Note 1*: Because hardware failures, network failures, file system
|
| 8969 |
+
races ([[fs.def.race]]), and many other kinds of errors occur
|
| 8970 |
+
frequently in file system operations, users should be aware that any
|
| 8971 |
+
filesystem operation function, no matter how apparently innocuous, may
|
| 8972 |
+
encounter an error; see [[fs.err.report]]. — *end note*]
|
| 8973 |
+
|
| 8974 |
+
#### Absolute <a id="fs.op.absolute">[[fs.op.absolute]]</a>
|
| 8975 |
+
|
| 8976 |
+
``` cpp
|
| 8977 |
+
path absolute(const path& p);
|
| 8978 |
+
path absolute(const path& p, error_code& ec);
|
| 8979 |
+
```
|
| 8980 |
+
|
| 8981 |
+
*Effects:* Composes an absolute path referencing the same file system
|
| 8982 |
+
location as `p` according to the operating system ([[fs.conform.os]]).
|
| 8983 |
+
|
| 8984 |
+
*Returns:* The composed path. The signature with argument `ec` returns
|
| 8985 |
+
`path()` if an error occurs.
|
| 8986 |
+
|
| 8987 |
+
[*Note 1*: For the returned path, `rp`, `rp.is_absolute()` is `true`
|
| 8988 |
+
unless an error occurs. — *end note*]
|
| 8989 |
+
|
| 8990 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 8991 |
+
|
| 8992 |
+
[*Note 2*: To resolve symlinks, or perform other sanitization which
|
| 8993 |
+
might require queries to secondary storage, such as hard disks, consider
|
| 8994 |
+
`canonical` ([[fs.op.canonical]]). — *end note*]
|
| 8995 |
+
|
| 8996 |
+
[*Note 3*: Implementations are strongly encouraged to not query
|
| 8997 |
+
secondary storage, and not consider `!exists(p)` an
|
| 8998 |
+
error. — *end note*]
|
| 8999 |
+
|
| 9000 |
+
[*Example 1*: For POSIX-based operating systems, `absolute(p)` is
|
| 9001 |
+
simply `current_path()/p`. For Windows-based operating systems,
|
| 9002 |
+
`absolute` might have the same semantics as
|
| 9003 |
+
`GetFullPathNameW`. — *end example*]
|
| 9004 |
+
|
| 9005 |
+
#### Canonical <a id="fs.op.canonical">[[fs.op.canonical]]</a>
|
| 9006 |
+
|
| 9007 |
+
``` cpp
|
| 9008 |
+
path canonical(const path& p, const path& base = current_path());
|
| 9009 |
+
path canonical(const path& p, error_code& ec);
|
| 9010 |
+
path canonical(const path& p, const path& base, error_code& ec);
|
| 9011 |
+
```
|
| 9012 |
+
|
| 9013 |
+
*Effects:* Converts `p`, which must exist, to an absolute path that has
|
| 9014 |
+
no symbolic link, *dot*, or *dot-dot* elements in its pathname in the
|
| 9015 |
+
generic format.
|
| 9016 |
+
|
| 9017 |
+
*Returns:* A path that refers to the same file system object as
|
| 9018 |
+
`absolute(p, base)`. For the overload without a `base` argument, `base`
|
| 9019 |
+
is `current_path()`. Signatures with argument `ec` return `path()` if an
|
| 9020 |
+
error occurs.
|
| 9021 |
+
|
| 9022 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9023 |
+
|
| 9024 |
+
*Remarks:* `!exists(p)` is an error.
|
| 9025 |
+
|
| 9026 |
+
#### Copy <a id="fs.op.copy">[[fs.op.copy]]</a>
|
| 9027 |
+
|
| 9028 |
+
``` cpp
|
| 9029 |
+
void copy(const path& from, const path& to);
|
| 9030 |
+
```
|
| 9031 |
+
|
| 9032 |
+
*Effects:* Equivalent to `copy(from, to, copy_options::none)`.
|
| 9033 |
+
|
| 9034 |
+
``` cpp
|
| 9035 |
+
void copy(const path& from, const path& to, error_code& ec) noexcept;
|
| 9036 |
+
```
|
| 9037 |
+
|
| 9038 |
+
*Effects:* Equivalent to `copy(from, to, copy_options::none, ec)`.
|
| 9039 |
+
|
| 9040 |
+
``` cpp
|
| 9041 |
+
void copy(const path& from, const path& to, copy_options options);
|
| 9042 |
+
void copy(const path& from, const path& to, copy_options options,
|
| 9043 |
+
error_code& ec) noexcept;
|
| 9044 |
+
```
|
| 9045 |
+
|
| 9046 |
+
*Requires:* At most one element from each option group
|
| 9047 |
+
([[fs.enum.copy.opts]]) is set in `options`.
|
| 9048 |
+
|
| 9049 |
+
*Effects:* Before the first use of `f` and `t`:
|
| 9050 |
+
|
| 9051 |
+
- If
|
| 9052 |
+
``` cpp
|
| 9053 |
+
(options & copy_options::create_symlinks) != copy_options::none ||
|
| 9054 |
+
(options & copy_options::skip_symlinks) != copy_options::none
|
| 9055 |
+
```
|
| 9056 |
+
|
| 9057 |
+
then `auto f = symlink_status(from)` and if needed
|
| 9058 |
+
`auto t = symlink_status(to)`.
|
| 9059 |
+
- Otherwise, if
|
| 9060 |
+
``` cpp
|
| 9061 |
+
(options & copy_options::copy_symlinks) != copy_options::none
|
| 9062 |
+
```
|
| 9063 |
+
|
| 9064 |
+
then `auto f = symlink_status(from)` and if needed
|
| 9065 |
+
`auto t = status(to)`.
|
| 9066 |
+
- Otherwise, `auto f = status(from)` and if needed
|
| 9067 |
+
`auto t = status(to)`.
|
| 9068 |
+
|
| 9069 |
+
Effects are then as follows:
|
| 9070 |
+
|
| 9071 |
+
- If `f.type()` or `t.type()` is an implementation-defined file
|
| 9072 |
+
type ([[fs.enum.file_type]]), then the effects are
|
| 9073 |
+
*implementation-defined*.
|
| 9074 |
+
- Otherwise, an error is reported as specified in [[fs.err.report]] if:
|
| 9075 |
+
- `!exists(f)`, or
|
| 9076 |
+
- `equivalent(from, to)`, or
|
| 9077 |
+
- `is_other(f) || is_other(t)`, or
|
| 9078 |
+
- `is_directory(f) && is_regular_file(t)`.
|
| 9079 |
+
- Otherwise, if `is_symlink(f)`, then:
|
| 9080 |
+
- If `(options & copy_options::skip_symlinks) != copy_options::none`
|
| 9081 |
+
then return.
|
| 9082 |
+
- Otherwise if
|
| 9083 |
+
``` cpp
|
| 9084 |
+
!exists(t) && (options & copy_options::copy_symlinks) != copy_options::none
|
| 9085 |
+
```
|
| 9086 |
+
|
| 9087 |
+
then `copy_symlink(from, to)`.
|
| 9088 |
+
- Otherwise report an error as specified in [[fs.err.report]].
|
| 9089 |
+
- Otherwise, if `is_regular_file(f)`, then:
|
| 9090 |
+
- If
|
| 9091 |
+
`(options & copy_options::directories_only) != copy_options::none`,
|
| 9092 |
+
then return.
|
| 9093 |
+
- Otherwise, if
|
| 9094 |
+
`(options & copy_options::create_symlinks) `` != copy_options::none`,
|
| 9095 |
+
then create a symbolic link to the source file.
|
| 9096 |
+
- Otherwise, if
|
| 9097 |
+
`(options & copy_options::create_hard_links) != copy_options::none`,
|
| 9098 |
+
then create a hard link to the source file.
|
| 9099 |
+
- Otherwise, if `is_directory(t)`, then
|
| 9100 |
+
`copy_file(from, to/from.filename(), options)`.
|
| 9101 |
+
- Otherwise, `copy_file(from, to, options)`.
|
| 9102 |
+
- Otherwise, if
|
| 9103 |
+
``` cpp
|
| 9104 |
+
is_directory(f) &&
|
| 9105 |
+
((options & copy_options::recursive) != copy_options::none ||
|
| 9106 |
+
options == copy_options::none)
|
| 9107 |
+
```
|
| 9108 |
+
|
| 9109 |
+
then:
|
| 9110 |
+
- If `!exists(t)`, then `create_directory(to, from)`.
|
| 9111 |
+
- Then, iterate over the files in `from`, as if by
|
| 9112 |
+
``` cpp
|
| 9113 |
+
for (const directory_entry& x : directory_iterator(from))
|
| 9114 |
+
copy(x.path(), to/x.path().filename(), options | copy_options::unspecified)
|
| 9115 |
+
```
|
| 9116 |
+
- Otherwise, for the signature with argument `ec`, `ec.clear()`.
|
| 9117 |
+
- Otherwise, no effects.
|
| 9118 |
+
|
| 9119 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9120 |
+
|
| 9121 |
+
*Remarks:* For the signature with argument `ec`, any library functions
|
| 9122 |
+
called by the implementation shall have an `error_code` argument if
|
| 9123 |
+
applicable.
|
| 9124 |
+
|
| 9125 |
+
[*Example 1*:
|
| 9126 |
+
|
| 9127 |
+
Given this directory structure:
|
| 9128 |
+
|
| 9129 |
+
``` cpp
|
| 9130 |
+
/dir1
|
| 9131 |
+
file1
|
| 9132 |
+
file2
|
| 9133 |
+
dir2
|
| 9134 |
+
file3
|
| 9135 |
+
```
|
| 9136 |
+
|
| 9137 |
+
Calling `copy("/dir1", "/dir3")` would result in:
|
| 9138 |
+
|
| 9139 |
+
``` cpp
|
| 9140 |
+
/dir1
|
| 9141 |
+
file1
|
| 9142 |
+
file2
|
| 9143 |
+
dir2
|
| 9144 |
+
file3
|
| 9145 |
+
/dir3
|
| 9146 |
+
file1
|
| 9147 |
+
file2
|
| 9148 |
+
```
|
| 9149 |
+
|
| 9150 |
+
Alternatively, calling `copy("/dir1", "/dir3", copy_options::recursive)`
|
| 9151 |
+
would result in:
|
| 9152 |
+
|
| 9153 |
+
``` cpp
|
| 9154 |
+
/dir1
|
| 9155 |
+
file1
|
| 9156 |
+
file2
|
| 9157 |
+
dir2
|
| 9158 |
+
file3
|
| 9159 |
+
/dir3
|
| 9160 |
+
file1
|
| 9161 |
+
file2
|
| 9162 |
+
dir2
|
| 9163 |
+
file3
|
| 9164 |
+
```
|
| 9165 |
+
|
| 9166 |
+
— *end example*]
|
| 9167 |
+
|
| 9168 |
+
#### Copy file <a id="fs.op.copy_file">[[fs.op.copy_file]]</a>
|
| 9169 |
+
|
| 9170 |
+
``` cpp
|
| 9171 |
+
bool copy_file(const path& from, const path& to);
|
| 9172 |
+
bool copy_file(const path& from, const path& to, error_code& ec) noexcept;
|
| 9173 |
+
```
|
| 9174 |
+
|
| 9175 |
+
*Returns:* `copy_file(from, to, copy_options::none)` or
|
| 9176 |
+
`copy_file(from, to, copy_options::none, ec)`, respectively.
|
| 9177 |
+
|
| 9178 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9179 |
+
|
| 9180 |
+
``` cpp
|
| 9181 |
+
bool copy_file(const path& from, const path& to, copy_options options);
|
| 9182 |
+
bool copy_file(const path& from, const path& to, copy_options options,
|
| 9183 |
+
error_code& ec) noexcept;
|
| 9184 |
+
```
|
| 9185 |
+
|
| 9186 |
+
*Requires:* At most one element from each option group
|
| 9187 |
+
([[fs.enum.copy.opts]]) is set in `options`.
|
| 9188 |
+
|
| 9189 |
+
*Effects:* As follows:
|
| 9190 |
+
|
| 9191 |
+
- Report a file already exists error as specified in [[fs.err.report]]
|
| 9192 |
+
if:
|
| 9193 |
+
- `!is_regular_file(from)`, or
|
| 9194 |
+
- `exists(to)` and `!is_regular_file(to)`, or
|
| 9195 |
+
- `exists(to)` and `equivalent(from, to)`, or
|
| 9196 |
+
- `exists(to)` and
|
| 9197 |
+
``` cpp
|
| 9198 |
+
(options & (copy_options::skip_existing |
|
| 9199 |
+
copy_options::overwrite_existing |
|
| 9200 |
+
copy_options::update_existing)) == copy_options::none
|
| 9201 |
+
```
|
| 9202 |
+
- Otherwise, copy the contents and attributes of the file `from`
|
| 9203 |
+
resolves to, to the file `to` resolves to, if:
|
| 9204 |
+
- `!exists(to)`, or
|
| 9205 |
+
- `(options & copy_options::overwrite_existing) != copy_options::none`,
|
| 9206 |
+
or
|
| 9207 |
+
- `(options & copy_options::update_existing) `` `` != copy_options::none`
|
| 9208 |
+
and `from` is more recent than `to`, determined as if by use of the
|
| 9209 |
+
`last_write_time` function ([[fs.op.last_write_time]]).
|
| 9210 |
+
- Otherwise, no effects.
|
| 9211 |
+
|
| 9212 |
+
*Returns:* `true` if the `from` file was copied, otherwise `false`. The
|
| 9213 |
+
signature with argument `ec` returns `false` if an error occurs.
|
| 9214 |
+
|
| 9215 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9216 |
+
|
| 9217 |
+
*Complexity:* At most one direct or indirect invocation of `status(to)`.
|
| 9218 |
+
|
| 9219 |
+
#### Copy symlink <a id="fs.op.copy_symlink">[[fs.op.copy_symlink]]</a>
|
| 9220 |
+
|
| 9221 |
+
``` cpp
|
| 9222 |
+
void copy_symlink(const path& existing_symlink, const path& new_symlink);
|
| 9223 |
+
void copy_symlink(const path& existing_symlink, const path& new_symlink,
|
| 9224 |
+
error_code& ec) noexcept;
|
| 9225 |
+
```
|
| 9226 |
+
|
| 9227 |
+
*Effects:* Equivalent to
|
| 9228 |
+
*`function`*`(read_symlink(existing_symlink), new_symlink)` or
|
| 9229 |
+
*`function`*`(read_symlink(existing_symlink, ec), new_symlink, ec)`,
|
| 9230 |
+
respectively, where in each case *`function`* is `create_symlink` or
|
| 9231 |
+
`create_directory_symlink` as appropriate.
|
| 9232 |
+
|
| 9233 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9234 |
+
|
| 9235 |
+
#### Create directories <a id="fs.op.create_directories">[[fs.op.create_directories]]</a>
|
| 9236 |
+
|
| 9237 |
+
``` cpp
|
| 9238 |
+
bool create_directories(const path& p);
|
| 9239 |
+
bool create_directories(const path& p, error_code& ec) noexcept;
|
| 9240 |
+
```
|
| 9241 |
+
|
| 9242 |
+
*Effects:* Establishes the postcondition by calling `create_directory()`
|
| 9243 |
+
for any element of `p` that does not exist.
|
| 9244 |
+
|
| 9245 |
+
*Postconditions:* `is_directory(p)`.
|
| 9246 |
+
|
| 9247 |
+
*Returns:* `true` if a new directory was created, otherwise `false`. The
|
| 9248 |
+
signature with argument `ec` returns `false` if an error occurs.
|
| 9249 |
+
|
| 9250 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9251 |
+
|
| 9252 |
+
*Complexity:* 𝑂(n) where *n* is the number of elements of `p` that do
|
| 9253 |
+
not exist.
|
| 9254 |
+
|
| 9255 |
+
#### Create directory <a id="fs.op.create_directory">[[fs.op.create_directory]]</a>
|
| 9256 |
+
|
| 9257 |
+
``` cpp
|
| 9258 |
+
bool create_directory(const path& p);
|
| 9259 |
+
bool create_directory(const path& p, error_code& ec) noexcept;
|
| 9260 |
+
```
|
| 9261 |
+
|
| 9262 |
+
*Effects:* Establishes the postcondition by attempting to create the
|
| 9263 |
+
directory `p` resolves to, as if by POSIX `mkdir()` with a second
|
| 9264 |
+
argument of `static_cast<int>(perms::all)`. Creation failure because `p`
|
| 9265 |
+
resolves to an existing directory shall not be treated as an error.
|
| 9266 |
+
|
| 9267 |
+
*Postconditions:* `is_directory(p)`.
|
| 9268 |
+
|
| 9269 |
+
*Returns:* `true` if a new directory was created, otherwise `false`. The
|
| 9270 |
+
signature with argument `ec` returns `false` if an error occurs.
|
| 9271 |
+
|
| 9272 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9273 |
+
|
| 9274 |
+
``` cpp
|
| 9275 |
+
bool create_directory(const path& p, const path& existing_p);
|
| 9276 |
+
bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;
|
| 9277 |
+
```
|
| 9278 |
+
|
| 9279 |
+
*Effects:* Establishes the postcondition by attempting to create the
|
| 9280 |
+
directory `p` resolves to, with attributes copied from directory
|
| 9281 |
+
`existing_p`. The set of attributes copied is operating system
|
| 9282 |
+
dependent. Creation failure because `p` resolves to an existing
|
| 9283 |
+
directory shall not be treated as an error.
|
| 9284 |
+
|
| 9285 |
+
[*Note 1*: For POSIX-based operating systems, the attributes are those
|
| 9286 |
+
copied by native API `stat(existing_p.c_str(), &attributes_stat)`
|
| 9287 |
+
followed by `mkdir(p.c_str(), attributes_stat.st_mode)`. For
|
| 9288 |
+
Windows-based operating systems, the attributes are those copied by
|
| 9289 |
+
native API
|
| 9290 |
+
`CreateDirectoryExW(existing_p.c_str(), p.c_str(), 0)`. — *end note*]
|
| 9291 |
+
|
| 9292 |
+
*Postconditions:* `is_directory(p)`.
|
| 9293 |
+
|
| 9294 |
+
*Returns:* `true` if a new directory was created, otherwise `false`. The
|
| 9295 |
+
signature with argument `ec` returns `false` if an error occurs.
|
| 9296 |
+
|
| 9297 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9298 |
+
|
| 9299 |
+
#### Create directory symlink <a id="fs.op.create_dir_symlk">[[fs.op.create_dir_symlk]]</a>
|
| 9300 |
+
|
| 9301 |
+
``` cpp
|
| 9302 |
+
void create_directory_symlink(const path& to, const path& new_symlink);
|
| 9303 |
+
void create_directory_symlink(const path& to, const path& new_symlink,
|
| 9304 |
+
error_code& ec) noexcept;
|
| 9305 |
+
```
|
| 9306 |
+
|
| 9307 |
+
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 9308 |
+
|
| 9309 |
+
*Postconditions:* `new_symlink` resolves to a symbolic link file that
|
| 9310 |
+
contains an unspecified representation of `to`.
|
| 9311 |
+
|
| 9312 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9313 |
+
|
| 9314 |
+
[*Note 1*: Some operating systems require symlink creation to identify
|
| 9315 |
+
that the link is to a directory. Portable code should use
|
| 9316 |
+
`create_directory_symlink()` to create directory symlinks rather than
|
| 9317 |
+
`create_symlink()` — *end note*]
|
| 9318 |
+
|
| 9319 |
+
[*Note 2*: Some operating systems do not support symbolic links at all
|
| 9320 |
+
or support them only for regular files. Some file systems (such as the
|
| 9321 |
+
FAT file system) do not support symbolic links regardless of the
|
| 9322 |
+
operating system. — *end note*]
|
| 9323 |
+
|
| 9324 |
+
#### Create hard link <a id="fs.op.create_hard_lk">[[fs.op.create_hard_lk]]</a>
|
| 9325 |
+
|
| 9326 |
+
``` cpp
|
| 9327 |
+
void create_hard_link(const path& to, const path& new_hard_link);
|
| 9328 |
+
void create_hard_link(const path& to, const path& new_hard_link,
|
| 9329 |
+
error_code& ec) noexcept;
|
| 9330 |
+
```
|
| 9331 |
+
|
| 9332 |
+
*Effects:* Establishes the postcondition, as if by POSIX `link()`.
|
| 9333 |
+
|
| 9334 |
+
*Postconditions:*
|
| 9335 |
+
|
| 9336 |
+
- `exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link)`
|
| 9337 |
+
- The contents of the file or directory `to` resolves to are unchanged.
|
| 9338 |
+
|
| 9339 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9340 |
+
|
| 9341 |
+
[*Note 1*: Some operating systems do not support hard links at all or
|
| 9342 |
+
support them only for regular files. Some file systems (such as the FAT
|
| 9343 |
+
file system) do not support hard links regardless of the operating
|
| 9344 |
+
system. Some file systems limit the number of links per
|
| 9345 |
+
file. — *end note*]
|
| 9346 |
+
|
| 9347 |
+
#### Create symlink <a id="fs.op.create_symlink">[[fs.op.create_symlink]]</a>
|
| 9348 |
+
|
| 9349 |
+
``` cpp
|
| 9350 |
+
void create_symlink(const path& to, const path& new_symlink);
|
| 9351 |
+
void create_symlink(const path& to, const path& new_symlink,
|
| 9352 |
+
error_code& ec) noexcept;
|
| 9353 |
+
```
|
| 9354 |
+
|
| 9355 |
+
*Effects:* Establishes the postcondition, as if by POSIX `symlink()`.
|
| 9356 |
+
|
| 9357 |
+
*Postconditions:* `new_symlink` resolves to a symbolic link file that
|
| 9358 |
+
contains an unspecified representation of `to`.
|
| 9359 |
+
|
| 9360 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9361 |
+
|
| 9362 |
+
[*Note 1*: Some operating systems do not support symbolic links at all
|
| 9363 |
+
or support them only for regular files. Some file systems (such as the
|
| 9364 |
+
FAT file system) do not support symbolic links regardless of the
|
| 9365 |
+
operating system. — *end note*]
|
| 9366 |
+
|
| 9367 |
+
#### Current path <a id="fs.op.current_path">[[fs.op.current_path]]</a>
|
| 9368 |
+
|
| 9369 |
+
``` cpp
|
| 9370 |
+
path current_path();
|
| 9371 |
+
path current_path(error_code& ec);
|
| 9372 |
+
```
|
| 9373 |
+
|
| 9374 |
+
*Returns:* The absolute path of the current working directory, whose
|
| 9375 |
+
pathname in the native format is obtained as if by POSIX `getcwd()`. The
|
| 9376 |
+
signature with argument `ec` returns `path()` if an error occurs.
|
| 9377 |
+
|
| 9378 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9379 |
+
|
| 9380 |
+
*Remarks:* The current working directory is the directory, associated
|
| 9381 |
+
with the process, that is used as the starting location in pathname
|
| 9382 |
+
resolution for relative paths.
|
| 9383 |
+
|
| 9384 |
+
[*Note 1*: The `current_path()` name was chosen to emphasize that the
|
| 9385 |
+
returned value is a path, not just a single directory
|
| 9386 |
+
name. — *end note*]
|
| 9387 |
+
|
| 9388 |
+
[*Note 2*: The current path as returned by many operating systems is a
|
| 9389 |
+
dangerous global variable. It may be changed unexpectedly by a
|
| 9390 |
+
third-party or system library functions, or by another
|
| 9391 |
+
thread. — *end note*]
|
| 9392 |
+
|
| 9393 |
+
``` cpp
|
| 9394 |
+
void current_path(const path& p);
|
| 9395 |
+
void current_path(const path& p, error_code& ec) noexcept;
|
| 9396 |
+
```
|
| 9397 |
+
|
| 9398 |
+
*Effects:* Establishes the postcondition, as if by POSIX `chdir()`.
|
| 9399 |
+
|
| 9400 |
+
*Postconditions:* `equivalent(p, current_path())`.
|
| 9401 |
+
|
| 9402 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9403 |
+
|
| 9404 |
+
[*Note 3*: The current path for many operating systems is a dangerous
|
| 9405 |
+
global state. It may be changed unexpectedly by a third-party or system
|
| 9406 |
+
library functions, or by another thread. — *end note*]
|
| 9407 |
+
|
| 9408 |
+
#### Equivalent <a id="fs.op.equivalent">[[fs.op.equivalent]]</a>
|
| 9409 |
+
|
| 9410 |
+
``` cpp
|
| 9411 |
+
bool equivalent(const path& p1, const path& p2);
|
| 9412 |
+
bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;
|
| 9413 |
+
```
|
| 9414 |
+
|
| 9415 |
+
Let `s1` and `s2` be `file_status`s, determined as if by `status(p1)`
|
| 9416 |
+
and `status(p2)`, respectively.
|
| 9417 |
+
|
| 9418 |
+
*Effects:* Determines `s1` and `s2`. If
|
| 9419 |
+
`(!exists(s1) && !exists(s2)) || (is_other(s1) && is_other(s2))` an
|
| 9420 |
+
error is reported ([[fs.err.report]]).
|
| 9421 |
+
|
| 9422 |
+
*Returns:* `true`, if `s1 == s2` and `p1` and `p2` resolve to the same
|
| 9423 |
+
file system entity, else `false`. The signature with argument `ec`
|
| 9424 |
+
returns `false` if an error occurs.
|
| 9425 |
+
|
| 9426 |
+
Two paths are considered to resolve to the same file system entity if
|
| 9427 |
+
two candidate entities reside on the same device at the same location.
|
| 9428 |
+
This is determined as if by the values of the POSIX `stat` structure,
|
| 9429 |
+
obtained as if by `stat()` for the two paths, having equal `st_dev`
|
| 9430 |
+
values and equal `st_ino` values.
|
| 9431 |
+
|
| 9432 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9433 |
+
|
| 9434 |
+
#### Exists <a id="fs.op.exists">[[fs.op.exists]]</a>
|
| 9435 |
+
|
| 9436 |
+
``` cpp
|
| 9437 |
+
bool exists(file_status s) noexcept;
|
| 9438 |
+
```
|
| 9439 |
+
|
| 9440 |
+
*Returns:* `status_known(s) && s.type() != file_type::not_found`.
|
| 9441 |
+
|
| 9442 |
+
``` cpp
|
| 9443 |
+
bool exists(const path& p);
|
| 9444 |
+
bool exists(const path& p, error_code& ec) noexcept;
|
| 9445 |
+
```
|
| 9446 |
+
|
| 9447 |
+
Let `s` be a `file_status`, determined as if by `status(p)` or
|
| 9448 |
+
`status(p, ec)`, respectively.
|
| 9449 |
+
|
| 9450 |
+
*Effects:* The signature with argument `ec` calls `ec.clear()` if
|
| 9451 |
+
`status_known(s)`.
|
| 9452 |
+
|
| 9453 |
+
*Returns:* `exists(s)`.
|
| 9454 |
+
|
| 9455 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9456 |
+
|
| 9457 |
+
#### File size <a id="fs.op.file_size">[[fs.op.file_size]]</a>
|
| 9458 |
+
|
| 9459 |
+
``` cpp
|
| 9460 |
+
uintmax_t file_size(const path& p);
|
| 9461 |
+
uintmax_t file_size(const path& p, error_code& ec) noexcept;
|
| 9462 |
+
```
|
| 9463 |
+
|
| 9464 |
+
*Returns:*
|
| 9465 |
+
|
| 9466 |
+
- If `!exists(p)` an error is reported ([[fs.err.report]]).
|
| 9467 |
+
- Otherwise, if `is_regular_file(p)`, the size in bytes of the file `p`
|
| 9468 |
+
resolves to, determined as if by the value of the POSIX `stat`
|
| 9469 |
+
structure member `st_size` obtained as if by POSIX `stat()`.
|
| 9470 |
+
- Otherwise, the result is *implementation-defined*.
|
| 9471 |
+
|
| 9472 |
+
The signature with argument `ec` returns `static_cast<uintmax_t>(-1)` if
|
| 9473 |
+
an error occurs.
|
| 9474 |
+
|
| 9475 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9476 |
+
|
| 9477 |
+
#### Hard link count <a id="fs.op.hard_lk_ct">[[fs.op.hard_lk_ct]]</a>
|
| 9478 |
+
|
| 9479 |
+
``` cpp
|
| 9480 |
+
uintmax_t hard_link_count(const path& p);
|
| 9481 |
+
uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;
|
| 9482 |
+
```
|
| 9483 |
+
|
| 9484 |
+
*Returns:* The number of hard links for `p`. The signature with argument
|
| 9485 |
+
`ec` returns `static_cast<uintmax_t>(-1)` if an error occurs.
|
| 9486 |
+
|
| 9487 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9488 |
+
|
| 9489 |
+
#### Is block file <a id="fs.op.is_block_file">[[fs.op.is_block_file]]</a>
|
| 9490 |
+
|
| 9491 |
+
``` cpp
|
| 9492 |
+
bool is_block_file(file_status s) noexcept;
|
| 9493 |
+
```
|
| 9494 |
+
|
| 9495 |
+
*Returns:* `s.type() == file_type::block`.
|
| 9496 |
+
|
| 9497 |
+
``` cpp
|
| 9498 |
+
bool is_block_file(const path& p);
|
| 9499 |
+
bool is_block_file(const path& p, error_code& ec) noexcept;
|
| 9500 |
+
```
|
| 9501 |
+
|
| 9502 |
+
*Returns:* `is_block_file(status(p))` or `is_block_file(status(p, ec))`,
|
| 9503 |
+
respectively. The signature with argument `ec` returns `false` if an
|
| 9504 |
+
error occurs.
|
| 9505 |
+
|
| 9506 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9507 |
+
|
| 9508 |
+
#### Is character file <a id="fs.op.is_char_file">[[fs.op.is_char_file]]</a>
|
| 9509 |
+
|
| 9510 |
+
``` cpp
|
| 9511 |
+
bool is_character_file(file_status s) noexcept;
|
| 9512 |
+
```
|
| 9513 |
+
|
| 9514 |
+
*Returns:* `s.type() == file_type::character`.
|
| 9515 |
+
|
| 9516 |
+
``` cpp
|
| 9517 |
+
bool is_character_file(const path& p);
|
| 9518 |
+
bool is_character_file(const path& p, error_code& ec) noexcept;
|
| 9519 |
+
```
|
| 9520 |
+
|
| 9521 |
+
*Returns:* `is_character_file(status(p))` or
|
| 9522 |
+
`is_character_file(status(p, ec))`, respectively.
|
| 9523 |
+
The signature with argument `ec` returns `false` if an error occurs.
|
| 9524 |
+
|
| 9525 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9526 |
+
|
| 9527 |
+
#### Is directory <a id="fs.op.is_directory">[[fs.op.is_directory]]</a>
|
| 9528 |
+
|
| 9529 |
+
``` cpp
|
| 9530 |
+
bool is_directory(file_status s) noexcept;
|
| 9531 |
+
```
|
| 9532 |
+
|
| 9533 |
+
*Returns:* `s.type() == file_type::directory`.
|
| 9534 |
+
|
| 9535 |
+
``` cpp
|
| 9536 |
+
bool is_directory(const path& p);
|
| 9537 |
+
bool is_directory(const path& p, error_code& ec) noexcept;
|
| 9538 |
+
```
|
| 9539 |
+
|
| 9540 |
+
*Returns:* `is_directory(status(p))` or `is_directory(status(p, ec))`,
|
| 9541 |
+
respectively. The signature with argument `ec` returns `false` if an
|
| 9542 |
+
error occurs.
|
| 9543 |
+
|
| 9544 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9545 |
+
|
| 9546 |
+
#### Is empty <a id="fs.op.is_empty">[[fs.op.is_empty]]</a>
|
| 9547 |
+
|
| 9548 |
+
``` cpp
|
| 9549 |
+
bool is_empty(const path& p);
|
| 9550 |
+
bool is_empty(const path& p, error_code& ec) noexcept;
|
| 9551 |
+
```
|
| 9552 |
+
|
| 9553 |
+
*Effects:*
|
| 9554 |
+
|
| 9555 |
+
- Determine `file_status s`, as if by `status(p)` or `status(p, ec)`,
|
| 9556 |
+
respectively.
|
| 9557 |
+
- For the signature with argument `ec`, return `false` if an error
|
| 9558 |
+
occurred.
|
| 9559 |
+
- Otherwise, if `is_directory(s)`:
|
| 9560 |
+
- Create a variable `itr`, as if by `directory_iterator itr(p)` or
|
| 9561 |
+
`directory_iterator itr(p, ec)`, respectively.
|
| 9562 |
+
- For the signature with argument `ec`, return `false` if an error
|
| 9563 |
+
occurred.
|
| 9564 |
+
- Otherwise, return `itr == directory_iterator()`.
|
| 9565 |
+
- Otherwise:
|
| 9566 |
+
- Determine `uintmax_t sz`, as if by `file_size(p)` or
|
| 9567 |
+
`file_size(p, ec)`, respectively.
|
| 9568 |
+
- For the signature with argument `ec`, return `false` if an error
|
| 9569 |
+
occurred.
|
| 9570 |
+
- Otherwise, return `sz == 0`.
|
| 9571 |
+
|
| 9572 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9573 |
+
|
| 9574 |
+
#### Is fifo <a id="fs.op.is_fifo">[[fs.op.is_fifo]]</a>
|
| 9575 |
+
|
| 9576 |
+
``` cpp
|
| 9577 |
+
bool is_fifo(file_status s) noexcept;
|
| 9578 |
+
```
|
| 9579 |
+
|
| 9580 |
+
*Returns:* `s.type() == file_type::fifo`.
|
| 9581 |
+
|
| 9582 |
+
``` cpp
|
| 9583 |
+
bool is_fifo(const path& p);
|
| 9584 |
+
bool is_fifo(const path& p, error_code& ec) noexcept;
|
| 9585 |
+
```
|
| 9586 |
+
|
| 9587 |
+
*Returns:* `is_fifo(status(p))` or `is_fifo(status(p, ec))`,
|
| 9588 |
+
respectively. The signature with argument `ec` returns `false` if an
|
| 9589 |
+
error occurs.
|
| 9590 |
+
|
| 9591 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9592 |
+
|
| 9593 |
+
#### Is other <a id="fs.op.is_other">[[fs.op.is_other]]</a>
|
| 9594 |
+
|
| 9595 |
+
``` cpp
|
| 9596 |
+
bool is_other(file_status s) noexcept;
|
| 9597 |
+
```
|
| 9598 |
+
|
| 9599 |
+
*Returns:*
|
| 9600 |
+
`exists(s) && !is_regular_file(s) && !is_directory(s) && !is_symlink(s)`.
|
| 9601 |
+
|
| 9602 |
+
``` cpp
|
| 9603 |
+
bool is_other(const path& p);
|
| 9604 |
+
bool is_other(const path& p, error_code& ec) noexcept;
|
| 9605 |
+
```
|
| 9606 |
+
|
| 9607 |
+
*Returns:* `is_other(status(p))` or `is_other(status(p, ec))`,
|
| 9608 |
+
respectively. The signature with argument `ec` returns `false` if an
|
| 9609 |
+
error occurs.
|
| 9610 |
+
|
| 9611 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9612 |
+
|
| 9613 |
+
#### Is regular file <a id="fs.op.is_regular_file">[[fs.op.is_regular_file]]</a>
|
| 9614 |
+
|
| 9615 |
+
``` cpp
|
| 9616 |
+
bool is_regular_file(file_status s) noexcept;
|
| 9617 |
+
```
|
| 9618 |
+
|
| 9619 |
+
*Returns:* `s.type() == file_type::regular`.
|
| 9620 |
+
|
| 9621 |
+
``` cpp
|
| 9622 |
+
bool is_regular_file(const path& p);
|
| 9623 |
+
```
|
| 9624 |
+
|
| 9625 |
+
*Returns:* `is_regular_file(status(p))`.
|
| 9626 |
+
|
| 9627 |
+
*Throws:* `filesystem_error` if `status(p)` would throw
|
| 9628 |
+
`filesystem_error.`
|
| 9629 |
+
|
| 9630 |
+
``` cpp
|
| 9631 |
+
bool is_regular_file(const path& p, error_code& ec) noexcept;
|
| 9632 |
+
```
|
| 9633 |
+
|
| 9634 |
+
*Effects:* Sets `ec` as if by `status(p, ec)`.
|
| 9635 |
+
|
| 9636 |
+
[*Note 1*: `file_type::none`, `file_type::not_found` and
|
| 9637 |
+
`file_type::unknown` cases set `ec` to error values. To distinguish
|
| 9638 |
+
between cases, call the `status` function directly. — *end note*]
|
| 9639 |
+
|
| 9640 |
+
*Returns:* `is_regular_file(status(p, ec))`. Returns `false` if an error
|
| 9641 |
+
occurs.
|
| 9642 |
+
|
| 9643 |
+
#### Is socket <a id="fs.op.is_socket">[[fs.op.is_socket]]</a>
|
| 9644 |
+
|
| 9645 |
+
``` cpp
|
| 9646 |
+
bool is_socket(file_status s) noexcept;
|
| 9647 |
+
```
|
| 9648 |
+
|
| 9649 |
+
*Returns:* `s.type() == file_type::socket`.
|
| 9650 |
+
|
| 9651 |
+
``` cpp
|
| 9652 |
+
bool is_socket(const path& p);
|
| 9653 |
+
bool is_socket(const path& p, error_code& ec) noexcept;
|
| 9654 |
+
```
|
| 9655 |
+
|
| 9656 |
+
*Returns:* `is_socket(status(p))` or `is_socket(status(p, ec))`,
|
| 9657 |
+
respectively. The signature with argument `ec` returns `false` if an
|
| 9658 |
+
error occurs.
|
| 9659 |
+
|
| 9660 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9661 |
+
|
| 9662 |
+
#### Is symlink <a id="fs.op.is_symlink">[[fs.op.is_symlink]]</a>
|
| 9663 |
+
|
| 9664 |
+
``` cpp
|
| 9665 |
+
bool is_symlink(file_status s) noexcept;
|
| 9666 |
+
```
|
| 9667 |
+
|
| 9668 |
+
*Returns:* `s.type() == file_type::symlink`.
|
| 9669 |
+
|
| 9670 |
+
``` cpp
|
| 9671 |
+
bool is_symlink(const path& p);
|
| 9672 |
+
bool is_symlink(const path& p, error_code& ec) noexcept;
|
| 9673 |
+
```
|
| 9674 |
+
|
| 9675 |
+
*Returns:* `is_symlink(symlink_status(p))` or
|
| 9676 |
+
`is_symlink(symlink_status(p, ec))`, respectively. The signature with
|
| 9677 |
+
argument `ec` returns `false` if an error occurs.
|
| 9678 |
+
|
| 9679 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9680 |
+
|
| 9681 |
+
#### Last write time <a id="fs.op.last_write_time">[[fs.op.last_write_time]]</a>
|
| 9682 |
+
|
| 9683 |
+
``` cpp
|
| 9684 |
+
file_time_type last_write_time(const path& p);
|
| 9685 |
+
file_time_type last_write_time(const path& p, error_code& ec) noexcept;
|
| 9686 |
+
```
|
| 9687 |
+
|
| 9688 |
+
*Returns:* The time of last data modification of `p`, determined as if
|
| 9689 |
+
by the value of the POSIX `stat` structure member `st_mtime` obtained as
|
| 9690 |
+
if by POSIX `stat()`. The signature with argument `ec` returns
|
| 9691 |
+
`file_time_type::min()` if an error occurs.
|
| 9692 |
+
|
| 9693 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9694 |
+
|
| 9695 |
+
``` cpp
|
| 9696 |
+
void last_write_time(const path& p, file_time_type new_time);
|
| 9697 |
+
void last_write_time(const path& p, file_time_type new_time,
|
| 9698 |
+
error_code& ec) noexcept;
|
| 9699 |
+
```
|
| 9700 |
+
|
| 9701 |
+
*Effects:* Sets the time of last data modification of the file resolved
|
| 9702 |
+
to by `p` to `new_time`, as if by POSIX `futimens()`.
|
| 9703 |
+
|
| 9704 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9705 |
+
|
| 9706 |
+
[*Note 1*: A postcondition of `last_write_time(p) == new_time` is not
|
| 9707 |
+
specified since it might not hold for file systems with coarse time
|
| 9708 |
+
granularity. — *end note*]
|
| 9709 |
+
|
| 9710 |
+
#### Permissions <a id="fs.op.permissions">[[fs.op.permissions]]</a>
|
| 9711 |
+
|
| 9712 |
+
``` cpp
|
| 9713 |
+
void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
|
| 9714 |
+
void permissions(const path& p, perms prms, error_code& ec) noexcept;
|
| 9715 |
+
void permissions(const path& p, perms prms, perm_options opts, error_code& ec);
|
| 9716 |
+
```
|
| 9717 |
+
|
| 9718 |
+
*Requires:* Exactly one of the `perm_options` constants `replace`,
|
| 9719 |
+
`add`, or `remove` is present in `opts`.
|
| 9720 |
+
|
| 9721 |
+
*Remarks:* The second signature behaves as if it had an additional
|
| 9722 |
+
parameter `perm_options` `opts` with an argument of
|
| 9723 |
+
`perm_options::replace`.
|
| 9724 |
+
|
| 9725 |
+
*Effects:* Applies the action specified by `opts` to the file `p`
|
| 9726 |
+
resolves to, or to file `p` itself if `p` is a symbolic link and
|
| 9727 |
+
`perm_options::nofollow` is set in `opts`. The action is applied as if
|
| 9728 |
+
by POSIX `fchmodat()`.
|
| 9729 |
+
|
| 9730 |
+
[*Note 1*: Conceptually permissions are viewed as bits, but the actual
|
| 9731 |
+
implementation may use some other mechanism. — *end note*]
|
| 9732 |
+
|
| 9733 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9734 |
+
|
| 9735 |
+
#### Proximate <a id="fs.op.proximate">[[fs.op.proximate]]</a>
|
| 9736 |
+
|
| 9737 |
+
``` cpp
|
| 9738 |
+
path proximate(const path& p, error_code& ec);
|
| 9739 |
+
```
|
| 9740 |
+
|
| 9741 |
+
*Returns:* `proximate(p, current_path(), ec)`.
|
| 9742 |
+
|
| 9743 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9744 |
+
|
| 9745 |
+
``` cpp
|
| 9746 |
+
path proximate(const path& p, const path& base = current_path());
|
| 9747 |
+
path proximate(const path& p, const path& base, error_code& ec);
|
| 9748 |
+
```
|
| 9749 |
+
|
| 9750 |
+
*Returns:* For the first form:
|
| 9751 |
+
|
| 9752 |
+
``` cpp
|
| 9753 |
+
weakly_canonical(p).lexically_proximate(weakly_canonical(base));
|
| 9754 |
+
```
|
| 9755 |
+
|
| 9756 |
+
For the second form:
|
| 9757 |
+
|
| 9758 |
+
``` cpp
|
| 9759 |
+
weakly_canonical(p, ec).lexically_proximate(weakly_canonical(base, ec));
|
| 9760 |
+
```
|
| 9761 |
+
|
| 9762 |
+
or `path()` at the first error occurrence, if any.
|
| 9763 |
+
|
| 9764 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9765 |
+
|
| 9766 |
+
#### Read symlink <a id="fs.op.read_symlink">[[fs.op.read_symlink]]</a>
|
| 9767 |
+
|
| 9768 |
+
``` cpp
|
| 9769 |
+
path read_symlink(const path& p);
|
| 9770 |
+
path read_symlink(const path& p, error_code& ec);
|
| 9771 |
+
```
|
| 9772 |
+
|
| 9773 |
+
*Returns:* If `p` resolves to a symbolic link, a `path` object
|
| 9774 |
+
containing the contents of that symbolic link. The signature with
|
| 9775 |
+
argument `ec` returns `path()` if an error occurs.
|
| 9776 |
+
|
| 9777 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9778 |
+
|
| 9779 |
+
[*Note 1*: It is an error if `p` does not resolve to a symbolic
|
| 9780 |
+
link. — *end note*]
|
| 9781 |
+
|
| 9782 |
+
#### Relative <a id="fs.op.relative">[[fs.op.relative]]</a>
|
| 9783 |
+
|
| 9784 |
+
``` cpp
|
| 9785 |
+
path relative(const path& p, error_code& ec);
|
| 9786 |
+
```
|
| 9787 |
+
|
| 9788 |
+
*Returns:* `relative(p, current_path(), ec)`.
|
| 9789 |
+
|
| 9790 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9791 |
+
|
| 9792 |
+
``` cpp
|
| 9793 |
+
path relative(const path& p, const path& base = current_path());
|
| 9794 |
+
path relative(const path& p, const path& base, error_code& ec);
|
| 9795 |
+
```
|
| 9796 |
+
|
| 9797 |
+
*Returns:* For the first form:
|
| 9798 |
+
|
| 9799 |
+
``` cpp
|
| 9800 |
+
weakly_canonical(p).lexically_relative(weakly_canonical(base));
|
| 9801 |
+
```
|
| 9802 |
+
|
| 9803 |
+
For the second form:
|
| 9804 |
+
|
| 9805 |
+
``` cpp
|
| 9806 |
+
weakly_canonical(p, ec).lexically_relative(weakly_canonical(base, ec));
|
| 9807 |
+
```
|
| 9808 |
+
|
| 9809 |
+
or `path()` at the first error occurrence, if any.
|
| 9810 |
+
|
| 9811 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9812 |
+
|
| 9813 |
+
#### Remove <a id="fs.op.remove">[[fs.op.remove]]</a>
|
| 9814 |
+
|
| 9815 |
+
``` cpp
|
| 9816 |
+
bool remove(const path& p);
|
| 9817 |
+
bool remove(const path& p, error_code& ec) noexcept;
|
| 9818 |
+
```
|
| 9819 |
+
|
| 9820 |
+
*Effects:* If `exists(symlink_status(p, ec))`, the file `p` is removed
|
| 9821 |
+
as if by POSIX `remove()`.
|
| 9822 |
+
|
| 9823 |
+
[*Note 1*: A symbolic link is itself removed, rather than the file it
|
| 9824 |
+
resolves to. — *end note*]
|
| 9825 |
+
|
| 9826 |
+
*Postconditions:* `!exists(symlink_status(p))`.
|
| 9827 |
+
|
| 9828 |
+
*Returns:* `false` if `p` did not exist, otherwise `true`. The signature
|
| 9829 |
+
with argument `ec` returns `false` if an error occurs.
|
| 9830 |
+
|
| 9831 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9832 |
+
|
| 9833 |
+
#### Remove all <a id="fs.op.remove_all">[[fs.op.remove_all]]</a>
|
| 9834 |
+
|
| 9835 |
+
``` cpp
|
| 9836 |
+
uintmax_t remove_all(const path& p);
|
| 9837 |
+
uintmax_t remove_all(const path& p, error_code& ec) noexcept;
|
| 9838 |
+
```
|
| 9839 |
+
|
| 9840 |
+
*Effects:* Recursively deletes the contents of `p` if it exists, then
|
| 9841 |
+
deletes file `p` itself, as if by POSIX `remove()`.
|
| 9842 |
+
|
| 9843 |
+
[*Note 1*: A symbolic link is itself removed, rather than the file it
|
| 9844 |
+
resolves to. — *end note*]
|
| 9845 |
+
|
| 9846 |
+
*Postconditions:* `!exists(symlink_status(p))`.
|
| 9847 |
+
|
| 9848 |
+
*Returns:* The number of files removed. The signature with argument `ec`
|
| 9849 |
+
returns `static_cast< uintmax_t>(-1)` if an error occurs.
|
| 9850 |
+
|
| 9851 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9852 |
+
|
| 9853 |
+
#### Rename <a id="fs.op.rename">[[fs.op.rename]]</a>
|
| 9854 |
+
|
| 9855 |
+
``` cpp
|
| 9856 |
+
void rename(const path& old_p, const path& new_p);
|
| 9857 |
+
void rename(const path& old_p, const path& new_p, error_code& ec) noexcept;
|
| 9858 |
+
```
|
| 9859 |
+
|
| 9860 |
+
*Effects:* Renames `old_p` to `new_p`, as if by POSIX `rename()`.
|
| 9861 |
+
|
| 9862 |
+
[*Note 1*:
|
| 9863 |
+
|
| 9864 |
+
- If `old_p` and `new_p` resolve to the same existing file, no action is
|
| 9865 |
+
taken.
|
| 9866 |
+
- Otherwise, the rename may include the following effects:
|
| 9867 |
+
- if `new_p` resolves to an existing non-directory file, `new_p` is
|
| 9868 |
+
removed; otherwise,
|
| 9869 |
+
- if `new_p` resolves to an existing directory, `new_p` is removed if
|
| 9870 |
+
empty on POSIX compliant operating systems but may be an error on
|
| 9871 |
+
other operating systems.
|
| 9872 |
+
|
| 9873 |
+
A symbolic link is itself renamed, rather than the file it resolves to.
|
| 9874 |
+
|
| 9875 |
+
— *end note*]
|
| 9876 |
+
|
| 9877 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9878 |
+
|
| 9879 |
+
#### Resize file <a id="fs.op.resize_file">[[fs.op.resize_file]]</a>
|
| 9880 |
+
|
| 9881 |
+
``` cpp
|
| 9882 |
+
void resize_file(const path& p, uintmax_t new_size);
|
| 9883 |
+
void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;
|
| 9884 |
+
```
|
| 9885 |
+
|
| 9886 |
+
*Postconditions:* `file_size(p) == new_size`.
|
| 9887 |
+
|
| 9888 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9889 |
+
|
| 9890 |
+
*Remarks:* Achieves its postconditions as if by POSIX `truncate()`.
|
| 9891 |
+
|
| 9892 |
+
#### Space <a id="fs.op.space">[[fs.op.space]]</a>
|
| 9893 |
+
|
| 9894 |
+
``` cpp
|
| 9895 |
+
space_info space(const path& p);
|
| 9896 |
+
space_info space(const path& p, error_code& ec) noexcept;
|
| 9897 |
+
```
|
| 9898 |
+
|
| 9899 |
+
*Returns:* An object of type `space_info`. The value of the `space_info`
|
| 9900 |
+
object is determined as if by using POSIX `statvfs` to obtain a POSIX
|
| 9901 |
+
`struct statvfs`, and then multiplying its `f_blocks`, `f_bfree`, and
|
| 9902 |
+
`f_bavail` members by its `f_frsize` member, and assigning the results
|
| 9903 |
+
to the `capacity`, `free`, and `available` members respectively. Any
|
| 9904 |
+
members for which the value cannot be determined shall be set to
|
| 9905 |
+
`static_cast<uintmax_t>(-1)`. For the signature with argument `ec`, all
|
| 9906 |
+
members are set to `static_cast<uintmax_t>(-1)` if an error occurs.
|
| 9907 |
+
|
| 9908 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 9909 |
+
|
| 9910 |
+
*Remarks:* The value of member `space_info::available` is operating
|
| 9911 |
+
system dependent.
|
| 9912 |
+
|
| 9913 |
+
[*Note 1*: `available` may be less than `free`. — *end note*]
|
| 9914 |
+
|
| 9915 |
+
#### Status <a id="fs.op.status">[[fs.op.status]]</a>
|
| 9916 |
+
|
| 9917 |
+
``` cpp
|
| 9918 |
+
file_status status(const path& p);
|
| 9919 |
+
```
|
| 9920 |
+
|
| 9921 |
+
*Effects:* As if:
|
| 9922 |
+
|
| 9923 |
+
``` cpp
|
| 9924 |
+
error_code ec;
|
| 9925 |
+
file_status result = status(p, ec);
|
| 9926 |
+
if (result.type() == file_type::none)
|
| 9927 |
+
throw filesystem_error(implementation-supplied-message, p, ec);
|
| 9928 |
+
return result;
|
| 9929 |
+
```
|
| 9930 |
+
|
| 9931 |
+
*Returns:* See above.
|
| 9932 |
+
|
| 9933 |
+
*Throws:* `filesystem_error`.
|
| 9934 |
+
|
| 9935 |
+
[*Note 1*: `result` values of `file_status(file_type::not_found)` and
|
| 9936 |
+
`file_status(file_type::unknown)` are not considered failures and do not
|
| 9937 |
+
cause an exception to be thrown. — *end note*]
|
| 9938 |
+
|
| 9939 |
+
``` cpp
|
| 9940 |
+
file_status status(const path& p, error_code& ec) noexcept;
|
| 9941 |
+
```
|
| 9942 |
+
|
| 9943 |
+
*Effects:* If possible, determines the attributes of the file `p`
|
| 9944 |
+
resolves to, as if by using POSIX `stat()` to obtain a POSIX
|
| 9945 |
+
`struct stat`. If, during attribute determination, the underlying file
|
| 9946 |
+
system API reports an error, sets `ec` to indicate the specific error
|
| 9947 |
+
reported. Otherwise, `ec.clear()`.
|
| 9948 |
+
|
| 9949 |
+
[*Note 2*: This allows users to inspect the specifics of underlying API
|
| 9950 |
+
errors even when the value returned by `status()` is not
|
| 9951 |
+
`file_status(file_type::none)`. — *end note*]
|
| 9952 |
+
|
| 9953 |
+
Let `prms` denote the result of `(m & perms::mask)`, where `m` is
|
| 9954 |
+
determined as if by converting the `st_mode` member of the obtained
|
| 9955 |
+
`struct stat` to the type `perms`.
|
| 9956 |
+
|
| 9957 |
+
*Returns:*
|
| 9958 |
+
|
| 9959 |
+
- If `ec != error_code()`:
|
| 9960 |
+
- If the specific error indicates that `p` cannot be resolved because
|
| 9961 |
+
some element of the path does not exist, returns
|
| 9962 |
+
`file_status(file_type::not_found)`.
|
| 9963 |
+
- Otherwise, if the specific error indicates that `p` can be resolved
|
| 9964 |
+
but the attributes cannot be determined, returns
|
| 9965 |
+
`file_status(file_type::unknown)`.
|
| 9966 |
+
- Otherwise, returns `file_status(file_type::none)`.
|
| 9967 |
+
|
| 9968 |
+
\[*Note 1*: These semantics distinguish between `p` being known not to
|
| 9969 |
+
exist, `p` existing but not being able to determine its attributes,
|
| 9970 |
+
and there being an error that prevents even knowing if `p` exists.
|
| 9971 |
+
These distinctions are important to some use cases. — *end note*]
|
| 9972 |
+
- Otherwise,
|
| 9973 |
+
- If the attributes indicate a regular file, as if by POSIX `S_ISREG`,
|
| 9974 |
+
returns `file_status(file_type::regular, prms)`.
|
| 9975 |
+
\[*Note 2*: `file_type::regular` implies appropriate `<fstream>`
|
| 9976 |
+
operations would succeed, assuming no hardware, permission, access,
|
| 9977 |
+
or file system race errors. Lack of `file_type::regular` does not
|
| 9978 |
+
necessarily imply `<fstream>` operations would fail on a
|
| 9979 |
+
directory. — *end note*]
|
| 9980 |
+
- Otherwise, if the attributes indicate a directory, as if by POSIX
|
| 9981 |
+
`S_ISDIR`, returns `file_status(file_type::directory, prms)`.
|
| 9982 |
+
\[*Note 3*: `file_type::directory` implies that calling
|
| 9983 |
+
`directory_iterator(p)` would succeed. — *end note*]
|
| 9984 |
+
- Otherwise, if the attributes indicate a block special file, as if by
|
| 9985 |
+
POSIX `S_ISBLK`, returns `file_status(file_type::block, prms)`.
|
| 9986 |
+
- Otherwise, if the attributes indicate a character special file, as
|
| 9987 |
+
if by POSIX `S_ISCHR`, returns
|
| 9988 |
+
`file_status(file_type::character, prms)`.
|
| 9989 |
+
- Otherwise, if the attributes indicate a fifo or pipe file, as if by
|
| 9990 |
+
POSIX `S_ISFIFO`, returns `file_status(file_type::fifo, prms)`.
|
| 9991 |
+
- Otherwise, if the attributes indicate a socket, as if by POSIX
|
| 9992 |
+
`S_ISSOCK`, returns `file_status(file_type::socket, prms)`.
|
| 9993 |
+
- Otherwise, if the attributes indicate an implementation-defined file
|
| 9994 |
+
type ([[fs.enum.file_type]]), returns
|
| 9995 |
+
`file_status(file_type::`*`A`*`, prms)`, where *A* is the constant
|
| 9996 |
+
for the *implementation-defined* file type.
|
| 9997 |
+
- Otherwise, returns `file_status(file_type::unknown, prms)`.
|
| 9998 |
+
|
| 9999 |
+
*Remarks:* If a symbolic link is encountered during pathname resolution,
|
| 10000 |
+
pathname resolution continues using the contents of the symbolic link.
|
| 10001 |
+
|
| 10002 |
+
#### Status known <a id="fs.op.status_known">[[fs.op.status_known]]</a>
|
| 10003 |
+
|
| 10004 |
+
``` cpp
|
| 10005 |
+
bool status_known(file_status s) noexcept;
|
| 10006 |
+
```
|
| 10007 |
+
|
| 10008 |
+
*Returns:* `s.type() != file_type::none`.
|
| 10009 |
+
|
| 10010 |
+
#### Symlink status <a id="fs.op.symlink_status">[[fs.op.symlink_status]]</a>
|
| 10011 |
+
|
| 10012 |
+
``` cpp
|
| 10013 |
+
file_status symlink_status(const path& p);
|
| 10014 |
+
file_status symlink_status(const path& p, error_code& ec) noexcept;
|
| 10015 |
+
```
|
| 10016 |
+
|
| 10017 |
+
*Effects:* Same as `status()`, above, except that the attributes of `p`
|
| 10018 |
+
are determined as if by using POSIX `lstat()` to obtain a POSIX
|
| 10019 |
+
`struct stat`.
|
| 10020 |
+
|
| 10021 |
+
Let `prms` denote the result of `(m & perms::mask)`, where `m` is
|
| 10022 |
+
determined as if by converting the `st_mode` member of the obtained
|
| 10023 |
+
`struct stat` to the type `perms`.
|
| 10024 |
+
|
| 10025 |
+
*Returns:* Same as `status()`, above, except that if the attributes
|
| 10026 |
+
indicate a symbolic link, as if by POSIX `S_ISLNK`, returns
|
| 10027 |
+
`file_status(file_type::symlink, prms)`. The signature with argument
|
| 10028 |
+
`ec` returns `file_status(file_type::none)` if an error occurs.
|
| 10029 |
+
|
| 10030 |
+
*Remarks:* Pathname resolution terminates if `p` names a symbolic link.
|
| 10031 |
+
|
| 10032 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 10033 |
+
|
| 10034 |
+
#### Temporary directory path <a id="fs.op.temp_dir_path">[[fs.op.temp_dir_path]]</a>
|
| 10035 |
+
|
| 10036 |
+
``` cpp
|
| 10037 |
+
path temp_directory_path();
|
| 10038 |
+
path temp_directory_path(error_code& ec);
|
| 10039 |
+
```
|
| 10040 |
+
|
| 10041 |
+
*Returns:* An unspecifed directory path suitable for temporary files. An
|
| 10042 |
+
error shall be reported if `!exists(p) || !is_directory(p)`, where `p`
|
| 10043 |
+
is the path to be returned. The signature with argument `ec` returns
|
| 10044 |
+
`path()` if an error occurs.
|
| 10045 |
+
|
| 10046 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 10047 |
+
|
| 10048 |
+
[*Example 1*: For POSIX-based operating systems, an implementation
|
| 10049 |
+
might return the path supplied by the first environment variable found
|
| 10050 |
+
in the list TMPDIR, TMP, TEMP, TEMPDIR, or if none of these are found,
|
| 10051 |
+
`"/tmp"`. For Windows-based operating systems, an implementation might
|
| 10052 |
+
return the path reported by the Windows `GetTempPath` API
|
| 10053 |
+
function. — *end example*]
|
| 10054 |
+
|
| 10055 |
+
#### Weakly canonical <a id="fs.op.weakly_canonical">[[fs.op.weakly_canonical]]</a>
|
| 10056 |
+
|
| 10057 |
+
``` cpp
|
| 10058 |
+
path weakly_canonical(const path& p);
|
| 10059 |
+
path weakly_canonical(const path& p, error_code& ec);
|
| 10060 |
+
```
|
| 10061 |
+
|
| 10062 |
+
*Returns:* `p` with symlinks resolved and the result
|
| 10063 |
+
normalized ([[fs.def.normal.form]]).
|
| 10064 |
+
|
| 10065 |
+
*Effects:* Using `status(p)` or `status(p, ec)`, respectively, to
|
| 10066 |
+
determine existence, return a path composed by `operator/=` from the
|
| 10067 |
+
result of calling `canonical()` without a `base` argument and with a
|
| 10068 |
+
path argument composed of the leading elements of `p` that exist, if
|
| 10069 |
+
any, followed by the elements of `p` that do not exist, if any. For the
|
| 10070 |
+
first form, `canonical()` is called without an `error_code` argument.
|
| 10071 |
+
For the second form, `canonical()` is called with `ec` as an
|
| 10072 |
+
`error_code` argument, and `path()` is returned at the first error
|
| 10073 |
+
occurrence, if any.
|
| 10074 |
+
|
| 10075 |
+
*Postconditions:* The returned path is in normal
|
| 10076 |
+
form ([[fs.def.normal.form]]).
|
| 10077 |
+
|
| 10078 |
+
*Remarks:* Implementations are encouraged to avoid unnecessary
|
| 10079 |
+
normalization such as when `canonical` has already been called on the
|
| 10080 |
+
entirety of `p`.
|
| 10081 |
+
|
| 10082 |
+
*Throws:* As specified in [[fs.err.report]].
|
| 10083 |
+
|
| 10084 |
+
## C library files <a id="c.files">[[c.files]]</a>
|
| 10085 |
+
|
| 10086 |
+
### Header `<cstdio>` synopsis <a id="cstdio.syn">[[cstdio.syn]]</a>
|
| 10087 |
+
|
| 10088 |
+
``` cpp
|
| 10089 |
+
namespace std {
|
| 10090 |
+
using size_t = see [support.types.layout];
|
| 10091 |
+
using FILE = see below;
|
| 10092 |
+
using fpos_t = see below;
|
| 10093 |
+
}
|
| 10094 |
+
|
| 10095 |
+
#define NULL see [support.types.nullptr]
|
| 10096 |
+
#define _IOFBF see below
|
| 10097 |
+
#define _IOLBF see below
|
| 10098 |
+
#define _IONBF see below
|
| 10099 |
+
#define BUFSIZ see below
|
| 10100 |
+
#define EOF see below
|
| 10101 |
+
#define FOPEN_MAX see below
|
| 10102 |
+
#define FILENAME_MAX see below
|
| 10103 |
+
#define L_tmpnam see below
|
| 10104 |
+
#define SEEK_CUR see below
|
| 10105 |
+
#define SEEK_END see below
|
| 10106 |
+
#define SEEK_SET see below
|
| 10107 |
+
#define TMP_MAX see below
|
| 10108 |
+
#define stderr see below
|
| 10109 |
+
#define stdin see below
|
| 10110 |
+
#define stdout see below
|
| 10111 |
+
|
| 10112 |
+
namespace std {
|
| 10113 |
+
int remove(const char* filename);
|
| 10114 |
+
int rename(const char* old, const char* new);
|
| 10115 |
+
FILE* tmpfile();
|
| 10116 |
+
char* tmpnam(char* s);
|
| 10117 |
+
int fclose(FILE* stream);
|
| 10118 |
+
int fflush(FILE* stream);
|
| 10119 |
+
FILE* fopen(const char* filename, const char* mode);
|
| 10120 |
+
FILE* freopen(const char* filename, const char* mode, FILE* stream);
|
| 10121 |
+
void setbuf(FILE* stream, char* buf);
|
| 10122 |
+
int setvbuf(FILE* stream, char* buf, int mode, size_t size);
|
| 10123 |
+
int fprintf(FILE* stream, const char* format, ...);
|
| 10124 |
+
int fscanf(FILE* stream, const char* format, ...);
|
| 10125 |
+
int printf(const char* format, ...);
|
| 10126 |
+
int scanf(const char* format, ...);
|
| 10127 |
+
int snprintf(char* s, size_t n, const char* format, ...);
|
| 10128 |
+
int sprintf(char* s, const char* format, ...);
|
| 10129 |
+
int sscanf(const char* s, const char* format, ...);
|
| 10130 |
+
int vfprintf(FILE* stream, const char* format, va_list arg);
|
| 10131 |
+
int vfscanf(FILE* stream, const char* format, va_list arg);
|
| 10132 |
+
int vprintf(const char* format, va_list arg);
|
| 10133 |
+
int vscanf(const char* format, va_list arg);
|
| 10134 |
+
int vsnprintf(char* s, size_t n, const char* format, va_list arg);
|
| 10135 |
+
int vsprintf(char* s, const char* format, va_list arg);
|
| 10136 |
+
int vsscanf(const char* s, const char* format, va_list arg);
|
| 10137 |
+
int fgetc(FILE* stream);
|
| 10138 |
+
char* fgets(char* s, int n, FILE* stream);
|
| 10139 |
+
int fputc(int c, FILE* stream);
|
| 10140 |
+
int fputs(const char* s, FILE* stream);
|
| 10141 |
+
int getc(FILE* stream);
|
| 10142 |
+
int getchar();
|
| 10143 |
+
int putc(int c, FILE* stream);
|
| 10144 |
+
int putchar(int c);
|
| 10145 |
+
int puts(const char* s);
|
| 10146 |
+
int ungetc(int c, FILE* stream);
|
| 10147 |
+
size_t fread(void* ptr, size_t size, size_t nmemb, FILE* stream);
|
| 10148 |
+
size_t fwrite(const void* ptr, size_t size, size_t nmemb, FILE* stream);
|
| 10149 |
+
int fgetpos(FILE* stream, fpos_t* pos);
|
| 10150 |
+
int fseek(FILE* stream, long int offset, int whence);
|
| 10151 |
+
int fsetpos(FILE* stream, const fpos_t* pos);
|
| 10152 |
+
long int ftell(FILE* stream);
|
| 10153 |
+
void rewind(FILE* stream);
|
| 10154 |
+
void clearerr(FILE* stream);
|
| 10155 |
+
int feof(FILE* stream);
|
| 10156 |
+
int ferror(FILE* stream);
|
| 10157 |
+
void perror(const char* s);
|
| 10158 |
+
}
|
| 10159 |
+
```
|
| 10160 |
+
|
| 10161 |
+
The contents and meaning of the header `<cstdio>` are the same as the C
|
| 10162 |
+
standard library header `<stdio.h>`.
|
| 10163 |
+
|
| 10164 |
+
Calls to the function `tmpnam` with an argument that is a null pointer
|
| 10165 |
+
value may introduce a data race ([[res.on.data.races]]) with other
|
| 10166 |
+
calls to `tmpnam` with an argument that is a null pointer value.
|
| 10167 |
+
|
| 10168 |
+
ISO C 7.21.
|
| 10169 |
+
|
| 10170 |
+
### Header `<cinttypes>` synopsis <a id="cinttypes.syn">[[cinttypes.syn]]</a>
|
| 10171 |
+
|
| 10172 |
+
``` cpp
|
| 10173 |
+
#include <cstdint> // see [cstdint.syn]
|
| 10174 |
+
|
| 10175 |
+
namespace std {
|
| 10176 |
+
using imaxdiv_t = see below;
|
| 10177 |
+
|
| 10178 |
+
intmax_t imaxabs(intmax_t j);
|
| 10179 |
+
imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
|
| 10180 |
+
intmax_t strtoimax(const char* nptr, char** endptr, int base);
|
| 10181 |
+
uintmax_t strtoumax(const char* nptr, char** endptr, int base);
|
| 10182 |
+
intmax_t wcstoimax(const wchar_t* nptr, wchar_t** endptr, int base);
|
| 10183 |
+
uintmax_t wcstoumax(const wchar_t* nptr, wchar_t** endptr, int base);
|
| 10184 |
+
|
| 10185 |
+
intmax_t abs(intmax_t); // optional, see below
|
| 10186 |
+
imaxdiv_t div(intmax_t, intmax_t); // optional, see below
|
| 10187 |
+
}
|
| 10188 |
+
|
| 10189 |
+
#define PRIdN see below
|
| 10190 |
+
#define PRIiN see below
|
| 10191 |
+
#define PRIoN see below
|
| 10192 |
+
#define PRIuN see below
|
| 10193 |
+
#define PRIxN see below
|
| 10194 |
+
#define PRIXN see below
|
| 10195 |
+
#define SCNdN see below
|
| 10196 |
+
#define SCNiN see below
|
| 10197 |
+
#define SCNoN see below
|
| 10198 |
+
#define SCNuN see below
|
| 10199 |
+
#define SCNxN see below
|
| 10200 |
+
#define PRIdLEASTN see below
|
| 10201 |
+
#define PRIiLEASTN see below
|
| 10202 |
+
#define PRIoLEASTN see below
|
| 10203 |
+
#define PRIuLEASTN see below
|
| 10204 |
+
#define PRIxLEASTN see below
|
| 10205 |
+
#define PRIXLEASTN see below
|
| 10206 |
+
#define SCNdLEASTN see below
|
| 10207 |
+
#define SCNiLEASTN see below
|
| 10208 |
+
#define SCNoLEASTN see below
|
| 10209 |
+
#define SCNuLEASTN see below
|
| 10210 |
+
#define SCNxLEASTN see below
|
| 10211 |
+
#define PRIdFASTN see below
|
| 10212 |
+
#define PRIiFASTN see below
|
| 10213 |
+
#define PRIoFASTN see below
|
| 10214 |
+
#define PRIuFASTN see below
|
| 10215 |
+
#define PRIxFASTN see below
|
| 10216 |
+
#define PRIXFASTN see below
|
| 10217 |
+
#define SCNdFASTN see below
|
| 10218 |
+
#define SCNiFASTN see below
|
| 10219 |
+
#define SCNoFASTN see below
|
| 10220 |
+
#define SCNuFASTN see below
|
| 10221 |
+
#define SCNxFASTN see below
|
| 10222 |
+
#define PRIdMAX see below
|
| 10223 |
+
#define PRIiMAX see below
|
| 10224 |
+
#define PRIoMAX see below
|
| 10225 |
+
#define PRIuMAX see below
|
| 10226 |
+
#define PRIxMAX see below
|
| 10227 |
+
#define PRIXMAX see below
|
| 10228 |
+
#define SCNdMAX see below
|
| 10229 |
+
#define SCNiMAX see below
|
| 10230 |
+
#define SCNoMAX see below
|
| 10231 |
+
#define SCNuMAX see below
|
| 10232 |
+
#define SCNxMAX see below
|
| 10233 |
+
#define PRIdPTR see below
|
| 10234 |
+
#define PRIiPTR see below
|
| 10235 |
+
#define PRIoPTR see below
|
| 10236 |
+
#define PRIuPTR see below
|
| 10237 |
+
#define PRIxPTR see below
|
| 10238 |
+
#define PRIXPTR see below
|
| 10239 |
+
#define SCNdPTR see below
|
| 10240 |
+
#define SCNiPTR see below
|
| 10241 |
+
#define SCNoPTR see below
|
| 10242 |
+
#define SCNuPTR see below
|
| 10243 |
+
#define SCNxPTR see below
|
| 10244 |
+
```
|
| 10245 |
+
|
| 10246 |
+
The contents and meaning of the header `<cinttypes>` are the same as the
|
| 10247 |
+
C standard library header `<inttypes.h>`, with the following changes:
|
| 10248 |
+
|
| 10249 |
+
- The header `<cinttypes>` includes the header `<cstdint>` instead of
|
| 10250 |
`<stdint.h>`, and
|
| 10251 |
- if and only if the type `intmax_t` designates an extended integer
|
| 10252 |
type ([[basic.fundamental]]), the following function signatures are
|
| 10253 |
added:
|
| 10254 |
``` cpp
|
|
|
|
| 10258 |
|
| 10259 |
which shall have the same semantics as the function signatures
|
| 10260 |
`intmax_t imaxabs(intmax_t)` and
|
| 10261 |
`imaxdiv_t imaxdiv(intmax_t, intmax_t)`, respectively.
|
| 10262 |
|
| 10263 |
+
ISO C 7.8.
|
| 10264 |
+
|
| 10265 |
<!-- Link reference definitions -->
|
| 10266 |
[adjustfield.manip]: #adjustfield.manip
|
| 10267 |
+
[allocator.requirements]: library.md#allocator.requirements
|
| 10268 |
[basefield.manip]: #basefield.manip
|
| 10269 |
[basic.fundamental]: basic.md#basic.fundamental
|
| 10270 |
[basic.ios.cons]: #basic.ios.cons
|
| 10271 |
[basic.ios.members]: #basic.ios.members
|
| 10272 |
+
[basic.start.main]: basic.md#basic.start.main
|
| 10273 |
+
[bidirectional.iterators]: iterators.md#bidirectional.iterators
|
| 10274 |
[bitmask.types]: library.md#bitmask.types
|
| 10275 |
[c.files]: #c.files
|
| 10276 |
+
[cinttypes.syn]: #cinttypes.syn
|
| 10277 |
+
[cstdio.syn]: #cstdio.syn
|
| 10278 |
+
[defns.ntcts]: library.md#defns.ntcts
|
| 10279 |
[enumerated.types]: library.md#enumerated.types
|
| 10280 |
[error.reporting]: #error.reporting
|
| 10281 |
[ext.manip]: #ext.manip
|
| 10282 |
[fig:streampos]: #fig:streampos
|
| 10283 |
[file.streams]: #file.streams
|
| 10284 |
[filebuf]: #filebuf
|
| 10285 |
[filebuf.assign]: #filebuf.assign
|
| 10286 |
[filebuf.cons]: #filebuf.cons
|
| 10287 |
[filebuf.members]: #filebuf.members
|
| 10288 |
[filebuf.virtuals]: #filebuf.virtuals
|
| 10289 |
+
[filesystem_error.members]: #filesystem_error.members
|
| 10290 |
+
[filesystems]: #filesystems
|
| 10291 |
[floatfield.manip]: #floatfield.manip
|
| 10292 |
[fmtflags.manip]: #fmtflags.manip
|
| 10293 |
[fmtflags.state]: #fmtflags.state
|
| 10294 |
[fpos]: #fpos
|
| 10295 |
[fpos.members]: #fpos.members
|
| 10296 |
[fpos.operations]: #fpos.operations
|
| 10297 |
+
[fs.class.directory_entry]: #fs.class.directory_entry
|
| 10298 |
+
[fs.class.directory_iterator]: #fs.class.directory_iterator
|
| 10299 |
+
[fs.class.file_status]: #fs.class.file_status
|
| 10300 |
+
[fs.class.filesystem_error]: #fs.class.filesystem_error
|
| 10301 |
+
[fs.class.path]: #fs.class.path
|
| 10302 |
+
[fs.class.rec.dir.itr]: #fs.class.rec.dir.itr
|
| 10303 |
+
[fs.conform.9945]: #fs.conform.9945
|
| 10304 |
+
[fs.conform.os]: #fs.conform.os
|
| 10305 |
+
[fs.conformance]: #fs.conformance
|
| 10306 |
+
[fs.def.absolute.path]: #fs.def.absolute.path
|
| 10307 |
+
[fs.def.filename]: #fs.def.filename
|
| 10308 |
+
[fs.def.link]: #fs.def.link
|
| 10309 |
+
[fs.def.native]: #fs.def.native
|
| 10310 |
+
[fs.def.native.encode]: #fs.def.native.encode
|
| 10311 |
+
[fs.def.normal.form]: #fs.def.normal.form
|
| 10312 |
+
[fs.def.osdep]: #fs.def.osdep
|
| 10313 |
+
[fs.def.path]: #fs.def.path
|
| 10314 |
+
[fs.def.pathname]: #fs.def.pathname
|
| 10315 |
+
[fs.def.pathres]: #fs.def.pathres
|
| 10316 |
+
[fs.def.race]: #fs.def.race
|
| 10317 |
+
[fs.def.symlink]: #fs.def.symlink
|
| 10318 |
+
[fs.definitions]: #fs.definitions
|
| 10319 |
+
[fs.dir.entry.cons]: #fs.dir.entry.cons
|
| 10320 |
+
[fs.dir.entry.mods]: #fs.dir.entry.mods
|
| 10321 |
+
[fs.dir.entry.obs]: #fs.dir.entry.obs
|
| 10322 |
+
[fs.dir.itr.members]: #fs.dir.itr.members
|
| 10323 |
+
[fs.dir.itr.nonmembers]: #fs.dir.itr.nonmembers
|
| 10324 |
+
[fs.enum]: #fs.enum
|
| 10325 |
+
[fs.enum.copy.opts]: #fs.enum.copy.opts
|
| 10326 |
+
[fs.enum.dir.opts]: #fs.enum.dir.opts
|
| 10327 |
+
[fs.enum.file_type]: #fs.enum.file_type
|
| 10328 |
+
[fs.enum.path.format]: #fs.enum.path.format
|
| 10329 |
+
[fs.enum.perm.opts]: #fs.enum.perm.opts
|
| 10330 |
+
[fs.enum.perms]: #fs.enum.perms
|
| 10331 |
+
[fs.err.report]: #fs.err.report
|
| 10332 |
+
[fs.file_status.cons]: #fs.file_status.cons
|
| 10333 |
+
[fs.file_status.mods]: #fs.file_status.mods
|
| 10334 |
+
[fs.file_status.obs]: #fs.file_status.obs
|
| 10335 |
+
[fs.filesystem.syn]: #fs.filesystem.syn
|
| 10336 |
+
[fs.general]: #fs.general
|
| 10337 |
+
[fs.norm.ref]: #fs.norm.ref
|
| 10338 |
+
[fs.op.absolute]: #fs.op.absolute
|
| 10339 |
+
[fs.op.canonical]: #fs.op.canonical
|
| 10340 |
+
[fs.op.copy]: #fs.op.copy
|
| 10341 |
+
[fs.op.copy_file]: #fs.op.copy_file
|
| 10342 |
+
[fs.op.copy_symlink]: #fs.op.copy_symlink
|
| 10343 |
+
[fs.op.create_dir_symlk]: #fs.op.create_dir_symlk
|
| 10344 |
+
[fs.op.create_directories]: #fs.op.create_directories
|
| 10345 |
+
[fs.op.create_directory]: #fs.op.create_directory
|
| 10346 |
+
[fs.op.create_hard_lk]: #fs.op.create_hard_lk
|
| 10347 |
+
[fs.op.create_symlink]: #fs.op.create_symlink
|
| 10348 |
+
[fs.op.current_path]: #fs.op.current_path
|
| 10349 |
+
[fs.op.equivalent]: #fs.op.equivalent
|
| 10350 |
+
[fs.op.exists]: #fs.op.exists
|
| 10351 |
+
[fs.op.file_size]: #fs.op.file_size
|
| 10352 |
+
[fs.op.funcs]: #fs.op.funcs
|
| 10353 |
+
[fs.op.hard_lk_ct]: #fs.op.hard_lk_ct
|
| 10354 |
+
[fs.op.is_block_file]: #fs.op.is_block_file
|
| 10355 |
+
[fs.op.is_char_file]: #fs.op.is_char_file
|
| 10356 |
+
[fs.op.is_directory]: #fs.op.is_directory
|
| 10357 |
+
[fs.op.is_empty]: #fs.op.is_empty
|
| 10358 |
+
[fs.op.is_fifo]: #fs.op.is_fifo
|
| 10359 |
+
[fs.op.is_other]: #fs.op.is_other
|
| 10360 |
+
[fs.op.is_regular_file]: #fs.op.is_regular_file
|
| 10361 |
+
[fs.op.is_socket]: #fs.op.is_socket
|
| 10362 |
+
[fs.op.is_symlink]: #fs.op.is_symlink
|
| 10363 |
+
[fs.op.last_write_time]: #fs.op.last_write_time
|
| 10364 |
+
[fs.op.permissions]: #fs.op.permissions
|
| 10365 |
+
[fs.op.proximate]: #fs.op.proximate
|
| 10366 |
+
[fs.op.read_symlink]: #fs.op.read_symlink
|
| 10367 |
+
[fs.op.relative]: #fs.op.relative
|
| 10368 |
+
[fs.op.remove]: #fs.op.remove
|
| 10369 |
+
[fs.op.remove_all]: #fs.op.remove_all
|
| 10370 |
+
[fs.op.rename]: #fs.op.rename
|
| 10371 |
+
[fs.op.resize_file]: #fs.op.resize_file
|
| 10372 |
+
[fs.op.space]: #fs.op.space
|
| 10373 |
+
[fs.op.status]: #fs.op.status
|
| 10374 |
+
[fs.op.status_known]: #fs.op.status_known
|
| 10375 |
+
[fs.op.symlink_status]: #fs.op.symlink_status
|
| 10376 |
+
[fs.op.temp_dir_path]: #fs.op.temp_dir_path
|
| 10377 |
+
[fs.op.weakly_canonical]: #fs.op.weakly_canonical
|
| 10378 |
+
[fs.path.append]: #fs.path.append
|
| 10379 |
+
[fs.path.assign]: #fs.path.assign
|
| 10380 |
+
[fs.path.compare]: #fs.path.compare
|
| 10381 |
+
[fs.path.concat]: #fs.path.concat
|
| 10382 |
+
[fs.path.construct]: #fs.path.construct
|
| 10383 |
+
[fs.path.cvt]: #fs.path.cvt
|
| 10384 |
+
[fs.path.decompose]: #fs.path.decompose
|
| 10385 |
+
[fs.path.factory]: #fs.path.factory
|
| 10386 |
+
[fs.path.fmt.cvt]: #fs.path.fmt.cvt
|
| 10387 |
+
[fs.path.gen]: #fs.path.gen
|
| 10388 |
+
[fs.path.generic]: #fs.path.generic
|
| 10389 |
+
[fs.path.generic.obs]: #fs.path.generic.obs
|
| 10390 |
+
[fs.path.io]: #fs.path.io
|
| 10391 |
+
[fs.path.itr]: #fs.path.itr
|
| 10392 |
+
[fs.path.member]: #fs.path.member
|
| 10393 |
+
[fs.path.modifiers]: #fs.path.modifiers
|
| 10394 |
+
[fs.path.native.obs]: #fs.path.native.obs
|
| 10395 |
+
[fs.path.nonmember]: #fs.path.nonmember
|
| 10396 |
+
[fs.path.query]: #fs.path.query
|
| 10397 |
+
[fs.path.req]: #fs.path.req
|
| 10398 |
+
[fs.path.type.cvt]: #fs.path.type.cvt
|
| 10399 |
+
[fs.race.behavior]: #fs.race.behavior
|
| 10400 |
+
[fs.rec.dir.itr.members]: #fs.rec.dir.itr.members
|
| 10401 |
+
[fs.rec.dir.itr.nonmembers]: #fs.rec.dir.itr.nonmembers
|
| 10402 |
+
[fs.req]: #fs.req
|
| 10403 |
+
[fs.req.namespace]: #fs.req.namespace
|
| 10404 |
[fstream]: #fstream
|
| 10405 |
[fstream.assign]: #fstream.assign
|
| 10406 |
[fstream.cons]: #fstream.cons
|
| 10407 |
[fstream.members]: #fstream.members
|
| 10408 |
+
[fstream.syn]: #fstream.syn
|
| 10409 |
[ifstream]: #ifstream
|
| 10410 |
[ifstream.assign]: #ifstream.assign
|
| 10411 |
[ifstream.cons]: #ifstream.cons
|
| 10412 |
[ifstream.members]: #ifstream.members
|
| 10413 |
+
[input.iterators]: iterators.md#input.iterators
|
| 10414 |
[input.output]: #input.output
|
| 10415 |
[input.output.general]: #input.output.general
|
| 10416 |
[input.streams]: #input.streams
|
| 10417 |
[intro.multithread]: intro.md#intro.multithread
|
| 10418 |
+
[iomanip.syn]: #iomanip.syn
|
| 10419 |
[ios]: #ios
|
| 10420 |
[ios.base]: #ios.base
|
| 10421 |
[ios.base.callback]: #ios.base.callback
|
| 10422 |
[ios.base.cons]: #ios.base.cons
|
| 10423 |
[ios.base.locales]: #ios.base.locales
|
| 10424 |
[ios.base.storage]: #ios.base.storage
|
| 10425 |
[ios.members.static]: #ios.members.static
|
| 10426 |
[ios.overview]: #ios.overview
|
| 10427 |
+
[ios.syn]: #ios.syn
|
| 10428 |
[ios.types]: #ios.types
|
| 10429 |
[ios::Init]: #ios::Init
|
| 10430 |
[ios::failure]: #ios::failure
|
| 10431 |
[ios::fmtflags]: #ios::fmtflags
|
| 10432 |
[ios::iostate]: #ios::iostate
|
| 10433 |
[ios::openmode]: #ios::openmode
|
| 10434 |
[ios::seekdir]: #ios::seekdir
|
| 10435 |
+
[iosfwd.syn]: #iosfwd.syn
|
| 10436 |
[iostate.flags]: #iostate.flags
|
| 10437 |
[iostream.assign]: #iostream.assign
|
| 10438 |
[iostream.cons]: #iostream.cons
|
| 10439 |
[iostream.dest]: #iostream.dest
|
| 10440 |
[iostream.format]: #iostream.format
|
|
|
|
| 10441 |
[iostream.forward]: #iostream.forward
|
| 10442 |
+
[iostream.forward.overview]: #iostream.forward.overview
|
| 10443 |
[iostream.limits.imbue]: #iostream.limits.imbue
|
| 10444 |
[iostream.objects]: #iostream.objects
|
| 10445 |
[iostream.objects.overview]: #iostream.objects.overview
|
| 10446 |
+
[iostream.syn]: #iostream.syn
|
| 10447 |
[iostreamclass]: #iostreamclass
|
| 10448 |
[iostreams.base]: #iostreams.base
|
|
|
|
| 10449 |
[iostreams.limits.pos]: #iostreams.limits.pos
|
| 10450 |
[iostreams.requirements]: #iostreams.requirements
|
| 10451 |
[iostreams.threadsafety]: #iostreams.threadsafety
|
| 10452 |
[istream]: #istream
|
| 10453 |
[istream.assign]: #istream.assign
|
| 10454 |
[istream.cons]: #istream.cons
|
| 10455 |
+
[istream.extractors]: #istream.extractors
|
| 10456 |
[istream.formatted]: #istream.formatted
|
| 10457 |
[istream.formatted.arithmetic]: #istream.formatted.arithmetic
|
| 10458 |
[istream.formatted.reqmts]: #istream.formatted.reqmts
|
| 10459 |
[istream.manip]: #istream.manip
|
| 10460 |
[istream.rvalue]: #istream.rvalue
|
| 10461 |
+
[istream.syn]: #istream.syn
|
| 10462 |
[istream.unformatted]: #istream.unformatted
|
|
|
|
| 10463 |
[istream::sentry]: #istream::sentry
|
| 10464 |
[istringstream]: #istringstream
|
| 10465 |
[istringstream.assign]: #istringstream.assign
|
| 10466 |
[istringstream.cons]: #istringstream.cons
|
| 10467 |
[istringstream.members]: #istringstream.members
|
| 10468 |
+
[lex.charset]: lex.md#lex.charset
|
| 10469 |
[locale.codecvt.virtuals]: localization.md#locale.codecvt.virtuals
|
| 10470 |
[locale.num.get]: localization.md#locale.num.get
|
| 10471 |
[narrow.stream.objects]: #narrow.stream.objects
|
| 10472 |
+
[numeric.limits]: language.md#numeric.limits
|
| 10473 |
[ofstream]: #ofstream
|
| 10474 |
[ofstream.assign]: #ofstream.assign
|
| 10475 |
[ofstream.cons]: #ofstream.cons
|
| 10476 |
[ofstream.members]: #ofstream.members
|
| 10477 |
[ostream]: #ostream
|
|
|
|
| 10483 |
[ostream.inserters.arithmetic]: #ostream.inserters.arithmetic
|
| 10484 |
[ostream.inserters.character]: #ostream.inserters.character
|
| 10485 |
[ostream.manip]: #ostream.manip
|
| 10486 |
[ostream.rvalue]: #ostream.rvalue
|
| 10487 |
[ostream.seeks]: #ostream.seeks
|
| 10488 |
+
[ostream.syn]: #ostream.syn
|
| 10489 |
[ostream.unformatted]: #ostream.unformatted
|
| 10490 |
[ostream::sentry]: #ostream::sentry
|
| 10491 |
[ostringstream]: #ostringstream
|
| 10492 |
[ostringstream.assign]: #ostringstream.assign
|
| 10493 |
[ostringstream.cons]: #ostringstream.cons
|
| 10494 |
[ostringstream.members]: #ostringstream.members
|
| 10495 |
[output.streams]: #output.streams
|
| 10496 |
[quoted.manip]: #quoted.manip
|
| 10497 |
[res.on.data.races]: library.md#res.on.data.races
|
| 10498 |
[res.on.exception.handling]: library.md#res.on.exception.handling
|
| 10499 |
+
[sstream.syn]: #sstream.syn
|
| 10500 |
[std.ios.manip]: #std.ios.manip
|
| 10501 |
[std.manip]: #std.manip
|
| 10502 |
[stream.buffers]: #stream.buffers
|
|
|
|
| 10503 |
[stream.types]: #stream.types
|
| 10504 |
[streambuf]: #streambuf
|
| 10505 |
[streambuf.assign]: #streambuf.assign
|
| 10506 |
[streambuf.buffer]: #streambuf.buffer
|
| 10507 |
[streambuf.cons]: #streambuf.cons
|
|
|
|
| 10512 |
[streambuf.pub.get]: #streambuf.pub.get
|
| 10513 |
[streambuf.pub.pback]: #streambuf.pub.pback
|
| 10514 |
[streambuf.pub.put]: #streambuf.pub.put
|
| 10515 |
[streambuf.put.area]: #streambuf.put.area
|
| 10516 |
[streambuf.reqts]: #streambuf.reqts
|
| 10517 |
+
[streambuf.syn]: #streambuf.syn
|
| 10518 |
[streambuf.virt.buffer]: #streambuf.virt.buffer
|
| 10519 |
[streambuf.virt.get]: #streambuf.virt.get
|
| 10520 |
[streambuf.virt.locales]: #streambuf.virt.locales
|
| 10521 |
[streambuf.virt.pback]: #streambuf.virt.pback
|
| 10522 |
[streambuf.virt.put]: #streambuf.virt.put
|
| 10523 |
[streambuf.virtuals]: #streambuf.virtuals
|
| 10524 |
[string.classes]: strings.md#string.classes
|
| 10525 |
[string.streams]: #string.streams
|
|
|
|
| 10526 |
[stringbuf]: #stringbuf
|
| 10527 |
[stringbuf.assign]: #stringbuf.assign
|
| 10528 |
[stringbuf.cons]: #stringbuf.cons
|
| 10529 |
[stringbuf.members]: #stringbuf.members
|
| 10530 |
[stringbuf.virtuals]: #stringbuf.virtuals
|
| 10531 |
[strings]: strings.md#strings
|
| 10532 |
[stringstream]: #stringstream
|
| 10533 |
[stringstream.assign]: #stringstream.assign
|
| 10534 |
[stringstream.cons]: #stringstream.cons
|
| 10535 |
[stringstream.members]: #stringstream.members
|
| 10536 |
+
[tab:enum.path.format]: #tab:enum.path.format
|
| 10537 |
+
[tab:enum.perm_options]: #tab:enum.perm_options
|
| 10538 |
+
[tab:filesystem_error.1]: #tab:filesystem_error.1
|
| 10539 |
+
[tab:filesystem_error.2]: #tab:filesystem_error.2
|
| 10540 |
+
[tab:filesystem_error.3]: #tab:filesystem_error.3
|
| 10541 |
+
[tab:fs.enum.copy_options]: #tab:fs.enum.copy_options
|
| 10542 |
+
[tab:fs.enum.directory_options]: #tab:fs.enum.directory_options
|
| 10543 |
+
[tab:fs.enum.file_type]: #tab:fs.enum.file_type
|
| 10544 |
+
[tab:fs.enum.perms]: #tab:fs.enum.perms
|
| 10545 |
[tab:iostreams.basicios.init.effects]: #tab:iostreams.basicios.init.effects
|
| 10546 |
[tab:iostreams.copyfmt.effects]: #tab:iostreams.copyfmt.effects
|
| 10547 |
[tab:iostreams.file.open.modes]: #tab:iostreams.file.open.modes
|
| 10548 |
[tab:iostreams.fmtflags.constants]: #tab:iostreams.fmtflags.constants
|
| 10549 |
[tab:iostreams.fmtflags.effects]: #tab:iostreams.fmtflags.effects
|
|
|
|
|
|
|
| 10550 |
[tab:iostreams.iostate.effects]: #tab:iostreams.iostate.effects
|
| 10551 |
[tab:iostreams.lib.summary]: #tab:iostreams.lib.summary
|
| 10552 |
[tab:iostreams.newoff.values]: #tab:iostreams.newoff.values
|
| 10553 |
[tab:iostreams.openmode.effects]: #tab:iostreams.openmode.effects
|
| 10554 |
[tab:iostreams.position.requirements]: #tab:iostreams.position.requirements
|
| 10555 |
[tab:iostreams.seekdir.effects]: #tab:iostreams.seekdir.effects
|
| 10556 |
[tab:iostreams.seekoff.effects]: #tab:iostreams.seekoff.effects
|
| 10557 |
[tab:iostreams.seekoff.positioning]: #tab:iostreams.seekoff.positioning
|
| 10558 |
+
[temp.deduct]: temp.md#temp.deduct
|
| 10559 |
+
[time.clock.req]: utilities.md#time.clock.req
|
| 10560 |
[wide.stream.objects]: #wide.stream.objects
|
| 10561 |
|
| 10562 |
[^1]: It is the implementation’s responsibility to implement headers so
|
| 10563 |
that including `<iosfwd>` and other headers does not violate the
|
| 10564 |
rules about multiple occurrences of default arguments.
|
|
|
|
| 10592 |
|
| 10593 |
[^9]: for example, because it cannot allocate space.
|
| 10594 |
|
| 10595 |
[^10]: This suggests an infinite amount of copying, but the
|
| 10596 |
implementation can keep track of the maximum element of the arrays
|
| 10597 |
+
that is nonzero.
|
| 10598 |
|
| 10599 |
[^11]: Checking `badbit` also for `fail()` is historical practice.
|
| 10600 |
|
| 10601 |
[^12]: The function signature `dec(ios_base&)` can be called by the
|
| 10602 |
function signature
|
|
|
|
| 10608 |
to assure that only objects for classes derived from this class may
|
| 10609 |
be constructed.
|
| 10610 |
|
| 10611 |
[^14]: `underflow` or `uflow` might fail by throwing an exception
|
| 10612 |
prematurely. The intention is not only that the calls will not
|
| 10613 |
+
return `eof()` but that they will return “immediately”.
|
| 10614 |
|
| 10615 |
[^15]: Classes derived from `basic_streambuf` can provide more efficient
|
| 10616 |
ways to implement `xsgetn()` and `xsputn()` by overriding these
|
| 10617 |
definitions from the base class.
|
| 10618 |
|
| 10619 |
+
[^16]: That is, for each class derived from an instance of
|
| 10620 |
+
`basic_streambuf` in this Clause ([[stringbuf]],
|
| 10621 |
+
[[filebuf]]), a specification of how consuming a character
|
| 10622 |
+
effects the associated output sequence is given. There is no
|
| 10623 |
+
requirement on a program-defined class.
|
| 10624 |
|
| 10625 |
+
[^17]: Typically, `overflow` returns `c` to indicate success, except
|
| 10626 |
+
when `traits::eq_int_type(c, traits::eof())` returns `true`, in
|
| 10627 |
+
which case it returns `traits::not_eof(c)`.
|
| 10628 |
+
|
| 10629 |
+
[^18]: This will be possible only in functions that are part of the
|
| 10630 |
library. The semantics of the constructor used in user code is as
|
| 10631 |
specified.
|
| 10632 |
|
| 10633 |
+
[^19]: The sentry constructor and destructor can also perform additional
|
| 10634 |
implementation-dependent operations.
|
| 10635 |
|
| 10636 |
+
[^20]: This is done without causing an `ios::failure` to be thrown.
|
|
|
|
|
|
|
|
|
|
| 10637 |
|
| 10638 |
[^21]: See, for example, the function signature
|
| 10639 |
+
`ws(basic_istream&)` ([[istream.manip]]).
|
| 10640 |
+
|
| 10641 |
+
[^22]: See, for example, the function signature
|
| 10642 |
`dec(ios_base&)` ([[basefield.manip]]).
|
| 10643 |
|
| 10644 |
+
[^23]: This is done without causing an `ios::failure` to be thrown.
|
|
|
|
|
|
|
|
|
|
| 10645 |
|
| 10646 |
[^24]: Note that this function is not overloaded on types `signed char`
|
| 10647 |
and `unsigned char`.
|
| 10648 |
|
| 10649 |
[^25]: Note that this function is not overloaded on types `signed char`
|
| 10650 |
and `unsigned char`.
|
| 10651 |
|
| 10652 |
+
[^26]: Note that this function is not overloaded on types `signed char`
|
| 10653 |
+
and `unsigned char`.
|
| 10654 |
+
|
| 10655 |
+
[^27]: Since the final input character is “extracted”, it is counted in
|
| 10656 |
the `gcount()`, even though it is not stored.
|
| 10657 |
|
| 10658 |
+
[^28]: This allows an input line which exactly fills the buffer, without
|
| 10659 |
setting `failbit`. This is different behavior than the historical
|
| 10660 |
AT&T implementation.
|
| 10661 |
|
| 10662 |
+
[^29]: This implies an empty input line will not cause `failbit` to be
|
| 10663 |
set.
|
| 10664 |
|
| 10665 |
+
[^30]: Note that this function is not overloaded on types `signed char`
|
| 10666 |
and `unsigned char`.
|
| 10667 |
|
| 10668 |
+
[^31]: The call `os.tie()->flush()` does not necessarily occur if the
|
| 10669 |
function can determine that no synchronization is necessary.
|
| 10670 |
|
| 10671 |
+
[^32]: The `sentry` constructor and destructor can also perform
|
| 10672 |
additional implementation-dependent operations.
|
| 10673 |
|
| 10674 |
+
[^33]: without causing an `ios::failure` to be thrown.
|
|
|
|
|
|
|
|
|
|
| 10675 |
|
| 10676 |
[^34]: See, for example, the function signature
|
| 10677 |
+
`endl(basic_ostream&)` ([[ostream.manip]]).
|
| 10678 |
+
|
| 10679 |
+
[^35]: See, for example, the function signature
|
| 10680 |
`dec(ios_base&)` ([[basefield.manip]]).
|
| 10681 |
|
| 10682 |
+
[^36]: without causing an `ios::failure` to be thrown.
|
|
|
|
|
|
|
|
|
|
| 10683 |
|
| 10684 |
[^37]: Note that this function is not overloaded on types `signed char`
|
| 10685 |
and `unsigned char`.
|
| 10686 |
|
| 10687 |
+
[^38]: Note that this function is not overloaded on types `signed char`
|
| 10688 |
+
and `unsigned char`.
|
| 10689 |
+
|
| 10690 |
+
[^39]: The expression `cin >> resetiosflags(ios_base::skipws)` clears
|
| 10691 |
`ios_base::skipws` in the format flags stored in the
|
| 10692 |
`basic_istream<charT, traits>` object `cin` (the same as
|
| 10693 |
`cin >> noskipws`), and the expression
|
| 10694 |
`cout << resetiosflags(ios_base::showbase)` clears
|
| 10695 |
`ios_base::showbase` in the format flags stored in the
|
| 10696 |
`basic_ostream<charT, traits>` object `cout` (the same as
|
| 10697 |
`cout << noshowbase`).
|
| 10698 |
|
| 10699 |
+
[^40]: The macro `SEEK_END` is defined, and the function signatures
|
| 10700 |
`fopen(const char*, const char*)` and `fseek(FILE*, long, int)` are
|
| 10701 |
+
declared, in `<cstdio>` ([[cstdio.syn]]).
|
| 10702 |
|
| 10703 |
+
[^41]: POSIX® is a registered trademark of The IEEE. Windows® is a
|
| 10704 |
+
registered trademark of Microsoft Corporation. This information is
|
| 10705 |
+
given for the convenience of users of this document and does not
|
| 10706 |
+
constitute an endorsement by ISO or IEC of these products.
|