diff --git a/doc/src/fs_path_patch.dox b/doc/src/fs_path_patch.dox index c0ef102..ec8a9bb 100644 --- a/doc/src/fs_path_patch.dox +++ b/doc/src/fs_path_patch.dox @@ -2,4 +2,72 @@ \page fs_path_patch std::filesystem::path Patch +As you know, the underlying char type of \c std::filesystem::path is \c wchar_t on Windows, +and in other platforms, it is simple \c char. +Due to this, if you try to create a \c std::filesystem::path instance by calling constructor with an UTF8 char sequence on Windows, +the library implementation will assume your input is based on current Windows code page, not UTF8. +And the final path stored in \c std::filesystem::path is not what you expcected. + +This patch gives you a way to create \c std::filesystem::path +and extract path string stored in \c std::filesystem::path with UTF8 encoding. +This patch namespace always use UTF8 as its argument. +You should use the functions provided by this namespace on any platforms +instead of vanilla \c std::filesystem::path functions. +However, if your C++ standard is higher than C++ 20, +you can directly use UTF8 string pointer and string container in \c std::filesystem::path, +because standard library has supported them. +This patch only just want to provide an uniform programming experience. + +This patch is served for Windows but also works on other plaftoms. +If you are in Windows, this patch will perform extra operations to achieve goals, +and in other platforms, they just redirect request to corresponding vanilla C++ functions. + +\section fs_path_patch__from_utf8_path Create Path from UTF8 String + +YYCC::FsPathPatch::FromUTF8Path provides this feature. +It accepts an string pointer to UTF8 string and try to create \c std::filesystem::path from it. +Function will throw exception if encoding convertion or constructor self failed. +There are some example: + +\code +auto foobar_path = YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("/foo/bar")); +auto slashed_path = foobar_path / YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("test")); +auto replaced_ext = foobar_path.replace_extension(YYCC::FsPathPatch::FromUTF8Path(YYCC_U8(".txt"))); +\endcode + +For first line in example, it is obvious that you can create a \c std::filesystem::path from this function. +However, for the second and third line in example, what we want to tell you is +that you should always use this function in other \c std::filesystem::path functions requiring path string. + +\c std::filesystem::path is a very \e conservative class. +Most of its functions only accept \c std::filesystem::path self as argument. +For example, \c std::filesystem::path::replace_extension do not accept string as argument. +It accepts a reference to \c std::filesystem::path as argument. +(it still is possible that pass string pointer or string container to it because they can be converted to \c std::filesystem::path implicitly.) +It's great. This is what we expected! +We now can safely deliver the result generated by our function to these functions, +and don't need to worry about the encoding of we provided string. +Because all strings have been converted to \c std::filesystem::path by our function before passing them. + +So, the second line will produce \c "/foo/bar/test" +and the third line will produce \c "/foo/bar.txt" in any platforms. + +You may notice std::filesystem::u8path. +However it is depracted since C++ 20, +because \c std::filesystem::path directly supports UTF8 by \c char8_t since C++ 20. +Because C++ standard is volatile, we create this function to have an uniform programming experience. + +\section fs_path_patch__to_utf8_path Extract UTF8 Path String from Path + +YYCC::FsPathPatch::ToUTF8Path provides this feature. +It basically is the reversed operation of YYCC::FsPathPatch::FromUTF8Path. +It is usually used when you have done all path work in \c std::filesystem::path +and want to get the result. +There is an example: + +\code +auto foobar_path = YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("/foo/bar")); +auto result = YYCC::FsPathPatch::ToUTF8Path(foobar_path / YYCC::FsPathPatch::FromUTF8Path(YYCC_U8("test"))); +\endcode + */