From 87fa30fe820a1798a8f772daf03f89ec0f0a8cf7 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Wed, 24 Jul 2024 15:03:31 +0800 Subject: [PATCH] doc: update documentation in code --- src/FsPathPatch.hpp | 19 ++++--- src/IOHelper.hpp | 9 ++- src/ParserHelper.hpp | 54 ++++++++++++++++++ src/StringHelper.cpp | 2 +- src/StringHelper.hpp | 132 +++++++++++++++++++++++++++++++++++-------- src/WinFctHelper.hpp | 29 +++++----- 6 files changed, 195 insertions(+), 50 deletions(-) diff --git a/src/FsPathPatch.hpp b/src/FsPathPatch.hpp index 3299b48..77e2b2e 100644 --- a/src/FsPathPatch.hpp +++ b/src/FsPathPatch.hpp @@ -3,21 +3,26 @@ #include +/** + * @brief \c std::filesystem::path related patches for UTF8 compatibility + * @details + * See also \ref fs_path_patch. +*/ namespace YYCC::FsPathPatch { /** - * @brief Constructs the path from a UTF8 character sequence - * @param[in] u8_path UTF8 path string for building this std::filesystem::path. - * @return std::filesystem::path instance. + * @brief Constructs \c std::filesystem::path from UTF8 path. + * @param[in] u8_path UTF8 path string for building. + * @return \c std::filesystem::path instance. * @exception std::invalid_argument Fail to parse given UTF8 string (maybe invalid?). */ std::filesystem::path FromUTF8Path(const yycc_char8_t* u8_path); /** - * @brief Returns the UTF8 representation of the pathname - * @param path[in] The string to be output. - * @return UTF8 encoded string representing given path. - * @exception std::invalid_argument Fail to parse to UTF8 string. + * @brief Returns the UTF8 representation of given \c std::filesystem::path. + * @param[in] path The \c std::filesystem::path instance converting to UTF8 path. + * @return The UTF8 representation of given \c std::filesystem::path. + * @exception std::invalid_argument Fail to convert to UTF8 string. */ yycc_u8string ToUTF8Path(const std::filesystem::path& path); diff --git a/src/IOHelper.hpp b/src/IOHelper.hpp index d56925e..a6ef75e 100644 --- a/src/IOHelper.hpp +++ b/src/IOHelper.hpp @@ -4,6 +4,11 @@ #include #include +/** + * @brief Some IO related stuff + * @details + * See also \ref io_helper. +*/ namespace YYCC::IOHelper { #if UINTPTR_MAX == UINT32_MAX @@ -24,13 +29,13 @@ namespace YYCC::IOHelper { #endif /** - * @brief The UTF8 version of std::fopen. + * @brief The UTF8 version of \c std::fopen. * @param[in] u8_filepath The UTF8 encoded path to the file to be opened. * @param[in] u8_mode UTF8 encoded mode string of the file to be opened. * @remarks * This function is suit for Windows because std::fopen do not support UTF8 on Windows. * On other platforms, this function will delegate request directly to std::fopen. - * @return FILE* of the file to be opened, or nullptr if failed. + * @return \c FILE* of the file to be opened, or nullptr if failed. */ FILE* UTF8FOpen(const yycc_char8_t* u8_filepath, const yycc_char8_t* u8_mode); diff --git a/src/ParserHelper.hpp b/src/ParserHelper.hpp index 4e3b437..3054c72 100644 --- a/src/ParserHelper.hpp +++ b/src/ParserHelper.hpp @@ -9,10 +9,24 @@ #include #include +/** + * @brief The helper involving convertion between arithmetic types (integral, floating point and bool) and string + * @details + * See also \ref parser_helper. +*/ namespace YYCC::ParserHelper { // Reference: https://zh.cppreference.com/w/cpp/utility/from_chars + /** + * @brief Try parsing given string to floating point types. + * @tparam _Ty The type derived from floating point type. + * @param[in] strl The string need to be parsed. + * @param[out] num + * The variable receiving result. + * There is no guarantee that the content is not modified when parsing failed. + * @return True if success, otherwise false. + */ template, int> = 0> bool TryParse(const yycc_u8string_view& strl, _Ty& num) { auto [ptr, ec] = std::from_chars( @@ -34,6 +48,16 @@ namespace YYCC::ParserHelper { throw std::runtime_error("unreachable code."); } } + /** + * @brief Try parsing given string to integral types. + * @tparam _Ty The type derived from integral type. + * @param[in] strl The string need to be parsed. + * @param[out] num + * The variable receiving result. + * There is no guarantee that the content is not modified when parsing failed. + * @param[in] base integer base to use: a value between 2 and 36 (inclusive). + * @return True if success, otherwise false. + */ template && !std::is_same_v<_Ty, bool>, int> = 0> bool TryParse(const yycc_u8string_view& strl, _Ty& num, int base = 10) { auto [ptr, ec] = std::from_chars( @@ -55,6 +79,15 @@ namespace YYCC::ParserHelper { throw std::runtime_error("unreachable code."); } } + /** + * @brief Try parsing given string to bool types. + * @tparam _Ty The type derived from bool type. + * @param[in] strl The string need to be parsed ("true" or "false"). + * @param[out] num + * The variable receiving result. + * There is no guarantee that the content is not modified when parsing failed. + * @return True if success, otherwise false. + */ template, int> = 0> bool TryParse(const yycc_u8string_view& strl, _Ty& num) { if (strl == YYCC_U8("true")) num = true; @@ -63,6 +96,15 @@ namespace YYCC::ParserHelper { return true; } + /** + * @brief Parse given string to arithmetic types. + * @tparam _Ty The type derived from arithmetic type. + * @param[in] strl The string need to be parsed. + * @return + * The parsing result. + * There is no guarantee about the content of this return value when parsing failed. + * It may be any possible value but usually is its default value. + */ template, int> = 0> _Ty Parse(const yycc_u8string_view& strl) { _Ty ret; @@ -72,6 +114,12 @@ namespace YYCC::ParserHelper { // Reference: https://en.cppreference.com/w/cpp/utility/to_chars + /** + * @brief Return a string version of given arithmetic value. + * @tparam _Ty The type derived from arithmetic type. + * @param[in] num The value getting string version. + * @return The string version of given value. + */ template && !std::is_same_v<_Ty, bool>, int> = 0> yycc_u8string ToString(_Ty num) { std::array buffer; @@ -91,6 +139,12 @@ namespace YYCC::ParserHelper { throw std::runtime_error("unreachable code."); } } + /** + * @brief Return a string version of given bool value. + * @tparam _Ty The type derived from bool type. + * @param[in] num The value getting string version. + * @return The string version of given value ("true" or "false"). + */ template, int> = 0> yycc_u8string ToString(_Ty num) { if (num) return yycc_u8string(YYCC_U8("true")); diff --git a/src/StringHelper.cpp b/src/StringHelper.cpp index 6a8fe88..82d2b26 100644 --- a/src/StringHelper.cpp +++ b/src/StringHelper.cpp @@ -170,7 +170,7 @@ namespace YYCC::StringHelper { #pragma region Upper Lower template - void GeneralStringLowerUpper(yycc_u8string& strl) { + static void GeneralStringLowerUpper(yycc_u8string& strl) { // References: // https://en.cppreference.com/w/cpp/algorithm/transform // https://en.cppreference.com/w/cpp/string/byte/tolower diff --git a/src/StringHelper.hpp b/src/StringHelper.hpp index 5be70cc..f5bf314 100644 --- a/src/StringHelper.hpp +++ b/src/StringHelper.hpp @@ -6,59 +6,141 @@ #include #include +/** + * @brief The helper containing string operations + * @details + * See also \ref string_helper. +*/ namespace YYCC::StringHelper { + /** + * @brief Perform a string formatting operation. + * @param[out] strl + * The string container receiving the result. + * There is no guarantee that the content is not modified when function failed. + * @param[in] format The format string. + * @param[in] ... Argument list of format string. + * @return True if success, otherwise false. + */ bool Printf(yycc_u8string& strl, const yycc_char8_t* format, ...); + /** + * @brief Perform a string formatting operation. + * @param[out] strl + * The string container receiving the result. + * There is no guarantee that the content is not modified when function failed. + * @param[in] format The format string. + * @param[in] argptr Argument list of format string. + * @return True if success, otherwise false. + */ bool VPrintf(yycc_u8string& strl, const yycc_char8_t* format, va_list argptr); + /** + * @brief Perform a string formatting operation. + * @param[in] format The format string. + * @param[in] ... Argument list of format string. + * @return The formatting result. Empty string if error happened. + */ yycc_u8string Printf(const yycc_char8_t* format, ...); + /** + * @brief Perform a string formatting operation. + * @param[in] format The format string. + * @param[in] argptr Argument list of format string. + * @return The formatting result. Empty string if error happened. + */ yycc_u8string VPrintf(const yycc_char8_t* format, va_list argptr); + /** + * @brief Modify given string with all occurrences of substring \e old replaced by \e new. + * @param[in,out] strl The string for replacing + * @param[in] _from_strl The \e old string. + * @param[in] _to_strl The \e new string. + */ void Replace(yycc_u8string& strl, const yycc_char8_t* _from_strl, const yycc_char8_t* _to_strl); + /** + * @brief Return a copy with all occurrences of substring \e old replaced by \e new. + * @param[in] _strl The string for replacing + * @param[in] _from_strl The \e old string. + * @param[in] _to_strl The \e new string. + * @return The result of replacement. + */ yycc_u8string Replace(const yycc_char8_t* _strl, const yycc_char8_t* _from_strl, const yycc_char8_t* _to_strl); /** - * @brief The data provider of general Join function. - * For the implementation of this function: - * Function return true to continue join. otherwise return false to terminate join. - * The argument assigned in the calling returning false is not included. - * During calling, implementation should assign the string view to the string need to be joined in given argument. + * @brief The data provider of general join function. + * @details + * For programmer using lambda to implement this function pointer: + * \li During calling, implementation should assign the reference of string view passed in argument + * to the string which need to be joined. + * \li Function return true to continue joining. otherwise return false to stop joining. + * The argument content assigned in the calling returning false is not included in join process. */ using JoinDataProvider = std::function; /** - * @brief General Join function. - * @details This function use function pointer as a general data provider interface, - * so this function suit for all types container, the user only need write a little bit adaption code. - * @param fct_data[in] The function pointer to data provider. - * @param decilmer[in] The decilmer. - * @return A std::string instance which containing the join result. + * @brief Universal join function. + * @details + * This function use function pointer as a general data provider interface, + * so this function suit for all types container. + * You can use this universal join function for any custom container by + * using C++ lambda syntax to create a code block adapted to this function pointer. + * @param[in] fct_data The function pointer in JoinDataProvider type prividing the data to be joined. + * @param[in] decilmer The decilmer used for joining. + * @return The result string of joining. */ yycc_u8string Join(JoinDataProvider fct_data, const yycc_char8_t* decilmer); /** - * @brief Specialized Join function for common used container. - * @param data - * @param decilmer - * @param reversed - * @return + * @brief Specialized join function for \c std::vector. + * @param[in] data The list to be joined. + * @param[in] decilmer The decilmer used for joining. + * @param[in] reversed True if this list should be joined in reversed order. + * @return The result string of joining. */ yycc_u8string Join(const std::vector& data, const yycc_char8_t* decilmer, bool reversed = false); + /** + * @brief Return a copy of the string converted to lowercase. + * @param[in] strl The string to be lowercase. + * @return The copy of the string converted to lowercase. + */ yycc_u8string Lower(const yycc_char8_t* strl); + /** + * @brief Convert given string to lowercase. + * @param[in,out] strl The string to be lowercase. + */ void Lower(yycc_u8string& strl); + /** + * @brief Return a copy of the string converted to uppercase. + * @param[in] strl The string to be uppercase. + * @return The copy of the string converted to uppercase. + */ yycc_u8string Upper(const yycc_char8_t* strl); + /** + * @brief Convert given string to uppercase. + * @param[in,out] strl The string to be uppercase. + */ void Upper(yycc_u8string& strl); /** - * @brief General Split function. - * @param strl[in] The string need to be splitting. - * If this is nullptr, the result will be empty. - * @param _decilmer[in] The decilmer for splitting. - * If decilmer is nullptr or zero length, the result will only have 1 element which is original string. - * @return - * @remarks This function may be low performance because it just a homebrew Split functon. - * It can works in most toy cases but not suit for high performance scenario. - * Also, this function will produce a copy of original string because it is not zero copy. + * @brief Split given string with specified decilmer. + * @param[in] strl The string need to be splitting. + * @param[in] _decilmer The decilmer for splitting. + * @return + * The split result. + * \par + * If given string is empty, or decilmer is nullptr or empty, + * the result container will only contain 1 entry which is equal to given string. */ std::vector Split(const yycc_u8string_view& strl, const yycc_char8_t* _decilmer); + /** + * @brief Split given string with specified decilmer as string view. + * @param[in] strl The string need to be splitting. + * @param[in] _decilmer The decilmer for splitting. + * @return + * The split result with string view format. + * This will not produce any copy of original string. + * \par + * If given string is empty, or decilmer is nullptr or empty, + * the result container will only contain 1 entry which is equal to given string. + * @see Split(const yycc_u8string_view&, const yycc_char8_t*) + */ std::vector SplitView(const yycc_u8string_view& strl, const yycc_char8_t* _decilmer); } diff --git a/src/WinFctHelper.hpp b/src/WinFctHelper.hpp index a66f430..50a5ffd 100644 --- a/src/WinFctHelper.hpp +++ b/src/WinFctHelper.hpp @@ -9,10 +9,11 @@ #include "WinImportSuffix.hpp" /** - * @brief The helper providing assistance to Win32 functions. + * @brief The helper providing assistance of Win32 functions. * @details * This helper is Windows specific. * If current environment is not Windows, the whole namespace will be unavailable. + * See also \ref win_fct_helper */ namespace YYCC::WinFctHelper { @@ -24,16 +25,16 @@ namespace YYCC::WinFctHelper { * * This function is frequently used by DLL. * Because some design need the HANDLE of current module, not the host EXE loading your DLL. - * For example, you may want to get the name of your built DLL at runtime, then you should pass current module HANDLE, not the HANDLE of EXE. - * Or, if you want to get the path to your DLL, you also should pass current module HANDLE. + * For example, you may want to get the path of your built DLL, or fetch resources from your DLL at runtime, + * then you should pass current module HANDLE, not NULL or the HANDLE of EXE. * @return A Windows HANDLE pointing to current module, NULL if failed. */ HMODULE GetCurrentModule(); /** - * @brief Get path to Windows temp folder. - * @param[out] ret - * The variable receiving UTF8 encoded path to Windows temp folder. + * @brief Get path to Windows temporary folder. + * @details Windows temporary folder usually is the target of \%TEMP\%. + * @param[out] ret The variable receiving UTF8 encoded path to Windows temp folder. * @return True if success, otherwise false. */ bool GetTempDirectory(yycc_u8string& ret); @@ -41,20 +42,18 @@ namespace YYCC::WinFctHelper { /** * @brief Get the file name of given module HANDLE * @param[in] hModule - * The HANDLE to the module where we want get file name. - * It is same as the HANDLE parameter of \c GetModuleFileName. - * @param[out] ret - * The variable receiving UTF8 encoded file name of given module. + * The HANDLE to the module where you want to get file name. + * It is same as the HANDLE parameter of Win32 \c GetModuleFileName. + * @param[out] ret The variable receiving UTF8 encoded file name of given module. * @return True if success, otherwise false. */ bool GetModuleFileName(HINSTANCE hModule, yycc_u8string& ret); /** - * @brief Get the path to LOCALAPPDATA. - * @details LOCALAPPDATA usually was used as putting local app data files - * @param[out] ret - * The variable receiving UTF8 encoded path to LOCALAPPDATA. - * @return + * @brief Get the path to \%LOCALAPPDATA\%. + * @details \%LOCALAPPDATA\% usually was used as putting local app data files + * @param[out] ret The variable receiving UTF8 encoded path to LOCALAPPDATA. + * @return True if success, otherwise false. */ bool GetLocalAppData(yycc_u8string& ret);