30 Input/output library [input.output]

30.10 File systems [filesystems]

30.10.27 Class path [fs.class.path]

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

30.10.27.6.2 path 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 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]