From Jason Turner

[iostream.format]

C++11 → C++14 25.1 KB 234 lines
Current Draft | LaTeX Source
Archived: C++11 | C++14
Markdown: C++11 | C++14
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp2yajlht5/{from.md → to.md} +149 -54
tmp/tmp2yajlht5/{from.md → to.md} RENAMED
@@ -56,10 +56,21 @@ namespace std {
56
  T6 setw(int n);
57
  template <class moneyT> T7 get_money(moneyT& mon, bool intl = false);
58
  template <class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
59
  template <class charT> T9 get_time(struct tm* tmb, const charT* fmt);
60
  template <class charT> T10 put_time(const struct tm* tmb, const charT* fmt);
 
 
 
 
 
 
 
 
 
 
 
61
  }
62
  ```
63
 
64
  ### Input streams <a id="input.streams">[[input.streams]]</a>
65
 
@@ -248,11 +259,11 @@ values returned by `gcount()` and `rhs.gcount()`.
248
  ``` cpp
249
  namespace std {
250
  template <class charT,class traits = char_traits<charT> >
251
  class basic_istream<charT,traits>::sentry {
252
  typedef traits traits_type;
253
- bool ok_; // exposition onlyr
254
  public:
255
  explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false);
256
  ~sentry();
257
  explicit operator bool() const { return ok_; }
258
  sentry(const sentry&) = delete;
@@ -266,19 +277,19 @@ exception safe prefix and suffix operations.
266
 
267
  ``` cpp
268
  explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false);
269
  ```
270
 
271
- *Effects:* If `is.good()` is `false`, calls is.setstate(failbit).
272
  Otherwise, prepares for formatted or unformatted input. First, if
273
  `is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
274
  to synchronize the output sequence with any associated external C
275
  stream. Except that this call can be suppressed if the put area of
276
  `is.tie()` is empty. Further an implementation is allowed to defer the
277
  call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
278
  such call occurs before the `sentry` object is destroyed, the call to
279
- `flush` may be eliminated entirely.[^16] If `noskipws` is zero and
280
  `is.flags() & ios_base::skipws` is nonzero, the function extracts and
281
  discards each character as long as the next available input character
282
  `c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
283
  `is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
284
  `setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
@@ -298,11 +309,11 @@ if (ctype.is(ctype.space,c)!=0)
298
  ```
299
 
300
  If, after any preparation is completed, `is.good()` is `true`,
301
  `ok_ != false` otherwise, `ok_ == false`. During preparation, the
302
  constructor may call `setstate(failbit)` (which may throw
303
- `ios_base::failure` ([[iostate.flags]]))[^17]
304
 
305
  ``` cpp
306
  ~sentry();
307
  ```
308
 
@@ -320,11 +331,11 @@ explicit operator bool() const;
320
 
321
  Each formatted input function begins execution by constructing an object
322
  of class `sentry` with the `noskipws` (second) argument `false`. If the
323
  `sentry` object returns `true`, when converted to a value of type
324
  `bool`, the function endeavors to obtain the requested input. If an
325
- exception is thrown during input then `ios::badbit` is turned on[^18] in
326
  `*this`’s error state. If `(exceptions()&badbit) != 0` then the
327
  exception is rethrown. In any case, the formatted input function
328
  destroys the `sentry` object. If no exception has been thrown, it
329
  returns `*this`.
330
 
@@ -413,17 +424,17 @@ setstate(err);
413
 
414
  ##### `basic_istream::operator>>` <a id="istream::extractors">[[istream::extractors]]</a>
415
 
416
  ``` cpp
417
  basic_istream<charT,traits>& operator>>
418
- (basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&))
419
  ```
420
 
421
  *Effects:* None. This extractor does not behave as a formatted input
422
  function (as described in  [[istream.formatted.reqmts]].)
423
 
424
- *Returns:* `pf(*this)`.[^19]
425
 
426
  ``` cpp
427
  basic_istream<charT,traits>& operator>>
428
  (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
429
  ```
@@ -437,11 +448,11 @@ in  [[istream.formatted.reqmts]]).
437
  ``` cpp
438
  basic_istream<charT,traits>& operator>>
439
  (ios_base& (*pf)(ios_base&));
440
  ```
441
 
442
- *Effects:* Calls `pf(*this)`.[^20] This extractor does not behave as a
443
  formatted input function (as described
444
  in  [[istream.formatted.reqmts]]).
445
 
446
  *Returns:* `*this`.
447
 
@@ -539,11 +550,11 @@ an exception or if the sentry object returns false, when converted to a
539
  value of type `bool`, the function returns without attempting to obtain
540
  any input. In either case the number of extracted characters is set to
541
  0; unformatted input functions taking a character array of non-zero size
542
  as an argument shall also store a null character (using `charT()`) in
543
  the first location of the array. If an exception is thrown during input
544
- then `ios::badbit` is turned on[^21] in `*this`’s error state.
545
  (Exceptions thrown from `basic_ios<>::clear()` are not caught or
546
  rethrown.) If `(exceptions()&badbit) != 0` then the exception is
547
  rethrown. It also counts the number of characters extracted. If no
548
  exception has been thrown it ends by storing the count in a member
549
  object and returning the value specified. In any event the `sentry`
@@ -576,11 +587,11 @@ basic_istream<charT,traits>& get(char_type& c);
576
  ```
577
 
578
  *Effects:* Behaves as an unformatted input function (as described
579
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
580
  object, extracts a character, if one is available, and assigns it to
581
- `c`.[^22] Otherwise, the function calls `setstate(failbit)` (which may
582
  throw `ios_base::failure` ([[iostate.flags]])).
583
 
584
  *Returns:* `*this`.
585
 
586
  ``` cpp
@@ -589,11 +600,11 @@ basic_istream<charT,traits>& get(char_type* s, streamsize n,
589
  ```
590
 
591
  *Effects:* Behaves as an unformatted input function (as described
592
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
593
  object, extracts characters and stores them into successive locations of
594
- an array whose first element is designated by `s`.[^23] Characters are
595
  extracted and stored until any of the following occurs:
596
 
597
  - `n` is less than one or `n - 1` characters are stored;
598
  - end-of-file occurs on the input sequence (in which case the function
599
  calls `setstate(eofbit)`);
@@ -606,11 +617,11 @@ if `n` is greater than zero it then stores a null character into the
606
  next successive location of the array.
607
 
608
  *Returns:* `*this`.
609
 
610
  ``` cpp
611
- basic_istream<charT,traits>& get(char_type* s, streamsize n)
612
  ```
613
 
614
  *Effects:* Calls `get(s,n,widen(’\n’))`
615
 
616
  *Returns:* Value returned by the call.
@@ -653,25 +664,25 @@ basic_istream<charT,traits>& getline(char_type* s, streamsize n,
653
  ```
654
 
655
  *Effects:* Behaves as an unformatted input function (as described
656
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
657
  object, extracts characters and stores them into successive locations of
658
- an array whose first element is designated by `s`.[^24] Characters are
659
  extracted and stored until one of the following occurs:
660
 
661
  1. end-of-file occurs on the input sequence (in which case the function
662
  calls `setstate(eofbit)`);
663
  2. `traits::eq(c, delim)` for the next available input character `c`
664
  (in which case the input character is extracted but not
665
- stored);[^25]
666
  3. `n` is less than one or `n - 1` characters are stored (in which case
667
  the function calls `setstate(failbit)`).
668
 
669
- These conditions are tested in the order shown.[^26]
670
 
671
  If the function extracts no characters, it calls `setstate(failbit)`
672
- (which may throw `ios_base::failure` ([[iostate.flags]])).[^27]
673
 
674
  In any case, if `n` is greater than zero, it then stores a null
675
  character (using `charT()`) into the next successive location of the
676
  array.
677
 
@@ -716,12 +727,12 @@ basic_istream<charT,traits>&
716
  *Effects:* Behaves as an unformatted input function (as described
717
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
718
  object, extracts characters and discards them. Characters are extracted
719
  until any of the following occurs:
720
 
721
- - if `n != numeric_limits<streamsize>::max()` ([[limits]]), `n`
722
- characters are extracted
723
  - end-of-file occurs on the input sequence (in which case the function
724
  calls `setstate(eofbit)`, which may throw
725
  `ios_base::failure` ([[iostate.flags]]));
726
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
727
  available input character `c` (in which case `c` is extracted).
@@ -749,11 +760,11 @@ basic_istream<charT,traits>& read(char_type* s, streamsize n);
749
  *Effects:* Behaves as an unformatted input function (as described
750
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
751
  object, if `!good()` calls `setstate(failbit)` which may throw an
752
  exception, and return. Otherwise extracts characters and stores them
753
  into successive locations of an array whose first element is designated
754
- by `s`.[^28] Characters are extracted and stored until either of the
755
  following occurs:
756
 
757
  - `n` characters are stored;
758
  - end-of-file occurs on the input sequence (in which case the function
759
  calls `setstate(failbit | eofbit)`, which may throw
@@ -1047,12 +1058,12 @@ namespace std {
1047
  protected:
1048
  basic_ostream(const basic_ostream& rhs) = delete;
1049
  basic_ostream(basic_ostream&& rhs);
1050
 
1051
  // [ostream.assign] Assign/swap
1052
- basic_ostream& operator=(basic_ostream& rhs) = delete;
1053
- basic_ostream& operator=(const basic_ostream&& rhs);
1054
  void swap(basic_ostream& rhs);
1055
  };
1056
 
1057
  // [ostream.inserters.character] character inserters
1058
  template<class charT, class traits>
@@ -1149,11 +1160,11 @@ void swap(basic_ostream& rhs);
1149
 
1150
  ``` cpp
1151
  namespace std {
1152
  template <class charT,class traits = char_traits<charT> >
1153
  class basic_ostream<charT,traits>::sentry {
1154
- bool ok_; // exposition onlyr
1155
  public:
1156
  explicit sentry(basic_ostream<charT,traits>& os);
1157
  ~sentry();
1158
  explicit operator bool() const { return ok_; }
1159
 
@@ -1169,16 +1180,16 @@ exception safe prefix and suffix operations.
1169
  ``` cpp
1170
  explicit sentry(basic_ostream<charT,traits>& os);
1171
  ```
1172
 
1173
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
1174
- If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
1175
 
1176
  If, after any preparation is completed, `os.good()` is `true`,
1177
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
1178
  constructor may call `setstate(failbit)` (which may throw
1179
- `ios_base::failure` ([[iostate.flags]]))[^30]
1180
 
1181
  ``` cpp
1182
  ~sentry();
1183
  ```
1184
 
@@ -1209,11 +1220,13 @@ basic_ostream<charT,traits>& seekp(pos_type pos);
1209
  ``` cpp
1210
  basic_ostream<charT,traits>& seekp(off_type off, ios_base::seekdir dir);
1211
  ```
1212
 
1213
  *Effects:* If `fail() != true`, executes
1214
- `rdbuf()->pubseekoff(off, dir, ios_base::out)`.
 
 
1215
 
1216
  *Returns:* `*this`.
1217
 
1218
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
1219
 
@@ -1223,19 +1236,28 @@ Each formatted output function begins execution by constructing an
1223
  object of class `sentry`. If this object returns `true` when converted
1224
  to a value of type `bool`, the function endeavors to generate the
1225
  requested output. If the generation fails, then the formatted output
1226
  function does `setstate(ios_base::failbit)`, which might throw an
1227
  exception. If an exception is thrown during output, then `ios::badbit`
1228
- is turned on[^31] in `*this`’s error state. If
1229
  `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
1230
  not an exception is thrown, the `sentry` object is destroyed before
1231
  leaving the formatted output function. If no exception is thrown, the
1232
  result of the formatted output function is `*this`.
1233
 
1234
- The descriptions of the individual formatted output operations describe
1235
  how they perform output and do not mention the `sentry` object.
1236
 
 
 
 
 
 
 
 
 
 
1237
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
1238
 
1239
  ``` cpp
1240
  operator<<(bool val);
1241
  operator<<(short val);
@@ -1307,11 +1329,11 @@ performed the following code fragment:
1307
 
1308
  ``` cpp
1309
  bool failed = use_facet<
1310
  num_put<charT,ostreambuf_iterator<charT,traits> >
1311
  >(getloc()).put(*this, *this, fill(),
1312
- static_cast<double>(va})).failed();
1313
  ```
1314
 
1315
  The first argument provides an object of the `ostreambuf_iterator<>`
1316
  class which is an iterator for class `basic_ostream<>`. It bypasses
1317
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
@@ -1326,32 +1348,32 @@ from which to obtain other facets. If `failed` is `true` then does
1326
 
1327
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
1328
 
1329
  ``` cpp
1330
  basic_ostream<charT,traits>& operator<<
1331
- (basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&))
1332
  ```
1333
 
1334
  *Effects:* None. Does not behave as a formatted output function (as
1335
  described in  [[ostream.formatted.reqmts]]).
1336
 
1337
- *Returns:* `pf(*this)`.[^32]
1338
 
1339
  ``` cpp
1340
  basic_ostream<charT,traits>& operator<<
1341
- (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&))
1342
  ```
1343
 
1344
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
1345
  formatted output function (as described
1346
  in  [[ostream.formatted.reqmts]]).
1347
 
1348
- *Returns:* `*this`.[^33]
1349
 
1350
  ``` cpp
1351
  basic_ostream<charT,traits>& operator<<
1352
- (ios_base& (*pf)(ios_base&))
1353
  ```
1354
 
1355
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
1356
  formatted output function (as described
1357
  in  [[ostream.formatted.reqmts]]).
@@ -1387,11 +1409,11 @@ caught exception is rethrown.
1387
  ##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
1388
 
1389
  ``` cpp
1390
  template<class charT, class traits>
1391
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
1392
- charT c};
1393
  template<class charT, class traits>
1394
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
1395
  char c);
1396
  // specialization
1397
  template<class traits>
@@ -1404,18 +1426,17 @@ template<class traits>
1404
  template<class traits>
1405
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
1406
  unsigned char c);
1407
  ```
1408
 
1409
- *Effects:* Behaves like a formatted inserter (as described
1410
- in  [[ostream.formatted.reqmts]]) of `out`. After a `sentry` object is
1411
- constructed it inserts characters. In case `c` has type `char` and the
1412
- character type of the stream is not `char`, then the character to be
1413
- inserted is `out.widen(c)`; otherwise the character is `c`. Padding is
1414
- determined as described in  [[facet.num.put.virtuals]]. `width(0)` is
1415
- called. The insertion character and any required padding are inserted
1416
- into `out`.
1417
 
1418
  *Returns:* `out`.
1419
 
1420
  ``` cpp
1421
  template<class charT, class traits>
@@ -1436,13 +1457,14 @@ template<class traits>
1436
  ```
1437
 
1438
  *Requires:* `s` shall not be a null pointer.
1439
 
1440
  *Effects:* Behaves like a formatted inserter (as described
1441
- in  [[ostream.formatted.reqmts]]) of `out`. After a `sentry` object is
1442
- constructed it inserts `n` characters starting at `s`, where `n` is the
1443
- number that would be computed as if by:
 
1444
 
1445
  - `traits::length(s)` for the overload where the first argument is of
1446
  type `basic_ostream<charT, traits>&` and the second is of type
1447
  `const charT*`, and also for the overload where the first argument is
1448
  of type `basic_ostream<char, traits>&` and the second is of type
@@ -1451,24 +1473,23 @@ number that would be computed as if by:
1451
  argument is of type `basic_ostream<charT, traits>&` and the second is
1452
  of type `const char*`,
1453
  - `traits::length(reinterpret_cast<const char*>(s))` for the other two
1454
  overloads.
1455
 
1456
- Padding is determined as described in  [[facet.num.put.virtuals]]. The
1457
- `n` characters starting at `s` are widened using
1458
- `out.widen` ([[basic.ios.members]]). The widened characters and any
1459
- required padding are inserted into `out`. Calls `width(0)`.
1460
 
1461
  *Returns:* `out`.
1462
 
1463
  #### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
1464
 
1465
  Each unformatted output function begins execution by constructing an
1466
  object of class `sentry`. If this object returns `true`, while
1467
  converting to a value of type `bool`, the function endeavors to generate
1468
  the requested output. If an exception is thrown during output, then
1469
- `ios::badbit` is turned on[^34] in `*this`’s error state. If
1470
  `(exceptions() & badbit) != 0` then the exception is rethrown. In any
1471
  case, the unformatted output function ends by destroying the sentry
1472
  object, then, if no exception was thrown, returning the value specified
1473
  for the unformatted output function.
1474
 
@@ -1476,11 +1497,11 @@ for the unformatted output function.
1476
  basic_ostream<charT,traits>& put(char_type c);
1477
  ```
1478
 
1479
  *Effects:* Behaves as an unformatted output function (as described
1480
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
1481
- object, inserts the character `c`, if possible.[^35]
1482
 
1483
  Otherwise, calls `setstate(badbit)` (which may throw
1484
  `ios_base::failure` ([[iostate.flags]])).
1485
 
1486
  *Returns:* `*this`.
@@ -1490,11 +1511,11 @@ basic_ostream& write(const char_type* s, streamsize n);
1490
  ```
1491
 
1492
  *Effects:* Behaves as an unformatted output function (as described
1493
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
1494
  object, obtains characters to insert from successive locations of an
1495
- array whose first element is designated by `s`.[^36] Characters are
1496
  inserted until either of the following occurs:
1497
 
1498
  - `n` characters are inserted;
1499
  - inserting in the output sequence fails (in which case the function
1500
  calls `setstate(badbit)`, which may throw
@@ -1578,11 +1599,11 @@ unspecified resetiosflags(ios_base::fmtflags mask);
1578
  *Returns:* An object of unspecified type such that if `out` is an object
1579
  of type `basic_ostream<charT, traits>` then the expression
1580
  `out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
1581
  if `in` is an object of type `basic_istream<charT, traits>` then the
1582
  expression `in >> resetiosflags(mask)` behaves as if it called
1583
- `f(in, mask)`, where the function `f` is defined as:[^37]
1584
 
1585
  ``` cpp
1586
  void f(ios_base& str, ios_base::fmtflags mask) {
1587
  // reset specified flags
1588
  str.setf(ios_base::fmtflags(0), mask);
@@ -1840,7 +1861,81 @@ void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
1840
  str.setstate(ios_base::badbit);
1841
  }
1842
  ```
1843
 
1844
  The expression `out << put_time(tmb, fmt)` shall have type
1845
- `basic_istream<charT, traits>&` and value `out`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1846
 
 
56
  T6 setw(int n);
57
  template <class moneyT> T7 get_money(moneyT& mon, bool intl = false);
58
  template <class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
59
  template <class charT> T9 get_time(struct tm* tmb, const charT* fmt);
60
  template <class charT> T10 put_time(const struct tm* tmb, const charT* fmt);
61
+
62
+ template <class charT>
63
+ T11 quoted(const charT* s, charT delim=charT('"'), charT escape=charT('\\'));
64
+
65
+ template <class charT, class traits, class Allocator>
66
+ T12 quoted(const basic_string<charT, traits, Allocator>& s,
67
+ charT delim=charT('"'), charT escape=charT('\\'));
68
+
69
+ template <class charT, class traits, class Allocator>
70
+ T13 quoted(basic_string<charT, traits, Allocator>& s,
71
+ charT delim=charT('"'), charT escape=charT('\\'));
72
  }
73
  ```
74
 
75
  ### Input streams <a id="input.streams">[[input.streams]]</a>
76
 
 
259
  ``` cpp
260
  namespace std {
261
  template <class charT,class traits = char_traits<charT> >
262
  class basic_istream<charT,traits>::sentry {
263
  typedef traits traits_type;
264
+ bool ok_; // exposition only
265
  public:
266
  explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false);
267
  ~sentry();
268
  explicit operator bool() const { return ok_; }
269
  sentry(const sentry&) = delete;
 
277
 
278
  ``` cpp
279
  explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false);
280
  ```
281
 
282
+ *Effects:* If `is.good()` is `false`, calls `is.setstate(failbit)`.
283
  Otherwise, prepares for formatted or unformatted input. First, if
284
  `is.tie()` is not a null pointer, the function calls `is.tie()->flush()`
285
  to synchronize the output sequence with any associated external C
286
  stream. Except that this call can be suppressed if the put area of
287
  `is.tie()` is empty. Further an implementation is allowed to defer the
288
  call to `flush` until a call of `is.rdbuf()->underflow()` occurs. If no
289
  such call occurs before the `sentry` object is destroyed, the call to
290
+ `flush` may be eliminated entirely.[^17] If `noskipws` is zero and
291
  `is.flags() & ios_base::skipws` is nonzero, the function extracts and
292
  discards each character as long as the next available input character
293
  `c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
294
  `is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
295
  `setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
 
309
  ```
310
 
311
  If, after any preparation is completed, `is.good()` is `true`,
312
  `ok_ != false` otherwise, `ok_ == false`. During preparation, the
313
  constructor may call `setstate(failbit)` (which may throw
314
+ `ios_base::failure` ([[iostate.flags]]))[^18]
315
 
316
  ``` cpp
317
  ~sentry();
318
  ```
319
 
 
331
 
332
  Each formatted input function begins execution by constructing an object
333
  of class `sentry` with the `noskipws` (second) argument `false`. If the
334
  `sentry` object returns `true`, when converted to a value of type
335
  `bool`, the function endeavors to obtain the requested input. If an
336
+ exception is thrown during input then `ios::badbit` is turned on[^19] in
337
  `*this`’s error state. If `(exceptions()&badbit) != 0` then the
338
  exception is rethrown. In any case, the formatted input function
339
  destroys the `sentry` object. If no exception has been thrown, it
340
  returns `*this`.
341
 
 
424
 
425
  ##### `basic_istream::operator>>` <a id="istream::extractors">[[istream::extractors]]</a>
426
 
427
  ``` cpp
428
  basic_istream<charT,traits>& operator>>
429
+ (basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&));
430
  ```
431
 
432
  *Effects:* None. This extractor does not behave as a formatted input
433
  function (as described in  [[istream.formatted.reqmts]].)
434
 
435
+ *Returns:* `pf(*this)`.[^20]
436
 
437
  ``` cpp
438
  basic_istream<charT,traits>& operator>>
439
  (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
440
  ```
 
448
  ``` cpp
449
  basic_istream<charT,traits>& operator>>
450
  (ios_base& (*pf)(ios_base&));
451
  ```
452
 
453
+ *Effects:* Calls `pf(*this)`.[^21] This extractor does not behave as a
454
  formatted input function (as described
455
  in  [[istream.formatted.reqmts]]).
456
 
457
  *Returns:* `*this`.
458
 
 
550
  value of type `bool`, the function returns without attempting to obtain
551
  any input. In either case the number of extracted characters is set to
552
  0; unformatted input functions taking a character array of non-zero size
553
  as an argument shall also store a null character (using `charT()`) in
554
  the first location of the array. If an exception is thrown during input
555
+ then `ios::badbit` is turned on[^22] in `*this`’s error state.
556
  (Exceptions thrown from `basic_ios<>::clear()` are not caught or
557
  rethrown.) If `(exceptions()&badbit) != 0` then the exception is
558
  rethrown. It also counts the number of characters extracted. If no
559
  exception has been thrown it ends by storing the count in a member
560
  object and returning the value specified. In any event the `sentry`
 
587
  ```
588
 
589
  *Effects:* Behaves as an unformatted input function (as described
590
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
591
  object, extracts a character, if one is available, and assigns it to
592
+ `c`.[^23] Otherwise, the function calls `setstate(failbit)` (which may
593
  throw `ios_base::failure` ([[iostate.flags]])).
594
 
595
  *Returns:* `*this`.
596
 
597
  ``` cpp
 
600
  ```
601
 
602
  *Effects:* Behaves as an unformatted input function (as described
603
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
604
  object, extracts characters and stores them into successive locations of
605
+ an array whose first element is designated by `s`.[^24] Characters are
606
  extracted and stored until any of the following occurs:
607
 
608
  - `n` is less than one or `n - 1` characters are stored;
609
  - end-of-file occurs on the input sequence (in which case the function
610
  calls `setstate(eofbit)`);
 
617
  next successive location of the array.
618
 
619
  *Returns:* `*this`.
620
 
621
  ``` cpp
622
+ basic_istream<charT,traits>& get(char_type* s, streamsize n);
623
  ```
624
 
625
  *Effects:* Calls `get(s,n,widen(’\n’))`
626
 
627
  *Returns:* Value returned by the call.
 
664
  ```
665
 
666
  *Effects:* Behaves as an unformatted input function (as described
667
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
668
  object, extracts characters and stores them into successive locations of
669
+ an array whose first element is designated by `s`.[^25] Characters are
670
  extracted and stored until one of the following occurs:
671
 
672
  1. end-of-file occurs on the input sequence (in which case the function
673
  calls `setstate(eofbit)`);
674
  2. `traits::eq(c, delim)` for the next available input character `c`
675
  (in which case the input character is extracted but not
676
+ stored);[^26]
677
  3. `n` is less than one or `n - 1` characters are stored (in which case
678
  the function calls `setstate(failbit)`).
679
 
680
+ These conditions are tested in the order shown.[^27]
681
 
682
  If the function extracts no characters, it calls `setstate(failbit)`
683
+ (which may throw `ios_base::failure` ([[iostate.flags]])).[^28]
684
 
685
  In any case, if `n` is greater than zero, it then stores a null
686
  character (using `charT()`) into the next successive location of the
687
  array.
688
 
 
727
  *Effects:* Behaves as an unformatted input function (as described
728
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
729
  object, extracts characters and discards them. Characters are extracted
730
  until any of the following occurs:
731
 
732
+ - `n != numeric_limits<streamsize>::max()` ([[limits]]) and `n`
733
+ characters have been extracted so far
734
  - end-of-file occurs on the input sequence (in which case the function
735
  calls `setstate(eofbit)`, which may throw
736
  `ios_base::failure` ([[iostate.flags]]));
737
  - `traits::eq_int_type(traits::to_int_type(c), delim)` for the next
738
  available input character `c` (in which case `c` is extracted).
 
760
  *Effects:* Behaves as an unformatted input function (as described
761
  in  [[istream.unformatted]], paragraph 1). After constructing a sentry
762
  object, if `!good()` calls `setstate(failbit)` which may throw an
763
  exception, and return. Otherwise extracts characters and stores them
764
  into successive locations of an array whose first element is designated
765
+ by `s`.[^29] Characters are extracted and stored until either of the
766
  following occurs:
767
 
768
  - `n` characters are stored;
769
  - end-of-file occurs on the input sequence (in which case the function
770
  calls `setstate(failbit | eofbit)`, which may throw
 
1058
  protected:
1059
  basic_ostream(const basic_ostream& rhs) = delete;
1060
  basic_ostream(basic_ostream&& rhs);
1061
 
1062
  // [ostream.assign] Assign/swap
1063
+ basic_ostream& operator=(const basic_ostream& rhs) = delete;
1064
+ basic_ostream& operator=(basic_ostream&& rhs);
1065
  void swap(basic_ostream& rhs);
1066
  };
1067
 
1068
  // [ostream.inserters.character] character inserters
1069
  template<class charT, class traits>
 
1160
 
1161
  ``` cpp
1162
  namespace std {
1163
  template <class charT,class traits = char_traits<charT> >
1164
  class basic_ostream<charT,traits>::sentry {
1165
+ bool ok_; // exposition only
1166
  public:
1167
  explicit sentry(basic_ostream<charT,traits>& os);
1168
  ~sentry();
1169
  explicit operator bool() const { return ok_; }
1170
 
 
1180
  ``` cpp
1181
  explicit sentry(basic_ostream<charT,traits>& os);
1182
  ```
1183
 
1184
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
1185
+ If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^30]
1186
 
1187
  If, after any preparation is completed, `os.good()` is `true`,
1188
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
1189
  constructor may call `setstate(failbit)` (which may throw
1190
+ `ios_base::failure` ([[iostate.flags]]))[^31]
1191
 
1192
  ``` cpp
1193
  ~sentry();
1194
  ```
1195
 
 
1220
  ``` cpp
1221
  basic_ostream<charT,traits>& seekp(off_type off, ios_base::seekdir dir);
1222
  ```
1223
 
1224
  *Effects:* If `fail() != true`, executes
1225
+ `rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
1226
+ function calls `setstate(failbit)` (which may throw
1227
+ `ios_base::failure`).
1228
 
1229
  *Returns:* `*this`.
1230
 
1231
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
1232
 
 
1236
  object of class `sentry`. If this object returns `true` when converted
1237
  to a value of type `bool`, the function endeavors to generate the
1238
  requested output. If the generation fails, then the formatted output
1239
  function does `setstate(ios_base::failbit)`, which might throw an
1240
  exception. If an exception is thrown during output, then `ios::badbit`
1241
+ is turned on[^32] in `*this`’s error state. If
1242
  `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
1243
  not an exception is thrown, the `sentry` object is destroyed before
1244
  leaving the formatted output function. If no exception is thrown, the
1245
  result of the formatted output function is `*this`.
1246
 
1247
+ The descriptions of the individual formatted output functions describe
1248
  how they perform output and do not mention the `sentry` object.
1249
 
1250
+ If a formatted output function of a stream `os` determines padding, it
1251
+ does so as follows. Given a `charT` character sequence `seq` where
1252
+ `charT` is the character type of the stream, if the length of `seq` is
1253
+ less than `os.width()`, then enough copies of `os.fill()` are added to
1254
+ this sequence as necessary to pad to a width of `os.width()` characters.
1255
+ If `(os.flags() & ios_base::adjustfield) == ios_base::left` is `true`,
1256
+ the fill characters are placed after the character sequence; otherwise,
1257
+ they are placed before the character sequence.
1258
+
1259
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
1260
 
1261
  ``` cpp
1262
  operator<<(bool val);
1263
  operator<<(short val);
 
1329
 
1330
  ``` cpp
1331
  bool failed = use_facet<
1332
  num_put<charT,ostreambuf_iterator<charT,traits> >
1333
  >(getloc()).put(*this, *this, fill(),
1334
+ static_cast<double>(val)).failed();
1335
  ```
1336
 
1337
  The first argument provides an object of the `ostreambuf_iterator<>`
1338
  class which is an iterator for class `basic_ostream<>`. It bypasses
1339
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
 
1348
 
1349
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
1350
 
1351
  ``` cpp
1352
  basic_ostream<charT,traits>& operator<<
1353
+ (basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&));
1354
  ```
1355
 
1356
  *Effects:* None. Does not behave as a formatted output function (as
1357
  described in  [[ostream.formatted.reqmts]]).
1358
 
1359
+ *Returns:* `pf(*this)`.[^33]
1360
 
1361
  ``` cpp
1362
  basic_ostream<charT,traits>& operator<<
1363
+ (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
1364
  ```
1365
 
1366
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
1367
  formatted output function (as described
1368
  in  [[ostream.formatted.reqmts]]).
1369
 
1370
+ *Returns:* `*this`.[^34]
1371
 
1372
  ``` cpp
1373
  basic_ostream<charT,traits>& operator<<
1374
+ (ios_base& (*pf)(ios_base&));
1375
  ```
1376
 
1377
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
1378
  formatted output function (as described
1379
  in  [[ostream.formatted.reqmts]]).
 
1409
  ##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
1410
 
1411
  ``` cpp
1412
  template<class charT, class traits>
1413
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
1414
+ charT c);
1415
  template<class charT, class traits>
1416
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
1417
  char c);
1418
  // specialization
1419
  template<class traits>
 
1426
  template<class traits>
1427
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
1428
  unsigned char c);
1429
  ```
1430
 
1431
+ *Effects:* Behaves as a formatted output function
1432
+ (  [[ostream.formatted.reqmts]]) of `out`. Constructs a character
1433
+ sequence `seq`. If `c` has type `char` and the character type of the
1434
+ stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
1435
+ `seq` consists of `c`. Determines padding for `seq` as described
1436
+ in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
1437
+ `os.width(0)`.
 
1438
 
1439
  *Returns:* `out`.
1440
 
1441
  ``` cpp
1442
  template<class charT, class traits>
 
1457
  ```
1458
 
1459
  *Requires:* `s` shall not be a null pointer.
1460
 
1461
  *Effects:* Behaves like a formatted inserter (as described
1462
+ in  [[ostream.formatted.reqmts]]) of `out`. Creates a character sequence
1463
+ `seq` of `n` characters starting at `s`, each widened using
1464
+ `out.widen()` ([[basic.ios.members]]), where `n` is the number that
1465
+ would be computed as if by:
1466
 
1467
  - `traits::length(s)` for the overload where the first argument is of
1468
  type `basic_ostream<charT, traits>&` and the second is of type
1469
  `const charT*`, and also for the overload where the first argument is
1470
  of type `basic_ostream<char, traits>&` and the second is of type
 
1473
  argument is of type `basic_ostream<charT, traits>&` and the second is
1474
  of type `const char*`,
1475
  - `traits::length(reinterpret_cast<const char*>(s))` for the other two
1476
  overloads.
1477
 
1478
+ Determines padding for `seq` as described
1479
+ in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
1480
+ `width(0)`.
 
1481
 
1482
  *Returns:* `out`.
1483
 
1484
  #### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
1485
 
1486
  Each unformatted output function begins execution by constructing an
1487
  object of class `sentry`. If this object returns `true`, while
1488
  converting to a value of type `bool`, the function endeavors to generate
1489
  the requested output. If an exception is thrown during output, then
1490
+ `ios::badbit` is turned on[^35] in `*this`’s error state. If
1491
  `(exceptions() & badbit) != 0` then the exception is rethrown. In any
1492
  case, the unformatted output function ends by destroying the sentry
1493
  object, then, if no exception was thrown, returning the value specified
1494
  for the unformatted output function.
1495
 
 
1497
  basic_ostream<charT,traits>& put(char_type c);
1498
  ```
1499
 
1500
  *Effects:* Behaves as an unformatted output function (as described
1501
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
1502
+ object, inserts the character `c`, if possible.[^36]
1503
 
1504
  Otherwise, calls `setstate(badbit)` (which may throw
1505
  `ios_base::failure` ([[iostate.flags]])).
1506
 
1507
  *Returns:* `*this`.
 
1511
  ```
1512
 
1513
  *Effects:* Behaves as an unformatted output function (as described
1514
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
1515
  object, obtains characters to insert from successive locations of an
1516
+ array whose first element is designated by `s`.[^37] Characters are
1517
  inserted until either of the following occurs:
1518
 
1519
  - `n` characters are inserted;
1520
  - inserting in the output sequence fails (in which case the function
1521
  calls `setstate(badbit)`, which may throw
 
1599
  *Returns:* An object of unspecified type such that if `out` is an object
1600
  of type `basic_ostream<charT, traits>` then the expression
1601
  `out << resetiosflags(mask)` behaves as if it called `f(out, mask)`, or
1602
  if `in` is an object of type `basic_istream<charT, traits>` then the
1603
  expression `in >> resetiosflags(mask)` behaves as if it called
1604
+ `f(in, mask)`, where the function `f` is defined as:[^38]
1605
 
1606
  ``` cpp
1607
  void f(ios_base& str, ios_base::fmtflags mask) {
1608
  // reset specified flags
1609
  str.setf(ios_base::fmtflags(0), mask);
 
1861
  str.setstate(ios_base::badbit);
1862
  }
1863
  ```
1864
 
1865
  The expression `out << put_time(tmb, fmt)` shall have type
1866
+ `basic_ostream<charT, traits>&` and value `out`.
1867
+
1868
+ ### Quoted manipulators <a id="quoted.manip">[[quoted.manip]]</a>
1869
+
1870
+ Quoted manipulators provide string insertion and extraction of quoted
1871
+ strings (for example, XML and CSV formats). Quoted manipulators are
1872
+ useful in ensuring that the content of a string with embedded spaces
1873
+ remains unchanged if inserted and then extracted via stream I/O.
1874
+
1875
+ ``` cpp
1876
+ template <class charT>
1877
+ unspecified quoted(const charT* s, charT delim=charT('"'), charT escape=charT('\\'));
1878
+ template <class charT, class traits, class Allocator>
1879
+ unspecified quoted(const basic_string<charT, traits, Allocator>& s,
1880
+ charT delim=charT('"'), charT escape=charT('\\'));
1881
+ ```
1882
+
1883
+ *Returns:* An object of unspecified type such that if `out` is an
1884
+ instance of `basic_ostream` with member type `char_type` the same as
1885
+ `charT` and with member type `traits_type`, which in the second form is
1886
+ the same as `traits`, then the expression
1887
+ `out << quoted(s, delim, escape)` behaves as a formatted output
1888
+ function ([[ostream.formatted.reqmts]]) of `out`. This forms a
1889
+ character sequence `seq`, initially consisting of the following
1890
+ elements:
1891
+
1892
+ - `delim`.
1893
+ - Each character in `s`. If the character to be output is equal to
1894
+ `escape` or `delim`, as determined by `traits_type::eq`, first output
1895
+ `escape`.
1896
+ - `delim`.
1897
+
1898
+ Let `x` be the number of elements initially in `seq`. Then padding is
1899
+ determined for `seq` as described in  [[ostream.formatted.reqmts]],
1900
+ `seq` is inserted as if by calling `out.rdbuf()->sputn(seq, n)`, where
1901
+ `n` is the larger of `out.width()` and `x`, and `out.width(0)` is
1902
+ called. The expression `out << quoted(s, delim, escape)` shall have type
1903
+ `basic_ostream<charT, traits>&` and value `out`.
1904
+
1905
+ ``` cpp
1906
+ template <class charT, class traits, class Allocator>
1907
+ unspecified quoted(basic_string<charT, traits, Allocator>& s,
1908
+ charT delim=charT('"'), charT escape=charT('\\'));
1909
+ ```
1910
+
1911
+ *Returns:* An object of unspecified type such that:
1912
+
1913
+ - If `in` is an instance of `basic_istream` with member types
1914
+ `char_type` and `traits_type` the same as `charT` and `traits`,
1915
+ respectively, then the expression `in >> quoted(s, delim, escape)`
1916
+ behaves as if it extracts the following characters from `in` using
1917
+ `basic_istream::operator>>` ([[istream::extractors]]) which may throw
1918
+ `ios_base::failure` ([[ios::failure]]):
1919
+ - If the first character extracted is equal to `delim`, as determined
1920
+ by `traits_type::eq`, then:
1921
+ - Turn off the `skipws` flag.
1922
+ - `s.clear()`
1923
+ - Until an unescaped `delim` character is reached or `!in`, extract
1924
+ characters from `in` and append them to `s`, except that if an
1925
+ `escape` is reached, ignore it and append the next character to
1926
+ `s`.
1927
+ - Discard the final `delim` character.
1928
+ - Restore the `skipws` flag to its original value.
1929
+ - Otherwise, `in >> s`.
1930
+ - If `out` is an instance of `basic_ostream` with member types
1931
+ `char_type` and `traits_type` the same as `charT` and `traits`,
1932
+ respectively, then the expression `out << quoted(s, delim, escape)`
1933
+ behaves as specified for the
1934
+ `const basic_string<charT, traits, Allocator>&` overload of the
1935
+ `quoted` function.
1936
+
1937
+ The expression `in >> quoted(s, delim, escape)` shall have type
1938
+ `basic_istream<charT, traits>&` and value `in`. The expression
1939
+ `out << quoted(s, delim, escape)` shall have type
1940
+ `basic_ostream<charT, traits>&` and value `out`.
1941