30 Input/output library [input.output]

30.10 File systems [filesystems]

30.10.8 Class path [fs.class.path]

30.10.8.4 path members [fs.path.member]

30.10.8.4.1 path constructors [fs.path.construct]

path() noexcept;

Effects: Constructs an object of class path.

Postconditions: empty() == true.

🔗

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.

🔗

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.

🔗

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.

🔗

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:

(7.1)
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.
(7.2)
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

A string is to be read from a database that is encoded in ISO/IEC 8859-1, and used to create a directory:

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

]

30.10.8.4.2 path assignments [fs.path.assign]

🔗

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.

🔗

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

A valid implementation is swap(p).

— end note

]

Returns: *this.

🔗

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.

🔗

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.

30.10.8.4.3 path appends [fs.path.append]

The append operations use operator/= to denote their semantic effect of appending preferred-separator when needed.

🔗

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:

(3.1)
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.
(3.2)
Then appends the native format pathname of p, omitting any root-name from its generic format pathname, to the native format pathname.

[ Example

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:

// 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.

🔗

template <class Source>
  path& operator/=(const Source& source);
template <class Source>
  path& append(const Source& source);

Effects: Equivalent to: return operator/=(path(source));

🔗

template <class InputIterator>
  path& append(InputIterator first, InputIterator last);

Effects: Equivalent to: return operator/=(path(first, last));

30.10.8.4.4 path concatenation [fs.path.concat]

🔗

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

This directly manipulates the value of native() and may not be portable between operating systems.

— end note

]

Returns: *this.

🔗

template <class InputIterator>
  path& concat(InputIterator first, InputIterator last);

Effects: Equivalent to return *this += path(first, last).

30.10.8.4.5 path modifiers [fs.path.modifiers]

🔗

void clear() noexcept;

Postconditions: empty() == true.

🔗

path& make_preferred();

Effects: Each directory-separator of the pathname in the generic format is converted to preferred-separator.

Returns: *this.

[ Example

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:

"foo/bar"
"foo/bar"

On an operating system where preferred-separator is a backslash, the output is:

"foo/bar"
"foo\bar"

— end example

]

🔗

path& remove_filename();

Postconditions: !has_filename().

Effects: Remove the generic format pathname of filename() from the generic format pathname.

Returns: *this.

[ Example

path("foo/bar").remove_filename(); // yields "foo/"
path("foo/").remove_filename();    // yields "foo/"
path("/foo").remove_filename();    // yields "/"
path("/").remove_filename();       // yields "/"

— end example

]

🔗

path& replace_filename(const path& replacement);

Effects: Equivalent to:

remove_filename();
operator/=(replacement);

Returns: *this.

[ Example

path("/foo").replace_filename("bar");  // yields "/bar" on POSIX
path("/").replace_filename("bar");     // yields "/bar" on POSIX

— end example

]

🔗

path& replace_extension(const path& replacement = path());

Effects:

(12.1)
Any existing extension()([fs.path.decompose]) is removed from the pathname in the generic format, then
(12.2)
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
(12.3)
operator+=(replacement);.

Returns: *this.

🔗

void swap(path& rhs) noexcept;

Effects: Swaps the contents (in all formats) of the two paths.

Complexity: Constant time.

30.10.8.4.6 path native format observers [fs.path.native.obs]

The string returned by all native format observers is in the native pathname format ([fs.def.native]).

🔗

const string_type& native() const noexcept;

Returns: The pathname in the native format.

🔗

const value_type* c_str() const noexcept;

Returns: Equivalent to native().c_str().

🔗

operator string_type() const;

Returns: native().

[ Note

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

]

🔗

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].

🔗

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.

30.10.8.4.7 path generic format observers [fs.path.generic.obs]

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

On an operating system that uses backslash as its preferred-separator,

path("foo\\bar").generic_string()

returns "foo/bar".

— end example

]

🔗

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].

🔗

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.

30.10.8.4.8 path compare [fs.path.compare]

🔗

int compare(const path& p) const noexcept;

Returns:

(1.1)
A value less than 0, if native() for the elements of *this are lexicographically less than native() for the elements of p; otherwise,
(1.2)
a value greater than 0, if native() for the elements of *this are lexicographically greater than native() for the elements of p; otherwise,
(1.3)
0.

Remarks: The elements are determined as if by iteration over the half-open range [begin(), end()) for *this and p.

🔗

int compare(const string_type& s) const
int compare(basic_string_view<value_type> s) const;

Returns: compare(path(s)).

🔗

int compare(const value_type* s) const

Returns: compare(path(s)).

30.10.8.4.9 path decomposition [fs.path.decompose]

🔗

path root_name() const;

Returns: root-name, if the pathname in the generic format includes root-name, otherwise path().

🔗

path root_directory() const;

Returns: root-directory, if the pathname in the generic format includes root-directory, otherwise path().

🔗

path root_path() const;

Returns: root_name() / root_directory().

🔗

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().

🔗

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.

🔗

path filename() const;

Returns: relative_path().empty() ? path() : *--end().

[ Example

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

]

🔗

path stem() const;

Returns: Let f be the generic format pathname of filename().

Returns a path whose pathname in the generic format is

(8.1)
f, if it contains no periods other than a leading period or consists solely of one or two periods;
(8.2)
otherwise, the prefix of f ending before its last period.

[ Example

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

]

🔗

path extension() const;

Returns: a path whose pathname in the generic format is the suffix of filename() not included in stem().

[ Example

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

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

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

]

30.10.8.4.10 path query [fs.path.query]

🔗

bool empty() const noexcept;

Returns: true if the pathname in the generic format is empty, else false.

🔗

bool has_root_path() const;

Returns: !root_path().empty().

🔗

bool has_root_name() const;

Returns: !root_name().empty().

🔗

bool has_root_directory() const;

Returns: !root_directory().empty().

🔗

bool has_relative_path() const;

Returns: !relative_path().empty().

🔗

bool has_parent_path() const;

Returns: !parent_path().empty().

🔗

bool has_filename() const;

Returns: !filename().empty().

🔗

bool has_stem() const;

Returns: !stem().empty().

🔗

bool has_extension() const;

Returns: !extension().empty().

🔗

bool is_absolute() const;

Returns: true if the pathname in the native format contains an absolute path ([fs.def.absolute.path]), else false.

[ Example

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().

30.10.8.4.11 path generation [fs.path.gen]

🔗

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

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

]

🔗

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:

auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());

Then,

(4.1)
if a == end() and b == base.end(), returns path("."); otherwise
(4.2)
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
(4.3)
returns an object of class path that is default-constructed, followed by
- (4.3.1)
  application of operator/=(path("..")) n times, and then
- (4.3.2)
  application of operator/= for each element in [a, end()).

[ Example

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

If symlink following semantics are desired, use the operational function relative().

— end note

]

[ Note

If normalization ([fs.def.normal.form]) is needed to ensure consistent matching of elements, apply lexically_normal() to *this, base, or both.

— end note

]

🔗

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

If symlink following semantics are desired, use the operational function proximate().

— end note

]

[ Note

If normalization ([fs.def.normal.form]) is needed to ensure consistent matching of elements, apply lexically_normal() to *this, base, or both.

— end note

]