[fs.path.member] - C++17 → C++20

Files changed (1) hide show

tmp/tmpwe4uds37/{from.md → to.md} +127 -114

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

@@ -1,16 +1,14 @@
-#### `path` members <a id="fs.path.member">[[fs.path.member]]</a>
-##### `path` constructors <a id="fs.path.construct">[[fs.path.construct]]</a>
 ``` cpp
 path() noexcept;
 ```
-*Effects:* Constructs an object of class `path`.
-*Postconditions:* `empty() == true`.
 ``` cpp
 path(const path& p);
 path(path&& p) noexcept;
 ```
@@ -23,49 +21,48 @@ state.
 ``` cpp
 path(string_type&& source, format fmt = auto_format);
 ```
 *Effects:* Constructs an object of class `path` for which the pathname
-in the detected-format of `source` has the original value of
-`source` ([[fs.path.fmt.cvt]]), converting format if
-required ([[fs.path.fmt.cvt]]). `source` is left in a valid but
-unspecified state.
 ``` cpp
 template<class Source>
   path(const Source& source, format fmt = auto_format);
 template<class InputIterator>
   path(InputIterator first, InputIterator last, format fmt = auto_format);
 ```
-*Effects:* Let `s` be the effective range of `source` ([[fs.path.req]])
-or the range \[`first`, `last`), with the encoding converted if
-required ([[fs.path.cvt]]). Finds the detected-format of
-`s` ([[fs.path.fmt.cvt]]) and constructs an object of class `path` for
-which the pathname in that format is `s`.
 ``` cpp
 template<class Source>
   path(const Source& source, const locale& loc, format fmt = auto_format);
 template<class InputIterator>
   path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
 ```
-*Requires:* The value type of `Source` and `InputIterator` is `char`.
 *Effects:* Let `s` be the effective range of `source` or the range
 \[`first`, `last`), after converting the encoding as follows:
 - If `value_type` is `wchar_t`, converts to the native wide
-  encoding ([[fs.def.native.encode]]) using the
   `codecvt<wchar_t, char, mbstate_t>` facet of `loc`.
 - Otherwise a conversion is performed using the
   `codecvt<wchar_t, char, mbstate_t>` facet of `loc`, and then a second
-  conversion to the current narrow encoding.
-Finds the detected-format of `s` ([[fs.path.fmt.cvt]]) and constructs
-an object of class `path` for which the pathname in that format is `s`.
 [*Example 1*:
 A string is to be read from a database that is encoded in ISO/IEC
 8859-1, and used to create a directory:
@@ -79,27 +76,27 @@ fs::create_directory(fs::path(latin1_string, latin1_locale));
 ```
 For POSIX-based operating systems, the path is constructed by first
 using `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string`
 to a wide character string in the native wide
-encoding ([[fs.def.native.encode]]). The resulting wide string is then
-converted to a narrow character pathname string in the current native
-narrow encoding. If the native wide encoding is UTF-16 or UTF-32, and
-the current native narrow encoding is UTF-8, all of the characters in
 the ISO/IEC 8859-1 character set will be converted to their Unicode
-representation, but for other native narrow encodings some characters
 may have no representation.
 For Windows-based operating systems, the path is constructed by using
 `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string` to a
 UTF-16 encoded wide character pathname string. All of the characters in
 the ISO/IEC 8859-1 character set will be converted to their Unicode
 representation.
 — *end example*]
-##### `path` assignments <a id="fs.path.assign">[[fs.path.assign]]</a>
 ``` cpp
 path& operator=(const path& p);
 ```
@@ -139,18 +136,18 @@ template <class Source>
   path& assign(const Source& source);
 template<class InputIterator>
   path& assign(InputIterator first, InputIterator last);
 ```
-*Effects:* Let `s` be the effective range of `source` ([[fs.path.req]])
-or the range \[`first`, `last`), with the encoding converted if
-required ([[fs.path.cvt]]). Finds the detected-format of
-`s` ([[fs.path.fmt.cvt]]) and sets the pathname in that format to `s`.
 *Returns:* `*this`.
-##### `path` appends <a id="fs.path.append">[[fs.path.append]]</a>
 The append operations use `operator/=` to denote their semantic effect
 of appending *preferred-separator* when needed.
 ``` cpp
@@ -173,26 +170,28 @@ Otherwise, modifies `*this` as if by these steps:
   pathname.
 [*Example 2*:
 Even if `//host` is interpreted as a *root-name*, both of the paths
-`path("//host")/"foo"` and `path("//host/")/"foo"` equal `"//host/foo"`.
 Expression examples:
 ``` cpp
 // On POSIX,
-path("foo") / ""; // yields "foo/"
-path("foo") / "/bar"; // yields "/bar"
-// On Windows, backslashes replace slashes in the above yields
 // On Windows,
-path("foo") / "c:/bar"; // yields "c:/bar"
-path("foo") / "c:"; // yields "c:"
-path("c:") / ""; // yields "c:"
-path("c:foo") / "/bar"; // yields "c:/bar"
-path("c:foo") / "c:bar"; // yields "c:foo/bar"
 ```
 — *end example*]
 *Returns:* `*this`.
@@ -211,22 +210,19 @@ template <class InputIterator>
   path& append(InputIterator first, InputIterator last);
 ```
 *Effects:* Equivalent to: `return operator/=(path(first, last));`
-##### `path` concatenation <a id="fs.path.concat">[[fs.path.concat]]</a>
 ``` cpp
 path& operator+=(const path& x);
 path& operator+=(const string_type& x);
 path& operator+=(basic_string_view<value_type> x);
 path& operator+=(const value_type* x);
-path& operator+=(value_type x);
 template<class Source>
   path& operator+=(const Source& x);
-template <class EcharT>
-  path& operator+=(EcharT x);
 template<class Source>
   path& concat(const Source& x);
 ```
 *Effects:* Appends `path(x).native()` to the pathname in the native
@@ -235,24 +231,32 @@ format.
 [*Note 2*: This directly manipulates the value of `native()` and may
 not be portable between operating systems. — *end note*]
 *Returns:* `*this`.
 ``` cpp
 template<class InputIterator>
   path& concat(InputIterator first, InputIterator last);
 ```
-*Effects:* Equivalent to `return *this += path(first, last)`.
-##### `path` modifiers <a id="fs.path.modifiers">[[fs.path.modifiers]]</a>
 ``` cpp
 void clear() noexcept;
 ```
-*Postconditions:* `empty() == true`.
 ``` cpp
 path& make_preferred();
 ```
@@ -290,15 +294,15 @@ output is:
 ``` cpp
 path& remove_filename();
 ```
-*Postconditions:* `!has_filename()`.
 *Effects:* Remove the generic format pathname of `filename()` from the
 generic format pathname.
 *Returns:* `*this`.
 [*Example 4*:
 ``` cpp
@@ -336,12 +340,12 @@ path("/").replace_filename("bar");     // yields "/bar" on POSIX
 path& replace_extension(const path& replacement = path());
 ```
 *Effects:*
-- Any existing `extension()(` [[fs.path.decompose]]`)` is removed from
- the pathname in the generic format, then
 - If `replacement` is not empty and does not begin with a dot character,
   a dot character is appended to the pathname in the generic format,
   then
 - `operator+=(replacement);`.
@@ -353,14 +357,14 @@ void swap(path& rhs) noexcept;
 *Effects:* Swaps the contents (in all formats) of the two paths.
 *Complexity:* Constant time.
-##### `path` native format observers <a id="fs.path.native.obs">[[fs.path.native.obs]]</a>
 The string returned by all native format observers is in the native
-pathname format ([[fs.def.native]]).
 ``` cpp
 const string_type& native() const noexcept;
 ```
@@ -368,11 +372,11 @@ const string_type& native() const noexcept;
 ``` cpp
 const value_type* c_str() const noexcept;
 ```
-*Returns:* Equivalent to `native().c_str()`.
 ``` cpp
 operator string_type() const;
 ```
@@ -396,26 +400,25 @@ be performed by `a`. Conversion, if any, is specified by
 [[fs.path.cvt]].
 ``` cpp
 std::string string() const;
 std::wstring wstring() const;
-std::string u8string() const;
 std::u16string u16string() const;
 std::u32string u32string() const;
 ```
-*Returns:* `pathstring`.
 *Remarks:* Conversion, if any, is performed as specified by
-[[fs.path.cvt]]. The encoding of the string returned by `u8string()` is
-always UTF-8.
-##### `path` 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*.
 [*Example 1*:
 On an operating system that uses backslash as its *preferred-separator*,
@@ -441,53 +444,51 @@ 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::string 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]]. The
-encoding of the string returned by `generic_u8string()` is always UTF-8.
-##### `path` compare <a id="fs.path.compare">[[fs.path.compare]]</a>
 ``` cpp
 int compare(const path& p) const noexcept;
 ```
 *Returns:*
-- A value less than `0`, if `native()` for the elements of `*this` are
- lexicographically less than `native()` for the elements of `p`;
- otherwise,
-- a value greater than `0`, if `native()` for the elements of `*this`
- are lexicographically greater than `native()` for the elements of `p`;
-  otherwise,
-- `0`.
-*Remarks:* The elements are determined as if by iteration over the
-half-open range \[`begin()`, `end()`) for `*this` and `p`.
 ``` cpp
-int compare(const string_type& s) const
 int compare(basic_string_view<value_type> s) const;
 ```
-*Returns:* `compare(path(s))`.
-``` cpp
-int compare(const value_type* s) const
-```
-*Returns:* `compare(path(s))`.
-##### `path` decomposition <a id="fs.path.decompose">[[fs.path.decompose]]</a>
 ``` cpp
 path root_name() const;
 ```
@@ -510,20 +511,21 @@ path root_path() const;
 ``` cpp
 path relative_path() const;
 ```
 *Returns:* A `path` composed from the pathname in the generic format, if
-`!empty()`, beginning with the first *filename* after *root-path*.
-Otherwise, `path()`.
 ``` cpp
 path parent_path() const;
 ```
-*Returns:* `*this` if `!has_relative_path()`, otherwise a path whose
-generic format pathname is the longest prefix of the generic format
-pathname of `*this` that produces one fewer element in its iteration.
 ``` cpp
 path filename() const;
 ```
@@ -570,11 +572,11 @@ for (; !p.extension().empty(); p = p.stem())
 ``` cpp
 path extension() const;
 ```
-*Returns:* a path whose pathname in the generic format is the suffix of
 `filename()` not included in `stem()`.
 [*Example 8*:
 ``` cpp
@@ -593,18 +595,18 @@ 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*]
-##### `path` 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, else
-`false`.
 ``` cpp
 bool has_root_path() const;
 ```
@@ -655,11 +657,11 @@ bool has_extension() const;
 ``` cpp
 bool is_absolute() const;
 ```
 *Returns:* `true` if the pathname in the native format contains an
-absolute path ([[fs.def.absolute.path]]), else `false`.
 [*Example 9*: `path("/").is_absolute()` is `true` for POSIX-based
 operating systems, and `false` for Windows-based operating
 systems. — *end example*]
@@ -667,18 +669,18 @@ systems. — *end example*]
 bool is_relative() const;
 ```
 *Returns:* `!is_absolute()`.
-##### `path` generation <a id="fs.path.gen">[[fs.path.gen]]</a>
 ``` cpp
 path lexically_normal() const;
 ```
 *Returns:* A path whose pathname in the generic format is the normal
-form ([[fs.def.normal.form]]) of the pathname in the generic format of
 `*this`.
 [*Example 10*:
 ``` cpp
@@ -695,29 +697,40 @@ 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.def.pathres]]) symlinks. Does not first
-normalize ([[fs.def.normal.form]]) `*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`, returns
-`path()`. Determines the first mismatched element of `*this` and `base`
-as if by:
 ``` cpp
 auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
 ```
 Then,
 - if `a == end()` and `b == base.end()`, returns `path(".")`; otherwise
 - let `n` be the number of *filename* elements in \[`b`, `base.end()`)
-  that are not *dot* or *dot-dot* minus the number that are *dot-dot*.
-  If `n<0,` returns `path()`; otherwise
 - 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()`).
@@ -736,26 +749,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.def.normal.form]]) 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.def.normal.form]]) is needed to
-ensure consistent matching of elements, apply `lexically_normal()` to
-`*this`, `base`, or both. — *end note*]

+#### Members <a id="fs.path.member">[[fs.path.member]]</a>
+##### Constructors <a id="fs.path.construct">[[fs.path.construct]]</a>
 ``` cpp
 path() noexcept;
 ```
+*Ensures:* `empty() == true`.
 ``` cpp
 path(const path& p);
 path(path&& p) noexcept;
 ```
 ``` cpp
 path(string_type&& source, format fmt = auto_format);
 ```
 *Effects:* Constructs an object of class `path` for which the pathname
+in the detected-format of `source` has the original value of `source`
+[[fs.path.fmt.cvt]], converting format if required [[fs.path.fmt.cvt]].
+`source` is left in a valid but unspecified state.
 ``` cpp
 template<class Source>
   path(const Source& source, format fmt = auto_format);
 template<class InputIterator>
   path(InputIterator first, InputIterator last, format fmt = auto_format);
 ```
+*Effects:* Let `s` be the effective range of `source` [[fs.path.req]] or
+the range \[`first`, `last`), with the encoding converted if
+required [[fs.path.cvt]]. Finds the detected-format of `s`
+[[fs.path.fmt.cvt]] and constructs an object of class `path` for which
+the pathname in that format is `s`.
 ``` cpp
 template<class Source>
   path(const Source& source, const locale& loc, format fmt = auto_format);
 template<class InputIterator>
   path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
 ```
+*Mandates:* The value type of `Source` and `InputIterator` is `char`.
 *Effects:* Let `s` be the effective range of `source` or the range
 \[`first`, `last`), after converting the encoding as follows:
 - If `value_type` is `wchar_t`, converts to the native wide
+  encoding [[fs.path.type.cvt]] using the
   `codecvt<wchar_t, char, mbstate_t>` facet of `loc`.
 - Otherwise a conversion is performed using the
   `codecvt<wchar_t, char, mbstate_t>` facet of `loc`, and then a second
+  conversion to the current ordinary encoding.
+Finds the detected-format of `s` [[fs.path.fmt.cvt]] and constructs an
+object of class `path` for which the pathname in that format is `s`.
 [*Example 1*:
 A string is to be read from a database that is encoded in ISO/IEC
 8859-1, and used to create a directory:
 ```
 For POSIX-based operating systems, the path is constructed by first
 using `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string`
 to a wide character string in the native wide
+encoding [[fs.path.type.cvt]]. The resulting wide string is then
+converted to an ordinary character pathname string in the current native
+ordinary encoding. If the native wide encoding is UTF-16 or UTF-32, and
+the current native ordinary encoding is UTF-8, all of the characters in
 the ISO/IEC 8859-1 character set will be converted to their Unicode
+representation, but for other native ordinary encodings some characters
 may have no representation.
 For Windows-based operating systems, the path is constructed by using
 `latin1_facet` to convert ISO/IEC 8859-1 encoded `latin1_string` to a
 UTF-16 encoded wide character pathname string. All of the characters in
 the ISO/IEC 8859-1 character set will be converted to their Unicode
 representation.
 — *end example*]
+##### Assignments <a id="fs.path.assign">[[fs.path.assign]]</a>
 ``` cpp
 path& operator=(const path& p);
 ```
   path& assign(const Source& source);
 template<class InputIterator>
   path& assign(InputIterator first, InputIterator last);
 ```
+*Effects:* Let `s` be the effective range of `source` [[fs.path.req]] or
+the range \[`first`, `last`), with the encoding converted if
+required [[fs.path.cvt]]. Finds the detected-format of `s`
+[[fs.path.fmt.cvt]] and sets the pathname in that format to `s`.
 *Returns:* `*this`.
+##### Appends <a id="fs.path.append">[[fs.path.append]]</a>
 The append operations use `operator/=` to denote their semantic effect
 of appending *preferred-separator* when needed.
 ``` cpp
   pathname.
 [*Example 2*:
 Even if `//host` is interpreted as a *root-name*, both of the paths
+`path("//host")/"foo"` and `path("//host/")/"foo"` equal `"//host/foo"`
+(although the former might use backslash as the preferred separator).
 Expression examples:
 ``` cpp
 // On POSIX,
+path("foo") /= path(""); // yields path("foo/")
+path("foo") /= path("/bar"); // yields path("/bar")
 // On Windows,
+path("foo") /= path(""); // yields path("foo\{")}
+path("foo") /= path("/bar"); // yields path("/bar")
+path("foo") /= path("c:/bar"); // yields path("c:/bar")
+path("foo") /= path("c:"); // yields path("c:")
+path("c:") /= path(""); // yields path("c:")
+path("c:foo") /= path("/bar");  // yields path("c:/bar")
+path("c:foo") /= path("c:bar"); // yields path("c:foo\{bar")}
 ```
 — *end example*]
 *Returns:* `*this`.
   path& append(InputIterator first, InputIterator last);
 ```
 *Effects:* Equivalent to: `return operator/=(path(first, last));`
+##### Concatenation <a id="fs.path.concat">[[fs.path.concat]]</a>
 ``` cpp
 path& operator+=(const path& x);
 path& operator+=(const string_type& x);
 path& operator+=(basic_string_view<value_type> x);
 path& operator+=(const value_type* x);
 template<class Source>
   path& operator+=(const Source& x);
 template<class Source>
   path& concat(const Source& x);
 ```
 *Effects:* Appends `path(x).native()` to the pathname in the native
 [*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);
+template<class EcharT>
+  path& operator+=(EcharT x);
+```
+*Effects:* Equivalent to: `return *this += basic_string_view(&x, 1);`
 ``` cpp
 template<class InputIterator>
   path& concat(InputIterator first, InputIterator last);
 ```
+*Effects:* Equivalent to: `return *this += path(first, last);`
+##### Modifiers <a id="fs.path.modifiers">[[fs.path.modifiers]]</a>
 ``` cpp
 void clear() noexcept;
 ```
+*Ensures:* `empty() == true`.
 ``` cpp
 path& make_preferred();
 ```
 ``` cpp
 path& remove_filename();
 ```
 *Effects:* Remove the generic format pathname of `filename()` from the
 generic format pathname.
+*Ensures:* `!has_filename()`.
 *Returns:* `*this`.
 [*Example 4*:
 ``` cpp
 path& replace_extension(const path& replacement = path());
 ```
 *Effects:*
+- Any existing `extension()` [[fs.path.decompose]] is removed from the
+  pathname in the generic format, then
 - If `replacement` is not empty and does not begin with a dot character,
   a dot character is appended to the pathname in the generic format,
   then
 - `operator+=(replacement);`.
 *Effects:* Swaps the contents (in all formats) of the two paths.
 *Complexity:* Constant time.
+##### Native format observers <a id="fs.path.native.obs">[[fs.path.native.obs]]</a>
 The string returned by all native format observers is in the native
+pathname format [[fs.class.path]].
 ``` cpp
 const string_type& native() const noexcept;
 ```
 ``` cpp
 const value_type* c_str() const noexcept;
 ```
+*Effects:* Equivalent to: `return native().c_str();`
 ``` cpp
 operator string_type() const;
 ```
 [[fs.path.cvt]].
 ``` cpp
 std::string 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]].
+##### 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*.
 [*Example 1*:
 On an operating system that uses backslash as its *preferred-separator*,
 [[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;
 ```
 *Returns:*
+- Let `rootNameComparison` be the result of
+  `this->root_name().native().compare(p.root_name().native())`. If
+ `rootNameComparison` is not `0`, `rootNameComparison`.
+- Otherwise, if `!this->has_root_directory()` and
+  `p.has_root_directory()`, a value less than `0`.
+- Otherwise, if `this->has_root_directory()` and
+  `!p.has_root_directory()`, a value greater than `0`.
+- Otherwise, if `native()` for the elements of `this->relative_path()`
+ are lexicographically less than `native()` for the elements of
+ `p.relative_path()`, a value less than `0`.
+- Otherwise, if `native()` for the elements of `this->relative_path()`
+  are lexicographically greater than `native()` for the elements of
+  `p.relative_path()`, a value greater than `0`.
+- Otherwise, `0`.
 ``` cpp
+int compare(const string_type& s) const;
 int compare(basic_string_view<value_type> s) const;
+int compare(const value_type* s) const;
 ```
+*Effects:* Equivalent to: `return compare(path(s));`
+##### Decomposition <a id="fs.path.decompose">[[fs.path.decompose]]</a>
 ``` cpp
 path root_name() const;
 ```
 ``` cpp
 path relative_path() const;
 ```
 *Returns:* A `path` composed from the pathname in the generic format, if
+`empty()` is `false`, beginning with the first *filename* after
+`root_path()`. Otherwise, `path()`.
 ``` cpp
 path parent_path() const;
 ```
+*Returns:* `*this` if `has_relative_path()` is `false`, otherwise a path
+whose generic format pathname is the longest prefix of the generic
+format pathname of `*this` that produces one fewer element in its
+iteration.
 ``` cpp
 path filename() const;
 ```
 ``` cpp
 path extension() const;
 ```
+*Returns:* A path whose pathname in the generic format is the suffix of
 `filename()` not included in `stem()`.
 [*Example 8*:
 ``` cpp
 [*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;
 ```
+*Returns:* `true` if the pathname in the generic format is empty,
+otherwise `false`.
 ``` cpp
 bool has_root_path() const;
 ```
 ``` cpp
 bool is_absolute() const;
 ```
 *Returns:* `true` if the pathname in the native format contains an
+absolute path [[fs.class.path]], otherwise `false`.
 [*Example 9*: `path("/").is_absolute()` is `true` for POSIX-based
 operating systems, and `false` for Windows-based operating
 systems. — *end example*]
 bool is_relative() const;
 ```
 *Returns:* `!is_absolute()`.
+##### Generation <a id="fs.path.gen">[[fs.path.gen]]</a>
 ``` cpp
 path lexically_normal() const;
 ```
 *Returns:* A path whose pathname in the generic format is the normal
+form [[fs.path.generic]] of the pathname in the generic format of
 `*this`.
 [*Example 10*:
 ``` cpp
 ``` 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
 auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
 ```
 Then,
 - if `a == end()` and `b == base.end()`, returns `path(".")`; otherwise
 - let `n` be the number of *filename* elements in \[`b`, `base.end()`)
+  that are not dot or dot-dot or empty, minus the number that are
+ dot-dot. If `n<0,` returns `path()`; otherwise
+- if `n == 0` and `(a == end() || a->empty())`, returns `path(".")`;
+  otherwise
 - 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()`).
 *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*]

Diff to HTML by rtfpessoa