Merge 2023-02 LWG Motion 12

tkoeppe · web-flow · commit b973c47b1601 · 2023-03-11T18:30:17.000Z
P2693R1 Formatting thread::id and stacktrace
diff --git a/source/diagnostics.tex b/source/diagnostics.tex
@@ -1744,6 +1744,10 @@
   template<class Allocator>
     ostream& operator<<(ostream& os, const basic_stacktrace<Allocator>& st);
 
+  // \ref{stacktrace.format}, formatting support
+  template<> struct formatter<stacktrace_entry>;
+  template<class Allocator> struct formatter<basic_stacktrace<Allocator>>;
+
   namespace pmr {
     using stacktrace = basic_stacktrace<polymorphic_allocator<stacktrace_entry>>;
   }
@@ -2396,6 +2400,48 @@
 Equivalent to: \tcode{return os << to_string(st);}
 \end{itemdescr}
 
+\rSec3[stacktrace.format]{Formatting support}
+
+\begin{itemdecl}
+template<> struct formatter<stacktrace_entry>;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\tcode{formatter<stacktrace_entry>} interprets \fmtgrammarterm{format-spec}
+as a \fmtgrammarterm{stacktrace-entry-format-spec}.
+The syntax of format specifications is as follows:
+
+\begin{ncbnf}
+\fmtnontermdef{stacktrace-entry-format-spec}\br
+    \opt{fill-and-align} \opt{width}
+\end{ncbnf}
+
+\begin{note}
+The productions \fmtgrammarterm{fill-and-align} and \fmtgrammarterm{width}
+are described in \ref{format.string.std}.
+\end{note}
+
+\pnum
+A \tcode{stacktrace_entry} object \tcode{se} is formatted as if by
+copying \tcode{to_string(se)} through the output iterator of the context
+with additional padding and adjustments as specified by the format specifiers.
+\end{itemdescr}
+
+\begin{itemdecl}
+template<class Allocator> struct formatter<basic_stacktrace<Allocator>>;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+For \tcode{formatter<basic_stacktrace<Allocator>>},
+\fmtgrammarterm{format-spec} is empty.
+
+\pnum
+A \tcode{basic_stacktrace} object \tcode{s} is formatted as if by
+copying \tcode{to_string(s)} through the output iterator of the context.
+\end{itemdescr}
+
 \rSec3[stacktrace.basic.hash]{Hash support}
 
 \begin{itemdecl}
diff --git a/source/macros.tex b/source/macros.tex
@@ -253,6 +253,13 @@
 % Usage: \defnadjx{scalar}{types}{type}
 \newcommand{\defnadjx}[3]{\indextext{#1 #3|see{#3, #1}}\indexdefn{#3!#1}\textit{#1 #2}}
 
+% Macros used for the grammar of std::format format specifications.
+% FIXME: For now, keep the format grammar productions out of the index, since
+% they conflict with the main grammar.
+% Consider renaming these en masse (to fmt-* ?) to avoid this problem.
+\newcommand{\fmtnontermdef}[1]{{\BnfNontermshape#1\itcorr}\textnormal{:}}
+\newcommand{\fmtgrammarterm}[1]{\gterm{#1}}
+
 %%--------------------------------------------------
 %% allow line break if needed for justification
 %%--------------------------------------------------
diff --git a/source/support.tex b/source/support.tex
@@ -624,6 +624,7 @@
 #define @\defnlibxname{cpp_lib_flat_set}@                          202207L // also in \libheader{flat_set}
 #define @\defnlibxname{cpp_lib_format}@                            202207L // also in \libheader{format}
 #define @\defnlibxname{cpp_lib_format_ranges}@                     202207L // also in \libheader{format}
+#define @\defnlibxname{cpp_lib_formatters}@                        202302L // also in \libheader{stacktrace}, \libheader{thread}
 #define @\defnlibxname{cpp_lib_forward_like}@                      202207L // also in \libheader{utility}
 #define @\defnlibxname{cpp_lib_gcd_lcm}@                           201606L // also in \libheader{numeric}
 #define @\defnlibxname{cpp_lib_generator}@                         202207L // also in \libheader{generator}
diff --git a/source/threads.tex b/source/threads.tex
@@ -1204,6 +1204,8 @@
     basic_ostream<charT, traits>&
       operator<<(basic_ostream<charT, traits>& out, thread::id id);
 
+  template<class charT> struct formatter<thread::id, charT>;
+
   // hash support
   template<class T> struct hash;
   template<> struct hash<thread::id>;
@@ -1220,6 +1222,16 @@
 equal to the \tcode{thread::id} object of any \tcode{thread} object that
 does not represent threads of execution.
 
+\pnum
+The \defn{text representation} for
+the character type \tcode{charT} of an object of type \tcode{thread::id}
+is an unspecified sequence of \tcode{charT} such that,
+for two objects of type \tcode{thread::id} \tcode{x} and \tcode{y},
+if \tcode{x == y} is \tcode{true},
+the \tcode{thread::id} objects have the same text representation, and
+if \tcode{x != y} is \tcode{true},
+the \tcode{thread::id} objects have distinct text representations.
+
 \pnum
 \tcode{thread::id} is a trivially copyable class\iref{class.prop}.
 The library may reuse the value of a \tcode{thread::id} of a terminated thread that can no longer be joined.
@@ -1283,17 +1295,44 @@
 \begin{itemdescr}
 \pnum
 \effects
-Inserts an unspecified text representation of \tcode{id} into
-\tcode{out}. For two objects of type \tcode{thread::id} \tcode{x} and \tcode{y},
-if \tcode{x == y} the \tcode{thread::id} objects have the same text
-representation and if \tcode{x != y} the \tcode{thread::id} objects have
-distinct text representations.
+Inserts the text representation for \tcode{charT} of \tcode{id} into
+\tcode{out}.
 
 \pnum
 \returns
 \tcode{out}.
 \end{itemdescr}
 
+\indexlibrary{\idxcode{formatter}!specializations!\idxcode{thread::id}}%
+\begin{itemdecl}
+template<class charT> struct formatter<thread::id, charT>;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\tcode{formatter<thread::id, charT>} interprets \fmtgrammarterm{format-spec}
+as a \fmtgrammarterm{thread-id-format-spec}.
+The syntax of format specifications is as follows:
+
+\begin{ncbnf}
+\fmtnontermdef{thread-id-format-spec}\br
+    \opt{fill-and-align} \opt{width}
+\end{ncbnf}
+
+\begin{note}
+The productions \fmtgrammarterm{fill-and-align} and \fmtgrammarterm{width}
+are described in \ref{format.string.std}.
+\end{note}
+
+\pnum
+If the \fmtgrammarterm{align} option is omitted it defaults to \tcode{>}.
+
+\pnum
+A \tcode{thread::id} object is formatted by
+writing its text representation for \tcode{charT} to the output
+with additional padding and adjustments as specified by the format specifiers.
+\end{itemdescr}
+
 \indexlibrarymember{hash}{thread::id}%
 \begin{itemdecl}
 template<> struct hash<thread::id>;
diff --git a/source/utilities.tex b/source/utilities.tex
@@ -14630,12 +14630,6 @@
 
 \rSec3[format.string.general]{In general}
 
-% FIXME: For now, keep the format grammar productions out of the index, since
-% they conflict with the main grammar.
-% Consider renaming these en masse (to fmt-* ?) to avoid this problem.
-\newcommand{\fmtnontermdef}[1]{{\BnfNontermshape#1\itcorr}\textnormal{:}}
-\newcommand{\fmtgrammarterm}[1]{\gterm{#1}}
-
 \pnum
 A \defn{format string} for arguments \tcode{args} is
 a (possibly empty) sequence of
