P2845R8 Formatting of std::filesystem::path

Editorial changes:
* Used Oxford commas, and added commas to help the parsing of longer sentences.
* Named the sections "formatter support" for consistency.
* Used "fmtr" instead of "fmt" in section names to avoid confusion
  with existing section names.
* Moved the grammar for path-format-spec into the "general" section,
  and add an introductory half-sentence.

Author: burblebee

source/iostreams.tex

@@ -13456,8 +13456,11 @@
   path weakly_canonical(const path& p, error_code& ec);
 }
 
-// \ref{fs.path.hash}, hash support
 namespace std {
+  // \ref{fs.path.fmtr}, formatting support
+  template<class charT> struct formatter<filesystem::path, charT>;
+
+  // \ref{fs.path.hash}, hash support
   template<class T> struct hash;
   template<> struct hash<filesystem::path>;
 }
@@ -15412,6 +15415,102 @@
 Equivalent to: \tcode{return path(lhs) /= rhs;}
 \end{itemdescr}
 
+\rSec3[fs.path.fmtr]{Formatting support}
+
+\rSec4[fs.path.fmtr.general]{Formatting support overview}
+
+\indexlibraryglobal{formatter}%
+\begin{codeblock}
+namespace std {
+  template<class charT> struct formatter<filesystem::path, charT> {
+    constexpr void set_debug_format();
+
+    constexpr typename basic_format_parse_context<charT>::iterator
+      parse(basic_format_parse_context<charT>& ctx);
+
+    template<class FormatContext>
+      typename FormatContext::iterator
+        format(const filesystem::path& path, FormatContext& ctx) const;
+  };
+}
+\end{codeblock}
+
+\pnum
+Formatting of paths uses formatting specifiers of the form
+\begin{ncbnf}
+\nontermdef{path-format-spec}\br
+    \opt{fill-and-align} \opt{width} \opt{\terminal{?}} \opt{\terminal{g}}
+\end{ncbnf}
+where the productions \fmtgrammarterm{fill-and-align} and \fmtgrammarterm{width}
+are described in \ref{format.string}.
+If the \tcode{?} option is used then
+the path is formatted as an escaped string\iref{format.string.escaped}.
+
+\rSec4[fs.path.fmtr.funcs]{Formatting support functions}
+
+\indexlibrarymember{formatter}{set_debug_format}%
+\begin{itemdecl}
+constexpr void set_debug_format();
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+Modifies the state of the \tcode{formatter} to be as if
+the \fmtgrammarterm{path-format-spec} parsed by the last call to \tcode{parse}
+contained the \tcode{?} option.
+\end{itemdescr}
+
+\indexlibrarymember{formatter}{basic_format_parse_context}%
+\begin{itemdecl}
+constexpr typename basic_format_parse_context<charT>::iterator
+  parse(basic_format_parse_context<charT>& ctx);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+Parses the format specifier as a \fmtgrammarterm{path-format-spec} and
+stores the parsed specifiers in \tcode{*this}.
+
+\pnum
+\returns
+An iterator past the end of the \fmtgrammarterm{path-format-spec}.
+\end{itemdescr}
+
+\indexlibrarymember{formatter}{format}%
+\begin{itemdecl}
+template<class FormatContext>
+  typename FormatContext::iterator
+    format(const filesystem::path& p, FormatContext& ctx) const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+Let \tcode{s} be \tcode{p.generic_string<filesystem::path::value_type>()}
+if the \tcode{g} option is used,
+otherwise \tcode{p.native()}.
+Writes \tcode{s} into \tcode{ctx.out()},
+adjusted according to the \fmtgrammarterm{path-format-spec}.
+If \tcode{charT} is \keyword{char},
+\tcode{path::value_type} is \keyword{wchar_t}, and
+the literal encoding is UTF-8,
+then the escaped path is transcoded from the native encoding for
+wide character strings to UTF-8 with
+maximal subparts of ill-formed subsequences
+substituted with \ucode{fffd} \uname{replacement character}
+per the Unicode Standard, Chapter 3.9 \ucode{fffd} Substitution in Conversion.
+If \tcode{charT} and \tcode{path::value_type} are the same
+then no transcoding is performed.
+Otherwise, transcoding is
+\impldef{transcoding of the escaped path when \tcode{charT} and \tcode{path::value_type} differ}.
+
+\pnum
+\returns
+An iterator past the end of the output range.
+\end{itemdescr}
+
 \rSec3[fs.path.hash]{Hash support}
 
 \begin{itemdecl}

source/support.tex

@@ -634,6 +634,7 @@
 #define @\defnlibxname{cpp_lib_flat_set}@                          202207L // also in \libheader{flat_set}
 #define @\defnlibxname{cpp_lib_format}@                            202311L // also in \libheader{format}
 #define @\defnlibxname{cpp_lib_format_ranges}@                     202207L // also in \libheader{format}
+#define @\defnlibxname{cpp_lib_format_path}@                       202403L // also in \libheader{filesystem}
 #define @\defnlibxname{cpp_lib_format_uchar}@                      202311L // also in \libheader{format}
 #define @\defnlibxname{cpp_lib_formatters}@                        202302L // also in \libheader{stacktrace}, \libheader{thread}
 #define @\defnlibxname{cpp_lib_forward_like}@                      202207L // freestanding, also in \libheader{utility}