From Jason Turner

[ostream.formatted]

C++23 → Trunk 9.7 KB 112 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpcsc3ehz0/{from.md → to.md} +52 -52
tmp/tmpcsc3ehz0/{from.md → to.md} RENAMED
@@ -19,16 +19,16 @@ function is `*this`.
19
  The descriptions of the individual formatted output functions describe
20
  how they perform output and do not mention the `sentry` object.
21
 
22
  If a formatted output function of a stream `os` determines padding, it
23
  does so as follows. Given a `charT` character sequence `seq` where
24
- `charT` is the character type of the stream, if the length of `seq` is
25
- less than `os.width()`, then enough copies of `os.fill()` are added to
26
- this sequence as necessary to pad to a width of `os.width()` characters.
27
- If `(os.flags() & ios_base::adjustfield) == ios_base::left` is `true`,
28
- the fill characters are placed after the character sequence; otherwise,
29
- they are placed before the character sequence.
30
 
31
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
32
 
33
  ``` cpp
34
  basic_ostream& operator<<(bool val);
@@ -53,59 +53,52 @@ When `val` is of type `bool`, `long`, `unsigned long`, `long long`,
53
  `unsigned long long`, `double`, `long double`, or `const void*`, the
54
  formatting conversion occurs as if it performed the following code
55
  fragment:
56
 
57
  ``` cpp
58
- bool failed = use_facet<
59
- num_put<charT, ostreambuf_iterator<charT, traits>>
60
- >(getloc()).put(*this, *this, fill(), val).failed();
61
  ```
62
 
63
  When `val` is of type `short` the formatting conversion occurs as if it
64
  performed the following code fragment:
65
 
66
  ``` cpp
67
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
68
- bool failed = use_facet<
69
- num_put<charT, ostreambuf_iterator<charT, traits>>
70
- >(getloc()).put(*this, *this, fill(),
71
  baseflags == ios_base::oct || baseflags == ios_base::hex
72
  ? static_cast<long>(static_cast<unsigned short>(val))
73
  : static_cast<long>(val)).failed();
74
  ```
75
 
76
  When `val` is of type `int` the formatting conversion occurs as if it
77
  performed the following code fragment:
78
 
79
  ``` cpp
80
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
81
- bool failed = use_facet<
82
- num_put<charT, ostreambuf_iterator<charT, traits>>
83
- >(getloc()).put(*this, *this, fill(),
84
  baseflags == ios_base::oct || baseflags == ios_base::hex
85
  ? static_cast<long>(static_cast<unsigned int>(val))
86
  : static_cast<long>(val)).failed();
87
  ```
88
 
89
  When `val` is of type `unsigned short` or `unsigned int` the formatting
90
  conversion occurs as if it performed the following code fragment:
91
 
92
  ``` cpp
93
- bool failed = use_facet<
94
- num_put<charT, ostreambuf_iterator<charT, traits>>
95
- >(getloc()).put(*this, *this, fill(),
96
- static_cast<unsigned long>(val)).failed();
97
  ```
98
 
99
  When `val` is of type `float` the formatting conversion occurs as if it
100
  performed the following code fragment:
101
 
102
  ``` cpp
103
- bool failed = use_facet<
104
- num_put<charT, ostreambuf_iterator<charT, traits>>
105
- >(getloc()).put(*this, *this, fill(),
106
- static_cast<double>(val)).failed();
107
  ```
108
 
109
  The first argument provides an object of the `ostreambuf_iterator<>`
110
  class which is an iterator for class `basic_ostream<>`. It bypasses
111
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
@@ -133,26 +126,22 @@ basic_ostream& operator<<(extended-floating-point-type val);
133
  *`extended-floating-point-type`* is less than or equal to that of
134
  `double`, the formatting conversion occurs as if it performed the
135
  following code fragment:
136
 
137
  ``` cpp
138
- bool failed = use_facet<
139
- num_put<charT, ostreambuf_iterator<charT, traits>>
140
- >(getloc()).put(*this, *this, fill(),
141
- static_cast<double>(val)).failed();
142
  ```
143
 
144
  Otherwise, if the floating-point conversion rank of
145
  *`extended-floating-point-type`* is less than or equal to that of
146
  `long double`, the formatting conversion occurs as if it performed the
147
  following code fragment:
148
 
149
  ``` cpp
150
- bool failed = use_facet<
151
- num_put<charT, ostreambuf_iterator<charT, traits>>
152
- >(getloc()).put(*this, *this, fill(),
153
- static_cast<long double>(val)).failed();
154
  ```
155
 
156
  Otherwise, an invocation of the operator function is conditionally
157
  supported with *implementation-defined* semantics.
158
 
@@ -246,15 +235,15 @@ template<class traits>
246
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
247
  ```
248
 
249
  *Effects:* Behaves as a formatted output
250
  function [[ostream.formatted.reqmts]] of `out`. Constructs a character
251
- sequence `seq`. If `c` has type `char` and the character type of the
252
- stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
253
- `seq` consists of `c`. Determines padding for `seq` as described
254
- in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
255
- `os.width(0)`.
256
 
257
  *Returns:* `out`.
258
 
259
  ``` cpp
260
  template<class charT, class traits>
@@ -304,28 +293,38 @@ template<class... Args>
304
 
305
  *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
306
  equivalent to:
307
 
308
  ``` cpp
309
- vprint_unicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
310
  ```
311
 
312
  Otherwise, equivalent to:
313
 
314
  ``` cpp
315
- vprint_nonunicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
316
  ```
317
 
318
  ``` cpp
319
  template<class... Args>
320
  void println(ostream& os, format_string<Args...> fmt, Args&&... args);
321
  ```
322
 
323
  *Effects:* Equivalent to:
324
 
325
  ``` cpp
326
- print(os, "{}\n", format(fmt, std::forward<Args>(args)...));
 
 
 
 
 
 
 
 
 
 
327
  ```
328
 
329
  ``` cpp
330
  void vprint_unicode(ostream& os, string_view fmt, format_args args);
331
  void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
@@ -337,28 +336,29 @@ function [[ostream.formatted.reqmts]] of `os`, except that:
337
  - failure to generate output is reported as specified below, and
338
  - any exception thrown by the call to `vformat` is propagated without
339
  regard to the value of `os.exceptions()` and without turning on
340
  `ios_base::badbit` in the error state of `os`.
341
 
342
- After constructing a `sentry` object, the function initializes an
343
- automatic variable via
344
 
345
  ``` cpp
346
  string out = vformat(os.getloc(), fmt, args);
347
  ```
348
 
349
- If the function is `vprint_unicode` and `os` is a stream that refers to
350
- a terminal capable of displaying Unicode which is determined in an
351
- implementation-defined manner, writes `out` to the terminal using the
352
- native Unicode API; if `out` contains invalid code units, the behavior
353
- is undefined and implementations are encouraged to diagnose it. If the
354
- native Unicode API is used, the function flushes `os` before writing
355
- `out`. Otherwise (if `os` is not such a stream or the function is
356
- `vprint_nonunicode`), inserts the character sequence \[`out.begin()`,
357
- `out.end()`) into `os`. If writing to the terminal or inserting into
358
- `os` fails, calls `os.setstate(ios_base::badbit)` (which may throw
359
- `ios_base::failure`).
 
360
 
361
  *Recommended practice:* For `vprint_unicode`, if invoking the native
362
  Unicode API requires transcoding, implementations should substitute
363
  invalid code units with U+fffd (replacement character) per the Unicode
364
  Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
 
19
  The descriptions of the individual formatted output functions describe
20
  how they perform output and do not mention the `sentry` object.
21
 
22
  If a formatted output function of a stream `os` determines padding, it
23
  does so as follows. Given a `charT` character sequence `seq` where
24
+ `charT` is the character container type of the stream, if the length of
25
+ `seq` is less than `os.width()`, then enough copies of `os.fill()` are
26
+ added to this sequence as necessary to pad to a width of `os.width()`
27
+ characters. If `(os.flags() & ios_base::adjustfield) == ios_base::left`
28
+ is `true`, the fill characters are placed after the character sequence;
29
+ otherwise, they are placed before the character sequence.
30
 
31
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
32
 
33
  ``` cpp
34
  basic_ostream& operator<<(bool val);
 
53
  `unsigned long long`, `double`, `long double`, or `const void*`, the
54
  formatting conversion occurs as if it performed the following code
55
  fragment:
56
 
57
  ``` cpp
58
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
59
+ getloc()).put(*this, *this, fill(), val).failed();
 
60
  ```
61
 
62
  When `val` is of type `short` the formatting conversion occurs as if it
63
  performed the following code fragment:
64
 
65
  ``` cpp
66
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
67
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
68
+ getloc()).put(*this, *this, fill(),
 
69
  baseflags == ios_base::oct || baseflags == ios_base::hex
70
  ? static_cast<long>(static_cast<unsigned short>(val))
71
  : static_cast<long>(val)).failed();
72
  ```
73
 
74
  When `val` is of type `int` the formatting conversion occurs as if it
75
  performed the following code fragment:
76
 
77
  ``` cpp
78
  ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
79
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
80
+ getloc()).put(*this, *this, fill(),
 
81
  baseflags == ios_base::oct || baseflags == ios_base::hex
82
  ? static_cast<long>(static_cast<unsigned int>(val))
83
  : static_cast<long>(val)).failed();
84
  ```
85
 
86
  When `val` is of type `unsigned short` or `unsigned int` the formatting
87
  conversion occurs as if it performed the following code fragment:
88
 
89
  ``` cpp
90
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
91
+ getloc()).put(*this, *this, fill(), static_cast<unsigned long>(val)).failed();
 
 
92
  ```
93
 
94
  When `val` is of type `float` the formatting conversion occurs as if it
95
  performed the following code fragment:
96
 
97
  ``` cpp
98
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
99
+ getloc()).put(*this, *this, fill(), static_cast<double>(val)).failed();
 
 
100
  ```
101
 
102
  The first argument provides an object of the `ostreambuf_iterator<>`
103
  class which is an iterator for class `basic_ostream<>`. It bypasses
104
  `ostream`s and uses `streambuf`s directly. Class `locale` relies on
 
126
  *`extended-floating-point-type`* is less than or equal to that of
127
  `double`, the formatting conversion occurs as if it performed the
128
  following code fragment:
129
 
130
  ``` cpp
131
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
132
+ getloc()).put(*this, *this, fill(), static_cast<double>(val)).failed();
 
 
133
  ```
134
 
135
  Otherwise, if the floating-point conversion rank of
136
  *`extended-floating-point-type`* is less than or equal to that of
137
  `long double`, the formatting conversion occurs as if it performed the
138
  following code fragment:
139
 
140
  ``` cpp
141
+ bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
142
+ getloc()).put(*this, *this, fill(), static_cast<long double>(val)).failed();
 
 
143
  ```
144
 
145
  Otherwise, an invocation of the operator function is conditionally
146
  supported with *implementation-defined* semantics.
147
 
 
235
  basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
236
  ```
237
 
238
  *Effects:* Behaves as a formatted output
239
  function [[ostream.formatted.reqmts]] of `out`. Constructs a character
240
+ sequence `seq`. If `c` has type `char` and the character container type
241
+ of the stream is not `char`, then `seq` consists of `out.widen(c)`;
242
+ otherwise `seq` consists of `c`. Determines padding for `seq` as
243
+ described in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`.
244
+ Calls `os.width(0)`.
245
 
246
  *Returns:* `out`.
247
 
248
  ``` cpp
249
  template<class charT, class traits>
 
293
 
294
  *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
295
  equivalent to:
296
 
297
  ``` cpp
298
+ vprint_unicode(os, fmt.str, make_format_args(args...));
299
  ```
300
 
301
  Otherwise, equivalent to:
302
 
303
  ``` cpp
304
+ vprint_nonunicode(os, fmt.str, make_format_args(args...));
305
  ```
306
 
307
  ``` cpp
308
  template<class... Args>
309
  void println(ostream& os, format_string<Args...> fmt, Args&&... args);
310
  ```
311
 
312
  *Effects:* Equivalent to:
313
 
314
  ``` cpp
315
+ print(os, "{}\n", format(os.getloc(), fmt, std::forward<Args>(args)...));
316
+ ```
317
+
318
+ ``` cpp
319
+ void println(ostream& os);
320
+ ```
321
+
322
+ *Effects:* Equivalent to:
323
+
324
+ ``` cpp
325
+ print(os, "\n");
326
  ```
327
 
328
  ``` cpp
329
  void vprint_unicode(ostream& os, string_view fmt, format_args args);
330
  void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
 
336
  - failure to generate output is reported as specified below, and
337
  - any exception thrown by the call to `vformat` is propagated without
338
  regard to the value of `os.exceptions()` and without turning on
339
  `ios_base::badbit` in the error state of `os`.
340
 
341
+ After constructing a `sentry` object, the function initializes a
342
+ variable with automatic storage duration via
343
 
344
  ``` cpp
345
  string out = vformat(os.getloc(), fmt, args);
346
  ```
347
 
348
+ - If the function is `vprint_unicode` and `os` is a stream that refers
349
+ to a terminal that is capable of displaying Unicode only via a native
350
+ Unicode API, which is determined in an implementation-defined manner,
351
+ flushes `os` and then writes `out` to the terminal using the native
352
+ Unicode API; if `out` contains invalid code units, the behavior is
353
+ undefined. Then establishes an observable
354
+ checkpoint [[intro.abstract]].
355
+ - Otherwise inserts the character sequence \[`out.begin()`, `out.end()`)
356
+ into `os`.
357
+
358
+ If writing to the terminal or inserting into `os` fails, calls
359
+ `os.setstate(ios_base::badbit)` (which may throw `ios_base::failure`).
360
 
361
  *Recommended practice:* For `vprint_unicode`, if invoking the native
362
  Unicode API requires transcoding, implementations should substitute
363
  invalid code units with U+fffd (replacement character) per the Unicode
364
  Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.