Init

cppdraft/depr/fs/path/factory.md

@@ -0,0 +1,111 @@
+[depr.fs.path.factory]
+
+# Annex D (normative) Compatibility features [[depr]](./#depr)
+
+## D.22 Deprecated file systems [[depr.filesystems]](depr.filesystems#depr.fs.path.factory)
+
+### D.22.1 Deprecated filesystem path factory functions [depr.fs.path.factory]
+
+[1](#1)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/future.tex#L793)
+
+The header [<filesystem>](fs.filesystem.syn#header:%3cfilesystem%3e "31.12.4 Header <filesystem> synopsis [fs.filesystem.syn]") has the following additions:
+
+[🔗](#lib:u8path)
+
+`template<class Source>
+  path u8path(const Source& source);
+template<class InputIterator>
+  path u8path(InputIterator first, InputIterator last);
+`
+
+[2](#2)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/future.tex#L804)
+
+*Mandates*: The value type of Source and InputIterator ischar or char8_t[.](#2.sentence-1)
+
+[3](#3)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/future.tex#L809)
+
+*Preconditions*: The source and [first, last) sequences are UTF-8 encoded[.](#3.sentence-1)
+
+Source meets the requirements specified in [[fs.path.req]](fs.path.req "31.12.6.4 Requirements")[.](#3.sentence-2)
+
+[4](#4)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/future.tex#L814)
+
+*Returns*: 
+
+- [(4.1)](#4.1)
+
+If path​::​value_type is char and the current native
+ narrow encoding ([[fs.path.type.cvt]](fs.path.type.cvt "31.12.6.3.2 Type and encoding conversions")) is UTF-8,
+ return path(source) or path(first, last);
+ otherwise,
+
+- [(4.2)](#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)](#4.3)
+
+convert source or [first, last)
+ to a temporary, tmp, of type u32string and
+ return path(tmp)[.](#4.sentence-1)
+
+[5](#5)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/future.tex#L833)
+
+*Remarks*: Argument format conversion ([[fs.path.fmt.cvt]](fs.path.fmt.cvt "31.12.6.3.1 Argument format conversions")) applies to the
+ arguments for these functions[.](#5.sentence-1)
+
+How Unicode encoding conversions are performed is
+ unspecified[.](#5.sentence-2)
+
+[6](#6)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/future.tex#L839)
+
+[*Example [1](#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[.](#6.sentence-2)
+
+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[.](#6.sentence-3)
+
+Some Unicode characters may have no native character
+ set representation[.](#6.sentence-4)
+
+For Windows-based operating systems a conversion from UTF-8 to
+ UTF-16 occurs[.](#6.sentence-5)
+
+— *end example*]
+
+[*Note [1](#note-1)*:
+
+The example above is representative of
+a historical use of filesystem​::​u8path[.](#6.sentence-6)
+
+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[.](#6.sentence-7)
+
+— *end note*]