Skip to content

Commit be77cdb

Browse files
vitautvitaut
committed
Update paper
1 parent aa28c3d commit be77cdb

File tree

2 files changed

+73
-24
lines changed

2 files changed

+73
-24
lines changed

‎papers/p3395.bs‎

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
<pre class='metadata'>
22
Title: Fix encoding issues and add a formatter for std::error_code
33
Shortname: P3395
4-
Revision: 1
4+
Revision: 2
55
Audience: LEWG
66
Status: P
77
Group: WG21
88
URL:
99
Editor: Victor Zverovich, victor.zverovich@gmail.com
1010
No abstract: true
11-
Date: 2025-03-12
11+
Date: 2025-03-17
1212
Markup Shorthands: markdown yes
1313
</pre>
1414

@@ -32,6 +32,12 @@ This paper proposes making `std::error_code` formattable using the formatting
3232
facility introduced in C++20 (`std::format`) and fixes encoding issues in the
3333
underlying API ([[LWG4156]]).
3434

35+
Changes since R1 {#changes1}
36+
================
37+
38+
- Added a debug format to avoid ambiguity when formatting error codes in maps.
39+
- Added SG16 poll results.
40+
3541
Changes since R0 {#changes0}
3642
================
3743

@@ -44,7 +50,22 @@ Changes since R0 {#changes0}
4450
literal encoding is not UTF-8 per SG16 feedback and for consistency with
4551
other similar cases in the standard.
4652

47-
<!-- TODO: add SG16 poll results -->
53+
Polls {#polls}
54+
=====
55+
56+
SG16 poll results for R0:
57+
58+
**Poll 1**: Forward P3395R0 to LEWG amended to specify an encoding for
59+
`std::error_category::name()` and for transcoding to be to UTF-8 if that
60+
matches the ordinary literal encoding and to an implementation-defined encoding
61+
otherwise.
62+
63+
```text
64+
SF F N A SA
65+
1 6 0 0 0
66+
```
67+
68+
Outcome: Strong consensus.
4869

4970
Motivation {#motivation}
5071
==========
@@ -244,6 +265,8 @@ Add a new section "Formatting" [system.error.fmt] under "Class `error_code`"
244265

245266
<pre>
246267
template&lt;class charT> struct formatter&lt;error_code, charT> {
268+
constexpr void set_debug_format();
269+
247270
constexpr typename basic_format_parse_context&lt;charT>::iterator
248271
parse(basic_format_parse_context&lt;charT>& ctx);
249272

@@ -254,14 +277,13 @@ template&lt;class charT> struct formatter&lt;error_code, charT> {
254277
</pre>
255278

256279

257-
<!--
258280
```
259281
constexpr void set_debug_format();
260282
```
261283

262284
*Effects*: Modifies the state of the `formatter` to be as if the
263-
*path-format-spec* parsed by the last call to `parse` contained the `?` option.
264-
-->
285+
*error-code-format-spec* parsed by the last call to `parse` contained the
286+
`?` option.
265287

266288
```
267289
constexpr typename basic_format_parse_context<charT>::iterator
@@ -272,10 +294,13 @@ constexpr typename basic_format_parse_context<charT>::iterator
272294
parsed specifiers in `*this`.
273295

274296
<i>error-code-format-spec</i>:<br>
275-
&nbsp;&nbsp;<i>fill-and-align<sub>opt</sub></i> <i>width<sub>opt</sub></i> <code>s</code><i><sub>opt</sub></i>
297+
&nbsp;&nbsp;<i>fill-and-align<sub>opt</sub></i> <i>width<sub>opt</sub></i>
298+
<code>?</code><i><sub>opt</sub></i> <code>s</code><i><sub>opt</sub></i>
276299

277300
where the productions <i>fill-and-align</i> and <i>width</i> are described in
278-
[[format.string](http://eel.is/c++draft/format#string)].
301+
[[format.string](http://eel.is/c++draft/format#string)]. If the `?` option is
302+
used then the path is formatted as an escaped string ([[format.string.escaped](
303+
http://eel.is/c++draft/format.string.escaped)]).
279304

280305
<!-- If the `?` option is
281306
used then the path is formatted as an escaped string ([[format.string.escaped](

‎papers/p3395.html‎

Lines changed: 40 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<head>
33
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
44
<meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport">
5-
<title>P3395R1: Fix encoding issues and add a formatter for std::error_code</title>
5+
<title>P3395R2: Fix encoding issues and add a formatter for std::error_code</title>
66
<style data-fill-with="stylesheet">/******************************************************************************
77
* Style sheet for the W3C specifications *
88
*
@@ -1563,7 +1563,7 @@
15631563
</style>
15641564
<meta content="Bikeshed version 4416b18d5, updated Tue Jan 2 15:52:39 2024 -0800" name="generator">
15651565
<link href="https://isocpp.org/favicon.ico" rel="icon">
1566-
<meta content="44ef9ac3e478d907cdd473d279bb56289847cd4c" name="revision">
1566+
<meta content="aa28c3d0e88e37c31ac5c5b10f18ee513c1c0442" name="revision">
15671567
<style type="text/css">
15681568
td {
15691569
vertical-align: middle;
@@ -2098,8 +2098,8 @@
20982098
<body class="h-entry">
20992099
<div class="head">
21002100
<p data-fill-with="logo"></p>
2101-
<h1 class="p-name no-ref" id="title">P3395R1<br>Fix encoding issues and add a formatter for std::error_code</h1>
2102-
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Published Proposal, <time class="dt-updated" datetime="2025-03-12">2025-03-12</time></span></h2>
2101+
<h1 class="p-name no-ref" id="title">P3395R2<br>Fix encoding issues and add a formatter for std::error_code</h1>
2102+
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Published Proposal, <time class="dt-updated" datetime="2025-03-17">2025-03-17</time></span></h2>
21032103
<div data-fill-with="spec-metadata">
21042104
<dl>
21052105
<dt class="editor">Author:
@@ -2117,11 +2117,13 @@ <h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span cla
21172117
<h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
21182118
<ol class="toc" role="directory">
21192119
<li><a href="#intro"><span class="secno">1</span> <span class="content">Introduction</span></a>
2120-
<li><a href="#changes0"><span class="secno">2</span> <span class="content">Changes since R0</span></a>
2121-
<li><a href="#motivation"><span class="secno">3</span> <span class="content">Motivation</span></a>
2122-
<li><a href="#proposal"><span class="secno">4</span> <span class="content">Proposal</span></a>
2123-
<li><a href="#wording"><span class="secno">5</span> <span class="content">Wording</span></a>
2124-
<li><a href="#impl"><span class="secno">6</span> <span class="content">Implementation</span></a>
2120+
<li><a href="#changes1"><span class="secno">2</span> <span class="content">Changes since R1</span></a>
2121+
<li><a href="#changes0"><span class="secno">3</span> <span class="content">Changes since R0</span></a>
2122+
<li><a href="#polls"><span class="secno">4</span> <span class="content">Polls</span></a>
2123+
<li><a href="#motivation"><span class="secno">5</span> <span class="content">Motivation</span></a>
2124+
<li><a href="#proposal"><span class="secno">6</span> <span class="content">Proposal</span></a>
2125+
<li><a href="#wording"><span class="secno">7</span> <span class="content">Wording</span></a>
2126+
<li><a href="#impl"><span class="secno">8</span> <span class="content">Implementation</span></a>
21252127
<li>
21262128
<a href="#references"><span class="secno"></span> <span class="content">References</span></a>
21272129
<ol class="toc">
@@ -2134,7 +2136,14 @@ <h2 class="heading settled" data-level="1" id="intro"><span class="secno">1. </s
21342136
<p>This paper proposes making <code class="highlight"><c- n>std</c-><c- o>::</c-><c- n>error_code</c-></code> formattable using the formatting
21352137
facility introduced in C++20 (<code class="highlight"><c- n>std</c-><c- o>::</c-><c- n>format</c-></code>) and fixes encoding issues in the
21362138
underlying API (<a data-link-type="biblio" href="#biblio-lwg4156" title="`error_category` messages have unspecified encoding">[LWG4156]</a>).</p>
2137-
<h2 class="heading settled" data-level="2" id="changes0"><span class="secno">2. </span><span class="content">Changes since R0</span><a class="self-link" href="#changes0"></a></h2>
2139+
<h2 class="heading settled" data-level="2" id="changes1"><span class="secno">2. </span><span class="content">Changes since R1</span><a class="self-link" href="#changes1"></a></h2>
2140+
<ul>
2141+
<li data-md>
2142+
<p>Added a debug format to avoid ambiguity when formatting error codes in maps.</p>
2143+
<li data-md>
2144+
<p>Added SG16 poll results.</p>
2145+
</ul>
2146+
<h2 class="heading settled" data-level="3" id="changes0"><span class="secno">3. </span><span class="content">Changes since R0</span><a class="self-link" href="#changes0"></a></h2>
21382147
<ul>
21392148
<li data-md>
21402149
<p>Changed the title from "Formatting of std::error_code" to "Fix encoding
@@ -2148,7 +2157,16 @@ <h2 class="heading settled" data-level="2" id="changes0"><span class="secno">2.
21482157
literal encoding is not UTF-8 per SG16 feedback and for consistency with
21492158
other similar cases in the standard.</p>
21502159
</ul>
2151-
<h2 class="heading settled" data-level="3" id="motivation"><span class="secno">3. </span><span class="content">Motivation</span><a class="self-link" href="#motivation"></a></h2>
2160+
<h2 class="heading settled" data-level="4" id="polls"><span class="secno">4. </span><span class="content">Polls</span><a class="self-link" href="#polls"></a></h2>
2161+
<p>SG16 poll results for R0:</p>
2162+
<p><strong>Poll 1</strong>: Forward P3395R0 to LEWG amended to specify an encoding for <code class="highlight"><c- n>std</c-><c- o>::</c-><c- n>error_category</c-><c- o>::</c-><c- n>name</c-><c- p>()</c-></code> and for transcoding to be to UTF-8 if that
2163+
matches the ordinary literal encoding and to an implementation-defined encoding
2164+
otherwise.</p>
2165+
<pre class="language-text highlight">SF F N A SA
2166+
1 6 0 0 0
2167+
</pre>
2168+
<p>Outcome: Strong consensus.</p>
2169+
<h2 class="heading settled" data-level="5" id="motivation"><span class="secno">5. </span><span class="content">Motivation</span><a class="self-link" href="#motivation"></a></h2>
21522170
<p><code class="highlight"><c- n>error_code</c-></code> has a rudimentary <code class="highlight"><c- n>ostream</c-></code> inserter. For example:</p>
21532171
<pre class="highlight"><c- n>std</c-><c- o>::</c-><c- n>error_code</c-> <c- n>ec</c-><c- p>;</c->
21542172
<c- k>auto</c-> <c- n>size</c-> <c- o>=</c-> <c- n>std</c-><c- o>::</c-><c- n>filesystem</c-><c- o>::</c-><c- n>file_size</c-><c- p>(</c-><c- s>"nonexistent"</c-><c- p>,</c-> <c- n>ec</c-><c- p>);</c->
@@ -2168,7 +2186,7 @@ <h2 class="heading settled" data-level="3" id="motivation"><span class="secno">3
21682186
</pre>
21692187
<p>Additionally, it doesn’t allow formatting the error message and introduces
21702188
potential encoding issues, as the encoding of the category name is unspecified.</p>
2171-
<h2 class="heading settled" data-level="4" id="proposal"><span class="secno">4. </span><span class="content">Proposal</span><a class="self-link" href="#proposal"></a></h2>
2189+
<h2 class="heading settled" data-level="6" id="proposal"><span class="secno">6. </span><span class="content">Proposal</span><a class="self-link" href="#proposal"></a></h2>
21722190
<p>This paper proposes adding a <code class="highlight"><c- n>formatter</c-></code> specialization for <code class="highlight"><c- n>std</c-><c- o>::</c-><c- n>error_code</c-></code> to address the problems discussed in the previous section.</p>
21732191
<p>The default format will produce the same output as the <code class="highlight"><c- n>ostream</c-></code> inserter:</p>
21742192
<pre class="highlight"><c- n>std</c-><c- o>::</c-><c- n>print</c-><c- p>(</c-><c- s>"{}</c-><c- se>\n</c-><c- s>"</c-><c- p>,</c-> <c- n>ec</c-><c- p>);</c->
@@ -2231,13 +2249,15 @@ <h2 class="heading settled" data-level="4" id="proposal"><span class="secno">4.
22312249
likely need to change anyway. This also resolves <a data-link-type="biblio" href="#biblio-lwg4156" title="`error_category` messages have unspecified encoding">[LWG4156]</a>.</p>
22322250
<p>An alternative approach could involve communicating the encoding from <code class="highlight"><c- n>error_category</c-></code>. However, this introduces ABI challenges and complicates usage
22332251
compared to adopting a single encoding.</p>
2234-
<h2 class="heading settled" data-level="5" id="wording"><span class="secno">5. </span><span class="content">Wording</span><a class="self-link" href="#wording"></a></h2>
2252+
<h2 class="heading settled" data-level="7" id="wording"><span class="secno">7. </span><span class="content">Wording</span><a class="self-link" href="#wording"></a></h2>
22352253
<p>Add to "Header &lt;system_error> synopsis" <a href="https://eel.is/c++draft/system.error.syn">[system.error.syn</a>]:</p>
22362254
<pre class="highlight"><c- c1>// [system.error.fmt], formatter</c->
22372255
<c- k>template</c-><c- o>&lt;</c-><c- k>class</c-> <c- nc>charT</c-><c- o>></c-> <c- k>struct</c-> <c- nc>formatter</c-><c- o>&lt;</c-><c- n>error_code</c-><c- p>,</c-> <c- n>charT</c-><c- o>></c-><c- p>;</c->
22382256
</pre>
22392257
<p>Add a new section "Formatting" [system.error.fmt] under "Class <code class="highlight"><c- n>error_code</c-></code>" <a href="https://eel.is/c++draft/syserr.errcode">[syserr.errcode</a>]:</p>
22402258
<pre class="highlight"><c- k>template</c-><c- o>&lt;</c-><c- k>class</c-> <c- nc>charT</c-><c- o>></c-> <c- k>struct</c-> <c- nc>formatter</c-><c- o>&lt;</c-><c- n>error_code</c-><c- p>,</c-> <c- n>charT</c-><c- o>></c-> <c- p>{</c->
2259+
<c- k>constexpr</c-> <c- b>void</c-> <c- nf>set_debug_format</c-><c- p>();</c->
2260+
22412261
<c- k>constexpr</c-> <c- k>typename</c-> <c- nc>basic_format_parse_context</c-><c- o>&lt;</c-><c- n>charT</c-><c- o>>::</c-><c- n>iterator</c->
22422262
<c- n>parse</c-><c- p>(</c-><c- n>basic_format_parse_context</c-><c- o>&lt;</c-><c- n>charT</c-><c- o>>&amp;</c-> <c- n>ctx</c-><c- p>);</c->
22432263

@@ -2246,13 +2266,17 @@ <h2 class="heading settled" data-level="5" id="wording"><span class="secno">5. <
22462266
<c- n>format</c-><c- p>(</c-><c- k>const</c-> <c- n>error_code</c-><c- o>&amp;</c-> <c- n>ec</c-><c- p>,</c-> <c- n>FormatContext</c-><c- o>&amp;</c-> <c- n>ctx</c-><c- p>)</c-> <c- k>const</c-><c- p>;</c->
22472267
<c- p>};</c->
22482268
</pre>
2269+
<pre class="highlight"><c- k>constexpr</c-> <c- b>void</c-> <c- nf>set_debug_format</c-><c- p>();</c->
2270+
</pre>
2271+
<p><em>Effects</em>: Modifies the state of the <code class="highlight"><c- n>formatter</c-></code> to be as if the <em>error-code-format-spec</em> parsed by the last call to <code class="highlight"><c- n>parse</c-></code> contained the <code class="highlight"><c- o>?</c-></code> option.</p>
22492272
<pre class="highlight"><c- k>constexpr</c-> <c- k>typename</c-> <c- nc>basic_format_parse_context</c-><c- o>&lt;</c-><c- n>charT</c-><c- o>>::</c-><c- n>iterator</c->
22502273
<c- n>parse</c-><c- p>(</c-><c- n>basic_format_parse_context</c-><c- o>&lt;</c-><c- n>charT</c-><c- o>>&amp;</c-> <c- n>ctx</c-><c- p>);</c->
22512274
</pre>
22522275
<p><em>Effects</em>: Parses the format specifier as a <em>error-code-format-spec</em> and stores the
22532276
parsed specifiers in <code class="highlight"><c- o>*</c-><c- k>this</c-></code>.</p>
2254-
<p><i>error-code-format-spec</i>:<br>   <i>fill-and-align<sub>opt</sub></i> <i>width<sub>opt</sub></i> <code class="highlight"><c- n>s</c-></code><i><sub>opt</sub></i></p>
2255-
<p>where the productions <i>fill-and-align</i> and <i>width</i> are described in <a href="http://eel.is/c++draft/format#string">[format.string</a>].</p>
2277+
<p><i>error-code-format-spec</i>:<br>   <i>fill-and-align<sub>opt</sub></i> <i>width<sub>opt</sub></i> <code class="highlight"><c- o>?</c-></code><i><sub>opt</sub></i> <code class="highlight"><c- n>s</c-></code><i><sub>opt</sub></i></p>
2278+
<p>where the productions <i>fill-and-align</i> and <i>width</i> are described in <a href="http://eel.is/c++draft/format#string">[format.string</a>]. If the <code class="highlight"><c- o>?</c-></code> option is
2279+
used then the path is formatted as an escaped string (<a href="http://eel.is/c++draft/format.string.escaped">[format.string.escaped</a>]).</p>
22562280
<p><em>Returns</em>: An iterator past the end of the <em>error-code-format-spec</em>.</p>
22572281
<pre class="highlight"><c- k>template</c-><c- o>&lt;</c-><c- k>class</c-> <c- nc>FormatContext</c-><c- o>></c->
22582282
<c- k>typename</c-> <c- nc>FormatContext</c-><c- o>::</c-><c- n>iterator</c->
@@ -2289,7 +2313,7 @@ <h2 class="heading settled" data-level="5" id="wording"><span class="secno">5. <
22892313
set</ins>
22902314
that describes the error condition denoted by <code class="highlight"><c- n>ev</c-></code>.
22912315
</p>
2292-
<h2 class="heading settled" data-level="6" id="impl"><span class="secno">6. </span><span class="content">Implementation</span><a class="self-link" href="#impl"></a></h2>
2316+
<h2 class="heading settled" data-level="8" id="impl"><span class="secno">8. </span><span class="content">Implementation</span><a class="self-link" href="#impl"></a></h2>
22932317
<p>The proposed <code class="highlight"><c- n>formatter</c-></code> for <code class="highlight"><c- n>std</c-><c- o>::</c-><c- n>error_code</c-></code> has been implemented in the
22942318
open-source {fmt} library (<a data-link-type="biblio" href="#biblio-fmt" title="The {fmt} library">[FMT]</a>).</p>
22952319
</main>

0 commit comments

Comments
 (0)