- tmp/tmpgddwfx70/{from.md → to.md} +654 -323
tmp/tmpgddwfx70/{from.md → to.md}
RENAMED
|
@@ -17,12 +17,12 @@ namespace std {
|
|
| 17 |
using wiostream = basic_iostream<wchar_t>;
|
| 18 |
|
| 19 |
template<class charT, class traits>
|
| 20 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 21 |
|
| 22 |
-
template<class
|
| 23 |
-
|
| 24 |
}
|
| 25 |
```
|
| 26 |
|
| 27 |
### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
|
| 28 |
|
|
@@ -46,56 +46,96 @@ namespace std {
|
|
| 46 |
template<class charT, class traits>
|
| 47 |
basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
|
| 48 |
template<class charT, class traits>
|
| 49 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 50 |
|
| 51 |
-
template<class
|
| 52 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 53 |
}
|
| 54 |
```
|
| 55 |
|
| 56 |
### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
|
| 57 |
|
| 58 |
``` cpp
|
| 59 |
namespace std {
|
| 60 |
-
|
| 61 |
-
|
| 62 |
-
|
| 63 |
-
|
| 64 |
-
|
| 65 |
-
|
| 66 |
-
|
| 67 |
-
template<class moneyT>
|
| 68 |
-
template<class
|
| 69 |
-
template<class charT>
|
| 70 |
-
template<class charT> T10 put_time(const struct tm* tmb, const charT* fmt);
|
| 71 |
|
| 72 |
template<class charT>
|
| 73 |
-
|
| 74 |
|
| 75 |
template<class charT, class traits, class Allocator>
|
| 76 |
-
|
| 77 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 78 |
|
| 79 |
template<class charT, class traits, class Allocator>
|
| 80 |
-
|
| 81 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 82 |
|
| 83 |
template<class charT, class traits>
|
| 84 |
-
|
| 85 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 86 |
}
|
| 87 |
```
|
| 88 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 89 |
### Input streams <a id="input.streams">[[input.streams]]</a>
|
| 90 |
|
| 91 |
-
|
| 92 |
-
|
| 93 |
-
|
|
|
|
|
|
|
| 94 |
|
| 95 |
#### Class template `basic_istream` <a id="istream">[[istream]]</a>
|
| 96 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 97 |
``` cpp
|
| 98 |
namespace std {
|
| 99 |
template<class charT, class traits = char_traits<charT>>
|
| 100 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 101 |
public:
|
|
@@ -112,64 +152,62 @@ namespace std {
|
|
| 112 |
|
| 113 |
// [istream.sentry], prefix/suffix
|
| 114 |
class sentry;
|
| 115 |
|
| 116 |
// [istream.formatted], formatted input
|
| 117 |
-
basic_istream
|
| 118 |
-
|
| 119 |
-
basic_istream
|
| 120 |
-
operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 121 |
-
basic_istream<charT, traits>&
|
| 122 |
-
operator>>(ios_base& (*pf)(ios_base&));
|
| 123 |
|
| 124 |
-
basic_istream
|
| 125 |
-
basic_istream
|
| 126 |
-
basic_istream
|
| 127 |
-
basic_istream
|
| 128 |
-
basic_istream
|
| 129 |
-
basic_istream
|
| 130 |
-
basic_istream
|
| 131 |
-
basic_istream
|
| 132 |
-
basic_istream
|
| 133 |
-
basic_istream
|
| 134 |
-
basic_istream
|
| 135 |
-
basic_istream
|
|
|
|
| 136 |
|
| 137 |
-
basic_istream
|
| 138 |
-
basic_istream
|
| 139 |
|
| 140 |
// [istream.unformatted], unformatted input
|
| 141 |
streamsize gcount() const;
|
| 142 |
int_type get();
|
| 143 |
-
basic_istream
|
| 144 |
-
basic_istream
|
| 145 |
-
basic_istream
|
| 146 |
-
basic_istream
|
| 147 |
-
basic_istream
|
| 148 |
|
| 149 |
-
basic_istream
|
| 150 |
-
basic_istream
|
| 151 |
|
| 152 |
-
basic_istream
|
| 153 |
int_type peek();
|
| 154 |
-
basic_istream
|
| 155 |
streamsize readsome(char_type* s, streamsize n);
|
| 156 |
|
| 157 |
-
basic_istream
|
| 158 |
-
basic_istream
|
| 159 |
int sync();
|
| 160 |
|
| 161 |
pos_type tellg();
|
| 162 |
-
basic_istream
|
| 163 |
-
basic_istream
|
| 164 |
|
| 165 |
protected:
|
| 166 |
// [istream.cons], copy/move constructor
|
| 167 |
basic_istream(const basic_istream&) = delete;
|
| 168 |
basic_istream(basic_istream&& rhs);
|
| 169 |
|
| 170 |
-
// [istream.assign],
|
| 171 |
basic_istream& operator=(const basic_istream&) = delete;
|
| 172 |
basic_istream& operator=(basic_istream&& rhs);
|
| 173 |
void swap(basic_istream& rhs);
|
| 174 |
};
|
| 175 |
|
|
@@ -198,22 +236,10 @@ Two groups of member function signatures share common properties: the
|
|
| 198 |
*formatted input functions* (or *extractors*) and the *unformatted input
|
| 199 |
functions.* Both groups of input functions are described as if they
|
| 200 |
obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
|
| 201 |
or `rdbuf()->sgetc()`. They may use other public members of `istream`.
|
| 202 |
|
| 203 |
-
If `rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`,
|
| 204 |
-
then the input function, except as explicitly noted otherwise, completes
|
| 205 |
-
its actions and does `setstate(eofbit)`, which may throw
|
| 206 |
-
`ios_base::failure` [[iostate.flags]], before returning.
|
| 207 |
-
|
| 208 |
-
If one of these called functions throws an exception, then unless
|
| 209 |
-
explicitly noted otherwise, the input function sets `badbit` in the
|
| 210 |
-
error state. If `badbit` is set in `exceptions()`, the input function
|
| 211 |
-
rethrows the exception without completing its actions, otherwise it does
|
| 212 |
-
not throw anything and proceeds as if the called function had returned a
|
| 213 |
-
failure indication.
|
| 214 |
-
|
| 215 |
##### Constructors <a id="istream.cons">[[istream.cons]]</a>
|
| 216 |
|
| 217 |
``` cpp
|
| 218 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 219 |
```
|
|
@@ -256,15 +282,16 @@ values returned by `gcount()` and `rhs.gcount()`.
|
|
| 256 |
|
| 257 |
##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
|
| 258 |
|
| 259 |
``` cpp
|
| 260 |
namespace std {
|
| 261 |
-
template<class charT, class traits
|
| 262 |
class basic_istream<charT, traits>::sentry {
|
| 263 |
bool ok_; // exposition only
|
|
|
|
| 264 |
public:
|
| 265 |
-
explicit sentry(basic_istream
|
| 266 |
~sentry();
|
| 267 |
explicit operator bool() const { return ok_; }
|
| 268 |
sentry(const sentry&) = delete;
|
| 269 |
sentry& operator=(const sentry&) = delete;
|
| 270 |
};
|
|
@@ -273,32 +300,34 @@ namespace std {
|
|
| 273 |
|
| 274 |
The class `sentry` defines a class that is responsible for doing
|
| 275 |
exception safe prefix and suffix operations.
|
| 276 |
|
| 277 |
``` cpp
|
| 278 |
-
explicit sentry(basic_istream
|
| 279 |
```
|
| 280 |
|
| 281 |
*Effects:* If `is.good()` is `false`, calls `is.setstate(failbit)`.
|
| 282 |
Otherwise, prepares for formatted or unformatted input. First, if
|
| 283 |
`is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
|
| 284 |
to synchronize the output sequence with any associated external C
|
| 285 |
stream. Except that this call can be suppressed if the put area of
|
| 286 |
`is.tie()` is empty. Further an implementation is allowed to defer the
|
| 287 |
call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
|
| 288 |
such call occurs before the `sentry` object is destroyed, the call to
|
| 289 |
-
`flush` may be eliminated entirely.[^18]
|
| 290 |
-
|
| 291 |
-
|
| 292 |
-
|
| 293 |
-
|
| 294 |
-
`
|
|
|
|
|
|
|
| 295 |
|
| 296 |
*Remarks:* The constructor
|
| 297 |
|
| 298 |
``` cpp
|
| 299 |
-
explicit sentry(basic_istream
|
| 300 |
```
|
| 301 |
|
| 302 |
uses the currently imbued locale in `is`, to determine whether the next
|
| 303 |
input character is whitespace or not.
|
| 304 |
|
|
@@ -331,47 +360,56 @@ explicit operator bool() const;
|
|
| 331 |
#### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
|
| 332 |
|
| 333 |
##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
|
| 334 |
|
| 335 |
Each formatted input function begins execution by constructing an object
|
| 336 |
-
of
|
|
|
|
|
|
|
| 337 |
`sentry` object returns `true`, when converted to a value of type
|
| 338 |
-
`bool`, the function endeavors to obtain the requested input.
|
| 339 |
-
|
| 340 |
-
|
| 341 |
-
the
|
| 342 |
-
|
| 343 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 344 |
|
| 345 |
##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
|
| 346 |
|
| 347 |
``` cpp
|
| 348 |
-
operator>>(unsigned short& val);
|
| 349 |
-
operator>>(unsigned int& val);
|
| 350 |
-
operator>>(long& val);
|
| 351 |
-
operator>>(unsigned long& val);
|
| 352 |
-
operator>>(long long& val);
|
| 353 |
-
operator>>(unsigned long long& val);
|
| 354 |
-
operator>>(float& val);
|
| 355 |
-
operator>>(double& val);
|
| 356 |
-
operator>>(long double& val);
|
| 357 |
-
operator>>(bool& val);
|
| 358 |
-
operator>>(void*& val);
|
| 359 |
```
|
| 360 |
|
| 361 |
As in the case of the inserters, these extractors depend on the locale’s
|
| 362 |
`num_get<>` [[locale.num.get]] object to perform parsing the input
|
| 363 |
stream data. These extractors behave as formatted input functions (as
|
| 364 |
-
described in [[istream.formatted.reqmts]]). After a sentry object is
|
| 365 |
constructed, the conversion occurs as if performed by the following code
|
| 366 |
-
fragment
|
|
|
|
| 367 |
|
| 368 |
``` cpp
|
| 369 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 370 |
-
|
| 371 |
-
use_facet<numget>(loc).get(*this, 0, *this, err, val);
|
| 372 |
-
setstate(err);
|
| 373 |
```
|
| 374 |
|
| 375 |
In the above fragment, `loc` stands for the private member of the
|
| 376 |
`basic_ios` class.
|
| 377 |
|
|
@@ -382,85 +420,123 @@ directly. — *end note*]
|
|
| 382 |
|
| 383 |
Class `locale` relies on this type as its interface to `istream`, so
|
| 384 |
that it does not need to depend directly on `istream`.
|
| 385 |
|
| 386 |
``` cpp
|
| 387 |
-
operator>>(short& val);
|
| 388 |
```
|
| 389 |
|
| 390 |
The conversion occurs as if performed by the following code fragment
|
| 391 |
(using the same notation as for the preceding code fragment):
|
| 392 |
|
| 393 |
``` cpp
|
| 394 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 395 |
-
iostate err = ios_base::goodbit;
|
| 396 |
long lval;
|
| 397 |
-
use_facet<numget>(loc).get(*this, 0, *this,
|
| 398 |
if (lval < numeric_limits<short>::min()) {
|
| 399 |
-
|
| 400 |
val = numeric_limits<short>::min();
|
| 401 |
} else if (numeric_limits<short>::max() < lval) {
|
| 402 |
-
|
| 403 |
val = numeric_limits<short>::max();
|
| 404 |
} else
|
| 405 |
val = static_cast<short>(lval);
|
| 406 |
-
setstate(err);
|
| 407 |
```
|
| 408 |
|
| 409 |
``` cpp
|
| 410 |
-
operator>>(int& val);
|
| 411 |
```
|
| 412 |
|
| 413 |
The conversion occurs as if performed by the following code fragment
|
| 414 |
(using the same notation as for the preceding code fragment):
|
| 415 |
|
| 416 |
``` cpp
|
| 417 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 418 |
-
iostate err = ios_base::goodbit;
|
| 419 |
long lval;
|
| 420 |
-
use_facet<numget>(loc).get(*this, 0, *this,
|
| 421 |
if (lval < numeric_limits<int>::min()) {
|
| 422 |
-
|
| 423 |
val = numeric_limits<int>::min();
|
| 424 |
} else if (numeric_limits<int>::max() < lval) {
|
| 425 |
-
|
| 426 |
val = numeric_limits<int>::max();
|
| 427 |
} else
|
| 428 |
val = static_cast<int>(lval);
|
| 429 |
-
setstate(err);
|
| 430 |
```
|
| 431 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 432 |
##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
|
| 433 |
|
| 434 |
``` cpp
|
| 435 |
-
basic_istream
|
| 436 |
-
operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
|
| 437 |
```
|
| 438 |
|
| 439 |
*Effects:* None. This extractor does not behave as a formatted input
|
| 440 |
function (as described in [[istream.formatted.reqmts]]).
|
| 441 |
|
| 442 |
-
*Returns:* `pf(*this)`.[^
|
| 443 |
|
| 444 |
``` cpp
|
| 445 |
-
basic_istream<charT, traits>&
|
| 446 |
-
operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 447 |
```
|
| 448 |
|
| 449 |
*Effects:* Calls `pf(*this)`. This extractor does not behave as a
|
| 450 |
formatted input function (as described
|
| 451 |
in [[istream.formatted.reqmts]]).
|
| 452 |
|
| 453 |
*Returns:* `*this`.
|
| 454 |
|
| 455 |
``` cpp
|
| 456 |
-
basic_istream
|
| 457 |
```
|
| 458 |
|
| 459 |
-
*Effects:* Calls `pf(*this)`.[^
|
| 460 |
-
|
| 461 |
-
|
|
|
|
| 462 |
|
| 463 |
*Returns:* `*this`.
|
| 464 |
|
| 465 |
``` cpp
|
| 466 |
template<class charT, class traits, size_t N>
|
|
@@ -486,12 +562,12 @@ Characters are extracted and stored until any of the following occurs:
|
|
| 486 |
|
| 487 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 488 |
which may be the first position if no characters were extracted.
|
| 489 |
`operator>>` then calls `width(0)`.
|
| 490 |
|
| 491 |
-
If the function extracted no characters,
|
| 492 |
-
|
| 493 |
|
| 494 |
*Returns:* `in`.
|
| 495 |
|
| 496 |
``` cpp
|
| 497 |
template<class charT, class traits>
|
|
@@ -501,132 +577,138 @@ template<class traits>
|
|
| 501 |
template<class traits>
|
| 502 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
|
| 503 |
```
|
| 504 |
|
| 505 |
*Effects:* Behaves like a formatted input member (as described
|
| 506 |
-
in [[istream.formatted.reqmts]]) of `in`.
|
| 507 |
-
|
| 508 |
-
|
|
|
|
| 509 |
|
| 510 |
*Returns:* `in`.
|
| 511 |
|
| 512 |
``` cpp
|
| 513 |
-
basic_istream
|
| 514 |
```
|
| 515 |
|
| 516 |
*Effects:* Behaves as an unformatted input
|
| 517 |
function [[istream.unformatted]]. If `sb` is null, calls
|
| 518 |
`setstate(failbit)`, which may throw `ios_base::failure`
|
| 519 |
-
[[iostate.flags]]. After a sentry object is constructed, extracts
|
| 520 |
characters from `*this` and inserts them in the output sequence
|
| 521 |
controlled by `sb`. Characters are extracted and inserted until any of
|
| 522 |
the following occurs:
|
| 523 |
|
| 524 |
- end-of-file occurs on the input sequence;
|
| 525 |
- inserting in the output sequence fails (in which case the character to
|
| 526 |
be inserted is not extracted);
|
| 527 |
- an exception occurs (in which case the exception is caught).
|
| 528 |
|
| 529 |
-
If the function inserts no characters,
|
| 530 |
-
|
| 531 |
-
characters because it caught an exception thrown while extracting
|
| 532 |
-
characters from `*this` and `failbit` is set in `exceptions()`
|
| 533 |
-
[[iostate.flags]], then the caught exception is rethrown.
|
| 534 |
|
| 535 |
*Returns:* `*this`.
|
| 536 |
|
| 537 |
#### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
|
| 538 |
|
| 539 |
Each unformatted input function begins execution by constructing an
|
| 540 |
-
object of
|
| 541 |
-
|
| 542 |
-
|
| 543 |
-
|
| 544 |
-
|
| 545 |
-
|
| 546 |
-
|
| 547 |
-
|
| 548 |
-
|
| 549 |
-
|
| 550 |
-
|
| 551 |
-
|
| 552 |
-
|
| 553 |
-
|
| 554 |
-
|
| 555 |
-
|
| 556 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 557 |
|
| 558 |
``` cpp
|
| 559 |
streamsize gcount() const;
|
| 560 |
```
|
| 561 |
|
| 562 |
*Effects:* None. This member function does not behave as an unformatted
|
| 563 |
input function (as described above).
|
| 564 |
|
| 565 |
*Returns:* The number of characters extracted by the last unformatted
|
| 566 |
-
input member function called for the object.
|
|
|
|
| 567 |
|
| 568 |
``` cpp
|
| 569 |
int_type get();
|
| 570 |
```
|
| 571 |
|
| 572 |
*Effects:* Behaves as an unformatted input function (as described
|
| 573 |
-
above). After constructing a sentry object, extracts a character `c`,
|
| 574 |
-
one is available. Otherwise,
|
| 575 |
-
|
| 576 |
|
| 577 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 578 |
|
| 579 |
``` cpp
|
| 580 |
-
basic_istream
|
| 581 |
```
|
| 582 |
|
| 583 |
*Effects:* Behaves as an unformatted input function (as described
|
| 584 |
-
above). After constructing a sentry object, extracts a character, if
|
| 585 |
-
is available, and assigns it to `c`.[^
|
| 586 |
-
|
| 587 |
-
|
|
|
|
| 588 |
|
| 589 |
*Returns:* `*this`.
|
| 590 |
|
| 591 |
``` cpp
|
| 592 |
-
basic_istream
|
| 593 |
```
|
| 594 |
|
| 595 |
*Effects:* Behaves as an unformatted input function (as described
|
| 596 |
-
above). After constructing a sentry object, extracts characters and
|
| 597 |
stores them into successive locations of an array whose first element is
|
| 598 |
-
designated by `s`.[^
|
| 599 |
-
|
|
|
|
| 600 |
|
| 601 |
- `n` is less than one or `n - 1` characters are stored;
|
| 602 |
-
- end-of-file occurs on the input sequence
|
| 603 |
-
calls `setstate(eofbit)`);
|
| 604 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 605 |
which case `c` is not extracted).
|
| 606 |
|
| 607 |
-
If the function stores no characters,
|
| 608 |
-
|
| 609 |
-
`n` is greater than zero it then stores a null character into
|
| 610 |
-
successive location of the array.
|
| 611 |
|
| 612 |
*Returns:* `*this`.
|
| 613 |
|
| 614 |
``` cpp
|
| 615 |
-
basic_istream
|
| 616 |
```
|
| 617 |
|
| 618 |
*Effects:* Calls `get(s, n, widen(’\n’))`.
|
| 619 |
|
| 620 |
*Returns:* Value returned by the call.
|
| 621 |
|
| 622 |
``` cpp
|
| 623 |
-
basic_istream
|
| 624 |
```
|
| 625 |
|
| 626 |
*Effects:* Behaves as an unformatted input function (as described
|
| 627 |
-
above). After constructing a sentry object, extracts characters and
|
| 628 |
inserts them in the output sequence controlled by `sb`. Characters are
|
| 629 |
extracted and inserted until any of the following occurs:
|
| 630 |
|
| 631 |
- end-of-file occurs on the input sequence;
|
| 632 |
- inserting in the output sequence fails (in which case the character to
|
|
@@ -634,45 +716,45 @@ extracted and inserted until any of the following occurs:
|
|
| 634 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 635 |
which case `c` is not extracted);
|
| 636 |
- an exception occurs (in which case, the exception is caught but not
|
| 637 |
rethrown).
|
| 638 |
|
| 639 |
-
If the function inserts no characters,
|
| 640 |
-
|
| 641 |
|
| 642 |
*Returns:* `*this`.
|
| 643 |
|
| 644 |
``` cpp
|
| 645 |
-
basic_istream
|
| 646 |
```
|
| 647 |
|
| 648 |
*Effects:* Calls `get(sb, widen(’\n’))`.
|
| 649 |
|
| 650 |
*Returns:* Value returned by the call.
|
| 651 |
|
| 652 |
``` cpp
|
| 653 |
-
basic_istream
|
| 654 |
```
|
| 655 |
|
| 656 |
*Effects:* Behaves as an unformatted input function (as described
|
| 657 |
-
above). After constructing a sentry object, extracts characters and
|
| 658 |
stores them into successive locations of an array whose first element is
|
| 659 |
-
designated by `s`.[^
|
| 660 |
-
the following occurs:
|
| 661 |
|
| 662 |
-
|
| 663 |
-
|
|
|
|
| 664 |
2. `traits::eq(c, delim)` for the next available input character `c`
|
| 665 |
(in which case the input character is extracted but not
|
| 666 |
-
stored);[^
|
| 667 |
3. `n` is less than one or `n - 1` characters are stored (in which case
|
| 668 |
the function calls `setstate(failbit)`).
|
| 669 |
|
| 670 |
-
These conditions are tested in the order shown.[^
|
| 671 |
|
| 672 |
-
If the function extracts no characters,
|
| 673 |
-
|
| 674 |
|
| 675 |
In any case, if `n` is greater than zero, it then stores a null
|
| 676 |
character (using `charT()`) into the next successive location of the
|
| 677 |
array.
|
| 678 |
|
|
@@ -706,21 +788,21 @@ int main() {
|
|
| 706 |
```
|
| 707 |
|
| 708 |
— *end example*]
|
| 709 |
|
| 710 |
``` cpp
|
| 711 |
-
basic_istream
|
| 712 |
```
|
| 713 |
|
| 714 |
*Returns:* `getline(s, n, widen(’\n’))`
|
| 715 |
|
| 716 |
``` cpp
|
| 717 |
-
basic_istream
|
| 718 |
```
|
| 719 |
|
| 720 |
*Effects:* Behaves as an unformatted input function (as described
|
| 721 |
-
above). After constructing a sentry object, extracts characters and
|
| 722 |
discards them. Characters are extracted until any of the following
|
| 723 |
occurs:
|
| 724 |
|
| 725 |
- `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
|
| 726 |
characters have been extracted so far
|
|
@@ -728,36 +810,38 @@ occurs:
|
|
| 728 |
calls `setstate(eofbit)`, which may throw `ios_base::failure`
|
| 729 |
[[iostate.flags]]);
|
| 730 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
| 731 |
available input character `c` (in which case `c` is extracted).
|
| 732 |
|
| 733 |
-
*
|
| 734 |
-
`traits::eq_int_type(delim, traits::eof())`.
|
| 735 |
|
| 736 |
*Returns:* `*this`.
|
| 737 |
|
| 738 |
``` cpp
|
| 739 |
int_type peek();
|
| 740 |
```
|
| 741 |
|
| 742 |
*Effects:* Behaves as an unformatted input function (as described
|
| 743 |
-
above). After constructing a sentry object, reads but does not extract
|
| 744 |
the current input character.
|
| 745 |
|
| 746 |
*Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
|
| 747 |
`rdbuf()->sgetc()`.
|
| 748 |
|
| 749 |
``` cpp
|
| 750 |
-
basic_istream
|
| 751 |
```
|
| 752 |
|
| 753 |
*Effects:* Behaves as an unformatted input function (as described
|
| 754 |
-
above). After constructing a sentry object, if `!good()` calls
|
| 755 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 756 |
extracts characters and stores them into successive locations of an
|
| 757 |
-
array whose first element is designated by `s`.[^
|
| 758 |
-
|
|
|
|
|
|
|
| 759 |
|
| 760 |
- `n` characters are stored;
|
| 761 |
- end-of-file occurs on the input sequence (in which case the function
|
| 762 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 763 |
`ios_base::failure` [[iostate.flags]]).
|
|
@@ -767,11 +851,11 @@ extracted and stored until either of the following occurs:
|
|
| 767 |
``` cpp
|
| 768 |
streamsize readsome(char_type* s, streamsize n);
|
| 769 |
```
|
| 770 |
|
| 771 |
*Effects:* Behaves as an unformatted input function (as described
|
| 772 |
-
above). After constructing a sentry object, if `!good()` calls
|
| 773 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 774 |
extracts characters and stores them into successive locations of an
|
| 775 |
array whose first element is designated by `s`. If
|
| 776 |
`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
|
| 777 |
`ios_base::failure` [[iostate.flags]]), and extracts no characters;
|
|
@@ -780,51 +864,51 @@ array whose first element is designated by `s`. If
|
|
| 780 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 781 |
|
| 782 |
*Returns:* The number of characters extracted.
|
| 783 |
|
| 784 |
``` cpp
|
| 785 |
-
basic_istream
|
| 786 |
```
|
| 787 |
|
| 788 |
*Effects:* Behaves as an unformatted input function (as described
|
| 789 |
above), except that the function first clears `eofbit`. After
|
| 790 |
-
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 791 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 792 |
calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
|
| 793 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 794 |
`ios_base::failure` [[iostate.flags]]).
|
| 795 |
|
| 796 |
-
[*Note 1*: This function extracts no characters, so the value returned
|
| 797 |
-
by the next call to `gcount()` is 0. — *end note*]
|
| 798 |
-
|
| 799 |
-
*Returns:* `*this`.
|
| 800 |
-
|
| 801 |
-
``` cpp
|
| 802 |
-
basic_istream<charT, traits>& unget();
|
| 803 |
-
```
|
| 804 |
-
|
| 805 |
-
*Effects:* Behaves as an unformatted input function (as described
|
| 806 |
-
above), except that the function first clears `eofbit`. After
|
| 807 |
-
constructing a sentry object, if `!good()` calls `setstate(failbit)`
|
| 808 |
-
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 809 |
-
calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
|
| 810 |
-
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 811 |
-
`ios_base::failure` [[iostate.flags]]).
|
| 812 |
-
|
| 813 |
[*Note 2*: This function extracts no characters, so the value returned
|
| 814 |
by the next call to `gcount()` is 0. — *end note*]
|
| 815 |
|
| 816 |
*Returns:* `*this`.
|
| 817 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 818 |
``` cpp
|
| 819 |
int sync();
|
| 820 |
```
|
| 821 |
|
| 822 |
*Effects:* Behaves as an unformatted input function (as described
|
| 823 |
above), except that it does not count the number of characters extracted
|
| 824 |
and does not affect the value returned by subsequent calls to
|
| 825 |
-
`gcount()`. After constructing a sentry object, if `rdbuf()` is a null
|
| 826 |
pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
|
| 827 |
that function returns `-1` calls `setstate(badbit)` (which may throw
|
| 828 |
`ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
|
| 829 |
returns zero.
|
| 830 |
|
|
@@ -835,38 +919,38 @@ pos_type tellg();
|
|
| 835 |
*Effects:* Behaves as an unformatted input function (as described
|
| 836 |
above), except that it does not count the number of characters extracted
|
| 837 |
and does not affect the value returned by subsequent calls to
|
| 838 |
`gcount()`.
|
| 839 |
|
| 840 |
-
*Returns:* After constructing a sentry object, if `fail() != false`,
|
| 841 |
returns `pos_type(-1)` to indicate failure. Otherwise, returns
|
| 842 |
`rdbuf()->pubseekoff(0, cur, in)`.
|
| 843 |
|
| 844 |
``` cpp
|
| 845 |
-
basic_istream
|
| 846 |
```
|
| 847 |
|
| 848 |
*Effects:* Behaves as an unformatted input function (as described
|
| 849 |
above), except that the function first clears `eofbit`, it does not
|
| 850 |
count the number of characters extracted, and it does not affect the
|
| 851 |
value returned by subsequent calls to `gcount()`. After constructing a
|
| 852 |
-
sentry object, if `fail() != true`, executes
|
| 853 |
`rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
|
| 854 |
function calls `setstate(failbit)` (which may throw
|
| 855 |
`ios_base::failure`).
|
| 856 |
|
| 857 |
*Returns:* `*this`.
|
| 858 |
|
| 859 |
``` cpp
|
| 860 |
-
basic_istream
|
| 861 |
```
|
| 862 |
|
| 863 |
*Effects:* Behaves as an unformatted input function (as described
|
| 864 |
above), except that the function first clears `eofbit`, does not count
|
| 865 |
the number of characters extracted, and does not affect the value
|
| 866 |
-
returned by subsequent calls to `gcount()`. After constructing a
|
| 867 |
-
object, if `fail() != true`, executes
|
| 868 |
`rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
|
| 869 |
function calls `setstate(failbit)` (which may throw
|
| 870 |
`ios_base::failure`).
|
| 871 |
|
| 872 |
*Returns:* `*this`.
|
|
@@ -882,11 +966,11 @@ template<class charT, class traits>
|
|
| 882 |
```
|
| 883 |
|
| 884 |
*Effects:* Behaves as an unformatted input
|
| 885 |
function [[istream.unformatted]], except that it does not count the
|
| 886 |
number of characters extracted and does not affect the value returned by
|
| 887 |
-
subsequent calls to `is.gcount()`. After constructing a sentry object
|
| 888 |
extracts characters as long as the next available character `c` is
|
| 889 |
whitespace or until there are no more characters in the sequence.
|
| 890 |
Whitespace characters are distinguished with the same criterion as used
|
| 891 |
by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
|
| 892 |
characters because there are no more available it sets `eofbit`, but not
|
|
@@ -900,22 +984,24 @@ characters because there are no more available it sets `eofbit`, but not
|
|
| 900 |
template<class Istream, class T>
|
| 901 |
Istream&& operator>>(Istream&& is, T&& x);
|
| 902 |
```
|
| 903 |
|
| 904 |
*Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
|
| 905 |
-
when treated as an unevaluated operand
|
| 906 |
-
unambiguously derived from `ios_base`.
|
| 907 |
|
| 908 |
*Effects:* Equivalent to:
|
| 909 |
|
| 910 |
``` cpp
|
| 911 |
is >> std::forward<T>(x);
|
| 912 |
return std::move(is);
|
| 913 |
```
|
| 914 |
|
| 915 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 916 |
|
|
|
|
|
|
|
| 917 |
``` cpp
|
| 918 |
namespace std {
|
| 919 |
template<class charT, class traits = char_traits<charT>>
|
| 920 |
class basic_iostream
|
| 921 |
: public basic_istream<charT, traits>,
|
|
@@ -936,11 +1022,11 @@ namespace std {
|
|
| 936 |
protected:
|
| 937 |
// [iostream.cons], constructor
|
| 938 |
basic_iostream(const basic_iostream&) = delete;
|
| 939 |
basic_iostream(basic_iostream&& rhs);
|
| 940 |
|
| 941 |
-
// [iostream.assign],
|
| 942 |
basic_iostream& operator=(const basic_iostream&) = delete;
|
| 943 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 944 |
void swap(basic_iostream& rhs);
|
| 945 |
};
|
| 946 |
}
|
|
@@ -965,11 +1051,11 @@ explicit basic_iostream(basic_streambuf<charT, traits>* sb);
|
|
| 965 |
``` cpp
|
| 966 |
basic_iostream(basic_iostream&& rhs);
|
| 967 |
```
|
| 968 |
|
| 969 |
*Effects:* Move constructs from the rvalue `rhs` by constructing the
|
| 970 |
-
`basic_istream` base class with `move(rhs)`.
|
| 971 |
|
| 972 |
##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
|
| 973 |
|
| 974 |
``` cpp
|
| 975 |
virtual ~basic_iostream();
|
|
@@ -991,16 +1077,24 @@ void swap(basic_iostream& rhs);
|
|
| 991 |
|
| 992 |
*Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
|
| 993 |
|
| 994 |
### Output streams <a id="output.streams">[[output.streams]]</a>
|
| 995 |
|
| 996 |
-
|
| 997 |
-
|
| 998 |
-
|
|
|
|
|
|
|
| 999 |
|
| 1000 |
#### Class template `basic_ostream` <a id="ostream">[[ostream]]</a>
|
| 1001 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1002 |
``` cpp
|
| 1003 |
namespace std {
|
| 1004 |
template<class charT, class traits = char_traits<charT>>
|
| 1005 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 1006 |
public:
|
|
@@ -1017,51 +1111,50 @@ namespace std {
|
|
| 1017 |
|
| 1018 |
// [ostream.sentry], prefix/suffix
|
| 1019 |
class sentry;
|
| 1020 |
|
| 1021 |
// [ostream.formatted], formatted output
|
| 1022 |
-
basic_ostream<
|
| 1023 |
-
|
| 1024 |
-
basic_ostream<
|
| 1025 |
-
operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 1026 |
-
basic_ostream<charT, traits>&
|
| 1027 |
-
operator<<(ios_base& (*pf)(ios_base&));
|
| 1028 |
|
| 1029 |
-
basic_ostream
|
| 1030 |
-
basic_ostream
|
| 1031 |
-
basic_ostream
|
| 1032 |
-
basic_ostream
|
| 1033 |
-
basic_ostream
|
| 1034 |
-
basic_ostream
|
| 1035 |
-
basic_ostream
|
| 1036 |
-
basic_ostream
|
| 1037 |
-
basic_ostream
|
| 1038 |
-
basic_ostream
|
| 1039 |
-
basic_ostream
|
| 1040 |
-
basic_ostream
|
|
|
|
| 1041 |
|
| 1042 |
-
basic_ostream
|
| 1043 |
-
basic_ostream
|
| 1044 |
-
basic_ostream
|
|
|
|
| 1045 |
|
| 1046 |
// [ostream.unformatted], unformatted output
|
| 1047 |
-
basic_ostream
|
| 1048 |
-
basic_ostream
|
| 1049 |
|
| 1050 |
-
basic_ostream
|
| 1051 |
|
| 1052 |
// [ostream.seeks], seeks
|
| 1053 |
pos_type tellp();
|
| 1054 |
-
basic_ostream
|
| 1055 |
-
basic_ostream
|
| 1056 |
|
| 1057 |
protected:
|
| 1058 |
// [ostream.cons], copy/move constructor
|
| 1059 |
basic_ostream(const basic_ostream&) = delete;
|
| 1060 |
basic_ostream(basic_ostream&& rhs);
|
| 1061 |
|
| 1062 |
-
// [ostream.assign],
|
| 1063 |
basic_ostream& operator=(const basic_ostream&) = delete;
|
| 1064 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 1065 |
void swap(basic_ostream& rhs);
|
| 1066 |
};
|
| 1067 |
|
|
@@ -1197,15 +1290,16 @@ void swap(basic_ostream& rhs);
|
|
| 1197 |
|
| 1198 |
##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
|
| 1199 |
|
| 1200 |
``` cpp
|
| 1201 |
namespace std {
|
| 1202 |
-
template<class charT, class traits
|
| 1203 |
class basic_ostream<charT, traits>::sentry {
|
| 1204 |
bool ok_; // exposition only
|
|
|
|
| 1205 |
public:
|
| 1206 |
-
explicit sentry(basic_ostream
|
| 1207 |
~sentry();
|
| 1208 |
explicit operator bool() const { return ok_; }
|
| 1209 |
|
| 1210 |
sentry(const sentry&) = delete;
|
| 1211 |
sentry& operator=(const sentry&) = delete;
|
|
@@ -1215,20 +1309,20 @@ namespace std {
|
|
| 1215 |
|
| 1216 |
The class `sentry` defines a class that is responsible for doing
|
| 1217 |
exception safe prefix and suffix operations.
|
| 1218 |
|
| 1219 |
``` cpp
|
| 1220 |
-
explicit sentry(basic_ostream
|
| 1221 |
```
|
| 1222 |
|
| 1223 |
If `os.good()` is nonzero, prepares for formatted or unformatted output.
|
| 1224 |
-
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^
|
| 1225 |
|
| 1226 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 1227 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 1228 |
constructor may call `setstate(failbit)` (which may throw
|
| 1229 |
-
`ios_base::failure` [[iostate.flags]]).[^
|
| 1230 |
|
| 1231 |
``` cpp
|
| 1232 |
~sentry();
|
| 1233 |
```
|
| 1234 |
|
|
@@ -1254,22 +1348,22 @@ pos_type tellp();
|
|
| 1254 |
|
| 1255 |
*Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
|
| 1256 |
failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
|
| 1257 |
|
| 1258 |
``` cpp
|
| 1259 |
-
basic_ostream
|
| 1260 |
```
|
| 1261 |
|
| 1262 |
*Effects:* If `fail() != true`, executes
|
| 1263 |
`rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
|
| 1264 |
function calls `setstate(failbit)` (which may throw
|
| 1265 |
`ios_base::failure`).
|
| 1266 |
|
| 1267 |
*Returns:* `*this`.
|
| 1268 |
|
| 1269 |
``` cpp
|
| 1270 |
-
basic_ostream
|
| 1271 |
```
|
| 1272 |
|
| 1273 |
*Effects:* If `fail() != true`, executes
|
| 1274 |
`rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
|
| 1275 |
function calls `setstate(failbit)` (which may throw
|
|
@@ -1280,20 +1374,22 @@ function calls `setstate(failbit)` (which may throw
|
|
| 1280 |
#### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
|
| 1281 |
|
| 1282 |
##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
|
| 1283 |
|
| 1284 |
Each formatted output function begins execution by constructing an
|
| 1285 |
-
object of class `sentry`. If
|
| 1286 |
to a value of type `bool`, the function endeavors to generate the
|
| 1287 |
requested output. If the generation fails, then the formatted output
|
| 1288 |
-
function does `setstate(ios_base::failbit)`, which
|
| 1289 |
exception. If an exception is thrown during output, then
|
| 1290 |
-
`ios_base::badbit` is
|
| 1291 |
-
|
| 1292 |
-
|
| 1293 |
-
|
| 1294 |
-
|
|
|
|
|
|
|
| 1295 |
|
| 1296 |
The descriptions of the individual formatted output functions describe
|
| 1297 |
how they perform output and do not mention the `sentry` object.
|
| 1298 |
|
| 1299 |
If a formatted output function of a stream `os` determines padding, it
|
|
@@ -1306,23 +1402,23 @@ the fill characters are placed after the character sequence; otherwise,
|
|
| 1306 |
they are placed before the character sequence.
|
| 1307 |
|
| 1308 |
##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
|
| 1309 |
|
| 1310 |
``` cpp
|
| 1311 |
-
operator<<(bool val);
|
| 1312 |
-
operator<<(short val);
|
| 1313 |
-
operator<<(unsigned short val);
|
| 1314 |
-
operator<<(int val);
|
| 1315 |
-
operator<<(unsigned int val);
|
| 1316 |
-
operator<<(long val);
|
| 1317 |
-
operator<<(unsigned long val);
|
| 1318 |
-
operator<<(long long val);
|
| 1319 |
-
operator<<(unsigned long long val);
|
| 1320 |
-
operator<<(float val);
|
| 1321 |
-
operator<<(double val);
|
| 1322 |
-
operator<<(long double val);
|
| 1323 |
-
operator<<(const void* val);
|
| 1324 |
```
|
| 1325 |
|
| 1326 |
*Effects:* The classes `num_get<>` and `num_put<>` handle
|
| 1327 |
locale-dependent numeric formatting and parsing. These inserter
|
| 1328 |
functions use the imbued `locale` value to perform numeric formatting.
|
|
@@ -1393,49 +1489,90 @@ It provides formatting specifications such as field width, and a locale
|
|
| 1393 |
from which to obtain other facets. If `failed` is `true` then does
|
| 1394 |
`setstate(badbit)`, which may throw an exception, and returns.
|
| 1395 |
|
| 1396 |
*Returns:* `*this`.
|
| 1397 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1398 |
##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
|
| 1399 |
|
| 1400 |
``` cpp
|
| 1401 |
-
basic_ostream<
|
| 1402 |
-
operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
|
| 1403 |
```
|
| 1404 |
|
| 1405 |
*Effects:* None. Does not behave as a formatted output function (as
|
| 1406 |
described in [[ostream.formatted.reqmts]]).
|
| 1407 |
|
| 1408 |
-
*Returns:* `pf(*this)`.[^
|
| 1409 |
|
| 1410 |
``` cpp
|
| 1411 |
-
basic_ostream<charT, traits>&
|
| 1412 |
-
operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 1413 |
```
|
| 1414 |
|
| 1415 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 1416 |
formatted output function (as described
|
| 1417 |
in [[ostream.formatted.reqmts]]).
|
| 1418 |
|
| 1419 |
-
*Returns:* `*this`.[^
|
| 1420 |
|
| 1421 |
``` cpp
|
| 1422 |
-
basic_ostream
|
| 1423 |
```
|
| 1424 |
|
| 1425 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 1426 |
formatted output function (as described
|
| 1427 |
in [[ostream.formatted.reqmts]]).
|
| 1428 |
|
| 1429 |
*Returns:* `*this`.
|
| 1430 |
|
| 1431 |
``` cpp
|
| 1432 |
-
basic_ostream
|
| 1433 |
```
|
| 1434 |
|
| 1435 |
*Effects:* Behaves as an unformatted output
|
| 1436 |
-
function [[ostream.unformatted]]. After the sentry object is
|
| 1437 |
constructed, if `sb` is null calls `setstate(badbit)` (which may throw
|
| 1438 |
`ios_base::failure`).
|
| 1439 |
|
| 1440 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 1441 |
read from `sb` and inserted until any of the following occurs:
|
|
@@ -1452,11 +1589,11 @@ the error state, and if `failbit` is set in `exceptions()` the caught
|
|
| 1452 |
exception is rethrown.
|
| 1453 |
|
| 1454 |
*Returns:* `*this`.
|
| 1455 |
|
| 1456 |
``` cpp
|
| 1457 |
-
basic_ostream
|
| 1458 |
```
|
| 1459 |
|
| 1460 |
*Effects:* Equivalent to:
|
| 1461 |
|
| 1462 |
``` cpp
|
|
@@ -1529,29 +1666,98 @@ Determines padding for `seq` as described
|
|
| 1529 |
in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
|
| 1530 |
`width(0)`.
|
| 1531 |
|
| 1532 |
*Returns:* `out`.
|
| 1533 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1534 |
#### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
|
| 1535 |
|
| 1536 |
Each unformatted output function begins execution by constructing an
|
| 1537 |
-
object of class `sentry`. If
|
| 1538 |
converting to a value of type `bool`, the function endeavors to generate
|
| 1539 |
the requested output. If an exception is thrown during output, then
|
| 1540 |
-
`ios_base::badbit` is
|
| 1541 |
-
|
| 1542 |
-
|
| 1543 |
-
|
| 1544 |
-
|
|
|
|
| 1545 |
|
| 1546 |
``` cpp
|
| 1547 |
-
basic_ostream
|
| 1548 |
```
|
| 1549 |
|
| 1550 |
*Effects:* Behaves as an unformatted output function (as described
|
| 1551 |
-
above). After constructing a sentry object, inserts the character `c`,
|
| 1552 |
-
if possible.[^
|
| 1553 |
|
| 1554 |
Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 1555 |
[[iostate.flags]]).
|
| 1556 |
|
| 1557 |
*Returns:* `*this`.
|
|
@@ -1559,14 +1765,15 @@ Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
|
|
| 1559 |
``` cpp
|
| 1560 |
basic_ostream& write(const char_type* s, streamsize n);
|
| 1561 |
```
|
| 1562 |
|
| 1563 |
*Effects:* Behaves as an unformatted output function (as described
|
| 1564 |
-
above). After constructing a sentry object, obtains characters to
|
| 1565 |
-
from successive locations of an array whose first element is
|
| 1566 |
-
by `s`.[^
|
| 1567 |
-
|
|
|
|
| 1568 |
|
| 1569 |
- `n` characters are inserted;
|
| 1570 |
- inserting in the output sequence fails (in which case the function
|
| 1571 |
calls `setstate(badbit)`, which may throw `ios_base::failure`
|
| 1572 |
[[iostate.flags]]).
|
|
@@ -1576,15 +1783,15 @@ occurs:
|
|
| 1576 |
``` cpp
|
| 1577 |
basic_ostream& flush();
|
| 1578 |
```
|
| 1579 |
|
| 1580 |
*Effects:* Behaves as an unformatted output function (as described
|
| 1581 |
-
above). If `rdbuf()` is not a null pointer, constructs a sentry
|
| 1582 |
-
If
|
| 1583 |
-
the function calls `rdbuf()->pubsync()`. If that function returns
|
| 1584 |
-
calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 1585 |
-
[[iostate.flags]]). Otherwise, if the sentry object returns `false`,
|
| 1586 |
does nothing.
|
| 1587 |
|
| 1588 |
*Returns:* `*this`.
|
| 1589 |
|
| 1590 |
#### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
|
|
@@ -1654,11 +1861,14 @@ template<class charT, class traits>
|
|
| 1654 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 1655 |
```
|
| 1656 |
|
| 1657 |
*Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
|
| 1658 |
`basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
|
| 1659 |
-
of exposition,
|
|
|
|
|
|
|
|
|
|
| 1660 |
|
| 1661 |
*Returns:* `os`.
|
| 1662 |
|
| 1663 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 1664 |
|
|
@@ -1688,11 +1898,11 @@ unspecified resetiosflags(ios_base::fmtflags mask);
|
|
| 1688 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 1689 |
of type `basic_ostream<charT, traits>` then the expression
|
| 1690 |
`out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
|
| 1691 |
if `in` is an object of type `basic_istream<charT, traits>` then the
|
| 1692 |
expression `in >> resetiosflags(mask)` behaves as if it called
|
| 1693 |
-
`f(in, mask)`, where the function `f` is defined as:[^
|
| 1694 |
|
| 1695 |
``` cpp
|
| 1696 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 1697 |
// reset specified flags
|
| 1698 |
str.setf(ios_base::fmtflags(0), mask);
|
|
@@ -1887,25 +2097,25 @@ void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
|
|
| 1887 |
|
| 1888 |
The expression `out << put_money(mon, intl)` has type
|
| 1889 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 1890 |
|
| 1891 |
``` cpp
|
| 1892 |
-
template<class charT> unspecified get_time(
|
| 1893 |
```
|
| 1894 |
|
| 1895 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 1896 |
-
type `
|
| 1897 |
-
|
| 1898 |
|
| 1899 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 1900 |
of type `basic_istream<charT, traits>` then the expression
|
| 1901 |
`in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
|
| 1902 |
where the function `f` is defined as:
|
| 1903 |
|
| 1904 |
``` cpp
|
| 1905 |
template<class charT, class traits>
|
| 1906 |
-
void f(basic_ios<charT, traits>& str,
|
| 1907 |
using Iter = istreambuf_iterator<charT, traits>;
|
| 1908 |
using TimeGet = time_get<charT, Iter>;
|
| 1909 |
|
| 1910 |
ios_base::iostate err = ios_base::goodbit;
|
| 1911 |
const TimeGet& tg = use_facet<TimeGet>(str.getloc());
|
|
@@ -1920,25 +2130,25 @@ void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
|
|
| 1920 |
|
| 1921 |
The expression `in >> get_time(tmb, fmt)` has type
|
| 1922 |
`basic_istream<charT, traits>&` and value `in`.
|
| 1923 |
|
| 1924 |
``` cpp
|
| 1925 |
-
template<class charT> unspecified put_time(const
|
| 1926 |
```
|
| 1927 |
|
| 1928 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 1929 |
-
type `
|
| 1930 |
-
|
| 1931 |
|
| 1932 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 1933 |
of type `basic_ostream<charT, traits>` then the expression
|
| 1934 |
`out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
|
| 1935 |
where the function `f` is defined as:
|
| 1936 |
|
| 1937 |
``` cpp
|
| 1938 |
template<class charT, class traits>
|
| 1939 |
-
void f(basic_ios<charT, traits>& str, const
|
| 1940 |
using Iter = ostreambuf_iterator<charT, traits>;
|
| 1941 |
using TimePut = time_put<charT, Iter>;
|
| 1942 |
|
| 1943 |
const TimePut& tp = use_facet<TimePut>(str.getloc());
|
| 1944 |
const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
|
|
@@ -2027,5 +2237,126 @@ template<class charT, class traits, class Allocator>
|
|
| 2027 |
- The expression `in >> quoted(s, delim, escape)` has type
|
| 2028 |
`basic_istream<charT, traits>&` and value `in`.
|
| 2029 |
- The expression `out << quoted(s, delim, escape)` has type
|
| 2030 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 2031 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 17 |
using wiostream = basic_iostream<wchar_t>;
|
| 18 |
|
| 19 |
template<class charT, class traits>
|
| 20 |
basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
|
| 21 |
|
| 22 |
+
template<class Istream, class T>
|
| 23 |
+
Istream&& operator>>(Istream&& is, T&& x);
|
| 24 |
}
|
| 25 |
```
|
| 26 |
|
| 27 |
### Header `<ostream>` synopsis <a id="ostream.syn">[[ostream.syn]]</a>
|
| 28 |
|
|
|
|
| 46 |
template<class charT, class traits>
|
| 47 |
basic_ostream<charT, traits>& noemit_on_flush(basic_ostream<charT, traits>& os);
|
| 48 |
template<class charT, class traits>
|
| 49 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 50 |
|
| 51 |
+
template<class Ostream, class T>
|
| 52 |
+
Ostream&& operator<<(Ostream&& os, const T& x);
|
| 53 |
+
|
| 54 |
+
// [ostream.formatted.print], print functions
|
| 55 |
+
template<class... Args>
|
| 56 |
+
void print(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 57 |
+
template<class... Args>
|
| 58 |
+
void println(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 59 |
+
|
| 60 |
+
void vprint_unicode(ostream& os, string_view fmt, format_args args);
|
| 61 |
+
void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
|
| 62 |
}
|
| 63 |
```
|
| 64 |
|
| 65 |
### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
|
| 66 |
|
| 67 |
``` cpp
|
| 68 |
namespace std {
|
| 69 |
+
unspecified resetiosflags(ios_base::fmtflags mask);
|
| 70 |
+
unspecified setiosflags (ios_base::fmtflags mask);
|
| 71 |
+
unspecified setbase(int base);
|
| 72 |
+
template<class charT> unspecified setfill(charT c);
|
| 73 |
+
unspecified setprecision(int n);
|
| 74 |
+
unspecified setw(int n);
|
| 75 |
+
template<class moneyT> unspecified get_money(moneyT& mon, bool intl = false);
|
| 76 |
+
template<class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);
|
| 77 |
+
template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
|
| 78 |
+
template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
|
|
|
|
| 79 |
|
| 80 |
template<class charT>
|
| 81 |
+
unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
|
| 82 |
|
| 83 |
template<class charT, class traits, class Allocator>
|
| 84 |
+
unspecified quoted(const basic_string<charT, traits, Allocator>& s,
|
| 85 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 86 |
|
| 87 |
template<class charT, class traits, class Allocator>
|
| 88 |
+
unspecified quoted(basic_string<charT, traits, Allocator>& s,
|
| 89 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 90 |
|
| 91 |
template<class charT, class traits>
|
| 92 |
+
unspecified quoted(basic_string_view<charT, traits> s,
|
| 93 |
\itcorr charT delim = charT('"'), charT escape = charT('\\'));
|
| 94 |
}
|
| 95 |
```
|
| 96 |
|
| 97 |
+
### Header `<print>` synopsis <a id="print.syn">[[print.syn]]</a>
|
| 98 |
+
|
| 99 |
+
``` cpp
|
| 100 |
+
namespace std {
|
| 101 |
+
// [print.fun], print functions
|
| 102 |
+
template<class... Args>
|
| 103 |
+
void print(format_string<Args...> fmt, Args&&... args);
|
| 104 |
+
template<class... Args>
|
| 105 |
+
void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 106 |
+
|
| 107 |
+
template<class... Args>
|
| 108 |
+
void println(format_string<Args...> fmt, Args&&... args);
|
| 109 |
+
template<class... Args>
|
| 110 |
+
void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 111 |
+
|
| 112 |
+
void vprint_unicode(string_view fmt, format_args args);
|
| 113 |
+
void vprint_unicode(FILE* stream, string_view fmt, format_args args);
|
| 114 |
+
|
| 115 |
+
void vprint_nonunicode(string_view fmt, format_args args);
|
| 116 |
+
void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
|
| 117 |
+
}
|
| 118 |
+
```
|
| 119 |
+
|
| 120 |
### Input streams <a id="input.streams">[[input.streams]]</a>
|
| 121 |
|
| 122 |
+
#### General <a id="input.streams.general">[[input.streams.general]]</a>
|
| 123 |
+
|
| 124 |
+
The header `<istream>` defines two class templates and a function
|
| 125 |
+
template that control input from a stream buffer, along with a function
|
| 126 |
+
template that extracts from stream rvalues.
|
| 127 |
|
| 128 |
#### Class template `basic_istream` <a id="istream">[[istream]]</a>
|
| 129 |
|
| 130 |
+
##### General <a id="istream.general">[[istream.general]]</a>
|
| 131 |
+
|
| 132 |
+
When a function is specified with a type placeholder of
|
| 133 |
+
`extended-floating-point-type`, the implementation provides overloads
|
| 134 |
+
for all cv-unqualified extended floating-point types
|
| 135 |
+
[[basic.fundamental]] in lieu of `extended-floating-{point-type}`.
|
| 136 |
+
|
| 137 |
``` cpp
|
| 138 |
namespace std {
|
| 139 |
template<class charT, class traits = char_traits<charT>>
|
| 140 |
class basic_istream : virtual public basic_ios<charT, traits> {
|
| 141 |
public:
|
|
|
|
| 152 |
|
| 153 |
// [istream.sentry], prefix/suffix
|
| 154 |
class sentry;
|
| 155 |
|
| 156 |
// [istream.formatted], formatted input
|
| 157 |
+
basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
|
| 158 |
+
basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 159 |
+
basic_istream& operator>>(ios_base& (*pf)(ios_base&));
|
|
|
|
|
|
|
|
|
|
| 160 |
|
| 161 |
+
basic_istream& operator>>(bool& n);
|
| 162 |
+
basic_istream& operator>>(short& n);
|
| 163 |
+
basic_istream& operator>>(unsigned short& n);
|
| 164 |
+
basic_istream& operator>>(int& n);
|
| 165 |
+
basic_istream& operator>>(unsigned int& n);
|
| 166 |
+
basic_istream& operator>>(long& n);
|
| 167 |
+
basic_istream& operator>>(unsigned long& n);
|
| 168 |
+
basic_istream& operator>>(long long& n);
|
| 169 |
+
basic_istream& operator>>(unsigned long long& n);
|
| 170 |
+
basic_istream& operator>>(float& f);
|
| 171 |
+
basic_istream& operator>>(double& f);
|
| 172 |
+
basic_istream& operator>>(long double& f);
|
| 173 |
+
basic_istream& operator>>(extended-floating-point-type& f);
|
| 174 |
|
| 175 |
+
basic_istream& operator>>(void*& p);
|
| 176 |
+
basic_istream& operator>>(basic_streambuf<char_type, traits>* sb);
|
| 177 |
|
| 178 |
// [istream.unformatted], unformatted input
|
| 179 |
streamsize gcount() const;
|
| 180 |
int_type get();
|
| 181 |
+
basic_istream& get(char_type& c);
|
| 182 |
+
basic_istream& get(char_type* s, streamsize n);
|
| 183 |
+
basic_istream& get(char_type* s, streamsize n, char_type delim);
|
| 184 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb);
|
| 185 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb, char_type delim);
|
| 186 |
|
| 187 |
+
basic_istream& getline(char_type* s, streamsize n);
|
| 188 |
+
basic_istream& getline(char_type* s, streamsize n, char_type delim);
|
| 189 |
|
| 190 |
+
basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
|
| 191 |
int_type peek();
|
| 192 |
+
basic_istream& read (char_type* s, streamsize n);
|
| 193 |
streamsize readsome(char_type* s, streamsize n);
|
| 194 |
|
| 195 |
+
basic_istream& putback(char_type c);
|
| 196 |
+
basic_istream& unget();
|
| 197 |
int sync();
|
| 198 |
|
| 199 |
pos_type tellg();
|
| 200 |
+
basic_istream& seekg(pos_type);
|
| 201 |
+
basic_istream& seekg(off_type, ios_base::seekdir);
|
| 202 |
|
| 203 |
protected:
|
| 204 |
// [istream.cons], copy/move constructor
|
| 205 |
basic_istream(const basic_istream&) = delete;
|
| 206 |
basic_istream(basic_istream&& rhs);
|
| 207 |
|
| 208 |
+
// [istream.assign], assignment and swap
|
| 209 |
basic_istream& operator=(const basic_istream&) = delete;
|
| 210 |
basic_istream& operator=(basic_istream&& rhs);
|
| 211 |
void swap(basic_istream& rhs);
|
| 212 |
};
|
| 213 |
|
|
|
|
| 236 |
*formatted input functions* (or *extractors*) and the *unformatted input
|
| 237 |
functions.* Both groups of input functions are described as if they
|
| 238 |
obtain (or *extract*) input *characters* by calling `rdbuf()->sbumpc()`
|
| 239 |
or `rdbuf()->sgetc()`. They may use other public members of `istream`.
|
| 240 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 241 |
##### Constructors <a id="istream.cons">[[istream.cons]]</a>
|
| 242 |
|
| 243 |
``` cpp
|
| 244 |
explicit basic_istream(basic_streambuf<charT, traits>* sb);
|
| 245 |
```
|
|
|
|
| 282 |
|
| 283 |
##### Class `basic_istream::sentry` <a id="istream.sentry">[[istream.sentry]]</a>
|
| 284 |
|
| 285 |
``` cpp
|
| 286 |
namespace std {
|
| 287 |
+
template<class charT, class traits>
|
| 288 |
class basic_istream<charT, traits>::sentry {
|
| 289 |
bool ok_; // exposition only
|
| 290 |
+
|
| 291 |
public:
|
| 292 |
+
explicit sentry(basic_istream& is, bool noskipws = false);
|
| 293 |
~sentry();
|
| 294 |
explicit operator bool() const { return ok_; }
|
| 295 |
sentry(const sentry&) = delete;
|
| 296 |
sentry& operator=(const sentry&) = delete;
|
| 297 |
};
|
|
|
|
| 300 |
|
| 301 |
The class `sentry` defines a class that is responsible for doing
|
| 302 |
exception safe prefix and suffix operations.
|
| 303 |
|
| 304 |
``` cpp
|
| 305 |
+
explicit sentry(basic_istream& is, bool noskipws = false);
|
| 306 |
```
|
| 307 |
|
| 308 |
*Effects:* If `is.good()` is `false`, calls `is.setstate(failbit)`.
|
| 309 |
Otherwise, prepares for formatted or unformatted input. First, if
|
| 310 |
`is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
|
| 311 |
to synchronize the output sequence with any associated external C
|
| 312 |
stream. Except that this call can be suppressed if the put area of
|
| 313 |
`is.tie()` is empty. Further an implementation is allowed to defer the
|
| 314 |
call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
|
| 315 |
such call occurs before the `sentry` object is destroyed, the call to
|
| 316 |
+
`flush` may be eliminated entirely.[^18]
|
| 317 |
+
|
| 318 |
+
If `noskipws` is zero and `is.flags() & ios_base::skipws` is nonzero,
|
| 319 |
+
the function extracts and discards each character as long as the next
|
| 320 |
+
available input character `c` is a whitespace character. If
|
| 321 |
+
`is.rdbuf()->sbumpc()` or `is.rdbuf()->sgetc()` returns `traits::eof()`,
|
| 322 |
+
the function calls `setstate(failbit | eofbit)` (which may throw
|
| 323 |
+
`ios_base::failure`).
|
| 324 |
|
| 325 |
*Remarks:* The constructor
|
| 326 |
|
| 327 |
``` cpp
|
| 328 |
+
explicit sentry(basic_istream& is, bool noskipws = false)
|
| 329 |
```
|
| 330 |
|
| 331 |
uses the currently imbued locale in `is`, to determine whether the next
|
| 332 |
input character is whitespace or not.
|
| 333 |
|
|
|
|
| 360 |
#### Formatted input functions <a id="istream.formatted">[[istream.formatted]]</a>
|
| 361 |
|
| 362 |
##### Common requirements <a id="istream.formatted.reqmts">[[istream.formatted.reqmts]]</a>
|
| 363 |
|
| 364 |
Each formatted input function begins execution by constructing an object
|
| 365 |
+
of type `ios_base::iostate`, termed the local error state, and
|
| 366 |
+
initializing it to `ios_base::goodbit`. It then creates an object of
|
| 367 |
+
class `sentry` with the `noskipws` (second) argument `false`. If the
|
| 368 |
`sentry` object returns `true`, when converted to a value of type
|
| 369 |
+
`bool`, the function endeavors to obtain the requested input. Otherwise,
|
| 370 |
+
if the `sentry` constructor exits by throwing an exception or if the
|
| 371 |
+
`sentry` object produces `false` when converted to a value of type
|
| 372 |
+
`bool`, the function returns without attempting to obtain any input. If
|
| 373 |
+
`rdbuf()->sbumpc()` or `rdbuf()->sgetc()` returns `traits::eof()`, then
|
| 374 |
+
`ios_base::eofbit` is set in the local error state and the input
|
| 375 |
+
function stops trying to obtain the requested input. If an exception is
|
| 376 |
+
thrown during input then `ios_base::badbit` is set in the local error
|
| 377 |
+
state, `*this`’s error state is set to the local error state, and the
|
| 378 |
+
exception is rethrown if `(exceptions() & badbit) != 0`. After
|
| 379 |
+
extraction is done, the input function calls `setstate`, which sets
|
| 380 |
+
`*this`’s error state to the local error state, and may throw an
|
| 381 |
+
exception. In any case, the formatted input function destroys the
|
| 382 |
+
`sentry` object. If no exception has been thrown, it returns `*this`.
|
| 383 |
|
| 384 |
##### Arithmetic extractors <a id="istream.formatted.arithmetic">[[istream.formatted.arithmetic]]</a>
|
| 385 |
|
| 386 |
``` cpp
|
| 387 |
+
basic_istream& operator>>(unsigned short& val);
|
| 388 |
+
basic_istream& operator>>(unsigned int& val);
|
| 389 |
+
basic_istream& operator>>(long& val);
|
| 390 |
+
basic_istream& operator>>(unsigned long& val);
|
| 391 |
+
basic_istream& operator>>(long long& val);
|
| 392 |
+
basic_istream& operator>>(unsigned long long& val);
|
| 393 |
+
basic_istream& operator>>(float& val);
|
| 394 |
+
basic_istream& operator>>(double& val);
|
| 395 |
+
basic_istream& operator>>(long double& val);
|
| 396 |
+
basic_istream& operator>>(bool& val);
|
| 397 |
+
basic_istream& operator>>(void*& val);
|
| 398 |
```
|
| 399 |
|
| 400 |
As in the case of the inserters, these extractors depend on the locale’s
|
| 401 |
`num_get<>` [[locale.num.get]] object to perform parsing the input
|
| 402 |
stream data. These extractors behave as formatted input functions (as
|
| 403 |
+
described in [[istream.formatted.reqmts]]). After a `sentry` object is
|
| 404 |
constructed, the conversion occurs as if performed by the following code
|
| 405 |
+
fragment, where `state` represents the input function’s local error
|
| 406 |
+
state:
|
| 407 |
|
| 408 |
``` cpp
|
| 409 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 410 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, val);
|
|
|
|
|
|
|
| 411 |
```
|
| 412 |
|
| 413 |
In the above fragment, `loc` stands for the private member of the
|
| 414 |
`basic_ios` class.
|
| 415 |
|
|
|
|
| 420 |
|
| 421 |
Class `locale` relies on this type as its interface to `istream`, so
|
| 422 |
that it does not need to depend directly on `istream`.
|
| 423 |
|
| 424 |
``` cpp
|
| 425 |
+
basic_istream& operator>>(short& val);
|
| 426 |
```
|
| 427 |
|
| 428 |
The conversion occurs as if performed by the following code fragment
|
| 429 |
(using the same notation as for the preceding code fragment):
|
| 430 |
|
| 431 |
``` cpp
|
| 432 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
|
|
|
| 433 |
long lval;
|
| 434 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, lval);
|
| 435 |
if (lval < numeric_limits<short>::min()) {
|
| 436 |
+
state |= ios_base::failbit;
|
| 437 |
val = numeric_limits<short>::min();
|
| 438 |
} else if (numeric_limits<short>::max() < lval) {
|
| 439 |
+
state |= ios_base::failbit;
|
| 440 |
val = numeric_limits<short>::max();
|
| 441 |
} else
|
| 442 |
val = static_cast<short>(lval);
|
|
|
|
| 443 |
```
|
| 444 |
|
| 445 |
``` cpp
|
| 446 |
+
basic_istream& operator>>(int& val);
|
| 447 |
```
|
| 448 |
|
| 449 |
The conversion occurs as if performed by the following code fragment
|
| 450 |
(using the same notation as for the preceding code fragment):
|
| 451 |
|
| 452 |
``` cpp
|
| 453 |
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
|
|
|
| 454 |
long lval;
|
| 455 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, lval);
|
| 456 |
if (lval < numeric_limits<int>::min()) {
|
| 457 |
+
state |= ios_base::failbit;
|
| 458 |
val = numeric_limits<int>::min();
|
| 459 |
} else if (numeric_limits<int>::max() < lval) {
|
| 460 |
+
state |= ios_base::failbit;
|
| 461 |
val = numeric_limits<int>::max();
|
| 462 |
} else
|
| 463 |
val = static_cast<int>(lval);
|
|
|
|
| 464 |
```
|
| 465 |
|
| 466 |
+
``` cpp
|
| 467 |
+
basic_istream& operator>>(extended-floating-point-type& val);
|
| 468 |
+
```
|
| 469 |
+
|
| 470 |
+
If the floating-point conversion rank of
|
| 471 |
+
*`extended-floating-point-type`* is not less than or equal to that of
|
| 472 |
+
`long double`, then an invocation of the operator function is
|
| 473 |
+
conditionally supported with *implementation-defined* semantics.
|
| 474 |
+
|
| 475 |
+
Otherwise, let `FP` be a standard floating-point type:
|
| 476 |
+
|
| 477 |
+
- if the floating-point conversion rank of
|
| 478 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 479 |
+
`float`, then `FP` is `float`,
|
| 480 |
+
- otherwise, if the floating-point conversion rank of
|
| 481 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 482 |
+
`double`, then `FP` is `double`,
|
| 483 |
+
- otherwise, `FP` is `long double`.
|
| 484 |
+
|
| 485 |
+
The conversion occurs as if performed by the following code fragment
|
| 486 |
+
(using the same notation as for the preceding code fragment):
|
| 487 |
+
|
| 488 |
+
``` cpp
|
| 489 |
+
using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
|
| 490 |
+
FP fval;
|
| 491 |
+
use_facet<numget>(loc).get(*this, 0, *this, state, fval);
|
| 492 |
+
if (fval < -numeric_limits<extended-floating-point-type>::max()) {
|
| 493 |
+
state |= ios_base::failbit;
|
| 494 |
+
val = -numeric_limits<extended-floating-point-type>::max();
|
| 495 |
+
} else if (numeric_limits<extended-floating-point-type>::max() < fval) {
|
| 496 |
+
state |= ios_base::failbit;
|
| 497 |
+
val = numeric_limits<extended-floating-point-type>::max();
|
| 498 |
+
} else {
|
| 499 |
+
val = static_cast<extended-floating-point-type>(fval);
|
| 500 |
+
}
|
| 501 |
+
```
|
| 502 |
+
|
| 503 |
+
[*Note 2*: When the extended floating-point type has a floating-point
|
| 504 |
+
conversion rank that is not equal to the rank of any standard
|
| 505 |
+
floating-point type, then double rounding during the conversion can
|
| 506 |
+
result in inaccurate results. `from_chars` can be used in situations
|
| 507 |
+
where maximum accuracy is important. — *end note*]
|
| 508 |
+
|
| 509 |
##### `basic_istream::operator>>` <a id="istream.extractors">[[istream.extractors]]</a>
|
| 510 |
|
| 511 |
``` cpp
|
| 512 |
+
basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
|
|
|
|
| 513 |
```
|
| 514 |
|
| 515 |
*Effects:* None. This extractor does not behave as a formatted input
|
| 516 |
function (as described in [[istream.formatted.reqmts]]).
|
| 517 |
|
| 518 |
+
*Returns:* `pf(*this)`. [^20]
|
| 519 |
|
| 520 |
``` cpp
|
| 521 |
+
basic_istream& operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
|
|
|
| 522 |
```
|
| 523 |
|
| 524 |
*Effects:* Calls `pf(*this)`. This extractor does not behave as a
|
| 525 |
formatted input function (as described
|
| 526 |
in [[istream.formatted.reqmts]]).
|
| 527 |
|
| 528 |
*Returns:* `*this`.
|
| 529 |
|
| 530 |
``` cpp
|
| 531 |
+
basic_istream& operator>>(ios_base& (*pf)(ios_base&));
|
| 532 |
```
|
| 533 |
|
| 534 |
+
*Effects:* Calls `pf(*this)`.[^21]
|
| 535 |
+
|
| 536 |
+
This extractor does not behave as a formatted input function (as
|
| 537 |
+
described in [[istream.formatted.reqmts]]).
|
| 538 |
|
| 539 |
*Returns:* `*this`.
|
| 540 |
|
| 541 |
``` cpp
|
| 542 |
template<class charT, class traits, size_t N>
|
|
|
|
| 562 |
|
| 563 |
`operator>>` then stores a null byte (`charT()`) in the next position,
|
| 564 |
which may be the first position if no characters were extracted.
|
| 565 |
`operator>>` then calls `width(0)`.
|
| 566 |
|
| 567 |
+
If the function extracted no characters, `ios_base::failbit` is set in
|
| 568 |
+
the input function’s local error state before `setstate` is called.
|
| 569 |
|
| 570 |
*Returns:* `in`.
|
| 571 |
|
| 572 |
``` cpp
|
| 573 |
template<class charT, class traits>
|
|
|
|
| 577 |
template<class traits>
|
| 578 |
basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);
|
| 579 |
```
|
| 580 |
|
| 581 |
*Effects:* Behaves like a formatted input member (as described
|
| 582 |
+
in [[istream.formatted.reqmts]]) of `in`. A character is extracted from
|
| 583 |
+
`in`, if one is available, and stored in `c`. Otherwise,
|
| 584 |
+
`ios_base::failbit` is set in the input function’s local error state
|
| 585 |
+
before `setstate` is called.
|
| 586 |
|
| 587 |
*Returns:* `in`.
|
| 588 |
|
| 589 |
``` cpp
|
| 590 |
+
basic_istream& operator>>(basic_streambuf<charT, traits>* sb);
|
| 591 |
```
|
| 592 |
|
| 593 |
*Effects:* Behaves as an unformatted input
|
| 594 |
function [[istream.unformatted]]. If `sb` is null, calls
|
| 595 |
`setstate(failbit)`, which may throw `ios_base::failure`
|
| 596 |
+
[[iostate.flags]]. After a `sentry` object is constructed, extracts
|
| 597 |
characters from `*this` and inserts them in the output sequence
|
| 598 |
controlled by `sb`. Characters are extracted and inserted until any of
|
| 599 |
the following occurs:
|
| 600 |
|
| 601 |
- end-of-file occurs on the input sequence;
|
| 602 |
- inserting in the output sequence fails (in which case the character to
|
| 603 |
be inserted is not extracted);
|
| 604 |
- an exception occurs (in which case the exception is caught).
|
| 605 |
|
| 606 |
+
If the function inserts no characters, `ios_base::failbit` is set in the
|
| 607 |
+
input function’s local error state before `setstate` is called.
|
|
|
|
|
|
|
|
|
|
| 608 |
|
| 609 |
*Returns:* `*this`.
|
| 610 |
|
| 611 |
#### Unformatted input functions <a id="istream.unformatted">[[istream.unformatted]]</a>
|
| 612 |
|
| 613 |
Each unformatted input function begins execution by constructing an
|
| 614 |
+
object of type `ios_base::iostate`, termed the local error state, and
|
| 615 |
+
initializing it to `ios_base::goodbit`. It then creates an object of
|
| 616 |
+
class `sentry` with the default argument `noskipws` (second) argument
|
| 617 |
+
`true`. If the `sentry` object returns `true`, when converted to a value
|
| 618 |
+
of type `bool`, the function endeavors to obtain the requested input.
|
| 619 |
+
Otherwise, if the `sentry` constructor exits by throwing an exception or
|
| 620 |
+
if the `sentry` object produces `false`, when converted to a value of
|
| 621 |
+
type `bool`, the function returns without attempting to obtain any
|
| 622 |
+
input. In either case the number of extracted characters is set to 0;
|
| 623 |
+
unformatted input functions taking a character array of nonzero size as
|
| 624 |
+
an argument shall also store a null character (using `charT()`) in the
|
| 625 |
+
first location of the array. If `rdbuf()->sbumpc()` or
|
| 626 |
+
`rdbuf()->sgetc()` returns `traits::eof()`, then `ios_base::eofbit` is
|
| 627 |
+
set in the local error state and the input function stops trying to
|
| 628 |
+
obtain the requested input. If an exception is thrown during input then
|
| 629 |
+
`ios_base::badbit` is set in the local error state, `*this`’s error
|
| 630 |
+
state is set to the local error state, and the exception is rethrown if
|
| 631 |
+
`(exceptions() & badbit) != 0`. If no exception has been thrown it
|
| 632 |
+
stores the number of characters extracted in a member object. After
|
| 633 |
+
extraction is done, the input function calls `setstate`, which sets
|
| 634 |
+
`*this`’s error state to the local error state, and may throw an
|
| 635 |
+
exception. In any event the `sentry` object is destroyed before leaving
|
| 636 |
+
the unformatted input function.
|
| 637 |
|
| 638 |
``` cpp
|
| 639 |
streamsize gcount() const;
|
| 640 |
```
|
| 641 |
|
| 642 |
*Effects:* None. This member function does not behave as an unformatted
|
| 643 |
input function (as described above).
|
| 644 |
|
| 645 |
*Returns:* The number of characters extracted by the last unformatted
|
| 646 |
+
input member function called for the object. If the number cannot be
|
| 647 |
+
represented, returns `numeric_limits<streamsize>::max()`.
|
| 648 |
|
| 649 |
``` cpp
|
| 650 |
int_type get();
|
| 651 |
```
|
| 652 |
|
| 653 |
*Effects:* Behaves as an unformatted input function (as described
|
| 654 |
+
above). After constructing a `sentry` object, extracts a character `c`,
|
| 655 |
+
if one is available. Otherwise, `ios_base::failbit` is set in the input
|
| 656 |
+
function’s local error state before `setstate` is called.
|
| 657 |
|
| 658 |
*Returns:* `c` if available, otherwise `traits::eof()`.
|
| 659 |
|
| 660 |
``` cpp
|
| 661 |
+
basic_istream& get(char_type& c);
|
| 662 |
```
|
| 663 |
|
| 664 |
*Effects:* Behaves as an unformatted input function (as described
|
| 665 |
+
above). After constructing a `sentry` object, extracts a character, if
|
| 666 |
+
one is available, and assigns it to `c`.[^22]
|
| 667 |
+
|
| 668 |
+
Otherwise, `ios_base::failbit` is set in the input function’s local
|
| 669 |
+
error state before `setstate` is called.
|
| 670 |
|
| 671 |
*Returns:* `*this`.
|
| 672 |
|
| 673 |
``` cpp
|
| 674 |
+
basic_istream& get(char_type* s, streamsize n, char_type delim);
|
| 675 |
```
|
| 676 |
|
| 677 |
*Effects:* Behaves as an unformatted input function (as described
|
| 678 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 679 |
stores them into successive locations of an array whose first element is
|
| 680 |
+
designated by `s`.[^23]
|
| 681 |
+
|
| 682 |
+
Characters are extracted and stored until any of the following occurs:
|
| 683 |
|
| 684 |
- `n` is less than one or `n - 1` characters are stored;
|
| 685 |
+
- end-of-file occurs on the input sequence;
|
|
|
|
| 686 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 687 |
which case `c` is not extracted).
|
| 688 |
|
| 689 |
+
If the function stores no characters, `ios_base::failbit` is set in the
|
| 690 |
+
input function’s local error state before `setstate` is called. In any
|
| 691 |
+
case, if `n` is greater than zero it then stores a null character into
|
| 692 |
+
the next successive location of the array.
|
| 693 |
|
| 694 |
*Returns:* `*this`.
|
| 695 |
|
| 696 |
``` cpp
|
| 697 |
+
basic_istream& get(char_type* s, streamsize n);
|
| 698 |
```
|
| 699 |
|
| 700 |
*Effects:* Calls `get(s, n, widen(’\n’))`.
|
| 701 |
|
| 702 |
*Returns:* Value returned by the call.
|
| 703 |
|
| 704 |
``` cpp
|
| 705 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb, char_type delim);
|
| 706 |
```
|
| 707 |
|
| 708 |
*Effects:* Behaves as an unformatted input function (as described
|
| 709 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 710 |
inserts them in the output sequence controlled by `sb`. Characters are
|
| 711 |
extracted and inserted until any of the following occurs:
|
| 712 |
|
| 713 |
- end-of-file occurs on the input sequence;
|
| 714 |
- inserting in the output sequence fails (in which case the character to
|
|
|
|
| 716 |
- `traits::eq(c, delim)` for the next available input character `c` (in
|
| 717 |
which case `c` is not extracted);
|
| 718 |
- an exception occurs (in which case, the exception is caught but not
|
| 719 |
rethrown).
|
| 720 |
|
| 721 |
+
If the function inserts no characters, `ios_base::failbit` is set in the
|
| 722 |
+
input function’s local error state before `setstate` is called.
|
| 723 |
|
| 724 |
*Returns:* `*this`.
|
| 725 |
|
| 726 |
``` cpp
|
| 727 |
+
basic_istream& get(basic_streambuf<char_type, traits>& sb);
|
| 728 |
```
|
| 729 |
|
| 730 |
*Effects:* Calls `get(sb, widen(’\n’))`.
|
| 731 |
|
| 732 |
*Returns:* Value returned by the call.
|
| 733 |
|
| 734 |
``` cpp
|
| 735 |
+
basic_istream& getline(char_type* s, streamsize n, char_type delim);
|
| 736 |
```
|
| 737 |
|
| 738 |
*Effects:* Behaves as an unformatted input function (as described
|
| 739 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 740 |
stores them into successive locations of an array whose first element is
|
| 741 |
+
designated by `s`.[^24]
|
|
|
|
| 742 |
|
| 743 |
+
Characters are extracted and stored until one of the following occurs:
|
| 744 |
+
|
| 745 |
+
1. end-of-file occurs on the input sequence;
|
| 746 |
2. `traits::eq(c, delim)` for the next available input character `c`
|
| 747 |
(in which case the input character is extracted but not
|
| 748 |
+
stored);[^25]
|
| 749 |
3. `n` is less than one or `n - 1` characters are stored (in which case
|
| 750 |
the function calls `setstate(failbit)`).
|
| 751 |
|
| 752 |
+
These conditions are tested in the order shown.[^26]
|
| 753 |
|
| 754 |
+
If the function extracts no characters, `ios_base::failbit` is set in
|
| 755 |
+
the input function’s local error state before `setstate` is called.[^27]
|
| 756 |
|
| 757 |
In any case, if `n` is greater than zero, it then stores a null
|
| 758 |
character (using `charT()`) into the next successive location of the
|
| 759 |
array.
|
| 760 |
|
|
|
|
| 788 |
```
|
| 789 |
|
| 790 |
— *end example*]
|
| 791 |
|
| 792 |
``` cpp
|
| 793 |
+
basic_istream& getline(char_type* s, streamsize n);
|
| 794 |
```
|
| 795 |
|
| 796 |
*Returns:* `getline(s, n, widen(’\n’))`
|
| 797 |
|
| 798 |
``` cpp
|
| 799 |
+
basic_istream& ignore(streamsize n = 1, int_type delim = traits::eof());
|
| 800 |
```
|
| 801 |
|
| 802 |
*Effects:* Behaves as an unformatted input function (as described
|
| 803 |
+
above). After constructing a `sentry` object, extracts characters and
|
| 804 |
discards them. Characters are extracted until any of the following
|
| 805 |
occurs:
|
| 806 |
|
| 807 |
- `n != numeric_limits<streamsize>::max()` [[numeric.limits]] and `n`
|
| 808 |
characters have been extracted so far
|
|
|
|
| 810 |
calls `setstate(eofbit)`, which may throw `ios_base::failure`
|
| 811 |
[[iostate.flags]]);
|
| 812 |
- `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
|
| 813 |
available input character `c` (in which case `c` is extracted).
|
| 814 |
|
| 815 |
+
[*Note 1*: The last condition will never occur if
|
| 816 |
+
`traits::eq_int_type(delim, traits::eof())`. — *end note*]
|
| 817 |
|
| 818 |
*Returns:* `*this`.
|
| 819 |
|
| 820 |
``` cpp
|
| 821 |
int_type peek();
|
| 822 |
```
|
| 823 |
|
| 824 |
*Effects:* Behaves as an unformatted input function (as described
|
| 825 |
+
above). After constructing a `sentry` object, reads but does not extract
|
| 826 |
the current input character.
|
| 827 |
|
| 828 |
*Returns:* `traits::eof()` if `good()` is `false`. Otherwise, returns
|
| 829 |
`rdbuf()->sgetc()`.
|
| 830 |
|
| 831 |
``` cpp
|
| 832 |
+
basic_istream& read(char_type* s, streamsize n);
|
| 833 |
```
|
| 834 |
|
| 835 |
*Effects:* Behaves as an unformatted input function (as described
|
| 836 |
+
above). After constructing a `sentry` object, if `!good()` calls
|
| 837 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 838 |
extracts characters and stores them into successive locations of an
|
| 839 |
+
array whose first element is designated by `s`.[^28]
|
| 840 |
+
|
| 841 |
+
Characters are extracted and stored until either of the following
|
| 842 |
+
occurs:
|
| 843 |
|
| 844 |
- `n` characters are stored;
|
| 845 |
- end-of-file occurs on the input sequence (in which case the function
|
| 846 |
calls `setstate(failbit | eofbit)`, which may throw
|
| 847 |
`ios_base::failure` [[iostate.flags]]).
|
|
|
|
| 851 |
``` cpp
|
| 852 |
streamsize readsome(char_type* s, streamsize n);
|
| 853 |
```
|
| 854 |
|
| 855 |
*Effects:* Behaves as an unformatted input function (as described
|
| 856 |
+
above). After constructing a `sentry` object, if `!good()` calls
|
| 857 |
`setstate(failbit)` which may throw an exception, and return. Otherwise
|
| 858 |
extracts characters and stores them into successive locations of an
|
| 859 |
array whose first element is designated by `s`. If
|
| 860 |
`rdbuf()->in_avail() == -1`, calls `setstate(eofbit)` (which may throw
|
| 861 |
`ios_base::failure` [[iostate.flags]]), and extracts no characters;
|
|
|
|
| 864 |
- If `rdbuf()->in_avail() > 0`, extracts `min(rdbuf()->in_avail(), n))`.
|
| 865 |
|
| 866 |
*Returns:* The number of characters extracted.
|
| 867 |
|
| 868 |
``` cpp
|
| 869 |
+
basic_istream& putback(char_type c);
|
| 870 |
```
|
| 871 |
|
| 872 |
*Effects:* Behaves as an unformatted input function (as described
|
| 873 |
above), except that the function first clears `eofbit`. After
|
| 874 |
+
constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
|
| 875 |
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 876 |
calls `rdbuf()->sputbackc(c)`. If `rdbuf()` is null, or if `sputbackc`
|
| 877 |
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 878 |
`ios_base::failure` [[iostate.flags]]).
|
| 879 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 880 |
[*Note 2*: This function extracts no characters, so the value returned
|
| 881 |
by the next call to `gcount()` is 0. — *end note*]
|
| 882 |
|
| 883 |
*Returns:* `*this`.
|
| 884 |
|
| 885 |
+
``` cpp
|
| 886 |
+
basic_istream& unget();
|
| 887 |
+
```
|
| 888 |
+
|
| 889 |
+
*Effects:* Behaves as an unformatted input function (as described
|
| 890 |
+
above), except that the function first clears `eofbit`. After
|
| 891 |
+
constructing a `sentry` object, if `!good()` calls `setstate(failbit)`
|
| 892 |
+
which may throw an exception, and return. If `rdbuf()` is not null,
|
| 893 |
+
calls `rdbuf()->sungetc()`. If `rdbuf()` is null, or if `sungetc`
|
| 894 |
+
returns `traits::eof()`, calls `setstate(badbit)` (which may throw
|
| 895 |
+
`ios_base::failure` [[iostate.flags]]).
|
| 896 |
+
|
| 897 |
+
[*Note 3*: This function extracts no characters, so the value returned
|
| 898 |
+
by the next call to `gcount()` is 0. — *end note*]
|
| 899 |
+
|
| 900 |
+
*Returns:* `*this`.
|
| 901 |
+
|
| 902 |
``` cpp
|
| 903 |
int sync();
|
| 904 |
```
|
| 905 |
|
| 906 |
*Effects:* Behaves as an unformatted input function (as described
|
| 907 |
above), except that it does not count the number of characters extracted
|
| 908 |
and does not affect the value returned by subsequent calls to
|
| 909 |
+
`gcount()`. After constructing a `sentry` object, if `rdbuf()` is a null
|
| 910 |
pointer, returns `-1`. Otherwise, calls `rdbuf()->pubsync()` and, if
|
| 911 |
that function returns `-1` calls `setstate(badbit)` (which may throw
|
| 912 |
`ios_base::failure` [[iostate.flags]], and returns `-1`. Otherwise,
|
| 913 |
returns zero.
|
| 914 |
|
|
|
|
| 919 |
*Effects:* Behaves as an unformatted input function (as described
|
| 920 |
above), except that it does not count the number of characters extracted
|
| 921 |
and does not affect the value returned by subsequent calls to
|
| 922 |
`gcount()`.
|
| 923 |
|
| 924 |
+
*Returns:* After constructing a `sentry` object, if `fail() != false`,
|
| 925 |
returns `pos_type(-1)` to indicate failure. Otherwise, returns
|
| 926 |
`rdbuf()->pubseekoff(0, cur, in)`.
|
| 927 |
|
| 928 |
``` cpp
|
| 929 |
+
basic_istream& seekg(pos_type pos);
|
| 930 |
```
|
| 931 |
|
| 932 |
*Effects:* Behaves as an unformatted input function (as described
|
| 933 |
above), except that the function first clears `eofbit`, it does not
|
| 934 |
count the number of characters extracted, and it does not affect the
|
| 935 |
value returned by subsequent calls to `gcount()`. After constructing a
|
| 936 |
+
`sentry` object, if `fail() != true`, executes
|
| 937 |
`rdbuf()->pubseekpos(pos, ios_base::in)`. In case of failure, the
|
| 938 |
function calls `setstate(failbit)` (which may throw
|
| 939 |
`ios_base::failure`).
|
| 940 |
|
| 941 |
*Returns:* `*this`.
|
| 942 |
|
| 943 |
``` cpp
|
| 944 |
+
basic_istream& seekg(off_type off, ios_base::seekdir dir);
|
| 945 |
```
|
| 946 |
|
| 947 |
*Effects:* Behaves as an unformatted input function (as described
|
| 948 |
above), except that the function first clears `eofbit`, does not count
|
| 949 |
the number of characters extracted, and does not affect the value
|
| 950 |
+
returned by subsequent calls to `gcount()`. After constructing a
|
| 951 |
+
`sentry` object, if `fail() != true`, executes
|
| 952 |
`rdbuf()->pubseekoff(off, dir, ios_base::in)`. In case of failure, the
|
| 953 |
function calls `setstate(failbit)` (which may throw
|
| 954 |
`ios_base::failure`).
|
| 955 |
|
| 956 |
*Returns:* `*this`.
|
|
|
|
| 966 |
```
|
| 967 |
|
| 968 |
*Effects:* Behaves as an unformatted input
|
| 969 |
function [[istream.unformatted]], except that it does not count the
|
| 970 |
number of characters extracted and does not affect the value returned by
|
| 971 |
+
subsequent calls to `is.gcount()`. After constructing a `sentry` object
|
| 972 |
extracts characters as long as the next available character `c` is
|
| 973 |
whitespace or until there are no more characters in the sequence.
|
| 974 |
Whitespace characters are distinguished with the same criterion as used
|
| 975 |
by `sentry::sentry` [[istream.sentry]]. If `ws` stops extracting
|
| 976 |
characters because there are no more available it sets `eofbit`, but not
|
|
|
|
| 984 |
template<class Istream, class T>
|
| 985 |
Istream&& operator>>(Istream&& is, T&& x);
|
| 986 |
```
|
| 987 |
|
| 988 |
*Constraints:* The expression `is >> std::forward<T>(x)` is well-formed
|
| 989 |
+
when treated as an unevaluated operand [[term.unevaluated.operand]] and
|
| 990 |
+
`Istream` is publicly and unambiguously derived from `ios_base`.
|
| 991 |
|
| 992 |
*Effects:* Equivalent to:
|
| 993 |
|
| 994 |
``` cpp
|
| 995 |
is >> std::forward<T>(x);
|
| 996 |
return std::move(is);
|
| 997 |
```
|
| 998 |
|
| 999 |
#### Class template `basic_iostream` <a id="iostreamclass">[[iostreamclass]]</a>
|
| 1000 |
|
| 1001 |
+
##### General <a id="iostreamclass.general">[[iostreamclass.general]]</a>
|
| 1002 |
+
|
| 1003 |
``` cpp
|
| 1004 |
namespace std {
|
| 1005 |
template<class charT, class traits = char_traits<charT>>
|
| 1006 |
class basic_iostream
|
| 1007 |
: public basic_istream<charT, traits>,
|
|
|
|
| 1022 |
protected:
|
| 1023 |
// [iostream.cons], constructor
|
| 1024 |
basic_iostream(const basic_iostream&) = delete;
|
| 1025 |
basic_iostream(basic_iostream&& rhs);
|
| 1026 |
|
| 1027 |
+
// [iostream.assign], assignment and swap
|
| 1028 |
basic_iostream& operator=(const basic_iostream&) = delete;
|
| 1029 |
basic_iostream& operator=(basic_iostream&& rhs);
|
| 1030 |
void swap(basic_iostream& rhs);
|
| 1031 |
};
|
| 1032 |
}
|
|
|
|
| 1051 |
``` cpp
|
| 1052 |
basic_iostream(basic_iostream&& rhs);
|
| 1053 |
```
|
| 1054 |
|
| 1055 |
*Effects:* Move constructs from the rvalue `rhs` by constructing the
|
| 1056 |
+
`basic_istream` base class with `std::move(rhs)`.
|
| 1057 |
|
| 1058 |
##### Destructor <a id="iostream.dest">[[iostream.dest]]</a>
|
| 1059 |
|
| 1060 |
``` cpp
|
| 1061 |
virtual ~basic_iostream();
|
|
|
|
| 1077 |
|
| 1078 |
*Effects:* Calls `basic_istream<charT, traits>::swap(rhs)`.
|
| 1079 |
|
| 1080 |
### Output streams <a id="output.streams">[[output.streams]]</a>
|
| 1081 |
|
| 1082 |
+
#### General <a id="output.streams.general">[[output.streams.general]]</a>
|
| 1083 |
+
|
| 1084 |
+
The header `<ostream>` defines a class template and several function
|
| 1085 |
+
templates that control output to a stream buffer, along with a function
|
| 1086 |
+
template that inserts into stream rvalues.
|
| 1087 |
|
| 1088 |
#### Class template `basic_ostream` <a id="ostream">[[ostream]]</a>
|
| 1089 |
|
| 1090 |
+
##### General <a id="ostream.general">[[ostream.general]]</a>
|
| 1091 |
+
|
| 1092 |
+
When a function has a parameter type `extended-floating-point-type`, the
|
| 1093 |
+
implementation provides overloads for all cv-unqualified extended
|
| 1094 |
+
floating-point types [[basic.fundamental]].
|
| 1095 |
+
|
| 1096 |
``` cpp
|
| 1097 |
namespace std {
|
| 1098 |
template<class charT, class traits = char_traits<charT>>
|
| 1099 |
class basic_ostream : virtual public basic_ios<charT, traits> {
|
| 1100 |
public:
|
|
|
|
| 1111 |
|
| 1112 |
// [ostream.sentry], prefix/suffix
|
| 1113 |
class sentry;
|
| 1114 |
|
| 1115 |
// [ostream.formatted], formatted output
|
| 1116 |
+
basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&));
|
| 1117 |
+
basic_ostream& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
| 1118 |
+
basic_ostream& operator<<(ios_base& (*pf)(ios_base&));
|
|
|
|
|
|
|
|
|
|
| 1119 |
|
| 1120 |
+
basic_ostream& operator<<(bool n);
|
| 1121 |
+
basic_ostream& operator<<(short n);
|
| 1122 |
+
basic_ostream& operator<<(unsigned short n);
|
| 1123 |
+
basic_ostream& operator<<(int n);
|
| 1124 |
+
basic_ostream& operator<<(unsigned int n);
|
| 1125 |
+
basic_ostream& operator<<(long n);
|
| 1126 |
+
basic_ostream& operator<<(unsigned long n);
|
| 1127 |
+
basic_ostream& operator<<(long long n);
|
| 1128 |
+
basic_ostream& operator<<(unsigned long long n);
|
| 1129 |
+
basic_ostream& operator<<(float f);
|
| 1130 |
+
basic_ostream& operator<<(double f);
|
| 1131 |
+
basic_ostream& operator<<(long double f);
|
| 1132 |
+
basic_ostream& operator<<(extended-floating-point-type f);
|
| 1133 |
|
| 1134 |
+
basic_ostream& operator<<(const void* p);
|
| 1135 |
+
basic_ostream& operator<<(const volatile void* p);
|
| 1136 |
+
basic_ostream& operator<<(nullptr_t);
|
| 1137 |
+
basic_ostream& operator<<(basic_streambuf<char_type, traits>* sb);
|
| 1138 |
|
| 1139 |
// [ostream.unformatted], unformatted output
|
| 1140 |
+
basic_ostream& put(char_type c);
|
| 1141 |
+
basic_ostream& write(const char_type* s, streamsize n);
|
| 1142 |
|
| 1143 |
+
basic_ostream& flush();
|
| 1144 |
|
| 1145 |
// [ostream.seeks], seeks
|
| 1146 |
pos_type tellp();
|
| 1147 |
+
basic_ostream& seekp(pos_type);
|
| 1148 |
+
basic_ostream& seekp(off_type, ios_base::seekdir);
|
| 1149 |
|
| 1150 |
protected:
|
| 1151 |
// [ostream.cons], copy/move constructor
|
| 1152 |
basic_ostream(const basic_ostream&) = delete;
|
| 1153 |
basic_ostream(basic_ostream&& rhs);
|
| 1154 |
|
| 1155 |
+
// [ostream.assign], assignment and swap
|
| 1156 |
basic_ostream& operator=(const basic_ostream&) = delete;
|
| 1157 |
basic_ostream& operator=(basic_ostream&& rhs);
|
| 1158 |
void swap(basic_ostream& rhs);
|
| 1159 |
};
|
| 1160 |
|
|
|
|
| 1290 |
|
| 1291 |
##### Class `basic_ostream::sentry` <a id="ostream.sentry">[[ostream.sentry]]</a>
|
| 1292 |
|
| 1293 |
``` cpp
|
| 1294 |
namespace std {
|
| 1295 |
+
template<class charT, class traits>
|
| 1296 |
class basic_ostream<charT, traits>::sentry {
|
| 1297 |
bool ok_; // exposition only
|
| 1298 |
+
|
| 1299 |
public:
|
| 1300 |
+
explicit sentry(basic_ostream& os);
|
| 1301 |
~sentry();
|
| 1302 |
explicit operator bool() const { return ok_; }
|
| 1303 |
|
| 1304 |
sentry(const sentry&) = delete;
|
| 1305 |
sentry& operator=(const sentry&) = delete;
|
|
|
|
| 1309 |
|
| 1310 |
The class `sentry` defines a class that is responsible for doing
|
| 1311 |
exception safe prefix and suffix operations.
|
| 1312 |
|
| 1313 |
``` cpp
|
| 1314 |
+
explicit sentry(basic_ostream& os);
|
| 1315 |
```
|
| 1316 |
|
| 1317 |
If `os.good()` is nonzero, prepares for formatted or unformatted output.
|
| 1318 |
+
If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
|
| 1319 |
|
| 1320 |
If, after any preparation is completed, `os.good()` is `true`,
|
| 1321 |
`ok_ == true` otherwise, `ok_ == false`. During preparation, the
|
| 1322 |
constructor may call `setstate(failbit)` (which may throw
|
| 1323 |
+
`ios_base::failure` [[iostate.flags]]).[^30]
|
| 1324 |
|
| 1325 |
``` cpp
|
| 1326 |
~sentry();
|
| 1327 |
```
|
| 1328 |
|
|
|
|
| 1348 |
|
| 1349 |
*Returns:* If `fail() != false`, returns `pos_type(-1)` to indicate
|
| 1350 |
failure. Otherwise, returns `rdbuf()->pubseekoff(0, cur, out)`.
|
| 1351 |
|
| 1352 |
``` cpp
|
| 1353 |
+
basic_ostream& seekp(pos_type pos);
|
| 1354 |
```
|
| 1355 |
|
| 1356 |
*Effects:* If `fail() != true`, executes
|
| 1357 |
`rdbuf()->pubseekpos(pos, ios_base::out)`. In case of failure, the
|
| 1358 |
function calls `setstate(failbit)` (which may throw
|
| 1359 |
`ios_base::failure`).
|
| 1360 |
|
| 1361 |
*Returns:* `*this`.
|
| 1362 |
|
| 1363 |
``` cpp
|
| 1364 |
+
basic_ostream& seekp(off_type off, ios_base::seekdir dir);
|
| 1365 |
```
|
| 1366 |
|
| 1367 |
*Effects:* If `fail() != true`, executes
|
| 1368 |
`rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
|
| 1369 |
function calls `setstate(failbit)` (which may throw
|
|
|
|
| 1374 |
#### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
|
| 1375 |
|
| 1376 |
##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
|
| 1377 |
|
| 1378 |
Each formatted output function begins execution by constructing an
|
| 1379 |
+
object of class `sentry`. If that object returns `true` when converted
|
| 1380 |
to a value of type `bool`, the function endeavors to generate the
|
| 1381 |
requested output. If the generation fails, then the formatted output
|
| 1382 |
+
function does `setstate(ios_base::failbit)`, which can throw an
|
| 1383 |
exception. If an exception is thrown during output, then
|
| 1384 |
+
`ios_base::badbit` is set[^31]
|
| 1385 |
+
|
| 1386 |
+
in `*this`’s error state. If `(exceptions()&badbit) != 0` then the
|
| 1387 |
+
exception is rethrown. Whether or not an exception is thrown, the
|
| 1388 |
+
`sentry` object is destroyed before leaving the formatted output
|
| 1389 |
+
function. If no exception is thrown, the result of the formatted output
|
| 1390 |
+
function is `*this`.
|
| 1391 |
|
| 1392 |
The descriptions of the individual formatted output functions describe
|
| 1393 |
how they perform output and do not mention the `sentry` object.
|
| 1394 |
|
| 1395 |
If a formatted output function of a stream `os` determines padding, it
|
|
|
|
| 1402 |
they are placed before the character sequence.
|
| 1403 |
|
| 1404 |
##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
|
| 1405 |
|
| 1406 |
``` cpp
|
| 1407 |
+
basic_ostream& operator<<(bool val);
|
| 1408 |
+
basic_ostream& operator<<(short val);
|
| 1409 |
+
basic_ostream& operator<<(unsigned short val);
|
| 1410 |
+
basic_ostream& operator<<(int val);
|
| 1411 |
+
basic_ostream& operator<<(unsigned int val);
|
| 1412 |
+
basic_ostream& operator<<(long val);
|
| 1413 |
+
basic_ostream& operator<<(unsigned long val);
|
| 1414 |
+
basic_ostream& operator<<(long long val);
|
| 1415 |
+
basic_ostream& operator<<(unsigned long long val);
|
| 1416 |
+
basic_ostream& operator<<(float val);
|
| 1417 |
+
basic_ostream& operator<<(double val);
|
| 1418 |
+
basic_ostream& operator<<(long double val);
|
| 1419 |
+
basic_ostream& operator<<(const void* val);
|
| 1420 |
```
|
| 1421 |
|
| 1422 |
*Effects:* The classes `num_get<>` and `num_put<>` handle
|
| 1423 |
locale-dependent numeric formatting and parsing. These inserter
|
| 1424 |
functions use the imbued `locale` value to perform numeric formatting.
|
|
|
|
| 1489 |
from which to obtain other facets. If `failed` is `true` then does
|
| 1490 |
`setstate(badbit)`, which may throw an exception, and returns.
|
| 1491 |
|
| 1492 |
*Returns:* `*this`.
|
| 1493 |
|
| 1494 |
+
``` cpp
|
| 1495 |
+
basic_ostream& operator<<(const volatile void* p);
|
| 1496 |
+
```
|
| 1497 |
+
|
| 1498 |
+
*Effects:* Equivalent to:
|
| 1499 |
+
`return operator<<(const_cast<const void*>(p));`
|
| 1500 |
+
|
| 1501 |
+
``` cpp
|
| 1502 |
+
basic_ostream& operator<<(extended-floating-point-type val);
|
| 1503 |
+
```
|
| 1504 |
+
|
| 1505 |
+
*Effects:* If the floating-point conversion rank of
|
| 1506 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 1507 |
+
`double`, the formatting conversion occurs as if it performed the
|
| 1508 |
+
following code fragment:
|
| 1509 |
+
|
| 1510 |
+
``` cpp
|
| 1511 |
+
bool failed = use_facet<
|
| 1512 |
+
num_put<charT, ostreambuf_iterator<charT, traits>>
|
| 1513 |
+
>(getloc()).put(*this, *this, fill(),
|
| 1514 |
+
static_cast<double>(val)).failed();
|
| 1515 |
+
```
|
| 1516 |
+
|
| 1517 |
+
Otherwise, if the floating-point conversion rank of
|
| 1518 |
+
*`extended-floating-point-type`* is less than or equal to that of
|
| 1519 |
+
`long double`, the formatting conversion occurs as if it performed the
|
| 1520 |
+
following code fragment:
|
| 1521 |
+
|
| 1522 |
+
``` cpp
|
| 1523 |
+
bool failed = use_facet<
|
| 1524 |
+
num_put<charT, ostreambuf_iterator<charT, traits>>
|
| 1525 |
+
>(getloc()).put(*this, *this, fill(),
|
| 1526 |
+
static_cast<long double>(val)).failed();
|
| 1527 |
+
```
|
| 1528 |
+
|
| 1529 |
+
Otherwise, an invocation of the operator function is conditionally
|
| 1530 |
+
supported with *implementation-defined* semantics.
|
| 1531 |
+
|
| 1532 |
+
If `failed` is `true` then does `setstate(badbit)`, which may throw an
|
| 1533 |
+
exception, and returns.
|
| 1534 |
+
|
| 1535 |
+
*Returns:* `*this`.
|
| 1536 |
+
|
| 1537 |
##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
|
| 1538 |
|
| 1539 |
``` cpp
|
| 1540 |
+
basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&));
|
|
|
|
| 1541 |
```
|
| 1542 |
|
| 1543 |
*Effects:* None. Does not behave as a formatted output function (as
|
| 1544 |
described in [[ostream.formatted.reqmts]]).
|
| 1545 |
|
| 1546 |
+
*Returns:* `pf(*this)`.[^32]
|
| 1547 |
|
| 1548 |
``` cpp
|
| 1549 |
+
basic_ostream& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
|
|
|
|
| 1550 |
```
|
| 1551 |
|
| 1552 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 1553 |
formatted output function (as described
|
| 1554 |
in [[ostream.formatted.reqmts]]).
|
| 1555 |
|
| 1556 |
+
*Returns:* `*this`.[^33]
|
| 1557 |
|
| 1558 |
``` cpp
|
| 1559 |
+
basic_ostream& operator<<(ios_base& (*pf)(ios_base&));
|
| 1560 |
```
|
| 1561 |
|
| 1562 |
*Effects:* Calls `pf(*this)`. This inserter does not behave as a
|
| 1563 |
formatted output function (as described
|
| 1564 |
in [[ostream.formatted.reqmts]]).
|
| 1565 |
|
| 1566 |
*Returns:* `*this`.
|
| 1567 |
|
| 1568 |
``` cpp
|
| 1569 |
+
basic_ostream& operator<<(basic_streambuf<charT, traits>* sb);
|
| 1570 |
```
|
| 1571 |
|
| 1572 |
*Effects:* Behaves as an unformatted output
|
| 1573 |
+
function [[ostream.unformatted]]. After the `sentry` object is
|
| 1574 |
constructed, if `sb` is null calls `setstate(badbit)` (which may throw
|
| 1575 |
`ios_base::failure`).
|
| 1576 |
|
| 1577 |
Gets characters from `sb` and inserts them in `*this`. Characters are
|
| 1578 |
read from `sb` and inserted until any of the following occurs:
|
|
|
|
| 1589 |
exception is rethrown.
|
| 1590 |
|
| 1591 |
*Returns:* `*this`.
|
| 1592 |
|
| 1593 |
``` cpp
|
| 1594 |
+
basic_ostream& operator<<(nullptr_t);
|
| 1595 |
```
|
| 1596 |
|
| 1597 |
*Effects:* Equivalent to:
|
| 1598 |
|
| 1599 |
``` cpp
|
|
|
|
| 1666 |
in [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
|
| 1667 |
`width(0)`.
|
| 1668 |
|
| 1669 |
*Returns:* `out`.
|
| 1670 |
|
| 1671 |
+
##### Print <a id="ostream.formatted.print">[[ostream.formatted.print]]</a>
|
| 1672 |
+
|
| 1673 |
+
``` cpp
|
| 1674 |
+
template<class... Args>
|
| 1675 |
+
void print(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 1676 |
+
```
|
| 1677 |
+
|
| 1678 |
+
*Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
|
| 1679 |
+
equivalent to:
|
| 1680 |
+
|
| 1681 |
+
``` cpp
|
| 1682 |
+
vprint_unicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 1683 |
+
```
|
| 1684 |
+
|
| 1685 |
+
Otherwise, equivalent to:
|
| 1686 |
+
|
| 1687 |
+
``` cpp
|
| 1688 |
+
vprint_nonunicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 1689 |
+
```
|
| 1690 |
+
|
| 1691 |
+
``` cpp
|
| 1692 |
+
template<class... Args>
|
| 1693 |
+
void println(ostream& os, format_string<Args...> fmt, Args&&... args);
|
| 1694 |
+
```
|
| 1695 |
+
|
| 1696 |
+
*Effects:* Equivalent to:
|
| 1697 |
+
|
| 1698 |
+
``` cpp
|
| 1699 |
+
print(os, "{}\n", format(fmt, std::forward<Args>(args)...));
|
| 1700 |
+
```
|
| 1701 |
+
|
| 1702 |
+
``` cpp
|
| 1703 |
+
void vprint_unicode(ostream& os, string_view fmt, format_args args);
|
| 1704 |
+
void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
|
| 1705 |
+
```
|
| 1706 |
+
|
| 1707 |
+
*Effects:* Behaves as a formatted output
|
| 1708 |
+
function [[ostream.formatted.reqmts]] of `os`, except that:
|
| 1709 |
+
|
| 1710 |
+
- failure to generate output is reported as specified below, and
|
| 1711 |
+
- any exception thrown by the call to `vformat` is propagated without
|
| 1712 |
+
regard to the value of `os.exceptions()` and without turning on
|
| 1713 |
+
`ios_base::badbit` in the error state of `os`.
|
| 1714 |
+
|
| 1715 |
+
After constructing a `sentry` object, the function initializes an
|
| 1716 |
+
automatic variable via
|
| 1717 |
+
|
| 1718 |
+
``` cpp
|
| 1719 |
+
string out = vformat(os.getloc(), fmt, args);
|
| 1720 |
+
```
|
| 1721 |
+
|
| 1722 |
+
If the function is `vprint_unicode` and `os` is a stream that refers to
|
| 1723 |
+
a terminal capable of displaying Unicode which is determined in an
|
| 1724 |
+
implementation-defined manner, writes `out` to the terminal using the
|
| 1725 |
+
native Unicode API; if `out` contains invalid code units, the behavior
|
| 1726 |
+
is undefined and implementations are encouraged to diagnose it. If the
|
| 1727 |
+
native Unicode API is used, the function flushes `os` before writing
|
| 1728 |
+
`out`. Otherwise (if `os` is not such a stream or the function is
|
| 1729 |
+
`vprint_nonunicode`), inserts the character sequence \[`out.begin()`,
|
| 1730 |
+
`out.end()`) into `os`. If writing to the terminal or inserting into
|
| 1731 |
+
`os` fails, calls `os.setstate(ios_base::badbit)` (which may throw
|
| 1732 |
+
`ios_base::failure`).
|
| 1733 |
+
|
| 1734 |
+
*Recommended practice:* For `vprint_unicode`, if invoking the native
|
| 1735 |
+
Unicode API requires transcoding, implementations should substitute
|
| 1736 |
+
invalid code units with U+fffd (replacement character) per the Unicode
|
| 1737 |
+
Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
|
| 1738 |
+
|
| 1739 |
#### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
|
| 1740 |
|
| 1741 |
Each unformatted output function begins execution by constructing an
|
| 1742 |
+
object of class `sentry`. If that object returns `true`, while
|
| 1743 |
converting to a value of type `bool`, the function endeavors to generate
|
| 1744 |
the requested output. If an exception is thrown during output, then
|
| 1745 |
+
`ios_base::badbit` is set[^34]
|
| 1746 |
+
|
| 1747 |
+
in `*this`’s error state. If `(exceptions() & badbit) != 0` then the
|
| 1748 |
+
exception is rethrown. In any case, the unformatted output function ends
|
| 1749 |
+
by destroying the `sentry` object, then, if no exception was thrown,
|
| 1750 |
+
returning the value specified for the unformatted output function.
|
| 1751 |
|
| 1752 |
``` cpp
|
| 1753 |
+
basic_ostream& put(char_type c);
|
| 1754 |
```
|
| 1755 |
|
| 1756 |
*Effects:* Behaves as an unformatted output function (as described
|
| 1757 |
+
above). After constructing a `sentry` object, inserts the character `c`,
|
| 1758 |
+
if possible.[^35]
|
| 1759 |
|
| 1760 |
Otherwise, calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 1761 |
[[iostate.flags]]).
|
| 1762 |
|
| 1763 |
*Returns:* `*this`.
|
|
|
|
| 1765 |
``` cpp
|
| 1766 |
basic_ostream& write(const char_type* s, streamsize n);
|
| 1767 |
```
|
| 1768 |
|
| 1769 |
*Effects:* Behaves as an unformatted output function (as described
|
| 1770 |
+
above). After constructing a `sentry` object, obtains characters to
|
| 1771 |
+
insert from successive locations of an array whose first element is
|
| 1772 |
+
designated by `s`.[^36]
|
| 1773 |
+
|
| 1774 |
+
Characters are inserted until either of the following occurs:
|
| 1775 |
|
| 1776 |
- `n` characters are inserted;
|
| 1777 |
- inserting in the output sequence fails (in which case the function
|
| 1778 |
calls `setstate(badbit)`, which may throw `ios_base::failure`
|
| 1779 |
[[iostate.flags]]).
|
|
|
|
| 1783 |
``` cpp
|
| 1784 |
basic_ostream& flush();
|
| 1785 |
```
|
| 1786 |
|
| 1787 |
*Effects:* Behaves as an unformatted output function (as described
|
| 1788 |
+
above). If `rdbuf()` is not a null pointer, constructs a `sentry`
|
| 1789 |
+
object. If that object returns `true` when converted to a value of type
|
| 1790 |
+
`bool` the function calls `rdbuf()->pubsync()`. If that function returns
|
| 1791 |
+
-1 calls `setstate(badbit)` (which may throw `ios_base::failure`
|
| 1792 |
+
[[iostate.flags]]). Otherwise, if the `sentry` object returns `false`,
|
| 1793 |
does nothing.
|
| 1794 |
|
| 1795 |
*Returns:* `*this`.
|
| 1796 |
|
| 1797 |
#### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
|
|
|
|
| 1861 |
basic_ostream<charT, traits>& flush_emit(basic_ostream<charT, traits>& os);
|
| 1862 |
```
|
| 1863 |
|
| 1864 |
*Effects:* Calls `os.flush()`. Then, if `os.rdbuf()` is a
|
| 1865 |
`basic_syncbuf<charT, traits, Allocator>*`, called `buf` for the purpose
|
| 1866 |
+
of exposition, behaves as an unformatted output
|
| 1867 |
+
function [[ostream.unformatted]] of `os`. After constructing a `sentry`
|
| 1868 |
+
object, calls `buf->emit()`. If that call returns `false`, calls
|
| 1869 |
+
`os.setstate(ios_base::badbit)`.
|
| 1870 |
|
| 1871 |
*Returns:* `os`.
|
| 1872 |
|
| 1873 |
#### Rvalue stream insertion <a id="ostream.rvalue">[[ostream.rvalue]]</a>
|
| 1874 |
|
|
|
|
| 1898 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 1899 |
of type `basic_ostream<charT, traits>` then the expression
|
| 1900 |
`out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
|
| 1901 |
if `in` is an object of type `basic_istream<charT, traits>` then the
|
| 1902 |
expression `in >> resetiosflags(mask)` behaves as if it called
|
| 1903 |
+
`f(in, mask)`, where the function `f` is defined as:[^37]
|
| 1904 |
|
| 1905 |
``` cpp
|
| 1906 |
void f(ios_base& str, ios_base::fmtflags mask) {
|
| 1907 |
// reset specified flags
|
| 1908 |
str.setf(ios_base::fmtflags(0), mask);
|
|
|
|
| 2097 |
|
| 2098 |
The expression `out << put_money(mon, intl)` has type
|
| 2099 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 2100 |
|
| 2101 |
``` cpp
|
| 2102 |
+
template<class charT> unspecified get_time(tm* tmb, const charT* fmt);
|
| 2103 |
```
|
| 2104 |
|
| 2105 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 2106 |
+
type `tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`) is a
|
| 2107 |
+
valid range.
|
| 2108 |
|
| 2109 |
*Returns:* An object of unspecified type such that if `in` is an object
|
| 2110 |
of type `basic_istream<charT, traits>` then the expression
|
| 2111 |
`in >> get_time(tmb, fmt)` behaves as if it called `f(in, tmb, fmt)`,
|
| 2112 |
where the function `f` is defined as:
|
| 2113 |
|
| 2114 |
``` cpp
|
| 2115 |
template<class charT, class traits>
|
| 2116 |
+
void f(basic_ios<charT, traits>& str, tm* tmb, const charT* fmt) {
|
| 2117 |
using Iter = istreambuf_iterator<charT, traits>;
|
| 2118 |
using TimeGet = time_get<charT, Iter>;
|
| 2119 |
|
| 2120 |
ios_base::iostate err = ios_base::goodbit;
|
| 2121 |
const TimeGet& tg = use_facet<TimeGet>(str.getloc());
|
|
|
|
| 2130 |
|
| 2131 |
The expression `in >> get_time(tmb, fmt)` has type
|
| 2132 |
`basic_istream<charT, traits>&` and value `in`.
|
| 2133 |
|
| 2134 |
``` cpp
|
| 2135 |
+
template<class charT> unspecified put_time(const tm* tmb, const charT* fmt);
|
| 2136 |
```
|
| 2137 |
|
| 2138 |
*Preconditions:* The argument `tmb` is a valid pointer to an object of
|
| 2139 |
+
type `tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`) is a
|
| 2140 |
+
valid range.
|
| 2141 |
|
| 2142 |
*Returns:* An object of unspecified type such that if `out` is an object
|
| 2143 |
of type `basic_ostream<charT, traits>` then the expression
|
| 2144 |
`out << put_time(tmb, fmt)` behaves as if it called `f(out, tmb, fmt)`,
|
| 2145 |
where the function `f` is defined as:
|
| 2146 |
|
| 2147 |
``` cpp
|
| 2148 |
template<class charT, class traits>
|
| 2149 |
+
void f(basic_ios<charT, traits>& str, const tm* tmb, const charT* fmt) {
|
| 2150 |
using Iter = ostreambuf_iterator<charT, traits>;
|
| 2151 |
using TimePut = time_put<charT, Iter>;
|
| 2152 |
|
| 2153 |
const TimePut& tp = use_facet<TimePut>(str.getloc());
|
| 2154 |
const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
|
|
|
|
| 2237 |
- The expression `in >> quoted(s, delim, escape)` has type
|
| 2238 |
`basic_istream<charT, traits>&` and value `in`.
|
| 2239 |
- The expression `out << quoted(s, delim, escape)` has type
|
| 2240 |
`basic_ostream<charT, traits>&` and value `out`.
|
| 2241 |
|
| 2242 |
+
### Print functions <a id="print.fun">[[print.fun]]</a>
|
| 2243 |
+
|
| 2244 |
+
``` cpp
|
| 2245 |
+
template<class... Args>
|
| 2246 |
+
void print(format_string<Args...> fmt, Args&&... args);
|
| 2247 |
+
```
|
| 2248 |
+
|
| 2249 |
+
*Effects:* Equivalent to:
|
| 2250 |
+
|
| 2251 |
+
``` cpp
|
| 2252 |
+
print(stdout, fmt, std::forward<Args>(args)...);
|
| 2253 |
+
```
|
| 2254 |
+
|
| 2255 |
+
``` cpp
|
| 2256 |
+
template<class... Args>
|
| 2257 |
+
void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 2258 |
+
```
|
| 2259 |
+
|
| 2260 |
+
*Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
|
| 2261 |
+
equivalent to:
|
| 2262 |
+
|
| 2263 |
+
``` cpp
|
| 2264 |
+
vprint_unicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 2265 |
+
```
|
| 2266 |
+
|
| 2267 |
+
Otherwise, equivalent to:
|
| 2268 |
+
|
| 2269 |
+
``` cpp
|
| 2270 |
+
vprint_nonunicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
|
| 2271 |
+
```
|
| 2272 |
+
|
| 2273 |
+
``` cpp
|
| 2274 |
+
template<class... Args>
|
| 2275 |
+
void println(format_string<Args...> fmt, Args&&... args);
|
| 2276 |
+
```
|
| 2277 |
+
|
| 2278 |
+
*Effects:* Equivalent to:
|
| 2279 |
+
|
| 2280 |
+
``` cpp
|
| 2281 |
+
println(stdout, fmt, std::forward<Args>(args)...);
|
| 2282 |
+
```
|
| 2283 |
+
|
| 2284 |
+
``` cpp
|
| 2285 |
+
template<class... Args>
|
| 2286 |
+
void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
|
| 2287 |
+
```
|
| 2288 |
+
|
| 2289 |
+
*Effects:* Equivalent to:
|
| 2290 |
+
|
| 2291 |
+
``` cpp
|
| 2292 |
+
print(stream, "{}\n", format(fmt, std::forward<Args>(args)...));
|
| 2293 |
+
```
|
| 2294 |
+
|
| 2295 |
+
``` cpp
|
| 2296 |
+
void vprint_unicode(string_view fmt, format_args args);
|
| 2297 |
+
```
|
| 2298 |
+
|
| 2299 |
+
*Effects:* Equivalent to:
|
| 2300 |
+
|
| 2301 |
+
``` cpp
|
| 2302 |
+
vprint_unicode(stdout, fmt, args);
|
| 2303 |
+
```
|
| 2304 |
+
|
| 2305 |
+
``` cpp
|
| 2306 |
+
void vprint_unicode(FILE* stream, string_view fmt, format_args args);
|
| 2307 |
+
```
|
| 2308 |
+
|
| 2309 |
+
*Preconditions:* `stream` is a valid pointer to an output C stream.
|
| 2310 |
+
|
| 2311 |
+
*Effects:* The function initializes an automatic variable via
|
| 2312 |
+
|
| 2313 |
+
``` cpp
|
| 2314 |
+
string out = vformat(fmt, args);
|
| 2315 |
+
```
|
| 2316 |
+
|
| 2317 |
+
If `stream` refers to a terminal capable of displaying Unicode, writes
|
| 2318 |
+
`out` to the terminal using the native Unicode API; if `out` contains
|
| 2319 |
+
invalid code units, the behavior is undefined and implementations are
|
| 2320 |
+
encouraged to diagnose it. Otherwise writes `out` to `stream` unchanged.
|
| 2321 |
+
If the native Unicode API is used, the function flushes `stream` before
|
| 2322 |
+
writing `out`.
|
| 2323 |
+
|
| 2324 |
+
[*Note 1*: On POSIX and Windows, `stream` referring to a terminal means
|
| 2325 |
+
that, respectively, `isatty(fileno(stream))` and
|
| 2326 |
+
`GetConsoleMode(_get_osfhandle(_fileno(stream)), ...)` return
|
| 2327 |
+
nonzero. — *end note*]
|
| 2328 |
+
|
| 2329 |
+
[*Note 2*: On Windows, the native Unicode API is
|
| 2330 |
+
`WriteConsoleW`. — *end note*]
|
| 2331 |
+
|
| 2332 |
+
*Throws:* Any exception thrown by the call to `vformat`
|
| 2333 |
+
[[format.err.report]]. `system_error` if writing to the terminal or
|
| 2334 |
+
`stream` fails. May throw `bad_alloc`.
|
| 2335 |
+
|
| 2336 |
+
*Recommended practice:* If invoking the native Unicode API requires
|
| 2337 |
+
transcoding, implementations should substitute invalid code units with
|
| 2338 |
+
U+fffd (replacement character) per the Unicode Standard, Chapter 3.9
|
| 2339 |
+
‘U+fffd‘ Substitution in Conversion.
|
| 2340 |
+
|
| 2341 |
+
``` cpp
|
| 2342 |
+
void vprint_nonunicode(string_view fmt, format_args args);
|
| 2343 |
+
```
|
| 2344 |
+
|
| 2345 |
+
*Effects:* Equivalent to:
|
| 2346 |
+
|
| 2347 |
+
``` cpp
|
| 2348 |
+
vprint_nonunicode(stdout, fmt, args);
|
| 2349 |
+
```
|
| 2350 |
+
|
| 2351 |
+
``` cpp
|
| 2352 |
+
void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
|
| 2353 |
+
```
|
| 2354 |
+
|
| 2355 |
+
*Preconditions:* `stream` is a valid pointer to an output C stream.
|
| 2356 |
+
|
| 2357 |
+
*Effects:* Writes the result of `vformat(fmt, args)` to `stream`.
|
| 2358 |
+
|
| 2359 |
+
*Throws:* Any exception thrown by the call to `vformat`
|
| 2360 |
+
[[format.err.report]]. `system_error` if writing to `stream` fails. May
|
| 2361 |
+
throw `bad_alloc`.
|
| 2362 |
+
|