[fs.class.path] - C++23 → Trunk

Files changed (1) hide show

tmp/tmp0zfuj_dm/{from.md → to.md} +119 -32

tmp/tmp0zfuj_dm/{from.md → to.md} RENAMED Viewed

@@ -36,12 +36,12 @@ Pathnames are formatted according to the generic pathname format grammar
 *Pathname resolution* is the operating system dependent mechanism for
 resolving a pathname to a particular file in a file hierarchy. There may
 be multiple pathnames that resolve to the same file.
-[*Example 1*: POSIX specifies the mechanism in section 4.12, Pathname
-resolution. — *end example*]
 ``` cpp
 namespace std::filesystem {
   class path {
   public:
@@ -124,22 +124,24 @@ namespace std::filesystem {
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         string(const Allocator& a = Allocator()) const;
-    std::string    string() const;
     std::wstring   wstring() const;
     std::u8string  u8string() const;
     std::u16string u16string() const;
     std::u32string u32string() const;
     // [fs.path.generic.obs], generic format observers
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         generic_string(const Allocator& a = Allocator()) const;
-    std::string    generic_string() const;
     std::wstring   generic_wstring() const;
     std::u8string  generic_u8string() const;
     std::u16string generic_u16string() const;
     std::u32string generic_u32string() const;
@@ -158,11 +160,11 @@ namespace std::filesystem {
     path filename() const;
     path stem() const;
     path extension() const;
     // [fs.path.query], query
- [[nodiscard]] bool empty() const noexcept;
     bool has_root_name() const;
     bool has_root_directory() const;
     bool has_root_path() const;
     bool has_relative_path() const;
     bool has_parent_path() const;
@@ -352,12 +354,12 @@ generic format and is not acceptable to the operating system as a native
 path.
 [*Note 2*: Some operating systems have no unambiguous way to
 distinguish between native format and generic format arguments. This is
 by design as it simplifies use for operating systems that do not require
-disambiguation. An implementation for an operating system where
-disambiguation is required is permitted to distinguish between the
 formats. — *end note*]
 Pathnames are converted as needed between the generic and native formats
 in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
 mathematical sense be the implementation’s functions that convert
@@ -443,16 +445,16 @@ named `Source` shall be one of:
   \[`source.begin()`, `source.end()`).
 - `basic_string_view<EcharT, traits>`. A function argument
   `const Source&` `source` shall have an effective range
   \[`source.begin()`, `source.end()`).
 - A type meeting the *Cpp17InputIterator* requirements that iterates
-  over a NTCTS. The value type shall be an encoded character type. A
   function argument `const Source&` `source` shall have an effective
   range \[`source`, `end`) where `end` is the first iterator value with
   an element value equal to `iterator_traits<Source>::value_type()`.
 - A character array that after array-to-pointer decay results in a
-  pointer to the start of a NTCTS. The value type shall be an encoded
   character type. A function argument `const Source&` `source` shall
   have an effective range \[`source`, `end`) where `end` is the first
   iterator value with an element value equal to
   `iterator_traits<decay_t<Source>>::value_type()`.
@@ -478,11 +480,11 @@ Arguments of type `Source` shall not be null pointers.
 ``` cpp
 path() noexcept;
 ```
-*Ensures:* `empty() == true`.
 ``` cpp
 path(const path& p);
 path(path&& p) noexcept;
 ```
@@ -726,11 +728,11 @@ template<class InputIterator>
 ``` cpp
 void clear() noexcept;
 ```
-*Ensures:* `empty() == true`.
 ``` cpp
 path& make_preferred();
 ```
@@ -855,24 +857,22 @@ operator string_type() const;
 ```
 *Returns:* `native()`.
 ``` cpp
-template<class EcharT, class traits = char_traits<EcharT>,
-         class Allocator = allocator<EcharT>>
-  basic_string<EcharT, traits, Allocator>
-    string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* `native()`.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
-std::string string() const;
 std::wstring wstring() const;
 std::u8string u8string() const;
 std::u16string u16string() const;
 std::u32string u32string() const;
 ```
@@ -880,10 +880,20 @@ std::u32string u32string() const;
 *Returns:* `native()`.
 *Remarks:* Conversion, if any, is performed as specified by
 [[fs.path.cvt]].
 ##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
 Generic format observer functions return strings formatted according to
 the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
 character is used as the *directory-separator*.
@@ -899,34 +909,42 @@ path("foo\\bar").generic_string()
 returns `"foo/bar"`.
 — *end example*]
 ``` cpp
-template<class EcharT, class traits = char_traits<EcharT>,
-         class Allocator = allocator<EcharT>>
-  basic_string<EcharT, traits, Allocator>
-    generic_string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
-std::string generic_string() const;
 std::wstring generic_wstring() const;
 std::u8string generic_u8string() const;
 std::u16string generic_u16string() const;
 std::u32string generic_u32string() const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]].
 ##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
 ``` cpp
 int compare(const path& p) const noexcept;
 ```
@@ -1057,22 +1075,22 @@ path(".bar").extension();               // yields "" and stem() is ".bar"
 path("..bar").extension();              // yields ".bar" and stem() is "."
 ```
 — *end example*]
-[*Note 3*: The period is included in the return value so that it is
 possible to distinguish between no extension and an empty
 extension. — *end note*]
-[*Note 4*: On non-POSIX operating systems, for a path `p`, it is
 possible that `p.stem() + p.extension() == p.filename()` is `false`,
 even though the generic format pathnames are the same. — *end note*]
 ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
 ``` cpp
-[[nodiscard]] bool empty() const noexcept;
 ```
 *Returns:* `true` if the pathname in the generic format is empty,
 otherwise `false`.
@@ -1176,11 +1194,11 @@ path lexically_relative(const path& base) const;
 - any *filename* in `relative_path()` or `base.relative_path()` can be
   interpreted as a *root-name*,
 returns `path()`.
-[*Note 5*: On a POSIX implementation, no *filename* in a
 *relative-path* is acceptable as a *root-name*. — *end note*]
 Determines the first mismatched element of `*this` and `base` as if by:
 ``` cpp
@@ -1219,28 +1237,28 @@ The above assertions will succeed. On Windows, the returned path’s
 *directory-separator* characters will be backslashes rather than
 slashes, but that does not affect `path` equality.
 — *end example*]
-[*Note 6*: If symlink following semantics are desired, use the
 operational function `relative()`. — *end note*]
-[*Note 7*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 ``` cpp
 path lexically_proximate(const path& base) const;
 ```
 *Returns:* If the value of `lexically_relative(base)` is not an empty
 path, return it. Otherwise return `*this`.
-[*Note 8*: If symlink following semantics are desired, use the
 operational function `proximate()`. — *end note*]
-[*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
@@ -1258,13 +1276,13 @@ iterators referring to elements of that object.
 For the elements of the pathname in the generic format, the forward
 traversal order is as follows:
 - The *root-name* element, if present.
-- The *root-directory* element, if present. \[*Note 1*: The generic
-  format is required to ensure lexicographical comparison works
- correctly. — *end note*]
 - Each successive *filename* element, if present.
 - An empty element, if a trailing non-root *directory-separator* is
   present.
 The backward traversal order is the reverse of forward traversal.
@@ -1359,10 +1377,79 @@ friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
 friend path operator/(const path& lhs, const path& rhs);
 ```
 *Effects:* Equivalent to: `return path(lhs) /= rhs;`
 #### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
 ``` cpp
 template<> struct hash<filesystem::path>;
 ```

 *Pathname resolution* is the operating system dependent mechanism for
 resolving a pathname to a particular file in a file hierarchy. There may
 be multiple pathnames that resolve to the same file.
+[*Example 1*: For POSIX-based operating systems, this mechanism is
+specified in POSIX, section 4.12, Pathname resolution. — *end example*]
 ``` cpp
 namespace std::filesystem {
   class path {
   public:
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         string(const Allocator& a = Allocator()) const;
+    std::string    display_string() const;
+    std::string    system_encoded_string() const;
     std::wstring   wstring() const;
     std::u8string  u8string() const;
     std::u16string u16string() const;
     std::u32string u32string() const;
     // [fs.path.generic.obs], generic format observers
     template<class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
       basic_string<EcharT, traits, Allocator>
         generic_string(const Allocator& a = Allocator()) const;
+    std::string    generic_display_string() const;
+    std::string    generic_system_encoded_string() const;
     std::wstring   generic_wstring() const;
     std::u8string  generic_u8string() const;
     std::u16string generic_u16string() const;
     std::u32string generic_u32string() const;
     path filename() const;
     path stem() const;
     path extension() const;
     // [fs.path.query], query
+    bool empty() const noexcept;
     bool has_root_name() const;
     bool has_root_directory() const;
     bool has_root_path() const;
     bool has_relative_path() const;
     bool has_parent_path() const;
 path.
 [*Note 2*: Some operating systems have no unambiguous way to
 distinguish between native format and generic format arguments. This is
 by design as it simplifies use for operating systems that do not require
+disambiguation. It is possible that an implementation for an operating
+system where disambiguation is needed distinguishes between the
 formats. — *end note*]
 Pathnames are converted as needed between the generic and native formats
 in an operating-system-dependent manner. Let *G(n)* and *N(g)* in a
 mathematical sense be the implementation’s functions that convert
   \[`source.begin()`, `source.end()`).
 - `basic_string_view<EcharT, traits>`. A function argument
   `const Source&` `source` shall have an effective range
   \[`source.begin()`, `source.end()`).
 - A type meeting the *Cpp17InputIterator* requirements that iterates
+  over an NTCTS. The value type shall be an encoded character type. A
   function argument `const Source&` `source` shall have an effective
   range \[`source`, `end`) where `end` is the first iterator value with
   an element value equal to `iterator_traits<Source>::value_type()`.
 - A character array that after array-to-pointer decay results in a
+  pointer to the start of an NTCTS. The value type shall be an encoded
   character type. A function argument `const Source&` `source` shall
   have an effective range \[`source`, `end`) where `end` is the first
   iterator value with an element value equal to
   `iterator_traits<decay_t<Source>>::value_type()`.
 ``` cpp
 path() noexcept;
 ```
+*Ensures:* `empty()` is `true`.
 ``` cpp
 path(const path& p);
 path(path&& p) noexcept;
 ```
 ``` cpp
 void clear() noexcept;
 ```
+*Ensures:* `empty()` is `true`.
 ``` cpp
 path& make_preferred();
 ```
 ```
 *Returns:* `native()`.
 ``` cpp
+template<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>>
+  basic_string<EcharT, traits, Allocator> string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* `native()`.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
+std::string system_encoded_string() const;
 std::wstring wstring() const;
 std::u8string u8string() const;
 std::u16string u16string() const;
 std::u32string u32string() const;
 ```
 *Returns:* `native()`.
 *Remarks:* Conversion, if any, is performed as specified by
 [[fs.path.cvt]].
+``` cpp
+std::string display_string() const;
+```
+*Returns:* `std::format("{}", *this)`.
+[*Note 3*: The returned string is suitable for use with
+formatting [[format.functions]] and print
+functions [[print.fun]]. — *end note*]
 ##### Generic format observers <a id="fs.path.generic.obs">[[fs.path.generic.obs]]</a>
 Generic format observer functions return strings formatted according to
 the generic pathname format [[fs.path.generic]]. A single slash (`'/'`)
 character is used as the *directory-separator*.
 returns `"foo/bar"`.
 — *end example*]
 ``` cpp
+template<class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>>
+  basic_string<EcharT, traits, Allocator> generic_string(const Allocator& a = Allocator()) const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* All memory allocation, including for the return value, shall
 be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
+std::string generic_system_encoded_string() const;
 std::wstring generic_wstring() const;
 std::u8string generic_u8string() const;
 std::u16string generic_u16string() const;
 std::u32string generic_u32string() const;
 ```
 *Returns:* The pathname in the generic format.
 *Remarks:* Conversion, if any, is specified by  [[fs.path.cvt]].
+``` cpp
+std::string generic_display_string() const;
+```
+*Returns:* `std::format("{:g}", *this)`.
+[*Note 4*: The returned string is suitable for use with
+formatting [[format.functions]] and print
+functions [[print.fun]]. — *end note*]
 ##### Compare <a id="fs.path.compare">[[fs.path.compare]]</a>
 ``` cpp
 int compare(const path& p) const noexcept;
 ```
 path("..bar").extension();              // yields ".bar" and stem() is "."
 ```
 — *end example*]
+[*Note 5*: The period is included in the return value so that it is
 possible to distinguish between no extension and an empty
 extension. — *end note*]
+[*Note 6*: On non-POSIX operating systems, for a path `p`, it is
 possible that `p.stem() + p.extension() == p.filename()` is `false`,
 even though the generic format pathnames are the same. — *end note*]
 ##### Query <a id="fs.path.query">[[fs.path.query]]</a>
 ``` cpp
+bool empty() const noexcept;
 ```
 *Returns:* `true` if the pathname in the generic format is empty,
 otherwise `false`.
 - any *filename* in `relative_path()` or `base.relative_path()` can be
   interpreted as a *root-name*,
 returns `path()`.
+[*Note 7*: On a POSIX implementation, no *filename* in a
 *relative-path* is acceptable as a *root-name*. — *end note*]
 Determines the first mismatched element of `*this` and `base` as if by:
 ``` cpp
 *directory-separator* characters will be backslashes rather than
 slashes, but that does not affect `path` equality.
 — *end example*]
+[*Note 8*: If symlink following semantics are desired, use the
 operational function `relative()`. — *end note*]
+[*Note 9*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 ``` cpp
 path lexically_proximate(const path& base) const;
 ```
 *Returns:* If the value of `lexically_relative(base)` is not an empty
 path, return it. Otherwise return `*this`.
+[*Note 10*: If symlink following semantics are desired, use the
 operational function `proximate()`. — *end note*]
+[*Note 11*: If normalization [[fs.path.generic]] is needed to ensure
 consistent matching of elements, apply `lexically_normal()` to `*this`,
 `base`, or both. — *end note*]
 #### Iterators <a id="fs.path.itr">[[fs.path.itr]]</a>
 For the elements of the pathname in the generic format, the forward
 traversal order is as follows:
 - The *root-name* element, if present.
+- The *root-directory* element, if present. \[*Note 1*: It is possible
+ that the use of the generic format is needed to ensure correct
+ lexicographical comparison. — *end note*]
 - Each successive *filename* element, if present.
 - An empty element, if a trailing non-root *directory-separator* is
   present.
 The backward traversal order is the reverse of forward traversal.
 friend path operator/(const path& lhs, const path& rhs);
 ```
 *Effects:* Equivalent to: `return path(lhs) /= rhs;`
+#### Formatting support <a id="fs.path.fmtr">[[fs.path.fmtr]]</a>
+##### Formatting support overview <a id="fs.path.fmtr.general">[[fs.path.fmtr.general]]</a>
+``` cpp
+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;
+  };
+}
+```
+##### Formatting support functions <a id="fs.path.fmtr.funcs">[[fs.path.fmtr.funcs]]</a>
+Formatting of paths uses formatting specifiers of the form
+``` bnf
+path-format-spec:
+    fill-and-alignₒₚₜ widthₒₚₜ '?'ₒₚₜ 'g'ₒₚₜ
+```
+where the productions *fill-and-align* and *width* are described in
+[[format.string]]. If the `?` option is used then the path is formatted
+as an escaped string [[format.string.escaped]].
+``` cpp
+constexpr void set_debug_format();
+```
+*Effects:* Modifies the state of the `formatter` to be as if the
+*path-format-spec* parsed by the last call to `parse` contained the `?`
+option.
+``` cpp
+constexpr typename basic_format_parse_context<charT>::iterator
+  parse(basic_format_parse_context<charT>& ctx);
+```
+*Effects:* Parses the format specifier as a *path-format-spec* and
+stores the parsed specifiers in `*this`.
+*Returns:* An iterator past the end of the *path-format-spec*.
+``` cpp
+template<class FormatContext>
+  typename FormatContext::iterator
+    format(const filesystem::path& p, FormatContext& ctx) const;
+```
+*Effects:* Let `s` be `p.generic_string<filesystem::path::value_type>()`
+if the `g` option is used, otherwise `p.native()`. Writes `s` into
+`ctx.out()`, adjusted according to the *path-format-spec*. If `charT` is
+`char`, `path::value_type` is `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 ‘U+fffd‘ replacement character per the
+Unicode Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion. If
+`charT` and `path::value_type` are the same then no transcoding is
+performed. Otherwise, transcoding is *implementation-defined*.
+*Returns:* An iterator past the end of the output range.
 #### Hash support <a id="fs.path.hash">[[fs.path.hash]]</a>
 ``` cpp
 template<> struct hash<filesystem::path>;
 ```

Diff to HTML by rtfpessoa