27 Input/output library [input.output]

27.10 File systems [filesystems]

27.10.8 Class path [class.path]

27.10.8.6 path non-member functions [path.non-member]

void swap(path& lhs, path& rhs) noexcept;

Effects: Equivalent to: lhs.swap(rhs);

size_t hash_value (const path& p) noexcept;

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;

Returns: lhs.compare(rhs) < 0.

bool operator<=(const path& lhs, const path& rhs) noexcept;

Returns: !(rhs < lhs).

bool operator> (const path& lhs, const path& rhs) noexcept;

Returns: rhs < lhs.

bool operator>=(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs < rhs).

bool operator==(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs < rhs) && !(rhs < lhs).

Note: Path equality and path equivalence have different semantics.

Equality is determined by the path non-member operator==, which considers the two path's lexical representations only. Thus path("foo") == "bar" is never true.

Equivalence is determined by the equivalent() non-member function, which determines if two paths resolve ([fs.def.pathres]) to the same file system entity. Thus equivalent("foo", "bar") will be true when both paths resolve to the same file.

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;

Returns: !(lhs == rhs).

path operator/ (const path& lhs, const path& rhs);

Effects: Equivalent to: return path(lhs) /= rhs;

27.10.8.6.1 path inserter and extractor [path.io]

template <class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const path& p);

Effects: Equivalent to: os << quoted(p.string<charT, traits>());Note: The quoted function is described in [quoted.manip].  — end note ]

Returns: os.

template <class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, path& p);

Effects: Equivalent to:

basic_string<charT, traits> tmp;
is >> quoted(tmp);
p = tmp;

Returns: is.

27.10.8.6.2 path factory functions [path.factory]

template <class Source> path u8path(const Source& source); template <class InputIterator> path u8path(InputIterator first, InputIterator last);

Requires: The source and [first, last) sequences are UTF-8 encoded. The value type of Source and InputIterator is char.

Returns:

  • If value_type is char and the current native narrow encoding ([fs.def.native.encode]) is UTF-8, return path(source) or path(first, last); otherwise,

  • 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,

  • convert source or [first, last) to a temporary, tmp, of type u32string and return path(tmp).

Remarks: Argument format conversion ([path.fmt.cvt]) applies to the arguments for these functions. How Unicode encoding conversions are performed is unspecified.

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 ]