diff --git a/source/iostreams.tex b/source/iostreams.tex index 715598e0ba..e865cd8211 100644 --- a/source/iostreams.tex +++ b/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 struct formatter; + + // \ref{fs.path.hash}, hash support template struct hash; template<> struct hash; } @@ -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 struct formatter { + constexpr void set_debug_format(); + + constexpr typename basic_format_parse_context::iterator + parse(basic_format_parse_context& ctx); + + template + typename FormatContext::iterator + format(const filesystem::path& path, FormatContext& ctx) const; + }; +} +\end{codeblock} + +\rSec4[fs.path.fmtr.funcs]{Formatting support functions} + +\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}. + +\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::iterator + parse(basic_format_parse_context& 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 + 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()} +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 a formatted 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} diff --git a/source/support.tex b/source/support.tex index 3e88feb346..b155577b98 100644 --- a/source/support.tex +++ b/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}