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

Files changed (1) hide show

tmp/tmpyo_77qs_/{from.md → to.md} +761 -0

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

	@@ -0,0 +1,761 @@

+#### `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;
+```
+*Effects:* Constructs an object of class `path` having the same pathname
+in the native and generic formats, respectively, as the original value
+of `p`. In the second form, `p` is left in a valid but unspecified
+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:
+``` cpp
+namespace fs = std::filesystem;
+std::string latin1_string = read_latin1_data();
+codecvt_8859_1<wchar_t> latin1_facet;
+std::locale latin1_locale(std::locale(), latin1_facet);
+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);
+```
+*Effects:* If `*this` and `p` are the same object, has no effect.
+Otherwise, sets both respective pathnames of `*this` to the respective
+pathnames of `p`.
+*Returns:* `*this`.
+``` cpp
+path& operator=(path&& p) noexcept;
+```
+*Effects:* If `*this` and `p` are the same object, has no effect.
+Otherwise, sets both respective pathnames of `*this` to the respective
+pathnames of `p`. `p` is left in a valid but unspecified state.
+[*Note 1*: A valid implementation is `swap(p)`. — *end note*]
+*Returns:* `*this`.
+``` cpp
+path& operator=(string_type&& source);
+path& assign(string_type&& source);
+```
+*Effects:* Sets the pathname in the detected-format of `source` to the
+original value of `source`. `source` is left in a valid but unspecified
+state.
+*Returns:* `*this`.
+``` cpp
+template <class Source>
+  path& operator=(const Source& source);
+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
+path& operator/=(const path& p);
+```
+*Effects:* If
+`p.is_absolute() || (p.has_root_name() && p.root_name() != root_name())`,
+then `operator=(p)`.
+Otherwise, modifies `*this` as if by these steps:
+- If `p.has_root_directory()`, then removes any root directory and
+  relative path from the generic format pathname. Otherwise, if
+  `!has_root_directory() && is_absolute()` is `true` or if
+  `has_filename()` is `true`, then appends `path::preferred_separator`
+  to the generic format pathname.
+- Then appends the native format pathname of `p`, omitting any
+  *root-name* from its generic format pathname, to the native format
+  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`.
+``` cpp
+template <class Source>
+  path& operator/=(const Source& source);
+template <class Source>
+  path& append(const Source& source);
+```
+*Effects:* Equivalent to: `return operator/=(path(source));`
+``` cpp
+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
+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();
+```
+*Effects:* Each *directory-separator* of the pathname in the generic
+format is converted to *preferred-separator*.
+*Returns:* `*this`.
+[*Example 3*:
+``` cpp
+path p("foo/bar");
+std::cout << p << '\n';
+p.make_preferred();
+std::cout << p << '\n';
+```
+On an operating system where *preferred-separator* is a slash, the
+output is:
+``` cpp
+"foo/bar"
+"foo/bar"
+```
+On an operating system where *preferred-separator* is a backslash, the
+output is:
+``` cpp
+"foo/bar"
+"foo\bar"
+```
+— *end example*]
+``` 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
+path("foo/bar").remove_filename(); // yields "foo/"
+path("foo/").remove_filename();    // yields "foo/"
+path("/foo").remove_filename();    // yields "/"
+path("/").remove_filename();       // yields "/"
+```
+— *end example*]
+``` cpp
+path& replace_filename(const path& replacement);
+```
+*Effects:* Equivalent to:
+``` cpp
+remove_filename();
+operator/=(replacement);
+```
+*Returns:* `*this`.
+[*Example 5*:
+``` cpp
+path("/foo").replace_filename("bar");  // yields "/bar" on POSIX
+path("/").replace_filename("bar");     // yields "/bar" on POSIX
+```
+— *end example*]
+``` 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);`.
+*Returns:* `*this`.
+``` cpp
+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;
+```
+*Returns:* The pathname in the native format.
+``` cpp
+const value_type* c_str() const noexcept;
+```
+*Returns:* Equivalent to `native().c_str()`.
+``` cpp
+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;
+```
+*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::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*,
+``` cpp
+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::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;
+```
+*Returns:* *root-name*, if the pathname in the generic format includes
+*root-name*, otherwise `path()`.
+``` cpp
+path root_directory() const;
+```
+*Returns:* *root-directory*, if the pathname in the generic format
+includes *root-directory*, otherwise `path()`.
+``` cpp
+path root_path() const;
+```
+*Returns:* `root_name() / root_directory()`.
+``` 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;
+```
+*Returns:* `relative_path().empty() ? path() : *–end()`.
+[*Example 6*:
+``` cpp
+path("/foo/bar.txt").filename();   // yields "bar.txt"
+path("/foo/bar").filename();       // yields "bar"
+path("/foo/bar/").filename();      // yields ""
+path("/").filename();              // yields ""
+path("//host").filename();         // yields ""
+path(".").filename();              // yields "."
+path("..").filename();             // yields ".."
+```
+— *end example*]
+``` cpp
+path stem() const;
+```
+*Returns:* Let `f` be the generic format pathname of `filename()`.
+Returns a path whose pathname in the generic format is
+- `f`, if it contains no periods other than a leading period or consists
+  solely of one or two periods;
+- otherwise, the prefix of `f` ending before its last period.
+[*Example 7*:
+``` cpp
+std::cout << path("/foo/bar.txt").stem(); // outputs "bar"
+path p = "foo.bar.baz.tar";
+for (; !p.extension().empty(); p = p.stem())
+  std::cout << p.extension() << '\n';
+  // outputs: .tar
+  //          .baz
+  //          .bar
+```
+— *end example*]
+``` 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
+path("/foo/bar.txt").extension();  // yields ".txt" and stem() is "bar"
+path("/foo/bar").extension();      // yields "" and stem() is "bar"
+path("/foo/.profile").extension(); // yields "" and stem() is ".profile"
+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*]
+##### `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;
+```
+*Returns:* `!root_path().empty()`.
+``` cpp
+bool has_root_name() const;
+```
+*Returns:* `!root_name().empty()`.
+``` cpp
+bool has_root_directory() const;
+```
+*Returns:* `!root_directory().empty()`.
+``` cpp
+bool has_relative_path() const;
+```
+*Returns:* `!relative_path().empty()`.
+``` cpp
+bool has_parent_path() const;
+```
+*Returns:* `!parent_path().empty()`.
+``` cpp
+bool has_filename() const;
+```
+*Returns:* `!filename().empty()`.
+``` cpp
+bool has_stem() const;
+```
+*Returns:* `!stem().empty()`.
+``` cpp
+bool has_extension() const;
+```
+*Returns:* `!extension().empty()`.
+``` 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*]
+``` cpp
+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
+assert(path("foo/./bar/..").lexically_normal() == "foo/");
+assert(path("foo/.///bar/../").lexically_normal() == "foo/");
+```
+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*]
+``` 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()`).
+[*Example 11*:
+``` cpp
+assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
+assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
+assert(path("a/b/c").lexically_relative("a") == "b/c");
+assert(path("a/b/c").lexically_relative("a/b/c/x/y") == "../..");
+assert(path("a/b/c").lexically_relative("a/b/c") == ".");
+assert(path("a/b").lexically_relative("c/d") == "../../a/b");
+```
+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*]

Diff to HTML by rtfpessoa