Skip to content

[LWG motion 8] P2845R8 Formatting of std::filesystem::path #6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 16, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 100 additions & 1 deletion source/iostreams.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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>;
}
Expand Down Expand Up @@ -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}

\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<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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think "the escaped path" is correct here, but that's what the paper says so I'll ask LWG.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs an LWG issue, the paper is wrong.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I'll leave this with you if that's OK?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now LWG 4070.

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}
Expand Down
1 change: 1 addition & 0 deletions source/support.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down