path-class.md

description	title	ms.date	f1_keywords
Learn more about: path Class	path Class	06/17/2022	filesystem/std::experimental::filesystem::path

path Class

The path class stores an object of type string_type, called myname here for the purposes of exposition, suitable for use as a pathname. string_type is a synonym for basic_string<value_type>, where value_type is a synonym for wchar_t on Windows or char on POSIX.

For more information, and code examples, see File System Navigation (C++).

Syntax

classpath;

Constructors

Constructor	Description
path	Constructs a path.

Typedefs

Type name	Description
const_iterator	A synonym for iterator.
iterator	A bidirectional constant iterator that designates the path components of myname.
string_type	The type is a synonym for basic_string<value_type>.

Member functions

Member function	Description
append	Appends the specified sequence to mypath, converted and inserting a preferred_separator as needed.
assign	Replaces mypath with the specified sequence, converted as needed.
begin	Returns a path::iterator designating the first path element in the pathname, if present.
c_str	Returns a pointer to the first character in mypath.
clear	Executes mypath.clear().
compare	Returns comparison values.
concat	Appends the specified sequence to mypath, converted (but not inserting a separator) as needed.
empty	Returns mypath.empty().
end	Returns an end-of-sequence iterator of type iterator.
extension	Returns the suffix of filename().
filename	Returns the root directory component of myname, specifically empty() ? path() : *--end(). The component may be empty.
generic_string	Returns this->string<Elem, Traits, Alloc>(al) with (under Windows) any backslash converted to a forward slash.
generic_u16string	Returns u16string() with (under Windows) any backslash converted to a forward slash.
generic_u32string	Returns u32string() with (under Windows) any backslash converted to a forward slash.
generic_u8string	Returns u8string() with (under Windows) any backslash converted to a forward slash.
generic_wstring	Returns wstring() with (under Windows) any backslash converted to a forward slash.
has_extension	Returns !extension().empty().
has_filename	Returns !filename().empty().
has_parent_path	Returns !parent_path().empty().
has_relative_path	Returns !relative_path().empty().
has_root_directory	Returns !root_directory().empty().
has_root_name	Returns !root_name().empty().
has_root_path	Returns !root_path().empty().
has_stem	Returns !stem().empty().
is_absolute	For Windows, the function returns has_root_name() && has_root_directory(). For POSIX, the function returns has_root_directory().
is_relative	Returns !is_absolute().
make_preferred	Converts each separator to a preferred_separator as needed.
native	Returns the native representation of the path.
parent_path	Returns the parent path component of myname.
preferred_separator	The constant object gives the preferred character for separating path components, depending on the host operating system.
relative_path	Returns the relative path component of myname.
remove_filename	Removes the filename.
replace_extension	Replaces the extension of myname.
replace_filename	Replaces the filename.
root_directory	Returns the root directory component of myname.
root_name	Returns the root name component of myname.
root_path	Returns the root path component of myname.
stem	Returns the stem component of myname.
string	Converts the sequence stored in mypath.
swap	Executes swap(mypath, right.mypath).
u16string	Converts the sequence stored in mypath to UTF-16 and returns it stored in an object of type u16string.
u32string	Converts the sequence stored in mypath to UTF-32 and returns it stored in an object of type u32string.
u8string	Converts the sequence stored in mypath to UTF-8 and returns it stored in an object of type u8string.
value_type	The type describes the path elements favored by the host operating system.
wstring	Converts the sequence stored in mypath to the encoding favored by the host system for a wchar_t sequence and returns it stored in an object of type wstring.

Operators

Operator	Description
operator=	Replaces the elements of the path with a copy of another path.
operator+=	Various concat expressions.
operator/=	Various append expressions.
operator string_type	Returns myname.

Requirements

Header:<filesystem>

Namespace:std::experimental::filesystem

path::append

Appends the specified sequence to mypath, converted and inserting a preferred_separator as needed.

template <classSource> path& append(const Source& source); template <classInIt> path& append(InIt first, InIt last);

Parameters

source
Specified sequence.

first
Start of specified sequence.

last
End of specified sequence.

path::assign

Replaces mypath with the specified sequence, converted as needed.

template <classSource> path& assign(const Source& source); template <classInIt> path& assign(InIt first, InIt last);

Parameters

source
Specified sequence.

first
Start of specified sequence.

last
End of specified sequence.

path::begin

Returns a path::iterator designating the first path element in the pathname, if present.

iterator begin() const;

path::c_str

Returns a pointer to the first character in mypath.

const value_type& *c_str() constnoexcept;

path::clear

Executes mypath.clear().

voidclear() noexcept;

path::compare

The first function returns mypath.compare(pval.native()). The second function returns mypath.compare(str). The third function returns mypath.compare(ptr).

intcompare(const path& pval) constnoexcept; intcompare(const string_type& str) const; intcompare(const value_type *ptr) const;

Parameters

pval
Path to compare.

str
String to compare.

ptr
Pointer to compare.

path::concat

Appends the specified sequence to mypath, converted (but not inserting a separator) as needed.

template <classSource> path& concat(const Source& source); template <classInIt> path& concat(InIt first, InIt last);

Parameters

source
Specified sequence.

first
Start of specified sequence.

last
End of specified sequence.

path::const_iterator

A synonym for iterator.

typedef iterator const_iterator;

path::empty

Returns mypath.empty().

boolempty() constnoexcept;

path::end

Returns an end-of-sequence iterator of type iterator.

iterator end() const;

path::extension

Returns the suffix of filename().

path extension() const;

Remarks

Returns the suffix of filename() X such that:

If X == path(".") || X == path("..") or if X contains no dot, the suffix is empty.

Otherwise, the suffix begins with (and includes) the rightmost dot.

path::filename

Returns the root directory component of myname, specifically empty() path() : *--end(). The component may be empty.

path filename() const;

path::generic_string

Returns this->string<Elem, Traits, Alloc>(al) with (under Windows) any backslash converted to a forward slash.

template <classElem, classTraits = char_traits<Elem>, classAlloc = allocator<Elem>> basic_string<Elem, Traits, Alloc> generic_string(const Alloc& al = Alloc()) const; string generic_string() const;

path::generic_u16string

Returns u16string() with (under Windows) any backslash converted to a forward slash.

u16string generic_u16string() const;

path::generic_u32string

Returns u32string() with (under Windows) any backslash converted to a forward slash.

u32string generic_u32string() const;

path::generic_u8string

Returns u8string() with (under Windows) any backslash converted to a forward slash.

string generic_u8string() const;

path::generic_wstring

Returns wstring() with (under Windows) any backslash converted to a forward slash.

wstring generic_wstring() const;

path::has_extension

Returns !extension().empty().

boolhas_extension() const;

path::has_filename

Returns !filename().empty().

boolhas_filename() const;

path::has_parent_path

Returns !parent_path().empty().

boolhas_parent_path() const;

path::has_relative_path

Returns !relative_path().empty().

boolhas_relative_path() const;

path::has_root_directory

Returns !root_directory().empty().

boolhas_root_directory() const;

path::has_root_name

Returns !root_name().empty().

boolhas_root_name() const;

path::has_root_path

Returns !root_path().empty().

boolhas_root_path() const;

path::has_stem

Returns !stem().empty().

boolhas_stem() const;

path::is_absolute

For Windows, the function returns has_root_name() && has_root_directory(). For POSIX, the function returns has_root_directory().

boolis_absolute() const;

path::is_relative

Returns !is_absolute().

boolis_relative() const;

path::iterator

A bidirectional constant iterator that designates the path components of myname.

classiterator { // bidirectional iterator for pathtypedef bidirectional_iterator_tag iterator_category; typedef path_type value_type; typedefptrdiff_t difference_type; typedefconst value_type *pointer; typedefconst value_type& reference; // ... };

Remarks

The class describes a bidirectional constant iterator that designates the path components of myname in the sequence:

1. the root name, if present

2. the root directory, if present

3. the remaining directory elements of the parent path, if present, ending with the filename, if present

For pval an object of type path:

1. path::iterator X = pval.begin() designates the first path element in the pathname, if present.

2. X == pval.end() is true when X points just past the end of the sequence of components.

3. *X returns a string that matches the current component

4. ++X designates the next component in the sequence, if present.

5. --X designates the preceding component in the sequence, if present.

6. Altering myname invalidates all iterators designating elements in myname.

path::make_preferred

Converts each separator to a preferred_separator as needed.

path& make_preferred();

path::native

Get the native string representation of the path.

const string_type& native() constnoexcept;

Remarks

The path is available in a portable generic format (see generic_string()) or the native format of the path. This function returns the native string. On a POSIX system, the generic format and the native format are the same.

In the following example running on Windows 11, the generic path string is c:/t/temp/temp.txt and the native string is c:\\t\\temp.txt

// Compile with /std:c++17 or higher #include<filesystem>intmain() { std::filesystem::path p(R"(c:\t\temp.txt)"); auto native = p.native(); // Windows: L"c:\\t\temp.txt"auto generic = p.generic_string(); // Windows: "c:/t/temp.txt" }

path::operator=

Replaces the elements of the path with a copy of another path.

path& operator=(const path& right); path& operator=(path&& right) noexcept; template <classSource> path& operator=(const Source& source);

Parameters

right
The path being copied into the path.

source
The source path.

Remarks

The first member operator copies right.myname to myname. The second member operator moves right.myname to myname. The third member operator behaves the same as *this = path(source).

path::operator+=

Various concat expressions.

path& operator+=(const path& right); path& operator+=(const string_type& str); path& operator+=(const value_type *ptr); path& operator+=(value_type elem); template <classSource> path& operator+=(const Source& source); template <classElem> path& operator+=(Elem elem);

Parameters

right
The added path.

str
The added string.

ptr
The added pointer.

elem
The added value_type or Elem.

source
The added source.

Remarks

The member functions behave the same as the following corresponding expressions:

1. concat(right);

2. concat(path(str));

3. concat(ptr);

4. concat(string_type(1, elem));

5. concat(source);

6. concat(path(basic_string<Elem>(1, elem)));

path::operator/=

Various append expressions.

path& operator/=(const path& right); template <classSource> path& operator/=(const Source& source);

Parameters

right
The added path.

source
The added source.

Remarks

The member functions behave the same as the following corresponding expressions:

1. append(right);

2. append(source);

path::operator string_type

Returns myname.

operatorstring_type() const;

path::parent_path

Returns the parent path component of myname.

path parent_path() const;

Remarks

Returns the parent path component of myname, specifically the prefix of myname after removing filename().native() and any immediately preceding directory separators. (Equally, if begin() != end(), it's the combining of all elements in the range [begin(), --end()) by successively applying operator/=.) The component may be empty.

path::path

Constructs a path in various ways.

path(); path(const path& right); path(path&& right) noexcept; template <classSource> path(const Source& source); template <classSource> path(const Source& source, const locale& loc); template <classInIt> path(InIt first, InIt last); template <classInIt> path(InIt first, InIt last, const locale& loc);

Parameters

right
The path of which the constructed path is to be a copy.

source
The source of which the constructed path is to be a copy.

loc
The specified locale.

first
The position of the first element to be copied.

last
The position of the last element to be copied.

Remarks

The constructors all construct myname in various ways:

For path() it's myname().

For path(const path& right) it's myname(right.myname).

For path(path&& right) it's myname(right.myname).

For template<class Source> path(const Source& source) it's myname(source).

For template<class Source> path(const Source& source, const locale& loc) it's myname(source), obtaining any needed codecvt facets from loc.

For template<class InIt> path(InIt first, InIt last) it's myname(first, last).

For template<class InIt> path(InIt first, InIt last, const locale& loc) it's myname(first, last), obtaining any needed codecvt facets from loc.

path::preferred_separator

The constant object gives the preferred character for separating path components, depending on the host operating system.

#if _WIN32_C_LIB staticconstexpr value_type preferred_separator == L'\\'; #else// assume POSIXstaticconstexpr value_type preferred_separator == '/'; #endif// filesystem model now defined

Remarks

It's equally permissible in most contexts under Windows to use L'/' in its place.

path::relative_path

Returns the relative path component of myname.

path relative_path() const;

Remarks

Returns the relative path component of myname, specifically the suffix of myname after removing root_path().native() and any immediately subsequent redundant directory separators. The component may be empty.

path::remove_filename

Removes the filename.

path& remove_filename();

path::replace_extension

Replaces the extension of myname.

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

Parameters

newext
The new extension.

Remarks

First removes the suffix extension().native() from myname. Then if !newext.empty() && newext[0] != dot (where dot is *path(".").c_str()), then dot is appended to myname. Then newext is appended to myname.

path::replace_filename

Replaces the filename.

path& replace_filename(const path& pval);

Parameters

pval
The path of the filename.

Remarks

The member function executes:

remove_filename(); *this /= pval; return (*this);

path::root_directory

Returns the root directory component of myname.

path root_directory() const;

Remarks

The component may be empty.

path::root_name

Returns the root name component of myname.

path root_name() const;

Remarks

The component may be empty.

path::root_path

Returns the root path component of myname.

path root_path() const;

Remarks

Returns the root path component of myname, specifically root_name() / root_directory. The component may be empty.

path::stem

Returns the stem component of myname.

path stem() const;

Remarks

Returns the stem component of myname, specifically filename().native() with any trailing extension().native() removed. The component may be empty.

path::string

Converts the sequence stored in mypath.

template \<classElem, classTraits = char_traits\<Elem>, classAlloc = allocator\<Elem>> basic_string\<Elem, Traits, Alloc> string(const Alloc& al = Alloc()) const; string string() const;

Remarks

The first (template) member function converts the sequence stored in mypath the same way as:

1. string() for string<char, Traits, Alloc>()

2. wstring() for string<wchar_t, Traits, Alloc>()

3. u16string() for string<char16_t, Traits, Alloc>()

4. u32string() for string<char32_t, Traits, Alloc>()

The second member function converts the sequence stored in mypath to the encoding favored by the host system for a char sequence and returns it stored in an object of type string.

path::string_type

The type is a synonym for basic_string<value_type>.

typedef basic_string<value_type> string_type;

path::swap

Executes swap(mypath, right.mypath).

voidswap(path& right) noexcept;

path::u16string

Converts the sequence stored in mypath to UTF-16 and returns it stored in an object of type u16string.

u16string u16string() const;

path::u32string

Converts the sequence stored in mypath to UTF-32 and returns it stored in an object of type u32string.

u32string u32string() const;

path::u8string

Converts the sequence stored in mypath to UTF-8 and returns it stored in an object of type u8string.

string u8string() const;

path::value_type

The type describes the path elements favored by the host operating system.

#if _WIN32_C_LIB typedefwchar_t value_type; #else// assume POSIXtypedefchar value_type; #endif// filesystem model now defined

path::wstring

Converts the sequence stored in mypath to the encoding favored by the host system for a wchar_t sequence and returns it stored in an object of type wstring.

wstring wstring() const;

See also

Header Files Reference