The class path normal_relative and
-relative member functions perform lexical processing only, and so do not
-follow symlinks. For existing path, or partially existing paths, that may
-contain symlinks use the relative operational functions which do
+
The normal and
+relative member functions, like all member functions of class path, perform lexical processing
+only. They do not
follow symlinks.
path normal_relative(const path& base) const;+
These semantics are useful for operating on paths that do not currently exist +or on paths generated by operational non-member functions that resolve symlinks.
+path normal() const;
- Returns: normal(*this).relative(normal(base)).
+Returns: A path with the same elements as *this
+except that redundant current (dot) directory and name element followed
+by parent (dot-dot) directory elements are removed. If the returned path
+would otherwise be empty, a path containing a single current (dot)
+directory is returned.
Remarks: Uses operator/= to compose the returned path.
[Example:
+assert(path("foo/./bar/..").normal() == path("foo");
+assert(path("foo/./bar/../").normal() == path("foo/.");
All of the above asserts would succeed. On Windows, the +returned path's separators would be backslashes rather than slashes, but that +does not affect equality. —end example]
+ -path relative(const path& base) const;+
path relative(const path& base) const;
Returns:
-
- -
-
path()if the first mismatched element of+
path()if the first mismatched element of*thisis equal tobegin()and the first mismatched element ofbaseis equal tobase.begin(), or
- -
application of
path(".")if the first mismatched element of+- +
@@ -82,39 +95,63 @@ follow symlinks.
path(".")if the first mismatched element of*thisis equal toend()and the first mismatched element of base is equal tobase.end(), or
operator/=for each element in the sequence [first mismatched element ofp,p.end()).Remarks: Uses
+ +std::mismatch(begin(), end(), +Remarks: Uses
+ Path equality is determined bystd::mismatch(begin(), end(), base.begin(), base.end())to determine the first mismatched element. - Path equality is determined byoperator==.operator==. Usesoperator/=+ to compose the returned path.[Note: Use the non-member operational function
+ +relative+ if symlink following semantics are desired. —end note][Note: Use the
+ +normalfunction to preprocess . —end note][Example:
++
assert(path("/a/d").relative("/a/b/c") == path("../../d"));
+assert(path("/a/b/c").relative("/a/d") == path("../b/c"));
+assert(path("a/b/c").relative("a") == path("b/c"));
+assert(path("a/b/c").relative("a/b/c/x/y") == path("../.."));
+assert(path("a/b/c").relative("a/b/c") == path("."));All of the above asserts would succeed. On Windows, the +returned path's separators would be backslashes rather than slashes, but that +does not affect equality. —end example]
path weakly_canonical(const path& p); -path weakly_canonical(const path& p, system::error_code& ec)-
+path weakly_canonical(const path& p, system::error_code& ec); +
+Returns:+
+- +
+If
exists(p),canonical(p)
+- +
+Otherwise,
p.parent_path().empty().
+ ? p
+ : weakly_canonical(p.parent_path()) / p.filename()Remarks: An implementation may use iteration +rather than recursion.
+Throws: As specified in Error reporting.
+
path relative(const path& p, system::error_code& ec);
-Returns:
relative(p, current_path(), ec).Throws: As specified in Error reporting.
path relative(const path& p, const path& base=current_path());+
path relative(const path& p, const path& base=current_path()); +path relative(const path& p, const path& base, system::error_code& ec);
--Returns:
-weakly_canonical(p).relative(weakly_canonical(base)).Throws: As specified in Error reporting.
-
path relative(const path& p, const path& base, system::error_code& ec); --
-Effects: Creates a temporary object
-path wc_base-with a value ofweakly_canonical(base, ec)and, if no -error occurred, creates another temporary objectpath wc_p-with a value ofweakly_canonical(p, ec).Returns:
-wc_p.relative(wc_base)if no error -occurred during processing of Effects, otherwisepath().Remarks: Names
+wc_baseandwc_p-are for exposition only. These names are not exposed to callers of-relative.Returns:
weakly_canonical(p[, ec]).relative(weakly_canonical(base[, +ec])). The second form returns+path()if an error occurs.Throws: As specified in Error reporting.
+[Note: For two paths
+aandbthat both exist, +relative(a, b)is equivalent + tocanonical(a).relative(canonical(b)).For two paths
aandbneither of which exist, +relative(a, b)is equivalent + toa.relative(b). —end note]
Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt
Revised -11 August 2015
+12 August 2015