27 Input/output library [input.output]

27.11 File systems [filesystems]

27.11.7 Class path [fs.class.path]

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

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 < 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 paths' lexical representations only.
    [ Example
    :
    path("foo") == "bar" is never true.
    — end example
     ]
  • 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;
Returns: !(lhs == rhs).
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).
path operator/ (const path& lhs, const path& rhs);
Effects: Equivalent to: return path(lhs) /= rhs;

27.11.7.7.1 Factory functions [fs.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.path.type.cvt]) 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 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
 ]