From Jason Turner

[output.streams]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp3pgbhhlu/{from.md → to.md} +43 -33
tmp/tmp3pgbhhlu/{from.md → to.md} RENAMED
@@ -63,12 +63,12 @@ namespace std {
63
  protected:
64
  basic_ostream(const basic_ostream& rhs) = delete;
65
  basic_ostream(basic_ostream&& rhs);
66
 
67
  // [ostream.assign] Assign/swap
68
- basic_ostream& operator=(basic_ostream& rhs) = delete;
69
- basic_ostream& operator=(const basic_ostream&& rhs);
70
  void swap(basic_ostream& rhs);
71
  };
72
 
73
  // [ostream.inserters.character] character inserters
74
  template<class charT, class traits>
@@ -165,11 +165,11 @@ void swap(basic_ostream& rhs);
165
 
166
  ``` cpp
167
  namespace std {
168
  template <class charT,class traits = char_traits<charT> >
169
  class basic_ostream<charT,traits>::sentry {
170
- bool ok_; // exposition onlyr
171
  public:
172
  explicit sentry(basic_ostream<charT,traits>& os);
173
  ~sentry();
174
  explicit operator bool() const { return ok_; }
175
 
@@ -185,16 +185,16 @@ exception safe prefix and suffix operations.
185
  ``` cpp
186
  explicit sentry(basic_ostream<charT,traits>& os);
187
  ```
188
 
189
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
190
- If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
191
 
192
  If, after any preparation is completed, `os.good()` is `true`,
193
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
194
  constructor may call `setstate(failbit)` (which may throw
195
- `ios_base::failure` ([[iostate.flags]]))[^30]
196
 
197
  ``` cpp
198
  ~sentry();
199
  ```
200
 
@@ -225,11 +225,13 @@ basic_ostream<charT,traits>& seekp(pos_type pos);
225
  ``` cpp
226
  basic_ostream<charT,traits>& seekp(off_type off, ios_base::seekdir dir);
227
  ```
228
 
229
  *Effects:* If `fail() != true`, executes
230
- `rdbuf()->pubseekoff(off, dir, ios_base::out)`.
 
 
231
 
232
  *Returns:* `*this`.
233
 
234
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
235
 
@@ -239,19 +241,28 @@ Each formatted output function begins execution by constructing an
239
  object of class `sentry`. If this object returns `true` when converted
240
  to a value of type `bool`, the function endeavors to generate the
241
  requested output. If the generation fails, then the formatted output
242
  function does `setstate(ios_base::failbit)`, which might throw an
243
  exception. If an exception is thrown during output, then `ios::badbit`
244
- is turned on[^31] in `*this`’s error state. If
245
  `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
246
  not an exception is thrown, the `sentry` object is destroyed before
247
  leaving the formatted output function. If no exception is thrown, the
248
  result of the formatted output function is `*this`.
249
 
250
- The descriptions of the individual formatted output operations describe
251
  how they perform output and do not mention the `sentry` object.
252
 
 
 
 
 
 
 
 
 
 
253
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
254
 
255
  ``` cpp
256
  operator<<(bool val);
257
  operator<<(short val);
@@ -323,11 +334,11 @@ performed the following code fragment:
323
 
324
  ``` cpp
325
  bool failed = use_facet<
326
  num_put<charT,ostreambuf_iterator<charT,traits> >
327
  >(getloc()).put(*this, *this, fill(),
328
- static_cast<double>(va})).failed();
329
  ```
330
 
331
  The first argument provides an object of the `ostreambuf_iterator<>`
332
  class which is an iterator for class `basic_ostream<>`. It bypasses
333
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
@@ -342,32 +353,32 @@ from which to obtain other facets. If `failed` is `true` then does
342
 
343
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
344
 
345
  ``` cpp
346
  basic_ostream<charT,traits>& operator<<
347
- (basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&))
348
  ```
349
 
350
  *Effects:* None. Does not behave as a formatted output function (as
351
  described in  [[ostream.formatted.reqmts]]).
352
 
353
- *Returns:* `pf(*this)`.[^32]
354
 
355
  ``` cpp
356
  basic_ostream<charT,traits>& operator<<
357
- (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&))
358
  ```
359
 
360
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
361
  formatted output function (as described
362
  in  [[ostream.formatted.reqmts]]).
363
 
364
- *Returns:* `*this`.[^33]
365
 
366
  ``` cpp
367
  basic_ostream<charT,traits>& operator<<
368
- (ios_base& (*pf)(ios_base&))
369
  ```
370
 
371
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
372
  formatted output function (as described
373
  in  [[ostream.formatted.reqmts]]).
@@ -403,11 +414,11 @@ caught exception is rethrown.
403
  ##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
404
 
405
  ``` cpp
406
  template<class charT, class traits>
407
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
408
- charT c};
409
  template<class charT, class traits>
410
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
411
  char c);
412
  // specialization
413
  template<class traits>
@@ -420,18 +431,17 @@ template<class traits>
420
  template<class traits>
421
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
422
  unsigned char c);
423
  ```
424
 
425
- *Effects:* Behaves like a formatted inserter (as described
426
- in  [[ostream.formatted.reqmts]]) of `out`. After a `sentry` object is
427
- constructed it inserts characters. In case `c` has type `char` and the
428
- character type of the stream is not `char`, then the character to be
429
- inserted is `out.widen(c)`; otherwise the character is `c`. Padding is
430
- determined as described in  [[facet.num.put.virtuals]]. `width(0)` is
431
- called. The insertion character and any required padding are inserted
432
- into `out`.
433
 
434
  *Returns:* `out`.
435
 
436
  ``` cpp
437
  template<class charT, class traits>
@@ -452,13 +462,14 @@ template<class traits>
452
  ```
453
 
454
  *Requires:* `s` shall not be a null pointer.
455
 
456
  *Effects:* Behaves like a formatted inserter (as described
457
- in  [[ostream.formatted.reqmts]]) of `out`. After a `sentry` object is
458
- constructed it inserts `n` characters starting at `s`, where `n` is the
459
- number that would be computed as if by:
 
460
 
461
  - `traits::length(s)` for the overload where the first argument is of
462
  type `basic_ostream<charT, traits>&` and the second is of type
463
  `const charT*`, and also for the overload where the first argument is
464
  of type `basic_ostream<char, traits>&` and the second is of type
@@ -467,24 +478,23 @@ number that would be computed as if by:
467
  argument is of type `basic_ostream<charT, traits>&` and the second is
468
  of type `const char*`,
469
  - `traits::length(reinterpret_cast<const char*>(s))` for the other two
470
  overloads.
471
 
472
- Padding is determined as described in  [[facet.num.put.virtuals]]. The
473
- `n` characters starting at `s` are widened using
474
- `out.widen` ([[basic.ios.members]]). The widened characters and any
475
- required padding are inserted into `out`. Calls `width(0)`.
476
 
477
  *Returns:* `out`.
478
 
479
  #### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
480
 
481
  Each unformatted output function begins execution by constructing an
482
  object of class `sentry`. If this object returns `true`, while
483
  converting to a value of type `bool`, the function endeavors to generate
484
  the requested output. If an exception is thrown during output, then
485
- `ios::badbit` is turned on[^34] in `*this`’s error state. If
486
  `(exceptions() & badbit) != 0` then the exception is rethrown. In any
487
  case, the unformatted output function ends by destroying the sentry
488
  object, then, if no exception was thrown, returning the value specified
489
  for the unformatted output function.
490
 
@@ -492,11 +502,11 @@ for the unformatted output function.
492
  basic_ostream<charT,traits>& put(char_type c);
493
  ```
494
 
495
  *Effects:* Behaves as an unformatted output function (as described
496
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
497
- object, inserts the character `c`, if possible.[^35]
498
 
499
  Otherwise, calls `setstate(badbit)` (which may throw
500
  `ios_base::failure` ([[iostate.flags]])).
501
 
502
  *Returns:* `*this`.
@@ -506,11 +516,11 @@ basic_ostream& write(const char_type* s, streamsize n);
506
  ```
507
 
508
  *Effects:* Behaves as an unformatted output function (as described
509
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
510
  object, obtains characters to insert from successive locations of an
511
- array whose first element is designated by `s`.[^36] Characters are
512
  inserted until either of the following occurs:
513
 
514
  - `n` characters are inserted;
515
  - inserting in the output sequence fails (in which case the function
516
  calls `setstate(badbit)`, which may throw
 
63
  protected:
64
  basic_ostream(const basic_ostream& rhs) = delete;
65
  basic_ostream(basic_ostream&& rhs);
66
 
67
  // [ostream.assign] Assign/swap
68
+ basic_ostream& operator=(const basic_ostream& rhs) = delete;
69
+ basic_ostream& operator=(basic_ostream&& rhs);
70
  void swap(basic_ostream& rhs);
71
  };
72
 
73
  // [ostream.inserters.character] character inserters
74
  template<class charT, class traits>
 
165
 
166
  ``` cpp
167
  namespace std {
168
  template <class charT,class traits = char_traits<charT> >
169
  class basic_ostream<charT,traits>::sentry {
170
+ bool ok_; // exposition only
171
  public:
172
  explicit sentry(basic_ostream<charT,traits>& os);
173
  ~sentry();
174
  explicit operator bool() const { return ok_; }
175
 
 
185
  ``` cpp
186
  explicit sentry(basic_ostream<charT,traits>& os);
187
  ```
188
 
189
  If `os.good()` is nonzero, prepares for formatted or unformatted output.
190
+ If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^30]
191
 
192
  If, after any preparation is completed, `os.good()` is `true`,
193
  `ok_ == true` otherwise, `ok_ == false`. During preparation, the
194
  constructor may call `setstate(failbit)` (which may throw
195
+ `ios_base::failure` ([[iostate.flags]]))[^31]
196
 
197
  ``` cpp
198
  ~sentry();
199
  ```
200
 
 
225
  ``` cpp
226
  basic_ostream<charT,traits>& seekp(off_type off, ios_base::seekdir dir);
227
  ```
228
 
229
  *Effects:* If `fail() != true`, executes
230
+ `rdbuf()->pubseekoff(off, dir, ios_base::out)`. In case of failure, the
231
+ function calls `setstate(failbit)` (which may throw
232
+ `ios_base::failure`).
233
 
234
  *Returns:* `*this`.
235
 
236
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
237
 
 
241
  object of class `sentry`. If this object returns `true` when converted
242
  to a value of type `bool`, the function endeavors to generate the
243
  requested output. If the generation fails, then the formatted output
244
  function does `setstate(ios_base::failbit)`, which might throw an
245
  exception. If an exception is thrown during output, then `ios::badbit`
246
+ is turned on[^32] in `*this`’s error state. If
247
  `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
248
  not an exception is thrown, the `sentry` object is destroyed before
249
  leaving the formatted output function. If no exception is thrown, the
250
  result of the formatted output function is `*this`.
251
 
252
+ The descriptions of the individual formatted output functions describe
253
  how they perform output and do not mention the `sentry` object.
254
 
255
+ If a formatted output function of a stream `os` determines padding, it
256
+ does so as follows. Given a `charT` character sequence `seq` where
257
+ `charT` is the character type of the stream, if the length of `seq` is
258
+ less than `os.width()`, then enough copies of `os.fill()` are added to
259
+ this sequence as necessary to pad to a width of `os.width()` characters.
260
+ If `(os.flags() & ios_base::adjustfield) == ios_base::left` is `true`,
261
+ the fill characters are placed after the character sequence; otherwise,
262
+ they are placed before the character sequence.
263
+
264
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
265
 
266
  ``` cpp
267
  operator<<(bool val);
268
  operator<<(short val);
 
334
 
335
  ``` cpp
336
  bool failed = use_facet<
337
  num_put<charT,ostreambuf_iterator<charT,traits> >
338
  >(getloc()).put(*this, *this, fill(),
339
+ static_cast<double>(val)).failed();
340
  ```
341
 
342
  The first argument provides an object of the `ostreambuf_iterator<>`
343
  class which is an iterator for class `basic_ostream<>`. It bypasses
344
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
 
353
 
354
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
355
 
356
  ``` cpp
357
  basic_ostream<charT,traits>& operator<<
358
+ (basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&));
359
  ```
360
 
361
  *Effects:* None. Does not behave as a formatted output function (as
362
  described in  [[ostream.formatted.reqmts]]).
363
 
364
+ *Returns:* `pf(*this)`.[^33]
365
 
366
  ``` cpp
367
  basic_ostream<charT,traits>& operator<<
368
+ (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
369
  ```
370
 
371
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
372
  formatted output function (as described
373
  in  [[ostream.formatted.reqmts]]).
374
 
375
+ *Returns:* `*this`.[^34]
376
 
377
  ``` cpp
378
  basic_ostream<charT,traits>& operator<<
379
+ (ios_base& (*pf)(ios_base&));
380
  ```
381
 
382
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
383
  formatted output function (as described
384
  in  [[ostream.formatted.reqmts]]).
 
414
  ##### Character inserter function templates <a id="ostream.inserters.character">[[ostream.inserters.character]]</a>
415
 
416
  ``` cpp
417
  template<class charT, class traits>
418
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
419
+ charT c);
420
  template<class charT, class traits>
421
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
422
  char c);
423
  // specialization
424
  template<class traits>
 
431
  template<class traits>
432
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
433
  unsigned char c);
434
  ```
435
 
436
+ *Effects:* Behaves as a formatted output function
437
+ (  [[ostream.formatted.reqmts]]) of `out`. Constructs a character
438
+ sequence `seq`. If `c` has type `char` and the character type of the
439
+ stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
440
+ `seq` consists of `c`. Determines padding for `seq` as described
441
+ in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
442
+ `os.width(0)`.
 
443
 
444
  *Returns:* `out`.
445
 
446
  ``` cpp
447
  template<class charT, class traits>
 
462
  ```
463
 
464
  *Requires:* `s` shall not be a null pointer.
465
 
466
  *Effects:* Behaves like a formatted inserter (as described
467
+ in  [[ostream.formatted.reqmts]]) of `out`. Creates a character sequence
468
+ `seq` of `n` characters starting at `s`, each widened using
469
+ `out.widen()` ([[basic.ios.members]]), where `n` is the number that
470
+ would be computed as if by:
471
 
472
  - `traits::length(s)` for the overload where the first argument is of
473
  type `basic_ostream<charT, traits>&` and the second is of type
474
  `const charT*`, and also for the overload where the first argument is
475
  of type `basic_ostream<char, traits>&` and the second is of type
 
478
  argument is of type `basic_ostream<charT, traits>&` and the second is
479
  of type `const char*`,
480
  - `traits::length(reinterpret_cast<const char*>(s))` for the other two
481
  overloads.
482
 
483
+ Determines padding for `seq` as described
484
+ in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
485
+ `width(0)`.
 
486
 
487
  *Returns:* `out`.
488
 
489
  #### Unformatted output functions <a id="ostream.unformatted">[[ostream.unformatted]]</a>
490
 
491
  Each unformatted output function begins execution by constructing an
492
  object of class `sentry`. If this object returns `true`, while
493
  converting to a value of type `bool`, the function endeavors to generate
494
  the requested output. If an exception is thrown during output, then
495
+ `ios::badbit` is turned on[^35] in `*this`’s error state. If
496
  `(exceptions() & badbit) != 0` then the exception is rethrown. In any
497
  case, the unformatted output function ends by destroying the sentry
498
  object, then, if no exception was thrown, returning the value specified
499
  for the unformatted output function.
500
 
 
502
  basic_ostream<charT,traits>& put(char_type c);
503
  ```
504
 
505
  *Effects:* Behaves as an unformatted output function (as described
506
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
507
+ object, inserts the character `c`, if possible.[^36]
508
 
509
  Otherwise, calls `setstate(badbit)` (which may throw
510
  `ios_base::failure` ([[iostate.flags]])).
511
 
512
  *Returns:* `*this`.
 
516
  ```
517
 
518
  *Effects:* Behaves as an unformatted output function (as described
519
  in  [[ostream.unformatted]], paragraph 1). After constructing a sentry
520
  object, obtains characters to insert from successive locations of an
521
+ array whose first element is designated by `s`.[^37] Characters are
522
  inserted until either of the following occurs:
523
 
524
  - `n` characters are inserted;
525
  - inserting in the output sequence fails (in which case the function
526
  calls `setstate(badbit)`, which may throw