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

Files changed (1) hide show

tmp/tmpkm3cqgdu/{from.md → to.md} +36 -20

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

@@ -4,11 +4,11 @@
 ``` cpp
 path() noexcept;
 ```
-*Ensures:* `empty() == true`.
 ``` cpp
 path(const path& p);
 path(path&& p) noexcept;
 ```
@@ -252,11 +252,11 @@ template<class InputIterator>
 ``` cpp
 void clear() noexcept;
 ```
-*Ensures:* `empty() == true`.
 ``` cpp
 path& make_preferred();
 ```
@@ -381,24 +381,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;
 ```
@@ -406,10 +404,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*.
@@ -425,34 +433,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;
 ```
@@ -583,22 +599,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`.
@@ -702,11 +718,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
@@ -745,26 +761,26 @@ 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*]

 ``` 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*]

Diff to HTML by rtfpessoa