- tmp/tmpj614w7us/{from.md → to.md} +1082 -732
tmp/tmpj614w7us/{from.md → to.md}
RENAMED
|
@@ -2,111 +2,160 @@
|
|
| 2 |
|
| 3 |
### Header `<format>` synopsis <a id="format.syn">[[format.syn]]</a>
|
| 4 |
|
| 5 |
``` cpp
|
| 6 |
namespace std {
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7 |
// [format.functions], formatting functions
|
| 8 |
template<class... Args>
|
| 9 |
-
string format(
|
| 10 |
template<class... Args>
|
| 11 |
-
wstring format(
|
| 12 |
template<class... Args>
|
| 13 |
-
string format(const locale& loc,
|
| 14 |
template<class... Args>
|
| 15 |
-
wstring format(const locale& loc,
|
| 16 |
|
| 17 |
string vformat(string_view fmt, format_args args);
|
| 18 |
wstring vformat(wstring_view fmt, wformat_args args);
|
| 19 |
string vformat(const locale& loc, string_view fmt, format_args args);
|
| 20 |
wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
|
| 21 |
|
| 22 |
template<class Out, class... Args>
|
| 23 |
-
Out format_to(Out out,
|
| 24 |
template<class Out, class... Args>
|
| 25 |
-
Out format_to(Out out,
|
| 26 |
template<class Out, class... Args>
|
| 27 |
-
Out format_to(Out out, const locale& loc,
|
| 28 |
template<class Out, class... Args>
|
| 29 |
-
Out format_to(Out out, const locale& loc,
|
| 30 |
|
| 31 |
template<class Out>
|
| 32 |
-
Out vformat_to(Out out, string_view fmt,
|
| 33 |
-
format_args_t<type_identity_t<Out>, char> args);
|
| 34 |
template<class Out>
|
| 35 |
-
Out vformat_to(Out out, wstring_view fmt,
|
| 36 |
-
format_args_t<type_identity_t<Out>, wchar_t> args);
|
| 37 |
template<class Out>
|
| 38 |
-
Out vformat_to(Out out, const locale& loc, string_view fmt,
|
| 39 |
-
format_args_t<type_identity_t<Out>, char> args);
|
| 40 |
template<class Out>
|
| 41 |
-
Out vformat_to(Out out, const locale& loc, wstring_view fmt,
|
| 42 |
-
format_args_t<type_identity_t<Out>, wchar_t> args);
|
| 43 |
|
| 44 |
template<class Out> struct format_to_n_result {
|
| 45 |
Out out;
|
| 46 |
iter_difference_t<Out> size;
|
| 47 |
};
|
| 48 |
template<class Out, class... Args>
|
| 49 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 50 |
-
|
| 51 |
template<class Out, class... Args>
|
| 52 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 53 |
-
|
| 54 |
template<class Out, class... Args>
|
| 55 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 56 |
-
const locale& loc,
|
| 57 |
-
|
| 58 |
template<class Out, class... Args>
|
| 59 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 60 |
-
const locale& loc,
|
| 61 |
-
|
| 62 |
|
| 63 |
template<class... Args>
|
| 64 |
-
size_t formatted_size(
|
| 65 |
template<class... Args>
|
| 66 |
-
size_t formatted_size(
|
| 67 |
template<class... Args>
|
| 68 |
-
size_t formatted_size(const locale& loc,
|
| 69 |
template<class... Args>
|
| 70 |
-
size_t formatted_size(const locale& loc,
|
| 71 |
|
| 72 |
// [format.formatter], formatter
|
| 73 |
template<class T, class charT = char> struct formatter;
|
| 74 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 75 |
// [format.parse.ctx], class template basic_format_parse_context
|
| 76 |
template<class charT> class basic_format_parse_context;
|
| 77 |
using format_parse_context = basic_format_parse_context<char>;
|
| 78 |
using wformat_parse_context = basic_format_parse_context<wchar_t>;
|
| 79 |
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 83 |
|
| 84 |
// [format.arguments], arguments
|
| 85 |
// [format.arg], class template basic_format_arg
|
| 86 |
template<class Context> class basic_format_arg;
|
| 87 |
|
| 88 |
template<class Visitor, class Context>
|
| 89 |
-
|
| 90 |
|
| 91 |
// [format.arg.store], class template format-arg-store
|
| 92 |
-
template<class Context, class... Args>
|
| 93 |
|
| 94 |
template<class Context = format_context, class... Args>
|
| 95 |
format-arg-store<Context, Args...>
|
| 96 |
-
make_format_args(
|
| 97 |
template<class... Args>
|
| 98 |
format-arg-store<wformat_context, Args...>
|
| 99 |
-
make_wformat_args(
|
| 100 |
-
|
| 101 |
-
// [format.args], class template basic_format_args
|
| 102 |
-
template<class Context> class basic_format_args;
|
| 103 |
-
using format_args = basic_format_args<format_context>;
|
| 104 |
-
using wformat_args = basic_format_args<wformat_context>;
|
| 105 |
-
|
| 106 |
-
template<class Out, class charT>
|
| 107 |
-
using format_args_t = basic_format_args<basic_format_context<Out, charT>>;
|
| 108 |
|
| 109 |
// [format.error], class format_error
|
| 110 |
class format_error;
|
| 111 |
}
|
| 112 |
```
|
|
@@ -198,13 +247,13 @@ manual indexing. — *end note*]
|
|
| 198 |
|
| 199 |
``` cpp
|
| 200 |
string s0 = format("{} to {}", "a", "b"); // OK, automatic indexing
|
| 201 |
string s1 = format("{1} to {0}", "a", "b"); // OK, manual indexing
|
| 202 |
string s2 = format("{0} to {}", "a", "b"); // not a format string (mixing automatic and manual indexing),
|
| 203 |
-
//
|
| 204 |
string s3 = format("{} to {1}", "a", "b"); // not a format string (mixing automatic and manual indexing),
|
| 205 |
-
//
|
| 206 |
```
|
| 207 |
|
| 208 |
— *end example*]
|
| 209 |
|
| 210 |
The *format-spec* field contains *format specifications* that define how
|
|
@@ -226,17 +275,17 @@ by *arg-id*, the string is not a format string for `args`.
|
|
| 226 |
|
| 227 |
— *end example*]
|
| 228 |
|
| 229 |
#### Standard format specifiers <a id="format.string.std">[[format.string.std]]</a>
|
| 230 |
|
| 231 |
-
Each `formatter`
|
| 232 |
for fundamental and string types interprets *format-spec* as a
|
| 233 |
*std-format-spec*.
|
| 234 |
|
| 235 |
[*Note 1*: The format specification can be used to specify such details
|
| 236 |
-
as field width, alignment, padding, and decimal precision. Some
|
| 237 |
-
formatting options are only supported for arithmetic
|
| 238 |
types. — *end note*]
|
| 239 |
|
| 240 |
The syntax of format specifications is as follows:
|
| 241 |
|
| 242 |
``` bnf
|
|
@@ -276,21 +325,40 @@ precision
|
|
| 276 |
'.' '{' arg-idₒₚₜ '}'
|
| 277 |
```
|
| 278 |
|
| 279 |
``` bnf
|
| 280 |
type one of
|
| 281 |
-
'a A b B c d e E f F g G o p s x X'
|
| 282 |
```
|
| 283 |
|
| 284 |
-
|
| 285 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 286 |
following it, which must be one of the alignment options. If the second
|
| 287 |
character of *std-format-spec* is not a valid alignment option, then it
|
| 288 |
-
is assumed that
|
| 289 |
absent. — *end note*]
|
| 290 |
|
| 291 |
-
The *align*
|
| 292 |
various alignment options is as specified in [[format.align]].
|
| 293 |
|
| 294 |
[*Example 1*:
|
| 295 |
|
| 296 |
``` cpp
|
|
@@ -300,34 +368,49 @@ string s1 = format("{:6}", 'x'); // value of s1 is "x\ \ \ \ \ "
|
|
| 300 |
string s2 = format("{:*<6}", 'x'); // value of s2 is "x*****"
|
| 301 |
string s3 = format("{:*>6}", 'x'); // value of s3 is "*****x"
|
| 302 |
string s4 = format("{:*^6}", 'x'); // value of s4 is "**x***"
|
| 303 |
string s5 = format("{:6d}", c); // value of s5 is "\ \ \ 120"
|
| 304 |
string s6 = format("{:6}", true); // value of s6 is "true\ \ "
|
|
|
|
|
|
|
|
|
|
|
|
|
| 305 |
```
|
| 306 |
|
| 307 |
— *end example*]
|
| 308 |
|
| 309 |
-
[*Note
|
| 310 |
-
|
| 311 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 312 |
|
| 313 |
**Table: Meaning of align options** <a id="format.align">[format.align]</a>
|
| 314 |
|
| 315 |
| Option | Meaning |
|
| 316 |
-
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 317 |
-
| `<` | Forces the
|
| 318 |
-
| % `>` | Forces the
|
| 319 |
-
| % `^` | Forces the
|
| 320 |
|
| 321 |
|
| 322 |
The *sign* option is only valid for arithmetic types other than `charT`
|
| 323 |
and `bool` or when an integer presentation type is specified. The
|
| 324 |
meaning of the various options is as specified in [[format.sign]].
|
| 325 |
|
| 326 |
-
|
| 327 |
-
|
| 328 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 329 |
|
| 330 |
The *sign* option applies to floating-point infinity and NaN.
|
| 331 |
|
| 332 |
[*Example 2*:
|
| 333 |
|
|
@@ -353,88 +436,82 @@ form causes the result of the conversion of finite values to always
|
|
| 353 |
contain a decimal-point character, even if no digits follow it.
|
| 354 |
Normally, a decimal-point character appears in the result of these
|
| 355 |
conversions only if a digit follows it. In addition, for `g` and `G`
|
| 356 |
conversions, trailing zeros are not removed from the result.
|
| 357 |
|
| 358 |
-
|
| 359 |
-
|
| 360 |
-
|
| 361 |
-
|
| 362 |
-
|
| 363 |
-
|
| 364 |
-
The *positive-integer* in *width* is a decimal integer defining the
|
| 365 |
-
minimum field width. If *width* is not specified, there is no minimum
|
| 366 |
-
field width, and the field width is determined based on the content of
|
| 367 |
-
the field.
|
| 368 |
-
|
| 369 |
-
The *width* of a string is defined as the estimated number of column
|
| 370 |
-
positions appropriate for displaying it in a terminal.
|
| 371 |
-
|
| 372 |
-
[*Note 5*: This is similar to the semantics of the POSIX `wcswidth`
|
| 373 |
-
function. — *end note*]
|
| 374 |
-
|
| 375 |
-
For the purposes of width computation, a string is assumed to be in a
|
| 376 |
-
locale-independent, implementation-defined encoding. Implementations
|
| 377 |
-
should use a Unicode encoding on platforms capable of displaying Unicode
|
| 378 |
-
text in a terminal.
|
| 379 |
-
|
| 380 |
-
[*Note 6*: This is the case for Windows-based and many POSIX-based
|
| 381 |
-
operating systems. — *end note*]
|
| 382 |
-
|
| 383 |
-
For a string in a Unicode encoding, implementations should estimate the
|
| 384 |
-
width of a string as the sum of estimated widths of the first code
|
| 385 |
-
points in its extended grapheme clusters. The extended grapheme clusters
|
| 386 |
-
of a string are defined by UAX \#29. The estimated width of the
|
| 387 |
-
following code points is 2:
|
| 388 |
-
|
| 389 |
-
- `U+1100-U+115F`
|
| 390 |
-
- `U+2329-U+232A`
|
| 391 |
-
- `U+2E80-U+303E`
|
| 392 |
-
- `U+3040-U+A4CF`
|
| 393 |
-
- `U+AC00-U+D7A3`
|
| 394 |
-
- `U+F900-U+FAFF`
|
| 395 |
-
- `U+FE10-U+FE19`
|
| 396 |
-
- `U+FE30-U+FE6F`
|
| 397 |
-
- `U+FF00-U+FF60`
|
| 398 |
-
- `U+FFE0-U+FFE6`
|
| 399 |
-
- `U+1F300-U+1F64F`
|
| 400 |
-
- `U+1F900-U+1F9FF`
|
| 401 |
-
- `U+20000-U+2FFFD`
|
| 402 |
-
- `U+30000-U+3FFFD`
|
| 403 |
-
|
| 404 |
-
The estimated width of other code points is 1.
|
| 405 |
-
|
| 406 |
-
For a string in a non-Unicode encoding, the width of a string is
|
| 407 |
-
unspecified.
|
| 408 |
-
|
| 409 |
-
A zero (`0`) character preceding the *width* field pads the field with
|
| 410 |
-
leading zeros (following any indication of sign or base) to the field
|
| 411 |
-
width, except when applied to an infinity or NaN. This option is only
|
| 412 |
-
valid for arithmetic types other than `charT` and `bool` or when an
|
| 413 |
-
integer presentation type is specified. If the `0` character and an
|
| 414 |
-
*align* option both appear, the `0` character is ignored.
|
| 415 |
|
| 416 |
[*Example 3*:
|
| 417 |
|
| 418 |
``` cpp
|
| 419 |
char c = 120;
|
| 420 |
string s1 = format("{:+06d}", c); // value of s1 is "+00120"
|
| 421 |
string s2 = format("{:#06x}", 0xa); // value of s2 is "0x000a"
|
| 422 |
-
string s3 = format("{:<06}", -42); // value of s3 is "-42\ \ \ " (0
|
|
|
|
| 423 |
```
|
| 424 |
|
| 425 |
— *end example*]
|
| 426 |
|
| 427 |
-
The *
|
| 428 |
-
|
| 429 |
-
|
| 430 |
-
|
| 431 |
-
|
| 432 |
-
|
| 433 |
-
|
| 434 |
-
|
| 435 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 436 |
|
| 437 |
When the `L` option is used, the form used for the conversion is called
|
| 438 |
the *locale-specific form*. The `L` option is only valid for arithmetic
|
| 439 |
types, and its effect depends upon the type.
|
| 440 |
|
|
@@ -455,22 +532,23 @@ The available string presentation types are specified in
|
|
| 455 |
[[format.type.string]].
|
| 456 |
|
| 457 |
**Table: Meaning of type options for strings** <a id="format.type.string">[format.type.string]</a>
|
| 458 |
|
| 459 |
| Type | Meaning |
|
| 460 |
-
| --------- | -------------------------------- |
|
| 461 |
| none, `s` | Copies the string to the output. |
|
|
|
|
| 462 |
|
| 463 |
|
| 464 |
The meaning of some non-string presentation types is defined in terms of
|
| 465 |
a call to `to_chars`. In such cases, let \[`first`, `last`) be a range
|
| 466 |
large enough to hold the `to_chars` output and `value` be the formatting
|
| 467 |
argument value. Formatting is done as if by calling `to_chars` as
|
| 468 |
specified and copying the output through the output iterator of the
|
| 469 |
format context.
|
| 470 |
|
| 471 |
-
[*Note
|
| 472 |
copying the output through the output iterator as specified by the
|
| 473 |
format specifiers. — *end note*]
|
| 474 |
|
| 475 |
The available integer presentation types for integral types other than
|
| 476 |
`bool` and `charT` are specified in [[format.type.int]].
|
|
@@ -479,49 +557,61 @@ The available integer presentation types for integral types other than
|
|
| 479 |
|
| 480 |
``` cpp
|
| 481 |
string s0 = format("{}", 42); // value of s0 is "42"
|
| 482 |
string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42); // value of s1 is "101010 42 52 2a"
|
| 483 |
string s2 = format("{0:#x} {0:#X}", 42); // value of s2 is "0x2a 0X2A"
|
| 484 |
-
string s3 = format("{:L}", 1234); // value of s3
|
| 485 |
// (depending on the locale)
|
| 486 |
```
|
| 487 |
|
| 488 |
— *end example*]
|
| 489 |
|
| 490 |
-
|
| 491 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 492 |
|
| 493 |
The available `charT` presentation types are specified in
|
| 494 |
[[format.type.char]].
|
| 495 |
|
| 496 |
**Table: Meaning of type options for `charT`** <a id="format.type.char">[format.type.char]</a>
|
| 497 |
|
| 498 |
| Type | Meaning |
|
| 499 |
-
| ------------------------------ | ------------------------------------ |
|
| 500 |
| none, `c` | Copies the character to the output. |
|
| 501 |
| % `b`, `B`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]]. |
|
|
|
|
| 502 |
|
| 503 |
|
| 504 |
The available `bool` presentation types are specified in
|
| 505 |
[[format.type.bool]].
|
| 506 |
|
| 507 |
**Table: Meaning of type options for `bool`** <a id="format.type.bool">[format.type.bool]</a>
|
| 508 |
|
| 509 |
| Type | Meaning |
|
| 510 |
-
| ------------------------------
|
| 511 |
| none, `s` | Copies textual representation, either `true` or `false`, to the output. |
|
| 512 |
-
| % `b`, `B`, `
|
| 513 |
|
| 514 |
|
| 515 |
The available floating-point presentation types and their meanings for
|
| 516 |
values other than infinity and NaN are specified in
|
| 517 |
[[format.type.float]]. For lower-case presentation types, infinity and
|
| 518 |
NaN are formatted as `inf` and `nan`, respectively. For upper-case
|
| 519 |
presentation types, infinity and NaN are formatted as `INF` and `NAN`,
|
| 520 |
respectively.
|
| 521 |
|
| 522 |
-
[*Note
|
| 523 |
*sign* option. — *end note*]
|
| 524 |
|
| 525 |
**Table: Meaning of type options for floating-point types** <a id="format.type.float">[format.type.float]</a>
|
| 526 |
|
| 527 |
| Type | Meaning |
|
|
@@ -537,77 +627,107 @@ respectively.
|
|
| 537 |
|
| 538 |
|
| 539 |
The available pointer presentation types and their mapping to `to_chars`
|
| 540 |
are specified in [[format.type.ptr]].
|
| 541 |
|
| 542 |
-
[*Note
|
| 543 |
`nullptr_t`. — *end note*]
|
| 544 |
|
| 545 |
**Table: Meaning of type options for pointer types** <a id="format.type.ptr">[format.type.ptr]</a>
|
| 546 |
|
| 547 |
| Type | Meaning |
|
| 548 |
-
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 549 |
-
| none, `p` | If `uintptr_t` is defined, \begin{codeblock} to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16) \end{codeblock} with the prefix `0x`
|
| 550 |
|
| 551 |
|
| 552 |
### Error reporting <a id="format.err.report">[[format.err.report]]</a>
|
| 553 |
|
| 554 |
Formatting functions throw `format_error` if an argument `fmt` is passed
|
| 555 |
that is not a format string for `args`. They propagate exceptions thrown
|
| 556 |
by operations of `formatter` specializations and iterators. Failure to
|
| 557 |
allocate storage is reported by throwing an exception as described in
|
| 558 |
[[res.on.exception.handling]].
|
| 559 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 560 |
### Formatting functions <a id="format.functions">[[format.functions]]</a>
|
| 561 |
|
| 562 |
In the description of the functions, operator `+` is used for some of
|
| 563 |
the iterator categories for which it does not have to be defined. In
|
| 564 |
these cases the semantics of `a + n` are the same as in
|
| 565 |
[[algorithms.requirements]].
|
| 566 |
|
| 567 |
``` cpp
|
| 568 |
template<class... Args>
|
| 569 |
-
string format(
|
| 570 |
```
|
| 571 |
|
| 572 |
*Effects:* Equivalent to:
|
| 573 |
|
| 574 |
``` cpp
|
| 575 |
-
return vformat(fmt, make_format_args(args...));
|
| 576 |
```
|
| 577 |
|
| 578 |
``` cpp
|
| 579 |
template<class... Args>
|
| 580 |
-
wstring format(
|
| 581 |
```
|
| 582 |
|
| 583 |
*Effects:* Equivalent to:
|
| 584 |
|
| 585 |
``` cpp
|
| 586 |
-
return vformat(fmt, make_wformat_args(args...));
|
| 587 |
```
|
| 588 |
|
| 589 |
``` cpp
|
| 590 |
template<class... Args>
|
| 591 |
-
string format(const locale& loc,
|
| 592 |
```
|
| 593 |
|
| 594 |
*Effects:* Equivalent to:
|
| 595 |
|
| 596 |
``` cpp
|
| 597 |
-
return vformat(loc, fmt, make_format_args(args...));
|
| 598 |
```
|
| 599 |
|
| 600 |
``` cpp
|
| 601 |
template<class... Args>
|
| 602 |
-
wstring format(const locale& loc,
|
| 603 |
```
|
| 604 |
|
| 605 |
*Effects:* Equivalent to:
|
| 606 |
|
| 607 |
``` cpp
|
| 608 |
-
return vformat(loc, fmt, make_wformat_args(args...));
|
| 609 |
```
|
| 610 |
|
| 611 |
``` cpp
|
| 612 |
string vformat(string_view fmt, format_args args);
|
| 613 |
wstring vformat(wstring_view fmt, wformat_args args);
|
|
@@ -622,98 +742,108 @@ locale-specific formatting.
|
|
| 622 |
|
| 623 |
*Throws:* As specified in [[format.err.report]].
|
| 624 |
|
| 625 |
``` cpp
|
| 626 |
template<class Out, class... Args>
|
| 627 |
-
Out format_to(Out out,
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 628 |
template<class Out, class... Args>
|
| 629 |
-
Out format_to(Out out,
|
| 630 |
```
|
| 631 |
|
| 632 |
*Effects:* Equivalent to:
|
| 633 |
|
| 634 |
``` cpp
|
| 635 |
-
|
| 636 |
-
return vformat_to(out, fmt, make_format_args<context>(args...));
|
| 637 |
```
|
| 638 |
|
| 639 |
``` cpp
|
| 640 |
template<class Out, class... Args>
|
| 641 |
-
Out format_to(Out out, const locale& loc,
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 642 |
template<class Out, class... Args>
|
| 643 |
-
Out format_to(Out out, const locale& loc,
|
| 644 |
```
|
| 645 |
|
| 646 |
*Effects:* Equivalent to:
|
| 647 |
|
| 648 |
``` cpp
|
| 649 |
-
|
| 650 |
-
return vformat_to(out, loc, fmt, make_format_args<context>(args...));
|
| 651 |
```
|
| 652 |
|
| 653 |
``` cpp
|
| 654 |
template<class Out>
|
| 655 |
-
Out vformat_to(Out out, string_view fmt,
|
| 656 |
-
format_args_t<type_identity_t<Out>, char> args);
|
| 657 |
template<class Out>
|
| 658 |
-
Out vformat_to(Out out, wstring_view fmt,
|
| 659 |
-
format_args_t<type_identity_t<Out>, wchar_t> args);
|
| 660 |
template<class Out>
|
| 661 |
-
Out vformat_to(Out out, const locale& loc, string_view fmt,
|
| 662 |
-
format_args_t<type_identity_t<Out>, char> args);
|
| 663 |
template<class Out>
|
| 664 |
-
Out vformat_to(Out out, const locale& loc, wstring_view fmt,
|
| 665 |
-
format_args_t<type_identity_t<Out>, wchar_t> args);
|
| 666 |
```
|
| 667 |
|
| 668 |
Let `charT` be `decltype(fmt)::value_type`.
|
| 669 |
|
| 670 |
*Constraints:* `Out` satisfies `output_iterator<const charT&>`.
|
| 671 |
|
| 672 |
*Preconditions:* `Out` models `output_iterator<const charT&>`.
|
| 673 |
|
| 674 |
*Effects:* Places the character representation of formatting the
|
| 675 |
arguments provided by `args`, formatted according to the specifications
|
| 676 |
-
given in `fmt`, into the range \[`out`, `out + N`), where `N` is
|
| 677 |
-
|
| 678 |
-
|
| 679 |
-
a `loc` parameter. If present, `loc` is used for locale-specific
|
| 680 |
-
formatting.
|
| 681 |
|
| 682 |
*Returns:* `out + N`.
|
| 683 |
|
| 684 |
*Throws:* As specified in [[format.err.report]].
|
| 685 |
|
| 686 |
``` cpp
|
| 687 |
template<class Out, class... Args>
|
| 688 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 689 |
-
|
| 690 |
template<class Out, class... Args>
|
| 691 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 692 |
-
|
| 693 |
template<class Out, class... Args>
|
| 694 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 695 |
-
const locale& loc,
|
| 696 |
-
|
| 697 |
template<class Out, class... Args>
|
| 698 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 699 |
-
const locale& loc,
|
| 700 |
-
|
| 701 |
```
|
| 702 |
|
| 703 |
Let
|
| 704 |
|
| 705 |
-
- `charT` be `decltype(fmt)::value_type`,
|
| 706 |
- `N` be `formatted_size(fmt, args...)` for the functions without a
|
| 707 |
`loc` parameter and `formatted_size(loc, fmt, args...)` for the
|
| 708 |
functions with a `loc` parameter, and
|
| 709 |
- `M` be `clamp(n, 0, N)`.
|
| 710 |
|
| 711 |
*Constraints:* `Out` satisfies `output_iterator<const charT&>`.
|
| 712 |
|
| 713 |
*Preconditions:* `Out` models `output_iterator<const charT&>`, and
|
| 714 |
-
`formatter<``Tᵢ``, charT>` meets the
|
| 715 |
requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
|
| 716 |
|
| 717 |
*Effects:* Places the first `M` characters of the character
|
| 718 |
representation of formatting the arguments provided by `args`, formatted
|
| 719 |
according to the specifications given in `fmt`, into the range \[`out`,
|
|
@@ -723,22 +853,22 @@ according to the specifications given in `fmt`, into the range \[`out`,
|
|
| 723 |
|
| 724 |
*Throws:* As specified in [[format.err.report]].
|
| 725 |
|
| 726 |
``` cpp
|
| 727 |
template<class... Args>
|
| 728 |
-
size_t formatted_size(
|
| 729 |
template<class... Args>
|
| 730 |
-
size_t formatted_size(
|
| 731 |
template<class... Args>
|
| 732 |
-
size_t formatted_size(const locale& loc,
|
| 733 |
template<class... Args>
|
| 734 |
-
size_t formatted_size(const locale& loc,
|
| 735 |
```
|
| 736 |
|
| 737 |
-
Let `charT` be `decltype(fmt)::value_type`.
|
| 738 |
|
| 739 |
-
*Preconditions:* `formatter<``Tᵢ``, charT>` meets the
|
| 740 |
requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
|
| 741 |
|
| 742 |
*Returns:* The number of characters in the character representation of
|
| 743 |
formatting arguments `args` formatted according to specifications given
|
| 744 |
in `fmt`. If present, `loc` is used for locale-specific formatting.
|
|
@@ -747,27 +877,30 @@ in `fmt`. If present, `loc` is used for locale-specific formatting.
|
|
| 747 |
|
| 748 |
### Formatter <a id="format.formatter">[[format.formatter]]</a>
|
| 749 |
|
| 750 |
#### Formatter requirements <a id="formatter.requirements">[[formatter.requirements]]</a>
|
| 751 |
|
| 752 |
-
A type `F` meets the requirements if
|
| 753 |
|
| 754 |
-
- it meets the
|
| 755 |
- *Cpp17DefaultConstructible* ([[cpp17.defaultconstructible]]),
|
| 756 |
- *Cpp17CopyConstructible* ([[cpp17.copyconstructible]]),
|
| 757 |
-
|
|
|
|
| 758 |
- *Cpp17Destructible* ([[cpp17.destructible]])
|
| 759 |
|
| 760 |
-
|
| 761 |
-
|
| 762 |
-
|
| 763 |
-
|
|
|
|
|
|
|
| 764 |
|
| 765 |
Given character type `charT`, output iterator type `Out`, and formatting
|
| 766 |
-
argument type `T`, in [[formatter]]:
|
| 767 |
|
| 768 |
-
- `f` is a value of type `F`,
|
|
|
|
| 769 |
- `u` is an lvalue of type `T`,
|
| 770 |
- `t` is a value of a type convertible to (possibly const) `T`,
|
| 771 |
- `PC` is `basic_format_parse_context<charT>`,
|
| 772 |
- `FC` is `basic_format_context<Out, charT>`,
|
| 773 |
- `pc` is an lvalue of type `PC`, and
|
|
@@ -779,35 +912,70 @@ string. If *format-spec* is empty then either `pc.begin() == pc.end()`
|
|
| 779 |
or `*pc.begin() == '}'`.
|
| 780 |
|
| 781 |
[*Note 1*: This allows formatters to emit meaningful error
|
| 782 |
messages. — *end note*]
|
| 783 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 784 |
#### Formatter specializations <a id="format.formatter.spec">[[format.formatter.spec]]</a>
|
| 785 |
|
| 786 |
The functions defined in [[format.functions]] use specializations of the
|
| 787 |
class template `formatter` to format individual arguments.
|
| 788 |
|
| 789 |
Let `charT` be either `char` or `wchar_t`. Each specialization of
|
| 790 |
-
`formatter` is either enabled or disabled, as described below.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 791 |
|
| 792 |
-
|
| 793 |
-
specializations do not. — *end note*]
|
| 794 |
-
|
| 795 |
-
Each header that declares the template `formatter` provides the
|
| 796 |
-
following enabled specializations:
|
| 797 |
-
|
| 798 |
-
- The specializations
|
| 799 |
``` cpp
|
| 800 |
template<> struct formatter<char, char>;
|
| 801 |
template<> struct formatter<char, wchar_t>;
|
| 802 |
template<> struct formatter<wchar_t, wchar_t>;
|
| 803 |
```
|
| 804 |
-
- For each `charT`, the string type specializations
|
| 805 |
``` cpp
|
| 806 |
template<> struct formatter<charT*, charT>;
|
| 807 |
template<> struct formatter<const charT*, charT>;
|
| 808 |
-
template<size_t N> struct formatter<
|
| 809 |
template<class traits, class Allocator>
|
| 810 |
struct formatter<basic_string<charT, traits, Allocator>, charT>;
|
| 811 |
template<class traits>
|
| 812 |
struct formatter<basic_string_view<charT, traits>, charT>;
|
| 813 |
```
|
|
@@ -826,21 +994,21 @@ following enabled specializations:
|
|
| 826 |
|
| 827 |
The `parse` member functions of these formatters interpret the format
|
| 828 |
specification as a *std-format-spec* as described in
|
| 829 |
[[format.string.std]].
|
| 830 |
|
| 831 |
-
[*Note
|
| 832 |
`formatter<const char*, wchar_t>` that would require implicit multibyte
|
| 833 |
/ wide string or character conversion are disabled. — *end note*]
|
| 834 |
|
| 835 |
For any types `T` and `charT` for which neither the library nor the user
|
| 836 |
provides an explicit or partial specialization of the class template
|
| 837 |
`formatter`, `formatter<T, charT>` is disabled.
|
| 838 |
|
| 839 |
If the library provides an explicit or partial specialization of
|
| 840 |
-
`formatter<T, charT>`, that specialization is enabled
|
| 841 |
-
otherwise.
|
| 842 |
|
| 843 |
If `F` is a disabled specialization of `formatter`, these values are
|
| 844 |
`false`:
|
| 845 |
|
| 846 |
- `is_default_constructible_v<F>`,
|
|
@@ -859,11 +1027,11 @@ An enabled specialization `formatter<T, charT>` meets the requirements
|
|
| 859 |
|
| 860 |
enum color { red, green, blue };
|
| 861 |
const char* color_names[] = { "red", "green", "blue" };
|
| 862 |
|
| 863 |
template<> struct std::formatter<color> : std::formatter<const char*> {
|
| 864 |
-
auto format(color c, format_context& ctx) {
|
| 865 |
return formatter<const char*>::format(color_names[c], ctx);
|
| 866 |
}
|
| 867 |
};
|
| 868 |
|
| 869 |
struct err {};
|
|
@@ -874,10 +1042,95 @@ std::string s2 = std::format("{}", red); // OK, user-provided formatter
|
|
| 874 |
std::string s3 = std::format("{}", err{}); // error: disabled formatter
|
| 875 |
```
|
| 876 |
|
| 877 |
— *end example*]
|
| 878 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 879 |
#### Class template `basic_format_parse_context` <a id="format.parse.ctx">[[format.parse.ctx]]</a>
|
| 880 |
|
| 881 |
``` cpp
|
| 882 |
namespace std {
|
| 883 |
template<class charT>
|
|
@@ -946,37 +1199,41 @@ constexpr void advance_to(const_iterator it);
|
|
| 946 |
|
| 947 |
``` cpp
|
| 948 |
constexpr size_t next_arg_id();
|
| 949 |
```
|
| 950 |
|
| 951 |
-
*Effects:* If `indexing_ != manual`, equivalent to:
|
| 952 |
|
| 953 |
``` cpp
|
| 954 |
if (indexing_ == unknown)
|
| 955 |
indexing_ = automatic;
|
| 956 |
return next_arg_id_++;
|
| 957 |
```
|
| 958 |
|
| 959 |
-
*Throws:* `format_error` if `indexing_ == manual`
|
| 960 |
-
of automatic and manual argument indexing.
|
|
|
|
|
|
|
|
|
|
|
|
|
| 961 |
|
| 962 |
``` cpp
|
| 963 |
constexpr void check_arg_id(size_t id);
|
| 964 |
```
|
| 965 |
|
| 966 |
-
*Effects:* If `indexing_ != automatic`, equivalent to:
|
| 967 |
|
| 968 |
``` cpp
|
| 969 |
if (indexing_ == unknown)
|
| 970 |
indexing_ = manual;
|
| 971 |
```
|
| 972 |
|
| 973 |
-
*Throws:* `format_error` if `indexing_ == automatic`
|
| 974 |
-
mixing of automatic and manual argument indexing.
|
| 975 |
|
| 976 |
-
*Remarks:* Call expressions where `id >= num_args_` are not
|
| 977 |
-
constant expressions [[expr.const]].
|
| 978 |
|
| 979 |
#### Class template `basic_format_context` <a id="format.context">[[format.context]]</a>
|
| 980 |
|
| 981 |
``` cpp
|
| 982 |
namespace std {
|
|
@@ -988,11 +1245,11 @@ namespace std {
|
|
| 988 |
public:
|
| 989 |
using iterator = Out;
|
| 990 |
using char_type = charT;
|
| 991 |
template<class T> using formatter_type = formatter<T, charT>;
|
| 992 |
|
| 993 |
-
basic_format_arg<basic_format_context> arg(size_t id) const;
|
| 994 |
std::locale locale();
|
| 995 |
|
| 996 |
iterator out();
|
| 997 |
void advance_to(iterator it);
|
| 998 |
};
|
|
@@ -1008,19 +1265,18 @@ of the formatting arguments and the output iterator.
|
|
| 1008 |
`basic_format_context` with an output iterator that appends to `string`,
|
| 1009 |
such as `back_insert_iterator<string>`. Similarly, `wformat_context` is
|
| 1010 |
an alias for a specialization of `basic_format_context` with an output
|
| 1011 |
iterator that appends to `wstring`.
|
| 1012 |
|
| 1013 |
-
|
| 1014 |
provide a single instantiation of `basic_format_context` for appending
|
| 1015 |
to `basic_string<charT>`, `vector<charT>`, or any other container with
|
| 1016 |
contiguous storage by wrapping those in temporary objects with a uniform
|
| 1017 |
-
interface (such as a `span<charT>`) and polymorphic
|
| 1018 |
-
reallocation. — *end note*]
|
| 1019 |
|
| 1020 |
``` cpp
|
| 1021 |
-
basic_format_arg<basic_format_context> arg(size_t id) const;
|
| 1022 |
```
|
| 1023 |
|
| 1024 |
*Returns:* `args_.get(id)`.
|
| 1025 |
|
| 1026 |
``` cpp
|
|
@@ -1032,17 +1288,17 @@ takes one, and `std::locale()` otherwise.
|
|
| 1032 |
|
| 1033 |
``` cpp
|
| 1034 |
iterator out();
|
| 1035 |
```
|
| 1036 |
|
| 1037 |
-
*
|
| 1038 |
|
| 1039 |
``` cpp
|
| 1040 |
void advance_to(iterator it);
|
| 1041 |
```
|
| 1042 |
|
| 1043 |
-
*Effects:* Equivalent to: `out_ = it;`
|
| 1044 |
|
| 1045 |
[*Example 1*:
|
| 1046 |
|
| 1047 |
``` cpp
|
| 1048 |
struct S { int value; };
|
|
@@ -1064,11 +1320,11 @@ template<> struct std::formatter<S> {
|
|
| 1064 |
ctx.check_arg_id(width_arg_id);
|
| 1065 |
return ++iter;
|
| 1066 |
}
|
| 1067 |
|
| 1068 |
// Formats an S with width given by the argument width_arg_id.
|
| 1069 |
-
auto format(S s, format_context& ctx) {
|
| 1070 |
int width = visit_format_arg([](auto value) -> int {
|
| 1071 |
if constexpr (!is_integral_v<decltype(value)>)
|
| 1072 |
throw format_error("width is not integral");
|
| 1073 |
else if (value < 0 || value > numeric_limits<int>::max())
|
| 1074 |
throw format_error("invalid width");
|
|
@@ -1082,10 +1338,425 @@ template<> struct std::formatter<S> {
|
|
| 1082 |
std::string s = std::format("{0:{1}}", S{42}, 10); // value of s is "xxxxxxxx42"
|
| 1083 |
```
|
| 1084 |
|
| 1085 |
— *end example*]
|
| 1086 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1087 |
### Arguments <a id="format.arguments">[[format.arguments]]</a>
|
| 1088 |
|
| 1089 |
#### Class template `basic_format_arg` <a id="format.arg">[[format.arg]]</a>
|
| 1090 |
|
| 1091 |
``` cpp
|
|
@@ -1102,28 +1773,11 @@ namespace std {
|
|
| 1102 |
int, unsigned int, long long int, unsigned long long int,
|
| 1103 |
float, double, long double,
|
| 1104 |
const char_type*, basic_string_view<char_type>,
|
| 1105 |
const void*, handle> value; // exposition only
|
| 1106 |
|
| 1107 |
-
template<class T> explicit basic_format_arg(
|
| 1108 |
-
explicit basic_format_arg(float n) noexcept; // exposition only
|
| 1109 |
-
explicit basic_format_arg(double n) noexcept; // exposition only
|
| 1110 |
-
explicit basic_format_arg(long double n) noexcept; // exposition only
|
| 1111 |
-
explicit basic_format_arg(const char_type* s); // exposition only
|
| 1112 |
-
|
| 1113 |
-
template<class traits>
|
| 1114 |
-
explicit basic_format_arg(
|
| 1115 |
-
basic_string_view<char_type, traits> s) noexcept; // exposition only
|
| 1116 |
-
|
| 1117 |
-
template<class traits, class Allocator>
|
| 1118 |
-
explicit basic_format_arg(
|
| 1119 |
-
const basic_string<char_type, traits, Allocator>& s) noexcept; // exposition only
|
| 1120 |
-
|
| 1121 |
-
explicit basic_format_arg(nullptr_t) noexcept; // exposition only
|
| 1122 |
-
|
| 1123 |
-
template<class T>
|
| 1124 |
-
explicit basic_format_arg(const T* p) noexcept; // exposition only
|
| 1125 |
|
| 1126 |
public:
|
| 1127 |
basic_format_arg() noexcept;
|
| 1128 |
|
| 1129 |
explicit operator bool() const noexcept;
|
|
@@ -1142,95 +1796,47 @@ basic_format_arg() noexcept;
|
|
| 1142 |
```
|
| 1143 |
|
| 1144 |
*Ensures:* `!(*this)`.
|
| 1145 |
|
| 1146 |
``` cpp
|
| 1147 |
-
template<class T> explicit basic_format_arg(
|
| 1148 |
```
|
| 1149 |
|
| 1150 |
-
*Constraints:*
|
| 1151 |
|
| 1152 |
-
```
|
| 1153 |
-
|
| 1154 |
-
```
|
| 1155 |
-
|
| 1156 |
-
meets the requirements [[formatter.requirements]]. The extent to which
|
| 1157 |
-
an implementation determines that the specialization meets the
|
| 1158 |
-
requirements is unspecified, except that as a minimum the expression
|
| 1159 |
-
|
| 1160 |
-
``` cpp
|
| 1161 |
-
typename Context::template formatter_type<T>()
|
| 1162 |
-
.format(declval<const T&>(), declval<Context&>())
|
| 1163 |
-
```
|
| 1164 |
-
|
| 1165 |
-
shall be well-formed when treated as an unevaluated operand.
|
| 1166 |
|
| 1167 |
-
*Effects:*
|
| 1168 |
|
| 1169 |
-
-
|
| 1170 |
-
- otherwise, if `
|
| 1171 |
`value` with `static_cast<wchar_t>(v)`;
|
| 1172 |
-
- otherwise, if `
|
| 1173 |
-
`sizeof(
|
| 1174 |
`static_cast<int>(v)`;
|
| 1175 |
-
- otherwise, if `
|
| 1176 |
-
`sizeof(
|
| 1177 |
`static_cast<unsigned int>(v)`;
|
| 1178 |
-
- otherwise, if `
|
| 1179 |
-
`sizeof(
|
| 1180 |
`static_cast<long long int>(v)`;
|
| 1181 |
-
- otherwise, if `
|
| 1182 |
-
`sizeof(
|
| 1183 |
with `static_cast<unsigned long long int>(v)`;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1184 |
- otherwise, initializes `value` with `handle(v)`.
|
| 1185 |
|
| 1186 |
-
``` cpp
|
| 1187 |
-
explicit basic_format_arg(float n) noexcept;
|
| 1188 |
-
explicit basic_format_arg(double n) noexcept;
|
| 1189 |
-
explicit basic_format_arg(long double n) noexcept;
|
| 1190 |
-
```
|
| 1191 |
-
|
| 1192 |
-
*Effects:* Initializes `value` with `n`.
|
| 1193 |
-
|
| 1194 |
-
``` cpp
|
| 1195 |
-
explicit basic_format_arg(const char_type* s);
|
| 1196 |
-
```
|
| 1197 |
-
|
| 1198 |
-
*Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
|
| 1199 |
-
|
| 1200 |
-
*Effects:* Initializes `value` with `s`.
|
| 1201 |
-
|
| 1202 |
-
``` cpp
|
| 1203 |
-
template<class traits>
|
| 1204 |
-
explicit basic_format_arg(basic_string_view<char_type, traits> s) noexcept;
|
| 1205 |
-
```
|
| 1206 |
-
|
| 1207 |
-
*Effects:* Initializes `value` with `s`.
|
| 1208 |
-
|
| 1209 |
-
``` cpp
|
| 1210 |
-
template<class traits, class Allocator>
|
| 1211 |
-
explicit basic_format_arg(
|
| 1212 |
-
const basic_string<char_type, traits, Allocator>& s) noexcept;
|
| 1213 |
-
```
|
| 1214 |
-
|
| 1215 |
-
*Effects:* Initializes `value` with
|
| 1216 |
-
`basic_string_view<char_type>(s.data(), s.size())`.
|
| 1217 |
-
|
| 1218 |
-
``` cpp
|
| 1219 |
-
explicit basic_format_arg(nullptr_t) noexcept;
|
| 1220 |
-
```
|
| 1221 |
-
|
| 1222 |
-
*Effects:* Initializes `value` with `static_cast<const void*>(nullptr)`.
|
| 1223 |
-
|
| 1224 |
-
``` cpp
|
| 1225 |
-
template<class T> explicit basic_format_arg(const T* p) noexcept;
|
| 1226 |
-
```
|
| 1227 |
-
|
| 1228 |
-
*Constraints:* `is_void_v<T>` is `true`.
|
| 1229 |
-
|
| 1230 |
-
*Effects:* Initializes `value` with `p`.
|
| 1231 |
-
|
| 1232 |
[*Note 1*: Constructing `basic_format_arg` from a pointer to a member
|
| 1233 |
is ill-formed unless the user provides an enabled specialization of
|
| 1234 |
`formatter` for that pointer to member type. — *end note*]
|
| 1235 |
|
| 1236 |
``` cpp
|
|
@@ -1247,32 +1853,41 @@ namespace std {
|
|
| 1247 |
class basic_format_arg<Context>::handle {
|
| 1248 |
const void* ptr_; // exposition only
|
| 1249 |
void (*format_)(basic_format_parse_context<char_type>&,
|
| 1250 |
Context&, const void*); // exposition only
|
| 1251 |
|
| 1252 |
-
template<class T> explicit handle(
|
| 1253 |
|
| 1254 |
friend class basic_format_arg<Context>; // exposition only
|
| 1255 |
|
| 1256 |
public:
|
| 1257 |
void format(basic_format_parse_context<char_type>&, Context& ctx) const;
|
| 1258 |
};
|
| 1259 |
}
|
| 1260 |
```
|
| 1261 |
|
| 1262 |
``` cpp
|
| 1263 |
-
template<class T> explicit handle(
|
| 1264 |
```
|
| 1265 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1266 |
*Effects:* Initializes `ptr_` with `addressof(val)` and `format_` with
|
| 1267 |
|
| 1268 |
``` cpp
|
| 1269 |
[](basic_format_parse_context<char_type>& parse_ctx,
|
| 1270 |
Context& format_ctx, const void* ptr) {
|
| 1271 |
-
typename Context::template formatter_type<
|
| 1272 |
parse_ctx.advance_to(f.parse(parse_ctx));
|
| 1273 |
-
format_ctx.advance_to(f.format(*static_cast<const
|
|
|
|
| 1274 |
}
|
| 1275 |
```
|
| 1276 |
|
| 1277 |
``` cpp
|
| 1278 |
void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
|
|
@@ -1280,43 +1895,46 @@ void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ct
|
|
| 1280 |
|
| 1281 |
*Effects:* Equivalent to: `format_(parse_ctx, format_ctx, ptr_);`
|
| 1282 |
|
| 1283 |
``` cpp
|
| 1284 |
template<class Visitor, class Context>
|
| 1285 |
-
|
| 1286 |
```
|
| 1287 |
|
| 1288 |
*Effects:* Equivalent to:
|
| 1289 |
-
`return visit(forward<Visitor>(vis), arg.value);`
|
| 1290 |
|
| 1291 |
#### Class template *`format-arg-store`* <a id="format.arg.store">[[format.arg.store]]</a>
|
| 1292 |
|
| 1293 |
``` cpp
|
| 1294 |
namespace std {
|
| 1295 |
template<class Context, class... Args>
|
| 1296 |
-
|
| 1297 |
-
array<basic_format_arg<Context>, sizeof...(Args)> args;
|
| 1298 |
};
|
| 1299 |
}
|
| 1300 |
```
|
| 1301 |
|
| 1302 |
An instance of *`format-arg-store`* stores formatting arguments.
|
| 1303 |
|
| 1304 |
``` cpp
|
| 1305 |
template<class Context = format_context, class... Args>
|
| 1306 |
-
format-arg-store<Context, Args...> make_format_args(
|
| 1307 |
```
|
| 1308 |
|
| 1309 |
*Preconditions:* The type
|
| 1310 |
-
`typename Context::template formatter_type<``Tᵢ``>`
|
| 1311 |
-
requirements [[formatter.requirements]] for each `Tᵢ` in
|
|
|
|
| 1312 |
|
| 1313 |
-
*Returns:* `
|
|
|
|
|
|
|
| 1314 |
|
| 1315 |
``` cpp
|
| 1316 |
template<class... Args>
|
| 1317 |
-
format-arg-store<wformat_context, Args...> make_wformat_args(
|
| 1318 |
```
|
| 1319 |
|
| 1320 |
*Effects:* Equivalent to:
|
| 1321 |
`return make_format_args<wformat_context>(args...);`
|
| 1322 |
|
|
@@ -1335,15 +1953,22 @@ namespace std {
|
|
| 1335 |
template<class... Args>
|
| 1336 |
basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
|
| 1337 |
|
| 1338 |
basic_format_arg<Context> get(size_t i) const noexcept;
|
| 1339 |
};
|
|
|
|
|
|
|
|
|
|
| 1340 |
}
|
| 1341 |
```
|
| 1342 |
|
| 1343 |
An instance of `basic_format_args` provides access to formatting
|
| 1344 |
-
arguments.
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1345 |
|
| 1346 |
``` cpp
|
| 1347 |
basic_format_args() noexcept;
|
| 1348 |
```
|
| 1349 |
|
|
@@ -1361,14 +1986,140 @@ template<class... Args>
|
|
| 1361 |
basic_format_arg<Context> get(size_t i) const noexcept;
|
| 1362 |
```
|
| 1363 |
|
| 1364 |
*Returns:* `i < size_ ? data_[i] : basic_format_arg<Context>()`.
|
| 1365 |
|
| 1366 |
-
|
| 1367 |
-
|
| 1368 |
-
|
| 1369 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1370 |
|
| 1371 |
### Class `format_error` <a id="format.error">[[format.error]]</a>
|
| 1372 |
|
| 1373 |
``` cpp
|
| 1374 |
namespace std {
|
|
@@ -1393,406 +2144,5 @@ format_error(const string& what_arg);
|
|
| 1393 |
format_error(const char* what_arg);
|
| 1394 |
```
|
| 1395 |
|
| 1396 |
*Ensures:* `strcmp(what(), what_arg) == 0`.
|
| 1397 |
|
| 1398 |
-
<!-- Link reference definitions -->
|
| 1399 |
-
[alg.sorting]: algorithms.md#alg.sorting
|
| 1400 |
-
[algorithms]: algorithms.md#algorithms
|
| 1401 |
-
[algorithms.general]: algorithms.md#algorithms.general
|
| 1402 |
-
[algorithms.requirements]: algorithms.md#algorithms.requirements
|
| 1403 |
-
[allocator.adaptor]: #allocator.adaptor
|
| 1404 |
-
[allocator.adaptor.cnstr]: #allocator.adaptor.cnstr
|
| 1405 |
-
[allocator.adaptor.members]: #allocator.adaptor.members
|
| 1406 |
-
[allocator.adaptor.syn]: #allocator.adaptor.syn
|
| 1407 |
-
[allocator.adaptor.types]: #allocator.adaptor.types
|
| 1408 |
-
[allocator.globals]: #allocator.globals
|
| 1409 |
-
[allocator.members]: #allocator.members
|
| 1410 |
-
[allocator.requirements.completeness]: library.md#allocator.requirements.completeness
|
| 1411 |
-
[allocator.tag]: #allocator.tag
|
| 1412 |
-
[allocator.traits]: #allocator.traits
|
| 1413 |
-
[allocator.traits.members]: #allocator.traits.members
|
| 1414 |
-
[allocator.traits.types]: #allocator.traits.types
|
| 1415 |
-
[allocator.uses]: #allocator.uses
|
| 1416 |
-
[allocator.uses.construction]: #allocator.uses.construction
|
| 1417 |
-
[allocator.uses.trait]: #allocator.uses.trait
|
| 1418 |
-
[any]: #any
|
| 1419 |
-
[any.assign]: #any.assign
|
| 1420 |
-
[any.bad.any.cast]: #any.bad.any.cast
|
| 1421 |
-
[any.class]: #any.class
|
| 1422 |
-
[any.cons]: #any.cons
|
| 1423 |
-
[any.modifiers]: #any.modifiers
|
| 1424 |
-
[any.nonmembers]: #any.nonmembers
|
| 1425 |
-
[any.observers]: #any.observers
|
| 1426 |
-
[any.synop]: #any.synop
|
| 1427 |
-
[arithmetic.operations]: #arithmetic.operations
|
| 1428 |
-
[arithmetic.operations.divides]: #arithmetic.operations.divides
|
| 1429 |
-
[arithmetic.operations.minus]: #arithmetic.operations.minus
|
| 1430 |
-
[arithmetic.operations.modulus]: #arithmetic.operations.modulus
|
| 1431 |
-
[arithmetic.operations.multiplies]: #arithmetic.operations.multiplies
|
| 1432 |
-
[arithmetic.operations.negate]: #arithmetic.operations.negate
|
| 1433 |
-
[arithmetic.operations.plus]: #arithmetic.operations.plus
|
| 1434 |
-
[array]: containers.md#array
|
| 1435 |
-
[associative]: containers.md#associative
|
| 1436 |
-
[basic.align]: basic.md#basic.align
|
| 1437 |
-
[basic.compound]: basic.md#basic.compound
|
| 1438 |
-
[basic.def.odr]: basic.md#basic.def.odr
|
| 1439 |
-
[basic.fundamental]: basic.md#basic.fundamental
|
| 1440 |
-
[basic.life]: basic.md#basic.life
|
| 1441 |
-
[basic.stc.dynamic.allocation]: basic.md#basic.stc.dynamic.allocation
|
| 1442 |
-
[basic.stc.dynamic.safety]: basic.md#basic.stc.dynamic.safety
|
| 1443 |
-
[basic.types]: basic.md#basic.types
|
| 1444 |
-
[bitmask.types]: library.md#bitmask.types
|
| 1445 |
-
[bitset]: #bitset
|
| 1446 |
-
[bitset.cons]: #bitset.cons
|
| 1447 |
-
[bitset.hash]: #bitset.hash
|
| 1448 |
-
[bitset.members]: #bitset.members
|
| 1449 |
-
[bitset.operators]: #bitset.operators
|
| 1450 |
-
[bitset.syn]: #bitset.syn
|
| 1451 |
-
[bitwise.operations]: #bitwise.operations
|
| 1452 |
-
[bitwise.operations.and]: #bitwise.operations.and
|
| 1453 |
-
[bitwise.operations.not]: #bitwise.operations.not
|
| 1454 |
-
[bitwise.operations.or]: #bitwise.operations.or
|
| 1455 |
-
[bitwise.operations.xor]: #bitwise.operations.xor
|
| 1456 |
-
[c.malloc]: #c.malloc
|
| 1457 |
-
[charconv]: #charconv
|
| 1458 |
-
[charconv.from.chars]: #charconv.from.chars
|
| 1459 |
-
[charconv.syn]: #charconv.syn
|
| 1460 |
-
[charconv.to.chars]: #charconv.to.chars
|
| 1461 |
-
[class.copy.ctor]: class.md#class.copy.ctor
|
| 1462 |
-
[class.mem]: class.md#class.mem
|
| 1463 |
-
[comparisons]: #comparisons
|
| 1464 |
-
[comparisons.equal.to]: #comparisons.equal.to
|
| 1465 |
-
[comparisons.greater]: #comparisons.greater
|
| 1466 |
-
[comparisons.greater.equal]: #comparisons.greater.equal
|
| 1467 |
-
[comparisons.less]: #comparisons.less
|
| 1468 |
-
[comparisons.less.equal]: #comparisons.less.equal
|
| 1469 |
-
[comparisons.not.equal.to]: #comparisons.not.equal.to
|
| 1470 |
-
[comparisons.three.way]: #comparisons.three.way
|
| 1471 |
-
[concepts.equality]: concepts.md#concepts.equality
|
| 1472 |
-
[conv.array]: expr.md#conv.array
|
| 1473 |
-
[conv.func]: expr.md#conv.func
|
| 1474 |
-
[conv.lval]: expr.md#conv.lval
|
| 1475 |
-
[conv.qual]: expr.md#conv.qual
|
| 1476 |
-
[conv.rank]: basic.md#conv.rank
|
| 1477 |
-
[cpp17.allocator]: #cpp17.allocator
|
| 1478 |
-
[cpp17.copyassignable]: #cpp17.copyassignable
|
| 1479 |
-
[cpp17.copyconstructible]: #cpp17.copyconstructible
|
| 1480 |
-
[cpp17.defaultconstructible]: #cpp17.defaultconstructible
|
| 1481 |
-
[cpp17.destructible]: #cpp17.destructible
|
| 1482 |
-
[cpp17.hash]: #cpp17.hash
|
| 1483 |
-
[cpp17.moveassignable]: #cpp17.moveassignable
|
| 1484 |
-
[cpp17.moveconstructible]: #cpp17.moveconstructible
|
| 1485 |
-
[cpp17.nullablepointer]: #cpp17.nullablepointer
|
| 1486 |
-
[dcl.array]: dcl.md#dcl.array
|
| 1487 |
-
[dcl.constexpr]: dcl.md#dcl.constexpr
|
| 1488 |
-
[dcl.ref]: dcl.md#dcl.ref
|
| 1489 |
-
[declval]: #declval
|
| 1490 |
-
[default.allocator]: #default.allocator
|
| 1491 |
-
[defns.const.subexpr]: library.md#defns.const.subexpr
|
| 1492 |
-
[defns.expression-equivalent]: library.md#defns.expression-equivalent
|
| 1493 |
-
[defns.ntcts]: library.md#defns.ntcts
|
| 1494 |
-
[defns.order.ptr]: #defns.order.ptr
|
| 1495 |
-
[defns.referenceable]: library.md#defns.referenceable
|
| 1496 |
-
[execpol]: #execpol
|
| 1497 |
-
[execpol.general]: #execpol.general
|
| 1498 |
-
[execpol.objects]: #execpol.objects
|
| 1499 |
-
[execpol.par]: #execpol.par
|
| 1500 |
-
[execpol.parunseq]: #execpol.parunseq
|
| 1501 |
-
[execpol.seq]: #execpol.seq
|
| 1502 |
-
[execpol.type]: #execpol.type
|
| 1503 |
-
[execpol.unseq]: #execpol.unseq
|
| 1504 |
-
[execution.syn]: #execution.syn
|
| 1505 |
-
[expr.add]: expr.md#expr.add
|
| 1506 |
-
[expr.alignof]: expr.md#expr.alignof
|
| 1507 |
-
[expr.bit.and]: expr.md#expr.bit.and
|
| 1508 |
-
[expr.call]: expr.md#expr.call
|
| 1509 |
-
[expr.const]: expr.md#expr.const
|
| 1510 |
-
[expr.eq]: expr.md#expr.eq
|
| 1511 |
-
[expr.log.and]: expr.md#expr.log.and
|
| 1512 |
-
[expr.log.or]: expr.md#expr.log.or
|
| 1513 |
-
[expr.mul]: expr.md#expr.mul
|
| 1514 |
-
[expr.or]: expr.md#expr.or
|
| 1515 |
-
[expr.prop]: expr.md#expr.prop
|
| 1516 |
-
[expr.rel]: expr.md#expr.rel
|
| 1517 |
-
[expr.unary.op]: expr.md#expr.unary.op
|
| 1518 |
-
[expr.xor]: expr.md#expr.xor
|
| 1519 |
-
[format]: #format
|
| 1520 |
-
[format.align]: #format.align
|
| 1521 |
-
[format.arg]: #format.arg
|
| 1522 |
-
[format.arg.store]: #format.arg.store
|
| 1523 |
-
[format.args]: #format.args
|
| 1524 |
-
[format.arguments]: #format.arguments
|
| 1525 |
-
[format.context]: #format.context
|
| 1526 |
-
[format.err.report]: #format.err.report
|
| 1527 |
-
[format.error]: #format.error
|
| 1528 |
-
[format.formatter]: #format.formatter
|
| 1529 |
-
[format.formatter.spec]: #format.formatter.spec
|
| 1530 |
-
[format.functions]: #format.functions
|
| 1531 |
-
[format.parse.ctx]: #format.parse.ctx
|
| 1532 |
-
[format.sign]: #format.sign
|
| 1533 |
-
[format.string]: #format.string
|
| 1534 |
-
[format.string.general]: #format.string.general
|
| 1535 |
-
[format.string.std]: #format.string.std
|
| 1536 |
-
[format.syn]: #format.syn
|
| 1537 |
-
[format.type.bool]: #format.type.bool
|
| 1538 |
-
[format.type.char]: #format.type.char
|
| 1539 |
-
[format.type.float]: #format.type.float
|
| 1540 |
-
[format.type.int]: #format.type.int
|
| 1541 |
-
[format.type.ptr]: #format.type.ptr
|
| 1542 |
-
[format.type.string]: #format.type.string
|
| 1543 |
-
[formatter]: #formatter
|
| 1544 |
-
[formatter.requirements]: #formatter.requirements
|
| 1545 |
-
[forward]: #forward
|
| 1546 |
-
[func.bind]: #func.bind
|
| 1547 |
-
[func.bind.bind]: #func.bind.bind
|
| 1548 |
-
[func.bind.front]: #func.bind.front
|
| 1549 |
-
[func.bind.isbind]: #func.bind.isbind
|
| 1550 |
-
[func.bind.isplace]: #func.bind.isplace
|
| 1551 |
-
[func.bind.place]: #func.bind.place
|
| 1552 |
-
[func.def]: #func.def
|
| 1553 |
-
[func.identity]: #func.identity
|
| 1554 |
-
[func.invoke]: #func.invoke
|
| 1555 |
-
[func.memfn]: #func.memfn
|
| 1556 |
-
[func.not.fn]: #func.not.fn
|
| 1557 |
-
[func.require]: #func.require
|
| 1558 |
-
[func.search]: #func.search
|
| 1559 |
-
[func.search.bm]: #func.search.bm
|
| 1560 |
-
[func.search.bmh]: #func.search.bmh
|
| 1561 |
-
[func.search.default]: #func.search.default
|
| 1562 |
-
[func.wrap]: #func.wrap
|
| 1563 |
-
[func.wrap.badcall]: #func.wrap.badcall
|
| 1564 |
-
[func.wrap.func]: #func.wrap.func
|
| 1565 |
-
[func.wrap.func.alg]: #func.wrap.func.alg
|
| 1566 |
-
[func.wrap.func.cap]: #func.wrap.func.cap
|
| 1567 |
-
[func.wrap.func.con]: #func.wrap.func.con
|
| 1568 |
-
[func.wrap.func.inv]: #func.wrap.func.inv
|
| 1569 |
-
[func.wrap.func.mod]: #func.wrap.func.mod
|
| 1570 |
-
[func.wrap.func.nullptr]: #func.wrap.func.nullptr
|
| 1571 |
-
[func.wrap.func.targ]: #func.wrap.func.targ
|
| 1572 |
-
[function.objects]: #function.objects
|
| 1573 |
-
[functional.syn]: #functional.syn
|
| 1574 |
-
[intro.multithread]: basic.md#intro.multithread
|
| 1575 |
-
[intro.object]: basic.md#intro.object
|
| 1576 |
-
[intseq]: #intseq
|
| 1577 |
-
[intseq.general]: #intseq.general
|
| 1578 |
-
[intseq.intseq]: #intseq.intseq
|
| 1579 |
-
[intseq.make]: #intseq.make
|
| 1580 |
-
[invalid.argument]: diagnostics.md#invalid.argument
|
| 1581 |
-
[iostate.flags]: input.md#iostate.flags
|
| 1582 |
-
[istream.formatted]: input.md#istream.formatted
|
| 1583 |
-
[logical.operations]: #logical.operations
|
| 1584 |
-
[logical.operations.and]: #logical.operations.and
|
| 1585 |
-
[logical.operations.not]: #logical.operations.not
|
| 1586 |
-
[logical.operations.or]: #logical.operations.or
|
| 1587 |
-
[mem.poly.allocator.class]: #mem.poly.allocator.class
|
| 1588 |
-
[mem.poly.allocator.ctor]: #mem.poly.allocator.ctor
|
| 1589 |
-
[mem.poly.allocator.eq]: #mem.poly.allocator.eq
|
| 1590 |
-
[mem.poly.allocator.mem]: #mem.poly.allocator.mem
|
| 1591 |
-
[mem.res]: #mem.res
|
| 1592 |
-
[mem.res.class]: #mem.res.class
|
| 1593 |
-
[mem.res.eq]: #mem.res.eq
|
| 1594 |
-
[mem.res.global]: #mem.res.global
|
| 1595 |
-
[mem.res.monotonic.buffer]: #mem.res.monotonic.buffer
|
| 1596 |
-
[mem.res.monotonic.buffer.ctor]: #mem.res.monotonic.buffer.ctor
|
| 1597 |
-
[mem.res.monotonic.buffer.mem]: #mem.res.monotonic.buffer.mem
|
| 1598 |
-
[mem.res.pool]: #mem.res.pool
|
| 1599 |
-
[mem.res.pool.ctor]: #mem.res.pool.ctor
|
| 1600 |
-
[mem.res.pool.mem]: #mem.res.pool.mem
|
| 1601 |
-
[mem.res.pool.options]: #mem.res.pool.options
|
| 1602 |
-
[mem.res.pool.overview]: #mem.res.pool.overview
|
| 1603 |
-
[mem.res.private]: #mem.res.private
|
| 1604 |
-
[mem.res.public]: #mem.res.public
|
| 1605 |
-
[mem.res.syn]: #mem.res.syn
|
| 1606 |
-
[memory]: #memory
|
| 1607 |
-
[memory.general]: #memory.general
|
| 1608 |
-
[memory.syn]: #memory.syn
|
| 1609 |
-
[meta]: #meta
|
| 1610 |
-
[meta.const.eval]: #meta.const.eval
|
| 1611 |
-
[meta.help]: #meta.help
|
| 1612 |
-
[meta.logical]: #meta.logical
|
| 1613 |
-
[meta.member]: #meta.member
|
| 1614 |
-
[meta.rel]: #meta.rel
|
| 1615 |
-
[meta.rqmts]: #meta.rqmts
|
| 1616 |
-
[meta.trans]: #meta.trans
|
| 1617 |
-
[meta.trans.arr]: #meta.trans.arr
|
| 1618 |
-
[meta.trans.cv]: #meta.trans.cv
|
| 1619 |
-
[meta.trans.other]: #meta.trans.other
|
| 1620 |
-
[meta.trans.ptr]: #meta.trans.ptr
|
| 1621 |
-
[meta.trans.ref]: #meta.trans.ref
|
| 1622 |
-
[meta.trans.sign]: #meta.trans.sign
|
| 1623 |
-
[meta.type.synop]: #meta.type.synop
|
| 1624 |
-
[meta.unary]: #meta.unary
|
| 1625 |
-
[meta.unary.cat]: #meta.unary.cat
|
| 1626 |
-
[meta.unary.comp]: #meta.unary.comp
|
| 1627 |
-
[meta.unary.prop]: #meta.unary.prop
|
| 1628 |
-
[meta.unary.prop.query]: #meta.unary.prop.query
|
| 1629 |
-
[namespace.std]: library.md#namespace.std
|
| 1630 |
-
[new.delete]: support.md#new.delete
|
| 1631 |
-
[optional]: #optional
|
| 1632 |
-
[optional.assign]: #optional.assign
|
| 1633 |
-
[optional.assign.copy]: #optional.assign.copy
|
| 1634 |
-
[optional.assign.copy.templ]: #optional.assign.copy.templ
|
| 1635 |
-
[optional.assign.move]: #optional.assign.move
|
| 1636 |
-
[optional.assign.move.templ]: #optional.assign.move.templ
|
| 1637 |
-
[optional.bad.access]: #optional.bad.access
|
| 1638 |
-
[optional.comp.with.t]: #optional.comp.with.t
|
| 1639 |
-
[optional.ctor]: #optional.ctor
|
| 1640 |
-
[optional.dtor]: #optional.dtor
|
| 1641 |
-
[optional.general]: #optional.general
|
| 1642 |
-
[optional.hash]: #optional.hash
|
| 1643 |
-
[optional.mod]: #optional.mod
|
| 1644 |
-
[optional.nullops]: #optional.nullops
|
| 1645 |
-
[optional.nullopt]: #optional.nullopt
|
| 1646 |
-
[optional.observe]: #optional.observe
|
| 1647 |
-
[optional.optional]: #optional.optional
|
| 1648 |
-
[optional.relops]: #optional.relops
|
| 1649 |
-
[optional.specalg]: #optional.specalg
|
| 1650 |
-
[optional.swap]: #optional.swap
|
| 1651 |
-
[optional.syn]: #optional.syn
|
| 1652 |
-
[ostream.formatted]: input.md#ostream.formatted
|
| 1653 |
-
[out.of.range]: diagnostics.md#out.of.range
|
| 1654 |
-
[over.match.call]: over.md#over.match.call
|
| 1655 |
-
[over.match.class.deduct]: over.md#over.match.class.deduct
|
| 1656 |
-
[overflow.error]: diagnostics.md#overflow.error
|
| 1657 |
-
[pair.astuple]: #pair.astuple
|
| 1658 |
-
[pair.piecewise]: #pair.piecewise
|
| 1659 |
-
[pairs]: #pairs
|
| 1660 |
-
[pairs.general]: #pairs.general
|
| 1661 |
-
[pairs.pair]: #pairs.pair
|
| 1662 |
-
[pairs.spec]: #pairs.spec
|
| 1663 |
-
[pointer.conversion]: #pointer.conversion
|
| 1664 |
-
[pointer.traits]: #pointer.traits
|
| 1665 |
-
[pointer.traits.functions]: #pointer.traits.functions
|
| 1666 |
-
[pointer.traits.optmem]: #pointer.traits.optmem
|
| 1667 |
-
[pointer.traits.types]: #pointer.traits.types
|
| 1668 |
-
[ptr.align]: #ptr.align
|
| 1669 |
-
[range.cmp]: #range.cmp
|
| 1670 |
-
[ratio]: #ratio
|
| 1671 |
-
[ratio.arithmetic]: #ratio.arithmetic
|
| 1672 |
-
[ratio.comparison]: #ratio.comparison
|
| 1673 |
-
[ratio.general]: #ratio.general
|
| 1674 |
-
[ratio.ratio]: #ratio.ratio
|
| 1675 |
-
[ratio.si]: #ratio.si
|
| 1676 |
-
[ratio.syn]: #ratio.syn
|
| 1677 |
-
[refwrap]: #refwrap
|
| 1678 |
-
[refwrap.access]: #refwrap.access
|
| 1679 |
-
[refwrap.assign]: #refwrap.assign
|
| 1680 |
-
[refwrap.const]: #refwrap.const
|
| 1681 |
-
[refwrap.helpers]: #refwrap.helpers
|
| 1682 |
-
[refwrap.invoke]: #refwrap.invoke
|
| 1683 |
-
[res.on.exception.handling]: library.md#res.on.exception.handling
|
| 1684 |
-
[round.style]: support.md#round.style
|
| 1685 |
-
[scoped.adaptor.operators]: #scoped.adaptor.operators
|
| 1686 |
-
[smartptr]: #smartptr
|
| 1687 |
-
[special]: class.md#special
|
| 1688 |
-
[specialized.addressof]: #specialized.addressof
|
| 1689 |
-
[specialized.algorithms]: algorithms.md#specialized.algorithms
|
| 1690 |
-
[stmt.dcl]: stmt.md#stmt.dcl
|
| 1691 |
-
[stmt.return]: stmt.md#stmt.return
|
| 1692 |
-
[support.signal]: support.md#support.signal
|
| 1693 |
-
[swappable.requirements]: library.md#swappable.requirements
|
| 1694 |
-
[temp.deduct]: temp.md#temp.deduct
|
| 1695 |
-
[temp.param]: temp.md#temp.param
|
| 1696 |
-
[temp.type]: temp.md#temp.type
|
| 1697 |
-
[template.bitset]: #template.bitset
|
| 1698 |
-
[time.format]: time.md#time.format
|
| 1699 |
-
[tuple]: #tuple
|
| 1700 |
-
[tuple.apply]: #tuple.apply
|
| 1701 |
-
[tuple.assign]: #tuple.assign
|
| 1702 |
-
[tuple.cnstr]: #tuple.cnstr
|
| 1703 |
-
[tuple.creation]: #tuple.creation
|
| 1704 |
-
[tuple.elem]: #tuple.elem
|
| 1705 |
-
[tuple.general]: #tuple.general
|
| 1706 |
-
[tuple.helper]: #tuple.helper
|
| 1707 |
-
[tuple.rel]: #tuple.rel
|
| 1708 |
-
[tuple.special]: #tuple.special
|
| 1709 |
-
[tuple.swap]: #tuple.swap
|
| 1710 |
-
[tuple.syn]: #tuple.syn
|
| 1711 |
-
[tuple.traits]: #tuple.traits
|
| 1712 |
-
[tuple.tuple]: #tuple.tuple
|
| 1713 |
-
[type.index]: #type.index
|
| 1714 |
-
[type.index.hash]: #type.index.hash
|
| 1715 |
-
[type.index.members]: #type.index.members
|
| 1716 |
-
[type.index.overview]: #type.index.overview
|
| 1717 |
-
[type.index.synopsis]: #type.index.synopsis
|
| 1718 |
-
[unique.ptr]: #unique.ptr
|
| 1719 |
-
[unique.ptr.create]: #unique.ptr.create
|
| 1720 |
-
[unique.ptr.dltr]: #unique.ptr.dltr
|
| 1721 |
-
[unique.ptr.dltr.dflt]: #unique.ptr.dltr.dflt
|
| 1722 |
-
[unique.ptr.dltr.dflt1]: #unique.ptr.dltr.dflt1
|
| 1723 |
-
[unique.ptr.dltr.general]: #unique.ptr.dltr.general
|
| 1724 |
-
[unique.ptr.io]: #unique.ptr.io
|
| 1725 |
-
[unique.ptr.runtime]: #unique.ptr.runtime
|
| 1726 |
-
[unique.ptr.runtime.asgn]: #unique.ptr.runtime.asgn
|
| 1727 |
-
[unique.ptr.runtime.ctor]: #unique.ptr.runtime.ctor
|
| 1728 |
-
[unique.ptr.runtime.modifiers]: #unique.ptr.runtime.modifiers
|
| 1729 |
-
[unique.ptr.runtime.observers]: #unique.ptr.runtime.observers
|
| 1730 |
-
[unique.ptr.single]: #unique.ptr.single
|
| 1731 |
-
[unique.ptr.single.asgn]: #unique.ptr.single.asgn
|
| 1732 |
-
[unique.ptr.single.ctor]: #unique.ptr.single.ctor
|
| 1733 |
-
[unique.ptr.single.dtor]: #unique.ptr.single.dtor
|
| 1734 |
-
[unique.ptr.single.modifiers]: #unique.ptr.single.modifiers
|
| 1735 |
-
[unique.ptr.single.observers]: #unique.ptr.single.observers
|
| 1736 |
-
[unique.ptr.special]: #unique.ptr.special
|
| 1737 |
-
[unord]: containers.md#unord
|
| 1738 |
-
[unord.hash]: #unord.hash
|
| 1739 |
-
[util.dynamic.safety]: #util.dynamic.safety
|
| 1740 |
-
[util.smartptr.enab]: #util.smartptr.enab
|
| 1741 |
-
[util.smartptr.getdeleter]: #util.smartptr.getdeleter
|
| 1742 |
-
[util.smartptr.hash]: #util.smartptr.hash
|
| 1743 |
-
[util.smartptr.ownerless]: #util.smartptr.ownerless
|
| 1744 |
-
[util.smartptr.shared]: #util.smartptr.shared
|
| 1745 |
-
[util.smartptr.shared.assign]: #util.smartptr.shared.assign
|
| 1746 |
-
[util.smartptr.shared.cast]: #util.smartptr.shared.cast
|
| 1747 |
-
[util.smartptr.shared.cmp]: #util.smartptr.shared.cmp
|
| 1748 |
-
[util.smartptr.shared.const]: #util.smartptr.shared.const
|
| 1749 |
-
[util.smartptr.shared.create]: #util.smartptr.shared.create
|
| 1750 |
-
[util.smartptr.shared.dest]: #util.smartptr.shared.dest
|
| 1751 |
-
[util.smartptr.shared.io]: #util.smartptr.shared.io
|
| 1752 |
-
[util.smartptr.shared.mod]: #util.smartptr.shared.mod
|
| 1753 |
-
[util.smartptr.shared.obs]: #util.smartptr.shared.obs
|
| 1754 |
-
[util.smartptr.shared.spec]: #util.smartptr.shared.spec
|
| 1755 |
-
[util.smartptr.weak]: #util.smartptr.weak
|
| 1756 |
-
[util.smartptr.weak.assign]: #util.smartptr.weak.assign
|
| 1757 |
-
[util.smartptr.weak.bad]: #util.smartptr.weak.bad
|
| 1758 |
-
[util.smartptr.weak.const]: #util.smartptr.weak.const
|
| 1759 |
-
[util.smartptr.weak.dest]: #util.smartptr.weak.dest
|
| 1760 |
-
[util.smartptr.weak.mod]: #util.smartptr.weak.mod
|
| 1761 |
-
[util.smartptr.weak.obs]: #util.smartptr.weak.obs
|
| 1762 |
-
[util.smartptr.weak.spec]: #util.smartptr.weak.spec
|
| 1763 |
-
[utilities]: #utilities
|
| 1764 |
-
[utilities.general]: #utilities.general
|
| 1765 |
-
[utilities.summary]: #utilities.summary
|
| 1766 |
-
[utility]: #utility
|
| 1767 |
-
[utility.as.const]: #utility.as.const
|
| 1768 |
-
[utility.exchange]: #utility.exchange
|
| 1769 |
-
[utility.intcmp]: #utility.intcmp
|
| 1770 |
-
[utility.swap]: #utility.swap
|
| 1771 |
-
[utility.syn]: #utility.syn
|
| 1772 |
-
[variant]: #variant
|
| 1773 |
-
[variant.assign]: #variant.assign
|
| 1774 |
-
[variant.bad.access]: #variant.bad.access
|
| 1775 |
-
[variant.ctor]: #variant.ctor
|
| 1776 |
-
[variant.dtor]: #variant.dtor
|
| 1777 |
-
[variant.general]: #variant.general
|
| 1778 |
-
[variant.get]: #variant.get
|
| 1779 |
-
[variant.hash]: #variant.hash
|
| 1780 |
-
[variant.helper]: #variant.helper
|
| 1781 |
-
[variant.mod]: #variant.mod
|
| 1782 |
-
[variant.monostate]: #variant.monostate
|
| 1783 |
-
[variant.monostate.relops]: #variant.monostate.relops
|
| 1784 |
-
[variant.relops]: #variant.relops
|
| 1785 |
-
[variant.specalg]: #variant.specalg
|
| 1786 |
-
[variant.status]: #variant.status
|
| 1787 |
-
[variant.swap]: #variant.swap
|
| 1788 |
-
[variant.syn]: #variant.syn
|
| 1789 |
-
[variant.variant]: #variant.variant
|
| 1790 |
-
[variant.visit]: #variant.visit
|
| 1791 |
-
|
| 1792 |
-
[^1]: `pointer_safety::preferred` might be returned to indicate that a
|
| 1793 |
-
leak detector is running so that the program can avoid spurious leak
|
| 1794 |
-
reports.
|
| 1795 |
-
|
| 1796 |
-
[^2]: Such a type is a function pointer or a class type which has a
|
| 1797 |
-
member `operator()` or a class type which has a conversion to a
|
| 1798 |
-
pointer to function.
|
|
|
|
| 2 |
|
| 3 |
### Header `<format>` synopsis <a id="format.syn">[[format.syn]]</a>
|
| 4 |
|
| 5 |
``` cpp
|
| 6 |
namespace std {
|
| 7 |
+
// [format.context], class template basic_format_context
|
| 8 |
+
template<class Out, class charT> class basic_format_context;
|
| 9 |
+
using format_context = basic_format_context<unspecified, char>;
|
| 10 |
+
using wformat_context = basic_format_context<unspecified, wchar_t>;
|
| 11 |
+
|
| 12 |
+
// [format.args], class template basic_format_args
|
| 13 |
+
template<class Context> class basic_format_args;
|
| 14 |
+
using format_args = basic_format_args<format_context>;
|
| 15 |
+
using wformat_args = basic_format_args<wformat_context>;
|
| 16 |
+
|
| 17 |
+
// [format.fmt.string], class template basic_format_string
|
| 18 |
+
template<class charT, class... Args>
|
| 19 |
+
struct basic_format_string;
|
| 20 |
+
|
| 21 |
+
template<class... Args>
|
| 22 |
+
using format_string = basic_format_string<char, type_identity_t<Args>...>;
|
| 23 |
+
template<class... Args>
|
| 24 |
+
using wformat_string = basic_format_string<wchar_t, type_identity_t<Args>...>;
|
| 25 |
+
|
| 26 |
// [format.functions], formatting functions
|
| 27 |
template<class... Args>
|
| 28 |
+
string format(format_string<Args...> fmt, Args&&... args);
|
| 29 |
template<class... Args>
|
| 30 |
+
wstring format(wformat_string<Args...> fmt, Args&&... args);
|
| 31 |
template<class... Args>
|
| 32 |
+
string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
|
| 33 |
template<class... Args>
|
| 34 |
+
wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
|
| 35 |
|
| 36 |
string vformat(string_view fmt, format_args args);
|
| 37 |
wstring vformat(wstring_view fmt, wformat_args args);
|
| 38 |
string vformat(const locale& loc, string_view fmt, format_args args);
|
| 39 |
wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
|
| 40 |
|
| 41 |
template<class Out, class... Args>
|
| 42 |
+
Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
|
| 43 |
template<class Out, class... Args>
|
| 44 |
+
Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
|
| 45 |
template<class Out, class... Args>
|
| 46 |
+
Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
|
| 47 |
template<class Out, class... Args>
|
| 48 |
+
Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
|
| 49 |
|
| 50 |
template<class Out>
|
| 51 |
+
Out vformat_to(Out out, string_view fmt, format_args args);
|
|
|
|
| 52 |
template<class Out>
|
| 53 |
+
Out vformat_to(Out out, wstring_view fmt, wformat_args args);
|
|
|
|
| 54 |
template<class Out>
|
| 55 |
+
Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
|
|
|
|
| 56 |
template<class Out>
|
| 57 |
+
Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
|
|
|
|
| 58 |
|
| 59 |
template<class Out> struct format_to_n_result {
|
| 60 |
Out out;
|
| 61 |
iter_difference_t<Out> size;
|
| 62 |
};
|
| 63 |
template<class Out, class... Args>
|
| 64 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 65 |
+
format_string<Args...> fmt, Args&&... args);
|
| 66 |
template<class Out, class... Args>
|
| 67 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 68 |
+
wformat_string<Args...> fmt, Args&&... args);
|
| 69 |
template<class Out, class... Args>
|
| 70 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 71 |
+
const locale& loc, format_string<Args...> fmt,
|
| 72 |
+
Args&&... args);
|
| 73 |
template<class Out, class... Args>
|
| 74 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 75 |
+
const locale& loc, wformat_string<Args...> fmt,
|
| 76 |
+
Args&&... args);
|
| 77 |
|
| 78 |
template<class... Args>
|
| 79 |
+
size_t formatted_size(format_string<Args...> fmt, Args&&... args);
|
| 80 |
template<class... Args>
|
| 81 |
+
size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
|
| 82 |
template<class... Args>
|
| 83 |
+
size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
|
| 84 |
template<class... Args>
|
| 85 |
+
size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
|
| 86 |
|
| 87 |
// [format.formatter], formatter
|
| 88 |
template<class T, class charT = char> struct formatter;
|
| 89 |
|
| 90 |
+
// [format.formattable], concept formattable
|
| 91 |
+
template<class T, class charT>
|
| 92 |
+
concept formattable = see below;
|
| 93 |
+
|
| 94 |
+
template<class R, class charT>
|
| 95 |
+
concept const-formattable-range = // exposition only
|
| 96 |
+
ranges::input_range<const R> &&
|
| 97 |
+
formattable<ranges::range_reference_t<const R>, charT>;
|
| 98 |
+
|
| 99 |
+
template<class R, class charT>
|
| 100 |
+
using fmt-maybe-const = // exposition only
|
| 101 |
+
conditional_t<const-formattable-range<R, charT>, const R, R>;
|
| 102 |
+
|
| 103 |
// [format.parse.ctx], class template basic_format_parse_context
|
| 104 |
template<class charT> class basic_format_parse_context;
|
| 105 |
using format_parse_context = basic_format_parse_context<char>;
|
| 106 |
using wformat_parse_context = basic_format_parse_context<wchar_t>;
|
| 107 |
|
| 108 |
+
// [format.range], formatting of ranges
|
| 109 |
+
// [format.range.fmtkind], variable template format_kind
|
| 110 |
+
enum class range_format {
|
| 111 |
+
disabled,
|
| 112 |
+
map,
|
| 113 |
+
set,
|
| 114 |
+
sequence,
|
| 115 |
+
string,
|
| 116 |
+
debug_string
|
| 117 |
+
};
|
| 118 |
+
|
| 119 |
+
template<class R>
|
| 120 |
+
constexpr unspecified format_kind = unspecified;
|
| 121 |
+
|
| 122 |
+
template<ranges::input_range R>
|
| 123 |
+
requires same_as<R, remove_cvref_t<R>>
|
| 124 |
+
constexpr range_format format_kind<R> = see below;
|
| 125 |
+
|
| 126 |
+
// [format.range.formatter], class template range_formatter
|
| 127 |
+
template<class T, class charT = char>
|
| 128 |
+
requires same_as<remove_cvref_t<T>, T> && formattable<T, charT>
|
| 129 |
+
class range_formatter;
|
| 130 |
+
|
| 131 |
+
// [format.range.fmtdef], class template range-default-formatter
|
| 132 |
+
template<range_format K, ranges::input_range R, class charT>
|
| 133 |
+
struct range-default-formatter; // exposition only
|
| 134 |
+
|
| 135 |
+
// [format.range.fmtmap], [format.range.fmtset], [format.range.fmtstr], specializations for maps, sets, and strings
|
| 136 |
+
template<ranges::input_range R, class charT>
|
| 137 |
+
requires (format_kind<R> != range_format::disabled) &&
|
| 138 |
+
formattable<ranges::range_reference_t<R>, charT>
|
| 139 |
+
struct formatter<R, charT> : range-default-formatter<format_kind<R>, R, charT> { };
|
| 140 |
|
| 141 |
// [format.arguments], arguments
|
| 142 |
// [format.arg], class template basic_format_arg
|
| 143 |
template<class Context> class basic_format_arg;
|
| 144 |
|
| 145 |
template<class Visitor, class Context>
|
| 146 |
+
decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
|
| 147 |
|
| 148 |
// [format.arg.store], class template format-arg-store
|
| 149 |
+
template<class Context, class... Args> class format-arg-store; // exposition only
|
| 150 |
|
| 151 |
template<class Context = format_context, class... Args>
|
| 152 |
format-arg-store<Context, Args...>
|
| 153 |
+
make_format_args(Args&&... fmt_args);
|
| 154 |
template<class... Args>
|
| 155 |
format-arg-store<wformat_context, Args...>
|
| 156 |
+
make_wformat_args(Args&&... args);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 157 |
|
| 158 |
// [format.error], class format_error
|
| 159 |
class format_error;
|
| 160 |
}
|
| 161 |
```
|
|
|
|
| 247 |
|
| 248 |
``` cpp
|
| 249 |
string s0 = format("{} to {}", "a", "b"); // OK, automatic indexing
|
| 250 |
string s1 = format("{1} to {0}", "a", "b"); // OK, manual indexing
|
| 251 |
string s2 = format("{0} to {}", "a", "b"); // not a format string (mixing automatic and manual indexing),
|
| 252 |
+
// ill-formed
|
| 253 |
string s3 = format("{} to {1}", "a", "b"); // not a format string (mixing automatic and manual indexing),
|
| 254 |
+
// ill-formed
|
| 255 |
```
|
| 256 |
|
| 257 |
— *end example*]
|
| 258 |
|
| 259 |
The *format-spec* field contains *format specifications* that define how
|
|
|
|
| 275 |
|
| 276 |
— *end example*]
|
| 277 |
|
| 278 |
#### Standard format specifiers <a id="format.string.std">[[format.string.std]]</a>
|
| 279 |
|
| 280 |
+
Each `formatter` specialization described in [[format.formatter.spec]]
|
| 281 |
for fundamental and string types interprets *format-spec* as a
|
| 282 |
*std-format-spec*.
|
| 283 |
|
| 284 |
[*Note 1*: The format specification can be used to specify such details
|
| 285 |
+
as minimum field width, alignment, padding, and decimal precision. Some
|
| 286 |
+
of the formatting options are only supported for arithmetic
|
| 287 |
types. — *end note*]
|
| 288 |
|
| 289 |
The syntax of format specifications is as follows:
|
| 290 |
|
| 291 |
``` bnf
|
|
|
|
| 325 |
'.' '{' arg-idₒₚₜ '}'
|
| 326 |
```
|
| 327 |
|
| 328 |
``` bnf
|
| 329 |
type one of
|
| 330 |
+
'a A b B c d e E f F g G o p s x X ?'
|
| 331 |
```
|
| 332 |
|
| 333 |
+
Field widths are specified in *field width units*; the number of column
|
| 334 |
+
positions required to display a sequence of characters in a terminal.
|
| 335 |
+
The *minimum field width* is the number of field width units a
|
| 336 |
+
replacement field minimally requires of the formatted sequence of
|
| 337 |
+
characters produced for a format argument. The *estimated field width*
|
| 338 |
+
is the number of field width units that are required for the formatted
|
| 339 |
+
sequence of characters produced for a format argument independent of the
|
| 340 |
+
effects of the *width* option. The *padding width* is the greater of `0`
|
| 341 |
+
and the difference of the minimum field width and the estimated field
|
| 342 |
+
width.
|
| 343 |
+
|
| 344 |
+
[*Note 2*: The POSIX `wcswidth` function is an example of a function
|
| 345 |
+
that, given a string, returns the number of column positions required by
|
| 346 |
+
a terminal to display the string. — *end note*]
|
| 347 |
+
|
| 348 |
+
The *fill character* is the character denoted by the *fill* option or,
|
| 349 |
+
if the *fill* option is absent, the space character. For a format
|
| 350 |
+
specification in UTF-8, UTF-16, or UTF-32, the fill character
|
| 351 |
+
corresponds to a single Unicode scalar value.
|
| 352 |
+
|
| 353 |
+
[*Note 3*: The presence of a *fill* option is signaled by the character
|
| 354 |
following it, which must be one of the alignment options. If the second
|
| 355 |
character of *std-format-spec* is not a valid alignment option, then it
|
| 356 |
+
is assumed that the *fill* and *align* options are both
|
| 357 |
absent. — *end note*]
|
| 358 |
|
| 359 |
+
The *align* option applies to all argument types. The meaning of the
|
| 360 |
various alignment options is as specified in [[format.align]].
|
| 361 |
|
| 362 |
[*Example 1*:
|
| 363 |
|
| 364 |
``` cpp
|
|
|
|
| 368 |
string s2 = format("{:*<6}", 'x'); // value of s2 is "x*****"
|
| 369 |
string s3 = format("{:*>6}", 'x'); // value of s3 is "*****x"
|
| 370 |
string s4 = format("{:*^6}", 'x'); // value of s4 is "**x***"
|
| 371 |
string s5 = format("{:6d}", c); // value of s5 is "\ \ \ 120"
|
| 372 |
string s6 = format("{:6}", true); // value of s6 is "true\ \ "
|
| 373 |
+
string s7 = format("{:*<6.3}", "123456"); // value of s7 is "123***"
|
| 374 |
+
string s8 = format("{:02}", 1234); // value of s8 is "1234"
|
| 375 |
+
string s9 = format("{:*<}", "12"); // value of s9 is "12"
|
| 376 |
+
string sA = format("{:*<6}", "12345678"); // value of sA is "12345678"
|
| 377 |
```
|
| 378 |
|
| 379 |
— *end example*]
|
| 380 |
|
| 381 |
+
[*Note 4*: The *fill*, *align*, and `0` options have no effect when the
|
| 382 |
+
minimum field width is not greater than the estimated field width
|
| 383 |
+
because padding width is `0` in that case. Since fill characters are
|
| 384 |
+
assumed to have a field width of `1`, use of a character with a
|
| 385 |
+
different field width can produce misaligned output. The
|
| 386 |
+
U+1f921 (clown face) character has a field width of `2`. The examples
|
| 387 |
+
above that include that character illustrate the effect of the field
|
| 388 |
+
width when that character is used as a fill character as opposed to when
|
| 389 |
+
it is used as a formatting argument. — *end note*]
|
| 390 |
|
| 391 |
**Table: Meaning of align options** <a id="format.align">[format.align]</a>
|
| 392 |
|
| 393 |
| Option | Meaning |
|
| 394 |
+
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
| 395 |
+
| `<` | Forces the formatted argument to be aligned to the start of the field by inserting $n$ fill characters after the formatted argument where $n$ is the padding width. This is the default for non-arithmetic non-pointer types, `charT`, and `bool`, unless an integer presentation type is specified. |
|
| 396 |
+
| % `>` | Forces the formatted argument to be aligned to the end of the field by inserting $n$ fill characters before the formatted argument where $n$ is the padding width. This is the default for arithmetic types other than `charT` and `bool`, pointer types, or when an integer presentation type is specified. |
|
| 397 |
+
| % `^` | Forces the formatted argument to be centered within the field by inserting $\bigl\lfloor \frac{n}{2} \bigr\rfloor$ fill characters before and $\bigl\lceil \frac{n}{2} \bigr\rceil$ fill characters after the formatted argument, where $n$ is the padding width. |
|
| 398 |
|
| 399 |
|
| 400 |
The *sign* option is only valid for arithmetic types other than `charT`
|
| 401 |
and `bool` or when an integer presentation type is specified. The
|
| 402 |
meaning of the various options is as specified in [[format.sign]].
|
| 403 |
|
| 404 |
+
**Table: Meaning of sign options** <a id="format.sign">[format.sign]</a>
|
| 405 |
+
|
| 406 |
+
| Option | Meaning |
|
| 407 |
+
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
| 408 |
+
| `+` | Indicates that a sign should be used for both non-negative and negative numbers. The `+` sign is inserted before the output of `to_chars` for non-negative numbers other than negative zero. *For negative numbers and negative zero the output of `to_chars` will already contain the sign so no additional transformation is performed.* |
|
| 409 |
+
| % `-` | Indicates that a sign should be used for negative numbers and negative zero only (this is the default behavior). |
|
| 410 |
+
| % space | Indicates that a leading space should be used for non-negative numbers other than negative zero, and a minus sign for negative numbers and negative zero. |
|
| 411 |
+
|
| 412 |
|
| 413 |
The *sign* option applies to floating-point infinity and NaN.
|
| 414 |
|
| 415 |
[*Example 2*:
|
| 416 |
|
|
|
|
| 436 |
contain a decimal-point character, even if no digits follow it.
|
| 437 |
Normally, a decimal-point character appears in the result of these
|
| 438 |
conversions only if a digit follows it. In addition, for `g` and `G`
|
| 439 |
conversions, trailing zeros are not removed from the result.
|
| 440 |
|
| 441 |
+
The `0` option is valid for arithmetic types other than `charT` and
|
| 442 |
+
`bool` or when an integer presentation type is specified. For formatting
|
| 443 |
+
arguments that have a value other than an infinity or a NaN, this option
|
| 444 |
+
pads the formatted argument by inserting the `0` character n times
|
| 445 |
+
following the sign or base prefix indicators (if any) where n is `0` if
|
| 446 |
+
the *align* option is present and is the padding width otherwise.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 447 |
|
| 448 |
[*Example 3*:
|
| 449 |
|
| 450 |
``` cpp
|
| 451 |
char c = 120;
|
| 452 |
string s1 = format("{:+06d}", c); // value of s1 is "+00120"
|
| 453 |
string s2 = format("{:#06x}", 0xa); // value of s2 is "0x000a"
|
| 454 |
+
string s3 = format("{:<06}", -42); // value of s3 is "-42\ \ \ " (0 has no effect)
|
| 455 |
+
string s4 = format("{:06}", inf); // value of s4 is "\ \ \ inf" (0 has no effect)
|
| 456 |
```
|
| 457 |
|
| 458 |
— *end example*]
|
| 459 |
|
| 460 |
+
The *width* option specifies the minimum field width. If the *width*
|
| 461 |
+
option is absent, the minimum field width is `0`.
|
| 462 |
+
|
| 463 |
+
If `{ \opt{arg-id} }` is used in a *width* or *precision* option, the
|
| 464 |
+
value of the corresponding formatting argument is used as the value of
|
| 465 |
+
the option. If the corresponding formatting argument is not of standard
|
| 466 |
+
signed or unsigned integer type, or its value is negative, an exception
|
| 467 |
+
of type `format_error` is thrown.
|
| 468 |
+
|
| 469 |
+
If *positive-integer* is used in a *width* option, the value of the
|
| 470 |
+
*positive-integer* is interpreted as a decimal integer and used as the
|
| 471 |
+
value of the option.
|
| 472 |
+
|
| 473 |
+
For the purposes of width computation, a string is assumed to be in a
|
| 474 |
+
locale-independent, *implementation-defined* encoding. Implementations
|
| 475 |
+
should use either UTF-8, UTF-16, or UTF-32, on platforms capable of
|
| 476 |
+
displaying Unicode text in a terminal.
|
| 477 |
+
|
| 478 |
+
[*Note 5*:
|
| 479 |
+
|
| 480 |
+
This is the case for Windows[^2]
|
| 481 |
+
|
| 482 |
+
-based and many POSIX-based operating systems.
|
| 483 |
+
|
| 484 |
+
— *end note*]
|
| 485 |
+
|
| 486 |
+
For a sequence of characters in UTF-8, UTF-16, or UTF-32, an
|
| 487 |
+
implementation should use as its field width the sum of the field widths
|
| 488 |
+
of the first code point of each extended grapheme cluster. Extended
|
| 489 |
+
grapheme clusters are defined by UAX \#29 of the Unicode Standard. The
|
| 490 |
+
following code points have a field width of 2:
|
| 491 |
+
|
| 492 |
+
- any code point with the `East_Asian_Width="W"` or
|
| 493 |
+
`East_Asian_Width="F"` Derived Extracted Property as described by UAX
|
| 494 |
+
\#44 of the Unicode Standard
|
| 495 |
+
- `U+4dc0` – `U+4dff` (Yijing Hexagram Symbols)
|
| 496 |
+
- `U+1f300` – `U+1f5ff` (Miscellaneous Symbols and Pictographs)
|
| 497 |
+
- `U+1f900` – `U+1f9ff` (Supplemental Symbols and Pictographs)
|
| 498 |
+
|
| 499 |
+
The field width of all other code points is 1.
|
| 500 |
+
|
| 501 |
+
For a sequence of characters in neither UTF-8, UTF-16, nor UTF-32, the
|
| 502 |
+
field width is unspecified.
|
| 503 |
+
|
| 504 |
+
The *precision* option is valid for floating-point and string types. For
|
| 505 |
+
floating-point types, the value of this option specifies the precision
|
| 506 |
+
to be used for the floating-point presentation type. For string types,
|
| 507 |
+
this option specifies the longest prefix of the formatted argument to be
|
| 508 |
+
included in the replacement field such that the field width of the
|
| 509 |
+
prefix is no greater than the value of this option.
|
| 510 |
+
|
| 511 |
+
If *nonnegative-integer* is used in a *precision* option, the value of
|
| 512 |
+
the decimal integer is used as the value of the option.
|
| 513 |
|
| 514 |
When the `L` option is used, the form used for the conversion is called
|
| 515 |
the *locale-specific form*. The `L` option is only valid for arithmetic
|
| 516 |
types, and its effect depends upon the type.
|
| 517 |
|
|
|
|
| 532 |
[[format.type.string]].
|
| 533 |
|
| 534 |
**Table: Meaning of type options for strings** <a id="format.type.string">[format.type.string]</a>
|
| 535 |
|
| 536 |
| Type | Meaning |
|
| 537 |
+
| --------- | ------------------------------------------------------------------ |
|
| 538 |
| none, `s` | Copies the string to the output. |
|
| 539 |
+
| % `?` | Copies the escaped string [[format.string.escaped]] to the output. |
|
| 540 |
|
| 541 |
|
| 542 |
The meaning of some non-string presentation types is defined in terms of
|
| 543 |
a call to `to_chars`. In such cases, let \[`first`, `last`) be a range
|
| 544 |
large enough to hold the `to_chars` output and `value` be the formatting
|
| 545 |
argument value. Formatting is done as if by calling `to_chars` as
|
| 546 |
specified and copying the output through the output iterator of the
|
| 547 |
format context.
|
| 548 |
|
| 549 |
+
[*Note 6*: Additional padding and adjustments are performed prior to
|
| 550 |
copying the output through the output iterator as specified by the
|
| 551 |
format specifiers. — *end note*]
|
| 552 |
|
| 553 |
The available integer presentation types for integral types other than
|
| 554 |
`bool` and `charT` are specified in [[format.type.int]].
|
|
|
|
| 557 |
|
| 558 |
``` cpp
|
| 559 |
string s0 = format("{}", 42); // value of s0 is "42"
|
| 560 |
string s1 = format("{0:b} {0:d} {0:o} {0:x}", 42); // value of s1 is "101010 42 52 2a"
|
| 561 |
string s2 = format("{0:#x} {0:#X}", 42); // value of s2 is "0x2a 0X2A"
|
| 562 |
+
string s3 = format("{:L}", 1234); // value of s3 can be "1,234"
|
| 563 |
// (depending on the locale)
|
| 564 |
```
|
| 565 |
|
| 566 |
— *end example*]
|
| 567 |
|
| 568 |
+
**Table: Meaning of type options for integer types** <a id="format.type.int">[format.type.int]</a>
|
| 569 |
+
|
| 570 |
+
| Type | Meaning |
|
| 571 |
+
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 572 |
+
| `b` | `to_chars(first, last, value, 2)`; \indextext{base prefix}% the base prefix is `0b`. |
|
| 573 |
+
| % `B` | The same as `b`, except that \indextext{base prefix}% the base prefix is `0B`. |
|
| 574 |
+
| % `c` | Copies the character `static_cast<charT>(value)` to the output. Throws `format_error` if `value` is not in the range of representable values for `charT`. |
|
| 575 |
+
| % `d` | `to_chars(first, last, value)`. |
|
| 576 |
+
| % `o` | `to_chars(first, last, value, 8)`; \indextext{base prefix}% the base prefix is `0` if `value` is nonzero and is empty otherwise. |
|
| 577 |
+
| % `x` | `to_chars(first, last, value, 16)`; \indextext{base prefix}% the base prefix is `0x`. |
|
| 578 |
+
| % `X` | The same as `x`, except that it uses uppercase letters for digits above 9 and \indextext{base prefix}% the base prefix is `0X`. |
|
| 579 |
+
| % none | The same as `d`. *If the formatting argument type is `charT` or `bool`, the default is instead `c` or `s`, respectively.* |
|
| 580 |
+
|
| 581 |
|
| 582 |
The available `charT` presentation types are specified in
|
| 583 |
[[format.type.char]].
|
| 584 |
|
| 585 |
**Table: Meaning of type options for `charT`** <a id="format.type.char">[format.type.char]</a>
|
| 586 |
|
| 587 |
| Type | Meaning |
|
| 588 |
+
| ------------------------------ | --------------------------------------------------------------------- |
|
| 589 |
| none, `c` | Copies the character to the output. |
|
| 590 |
| % `b`, `B`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]]. |
|
| 591 |
+
| % `?` | Copies the escaped character [[format.string.escaped]] to the output. |
|
| 592 |
|
| 593 |
|
| 594 |
The available `bool` presentation types are specified in
|
| 595 |
[[format.type.bool]].
|
| 596 |
|
| 597 |
**Table: Meaning of type options for `bool`** <a id="format.type.bool">[format.type.bool]</a>
|
| 598 |
|
| 599 |
| Type | Meaning |
|
| 600 |
+
| ------------------------------ | -------------------------------------------------------------------------------------- |
|
| 601 |
| none, `s` | Copies textual representation, either `true` or `false`, to the output. |
|
| 602 |
+
| % `b`, `B`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]] for the value `static_cast<unsigned char>(value)`. |
|
| 603 |
|
| 604 |
|
| 605 |
The available floating-point presentation types and their meanings for
|
| 606 |
values other than infinity and NaN are specified in
|
| 607 |
[[format.type.float]]. For lower-case presentation types, infinity and
|
| 608 |
NaN are formatted as `inf` and `nan`, respectively. For upper-case
|
| 609 |
presentation types, infinity and NaN are formatted as `INF` and `NAN`,
|
| 610 |
respectively.
|
| 611 |
|
| 612 |
+
[*Note 7*: In either case, a sign is included if indicated by the
|
| 613 |
*sign* option. — *end note*]
|
| 614 |
|
| 615 |
**Table: Meaning of type options for floating-point types** <a id="format.type.float">[format.type.float]</a>
|
| 616 |
|
| 617 |
| Type | Meaning |
|
|
|
|
| 627 |
|
| 628 |
|
| 629 |
The available pointer presentation types and their mapping to `to_chars`
|
| 630 |
are specified in [[format.type.ptr]].
|
| 631 |
|
| 632 |
+
[*Note 8*: Pointer presentation types also apply to
|
| 633 |
`nullptr_t`. — *end note*]
|
| 634 |
|
| 635 |
**Table: Meaning of type options for pointer types** <a id="format.type.ptr">[format.type.ptr]</a>
|
| 636 |
|
| 637 |
| Type | Meaning |
|
| 638 |
+
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 639 |
+
| none, `p` | If `uintptr_t` is defined, \begin{codeblock} to_chars(first, last, reinterpret_cast<uintptr_t>(value), 16) \end{codeblock} with the prefix `0x` inserted immediately before the output of `to_chars`; otherwise, implementation-defined. |
|
| 640 |
|
| 641 |
|
| 642 |
### Error reporting <a id="format.err.report">[[format.err.report]]</a>
|
| 643 |
|
| 644 |
Formatting functions throw `format_error` if an argument `fmt` is passed
|
| 645 |
that is not a format string for `args`. They propagate exceptions thrown
|
| 646 |
by operations of `formatter` specializations and iterators. Failure to
|
| 647 |
allocate storage is reported by throwing an exception as described in
|
| 648 |
[[res.on.exception.handling]].
|
| 649 |
|
| 650 |
+
### Class template `basic_format_string` <a id="format.fmt.string">[[format.fmt.string]]</a>
|
| 651 |
+
|
| 652 |
+
``` cpp
|
| 653 |
+
namespace std {
|
| 654 |
+
template<class charT, class... Args>
|
| 655 |
+
struct basic_format_string {
|
| 656 |
+
private:
|
| 657 |
+
basic_string_view<charT> str; // exposition only
|
| 658 |
+
|
| 659 |
+
public:
|
| 660 |
+
template<class T> consteval basic_format_string(const T& s);
|
| 661 |
+
|
| 662 |
+
constexpr basic_string_view<charT> get() const noexcept { return str; }
|
| 663 |
+
};
|
| 664 |
+
}
|
| 665 |
+
```
|
| 666 |
+
|
| 667 |
+
``` cpp
|
| 668 |
+
template<class T> consteval basic_format_string(const T& s);
|
| 669 |
+
```
|
| 670 |
+
|
| 671 |
+
*Constraints:* `const T&` models
|
| 672 |
+
`convertible_to<basic_string_view<charT>>`.
|
| 673 |
+
|
| 674 |
+
*Effects:* Direct-non-list-initializes *str* with `s`.
|
| 675 |
+
|
| 676 |
+
*Remarks:* A call to this function is not a core constant
|
| 677 |
+
expression [[expr.const]] unless there exist `args` of types `Args` such
|
| 678 |
+
that *str* is a format string for `args`.
|
| 679 |
+
|
| 680 |
### Formatting functions <a id="format.functions">[[format.functions]]</a>
|
| 681 |
|
| 682 |
In the description of the functions, operator `+` is used for some of
|
| 683 |
the iterator categories for which it does not have to be defined. In
|
| 684 |
these cases the semantics of `a + n` are the same as in
|
| 685 |
[[algorithms.requirements]].
|
| 686 |
|
| 687 |
``` cpp
|
| 688 |
template<class... Args>
|
| 689 |
+
string format(format_string<Args...> fmt, Args&&... args);
|
| 690 |
```
|
| 691 |
|
| 692 |
*Effects:* Equivalent to:
|
| 693 |
|
| 694 |
``` cpp
|
| 695 |
+
return vformat(fmt.str, make_format_args(args...));
|
| 696 |
```
|
| 697 |
|
| 698 |
``` cpp
|
| 699 |
template<class... Args>
|
| 700 |
+
wstring format(wformat_string<Args...> fmt, Args&&... args);
|
| 701 |
```
|
| 702 |
|
| 703 |
*Effects:* Equivalent to:
|
| 704 |
|
| 705 |
``` cpp
|
| 706 |
+
return vformat(fmt.str, make_wformat_args(args...));
|
| 707 |
```
|
| 708 |
|
| 709 |
``` cpp
|
| 710 |
template<class... Args>
|
| 711 |
+
string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
|
| 712 |
```
|
| 713 |
|
| 714 |
*Effects:* Equivalent to:
|
| 715 |
|
| 716 |
``` cpp
|
| 717 |
+
return vformat(loc, fmt.str, make_format_args(args...));
|
| 718 |
```
|
| 719 |
|
| 720 |
``` cpp
|
| 721 |
template<class... Args>
|
| 722 |
+
wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
|
| 723 |
```
|
| 724 |
|
| 725 |
*Effects:* Equivalent to:
|
| 726 |
|
| 727 |
``` cpp
|
| 728 |
+
return vformat(loc, fmt.str, make_wformat_args(args...));
|
| 729 |
```
|
| 730 |
|
| 731 |
``` cpp
|
| 732 |
string vformat(string_view fmt, format_args args);
|
| 733 |
wstring vformat(wstring_view fmt, wformat_args args);
|
|
|
|
| 742 |
|
| 743 |
*Throws:* As specified in [[format.err.report]].
|
| 744 |
|
| 745 |
``` cpp
|
| 746 |
template<class Out, class... Args>
|
| 747 |
+
Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
|
| 748 |
+
```
|
| 749 |
+
|
| 750 |
+
*Effects:* Equivalent to:
|
| 751 |
+
|
| 752 |
+
``` cpp
|
| 753 |
+
return vformat_to(std::move(out), fmt.str, make_format_args(args...));
|
| 754 |
+
```
|
| 755 |
+
|
| 756 |
+
``` cpp
|
| 757 |
template<class Out, class... Args>
|
| 758 |
+
Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
|
| 759 |
```
|
| 760 |
|
| 761 |
*Effects:* Equivalent to:
|
| 762 |
|
| 763 |
``` cpp
|
| 764 |
+
return vformat_to(std::move(out), fmt.str, make_wformat_args(args...));
|
|
|
|
| 765 |
```
|
| 766 |
|
| 767 |
``` cpp
|
| 768 |
template<class Out, class... Args>
|
| 769 |
+
Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args);
|
| 770 |
+
```
|
| 771 |
+
|
| 772 |
+
*Effects:* Equivalent to:
|
| 773 |
+
|
| 774 |
+
``` cpp
|
| 775 |
+
return vformat_to(std::move(out), loc, fmt.str, make_format_args(args...));
|
| 776 |
+
```
|
| 777 |
+
|
| 778 |
+
``` cpp
|
| 779 |
template<class Out, class... Args>
|
| 780 |
+
Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
|
| 781 |
```
|
| 782 |
|
| 783 |
*Effects:* Equivalent to:
|
| 784 |
|
| 785 |
``` cpp
|
| 786 |
+
return vformat_to(std::move(out), loc, fmt.str, make_wformat_args(args...));
|
|
|
|
| 787 |
```
|
| 788 |
|
| 789 |
``` cpp
|
| 790 |
template<class Out>
|
| 791 |
+
Out vformat_to(Out out, string_view fmt, format_args args);
|
|
|
|
| 792 |
template<class Out>
|
| 793 |
+
Out vformat_to(Out out, wstring_view fmt, wformat_args args);
|
|
|
|
| 794 |
template<class Out>
|
| 795 |
+
Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
|
|
|
|
| 796 |
template<class Out>
|
| 797 |
+
Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
|
|
|
|
| 798 |
```
|
| 799 |
|
| 800 |
Let `charT` be `decltype(fmt)::value_type`.
|
| 801 |
|
| 802 |
*Constraints:* `Out` satisfies `output_iterator<const charT&>`.
|
| 803 |
|
| 804 |
*Preconditions:* `Out` models `output_iterator<const charT&>`.
|
| 805 |
|
| 806 |
*Effects:* Places the character representation of formatting the
|
| 807 |
arguments provided by `args`, formatted according to the specifications
|
| 808 |
+
given in `fmt`, into the range \[`out`, `out + N`), where `N` is the
|
| 809 |
+
number of characters in that character representation. If present, `loc`
|
| 810 |
+
is used for locale-specific formatting.
|
|
|
|
|
|
|
| 811 |
|
| 812 |
*Returns:* `out + N`.
|
| 813 |
|
| 814 |
*Throws:* As specified in [[format.err.report]].
|
| 815 |
|
| 816 |
``` cpp
|
| 817 |
template<class Out, class... Args>
|
| 818 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 819 |
+
format_string<Args...> fmt, Args&&... args);
|
| 820 |
template<class Out, class... Args>
|
| 821 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 822 |
+
wformat_string<Args...> fmt, Args&&... args);
|
| 823 |
template<class Out, class... Args>
|
| 824 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 825 |
+
const locale& loc, format_string<Args...> fmt,
|
| 826 |
+
Args&&... args);
|
| 827 |
template<class Out, class... Args>
|
| 828 |
format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
|
| 829 |
+
const locale& loc, wformat_string<Args...> fmt,
|
| 830 |
+
Args&&... args);
|
| 831 |
```
|
| 832 |
|
| 833 |
Let
|
| 834 |
|
| 835 |
+
- `charT` be `decltype(fmt.`*`str`*`)::value_type`,
|
| 836 |
- `N` be `formatted_size(fmt, args...)` for the functions without a
|
| 837 |
`loc` parameter and `formatted_size(loc, fmt, args...)` for the
|
| 838 |
functions with a `loc` parameter, and
|
| 839 |
- `M` be `clamp(n, 0, N)`.
|
| 840 |
|
| 841 |
*Constraints:* `Out` satisfies `output_iterator<const charT&>`.
|
| 842 |
|
| 843 |
*Preconditions:* `Out` models `output_iterator<const charT&>`, and
|
| 844 |
+
`formatter<``remove_cvref_t<Tᵢ``>, charT>` meets the
|
| 845 |
requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
|
| 846 |
|
| 847 |
*Effects:* Places the first `M` characters of the character
|
| 848 |
representation of formatting the arguments provided by `args`, formatted
|
| 849 |
according to the specifications given in `fmt`, into the range \[`out`,
|
|
|
|
| 853 |
|
| 854 |
*Throws:* As specified in [[format.err.report]].
|
| 855 |
|
| 856 |
``` cpp
|
| 857 |
template<class... Args>
|
| 858 |
+
size_t formatted_size(format_string<Args...> fmt, Args&&... args);
|
| 859 |
template<class... Args>
|
| 860 |
+
size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
|
| 861 |
template<class... Args>
|
| 862 |
+
size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
|
| 863 |
template<class... Args>
|
| 864 |
+
size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
|
| 865 |
```
|
| 866 |
|
| 867 |
+
Let `charT` be `decltype(fmt.`*`str`*`)::value_type`.
|
| 868 |
|
| 869 |
+
*Preconditions:* `formatter<``remove_cvref_t<Tᵢ``>, charT>` meets the
|
| 870 |
requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
|
| 871 |
|
| 872 |
*Returns:* The number of characters in the character representation of
|
| 873 |
formatting arguments `args` formatted according to specifications given
|
| 874 |
in `fmt`. If present, `loc` is used for locale-specific formatting.
|
|
|
|
| 877 |
|
| 878 |
### Formatter <a id="format.formatter">[[format.formatter]]</a>
|
| 879 |
|
| 880 |
#### Formatter requirements <a id="formatter.requirements">[[formatter.requirements]]</a>
|
| 881 |
|
| 882 |
+
A type `F` meets the requirements if it meets the
|
| 883 |
|
|
|
|
| 884 |
- *Cpp17DefaultConstructible* ([[cpp17.defaultconstructible]]),
|
| 885 |
- *Cpp17CopyConstructible* ([[cpp17.copyconstructible]]),
|
| 886 |
+
- *Cpp17CopyAssignable* ([[cpp17.copyassignable]]),
|
| 887 |
+
- *Cpp17Swappable* [[swappable.requirements]], and
|
| 888 |
- *Cpp17Destructible* ([[cpp17.destructible]])
|
| 889 |
|
| 890 |
+
requirements, and the expressions shown in [[formatter.basic]] are valid
|
| 891 |
+
and have the indicated semantics.
|
| 892 |
+
|
| 893 |
+
A type `F` meets the requirements if it meets the requirements and the
|
| 894 |
+
expressions shown in [[formatter]] are valid and have the indicated
|
| 895 |
+
semantics.
|
| 896 |
|
| 897 |
Given character type `charT`, output iterator type `Out`, and formatting
|
| 898 |
+
argument type `T`, in [[formatter.basic]] and [[formatter]]:
|
| 899 |
|
| 900 |
+
- `f` is a value of type (possibly const) `F`,
|
| 901 |
+
- `g` is an lvalue of type `F`,
|
| 902 |
- `u` is an lvalue of type `T`,
|
| 903 |
- `t` is a value of a type convertible to (possibly const) `T`,
|
| 904 |
- `PC` is `basic_format_parse_context<charT>`,
|
| 905 |
- `FC` is `basic_format_context<Out, charT>`,
|
| 906 |
- `pc` is an lvalue of type `PC`, and
|
|
|
|
| 912 |
or `*pc.begin() == '}'`.
|
| 913 |
|
| 914 |
[*Note 1*: This allows formatters to emit meaningful error
|
| 915 |
messages. — *end note*]
|
| 916 |
|
| 917 |
+
**Table: \newoldconcept{Formatter} requirements** <a id="formatter">[formatter]</a>
|
| 918 |
+
|
| 919 |
+
| Expression | Return type | Requirement |
|
| 920 |
+
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 921 |
+
| `f.format(t, fc)` | `FC::iterator` | Formats `t` according to the specifiers stored in `*this`, writes the output to `fc.out()`, and returns an iterator past the end of the output range. The output shall only depend on `t`, `fc.locale()`, `fc.arg(n)` for any value `n` of type `size_t`, and the range {[}`pc.begin()`, `pc.end()`{)} from the last call to `f.parse(pc)`. |
|
| 922 |
+
| `f.format(u, fc)` | `FC::iterator` | As above, but does not modify `u`. |
|
| 923 |
+
|
| 924 |
+
|
| 925 |
+
#### Concept <a id="format.formattable">[[format.formattable]]</a>
|
| 926 |
+
|
| 927 |
+
Let `fmt-iter-for<charT>` be an unspecified type that models
|
| 928 |
+
`output_iterator<const charT&>` [[iterator.concept.output]].
|
| 929 |
+
|
| 930 |
+
``` cpp
|
| 931 |
+
template<class T, class Context,
|
| 932 |
+
class Formatter = typename Context::template formatter_type<remove_const_t<T>>>
|
| 933 |
+
concept formattable-with = // exposition only
|
| 934 |
+
semiregular<Formatter> &&
|
| 935 |
+
requires(Formatter& f, const Formatter& cf, T&& t, Context fc,
|
| 936 |
+
basic_format_parse_context<typename Context::char_type> pc)
|
| 937 |
+
{
|
| 938 |
+
{ f.parse(pc) } -> same_as<typename decltype(pc)::iterator>;
|
| 939 |
+
{ cf.format(t, fc) } -> same_as<typename Context::iterator>;
|
| 940 |
+
};
|
| 941 |
+
|
| 942 |
+
template<class T, class charT>
|
| 943 |
+
concept formattable =
|
| 944 |
+
formattable-with<remove_reference_t<T>, basic_format_context<fmt-iter-for<charT>>>;
|
| 945 |
+
```
|
| 946 |
+
|
| 947 |
+
A type `T` and a character type `charT` model `formattable` if
|
| 948 |
+
`formatter<remove_cvref_t<T>, charT>` meets the requirements
|
| 949 |
+
[[formatter.requirements]] and, if `remove_reference_t<T>` is
|
| 950 |
+
const-qualified, the requirements.
|
| 951 |
+
|
| 952 |
#### Formatter specializations <a id="format.formatter.spec">[[format.formatter.spec]]</a>
|
| 953 |
|
| 954 |
The functions defined in [[format.functions]] use specializations of the
|
| 955 |
class template `formatter` to format individual arguments.
|
| 956 |
|
| 957 |
Let `charT` be either `char` or `wchar_t`. Each specialization of
|
| 958 |
+
`formatter` is either enabled or disabled, as described below. A
|
| 959 |
+
*debug-enabled* specialization of `formatter` additionally provides a
|
| 960 |
+
public, constexpr, non-static member function `set_debug_format()` which
|
| 961 |
+
modifies the state of the `formatter` to be as if the type of the
|
| 962 |
+
*std-format-spec* parsed by the last call to `parse` were `?`. Each
|
| 963 |
+
header that declares the template `formatter` provides the following
|
| 964 |
+
enabled specializations:
|
| 965 |
|
| 966 |
+
- The debug-enabled specializations
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 967 |
``` cpp
|
| 968 |
template<> struct formatter<char, char>;
|
| 969 |
template<> struct formatter<char, wchar_t>;
|
| 970 |
template<> struct formatter<wchar_t, wchar_t>;
|
| 971 |
```
|
| 972 |
+
- For each `charT`, the debug-enabled string type specializations
|
| 973 |
``` cpp
|
| 974 |
template<> struct formatter<charT*, charT>;
|
| 975 |
template<> struct formatter<const charT*, charT>;
|
| 976 |
+
template<size_t N> struct formatter<charT[N], charT>;
|
| 977 |
template<class traits, class Allocator>
|
| 978 |
struct formatter<basic_string<charT, traits, Allocator>, charT>;
|
| 979 |
template<class traits>
|
| 980 |
struct formatter<basic_string_view<charT, traits>, charT>;
|
| 981 |
```
|
|
|
|
| 994 |
|
| 995 |
The `parse` member functions of these formatters interpret the format
|
| 996 |
specification as a *std-format-spec* as described in
|
| 997 |
[[format.string.std]].
|
| 998 |
|
| 999 |
+
[*Note 1*: Specializations such as `formatter<wchar_t, char>` and
|
| 1000 |
`formatter<const char*, wchar_t>` that would require implicit multibyte
|
| 1001 |
/ wide string or character conversion are disabled. — *end note*]
|
| 1002 |
|
| 1003 |
For any types `T` and `charT` for which neither the library nor the user
|
| 1004 |
provides an explicit or partial specialization of the class template
|
| 1005 |
`formatter`, `formatter<T, charT>` is disabled.
|
| 1006 |
|
| 1007 |
If the library provides an explicit or partial specialization of
|
| 1008 |
+
`formatter<T, charT>`, that specialization is enabled and meets the
|
| 1009 |
+
requirements except as noted otherwise.
|
| 1010 |
|
| 1011 |
If `F` is a disabled specialization of `formatter`, these values are
|
| 1012 |
`false`:
|
| 1013 |
|
| 1014 |
- `is_default_constructible_v<F>`,
|
|
|
|
| 1027 |
|
| 1028 |
enum color { red, green, blue };
|
| 1029 |
const char* color_names[] = { "red", "green", "blue" };
|
| 1030 |
|
| 1031 |
template<> struct std::formatter<color> : std::formatter<const char*> {
|
| 1032 |
+
auto format(color c, format_context& ctx) const {
|
| 1033 |
return formatter<const char*>::format(color_names[c], ctx);
|
| 1034 |
}
|
| 1035 |
};
|
| 1036 |
|
| 1037 |
struct err {};
|
|
|
|
| 1042 |
std::string s3 = std::format("{}", err{}); // error: disabled formatter
|
| 1043 |
```
|
| 1044 |
|
| 1045 |
— *end example*]
|
| 1046 |
|
| 1047 |
+
#### Formatting escaped characters and strings <a id="format.string.escaped">[[format.string.escaped]]</a>
|
| 1048 |
+
|
| 1049 |
+
A character or string can be formatted as *escaped* to make it more
|
| 1050 |
+
suitable for debugging or for logging.
|
| 1051 |
+
|
| 1052 |
+
The escaped string *E* representation of a string *S* is constructed by
|
| 1053 |
+
encoding a sequence of characters as follows. The associated character
|
| 1054 |
+
encoding *CE* for `charT` ([[lex.string.literal]]) is used to both
|
| 1055 |
+
interpret *S* and construct *E*.
|
| 1056 |
+
|
| 1057 |
+
- U+0022 (quotation mark) (`"`) is appended to *E*.
|
| 1058 |
+
- For each code unit sequence *X* in *S* that either encodes a single
|
| 1059 |
+
character, is a shift sequence, or is a sequence of ill-formed code
|
| 1060 |
+
units, processing is in order as follows:
|
| 1061 |
+
- If *X* encodes a single character *C*, then:
|
| 1062 |
+
- If *C* is one of the characters in [[format.escape.sequences]],
|
| 1063 |
+
then the two characters shown as the corresponding escape sequence
|
| 1064 |
+
are appended to *E*.
|
| 1065 |
+
- Otherwise, if *C* is not U+0020 (space) and
|
| 1066 |
+
- *CE* is UTF-8, UTF-16, or UTF-32 and *C* corresponds to a
|
| 1067 |
+
Unicode scalar value whose Unicode property `General_Category`
|
| 1068 |
+
has a value in the groups `Separator` (`Z`) or `Other` (`C`), as
|
| 1069 |
+
described by UAX \#44 of the Unicode Standard, or
|
| 1070 |
+
- *CE* is UTF-8, UTF-16, or UTF-32 and *C* corresponds to a
|
| 1071 |
+
Unicode scalar value with the Unicode property
|
| 1072 |
+
`Grapheme_Extend=Yes` as described by UAX \#44 of the Unicode
|
| 1073 |
+
Standard and *C* is not immediately preceded in *S* by a
|
| 1074 |
+
character *P* appended to *E* without translation to an escape
|
| 1075 |
+
sequence, or
|
| 1076 |
+
- *CE* is neither UTF-8, UTF-16, nor UTF-32 and *C* is one of an
|
| 1077 |
+
implementation-defined set of separator or non-printable
|
| 1078 |
+
characters
|
| 1079 |
+
|
| 1080 |
+
then the sequence `\u{hex-digit-sequence}` is appended to *E*,
|
| 1081 |
+
where `hex-digit-sequence` is the shortest hexadecimal
|
| 1082 |
+
representation of *C* using lower-case hexadecimal digits.
|
| 1083 |
+
- Otherwise, *C* is appended to *E*.
|
| 1084 |
+
- Otherwise, if *X* is a shift sequence, the effect on *E* and further
|
| 1085 |
+
decoding of *S* is unspecified. *Recommended practice:* A shift
|
| 1086 |
+
sequence should be represented in *E* such that the original code
|
| 1087 |
+
unit sequence of *S* can be reconstructed.
|
| 1088 |
+
- Otherwise (*X* is a sequence of ill-formed code units), each code
|
| 1089 |
+
unit *U* is appended to *E* in order as the sequence
|
| 1090 |
+
`\x{hex-digit-sequence}`, where `hex-digit-sequence` is the shortest
|
| 1091 |
+
hexadecimal representation of *U* using lower-case hexadecimal
|
| 1092 |
+
digits.
|
| 1093 |
+
- Finally, U+0022 (quotation mark) (`"`) is appended to *E*.
|
| 1094 |
+
|
| 1095 |
+
**Table: Mapping of characters to escape sequences** <a id="format.escape.sequences">[format.escape.sequences]</a>
|
| 1096 |
+
|
| 1097 |
+
| Character | Escape sequence |
|
| 1098 |
+
| ----------------------------- | --------------- |
|
| 1099 |
+
| U+0009 (character tabulation) | `\t` |
|
| 1100 |
+
| % U+000a (line feed) | `\n` |
|
| 1101 |
+
| % U+000d (carriage return) | `\r` |
|
| 1102 |
+
| % U+0022 (quotation mark) | `\"` |
|
| 1103 |
+
| % U+005c (reverse solidus) | `` |
|
| 1104 |
+
|
| 1105 |
+
|
| 1106 |
+
The escaped string representation of a character *C* is equivalent to
|
| 1107 |
+
the escaped string representation of a string of *C*, except that:
|
| 1108 |
+
|
| 1109 |
+
- the result starts and ends with U+0027 (apostrophe) (`'`) instead of
|
| 1110 |
+
U+0022 (quotation mark) (`"`), and
|
| 1111 |
+
- if *C* is U+0027 (apostrophe), the two characters `\'` are appended to
|
| 1112 |
+
*E*, and
|
| 1113 |
+
- if *C* is U+0022 (quotation mark), then *C* is appended unchanged.
|
| 1114 |
+
|
| 1115 |
+
[*Example 1*:
|
| 1116 |
+
|
| 1117 |
+
``` cpp
|
| 1118 |
+
string s0 = format("[{}]", "h\tllo"); // s0 has value: [h\ \ \ \ llo]
|
| 1119 |
+
string s1 = format("[{:?}]", "h\tllo"); // s1 has value: ["h\ tllo"]
|
| 1120 |
+
string s3 = format("[{:?}, {:?}]", '\'', '"'); // s3 has value: ['\ '', '"']
|
| 1121 |
+
|
| 1122 |
+
// The following examples assume use of the UTF-8 encoding
|
| 1123 |
+
string s4 = format("[{:?}]", string("\0 \n \t \x02 \x1b", 9));
|
| 1124 |
+
// s4 has value: ["\ u{0\ \ n \ t \ u{2} \ u{1b}"]}
|
| 1125 |
+
string s5 = format("[{:?}]", "\xc3\x28"); // invalid UTF-8, s5 has value: ["\ x{c3\("]}
|
| 1126 |
+
string s7 = format("[{:?}]", "\u0301"); // s7 has value: ["\ u{301"]}
|
| 1127 |
+
string s8 = format("[{:?}]", "\\\u0301"); // s8 has value: ["\ \ \ u{301"]}
|
| 1128 |
+
```
|
| 1129 |
+
|
| 1130 |
+
— *end example*]
|
| 1131 |
+
|
| 1132 |
#### Class template `basic_format_parse_context` <a id="format.parse.ctx">[[format.parse.ctx]]</a>
|
| 1133 |
|
| 1134 |
``` cpp
|
| 1135 |
namespace std {
|
| 1136 |
template<class charT>
|
|
|
|
| 1199 |
|
| 1200 |
``` cpp
|
| 1201 |
constexpr size_t next_arg_id();
|
| 1202 |
```
|
| 1203 |
|
| 1204 |
+
*Effects:* If `indexing_ != manual` is `true`, equivalent to:
|
| 1205 |
|
| 1206 |
``` cpp
|
| 1207 |
if (indexing_ == unknown)
|
| 1208 |
indexing_ = automatic;
|
| 1209 |
return next_arg_id_++;
|
| 1210 |
```
|
| 1211 |
|
| 1212 |
+
*Throws:* `format_error` if `indexing_ == manual` is `true` which
|
| 1213 |
+
indicates mixing of automatic and manual argument indexing.
|
| 1214 |
+
|
| 1215 |
+
*Remarks:* Let *`cur-arg-id`* be the value of `next_arg_id_` prior to
|
| 1216 |
+
this call. Call expressions where *`cur-arg-id`*` >= num_args_` is
|
| 1217 |
+
`true` are not core constant expressions [[expr.const]].
|
| 1218 |
|
| 1219 |
``` cpp
|
| 1220 |
constexpr void check_arg_id(size_t id);
|
| 1221 |
```
|
| 1222 |
|
| 1223 |
+
*Effects:* If `indexing_ != automatic` is `true`, equivalent to:
|
| 1224 |
|
| 1225 |
``` cpp
|
| 1226 |
if (indexing_ == unknown)
|
| 1227 |
indexing_ = manual;
|
| 1228 |
```
|
| 1229 |
|
| 1230 |
+
*Throws:* `format_error` if `indexing_ == automatic` is `true` which
|
| 1231 |
+
indicates mixing of automatic and manual argument indexing.
|
| 1232 |
|
| 1233 |
+
*Remarks:* Call expressions where `id >= num_args_` is `true` are not
|
| 1234 |
+
core constant expressions [[expr.const]].
|
| 1235 |
|
| 1236 |
#### Class template `basic_format_context` <a id="format.context">[[format.context]]</a>
|
| 1237 |
|
| 1238 |
``` cpp
|
| 1239 |
namespace std {
|
|
|
|
| 1245 |
public:
|
| 1246 |
using iterator = Out;
|
| 1247 |
using char_type = charT;
|
| 1248 |
template<class T> using formatter_type = formatter<T, charT>;
|
| 1249 |
|
| 1250 |
+
basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
|
| 1251 |
std::locale locale();
|
| 1252 |
|
| 1253 |
iterator out();
|
| 1254 |
void advance_to(iterator it);
|
| 1255 |
};
|
|
|
|
| 1265 |
`basic_format_context` with an output iterator that appends to `string`,
|
| 1266 |
such as `back_insert_iterator<string>`. Similarly, `wformat_context` is
|
| 1267 |
an alias for a specialization of `basic_format_context` with an output
|
| 1268 |
iterator that appends to `wstring`.
|
| 1269 |
|
| 1270 |
+
*Recommended practice:* For a given type `charT`, implementations should
|
| 1271 |
provide a single instantiation of `basic_format_context` for appending
|
| 1272 |
to `basic_string<charT>`, `vector<charT>`, or any other container with
|
| 1273 |
contiguous storage by wrapping those in temporary objects with a uniform
|
| 1274 |
+
interface (such as a `span<charT>`) and polymorphic reallocation.
|
|
|
|
| 1275 |
|
| 1276 |
``` cpp
|
| 1277 |
+
basic_format_arg<basic_format_context> arg(size_t id) const noexcept;
|
| 1278 |
```
|
| 1279 |
|
| 1280 |
*Returns:* `args_.get(id)`.
|
| 1281 |
|
| 1282 |
``` cpp
|
|
|
|
| 1288 |
|
| 1289 |
``` cpp
|
| 1290 |
iterator out();
|
| 1291 |
```
|
| 1292 |
|
| 1293 |
+
*Effects:* Equivalent to: `return std::move(out_);`
|
| 1294 |
|
| 1295 |
``` cpp
|
| 1296 |
void advance_to(iterator it);
|
| 1297 |
```
|
| 1298 |
|
| 1299 |
+
*Effects:* Equivalent to: `out_ = std::move(it);`
|
| 1300 |
|
| 1301 |
[*Example 1*:
|
| 1302 |
|
| 1303 |
``` cpp
|
| 1304 |
struct S { int value; };
|
|
|
|
| 1320 |
ctx.check_arg_id(width_arg_id);
|
| 1321 |
return ++iter;
|
| 1322 |
}
|
| 1323 |
|
| 1324 |
// Formats an S with width given by the argument width_arg_id.
|
| 1325 |
+
auto format(S s, format_context& ctx) const {
|
| 1326 |
int width = visit_format_arg([](auto value) -> int {
|
| 1327 |
if constexpr (!is_integral_v<decltype(value)>)
|
| 1328 |
throw format_error("width is not integral");
|
| 1329 |
else if (value < 0 || value > numeric_limits<int>::max())
|
| 1330 |
throw format_error("invalid width");
|
|
|
|
| 1338 |
std::string s = std::format("{0:{1}}", S{42}, 10); // value of s is "xxxxxxxx42"
|
| 1339 |
```
|
| 1340 |
|
| 1341 |
— *end example*]
|
| 1342 |
|
| 1343 |
+
### Formatting of ranges <a id="format.range">[[format.range]]</a>
|
| 1344 |
+
|
| 1345 |
+
#### Variable template `format_kind` <a id="format.range.fmtkind">[[format.range.fmtkind]]</a>
|
| 1346 |
+
|
| 1347 |
+
``` cpp
|
| 1348 |
+
template<ranges::input_range R>
|
| 1349 |
+
requires same_as<R, remove_cvref_t<R>>
|
| 1350 |
+
constexpr range_format format_kind<R> = see below;
|
| 1351 |
+
```
|
| 1352 |
+
|
| 1353 |
+
A program that instantiates the primary template of `format_kind` is
|
| 1354 |
+
ill-formed.
|
| 1355 |
+
|
| 1356 |
+
For a type `R`, `format_kind<R>` is defined as follows:
|
| 1357 |
+
|
| 1358 |
+
- If `same_as<remove_cvref_t<ranges::range_reference_t<R>>, R>` is
|
| 1359 |
+
`true`, `format_kind<R>` is `range_format::disabled`. \[*Note 1*: This
|
| 1360 |
+
prevents constraint recursion for ranges whose reference type is the
|
| 1361 |
+
same range type. For example, `std::filesystem::path` is a range of
|
| 1362 |
+
`std::filesystem::path`. — *end note*]
|
| 1363 |
+
- Otherwise, if the *qualified-id* `R::key_type` is valid and denotes a
|
| 1364 |
+
type:
|
| 1365 |
+
- If the *qualified-id* `R::mapped_type` is valid and denotes a type,
|
| 1366 |
+
let `U` be `remove_cvref_t<ranges::range_reference_t<R>>`. If either
|
| 1367 |
+
`U` is a specialization of `pair` or `U` is a specialization of
|
| 1368 |
+
`tuple` and `tuple_size_v<U> == 2`, `format_kind<R>` is
|
| 1369 |
+
`range_format::map`.
|
| 1370 |
+
- Otherwise, `format_kind<R>` is `range_format::set`.
|
| 1371 |
+
- Otherwise, `format_kind<R>` is `range_format::sequence`.
|
| 1372 |
+
|
| 1373 |
+
*Remarks:* Pursuant to [[namespace.std]], users may specialize
|
| 1374 |
+
`format_kind` for cv-unqualified program-defined types that model
|
| 1375 |
+
`ranges::input_range`. Such specializations shall be usable in constant
|
| 1376 |
+
expressions [[expr.const]] and have type `const range_format`.
|
| 1377 |
+
|
| 1378 |
+
#### Class template `range_formatter` <a id="format.range.formatter">[[format.range.formatter]]</a>
|
| 1379 |
+
|
| 1380 |
+
``` cpp
|
| 1381 |
+
namespace std {
|
| 1382 |
+
template<class T, class charT = char>
|
| 1383 |
+
requires same_as<remove_cvref_t<T>, T> && formattable<T, charT>
|
| 1384 |
+
class range_formatter {
|
| 1385 |
+
formatter<T, charT> underlying_; // exposition only
|
| 1386 |
+
basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only
|
| 1387 |
+
basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("["); // exposition only
|
| 1388 |
+
basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>("]"); // exposition only
|
| 1389 |
+
|
| 1390 |
+
public:
|
| 1391 |
+
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
|
| 1392 |
+
constexpr void set_brackets(basic_string_view<charT> opening,
|
| 1393 |
+
basic_string_view<charT> closing) noexcept;
|
| 1394 |
+
constexpr formatter<T, charT>& underlying() noexcept { return underlying_; }
|
| 1395 |
+
constexpr const formatter<T, charT>& underlying() const noexcept { return underlying_; }
|
| 1396 |
+
|
| 1397 |
+
template<class ParseContext>
|
| 1398 |
+
constexpr typename ParseContext::iterator
|
| 1399 |
+
parse(ParseContext& ctx);
|
| 1400 |
+
|
| 1401 |
+
template<ranges::input_range R, class FormatContext>
|
| 1402 |
+
requires formattable<ranges::range_reference_t<R>, charT> &&
|
| 1403 |
+
same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
|
| 1404 |
+
typename FormatContext::iterator
|
| 1405 |
+
format(R&& r, FormatContext& ctx) const;
|
| 1406 |
+
};
|
| 1407 |
+
}
|
| 1408 |
+
```
|
| 1409 |
+
|
| 1410 |
+
The class template `range_formatter` is a utility for implementing
|
| 1411 |
+
`formatter` specializations for range types.
|
| 1412 |
+
|
| 1413 |
+
`range_formatter` interprets *format-spec* as a *range-format-spec*. The
|
| 1414 |
+
syntax of format specifications is as follows:
|
| 1415 |
+
|
| 1416 |
+
``` bnf
|
| 1417 |
+
range-format-spec
|
| 1418 |
+
range-fill-and-alignₒₚₜ widthₒₚₜ 'n'ₒₚₜ range-typeₒₚₜ range-underlying-specₒₚₜ
|
| 1419 |
+
```
|
| 1420 |
+
|
| 1421 |
+
``` bnf
|
| 1422 |
+
range-fill-and-align
|
| 1423 |
+
range-fillₒₚₜ align
|
| 1424 |
+
```
|
| 1425 |
+
|
| 1426 |
+
``` bnf
|
| 1427 |
+
range-fill
|
| 1428 |
+
any character other than '{' or '}' or ':'
|
| 1429 |
+
```
|
| 1430 |
+
|
| 1431 |
+
``` bnf
|
| 1432 |
+
range-type
|
| 1433 |
+
'm'
|
| 1434 |
+
's'
|
| 1435 |
+
'?s'
|
| 1436 |
+
```
|
| 1437 |
+
|
| 1438 |
+
``` bnf
|
| 1439 |
+
range-underlying-spec
|
| 1440 |
+
':' format-spec
|
| 1441 |
+
```
|
| 1442 |
+
|
| 1443 |
+
For `range_formatter<T, charT>`, the *format-spec* in a
|
| 1444 |
+
*range-underlying-spec*, if any, is interpreted by
|
| 1445 |
+
`formatter<T, charT>`.
|
| 1446 |
+
|
| 1447 |
+
The *range-fill-and-align* is interpreted the same way as a
|
| 1448 |
+
*fill-and-align* [[format.string.std]]. The productions *align* and
|
| 1449 |
+
*width* are described in [[format.string]].
|
| 1450 |
+
|
| 1451 |
+
The `n` option causes the range to be formatted without the opening and
|
| 1452 |
+
closing brackets.
|
| 1453 |
+
|
| 1454 |
+
[*Note 1*: This is equivalent to invoking
|
| 1455 |
+
`set_brackets({}, {})`. — *end note*]
|
| 1456 |
+
|
| 1457 |
+
The *range-type* specifier changes the way a range is formatted, with
|
| 1458 |
+
certain options only valid with certain argument types. The meaning of
|
| 1459 |
+
the various type options is as specified in [[formatter.range.type]].
|
| 1460 |
+
|
| 1461 |
+
**Table: Meaning of range-type options** <a id="formatter.range.type">[formatter.range.type]</a>
|
| 1462 |
+
|
| 1463 |
+
| Option | Requirements | Meaning |
|
| 1464 |
+
| ------ | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 1465 |
+
| % `m` | `T` shall be either a specialization of `pair` or a specialization of `tuple` such that `tuple_size_v<T>` is `2`. | Indicates that the opening bracket should be `"{"`, the closing bracket should be `"}"`, the separator should be `", "`, and each range element should be formatted as if `m` were specified for its tuple-type. *If the `n` option is provided in addition to the `m` option, both the opening and closing brackets are still empty.* |
|
| 1466 |
+
| % `s` | `T` shall be `charT`. | Indicates that the range should be formatted as a `string`. |
|
| 1467 |
+
| % `?s` | `T` shall be `charT`. | Indicates that the range should be formatted as an escaped string [[format.string.escaped]]. |
|
| 1468 |
+
|
| 1469 |
+
|
| 1470 |
+
If the *range-type* is `s` or `?s`, then there shall be no `n` option
|
| 1471 |
+
and no *range-underlying-spec*.
|
| 1472 |
+
|
| 1473 |
+
``` cpp
|
| 1474 |
+
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
|
| 1475 |
+
```
|
| 1476 |
+
|
| 1477 |
+
*Effects:* Equivalent to: *`separator_`*` = sep;`
|
| 1478 |
+
|
| 1479 |
+
``` cpp
|
| 1480 |
+
constexpr void set_brackets(basic_string_view<charT> opening,
|
| 1481 |
+
basic_string_view<charT> closing) noexcept;
|
| 1482 |
+
```
|
| 1483 |
+
|
| 1484 |
+
*Effects:* Equivalent to:
|
| 1485 |
+
|
| 1486 |
+
``` cpp
|
| 1487 |
+
opening-bracket_ = opening;
|
| 1488 |
+
closing-bracket_ = closing;
|
| 1489 |
+
```
|
| 1490 |
+
|
| 1491 |
+
``` cpp
|
| 1492 |
+
template<class ParseContext>
|
| 1493 |
+
constexpr typename ParseContext::iterator
|
| 1494 |
+
parse(ParseContext& ctx);
|
| 1495 |
+
```
|
| 1496 |
+
|
| 1497 |
+
*Effects:* Parses the format specifier as a *range-format-spec* and
|
| 1498 |
+
stores the parsed specifiers in `*this`. The values of
|
| 1499 |
+
*opening-bracket\_*, *closing-bracket\_*, and *separator\_* are modified
|
| 1500 |
+
if and only if required by the *range-type* or the `n` option, if
|
| 1501 |
+
present. If:
|
| 1502 |
+
|
| 1503 |
+
- the *range-type* is neither `s` nor `?s`,
|
| 1504 |
+
- *`underlying_`*`.set_debug_format()` is a valid expression, and
|
| 1505 |
+
- there is no *range-underlying-spec*,
|
| 1506 |
+
|
| 1507 |
+
then calls *`underlying_`*`.set_debug_format()`.
|
| 1508 |
+
|
| 1509 |
+
*Returns:* An iterator past the end of the *range-format-spec*.
|
| 1510 |
+
|
| 1511 |
+
``` cpp
|
| 1512 |
+
template<ranges::input_range R, class FormatContext>
|
| 1513 |
+
requires formattable<ranges::range_reference_t<R>, charT> &&
|
| 1514 |
+
same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
|
| 1515 |
+
typename FormatContext::iterator
|
| 1516 |
+
format(R&& r, FormatContext& ctx) const;
|
| 1517 |
+
```
|
| 1518 |
+
|
| 1519 |
+
*Effects:* Writes the following into `ctx.out()`, adjusted according to
|
| 1520 |
+
the *range-format-spec*:
|
| 1521 |
+
|
| 1522 |
+
- If the *range-type* was `s`, then as if by formatting
|
| 1523 |
+
`basic_string<charT>(from_range, r)`.
|
| 1524 |
+
- Otherwise, if the *range-type* was `?s`, then as if by formatting
|
| 1525 |
+
`basic_string<charT>(from_range, r)` as an escaped
|
| 1526 |
+
string [[format.string.escaped]].
|
| 1527 |
+
- Otherwise,
|
| 1528 |
+
- *opening-bracket\_*,
|
| 1529 |
+
- for each element `e` of the range `r`:
|
| 1530 |
+
- the result of writing `e` via *underlying\_* and
|
| 1531 |
+
- *separator\_*, unless `e` is the last element of `r`, and
|
| 1532 |
+
- *closing-bracket\_*.
|
| 1533 |
+
|
| 1534 |
+
*Returns:* An iterator past the end of the output range.
|
| 1535 |
+
|
| 1536 |
+
#### Class template *`range-default-formatter`* <a id="format.range.fmtdef">[[format.range.fmtdef]]</a>
|
| 1537 |
+
|
| 1538 |
+
``` cpp
|
| 1539 |
+
namespace std {
|
| 1540 |
+
template<ranges::input_range R, class charT>
|
| 1541 |
+
struct range-default-formatter<range_format::sequence, R, charT> { // exposition only
|
| 1542 |
+
private:
|
| 1543 |
+
using maybe-const-r = fmt-maybe-const<R, charT>; // exposition only
|
| 1544 |
+
range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-r>>,
|
| 1545 |
+
charT> underlying_; // exposition only
|
| 1546 |
+
|
| 1547 |
+
public:
|
| 1548 |
+
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
|
| 1549 |
+
constexpr void set_brackets(basic_string_view<charT> opening,
|
| 1550 |
+
basic_string_view<charT> closing) noexcept;
|
| 1551 |
+
|
| 1552 |
+
template<class ParseContext>
|
| 1553 |
+
constexpr typename ParseContext::iterator
|
| 1554 |
+
parse(ParseContext& ctx);
|
| 1555 |
+
|
| 1556 |
+
template<class FormatContext>
|
| 1557 |
+
typename FormatContext::iterator
|
| 1558 |
+
format(maybe-const-r& elems, FormatContext& ctx) const;
|
| 1559 |
+
};
|
| 1560 |
+
}
|
| 1561 |
+
```
|
| 1562 |
+
|
| 1563 |
+
``` cpp
|
| 1564 |
+
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
|
| 1565 |
+
```
|
| 1566 |
+
|
| 1567 |
+
*Effects:* Equivalent to: *`underlying_`*`.set_separator(sep);`
|
| 1568 |
+
|
| 1569 |
+
``` cpp
|
| 1570 |
+
constexpr void set_brackets(basic_string_view<charT> opening,
|
| 1571 |
+
basic_string_view<charT> closing) noexcept;
|
| 1572 |
+
```
|
| 1573 |
+
|
| 1574 |
+
*Effects:* Equivalent to:
|
| 1575 |
+
*`underlying_`*`.set_brackets(opening, closing);`
|
| 1576 |
+
|
| 1577 |
+
``` cpp
|
| 1578 |
+
template<class ParseContext>
|
| 1579 |
+
constexpr typename ParseContext::iterator
|
| 1580 |
+
parse(ParseContext& ctx);
|
| 1581 |
+
```
|
| 1582 |
+
|
| 1583 |
+
*Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
|
| 1584 |
+
|
| 1585 |
+
``` cpp
|
| 1586 |
+
template<class FormatContext>
|
| 1587 |
+
typename FormatContext::iterator
|
| 1588 |
+
format(maybe-const-r& elems, FormatContext& ctx) const;
|
| 1589 |
+
```
|
| 1590 |
+
|
| 1591 |
+
*Effects:* Equivalent to: `return `*`underlying_`*`.format(elems, ctx);`
|
| 1592 |
+
|
| 1593 |
+
#### Specialization of *`range-default-formatter`* for maps <a id="format.range.fmtmap">[[format.range.fmtmap]]</a>
|
| 1594 |
+
|
| 1595 |
+
``` cpp
|
| 1596 |
+
namespace std {
|
| 1597 |
+
template<ranges::input_range R, class charT>
|
| 1598 |
+
struct range-default-formatter<range_format::map, R, charT> {
|
| 1599 |
+
private:
|
| 1600 |
+
using maybe-const-map = fmt-maybe-const<R, charT>; // exposition only
|
| 1601 |
+
using element-type = // exposition only
|
| 1602 |
+
remove_cvref_t<ranges::range_reference_t<maybe-const-map>>;
|
| 1603 |
+
range_formatter<element-type, charT> underlying_; // exposition only
|
| 1604 |
+
|
| 1605 |
+
public:
|
| 1606 |
+
constexpr range-default-formatter();
|
| 1607 |
+
|
| 1608 |
+
template<class ParseContext>
|
| 1609 |
+
constexpr typename ParseContext::iterator
|
| 1610 |
+
parse(ParseContext& ctx);
|
| 1611 |
+
|
| 1612 |
+
template<class FormatContext>
|
| 1613 |
+
typename FormatContext::iterator
|
| 1614 |
+
format(maybe-const-map& r, FormatContext& ctx) const;
|
| 1615 |
+
};
|
| 1616 |
+
}
|
| 1617 |
+
```
|
| 1618 |
+
|
| 1619 |
+
``` cpp
|
| 1620 |
+
constexpr range-default-formatter();
|
| 1621 |
+
```
|
| 1622 |
+
|
| 1623 |
+
*Mandates:* Either:
|
| 1624 |
+
|
| 1625 |
+
- *element-type* is a specialization of `pair`, or
|
| 1626 |
+
- *element-type* is a specialization of `tuple` and
|
| 1627 |
+
`tuple_size_v<`*`element-type`*`> == 2`.
|
| 1628 |
+
|
| 1629 |
+
*Effects:* Equivalent to:
|
| 1630 |
+
|
| 1631 |
+
``` cpp
|
| 1632 |
+
underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
|
| 1633 |
+
underlying_.underlying().set_brackets({}, {});
|
| 1634 |
+
underlying_.underlying().set_separator(STATICALLY-WIDEN<charT>(": "));
|
| 1635 |
+
```
|
| 1636 |
+
|
| 1637 |
+
``` cpp
|
| 1638 |
+
template<class ParseContext>
|
| 1639 |
+
constexpr typename ParseContext::iterator
|
| 1640 |
+
parse(ParseContext& ctx);
|
| 1641 |
+
```
|
| 1642 |
+
|
| 1643 |
+
*Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
|
| 1644 |
+
|
| 1645 |
+
``` cpp
|
| 1646 |
+
template<class FormatContext>
|
| 1647 |
+
typename FormatContext::iterator
|
| 1648 |
+
format(maybe-const-map& r, FormatContext& ctx) const;
|
| 1649 |
+
```
|
| 1650 |
+
|
| 1651 |
+
*Effects:* Equivalent to: `return `*`underlying_`*`.format(r, ctx);`
|
| 1652 |
+
|
| 1653 |
+
#### Specialization of *`range-default-formatter`* for sets <a id="format.range.fmtset">[[format.range.fmtset]]</a>
|
| 1654 |
+
|
| 1655 |
+
``` cpp
|
| 1656 |
+
namespace std {
|
| 1657 |
+
template<ranges::input_range R, class charT>
|
| 1658 |
+
struct range-default-formatter<range_format::set, R, charT> {
|
| 1659 |
+
private:
|
| 1660 |
+
using maybe-const-set = fmt-maybe-const<R, charT>; // exposition only
|
| 1661 |
+
range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-set>>,
|
| 1662 |
+
charT> underlying_; // exposition only
|
| 1663 |
+
|
| 1664 |
+
public:
|
| 1665 |
+
constexpr range-default-formatter();
|
| 1666 |
+
|
| 1667 |
+
template<class ParseContext>
|
| 1668 |
+
constexpr typename ParseContext::iterator
|
| 1669 |
+
parse(ParseContext& ctx);
|
| 1670 |
+
|
| 1671 |
+
template<class FormatContext>
|
| 1672 |
+
typename FormatContext::iterator
|
| 1673 |
+
format(maybe-const-set& r, FormatContext& ctx) const;
|
| 1674 |
+
};
|
| 1675 |
+
}
|
| 1676 |
+
```
|
| 1677 |
+
|
| 1678 |
+
``` cpp
|
| 1679 |
+
constexpr range-default-formatter();
|
| 1680 |
+
```
|
| 1681 |
+
|
| 1682 |
+
*Effects:* Equivalent to:
|
| 1683 |
+
|
| 1684 |
+
``` cpp
|
| 1685 |
+
underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
|
| 1686 |
+
```
|
| 1687 |
+
|
| 1688 |
+
``` cpp
|
| 1689 |
+
template<class ParseContext>
|
| 1690 |
+
constexpr typename ParseContext::iterator
|
| 1691 |
+
parse(ParseContext& ctx);
|
| 1692 |
+
```
|
| 1693 |
+
|
| 1694 |
+
*Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
|
| 1695 |
+
|
| 1696 |
+
``` cpp
|
| 1697 |
+
template<class FormatContext>
|
| 1698 |
+
typename FormatContext::iterator
|
| 1699 |
+
format(maybe-const-set& r, FormatContext& ctx) const;
|
| 1700 |
+
```
|
| 1701 |
+
|
| 1702 |
+
*Effects:* Equivalent to: `return `*`underlying_`*`.format(r, ctx);`
|
| 1703 |
+
|
| 1704 |
+
#### Specialization of *`range-default-formatter`* for strings <a id="format.range.fmtstr">[[format.range.fmtstr]]</a>
|
| 1705 |
+
|
| 1706 |
+
``` cpp
|
| 1707 |
+
namespace std {
|
| 1708 |
+
template<range_format K, ranges::input_range R, class charT>
|
| 1709 |
+
requires (K == range_format::string || K == range_format::debug_string)
|
| 1710 |
+
struct range-default-formatter<K, R, charT> {
|
| 1711 |
+
private:
|
| 1712 |
+
formatter<basic_string<charT>, charT> underlying_; // exposition only
|
| 1713 |
+
|
| 1714 |
+
public:
|
| 1715 |
+
template<class ParseContext>
|
| 1716 |
+
constexpr typename ParseContext::iterator
|
| 1717 |
+
parse(ParseContext& ctx);
|
| 1718 |
+
|
| 1719 |
+
template<class FormatContext>
|
| 1720 |
+
typename FormatContext::iterator
|
| 1721 |
+
format(see below& str, FormatContext& ctx) const;
|
| 1722 |
+
};
|
| 1723 |
+
}
|
| 1724 |
+
```
|
| 1725 |
+
|
| 1726 |
+
*Mandates:* `same_as<remove_cvref_t<range_reference_t<R>>, charT>` is
|
| 1727 |
+
`true`.
|
| 1728 |
+
|
| 1729 |
+
``` cpp
|
| 1730 |
+
template<class ParseContext>
|
| 1731 |
+
constexpr typename ParseContext::iterator
|
| 1732 |
+
parse(ParseContext& ctx);
|
| 1733 |
+
```
|
| 1734 |
+
|
| 1735 |
+
*Effects:* Equivalent to:
|
| 1736 |
+
|
| 1737 |
+
``` cpp
|
| 1738 |
+
auto i = underlying_.parse(ctx);
|
| 1739 |
+
if constexpr (K == range_format::debug_string) {
|
| 1740 |
+
underlying_.set_debug_format();
|
| 1741 |
+
}
|
| 1742 |
+
return i;
|
| 1743 |
+
```
|
| 1744 |
+
|
| 1745 |
+
``` cpp
|
| 1746 |
+
template<class FormatContext>
|
| 1747 |
+
typename FormatContext::iterator
|
| 1748 |
+
format(see below& r, FormatContext& ctx) const;
|
| 1749 |
+
```
|
| 1750 |
+
|
| 1751 |
+
The type of `r` is `const R&` if `ranges::input_range<const R>` is
|
| 1752 |
+
`true` and `R&` otherwise.
|
| 1753 |
+
|
| 1754 |
+
*Effects:* Let *`s`* be a `basic_string<charT>` such that
|
| 1755 |
+
`ranges::equal(`*`s`*`, r)` is `true`. Equivalent to:
|
| 1756 |
+
`return `*`underlying_`*`.format(`*`s`*`, ctx);`
|
| 1757 |
+
|
| 1758 |
### Arguments <a id="format.arguments">[[format.arguments]]</a>
|
| 1759 |
|
| 1760 |
#### Class template `basic_format_arg` <a id="format.arg">[[format.arg]]</a>
|
| 1761 |
|
| 1762 |
``` cpp
|
|
|
|
| 1773 |
int, unsigned int, long long int, unsigned long long int,
|
| 1774 |
float, double, long double,
|
| 1775 |
const char_type*, basic_string_view<char_type>,
|
| 1776 |
const void*, handle> value; // exposition only
|
| 1777 |
|
| 1778 |
+
template<class T> explicit basic_format_arg(T& v) noexcept; // exposition only
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1779 |
|
| 1780 |
public:
|
| 1781 |
basic_format_arg() noexcept;
|
| 1782 |
|
| 1783 |
explicit operator bool() const noexcept;
|
|
|
|
| 1796 |
```
|
| 1797 |
|
| 1798 |
*Ensures:* `!(*this)`.
|
| 1799 |
|
| 1800 |
``` cpp
|
| 1801 |
+
template<class T> explicit basic_format_arg(T& v) noexcept;
|
| 1802 |
```
|
| 1803 |
|
| 1804 |
+
*Constraints:* `T` satisfies `formattable-with<Context>`.
|
| 1805 |
|
| 1806 |
+
*Preconditions:* If `decay_t<T>` is `char_type*` or `const char_type*`,
|
| 1807 |
+
`static_cast<const char_type*>(v)` points to a NTCTS [[defns.ntcts]].
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1808 |
|
| 1809 |
+
*Effects:* Let `TD` be `remove_const_t<T>`.
|
| 1810 |
|
| 1811 |
+
- If `TD` is `bool` or `char_type`, initializes `value` with `v`;
|
| 1812 |
+
- otherwise, if `TD` is `char` and `char_type` is `wchar_t`, initializes
|
| 1813 |
`value` with `static_cast<wchar_t>(v)`;
|
| 1814 |
+
- otherwise, if `TD` is a signed integer type [[basic.fundamental]] and
|
| 1815 |
+
`sizeof(TD) <= sizeof(int)`, initializes `value` with
|
| 1816 |
`static_cast<int>(v)`;
|
| 1817 |
+
- otherwise, if `TD` is an unsigned integer type and
|
| 1818 |
+
`sizeof(TD) <= sizeof(unsigned int)`, initializes `value` with
|
| 1819 |
`static_cast<unsigned int>(v)`;
|
| 1820 |
+
- otherwise, if `TD` is a signed integer type and
|
| 1821 |
+
`sizeof(TD) <= sizeof(long long int)`, initializes `value` with
|
| 1822 |
`static_cast<long long int>(v)`;
|
| 1823 |
+
- otherwise, if `TD` is an unsigned integer type and
|
| 1824 |
+
`sizeof(TD) <= sizeof(unsigned long long int)`, initializes `value`
|
| 1825 |
with `static_cast<unsigned long long int>(v)`;
|
| 1826 |
+
- otherwise, if `TD` is a standard floating-point type, initializes
|
| 1827 |
+
`value` with `v`;
|
| 1828 |
+
- otherwise, if `TD` is a specialization of `basic_string_view` or
|
| 1829 |
+
`basic_string` and `TD::value_type` is `char_type`, initializes
|
| 1830 |
+
`value` with `basic_string_view<char_type>(v.data(), v.size())`;
|
| 1831 |
+
- otherwise, if `decay_t<TD>` is `char_type*` or `const char_type*`,
|
| 1832 |
+
initializes `value` with `static_cast<const char_type*>(v)`;
|
| 1833 |
+
- otherwise, if `is_void_v<remove_pointer_t<TD>>` is `true` or
|
| 1834 |
+
`is_null_pointer_v<TD>` is `true`, initializes `value` with
|
| 1835 |
+
`static_cast<const void*>(v)`;
|
| 1836 |
- otherwise, initializes `value` with `handle(v)`.
|
| 1837 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1838 |
[*Note 1*: Constructing `basic_format_arg` from a pointer to a member
|
| 1839 |
is ill-formed unless the user provides an enabled specialization of
|
| 1840 |
`formatter` for that pointer to member type. — *end note*]
|
| 1841 |
|
| 1842 |
``` cpp
|
|
|
|
| 1853 |
class basic_format_arg<Context>::handle {
|
| 1854 |
const void* ptr_; // exposition only
|
| 1855 |
void (*format_)(basic_format_parse_context<char_type>&,
|
| 1856 |
Context&, const void*); // exposition only
|
| 1857 |
|
| 1858 |
+
template<class T> explicit handle(T& val) noexcept; // exposition only
|
| 1859 |
|
| 1860 |
friend class basic_format_arg<Context>; // exposition only
|
| 1861 |
|
| 1862 |
public:
|
| 1863 |
void format(basic_format_parse_context<char_type>&, Context& ctx) const;
|
| 1864 |
};
|
| 1865 |
}
|
| 1866 |
```
|
| 1867 |
|
| 1868 |
``` cpp
|
| 1869 |
+
template<class T> explicit handle(T& val) noexcept;
|
| 1870 |
```
|
| 1871 |
|
| 1872 |
+
Let
|
| 1873 |
+
|
| 1874 |
+
- `TD` be `remove_const_t<T>`,
|
| 1875 |
+
- `TQ` be `const TD` if `const TD` satisfies `formattable-with<Context>`
|
| 1876 |
+
and `TD` otherwise.
|
| 1877 |
+
|
| 1878 |
+
*Mandates:* `TQ` satisfies `formattable-with<Context>`.
|
| 1879 |
+
|
| 1880 |
*Effects:* Initializes `ptr_` with `addressof(val)` and `format_` with
|
| 1881 |
|
| 1882 |
``` cpp
|
| 1883 |
[](basic_format_parse_context<char_type>& parse_ctx,
|
| 1884 |
Context& format_ctx, const void* ptr) {
|
| 1885 |
+
typename Context::template formatter_type<TD> f;
|
| 1886 |
parse_ctx.advance_to(f.parse(parse_ctx));
|
| 1887 |
+
format_ctx.advance_to(f.format(*const_cast<TQ*>(static_cast<const TD*>(ptr)),
|
| 1888 |
+
format_ctx));
|
| 1889 |
}
|
| 1890 |
```
|
| 1891 |
|
| 1892 |
``` cpp
|
| 1893 |
void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
|
|
|
|
| 1895 |
|
| 1896 |
*Effects:* Equivalent to: `format_(parse_ctx, format_ctx, ptr_);`
|
| 1897 |
|
| 1898 |
``` cpp
|
| 1899 |
template<class Visitor, class Context>
|
| 1900 |
+
decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
|
| 1901 |
```
|
| 1902 |
|
| 1903 |
*Effects:* Equivalent to:
|
| 1904 |
+
`return visit(std::forward<Visitor>(vis), arg.value);`
|
| 1905 |
|
| 1906 |
#### Class template *`format-arg-store`* <a id="format.arg.store">[[format.arg.store]]</a>
|
| 1907 |
|
| 1908 |
``` cpp
|
| 1909 |
namespace std {
|
| 1910 |
template<class Context, class... Args>
|
| 1911 |
+
class format-arg-store { // exposition only
|
| 1912 |
+
array<basic_format_arg<Context>, sizeof...(Args)> args; // exposition only
|
| 1913 |
};
|
| 1914 |
}
|
| 1915 |
```
|
| 1916 |
|
| 1917 |
An instance of *`format-arg-store`* stores formatting arguments.
|
| 1918 |
|
| 1919 |
``` cpp
|
| 1920 |
template<class Context = format_context, class... Args>
|
| 1921 |
+
format-arg-store<Context, Args...> make_format_args(Args&&... fmt_args);
|
| 1922 |
```
|
| 1923 |
|
| 1924 |
*Preconditions:* The type
|
| 1925 |
+
`typename Context::template formatter_type<remove_cvref_t<``Tᵢ``>>`
|
| 1926 |
+
meets the requirements [[formatter.requirements]] for each `Tᵢ` in
|
| 1927 |
+
`Args`.
|
| 1928 |
|
| 1929 |
+
*Returns:* An object of type *`format-arg-store`*`<Context, Args...>`
|
| 1930 |
+
whose *args* data member is initialized with
|
| 1931 |
+
`{basic_format_arg<Context>(fmt_args)...}`.
|
| 1932 |
|
| 1933 |
``` cpp
|
| 1934 |
template<class... Args>
|
| 1935 |
+
format-arg-store<wformat_context, Args...> make_wformat_args(Args&&... args);
|
| 1936 |
```
|
| 1937 |
|
| 1938 |
*Effects:* Equivalent to:
|
| 1939 |
`return make_format_args<wformat_context>(args...);`
|
| 1940 |
|
|
|
|
| 1953 |
template<class... Args>
|
| 1954 |
basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
|
| 1955 |
|
| 1956 |
basic_format_arg<Context> get(size_t i) const noexcept;
|
| 1957 |
};
|
| 1958 |
+
|
| 1959 |
+
template<class Context, class... Args>
|
| 1960 |
+
basic_format_args(format-arg-store<Context, Args...>) -> basic_format_args<Context>;
|
| 1961 |
}
|
| 1962 |
```
|
| 1963 |
|
| 1964 |
An instance of `basic_format_args` provides access to formatting
|
| 1965 |
+
arguments. Implementations should optimize the representation of
|
| 1966 |
+
`basic_format_args` for a small number of formatting arguments.
|
| 1967 |
+
|
| 1968 |
+
[*Note 1*: For example, by storing indices of type alternatives
|
| 1969 |
+
separately from values and packing the former. — *end note*]
|
| 1970 |
|
| 1971 |
``` cpp
|
| 1972 |
basic_format_args() noexcept;
|
| 1973 |
```
|
| 1974 |
|
|
|
|
| 1986 |
basic_format_arg<Context> get(size_t i) const noexcept;
|
| 1987 |
```
|
| 1988 |
|
| 1989 |
*Returns:* `i < size_ ? data_[i] : basic_format_arg<Context>()`.
|
| 1990 |
|
| 1991 |
+
### Tuple formatter <a id="format.tuple">[[format.tuple]]</a>
|
| 1992 |
+
|
| 1993 |
+
For each of `pair` and `tuple`, the library provides the following
|
| 1994 |
+
formatter specialization where `pair-or-tuple` is the name of the
|
| 1995 |
+
template:
|
| 1996 |
+
|
| 1997 |
+
``` cpp
|
| 1998 |
+
namespace std {
|
| 1999 |
+
template<class charT, formattable<charT>... Ts>
|
| 2000 |
+
struct formatter<pair-or-tuple<Ts...>, charT> {
|
| 2001 |
+
private:
|
| 2002 |
+
tuple<formatter<remove_cvref_t<Ts>, charT>...> underlying_; // exposition only
|
| 2003 |
+
basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only
|
| 2004 |
+
basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("("); // exposition only
|
| 2005 |
+
basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>(")"); // exposition only
|
| 2006 |
+
|
| 2007 |
+
public:
|
| 2008 |
+
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
|
| 2009 |
+
constexpr void set_brackets(basic_string_view<charT> opening,
|
| 2010 |
+
basic_string_view<charT> closing) noexcept;
|
| 2011 |
+
|
| 2012 |
+
template<class ParseContext>
|
| 2013 |
+
constexpr typename ParseContext::iterator
|
| 2014 |
+
parse(ParseContext& ctx);
|
| 2015 |
+
|
| 2016 |
+
template<class FormatContext>
|
| 2017 |
+
typename FormatContext::iterator
|
| 2018 |
+
format(see below& elems, FormatContext& ctx) const;
|
| 2019 |
+
};
|
| 2020 |
+
}
|
| 2021 |
+
```
|
| 2022 |
+
|
| 2023 |
+
The `parse` member functions of these formatters interpret the format
|
| 2024 |
+
specification as a *tuple-format-spec* according to the following
|
| 2025 |
+
syntax:
|
| 2026 |
+
|
| 2027 |
+
``` bnf
|
| 2028 |
+
tuple-format-spec
|
| 2029 |
+
tuple-fill-and-alignₒₚₜ widthₒₚₜ tuple-typeₒₚₜ
|
| 2030 |
+
```
|
| 2031 |
+
|
| 2032 |
+
``` bnf
|
| 2033 |
+
tuple-fill-and-align
|
| 2034 |
+
tuple-fillₒₚₜ align
|
| 2035 |
+
```
|
| 2036 |
+
|
| 2037 |
+
``` bnf
|
| 2038 |
+
tuple-fill
|
| 2039 |
+
any character other than '{' or '}' or ':'
|
| 2040 |
+
```
|
| 2041 |
+
|
| 2042 |
+
``` bnf
|
| 2043 |
+
tuple-type
|
| 2044 |
+
'm'
|
| 2045 |
+
'n'
|
| 2046 |
+
```
|
| 2047 |
+
|
| 2048 |
+
The *tuple-fill-and-align* is interpreted the same way as a
|
| 2049 |
+
*fill-and-align* [[format.string.std]]. The productions *align* and
|
| 2050 |
+
*width* are described in [[format.string]].
|
| 2051 |
+
|
| 2052 |
+
The *tuple-type* specifier changes the way a `pair` or `tuple` is
|
| 2053 |
+
formatted, with certain options only valid with certain argument types.
|
| 2054 |
+
The meaning of the various type options is as specified in
|
| 2055 |
+
[[formatter.tuple.type]].
|
| 2056 |
+
|
| 2057 |
+
**Table: Meaning of tuple-type options** <a id="formatter.tuple.type">[formatter.tuple.type]</a>
|
| 2058 |
+
|
| 2059 |
+
| Option | Requirements | Meaning |
|
| 2060 |
+
| ------ | ------------ | -------------------------------------- |
|
| 2061 |
+
| <charT>(": ")); set_brackets({}, {}); \end{codeblock}% |
|
| 2062 |
+
| % `n` | none | Equivalent to: `set_brackets({}, {});` |
|
| 2063 |
+
| % none | none | No effects |
|
| 2064 |
+
|
| 2065 |
+
``` cpp
|
| 2066 |
+
constexpr void set_separator(basic_string_view<charT> sep) noexcept;
|
| 2067 |
+
```
|
| 2068 |
+
|
| 2069 |
+
*Effects:* Equivalent to: *`separator_`*` = sep;`
|
| 2070 |
+
|
| 2071 |
+
``` cpp
|
| 2072 |
+
constexpr void set_brackets(basic_string_view<charT> opening,
|
| 2073 |
+
basic_string_view<charT> closing) noexcept;
|
| 2074 |
+
```
|
| 2075 |
+
|
| 2076 |
+
*Effects:* Equivalent to:
|
| 2077 |
+
|
| 2078 |
+
``` cpp
|
| 2079 |
+
opening-bracket_ = opening;
|
| 2080 |
+
closing-bracket_ = closing;
|
| 2081 |
+
```
|
| 2082 |
+
|
| 2083 |
+
``` cpp
|
| 2084 |
+
template<class ParseContext>
|
| 2085 |
+
constexpr typename ParseContext::iterator
|
| 2086 |
+
parse(ParseContext& ctx);
|
| 2087 |
+
```
|
| 2088 |
+
|
| 2089 |
+
*Effects:* Parses the format specifier as a *tuple-format-spec* and
|
| 2090 |
+
stores the parsed specifiers in `*this`. The values of
|
| 2091 |
+
*opening-bracket\_*, *closing-bracket\_*, and *separator\_* are modified
|
| 2092 |
+
if and only if required by the *tuple-type*, if present. For each
|
| 2093 |
+
element *`e`* in *underlying\_*, if *`e`*`.set_debug_format()` is a
|
| 2094 |
+
valid expression, calls *`e`*`.set_debug_format()`.
|
| 2095 |
+
|
| 2096 |
+
*Returns:* An iterator past the end of the *tuple-format-spec*.
|
| 2097 |
+
|
| 2098 |
+
``` cpp
|
| 2099 |
+
template<class FormatContext>
|
| 2100 |
+
typename FormatContext::iterator
|
| 2101 |
+
format(see below& elems, FormatContext& ctx) const;
|
| 2102 |
+
```
|
| 2103 |
+
|
| 2104 |
+
The type of `elems` is:
|
| 2105 |
+
|
| 2106 |
+
- If `(formattable<const Ts, charT> && ...)` is `true`,
|
| 2107 |
+
`const `*`pair-or-tuple`*`<Ts...>&`.
|
| 2108 |
+
- Otherwise *`pair-or-tuple`*`<Ts...>&`.
|
| 2109 |
+
|
| 2110 |
+
*Effects:* Writes the following into `ctx.out()`, adjusted according to
|
| 2111 |
+
the *tuple-format-spec*:
|
| 2112 |
+
|
| 2113 |
+
- *opening-bracket\_*,
|
| 2114 |
+
- for each index `I` in the \[`0`, `sizeof...(Ts)`):
|
| 2115 |
+
- if `I != 0`, *separator\_*,
|
| 2116 |
+
- the result of writing `get<I>(elems)` via
|
| 2117 |
+
`get<I>(`*`underlying_`*`)`, and
|
| 2118 |
+
- *closing-bracket\_*.
|
| 2119 |
+
|
| 2120 |
+
*Returns:* An iterator past the end of the output range.
|
| 2121 |
|
| 2122 |
### Class `format_error` <a id="format.error">[[format.error]]</a>
|
| 2123 |
|
| 2124 |
``` cpp
|
| 2125 |
namespace std {
|
|
|
|
| 2144 |
format_error(const char* what_arg);
|
| 2145 |
```
|
| 2146 |
|
| 2147 |
*Ensures:* `strcmp(what(), what_arg) == 0`.
|
| 2148 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|