From Jason Turner

[format.arguments]

C++20 → C++23 10.8 KB 177 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/tmpi81mvg_h/{from.md → to.md} +59 -110
tmp/tmpi81mvg_h/{from.md → to.md} RENAMED
@@ -16,28 +16,11 @@ namespace std {
16
  int, unsigned int, long long int, unsigned long long int,
17
  float, double, long double,
18
  const char_type*, basic_string_view<char_type>,
19
  const void*, handle> value; // exposition only
20
 
21
- template<class T> explicit basic_format_arg(const T& v) noexcept; // exposition only
22
- explicit basic_format_arg(float n) noexcept; // exposition only
23
- explicit basic_format_arg(double n) noexcept; // exposition only
24
- explicit basic_format_arg(long double n) noexcept; // exposition only
25
- explicit basic_format_arg(const char_type* s); // exposition only
26
-
27
- template<class traits>
28
- explicit basic_format_arg(
29
- basic_string_view<char_type, traits> s) noexcept; // exposition only
30
-
31
- template<class traits, class Allocator>
32
- explicit basic_format_arg(
33
- const basic_string<char_type, traits, Allocator>& s) noexcept; // exposition only
34
-
35
- explicit basic_format_arg(nullptr_t) noexcept; // exposition only
36
-
37
- template<class T>
38
- explicit basic_format_arg(const T* p) noexcept; // exposition only
39
 
40
  public:
41
  basic_format_arg() noexcept;
42
 
43
  explicit operator bool() const noexcept;
@@ -56,95 +39,47 @@ basic_format_arg() noexcept;
56
  ```
57
 
58
  *Ensures:* `!(*this)`.
59
 
60
  ``` cpp
61
- template<class T> explicit basic_format_arg(const T& v) noexcept;
62
  ```
63
 
64
- *Constraints:* The template specialization
65
 
66
- ``` cpp
67
- typename Context::template formatter_type<T>
68
- ```
69
-
70
- meets the requirements [[formatter.requirements]]. The extent to which
71
- an implementation determines that the specialization meets the
72
- requirements is unspecified, except that as a minimum the expression
73
-
74
- ``` cpp
75
- typename Context::template formatter_type<T>()
76
- .format(declval<const T&>(), declval<Context&>())
77
- ```
78
-
79
- shall be well-formed when treated as an unevaluated operand.
80
 
81
- *Effects:*
82
 
83
- - if `T` is `bool` or `char_type`, initializes `value` with `v`;
84
- - otherwise, if `T` is `char` and `char_type` is `wchar_t`, initializes
85
  `value` with `static_cast<wchar_t>(v)`;
86
- - otherwise, if `T` is a signed integer type [[basic.fundamental]] and
87
- `sizeof(T) <= sizeof(int)`, initializes `value` with
88
  `static_cast<int>(v)`;
89
- - otherwise, if `T` is an unsigned integer type and
90
- `sizeof(T) <= sizeof(unsigned int)`, initializes `value` with
91
  `static_cast<unsigned int>(v)`;
92
- - otherwise, if `T` is a signed integer type and
93
- `sizeof(T) <= sizeof(long long int)`, initializes `value` with
94
  `static_cast<long long int>(v)`;
95
- - otherwise, if `T` is an unsigned integer type and
96
- `sizeof(T) <= sizeof(unsigned long long int)`, initializes `value`
97
  with `static_cast<unsigned long long int>(v)`;
 
 
 
 
 
 
 
 
 
 
98
  - otherwise, initializes `value` with `handle(v)`.
99
 
100
- ``` cpp
101
- explicit basic_format_arg(float n) noexcept;
102
- explicit basic_format_arg(double n) noexcept;
103
- explicit basic_format_arg(long double n) noexcept;
104
- ```
105
-
106
- *Effects:* Initializes `value` with `n`.
107
-
108
- ``` cpp
109
- explicit basic_format_arg(const char_type* s);
110
- ```
111
-
112
- *Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
113
-
114
- *Effects:* Initializes `value` with `s`.
115
-
116
- ``` cpp
117
- template<class traits>
118
- explicit basic_format_arg(basic_string_view<char_type, traits> s) noexcept;
119
- ```
120
-
121
- *Effects:* Initializes `value` with `s`.
122
-
123
- ``` cpp
124
- template<class traits, class Allocator>
125
- explicit basic_format_arg(
126
- const basic_string<char_type, traits, Allocator>& s) noexcept;
127
- ```
128
-
129
- *Effects:* Initializes `value` with
130
- `basic_string_view<char_type>(s.data(), s.size())`.
131
-
132
- ``` cpp
133
- explicit basic_format_arg(nullptr_t) noexcept;
134
- ```
135
-
136
- *Effects:* Initializes `value` with `static_cast<const void*>(nullptr)`.
137
-
138
- ``` cpp
139
- template<class T> explicit basic_format_arg(const T* p) noexcept;
140
- ```
141
-
142
- *Constraints:* `is_void_v<T>` is `true`.
143
-
144
- *Effects:* Initializes `value` with `p`.
145
-
146
  [*Note 1*: Constructing `basic_format_arg` from a pointer to a member
147
  is ill-formed unless the user provides an enabled specialization of
148
  `formatter` for that pointer to member type. — *end note*]
149
 
150
  ``` cpp
@@ -161,32 +96,41 @@ namespace std {
161
  class basic_format_arg<Context>::handle {
162
  const void* ptr_; // exposition only
163
  void (*format_)(basic_format_parse_context<char_type>&,
164
  Context&, const void*); // exposition only
165
 
166
- template<class T> explicit handle(const T& val) noexcept; // exposition only
167
 
168
  friend class basic_format_arg<Context>; // exposition only
169
 
170
  public:
171
  void format(basic_format_parse_context<char_type>&, Context& ctx) const;
172
  };
173
  }
174
  ```
175
 
176
  ``` cpp
177
- template<class T> explicit handle(const T& val) noexcept;
178
  ```
179
 
 
 
 
 
 
 
 
 
180
  *Effects:* Initializes `ptr_` with `addressof(val)` and `format_` with
181
 
182
  ``` cpp
183
  [](basic_format_parse_context<char_type>& parse_ctx,
184
  Context& format_ctx, const void* ptr) {
185
- typename Context::template formatter_type<T> f;
186
  parse_ctx.advance_to(f.parse(parse_ctx));
187
- format_ctx.advance_to(f.format(*static_cast<const T*>(ptr), format_ctx));
 
188
  }
189
  ```
190
 
191
  ``` cpp
192
  void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
@@ -194,43 +138,46 @@ void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ct
194
 
195
  *Effects:* Equivalent to: `format_(parse_ctx, format_ctx, ptr_);`
196
 
197
  ``` cpp
198
  template<class Visitor, class Context>
199
- see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
200
  ```
201
 
202
  *Effects:* Equivalent to:
203
- `return visit(forward<Visitor>(vis), arg.value);`
204
 
205
  #### Class template *`format-arg-store`* <a id="format.arg.store">[[format.arg.store]]</a>
206
 
207
  ``` cpp
208
  namespace std {
209
  template<class Context, class... Args>
210
- struct format-arg-store { // exposition only
211
- array<basic_format_arg<Context>, sizeof...(Args)> args;
212
  };
213
  }
214
  ```
215
 
216
  An instance of *`format-arg-store`* stores formatting arguments.
217
 
218
  ``` cpp
219
  template<class Context = format_context, class... Args>
220
- format-arg-store<Context, Args...> make_format_args(const Args&... args);
221
  ```
222
 
223
  *Preconditions:* The type
224
- `typename Context::template formatter_type<``Tᵢ``>` meets the
225
- requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
 
226
 
227
- *Returns:* `{basic_format_arg<Context>(args)...}`.
 
 
228
 
229
  ``` cpp
230
  template<class... Args>
231
- format-arg-store<wformat_context, Args...> make_wformat_args(const Args&... args);
232
  ```
233
 
234
  *Effects:* Equivalent to:
235
  `return make_format_args<wformat_context>(args...);`
236
 
@@ -249,15 +196,22 @@ namespace std {
249
  template<class... Args>
250
  basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
251
 
252
  basic_format_arg<Context> get(size_t i) const noexcept;
253
  };
 
 
 
254
  }
255
  ```
256
 
257
  An instance of `basic_format_args` provides access to formatting
258
- arguments.
 
 
 
 
259
 
260
  ``` cpp
261
  basic_format_args() noexcept;
262
  ```
263
 
@@ -275,10 +229,5 @@ template<class... Args>
275
  basic_format_arg<Context> get(size_t i) const noexcept;
276
  ```
277
 
278
  *Returns:* `i < size_ ? data_[i] : basic_format_arg<Context>()`.
279
 
280
- [*Note 1*: Implementations are encouraged to optimize the
281
- representation of `basic_format_args` for small number of formatting
282
- arguments by storing indices of type alternatives separately from values
283
- and packing the former. — *end note*]
284
-
 
16
  int, unsigned int, long long int, unsigned long long int,
17
  float, double, long double,
18
  const char_type*, basic_string_view<char_type>,
19
  const void*, handle> value; // exposition only
20
 
21
+ template<class T> explicit basic_format_arg(T& v) noexcept; // exposition only
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
22
 
23
  public:
24
  basic_format_arg() noexcept;
25
 
26
  explicit operator bool() const noexcept;
 
39
  ```
40
 
41
  *Ensures:* `!(*this)`.
42
 
43
  ``` cpp
44
+ template<class T> explicit basic_format_arg(T& v) noexcept;
45
  ```
46
 
47
+ *Constraints:* `T` satisfies `formattable-with<Context>`.
48
 
49
+ *Preconditions:* If `decay_t<T>` is `char_type*` or `const char_type*`,
50
+ `static_cast<const char_type*>(v)` points to a NTCTS [[defns.ntcts]].
 
 
 
 
 
 
 
 
 
 
 
 
51
 
52
+ *Effects:* Let `TD` be `remove_const_t<T>`.
53
 
54
+ - If `TD` is `bool` or `char_type`, initializes `value` with `v`;
55
+ - otherwise, if `TD` is `char` and `char_type` is `wchar_t`, initializes
56
  `value` with `static_cast<wchar_t>(v)`;
57
+ - otherwise, if `TD` is a signed integer type [[basic.fundamental]] and
58
+ `sizeof(TD) <= sizeof(int)`, initializes `value` with
59
  `static_cast<int>(v)`;
60
+ - otherwise, if `TD` is an unsigned integer type and
61
+ `sizeof(TD) <= sizeof(unsigned int)`, initializes `value` with
62
  `static_cast<unsigned int>(v)`;
63
+ - otherwise, if `TD` is a signed integer type and
64
+ `sizeof(TD) <= sizeof(long long int)`, initializes `value` with
65
  `static_cast<long long int>(v)`;
66
+ - otherwise, if `TD` is an unsigned integer type and
67
+ `sizeof(TD) <= sizeof(unsigned long long int)`, initializes `value`
68
  with `static_cast<unsigned long long int>(v)`;
69
+ - otherwise, if `TD` is a standard floating-point type, initializes
70
+ `value` with `v`;
71
+ - otherwise, if `TD` is a specialization of `basic_string_view` or
72
+ `basic_string` and `TD::value_type` is `char_type`, initializes
73
+ `value` with `basic_string_view<char_type>(v.data(), v.size())`;
74
+ - otherwise, if `decay_t<TD>` is `char_type*` or `const char_type*`,
75
+ initializes `value` with `static_cast<const char_type*>(v)`;
76
+ - otherwise, if `is_void_v<remove_pointer_t<TD>>` is `true` or
77
+ `is_null_pointer_v<TD>` is `true`, initializes `value` with
78
+ `static_cast<const void*>(v)`;
79
  - otherwise, initializes `value` with `handle(v)`.
80
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
81
  [*Note 1*: Constructing `basic_format_arg` from a pointer to a member
82
  is ill-formed unless the user provides an enabled specialization of
83
  `formatter` for that pointer to member type. — *end note*]
84
 
85
  ``` cpp
 
96
  class basic_format_arg<Context>::handle {
97
  const void* ptr_; // exposition only
98
  void (*format_)(basic_format_parse_context<char_type>&,
99
  Context&, const void*); // exposition only
100
 
101
+ template<class T> explicit handle(T& val) noexcept; // exposition only
102
 
103
  friend class basic_format_arg<Context>; // exposition only
104
 
105
  public:
106
  void format(basic_format_parse_context<char_type>&, Context& ctx) const;
107
  };
108
  }
109
  ```
110
 
111
  ``` cpp
112
+ template<class T> explicit handle(T& val) noexcept;
113
  ```
114
 
115
+ Let
116
+
117
+ - `TD` be `remove_const_t<T>`,
118
+ - `TQ` be `const TD` if `const TD` satisfies `formattable-with<Context>`
119
+ and `TD` otherwise.
120
+
121
+ *Mandates:* `TQ` satisfies `formattable-with<Context>`.
122
+
123
  *Effects:* Initializes `ptr_` with `addressof(val)` and `format_` with
124
 
125
  ``` cpp
126
  [](basic_format_parse_context<char_type>& parse_ctx,
127
  Context& format_ctx, const void* ptr) {
128
+ typename Context::template formatter_type<TD> f;
129
  parse_ctx.advance_to(f.parse(parse_ctx));
130
+ format_ctx.advance_to(f.format(*const_cast<TQ*>(static_cast<const TD*>(ptr)),
131
+ format_ctx));
132
  }
133
  ```
134
 
135
  ``` cpp
136
  void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
 
138
 
139
  *Effects:* Equivalent to: `format_(parse_ctx, format_ctx, ptr_);`
140
 
141
  ``` cpp
142
  template<class Visitor, class Context>
143
+ decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
144
  ```
145
 
146
  *Effects:* Equivalent to:
147
+ `return visit(std::forward<Visitor>(vis), arg.value);`
148
 
149
  #### Class template *`format-arg-store`* <a id="format.arg.store">[[format.arg.store]]</a>
150
 
151
  ``` cpp
152
  namespace std {
153
  template<class Context, class... Args>
154
+ class format-arg-store { // exposition only
155
+ array<basic_format_arg<Context>, sizeof...(Args)> args; // exposition only
156
  };
157
  }
158
  ```
159
 
160
  An instance of *`format-arg-store`* stores formatting arguments.
161
 
162
  ``` cpp
163
  template<class Context = format_context, class... Args>
164
+ format-arg-store<Context, Args...> make_format_args(Args&&... fmt_args);
165
  ```
166
 
167
  *Preconditions:* The type
168
+ `typename Context::template formatter_type<remove_cvref_t<``Tᵢ``>>`
169
+ meets the requirements [[formatter.requirements]] for each `Tᵢ` in
170
+ `Args`.
171
 
172
+ *Returns:* An object of type *`format-arg-store`*`<Context, Args...>`
173
+ whose *args* data member is initialized with
174
+ `{basic_format_arg<Context>(fmt_args)...}`.
175
 
176
  ``` cpp
177
  template<class... Args>
178
+ format-arg-store<wformat_context, Args...> make_wformat_args(Args&&... args);
179
  ```
180
 
181
  *Effects:* Equivalent to:
182
  `return make_format_args<wformat_context>(args...);`
183
 
 
196
  template<class... Args>
197
  basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
198
 
199
  basic_format_arg<Context> get(size_t i) const noexcept;
200
  };
201
+
202
+ template<class Context, class... Args>
203
+ basic_format_args(format-arg-store<Context, Args...>) -> basic_format_args<Context>;
204
  }
205
  ```
206
 
207
  An instance of `basic_format_args` provides access to formatting
208
+ arguments. Implementations should optimize the representation of
209
+ `basic_format_args` for a small number of formatting arguments.
210
+
211
+ [*Note 1*: For example, by storing indices of type alternatives
212
+ separately from values and packing the former. — *end note*]
213
 
214
  ``` cpp
215
  basic_format_args() noexcept;
216
  ```
217
 
 
229
  basic_format_arg<Context> get(size_t i) const noexcept;
230
  ```
231
 
232
  *Returns:* `i < size_ ? data_[i] : basic_format_arg<Context>()`.
233