From Jason Turner

[format.range.formatter]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpekn3j6xl/{from.md → to.md} +158 -0
tmp/tmpekn3j6xl/{from.md → to.md} RENAMED
@@ -0,0 +1,158 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #### Class template `range_formatter` <a id="format.range.formatter">[[format.range.formatter]]</a>
2
+
3
+ ``` cpp
4
+ namespace std {
5
+ template<class T, class charT = char>
6
+ requires same_as<remove_cvref_t<T>, T> && formattable<T, charT>
7
+ class range_formatter {
8
+ formatter<T, charT> underlying_; // exposition only
9
+ basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only
10
+ basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("["); // exposition only
11
+ basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>("]"); // exposition only
12
+
13
+ public:
14
+ constexpr void set_separator(basic_string_view<charT> sep) noexcept;
15
+ constexpr void set_brackets(basic_string_view<charT> opening,
16
+ basic_string_view<charT> closing) noexcept;
17
+ constexpr formatter<T, charT>& underlying() noexcept { return underlying_; }
18
+ constexpr const formatter<T, charT>& underlying() const noexcept { return underlying_; }
19
+
20
+ template<class ParseContext>
21
+ constexpr typename ParseContext::iterator
22
+ parse(ParseContext& ctx);
23
+
24
+ template<ranges::input_range R, class FormatContext>
25
+ requires formattable<ranges::range_reference_t<R>, charT> &&
26
+ same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
27
+ typename FormatContext::iterator
28
+ format(R&& r, FormatContext& ctx) const;
29
+ };
30
+ }
31
+ ```
32
+
33
+ The class template `range_formatter` is a utility for implementing
34
+ `formatter` specializations for range types.
35
+
36
+ `range_formatter` interprets *format-spec* as a *range-format-spec*. The
37
+ syntax of format specifications is as follows:
38
+
39
+ ``` bnf
40
+ range-format-spec
41
+ range-fill-and-alignₒₚₜ widthₒₚₜ 'n'ₒₚₜ range-typeₒₚₜ range-underlying-specₒₚₜ
42
+ ```
43
+
44
+ ``` bnf
45
+ range-fill-and-align
46
+ range-fillₒₚₜ align
47
+ ```
48
+
49
+ ``` bnf
50
+ range-fill
51
+ any character other than '{' or '}' or ':'
52
+ ```
53
+
54
+ ``` bnf
55
+ range-type
56
+ 'm'
57
+ 's'
58
+ '?s'
59
+ ```
60
+
61
+ ``` bnf
62
+ range-underlying-spec
63
+ ':' format-spec
64
+ ```
65
+
66
+ For `range_formatter<T, charT>`, the *format-spec* in a
67
+ *range-underlying-spec*, if any, is interpreted by
68
+ `formatter<T, charT>`.
69
+
70
+ The *range-fill-and-align* is interpreted the same way as a
71
+ *fill-and-align* [[format.string.std]]. The productions *align* and
72
+ *width* are described in [[format.string]].
73
+
74
+ The `n` option causes the range to be formatted without the opening and
75
+ closing brackets.
76
+
77
+ [*Note 1*: This is equivalent to invoking
78
+ `set_brackets({}, {})`. — *end note*]
79
+
80
+ The *range-type* specifier changes the way a range is formatted, with
81
+ certain options only valid with certain argument types. The meaning of
82
+ the various type options is as specified in [[formatter.range.type]].
83
+
84
+ **Table: Meaning of range-type options** <a id="formatter.range.type">[formatter.range.type]</a>
85
+
86
+ | Option | Requirements | Meaning |
87
+ | ------ | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
88
+ | % `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.* |
89
+ | % `s` | `T` shall be `charT`. | Indicates that the range should be formatted as a `string`. |
90
+ | % `?s` | `T` shall be `charT`. | Indicates that the range should be formatted as an escaped string [[format.string.escaped]]. |
91
+
92
+
93
+ If the *range-type* is `s` or `?s`, then there shall be no `n` option
94
+ and no *range-underlying-spec*.
95
+
96
+ ``` cpp
97
+ constexpr void set_separator(basic_string_view<charT> sep) noexcept;
98
+ ```
99
+
100
+ *Effects:* Equivalent to: *`separator_`*` = sep;`
101
+
102
+ ``` cpp
103
+ constexpr void set_brackets(basic_string_view<charT> opening,
104
+ basic_string_view<charT> closing) noexcept;
105
+ ```
106
+
107
+ *Effects:* Equivalent to:
108
+
109
+ ``` cpp
110
+ opening-bracket_ = opening;
111
+ closing-bracket_ = closing;
112
+ ```
113
+
114
+ ``` cpp
115
+ template<class ParseContext>
116
+ constexpr typename ParseContext::iterator
117
+ parse(ParseContext& ctx);
118
+ ```
119
+
120
+ *Effects:* Parses the format specifier as a *range-format-spec* and
121
+ stores the parsed specifiers in `*this`. The values of
122
+ *opening-bracket\_*, *closing-bracket\_*, and *separator\_* are modified
123
+ if and only if required by the *range-type* or the `n` option, if
124
+ present. If:
125
+
126
+ - the *range-type* is neither `s` nor `?s`,
127
+ - *`underlying_`*`.set_debug_format()` is a valid expression, and
128
+ - there is no *range-underlying-spec*,
129
+
130
+ then calls *`underlying_`*`.set_debug_format()`.
131
+
132
+ *Returns:* An iterator past the end of the *range-format-spec*.
133
+
134
+ ``` cpp
135
+ template<ranges::input_range R, class FormatContext>
136
+ requires formattable<ranges::range_reference_t<R>, charT> &&
137
+ same_as<remove_cvref_t<ranges::range_reference_t<R>>, T>
138
+ typename FormatContext::iterator
139
+ format(R&& r, FormatContext& ctx) const;
140
+ ```
141
+
142
+ *Effects:* Writes the following into `ctx.out()`, adjusted according to
143
+ the *range-format-spec*:
144
+
145
+ - If the *range-type* was `s`, then as if by formatting
146
+ `basic_string<charT>(from_range, r)`.
147
+ - Otherwise, if the *range-type* was `?s`, then as if by formatting
148
+ `basic_string<charT>(from_range, r)` as an escaped
149
+ string [[format.string.escaped]].
150
+ - Otherwise,
151
+ - *opening-bracket\_*,
152
+ - for each element `e` of the range `r`:
153
+ - the result of writing `e` via *underlying\_* and
154
+ - *separator\_*, unless `e` is the last element of `r`, and
155
+ - *closing-bracket\_*.
156
+
157
+ *Returns:* An iterator past the end of the output range.
158
+