27 Input/output library [input.output]

27.11 File systems [filesystems]

27.11.7 Class path [fs.class.path]

1
#
An object of class path represents a path and contains a pathname.
Such an object is concerned only with the lexical and syntactic aspects of a path.
The path does not necessarily exist in external storage, and the pathname is not necessarily valid for the current operating system or for a particular file system.
2
#
[ Note
:
Class path is used to support the differences between the string types used by different operating systems to represent pathnames, and to perform conversions between encodings when necessary.
— end note
 ]
3
#
A path is a sequence of elements that identify the location of a file within a filesystem.
The elements are the root-name, root-directory, and an optional sequence of filenames.
The maximum number of elements in the sequence is operating system dependent ([fs.conform.os]).
4
#
An absolute path is a path that unambiguously identifies the location of a file without reference to an additional starting location.
The elements of a path that determine if it is absolute are operating system dependent.
A relative path is a path that is not absolute, and as such, only unambiguously identifies the location of a file when resolved relative to an implied starting location.
The elements of a path that determine if it is relative are operating system dependent.
[ Note
:
Pathnames “.
” and “.
” are relative paths.
— end note
 ]
5
#
A pathname is a character string that represents the name of a path.
Pathnames are formatted according to the generic pathname format grammar ([fs.path.generic]) or according to an operating system dependent native pathname format accepted by the host operating system.
6
#
Pathname resolution is the operating system dependent mechanism for resolving a pathname to a particular file in a file hierarchy.
There may be multiple pathnames that resolve to the same file.
[ Example
:
POSIX specifies the mechanism in section 4.11, Pathname resolution.
— end example
 ]
namespace std::filesystem {
  class path {
  public:
    using value_type  = see below;
    using string_type = basic_string<value_type>;
    static constexpr value_type preferred_separator = see below;

    // [fs.enum.path.format], enumeration format
    enum format;

    // [fs.path.construct], constructors and destructor
    path() noexcept;
    path(const path& p);
    path(path&& p) noexcept;
    path(string_type&& source, format fmt = auto_format);
    template<class Source>
      path(const Source& source, format fmt = auto_format);
    template<class InputIterator>
      path(InputIterator first, InputIterator last, format fmt = auto_format);
    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);
    ~path();

    // [fs.path.assign], assignments
    path& operator=(const path& p);
    path& operator=(path&& p) noexcept;
    path& operator=(string_type&& source);
    path& assign(string_type&& source);
    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);

    // [fs.path.append], appends
    path& operator/=(const path& p);
    template<class Source>
      path& operator/=(const Source& source);
    template<class Source>
      path& append(const Source& source);
    template<class InputIterator>
      path& append(InputIterator first, InputIterator last);

    // [fs.path.concat], concatenation
    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);
    template<class InputIterator>
      path& concat(InputIterator first, InputIterator last);

    // [fs.path.modifiers], modifiers
    void  clear() noexcept;
    path& make_preferred();
    path& remove_filename();
    path& replace_filename(const path& replacement);
    path& replace_extension(const path& replacement = path());
    void  swap(path& rhs) noexcept;

    // [fs.path.native.obs], native format observers
    const string_type& native() const noexcept;
    const value_type*  c_str() const noexcept;
    operator string_type() const;

    template<class EcharT, class traits = char_traits<EcharT>,
             class Allocator = allocator<EcharT>>
      basic_string<EcharT, traits, Allocator>
        string(const Allocator& a = Allocator()) const;
    std::string    string() const;
    std::wstring   wstring() const;
    std::string    u8string() const;
    std::u16string u16string() const;
    std::u32string u32string() const;

    // [fs.path.generic.obs], generic format observers
    template<class EcharT, class traits = char_traits<EcharT>,
             class Allocator = allocator<EcharT>>
      basic_string<EcharT, traits, Allocator>
        generic_string(const Allocator& a = Allocator()) const;
    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;

    // [fs.path.compare], compare
    int compare(const path& p) const noexcept;
    int compare(const string_type& s) const;
    int compare(basic_string_view<value_type> s) const;
    int compare(const value_type* s) const;

    // [fs.path.decompose], decomposition
    path root_name() const;
    path root_directory() const;
    path root_path() const;
    path relative_path() const;
    path parent_path() const;
    path filename() const;
    path stem() const;
    path extension() const;

    // [fs.path.query], query
    [[nodiscard]] bool empty() const noexcept;
    bool has_root_name() const;
    bool has_root_directory() const;
    bool has_root_path() const;
    bool has_relative_path() const;
    bool has_parent_path() const;
    bool has_filename() const;
    bool has_stem() const;
    bool has_extension() const;
    bool is_absolute() const;
    bool is_relative() const;

    // [fs.path.gen], generation
    path lexically_normal() const;
    path lexically_relative(const path& base) const;
    path lexically_proximate(const path& base) const;

    // [fs.path.itr], iterators
    class iterator;
    using const_iterator = iterator;

    iterator begin() const;
    iterator end() const;

    // [fs.path.io], path inserter and extractor
    template<class charT, class traits>
      friend basic_ostream<charT, traits>&
        operator<<(basic_ostream<charT, traits>& os, const path& p);
    template<class charT, class traits>
      friend basic_istream<charT, traits>&
        operator>>(basic_istream<charT, traits>& is, path& p);
  };
}
7
#
value_­type is a typedef for the operating system dependent encoded character type used to represent pathnames.
8
#
The value of the preferred_­separator member is the operating system dependent preferred-separator character ([fs.path.generic]).
9
#
[ Example
:
For POSIX-based operating systems, value_­type is char and preferred_­separator is the slash character ('/').
For Windows-based operating systems, value_­type is wchar_­t and preferred_­separator is the backslash character (L'\\').
— end example
 ]

27.11.7.1 Generic pathname format [fs.path.generic]

pathname:
	root-name root-directory relative-path

root-name:
	operating system dependent sequences of characters
	implementation-defined sequences of characters

root-directory:
	directory-separator

relative-path:
	filename
	filename directory-separator relative-path
	an empty path

filename:
	non-empty sequence of characters other than directory-separator characters

directory-separator:
	preferred-separator directory-separator
	fallback-separator directory-separator

preferred-separator:
	operating system dependent directory separator character

fallback-separator:
	/, if preferred-separator is not /
1
#
A filename is the name of a file.
The dot and dot-dot filenames, consisting solely of one and two period characters respectively, have special meaning.
The following characteristics of filenames are operating system dependent:
  • (1.1)
    The permitted characters.
    [ Example
    :
    Some operating systems prohibit the ASCII control characters (0x00 – 0x1F) in filenames.
    — end example
     ]
    [ Note
    :
    For wide portability, users may wish to limit filename characters to the POSIX Portable Filename Character Set:
    A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
    a b c d e f g h i j k l m n o p q r s t u v w x y z
    0 1 2 3 4 5 6 7 8 9 . _­ -
    — end note
     ]
  • (1.2)
    The maximum permitted length.
  • (1.3)
    Filenames that are not permitted.
  • (1.4)
    Filenames that have special meaning.
  • (1.5)
    Case awareness and sensitivity during path resolution.
  • (1.6)
    Special rules that may apply to file types other than regular files, such as directories.
2
#
Except in a root-name, multiple successive directory-separator characters are considered to be the same as one directory-separator character.
3
#
The dot filename is treated as a reference to the current directory.
The dot-dot filename is treated as a reference to the parent directory.
What the dot-dot filename refers to relative to root-directory is implementation-defined.
Specific filenames may have special meanings for a particular operating system.
4
#
A root-name identifies the starting location for pathname resolution ([fs.class.path]).
If there are no operating system dependent root-names, at least one implementation-defined root-name is required.
[ Note
:
Many operating systems define a name beginning with two directory-separator characters as a root-name that identifies network or other resource locations.
Some operating systems define a single letter followed by a colon as a drive specifier – a root-name identifying a specific device such as a disk drive.
— end note
 ]
5
#
If a root-name is otherwise ambiguous, the possibility with the longest sequence of characters is chosen.
[ Note
:
On a POSIX-like operating system, it is impossible to have a root-name and a relative-path without an intervening root-directory element.
— end note
 ]
6
#
Normalization of a generic format pathname means:
  1. 1.
    If the path is empty, stop.
  2. 2.
    Replace each slash character in the root-name with a preferred-separator.
  3. 3.
    [ Note
    :
    The generic pathname grammar ([fs.path.generic]) defines directory-separator as one or more slashes and preferred-separators.
    — end note
     ]
  4. 4.
    Remove each dot filename and any immediately following directory-separator.
  5. 5.
    As long as any appear, remove a non-dot-dot filename immediately followed by a directory-separator and a dot-dot filename, along with any immediately following directory-separator.
  6. 6.
    If there is a root-directory, remove all dot-dot filenames and any directory-separators immediately following them.
    [ Note
    :
    These dot-dot filenames attempt to refer to nonexistent parent directories.
    — end note
     ]
  7. 7.
    If the last filename is dot-dot, remove any trailing directory-separator.
  8. 8.
    If the path is empty, add a dot.
The result of normalization is a path in normal form, which is said to be normalized.

27.11.7.2 path conversions [fs.path.cvt]

27.11.7.2.1 path argument format conversions [fs.path.fmt.cvt]

1
#
[ Note
:
The format conversions described in this subclause are not applied on POSIX-based operating systems because on these systems:
  • (1.1)
    The generic format is acceptable as a native path.
  • (1.2)
    There is no need to distinguish between native format and generic format in function arguments.
  • (1.3)
    Paths for regular files and paths for directories share the same syntax.
— end note
 ]
2
#
Several functions are defined to accept detected-format arguments, which are character sequences.
A detected-format argument represents a path using either a pathname in the generic format ([fs.path.generic]) or a pathname in the native format ([fs.class.path]).
Such an argument is taken to be in the generic format if and only if it matches the generic format and is not acceptable to the operating system as a native path.
3
#
[ Note
:
Some operating systems may have no unambiguous way to distinguish between native format and generic format arguments.
This is by design as it simplifies use for operating systems that do not require disambiguation.
An implementation for an operating system where disambiguation is required is permitted to distinguish between the formats.
— end note
 ]
4
#
Pathnames are converted as needed between the generic and native formats in an operating-system-dependent manner.
Let G(n) and N(g) in a mathematical sense be the implementation's functions that convert native-to-generic and generic-to-native formats respectively.
If g=G(n) for some n, then G(N(g))=g; if n=N(g) for some g, then N(G(n))=n.
[ Note
:
Neither G nor N need be invertible.
— end note
 ]
5
#
If the native format requires paths for regular files to be formatted differently from paths for directories, the path shall be treated as a directory path if its last element is a directory-separator, otherwise it shall be treated as a path to a regular file.
6
#
[ Note
:
A path stores a native format pathname ([fs.path.native.obs]) and acts as if it also stores a generic format pathname, related as given below.
The implementation may generate the generic format pathname based on the native format pathname (and possibly other information) when requested.
— end note
 ]
7
#
When a path is constructed from or is assigned a single representation separate from any path, the other representation is selected by the appropriate conversion function (G or N).
8
#
When the (new) value p of one representation of a path is derived from the representation of that or another path, a value q is chosen for the other representation.
The value q converts to p (by G or N as appropriate) if any such value does so; q is otherwise unspecified.
[ Note
:
If q is the result of converting any path at all, it is the result of converting p.
— end note
 ]

27.11.7.2.2 path type and encoding conversions [fs.path.type.cvt]

1
#
The native encoding of a narrow character string is the operating system dependent current encoding for pathnames ([fs.class.path]).
The native encoding for wide character strings is the implementation-defined execution wide-character set encoding ([lex.charset]).
2
#
For member function arguments that take character sequences representing paths and for member functions returning strings, value type and encoding conversion is performed if the value type of the argument or return value differs from path​::​value_­type.
For the argument or return value, the method of conversion and the encoding to be converted to is determined by its value type:
  • (2.1)
    char: The encoding is the native narrow encoding.
    The method of conversion, if any, is operating system dependent.
    [ Note
    :
    For POSIX-based operating systems path​::​value_­type is char so no conversion from char value type arguments or to char value type return values is performed.
    For Windows-based operating systems, the native narrow encoding is determined by calling a Windows API function.
    — end note
     ]
    [ Note
    :
    This results in behavior identical to other C and C++ standard library functions that perform file operations using narrow character strings to identify paths.
    Changing this behavior would be surprising and error prone.
    — end note
     ]
  • (2.2)
    wchar_­t: The encoding is the native wide encoding.
    The method of conversion is unspecified.
    [ Note
    :
    For Windows-based operating systems path​::​value_­type is wchar_­t so no conversion from wchar_­t value type arguments or to wchar_­t value type return values is performed.
    — end note
     ]
  • (2.3)
    char16_­t: The encoding is UTF-16.
    The method of conversion is unspecified.
  • (2.4)
    char32_­t: The encoding is UTF-32.
    The method of conversion is unspecified.
3
#
If the encoding being converted to has no representation for source characters, the resulting converted characters, if any, are unspecified.
Implementations should not modify member function arguments if already of type path​::​value_­type.

27.11.7.3 path requirements [fs.path.req]

1
#
In addition to the requirements ([fs.req]), function template parameters named Source shall be one of:
  • (1.1)
    basic_­string<EcharT, traits, Allocator>.
    A function argument const Source& source shall have an effective range [source.begin(), source.end()).
  • (1.2)
    basic_­string_­view<EcharT, traits>.
    A function argument const Source& source shall have an effective range [source.begin(), source.end()).
  • (1.3)
    A type meeting the Cpp17InputIterator requirements that iterates over a NTCTS.
    The value type shall be an encoded character type.
    A function argument const Source& source shall have an effective range [source, end) where end is the first iterator value with an element value equal to iterator_­traits<Source>​::​value_­type().
  • (1.4)
    A character array that after array-to-pointer decay results in a pointer to the start of a NTCTS.
    The value type shall be an encoded character type.
    A function argument const Source& source shall have an effective range [source, end) where end is the first iterator value with an element value equal to iterator_­traits<decay_­t<Source>>​::​value_­type().
2
#
Functions taking template parameters named Source shall not participate in overload resolution unless either
  • (2.1)
    Source is a specialization of basic_­string or basic_­string_­view, or
  • (2.2)
    the qualified-id iterator_­traits<decay_­t<Source>>​::​value_­type is valid and denotes a possibly const encoded character type ([temp.deduct]).
3
#
[ Note
:
See path conversions for how the value types above and their encodings convert to path​::​value_­type and its encoding.
— end note
 ]
4
#
Arguments of type Source shall not be null pointers.

27.11.7.4 path members [fs.path.member]

27.11.7.4.1 path constructors [fs.path.construct]

🔗
path() noexcept;
1
#
Effects: Constructs an object of class path.
2
#
Ensures: empty() == true.
🔗
path(const path& p); path(path&& p) noexcept;
3
#
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);
4
#
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);
5
#
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);
6
#
Requires: The value type of Source and InputIterator is char.
7
#
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.path.type.cvt]) 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.
8
#
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.path.type.cvt]).
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
 ]

27.11.7.4.2 path assignments [fs.path.assign]

🔗
path& operator=(const path& p);
1
#
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.
2
#
Returns: *this.
🔗
path& operator=(path&& p) noexcept;
3
#
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
 ]
4
#
Returns: *this.
🔗
path& operator=(string_type&& source); path& assign(string_type&& source);
5
#
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.
6
#
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);
7
#
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.
8
#
Returns: *this.

27.11.7.4.3 path appends [fs.path.append]

1
#
The append operations use operator/= to denote their semantic effect of appending preferred-separator when needed.
🔗
path& operator/=(const path& p);
2
#
Effects: If p.is_­absolute() || (p.has_­root_­name() && p.root_­name() != root_­name()), then operator=(p).
3
#
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.
4
#
[ 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
 ]
5
#
Returns: *this.
🔗
template<class Source> path& operator/=(const Source& source); template<class Source> path& append(const Source& source);
6
#
Effects: Equivalent to: return operator/=(path(source));
🔗
template<class InputIterator> path& append(InputIterator first, InputIterator last);
7
#
Effects: Equivalent to: return operator/=(path(first, last));

27.11.7.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);
1
#
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
 ]
2
#
Returns: *this.
🔗
template<class InputIterator> path& concat(InputIterator first, InputIterator last);
3
#
Effects: Equivalent to: return *this += path(first, last);

27.11.7.4.5 path modifiers [fs.path.modifiers]

🔗
void clear() noexcept;
1
#
Ensures: empty() == true.
🔗
path& make_preferred();
2
#
Effects: Each directory-separator of the pathname in the generic format is converted to preferred-separator.
3
#
Returns: *this.
4
#
[ 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();
5
#
Ensures: !has_­filename().
6
#
Effects: Remove the generic format pathname of filename() from the generic format pathname.
7
#
Returns: *this.
8
#
[ 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);
9
#
Effects: Equivalent to: 
remove_filename();
operator/=(replacement);
10
#
Returns: *this.
11
#
[ 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());
12
#
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);.
13
#
Returns: *this.
🔗
void swap(path& rhs) noexcept;
14
#
Effects: Swaps the contents (in all formats) of the two paths.
15
#
Complexity: Constant time.

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

1
#
The string returned by all native format observers is in the native pathname format ([fs.class.path]).
🔗
const string_type& native() const noexcept;
2
#
Returns: The pathname in the native format.
🔗
const value_type* c_str() const noexcept;
3
#
Effects: Equivalent to: return native().c_­str();
🔗
operator string_type() const;
4
#
Returns: native().
5
#
[ 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;
6
#
Returns: native().
7
#
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;
8
#
Returns: native().
9
#
Remarks: Conversion, if any, is performed as specified by [fs.path.cvt].
The encoding of the string returned by u8string() is always UTF-8.

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

1
#
Generic format observer functions return strings formatted according to the generic pathname format.
A single slash ('/') character is used as the directory-separator.
2
#
[ 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;
3
#
Returns: The pathname in the generic format.
4
#
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;
5
#
Returns: The pathname in the generic format.
6
#
Remarks: Conversion, if any, is specified by [fs.path.cvt].
The encoding of the string returned by generic_­u8string() is always UTF-8.

27.11.7.4.8 path compare [fs.path.compare]

🔗
int compare(const path& p) const noexcept;
1
#
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.
2
#
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;
3
#
Returns: compare(path(s)).
🔗
int compare(const value_type* s) const
4
#
Returns: compare(path(s)).

27.11.7.4.9 path decomposition [fs.path.decompose]

🔗
path root_name() const;
1
#
Returns: root-name, if the pathname in the generic format includes root-name, otherwise path().
🔗
path root_directory() const;
2
#
Returns: root-directory, if the pathname in the generic format includes root-directory, otherwise path().
🔗
path root_path() const;
3
#
Returns: root_­name() / root_­directory().
🔗
path relative_path() const;
4
#
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().
🔗
path parent_path() const;
5
#
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.
🔗
path filename() const;
6
#
Returns: relative_­path().empty() ? path() : *--end().
7
#
[ 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;
8
#
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.
9
#
[ 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;
10
#
Returns: A path whose pathname in the generic format is the suffix of filename() not included in stem().
11
#
[ 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
 ]
12
#
[ 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
 ]
13
#
[ 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
 ]

27.11.7.4.10 path query [fs.path.query]

🔗
[[nodiscard]] bool empty() const noexcept;
1
#
Returns: true if the pathname in the generic format is empty, else false.
🔗
bool has_root_path() const;
2
#
Returns: !root_­path().empty().
🔗
bool has_root_name() const;
3
#
Returns: !root_­name().empty().
🔗
bool has_root_directory() const;
4
#
Returns: !root_­directory().empty().
🔗
bool has_relative_path() const;
5
#
Returns: !relative_­path().empty().
🔗
bool has_parent_path() const;
6
#
Returns: !parent_­path().empty().
🔗
bool has_filename() const;
7
#
Returns: !filename().empty().
🔗
bool has_stem() const;
8
#
Returns: !stem().empty().
🔗
bool has_extension() const;
9
#
Returns: !extension().empty().
🔗
bool is_absolute() const;
10
#
Returns: true if the pathname in the native format contains an absolute path ([fs.class.path]), else false.
11
#
[ Example
:
path("/").is_­absolute() is true for POSIX-based operating systems, and false for Windows-based operating systems.
— end example
 ]
🔗
bool is_relative() const;
12
#
Returns: !is_­absolute().

27.11.7.4.11 path generation [fs.path.gen]

🔗
path lexically_normal() const;
1
#
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.
2
#
[ 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;
3
#
Returns: *this made relative to base.
Does not resolve ([fs.class.path]) symlinks.
Does not first normalize ([fs.path.generic]) *this or base.
4
#
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()).
5
#
[ 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
 ]
6
#
[ Note
:
If symlink following semantics are desired, use the operational function relative().
— end note
 ]
7
#
[ Note
:
If normalization ([fs.path.generic]) 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;
8
#
Returns: If the value of lexically_­relative(base) is not an empty path, return it.
Otherwise return *this.
9
#
[ Note
:
If symlink following semantics are desired, use the operational function proximate().
— end note
 ]
10
#
[ Note
:
If normalization ([fs.path.generic]) is needed to ensure consistent matching of elements, apply lexically_­normal() to *this, base, or both.
— end note
 ]

27.11.7.5 path iterators [fs.path.itr]

1
#
Path iterators iterate over the elements of the pathname in the generic format.
2
#
A path​::​iterator is a constant iterator satisfying all the requirements of a bidirectional iterator except that, for dereferenceable iterators a and b of type path​::​iterator with a == b, there is no requirement that *a and *b are bound to the same object.
Its value_­type is path.
3
#
Calling any non-const member function of a path object invalidates all iterators referring to elements of that object.
4
#
For the elements of the pathname in the generic format, the forward traversal order is as follows:
5
#
The backward traversal order is the reverse of forward traversal.
🔗
iterator begin() const;
6
#
Returns: An iterator for the first present element in the traversal list above.
If no elements are present, the end iterator.
🔗
iterator end() const;
7
#
Returns: The end iterator.

27.11.7.6 path inserter and extractor [fs.path.io]

🔗
template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const path& p);
1
#
Effects: Equivalent to os << quoted(p.string<charT, traits>()).
[ Note
:
The quoted function is described in [quoted.manip].
— end note
 ]
2
#
Returns: os.
🔗
template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, path& p);
3
#
Effects: Equivalent to: 
basic_string<charT, traits> tmp;
is >> quoted(tmp);
p = tmp;
4
#
Returns: is.

27.11.7.7 path non-member functions [fs.path.nonmember]

🔗
void swap(path& lhs, path& rhs) noexcept;
1
#
Effects: Equivalent to lhs.swap(rhs).
🔗
size_t hash_value (const path& p) noexcept;
2
#
Returns: A hash value for the path p.
If for two paths, p1 == p2 then hash_­value(p1) == hash_­value(p2).
🔗
bool operator==(const path& lhs, const path& rhs) noexcept;
3
#
Returns: !(lhs < rhs) && !(rhs < lhs).
4
#
[ Note
:
Path equality and path equivalence have different semantics.
  • (4.1)
    Equality is determined by the path non-member operator==, which considers the two paths' lexical representations only.
    [ Example
    :
    path("foo") == "bar" is never true.
    — end example
     ]
  • (4.2)
    Equivalence is determined by the equivalent() non-member function, which determines if two paths resolve ([fs.class.path]) to the same file system entity.
    [ Example
    :
    equivalent("foo", "bar") will be true when both paths resolve to the same file.
    — end example
     ]
Programmers wishing to determine if two paths are “the same” must decide if “the same” means “the same representation” or “resolve to the same actual file”, and choose the appropriate function accordingly.
— end note
 ]
🔗
bool operator!=(const path& lhs, const path& rhs) noexcept;
5
#
Returns: !(lhs == rhs).
🔗
bool operator< (const path& lhs, const path& rhs) noexcept;
6
#
Returns: lhs.compare(rhs) < 0.
🔗
bool operator<=(const path& lhs, const path& rhs) noexcept;
7
#
Returns: !(rhs < lhs).
🔗
bool operator> (const path& lhs, const path& rhs) noexcept;
8
#
Returns: rhs < lhs.
🔗
bool operator>=(const path& lhs, const path& rhs) noexcept;
9
#
Returns: !(lhs < rhs).
🔗
path operator/ (const path& lhs, const path& rhs);
10
#
Effects: Equivalent to: return path(lhs) /= rhs;

27.11.7.7.1 path factory functions [fs.path.factory]

🔗
template<class Source> path u8path(const Source& source); template<class InputIterator> path u8path(InputIterator first, InputIterator last);
1
#
Requires: The source and [first, last) sequences are UTF-8 encoded.
The value type of Source and InputIterator is char.
2
#
Returns:
  • (2.1)
    If value_­type is char and the current native narrow encoding ([fs.path.type.cvt]) is UTF-8, return path(source) or path(first, last); otherwise,
  • (2.2)
    if value_­type is wchar_­t and the native wide encoding is UTF-16, or if value_­type is char16_­t or char32_­t, convert source or [first, last) to a temporary, tmp, of type string_­type and return path(tmp); otherwise,
  • (2.3)
    convert source or [first, last) to a temporary, tmp, of type u32string and return path(tmp).
3
#
Remarks: Argument format conversion applies to the arguments for these functions.
How Unicode encoding conversions are performed is unspecified.
4
#
[ Example
:
A string is to be read from a database that is encoded in UTF-8, and used to create a directory using the native encoding for filenames: 
namespace fs = std::filesystem;
std::string utf8_string = read_utf8_data();
fs::create_directory(fs::u8path(utf8_string));
For POSIX-based operating systems with the native narrow encoding set to UTF-8, no encoding or type conversion occurs.
For POSIX-based operating systems with the native narrow encoding not set to UTF-8, a conversion to UTF-32 occurs, followed by a conversion to the current native narrow encoding.
Some Unicode characters may have no native character set representation.
For Windows-based operating systems a conversion from UTF-8 to UTF-16 occurs.
— end example
 ]