From Jason Turner

[ostream.formatted]

C++20 → C++23 9.1 KB 178 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpe33isr3e/{from.md → to.md} +141 -30
tmp/tmpe33isr3e/{from.md → to.md} RENAMED
@@ -1,20 +1,22 @@
1
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
2
 
3
  ##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
4
 
5
  Each formatted output function begins execution by constructing an
6
- object of class `sentry`. If this object returns `true` when converted
7
  to a value of type `bool`, the function endeavors to generate the
8
  requested output. If the generation fails, then the formatted output
9
- function does `setstate(ios_base::failbit)`, which might throw an
10
  exception. If an exception is thrown during output, then
11
- `ios_base::badbit` is turned on[^33] in `*this`’s error state. If
12
- `(exceptions()&badbit) != 0` then the exception is rethrown. Whether or
13
- not an exception is thrown, the `sentry` object is destroyed before
14
- leaving the formatted output function. If no exception is thrown, the
15
- result of the formatted output function is `*this`.
 
 
16
 
17
  The descriptions of the individual formatted output functions describe
18
  how they perform output and do not mention the `sentry` object.
19
 
20
  If a formatted output function of a stream `os` determines padding, it
@@ -27,23 +29,23 @@ the fill characters are placed after the character sequence; otherwise,
27
  they are placed before the character sequence.
28
 
29
  ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
30
 
31
  ``` cpp
32
- operator<<(bool val);
33
- operator<<(short val);
34
- operator<<(unsigned short val);
35
- operator<<(int val);
36
- operator<<(unsigned int val);
37
- operator<<(long val);
38
- operator<<(unsigned long val);
39
- operator<<(long long val);
40
- operator<<(unsigned long long val);
41
- operator<<(float val);
42
- operator<<(double val);
43
- operator<<(long double val);
44
- operator<<(const void* val);
45
  ```
46
 
47
  *Effects:* The classes `num_get<>` and `num_put<>` handle
48
  locale-dependent numeric formatting and parsing. These inserter
49
  functions use the imbued `locale` value to perform numeric formatting.
@@ -114,49 +116,90 @@ It provides formatting specifications such as field width, and a locale
114
  from which to obtain other facets. If `failed` is `true` then does
115
  `setstate(badbit)`, which may throw an exception, and returns.
116
 
117
  *Returns:* `*this`.
118
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
119
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
120
 
121
  ``` cpp
122
- basic_ostream<charT, traits>&
123
- operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
124
  ```
125
 
126
  *Effects:* None. Does not behave as a formatted output function (as
127
  described in  [[ostream.formatted.reqmts]]).
128
 
129
- *Returns:* `pf(*this)`.[^34]
130
 
131
  ``` cpp
132
- basic_ostream<charT, traits>&
133
- operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
134
  ```
135
 
136
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
137
  formatted output function (as described
138
  in  [[ostream.formatted.reqmts]]).
139
 
140
- *Returns:* `*this`.[^35]
141
 
142
  ``` cpp
143
- basic_ostream<charT, traits>& operator<<(ios_base& (*pf)(ios_base&));
144
  ```
145
 
146
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
147
  formatted output function (as described
148
  in  [[ostream.formatted.reqmts]]).
149
 
150
  *Returns:* `*this`.
151
 
152
  ``` cpp
153
- basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);
154
  ```
155
 
156
  *Effects:* Behaves as an unformatted output
157
- function [[ostream.unformatted]]. After the sentry object is
158
  constructed, if `sb` is null calls `setstate(badbit)` (which may throw
159
  `ios_base::failure`).
160
 
161
  Gets characters from `sb` and inserts them in `*this`. Characters are
162
  read from `sb` and inserted until any of the following occurs:
@@ -173,11 +216,11 @@ the error state, and if `failbit` is set in `exceptions()` the caught
173
  exception is rethrown.
174
 
175
  *Returns:* `*this`.
176
 
177
  ``` cpp
178
- basic_ostream<charT, traits>& operator<<(nullptr_t);
179
  ```
180
 
181
  *Effects:* Equivalent to:
182
 
183
  ``` cpp
@@ -250,5 +293,73 @@ Determines padding for `seq` as described
250
  in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
251
  `width(0)`.
252
 
253
  *Returns:* `out`.
254
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  #### Formatted output functions <a id="ostream.formatted">[[ostream.formatted]]</a>
2
 
3
  ##### Common requirements <a id="ostream.formatted.reqmts">[[ostream.formatted.reqmts]]</a>
4
 
5
  Each formatted output function begins execution by constructing an
6
+ object of class `sentry`. If that object returns `true` when converted
7
  to a value of type `bool`, the function endeavors to generate the
8
  requested output. If the generation fails, then the formatted output
9
+ function does `setstate(ios_base::failbit)`, which can throw an
10
  exception. If an exception is thrown during output, then
11
+ `ios_base::badbit` is set[^31]
12
+
13
+ in `*this`’s error state. If `(exceptions()&badbit) != 0` then the
14
+ exception is rethrown. Whether or not an exception is thrown, the
15
+ `sentry` object is destroyed before leaving the formatted output
16
+ function. If no exception is thrown, the result of the formatted output
17
+ function is `*this`.
18
 
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
 
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);
35
+ basic_ostream& operator<<(short val);
36
+ basic_ostream& operator<<(unsigned short val);
37
+ basic_ostream& operator<<(int val);
38
+ basic_ostream& operator<<(unsigned int val);
39
+ basic_ostream& operator<<(long val);
40
+ basic_ostream& operator<<(unsigned long val);
41
+ basic_ostream& operator<<(long long val);
42
+ basic_ostream& operator<<(unsigned long long val);
43
+ basic_ostream& operator<<(float val);
44
+ basic_ostream& operator<<(double val);
45
+ basic_ostream& operator<<(long double val);
46
+ basic_ostream& operator<<(const void* val);
47
  ```
48
 
49
  *Effects:* The classes `num_get<>` and `num_put<>` handle
50
  locale-dependent numeric formatting and parsing. These inserter
51
  functions use the imbued `locale` value to perform numeric formatting.
 
116
  from which to obtain other facets. If `failed` is `true` then does
117
  `setstate(badbit)`, which may throw an exception, and returns.
118
 
119
  *Returns:* `*this`.
120
 
121
+ ``` cpp
122
+ basic_ostream& operator<<(const volatile void* p);
123
+ ```
124
+
125
+ *Effects:* Equivalent to:
126
+ `return operator<<(const_cast<const void*>(p));`
127
+
128
+ ``` cpp
129
+ basic_ostream& operator<<(extended-floating-point-type val);
130
+ ```
131
+
132
+ *Effects:* If the floating-point conversion rank of
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
+
159
+ If `failed` is `true` then does `setstate(badbit)`, which may throw an
160
+ exception, and returns.
161
+
162
+ *Returns:* `*this`.
163
+
164
  ##### `basic_ostream::operator<<` <a id="ostream.inserters">[[ostream.inserters]]</a>
165
 
166
  ``` cpp
167
+ basic_ostream& operator<<(basic_ostream& (*pf)(basic_ostream&));
 
168
  ```
169
 
170
  *Effects:* None. Does not behave as a formatted output function (as
171
  described in  [[ostream.formatted.reqmts]]).
172
 
173
+ *Returns:* `pf(*this)`.[^32]
174
 
175
  ``` cpp
176
+ basic_ostream& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
 
177
  ```
178
 
179
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
180
  formatted output function (as described
181
  in  [[ostream.formatted.reqmts]]).
182
 
183
+ *Returns:* `*this`.[^33]
184
 
185
  ``` cpp
186
+ basic_ostream& operator<<(ios_base& (*pf)(ios_base&));
187
  ```
188
 
189
  *Effects:* Calls `pf(*this)`. This inserter does not behave as a
190
  formatted output function (as described
191
  in  [[ostream.formatted.reqmts]]).
192
 
193
  *Returns:* `*this`.
194
 
195
  ``` cpp
196
+ basic_ostream& operator<<(basic_streambuf<charT, traits>* sb);
197
  ```
198
 
199
  *Effects:* Behaves as an unformatted output
200
+ function [[ostream.unformatted]]. After the `sentry` object is
201
  constructed, if `sb` is null calls `setstate(badbit)` (which may throw
202
  `ios_base::failure`).
203
 
204
  Gets characters from `sb` and inserts them in `*this`. Characters are
205
  read from `sb` and inserted until any of the following occurs:
 
216
  exception is rethrown.
217
 
218
  *Returns:* `*this`.
219
 
220
  ``` cpp
221
+ basic_ostream& operator<<(nullptr_t);
222
  ```
223
 
224
  *Effects:* Equivalent to:
225
 
226
  ``` cpp
 
293
  in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
294
  `width(0)`.
295
 
296
  *Returns:* `out`.
297
 
298
+ ##### Print <a id="ostream.formatted.print">[[ostream.formatted.print]]</a>
299
+
300
+ ``` cpp
301
+ template<class... Args>
302
+ void print(ostream& os, format_string<Args...> fmt, Args&&... args);
303
+ ```
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);
332
+ ```
333
+
334
+ *Effects:* Behaves as a formatted output
335
+ function [[ostream.formatted.reqmts]] of `os`, except that:
336
+
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.
365
+