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

Files changed (1) hide show

tmp/tmpfic2fm0l/{from.md → to.md} +40 -36

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

@@ -1,7 +1,9 @@
 ### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
 An object of class `path` represents a path and contains a pathname.
 Such an object is concerned only with the lexical and syntactic aspects
 of a path. The path does not necessarily exist in external storage, and
 the pathname is not necessarily valid for the current operating system
 or for a particular file system.
@@ -23,22 +25,22 @@ elements of a path that determine if it is absolute are operating system
 dependent. A *relative path* is a path that is not absolute, and as
 such, only unambiguously identifies the location of a file when resolved
 relative to an implied starting location. The elements of a path that
 determine if it is relative are operating system dependent.
-[*Note 2*: Pathnames “.” and “..” are relative paths. — *end note*]
 A *pathname* is a character string that represents the name of a path.
 Pathnames are formatted according to the generic pathname format grammar
 [[fs.path.generic]] or according to an operating system dependent
 *native pathname format* accepted by the host operating system.
 *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.11, Pathname
 resolution. — *end example*]
 ``` cpp
 namespace std::filesystem {
   class path {
@@ -256,13 +258,13 @@ consisting solely of one and two period characters respectively, have
 special meaning. The following characteristics of filenames are
 operating system dependent:
 - The permitted characters. \[*Example 1*: Some operating systems
   prohibit the ASCII control characters (0x00 – 0x1F) in
-  filenames. — *end example*] \[*Note 1*: For wide portability, users
- may wish to limit *filename* characters to the POSIX Portable Filename
-  Character Set:
   `A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
   `a b c d e f g h i j k l m n o p q r s t u v w x y z`
   `0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
 - The maximum permitted length.
 - Filenames that are not permitted.
@@ -287,11 +289,11 @@ A *root-name* identifies the starting location for pathname resolution
 required.
 [*Note 2*: Many operating systems define a name beginning with two
 *directory-separator* characters as a *root-name* that identifies
 network or other resource locations. Some operating systems define a
-single letter followed by a colon as a drive specifier – a *root-name*
 identifying a specific device such as a disk drive. — *end note*]
 If a *root-name* is otherwise ambiguous, the possibility with the
 longest sequence of characters is chosen.
@@ -303,11 +305,11 @@ longest sequence of characters is chosen.
 1.  If the path is empty, stop.
 2.  Replace each slash character in the *root-name* with a
     *preferred-separator*.
 3.  Replace each *directory-separator* with a *preferred-separator*.
-    \[*Note 4*: The generic pathname grammar [[fs.path.generic]] defines
     *directory-separator* as one or more slashes and
     *preferred-separator*s. — *end note*]
 4.  Remove each dot filename and any immediately following
     *directory-separator*.
 5.  As long as any appear, remove a non-dot-dot filename immediately
@@ -347,11 +349,11 @@ path using either a pathname in the generic format [[fs.path.generic]]
 or a pathname in the native format [[fs.class.path]]. Such an argument
 is taken to be in the generic format if and only if it matches the
 generic format and is not acceptable to the operating system as a native
 path.
-[*Note 2*: Some operating systems may 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*]
@@ -370,11 +372,11 @@ differently from paths for directories, the path shall be treated as a
 directory path if its last element is a *directory-separator*, otherwise
 it shall be treated as a path to a regular file.
 [*Note 4*: A path stores a native format pathname
 [[fs.path.native.obs]] and acts as if it also stores a generic format
-pathname, related as given below. The implementation may generate the
 generic format pathname based on the native format pathname (and
 possibly other information) when requested. — *end note*]
 When a path is constructed from or is assigned a single representation
 separate from any path, the other representation is selected by the
@@ -392,11 +394,11 @@ the result of converting *p*. — *end note*]
 The *native encoding* of an ordinary character string is the operating
 system dependent current encoding for pathnames [[fs.class.path]]. The
 *native encoding* for wide character strings is the
 implementation-defined execution wide-character set encoding
-[[lex.charset]].
 For member function arguments that take character sequences representing
 paths and for member functions returning strings, value type and
 encoding conversion is performed if the value type of the argument or
 return value differs from `path::value_type`. For the argument or return
@@ -410,12 +412,12 @@ determined by its value type:
   return values is performed. For Windows-based operating systems, the
   native ordinary encoding is determined by calling a Windows API
   function. — *end note*] \[*Note 7*: This results in behavior
   identical to other C and C++ standard library functions that perform
   file operations using ordinary character strings to identify paths.
-  Changing this behavior would be surprising and error
-  prone. — *end note*]
 - `wchar_t`: The encoding is the native wide encoding. The method of
   conversion is unspecified. \[*Note 8*: For Windows-based operating
   systems `path::value_type` is `wchar_t` so no conversion from
   `wchar_t` value type arguments or to `wchar_t` value type return
   values is performed. — *end note*]
@@ -459,11 +461,11 @@ participate in overload resolution unless `Source` denotes a type other
 than `path`, and either
 - `Source` is a specialization of `basic_string` or `basic_string_view`,
   or
 - the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
-  valid and denotes a possibly `const` encoded character type
   [[temp.deduct]].
 [*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
 above and their encodings convert to `path::value_type` and its
 encoding. — *end note*]
@@ -698,12 +700,12 @@ template<class Source>
 ```
 *Effects:* Appends `path(x).native()` to the pathname in the native
 format.
-[*Note 2*: This directly manipulates the value of `native()` and may
-not be portable between operating systems. — *end note*]
 *Returns:* `*this`.
 ``` cpp
 path& operator+=(value_type x);
@@ -852,14 +854,10 @@ const value_type* c_str() const noexcept;
 operator string_type() const;
 ```
 *Returns:* `native()`.
-[*Note 3*: Conversion to `string_type` is provided so that an object of
-class `path` can be given as an argument to existing standard library
-file stream constructors and open functions. — *end note*]
 ``` cpp
 template<class EcharT, class traits = char_traits<EcharT>,
          class Allocator = allocator<EcharT>>
   basic_string<EcharT, traits, Allocator>
     string(const Allocator& a = Allocator()) const;
@@ -1059,17 +1057,17 @@ path(".bar").extension();               // yields "" and stem() is ".bar"
 path("..bar").extension();              // yields ".bar" and stem() is "."
 ```
 — *end example*]
-[*Note 4*: 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 5*: On non-POSIX operating systems, for a path `p`, it may not
-be the case that `p.stem() + p.extension() == p.filename()`, 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;
@@ -1168,25 +1166,21 @@ slashes, but that does not affect `path` equality.
 ``` cpp
 path lexically_relative(const path& base) const;
 ```
-*Returns:* `*this` made relative to `base`. Does not
-resolve [[fs.class.path]] symlinks. Does not first
-normalize [[fs.path.generic]] `*this` or `base`.
 *Effects:* If:
 - `root_name() != base.root_name()` is `true`, or
 - `is_absolute() != base.is_absolute()` is `true`, or
 - `!has_root_directory() && base.has_root_directory()` is `true`, or
 - any *filename* in `relative_path()` or `base.relative_path()` can be
   interpreted as a *root-name*,
 returns `path()`.
-[*Note 6*: 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
@@ -1204,10 +1198,14 @@ Then,
 - returns an object of class `path` that is default-constructed,
   followed by
   - application of `operator/=(path(".."))` `n` times, and then
   - application of `operator/=` for each element in \[`a`, `end()`).
 [*Example 11*:
 ``` cpp
 assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
 assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
@@ -1221,28 +1219,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 7*: If symlink following semantics are desired, use the
 operational function `relative()`. — *end note*]
-[*Note 8*: 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 9*: If symlink following semantics are desired, use the
 operational function `proximate()`. — *end note*]
-[*Note 10*: 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>
@@ -1347,14 +1345,10 @@ Path equality and path equivalence have different semantics.
 - Equivalence is determined by the `equivalent()` non-member function,
   which determines if two paths resolve [[fs.class.path]] to the same
   file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
   `true` when both paths resolve to the same file. — *end example*]
-Programmers wishing to determine if two paths are “the same” must decide
-if “the same” means “the same representation” or “resolve to the same
-actual file”, and choose the appropriate function accordingly.
 — *end note*]
 ``` cpp
 friend strong_ordering operator<=>(const path& lhs, const path& rhs) noexcept;
 ```
@@ -1365,5 +1359,15 @@ 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;`

 ### Class `path` <a id="fs.class.path">[[fs.class.path]]</a>
+#### General <a id="fs.class.path.general">[[fs.class.path.general]]</a>
 An object of class `path` represents a path and contains a pathname.
 Such an object is concerned only with the lexical and syntactic aspects
 of a path. The path does not necessarily exist in external storage, and
 the pathname is not necessarily valid for the current operating system
 or for a particular file system.
 dependent. A *relative path* is a path that is not absolute, and as
 such, only unambiguously identifies the location of a file when resolved
 relative to an implied starting location. The elements of a path that
 determine if it is relative are operating system dependent.
+[*Note 2*: Pathnames “.” and “..” are relative paths. — *end note*]
 A *pathname* is a character string that represents the name of a path.
 Pathnames are formatted according to the generic pathname format grammar
 [[fs.path.generic]] or according to an operating system dependent
 *native pathname format* accepted by the host operating system.
 *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 {
 special meaning. The following characteristics of filenames are
 operating system dependent:
 - The permitted characters. \[*Example 1*: Some operating systems
   prohibit the ASCII control characters (0x00 – 0x1F) in
+  filenames. — *end example*] \[*Note 1*: Wider portability can be
+ achieved by limiting *filename* characters to the POSIX Portable
+ Filename Character Set:
   `A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
   `a b c d e f g h i j k l m n o p q r s t u v w x y z`
   `0 1 2 3 4 5 6 7 8 9 . _ -` — *end note*]
 - The maximum permitted length.
 - Filenames that are not permitted.
 required.
 [*Note 2*: Many operating systems define a name beginning with two
 *directory-separator* characters as a *root-name* that identifies
 network or other resource locations. Some operating systems define a
+single letter followed by a colon as a drive specifier — a *root-name*
 identifying a specific device such as a disk drive. — *end note*]
 If a *root-name* is otherwise ambiguous, the possibility with the
 longest sequence of characters is chosen.
 1.  If the path is empty, stop.
 2.  Replace each slash character in the *root-name* with a
     *preferred-separator*.
 3.  Replace each *directory-separator* with a *preferred-separator*.
+    \[*Note 4*: The generic pathname grammar defines
     *directory-separator* as one or more slashes and
     *preferred-separator*s. — *end note*]
 4.  Remove each dot filename and any immediately following
     *directory-separator*.
 5.  As long as any appear, remove a non-dot-dot filename immediately
 or a pathname in the native format [[fs.class.path]]. Such an argument
 is taken to be in the generic format if and only if it matches the
 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*]
 directory path if its last element is a *directory-separator*, otherwise
 it shall be treated as a path to a regular file.
 [*Note 4*: A path stores a native format pathname
 [[fs.path.native.obs]] and acts as if it also stores a generic format
+pathname, related as given below. The implementation can generate the
 generic format pathname based on the native format pathname (and
 possibly other information) when requested. — *end note*]
 When a path is constructed from or is assigned a single representation
 separate from any path, the other representation is selected by the
 The *native encoding* of an ordinary character string is the operating
 system dependent current encoding for pathnames [[fs.class.path]]. The
 *native encoding* for wide character strings is the
 implementation-defined execution wide-character set encoding
+[[character.seq]].
 For member function arguments that take character sequences representing
 paths and for member functions returning strings, value type and
 encoding conversion is performed if the value type of the argument or
 return value differs from `path::value_type`. For the argument or return
   return values is performed. For Windows-based operating systems, the
   native ordinary encoding is determined by calling a Windows API
   function. — *end note*] \[*Note 7*: This results in behavior
   identical to other C and C++ standard library functions that perform
   file operations using ordinary character strings to identify paths.
+  Changing this behavior would be surprising and
+ error-prone. — *end note*]
 - `wchar_t`: The encoding is the native wide encoding. The method of
   conversion is unspecified. \[*Note 8*: For Windows-based operating
   systems `path::value_type` is `wchar_t` so no conversion from
   `wchar_t` value type arguments or to `wchar_t` value type return
   values is performed. — *end note*]
 than `path`, and either
 - `Source` is a specialization of `basic_string` or `basic_string_view`,
   or
 - the *qualified-id* `iterator_traits<decay_t<Source>>::value_type` is
+  valid and denotes a possibly const encoded character type
   [[temp.deduct]].
 [*Note 1*: See path conversions [[fs.path.cvt]] for how the value types
 above and their encodings convert to `path::value_type` and its
 encoding. — *end note*]
 ```
 *Effects:* Appends `path(x).native()` to the pathname in the native
 format.
+[*Note 2*: This directly manipulates the value of `native()`, which is
+not necessarily portable between operating systems. — *end note*]
 *Returns:* `*this`.
 ``` cpp
 path& operator+=(value_type x);
 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;
 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;
 ``` cpp
 path lexically_relative(const path& base) const;
 ```
 *Effects:* If:
 - `root_name() != base.root_name()` is `true`, or
 - `is_absolute() != base.is_absolute()` is `true`, or
 - `!has_root_directory() && base.has_root_directory()` is `true`, or
 - 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
 - returns an object of class `path` that is default-constructed,
   followed by
   - application of `operator/=(path(".."))` `n` times, and then
   - application of `operator/=` for each element in \[`a`, `end()`).
+*Returns:* `*this` made relative to `base`. Does not
+resolve [[fs.class.path]] symlinks. Does not first
+normalize [[fs.path.generic]] `*this` or `base`.
 [*Example 11*:
 ``` cpp
 assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
 assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
 *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>
 - Equivalence is determined by the `equivalent()` non-member function,
   which determines if two paths resolve [[fs.class.path]] to the same
   file system entity. \[*Example 2*: `equivalent("foo", "bar")` will be
   `true` when both paths resolve to the same file. — *end example*]
 — *end note*]
 ``` cpp
 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>;
+```
+For an object `p` of type `filesystem::path`,
+`hash<filesystem::path>()(p)` evaluates to the same result as
+`filesystem::hash_value(p)`.

Diff to HTML by rtfpessoa