From Jason Turner

[iostream.format]

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. 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 charT, class traits, class T>
23
- basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);
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 charT, class traits, class T>
52
- basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);
 
 
 
 
 
 
 
 
 
53
  }
54
  ```
55
 
56
  ### Header `<iomanip>` synopsis <a id="iomanip.syn">[[iomanip.syn]]</a>
57
 
58
  ``` cpp
59
  namespace std {
60
- // types T1, T2, ... are unspecified implementation types
61
- T1 resetiosflags(ios_base::fmtflags mask);
62
- T2 setiosflags (ios_base::fmtflags mask);
63
- T3 setbase(int base);
64
- template<class charT> T4 setfill(charT c);
65
- T5 setprecision(int n);
66
- T6 setw(int n);
67
- template<class moneyT> T7 get_money(moneyT& mon, bool intl = false);
68
- template<class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
69
- template<class charT> T9 get_time(struct tm* tmb, const charT* fmt);
70
- template<class charT> T10 put_time(const struct tm* tmb, const charT* fmt);
71
 
72
  template<class charT>
73
- T11 quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));
74
 
75
  template<class charT, class traits, class Allocator>
76
- T12 quoted(const basic_string<charT, traits, Allocator>& s,
77
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
78
 
79
  template<class charT, class traits, class Allocator>
80
- T13 quoted(basic_string<charT, traits, Allocator>& s,
81
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
82
 
83
  template<class charT, class traits>
84
- T14 quoted(basic_string_view<charT, traits> s,
85
  \itcorr charT delim = charT('"'), charT escape = charT('\\'));
86
  }
87
  ```
88
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
89
  ### Input streams <a id="input.streams">[[input.streams]]</a>
90
 
91
- The header `<istream>` defines two types and a function signature that
92
- control input from a stream buffer along with a function template that
93
- extracts from stream rvalues.
 
 
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<charT, traits>&
118
- operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
119
- basic_istream<charT, traits>&
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<charT, traits>& operator>>(bool& n);
125
- basic_istream<charT, traits>& operator>>(short& n);
126
- basic_istream<charT, traits>& operator>>(unsigned short& n);
127
- basic_istream<charT, traits>& operator>>(int& n);
128
- basic_istream<charT, traits>& operator>>(unsigned int& n);
129
- basic_istream<charT, traits>& operator>>(long& n);
130
- basic_istream<charT, traits>& operator>>(unsigned long& n);
131
- basic_istream<charT, traits>& operator>>(long long& n);
132
- basic_istream<charT, traits>& operator>>(unsigned long long& n);
133
- basic_istream<charT, traits>& operator>>(float& f);
134
- basic_istream<charT, traits>& operator>>(double& f);
135
- basic_istream<charT, traits>& operator>>(long double& f);
 
136
 
137
- basic_istream<charT, traits>& operator>>(void*& p);
138
- basic_istream<charT, traits>& operator>>(basic_streambuf<char_type, traits>* sb);
139
 
140
  // [istream.unformatted], unformatted input
141
  streamsize gcount() const;
142
  int_type get();
143
- basic_istream<charT, traits>& get(char_type& c);
144
- basic_istream<charT, traits>& get(char_type* s, streamsize n);
145
- basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
146
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
147
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
148
 
149
- basic_istream<charT, traits>& getline(char_type* s, streamsize n);
150
- basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
151
 
152
- basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
153
  int_type peek();
154
- basic_istream<charT, traits>& read (char_type* s, streamsize n);
155
  streamsize readsome(char_type* s, streamsize n);
156
 
157
- basic_istream<charT, traits>& putback(char_type c);
158
- basic_istream<charT, traits>& unget();
159
  int sync();
160
 
161
  pos_type tellg();
162
- basic_istream<charT, traits>& seekg(pos_type);
163
- basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);
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], assign and swap
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 = char_traits<charT>>
262
  class basic_istream<charT, traits>::sentry {
263
  bool ok_; // exposition only
 
264
  public:
265
- explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
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<charT, traits>& is, bool noskipws = false);
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] If `noskipws` is zero and
290
- `is.flags() & ios_base::skipws` is nonzero, the function extracts and
291
- discards each character as long as the next available input character
292
- `c` is a whitespace character. If `is.rdbuf()->sbumpc()` or
293
- `is.rdbuf()->sgetc()` returns `traits::eof()`, the function calls
294
- `setstate(failbit | eofbit)` (which may throw `ios_base::failure`).
 
 
295
 
296
  *Remarks:* The constructor
297
 
298
  ``` cpp
299
- explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false)
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 class `sentry` with the `noskipws` (second) argument `false`. If the
 
 
337
  `sentry` object returns `true`, when converted to a value of type
338
- `bool`, the function endeavors to obtain the requested input. If an
339
- exception is thrown during input then `ios_base::badbit` is turned
340
- on[^20] in `*this`’s error state. If `(exceptions()&badbit) != 0` then
341
- the exception is rethrown. In any case, the formatted input function
342
- destroys the `sentry` object. If no exception has been thrown, it
343
- returns `*this`.
 
 
 
 
 
 
 
 
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
- iostate err = iostate::goodbit;
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, err, lval);
398
  if (lval < numeric_limits<short>::min()) {
399
- err |= ios_base::failbit;
400
  val = numeric_limits<short>::min();
401
  } else if (numeric_limits<short>::max() < lval) {
402
- err |= ios_base::failbit;
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, err, lval);
421
  if (lval < numeric_limits<int>::min()) {
422
- err |= ios_base::failbit;
423
  val = numeric_limits<int>::min();
424
  } else if (numeric_limits<int>::max() < lval) {
425
- err |= ios_base::failbit;
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<charT, traits>&
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)`.[^21]
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<charT, traits>& operator>>(ios_base& (*pf)(ios_base&));
457
  ```
458
 
459
- *Effects:* Calls `pf(*this)`.[^22] This extractor does not behave as a
460
- formatted input function (as described
461
- in  [[istream.formatted.reqmts]]).
 
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, it calls `setstate(failbit)`,
492
- which may throw `ios_base::failure` [[iostate.flags]].
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`. After a `sentry` object is
507
- constructed a character is extracted from `in`, if one is available, and
508
- stored in `c`. Otherwise, the function calls `in.setstate(failbit)`.
 
509
 
510
  *Returns:* `in`.
511
 
512
  ``` cpp
513
- basic_istream<charT, traits>& operator>>(basic_streambuf<charT, traits>* sb);
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, it calls `setstate(failbit)`,
530
- which may throw `ios_base::failure` [[iostate.flags]]. If it inserted no
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 class `sentry` with the default argument `noskipws` (second)
541
- argument `true`. If the `sentry` object returns `true`, when converted
542
- to a value of type `bool`, the function endeavors to obtain the
543
- requested input. Otherwise, if the sentry constructor exits by throwing
544
- an exception or if the sentry object returns `false`, when converted to
545
- a value of type `bool`, the function returns without attempting to
546
- obtain any input. In either case the number of extracted characters is
547
- set to 0; unformatted input functions taking a character array of
548
- nonzero size as an argument shall also store a null character (using
549
- `charT()`) in the first location of the array. If an exception is thrown
550
- during input then `ios_base::badbit` is turned on[^23] in `*this`’s
551
- error state. (Exceptions thrown from `basic_ios<>::clear()` are not
552
- caught or rethrown.) If `(exceptions()&badbit) != 0` then the exception
553
- is rethrown. It also counts the number of characters extracted. If no
554
- exception has been thrown it ends by storing the count in a member
555
- object and returning the value specified. In any event the `sentry`
556
- object is destroyed before leaving the unformatted input function.
 
 
 
 
 
 
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`, if
574
- one is available. Otherwise, the function calls `setstate(failbit)`,
575
- which may throw `ios_base::failure` [[iostate.flags]].
576
 
577
  *Returns:* `c` if available, otherwise `traits::eof()`.
578
 
579
  ``` cpp
580
- basic_istream<charT, traits>& get(char_type& c);
581
  ```
582
 
583
  *Effects:* Behaves as an unformatted input function (as described
584
- above). After constructing a sentry object, extracts a character, if one
585
- is available, and assigns it to `c`.[^24] Otherwise, the function calls
586
- `setstate(failbit)` (which may throw `ios_base::failure`
587
- [[iostate.flags]]).
 
588
 
589
  *Returns:* `*this`.
590
 
591
  ``` cpp
592
- basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
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`.[^25] Characters are extracted and stored until any of
599
- the following occurs:
 
600
 
601
  - `n` is less than one or `n - 1` characters are stored;
602
- - end-of-file occurs on the input sequence (in which case the function
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, it calls `setstate(failbit)`
608
- (which may throw `ios_base::failure` [[iostate.flags]]). In any case, if
609
- `n` is greater than zero it then stores a null character into the next
610
- successive location of the array.
611
 
612
  *Returns:* `*this`.
613
 
614
  ``` cpp
615
- basic_istream<charT, traits>& get(char_type* s, streamsize n);
616
  ```
617
 
618
  *Effects:* Calls `get(s, n, widen(’\n’))`.
619
 
620
  *Returns:* Value returned by the call.
621
 
622
  ``` cpp
623
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);
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, it calls `setstate(failbit)`,
640
- which may throw `ios_base::failure` [[iostate.flags]].
641
 
642
  *Returns:* `*this`.
643
 
644
  ``` cpp
645
- basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
646
  ```
647
 
648
  *Effects:* Calls `get(sb, widen(’\n’))`.
649
 
650
  *Returns:* Value returned by the call.
651
 
652
  ``` cpp
653
- basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);
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`.[^26] Characters are extracted and stored until one of
660
- the following occurs:
661
 
662
- 1. end-of-file occurs on the input sequence (in which case the function
663
- calls `setstate(eofbit)`);
 
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);[^27]
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.[^28]
671
 
672
- If the function extracts no characters, it calls `setstate(failbit)`
673
- (which may throw `ios_base::failure` [[iostate.flags]]).[^29]
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<charT, traits>& getline(char_type* s, streamsize n);
712
  ```
713
 
714
  *Returns:* `getline(s, n, widen(’\n’))`
715
 
716
  ``` cpp
717
- basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
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
- *Remarks:* The last condition will never occur if
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<charT, traits>& read(char_type* s, streamsize n);
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`.[^30] Characters are
758
- extracted and stored until either of the following occurs:
 
 
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<charT, traits>& putback(char_type c);
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<charT, traits>& seekg(pos_type pos);
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<charT, traits>& seekg(off_type off, ios_base::seekdir dir);
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 sentry
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 and `Istream` is publicly and
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], assign and swap
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
- The header `<ostream>` defines a type and several function signatures
997
- that control output to a stream buffer along with a function template
998
- that inserts into stream rvalues.
 
 
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<charT, traits>&
1023
- operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
1024
- basic_ostream<charT, traits>&
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<charT, traits>& operator<<(bool n);
1030
- basic_ostream<charT, traits>& operator<<(short n);
1031
- basic_ostream<charT, traits>& operator<<(unsigned short n);
1032
- basic_ostream<charT, traits>& operator<<(int n);
1033
- basic_ostream<charT, traits>& operator<<(unsigned int n);
1034
- basic_ostream<charT, traits>& operator<<(long n);
1035
- basic_ostream<charT, traits>& operator<<(unsigned long n);
1036
- basic_ostream<charT, traits>& operator<<(long long n);
1037
- basic_ostream<charT, traits>& operator<<(unsigned long long n);
1038
- basic_ostream<charT, traits>& operator<<(float f);
1039
- basic_ostream<charT, traits>& operator<<(double f);
1040
- basic_ostream<charT, traits>& operator<<(long double f);
 
1041
 
1042
- basic_ostream<charT, traits>& operator<<(const void* p);
1043
- basic_ostream<charT, traits>& operator<<(nullptr_t);
1044
- basic_ostream<charT, traits>& operator<<(basic_streambuf<char_type, traits>* sb);
 
1045
 
1046
  // [ostream.unformatted], unformatted output
1047
- basic_ostream<charT, traits>& put(char_type c);
1048
- basic_ostream<charT, traits>& write(const char_type* s, streamsize n);
1049
 
1050
- basic_ostream<charT, traits>& flush();
1051
 
1052
  // [ostream.seeks], seeks
1053
  pos_type tellp();
1054
- basic_ostream<charT, traits>& seekp(pos_type);
1055
- basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);
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], assign and swap
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 = char_traits<charT>>
1203
  class basic_ostream<charT, traits>::sentry {
1204
  bool ok_; // exposition only
 
1205
  public:
1206
- explicit sentry(basic_ostream<charT, traits>& os);
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<charT, traits>& os);
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()`.[^31]
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]]).[^32]
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<charT, traits>& seekp(pos_type pos);
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<charT, traits>& seekp(off_type off, ios_base::seekdir dir);
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 this object returns `true` when converted
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 might throw an
1289
  exception. If an exception is thrown during output, then
1290
- `ios_base::badbit` is turned on[^33] in `*this`’s error state. If
1291
- `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
1292
- not an exception is thrown, the `sentry` object is destroyed before
1293
- leaving the formatted output function. If no exception is thrown, the
1294
- result of the formatted output function is `*this`.
 
 
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<charT, traits>&
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)`.[^34]
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`.[^35]
1420
 
1421
  ``` cpp
1422
- basic_ostream<charT, traits>& operator<<(ios_base& (*pf)(ios_base&));
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<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
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<charT, traits>& operator<<(nullptr_t);
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 this object returns `true`, while
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 turned on[^36] in `*this`’s error state. If
1541
- `(exceptions() & badbit) != 0` then the exception is rethrown. In any
1542
- case, the unformatted output function ends by destroying the sentry
1543
- object, then, if no exception was thrown, returning the value specified
1544
- for the unformatted output function.
 
1545
 
1546
  ``` cpp
1547
- basic_ostream<charT, traits>& put(char_type c);
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.[^37]
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 insert
1565
- from successive locations of an array whose first element is designated
1566
- by `s`.[^38] Characters are inserted until either of the following
1567
- occurs:
 
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 object.
1582
- If this object returns `true` when converted to a value of type `bool`
1583
- the function calls `rdbuf()->pubsync()`. If that function returns -1
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, calls `buf->emit()`.
 
 
 
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:[^39]
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(struct tm* tmb, const charT* fmt);
1893
  ```
1894
 
1895
  *Preconditions:* The argument `tmb` is a valid pointer to an object of
1896
- type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
1897
- is a valid range.
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, struct tm* tmb, const charT* fmt) {
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 struct tm* tmb, const charT* fmt);
1926
  ```
1927
 
1928
  *Preconditions:* The argument `tmb` is a valid pointer to an object of
1929
- type `struct tm`, and \[`fmt`, `fmt + char_traits<charT>::length(fmt)`)
1930
- is a valid range.
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 struct tm* tmb, const charT* fmt) {
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
+