Annex D (normative) Compatibility features [depr]

D.21 Deprecated filesystem path factory functions [depr.fs.path.factory]

The header <filesystem> has the following additions:

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

Mandates: The value type of Source and InputIterator is char or char8_t.

Preconditions: The source and [first, last) sequences are UTF-8 encoded.

Source meets the requirements specified in [fs.path.req].

Returns:

(4.1)
If path::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,
(4.2)
if path::value_type is wchar_t and the native wide encoding is UTF-16, or if path::value_type is char16_t or char32_t, convert source or [first, last) to a temporary, tmp, of type path::string_type and return path(tmp); otherwise,
(4.3)
convert source or [first, last) to a temporary, tmp, of type u32string and return path(tmp).

Remarks: Argument format conversion ([fs.path.fmt.cvt]) applies to the arguments for these functions.

How Unicode encoding conversions are performed is unspecified.

[Example 1:

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]

[Note 1:

The example above is representative of a historical use of filesystem::u8path.

To indicate a UTF-8 encoding, passing a std::u8string to path's constructor is preferred as it is consistent with path's handling of other encodings.

— end note]