yyc12345/YYCCommonplace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: update documentation in code

Browse Source
This commit is contained in:
yyc12345 2024-07-24 15:03:31 +08:00
parent ecb06504bc
commit 87fa30fe82
6 changed files with 195 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
src/FsPathPatch.hpp
View File

@ -3,21 +3,26 @@
#include <filesystem>
/**
* @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);

9
src/IOHelper.hpp
View File

@ -4,6 +4,11 @@
#include <cstdio>
#include <filesystem>
/**
* @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);

54
src/ParserHelper.hpp
View File

@ -9,10 +9,24 @@
#include <charconv>
#include <array>
/**
* @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<typename _Ty, std::enable_if_t<std::is_floating_point_v<_Ty>, 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<typename _Ty, std::enable_if_t<std::is_integral_v<_Ty> && !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<typename _Ty, std::enable_if_t<std::is_same_v<_Ty, bool>, 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<typename _Ty, std::enable_if_t<std::is_arithmetic_v<_Ty>, 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<typename _Ty, std::enable_if_t<std::is_arithmetic_v<_Ty> && !std::is_same_v<_Ty, bool>, int> = 0>
yycc_u8string ToString(_Ty num) {
std::array<yycc_char8_t, 64> 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<typename _Ty, std::enable_if_t<std::is_same_v<_Ty, bool>, int> = 0>
yycc_u8string ToString(_Ty num) {
if (num) return yycc_u8string(YYCC_U8("true"));

2
src/StringHelper.cpp
View File

@ -170,7 +170,7 @@ namespace YYCC::StringHelper {
#pragma region Upper Lower
template<bool bIsToLower>
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

130
src/StringHelper.hpp
View File

@ -6,59 +6,141 @@
#include <functional>
#include <vector>
/**
* @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<bool(yycc_u8string_view&)>;
/**
* @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<yycc_u8string>& 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.
* @brief Split given string with specified decilmer.
* @param[in] strl The string need to be splitting.
* @param[in] _decilmer The decilmer for splitting.
* @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.
* 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<yycc_u8string> 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<yycc_u8string_view> SplitView(const yycc_u8string_view& strl, const yycc_char8_t* _decilmer);
}

29
src/WinFctHelper.hpp
View File

@ -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);