An object of class path represents a path ([fs.def.path]) and contains a pathname ([fs.def.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.
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;
// [path.construct], constructors and destructor
path() noexcept;
path(const path& p);
path(path&& p) noexcept;
path(string_type&& source);
template <class Source>
path(const Source& source);
template <class InputIterator>
path(InputIterator first, InputIterator last);
template <class Source>
path(const Source& source, const locale& loc);
template <class InputIterator>
path(InputIterator first, InputIterator last, const locale& loc);
~path();
// [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);
// [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);
// [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);
// [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;
// [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;
// [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;
// [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;
// [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;
// [path.query], query
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;
// [path.gen], generation
path lexically_normal() const;
path lexically_relative(const path& base) const;
path lexically_proximate(const path& base) const;
// [path.itr], iterators
class iterator;
using const_iterator = iterator;
iterator begin() const;
iterator end() const;
private:
string_type pathstring; // exposition only
};
}
value_type is a typedef for the operating system dependent encoded character type used to represent pathnames.
The value of preferred_separator is the operating system dependent preferred-separator character ([path.generic]).
[ 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 ]
pathname: root-name root-directoryopt relative-pathopt root-directory relative-pathopt relative-path
root-name: An operating system dependent name that identifies the starting location for absolute paths. [ 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 ]
root-directory: directory-separator
relative-path: filename relative-path directory-separator relative-path directory-separator filename
filename: name dot dot-dot
name: A sequence of characters other than directory-separator characters. [ Note: Operating systems often place restrictions on the characters that may be used in a filename. 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 ]
dot: The filename consisting solely of a single period character (.).
dot-dot: The filename consisting solely of two period characters (..).
directory-separator: slash slash directory-separator preferred-separator preferred-separator directory-separator
preferred-separator: An operating system dependent directory separator character. May be a synonym for slash.
slash: The slash character (/).
Multiple successive directory-separator characters are considered to be the same as one directory-separator character.
The filename dot is treated as a reference to the current directory. The filename dot-dot is treated as a reference to the parent directory. What the filename dot-dot refers to relative to root-directory is implementation-defined. Specific filenames may have special meanings for a particular operating system.
[ Note: The format conversions described in this section are not applied on POSIX- or Windows-based operating systems because on these systems:
The generic format is acceptable as a native path.
There is no need to distinguish between native format and generic format in function arguments.
Paths for regular files and paths for directories share the same syntax.
— end note ]
Function arguments that take character sequences representing paths may use the generic pathname format grammar ([path.generic]) or the native pathname format ([fs.def.native]). If and only if such arguments are in the generic format and the generic format is not acceptable to the operating system as a native path, conversion to native format shall be performed during the processing of the argument.
[ 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 ]
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.
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:
char: The encoding is the native narrow encoding ([fs.def.native.encode]). 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 ]
wchar_t: The encoding is the native wide encoding ([fs.def.native.encode]). 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 ]
char16_t: The encoding is UTF-16. The method of conversion is unspecified.
char32_t: The encoding is UTF-32. The method of conversion is unspecified.
If the encoding being converted to has no representation for source characters, the resulting converted characters, if any, are unspecified.
In addition to the requirements ([fs.req]), function template parameters named Source shall be one of:
basic_string<EcharT, traits, Allocator>. A function argument const Source& source shall have an effective range [source.begin(), source.end()).
basic_string_view<EcharT, traits>. A function argument const Source& source shall have an effective range [source.begin(), source.end()).
A type meeting the input iterator 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().
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().
Functions taking template parameters named Source shall not participate in overload resolution unless either Source is a specialization of basic_string or basic_string_view or the qualified-id iterator_traits<decay_t<Source>>::value_type is valid and denotes a possibly const encoded character type ([temp.deduct]).
[ Note: See path conversions ([path.cvt]) for how the value types above and their encodings convert to path::value_type and its encoding. — end note ]
Arguments of type Source shall not be null pointers.
Effects: Constructs an object of class path.
Postconditions: empty() == true.
path(const path& p);
path(path&& p) noexcept;
Effects: Constructs an object of class path with pathstring having the original value of p.pathstring. In the second form, p is left in a valid but unspecified state.
Effects: Constructs an object of class path with pathstring having the original value of source. source is left in a valid but unspecified state.
template <class Source>
path(const Source& source);
template <class InputIterator>
path(InputIterator first, InputIterator last);
Effects: Constructs an object of class path, storing the effective range of source ([path.req]) or the range [first, last) in pathstring, converting format and encoding if required ([path.cvt]).
template <class Source>
path(const Source& source, const locale& loc);
template <class InputIterator>
path(InputIterator first, InputIterator last, const locale& loc);
Requires: The value type of Source and InputIterator is char.
Effects: Constructs an object of class path, storing the effective range of source or the range [first, last) in pathstring, after converting format if required and after converting the encoding as follows:
If value_type is wchar_t, converts to the native wide encoding ([fs.def.native.encode]) using the codecvt<wchar_t, char, mbstate_t> facet of loc.
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.
[ 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.def.native.encode]). The resulting wide string is then converted to a narrow character pathstring 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 pathstring string. All of the characters in the ISO/IEC 8859-1 character set will be converted to their Unicode representation. — end example ]
path& operator=(const path& p);
Effects: If *this and p are the same object, has no effect. Otherwise, modifies pathstring to have the original value of p.pathstring.
Returns: *this.
path& operator=(path&& p) noexcept;
Effects: If *this and p are the same object, has no effect. Otherwise, modifies pathstring to have the original value of p.pathstring. p is left in a valid but unspecified state. [ Note: A valid implementation is swap(p). — end note ]
Returns: *this.
path& operator=(string_type&& source);
path& assign(string_type&& source);
Effects: Modifies pathstring to have the original value of source. source is left in a valid but unspecified state.
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);
Effects: Stores the effective range of source ([path.req]) or the range [first, last) in pathstring, converting format and encoding if required ([path.cvt]).
Returns: *this.
The append operations use operator/= to denote their semantic effect of appending preferred-separator when needed.
Requires: !p.has_root_name().
Effects: Appends path::preferred_separator to pathstring unless:
an added directory-separator would be redundant, or
an added directory-separator would change a relative path into an absolute path [ Note: An empty path is relative. — end note ], or
p.empty() is true, or
*p.native().cbegin() is a directory-separator.
Then appends p.native() to pathstring.
Returns: *this.
template <class Source>
path& operator/=(const Source& source);
template <class Source>
path& append(const Source& source);
Effects: Equivalent to: return operator/=(path(source));
template <class InputIterator>
path& append(InputIterator first, InputIterator last);
Effects: Equivalent to: return operator/=(path(first, last));
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);
Postconditions: native() == prior_native + effective-argument, where prior_native is native() prior to the call to operator+=, and effective-argument is:
if x is present and is const path&, x.native(); otherwise,
if source is present, the effective range of source ([path.req]); otherwise,
if first and last are present, the range [first, last); otherwise,
x.
If the value type of effective-argument would not be path::value_type, the actual argument or argument range is first converted ([path.type.cvt]) so that effective-argument has value type path::value_type.
Returns: *this.
Postconditions: empty() == true.
Effects: Each directory-separator is converted to preferred-separator.
Returns: *this.
[ Example:
path p("foo/bar");
std::cout << p << '\n';
p.make_preferred();
std::cout << p << '\n';
On an operating system where preferred-separator is the same as directory-separator, 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 ]
Postconditions: !has_filename().
Returns: *this.
[ Example:
std::cout << path("/foo").remove_filename(); // outputs "/"
std::cout << path("/").remove_filename(); // outputs ""
— end example ]
path& replace_filename(const path& replacement);
Effects: Equivalent to:
remove_filename(); operator/=(replacement);
Returns: *this.
[ Example:
std::cout << path("/").replace_filename("bar"); // outputs "bar"
— end example ]
path& replace_extension(const path& replacement = path());
Effects: pathstring (the stored path) is modified as follows:
Any existing extension()([path.decompose]) is removed from the stored path, then
If replacement is not empty and does not begin with a dot character, a dot character is appended to the stored path, then
replacement is concatenated to the stored path.
Returns: *this.
void swap(path& rhs) noexcept;
Effects: Swaps the contents of the two paths pathstring and rhs.pathstring.
Complexity: Constant time.
The string returned by all native format observers is in the native pathname format ([fs.def.native]).
Returns: pathstring.
const value_type* c_str() const noexcept;
Returns: pathstring.c_str().
Returns: pathstring.
[ 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;
Returns: pathstring.
Remarks: All memory allocation, including for the return value, shall be performed by a. Conversion, if any, is specified by [path.cvt].
std::string string() const;
std::wstring wstring() const;
std::string u8string() const;
std::u16string u16string() const;
std::u32string u32string() const;
Returns: pathstring.
Remarks: Conversion, if any, is performed as specified by [path.cvt]. The encoding of the string returned by u8string() is always UTF-8.
Generic format observer functions return strings formatted according to the generic pathname format ([path.generic]). The forward slash ('/') character is used as the directory-separator character.
[ 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;
Returns: pathstring, reformatted according to the generic pathname format ([path.generic]).
Remarks: All memory allocation, including for the return value, shall be performed by a. Conversion, if any, is specified by [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;
Returns: pathstring, reformatted according to the generic pathname format ([path.generic]).
Remarks: Conversion, if any, is specified by [path.cvt]. The encoding of the string returned by generic_u8string() is always UTF-8.
int compare(const path& p) const noexcept;
Returns:
A value less than 0, if native() for the elements of *this are lexicographically less than native() for the elements of p; otherwise,
a value greater than 0, if native() for the elements of *this are lexicographically greater than native() for the elements of p; otherwise,
0.
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;
Returns: compare(path(s)).
int compare(const value_type* s) const
Returns: compare(path(s)).
Returns: root-directory, if pathstring includes root-directory, otherwise path().
Returns: root_name() / root_directory().
Returns: A path composed from pathstring, if !empty(), beginning with the first filename after root-path. Otherwise, path().
Returns: (empty() || begin() == --end()) ? path() : pp, where pp is constructed as if by starting with an empty path and successively applying operator/= for each element in the range [begin(), --end()).
Returns: empty() ? path() : *--end().
[ Example:
std::cout << path("/foo/bar.txt").filename(); // outputs "bar.txt"
std::cout << path("/").filename(); // outputs "/"
std::cout << path(".").filename(); // outputs "."
std::cout << path("..").filename(); // outputs ".."
— end example ]
Returns: if filename() contains a period but does not consist solely of one or two periods, returns the substring of filename() starting at its beginning and ending with the character before the last period. Otherwise, returns filename().
[ 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 ]
Returns: if filename() contains a period but does not consist solely of one or two periods, returns the substring of filename() starting at the rightmost period and for the remainder of the path. Otherwise, returns an empty path object.
Remarks: Implementations are permitted to define additional behavior for file systems which append additional elements to extensions, such as alternate data streams or partitioned dataset names.
[ Example:
std::cout << path("/foo/bar.txt").extension(); // outputs ".txt"
— end example ]
[ Note: The period is included in the return value so that it is possible to distinguish between no extension and an empty extension. Also note that for a path p, p.stem()+p.extension() == p.filename(). — end note ]
Returns: pathstring.empty().
Returns: !root_path().empty().
Returns: !root_name().empty().
bool has_root_directory() const;
Returns: !root_directory().empty().
bool has_relative_path() const;
Returns: !relative_path().empty().
Returns: !parent_path().empty().
Returns: !filename().empty().
Returns: !stem().empty().
Returns: !extension().empty().
Returns: true if pathstring contains an absolute path ([fs.def.absolute.path]), else false.
[ Example: path("/").is_absolute() is true for POSIX-based operating systems, and false for Windows-based operating systems. — end example ]
Returns: !is_absolute().
path lexically_normal() const;
Returns: *this in normal form ([fs.def.normal.form]).
[ Example:
assert(path("foo/./bar/..").lexically_normal() == "foo");
assert(path("foo/.///bar/../").lexically_normal() == "foo/.");
The above assertions will succeed. The second example ends with a current directory (dot) element appended to support operating systems that use different syntax for directory names and regular file names.
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;
Returns: *this made relative to base. Does not resolve ([fs.def.pathres]) symlinks. Does not first normalize ([fs.def.normal.form]) *this or base.
Effects: Determines the first mismatched element of *this and base as if by:
auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());
Then,
if a == begin() and b == base.begin(), returns path(); otherwise
if a == end() and b == base.end(), returns path("."); otherwise
returns an object of class path that is default-constructed, followed by
application of operator/=(path("..")) for each element in [b, base.end()), and then
application of operator/= for each element in [a, end()).
[ 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") == "");
The above assertions will succeed. On Windows, the returned path's directory-separator characters will be backslashes rather than forward slashes, but that does not affect path equality. — end example ]
[ Note: If symlink following semantics are desired, use the operational function relative(). — end note ]
[ Note: If normalization ([fs.def.normal.form]) 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;
Returns: If the value of lexically_relative(base) is not an empty path, return it. Otherwise return *this.
[ Note: If symlink following semantics are desired, use the operational function proximate(). — end note ]
[ Note: If normalization ([fs.def.normal.form]) is needed to ensure consistent matching of elements, apply lexically_normal() to *this, base, or both. — end note ]
Path iterators iterate over the elements of pathstring in the generic format ([path.generic]).
A path::iterator is a constant iterator satisfying all the requirements of a bidirectional iterator ([bidirectional.iterators]) 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.
Calling any non-const member function of a path object invalidates all iterators referring to elements of that object.
For the elements of pathstring in the generic format, the forward traversal order is as follows:
The root-name element, if present.
The root-directory element, if present. [ Note: the generic format is required to ensure lexicographical comparison works correctly. — end note ]
Each successive filename element, if present.
dot, if one or more trailing non-root slash characters are present.
Returns: An iterator for the first present element in the traversal list above. If no elements are present, the end iterator.
Returns: The end iterator.
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;
[ 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;
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.
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 ]