From Jason Turner

[format]

Large diff (106.0 KB) - rendering may be slow on some devices

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. 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(string_view fmt, const Args&... args);
10
  template<class... Args>
11
- wstring format(wstring_view fmt, const Args&... args);
12
  template<class... Args>
13
- string format(const locale& loc, string_view fmt, const Args&... args);
14
  template<class... Args>
15
- wstring format(const locale& loc, wstring_view fmt, const Args&... args);
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, string_view fmt, const Args&... args);
24
  template<class Out, class... Args>
25
- Out format_to(Out out, wstring_view fmt, const Args&... args);
26
  template<class Out, class... Args>
27
- Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args);
28
  template<class Out, class... Args>
29
- Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
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
- string_view fmt, const Args&... args);
51
  template<class Out, class... Args>
52
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
53
- wstring_view fmt, const Args&... args);
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, string_view fmt,
57
- const Args&... args);
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, wstring_view fmt,
61
- const Args&... args);
62
 
63
  template<class... Args>
64
- size_t formatted_size(string_view fmt, const Args&... args);
65
  template<class... Args>
66
- size_t formatted_size(wstring_view fmt, const Args&... args);
67
  template<class... Args>
68
- size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
69
  template<class... Args>
70
- size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
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
- template<class Out, class charT> class basic_format_context;
81
- using format_context = basic_format_context<unspecified, char>;
82
- using wformat_context = basic_format_context<unspecified, wchar_t>;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
- see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
90
 
91
  // [format.arg.store], class template format-arg-store
92
- template<class Context, class... Args> struct format-arg-store; // exposition only
93
 
94
  template<class Context = format_context, class... Args>
95
  format-arg-store<Context, Args...>
96
- make_format_args(const Args&... args);
97
  template<class... Args>
98
  format-arg-store<wformat_context, Args...>
99
- make_wformat_args(const Args&... 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
- // throws format_error
204
  string s3 = format("{} to {1}", "a", "b"); // not a format string (mixing automatic and manual indexing),
205
- // throws format_error
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` specializations described in [[format.formatter.spec]]
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 of the
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
- [*Note 2*: The *fill* character can be any character other than `{` or
285
- `}`. The presence of a fill character is signaled by the character
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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 both the fill character and the alignment option are
289
  absent. — *end note*]
290
 
291
- The *align* specifier applies to all argument types. The meaning of the
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 3*: Unless a minimum field width is defined, the field width is
310
- determined by the size of the content and the alignment option has no
311
- effect. *end note*]
 
 
 
 
 
 
312
 
313
  **Table: Meaning of align options** <a id="format.align">[format.align]</a>
314
 
315
  | Option | Meaning |
316
- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
317
- | `<` | Forces the field to be aligned to the start of the available space. This is the default for non-arithmetic types, `charT`, and `bool`, unless an integer presentation type is specified. |
318
- | % `>` | Forces the field to be aligned to the end of the available space. This is the default for arithmetic types other than `charT` and `bool` or when an integer presentation type is specified. |
319
- | % `^` | Forces the field to be centered within the available space by inserting $\bigl\lfloor \frac{n}{2} \bigr\rfloor$ characters before and $\bigl\lceil \frac{n}{2} \bigr\rceil$ characters after the value, where $n$ is the total number of fill characters to insert. |
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
- [*Note 4*: For negative numbers and negative zero the output of
327
- `to_chars` will already contain the sign so no additional transformation
328
- is performed. — *end note*]
 
 
 
 
 
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
- If `{ \opt{arg-id} }` is used in a *width* or *precision*, the value of
359
- the corresponding formatting argument is used in its place. If the
360
- corresponding formatting argument is not of integral type, or its value
361
- is negative for *precision* or non-positive for *width*, an exception of
362
- type `format_error` is thrown.
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 is ignored because of < alignment)
 
423
  ```
424
 
425
  — *end example*]
426
 
427
- The *nonnegative-integer* in *precision* is a decimal integer defining
428
- the precision or maximum field size. It can only be used with
429
- floating-point and string types. For floating-point types this field
430
- specifies the formatting precision. For string types, this field
431
- provides an upper bound for the estimated width of the prefix of the
432
- input string that is copied into the output. For a string in a Unicode
433
- encoding, the formatter copies to the output the longest prefix of whole
434
- extended grapheme clusters whose estimated width is no greater than the
435
- precision.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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 7*: Additional padding and adjustments are performed prior to
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 might be "1,234"
485
  // (depending on the locale)
486
  ```
487
 
488
  — *end example*]
489
 
490
- [*Note 8*: If the formatting argument type is `charT` or `bool`, the
491
- default is instead `c` or `s`, respectively. — *end note*]
 
 
 
 
 
 
 
 
 
 
 
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`, `c`, `d`, `o`, `x`, `X` | As specified in [[format.type.int]] for the value `static_cast<unsigned char>(value)`. |
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 9*: In either case, a sign is included if indicated by the
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 10*: Pointer presentation types also apply to
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` added to the output; otherwise, implementation-defined. |
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(string_view fmt, const Args&... args);
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(wstring_view fmt, const Args&... args);
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, string_view fmt, const Args&... args);
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, wstring_view fmt, const Args&... args);
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, string_view fmt, const Args&... args);
 
 
 
 
 
 
 
 
 
628
  template<class Out, class... Args>
629
- Out format_to(Out out, wstring_view fmt, const Args&... args);
630
  ```
631
 
632
  *Effects:* Equivalent to:
633
 
634
  ``` cpp
635
- using context = basic_format_context<Out, decltype(fmt)::value_type>;
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, string_view fmt, const Args&... args);
 
 
 
 
 
 
 
 
 
642
  template<class Out, class... Args>
643
- Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
644
  ```
645
 
646
  *Effects:* Equivalent to:
647
 
648
  ``` cpp
649
- using context = basic_format_context<Out, decltype(fmt)::value_type>;
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
- `formatted_size(fmt, args...)` for the functions without a `loc`
678
- parameter and `formatted_size(loc, fmt, args...)` for the functions with
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
- string_view fmt, const Args&... args);
690
  template<class Out, class... Args>
691
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
692
- wstring_view fmt, const Args&... args);
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, string_view fmt,
696
- const Args&... args);
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, wstring_view fmt,
700
- const Args&... args);
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(string_view fmt, const Args&... args);
729
  template<class... Args>
730
- size_t formatted_size(wstring_view fmt, const Args&... args);
731
  template<class... Args>
732
- size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
733
  template<class... Args>
734
- size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
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
- - *Cpp17CopyAssignable* ([[cpp17.copyassignable]]), and
 
758
  - *Cpp17Destructible* ([[cpp17.destructible]])
759
 
760
- requirements,
761
- - it is swappable [[swappable.requirements]] for lvalues, and
762
- - the expressions shown in [[formatter]] are valid and have the
763
- indicated semantics.
 
 
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
- [*Note 1*: Enabled specializations meet the requirements, and disabled
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<const charT[N], charT>;
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 2*: Specializations such as `formatter<wchar_t, char>` and
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 except as noted
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` which indicates mixing
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` which indicates
974
- mixing of automatic and manual argument indexing.
975
 
976
- *Remarks:* Call expressions where `id >= num_args_` are not core
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
- [*Note 1*: For a given type `charT`, implementations are encouraged to
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
- *Returns:* `out_`.
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(const T& v) noexcept; // exposition only
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(const T& v) noexcept;
1148
  ```
1149
 
1150
- *Constraints:* The template specialization
1151
 
1152
- ``` cpp
1153
- typename Context::template formatter_type<T>
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
- - if `T` is `bool` or `char_type`, initializes `value` with `v`;
1170
- - otherwise, if `T` is `char` and `char_type` is `wchar_t`, initializes
1171
  `value` with `static_cast<wchar_t>(v)`;
1172
- - otherwise, if `T` is a signed integer type [[basic.fundamental]] and
1173
- `sizeof(T) <= sizeof(int)`, initializes `value` with
1174
  `static_cast<int>(v)`;
1175
- - otherwise, if `T` is an unsigned integer type and
1176
- `sizeof(T) <= sizeof(unsigned int)`, initializes `value` with
1177
  `static_cast<unsigned int>(v)`;
1178
- - otherwise, if `T` is a signed integer type and
1179
- `sizeof(T) <= sizeof(long long int)`, initializes `value` with
1180
  `static_cast<long long int>(v)`;
1181
- - otherwise, if `T` is an unsigned integer type and
1182
- `sizeof(T) <= sizeof(unsigned long long int)`, initializes `value`
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(const T& val) noexcept; // exposition only
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(const T& val) noexcept;
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<T> f;
1272
  parse_ctx.advance_to(f.parse(parse_ctx));
1273
- format_ctx.advance_to(f.format(*static_cast<const T*>(ptr), format_ctx));
 
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
- see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
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
- struct format-arg-store { // exposition only
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(const Args&... args);
1307
  ```
1308
 
1309
  *Preconditions:* The type
1310
- `typename Context::template formatter_type<``Tᵢ``>` meets the
1311
- requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
 
1312
 
1313
- *Returns:* `{basic_format_arg<Context>(args)...}`.
 
 
1314
 
1315
  ``` cpp
1316
  template<class... Args>
1317
- format-arg-store<wformat_context, Args...> make_wformat_args(const Args&... 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
- [*Note 1*: Implementations are encouraged to optimize the
1367
- representation of `basic_format_args` for small number of formatting
1368
- arguments by storing indices of type alternatives separately from values
1369
- and packing the former. *end note*]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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