yyc12345/YYCCommonplace
1
0
Fork 0
Code Activity

doc: write doc for parse&stringify and windows import guard

Browse Source
This commit is contained in:
yyc12345
2025-12-30 16:15:34 +08:00
parent e929ba3776
commit c708e1e672
4 changed files with 85 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
doc/src/num/parser.dox Normal file
View File

@@ -0,0 +1,70 @@
namespace yycc::num::parse {
/**
\page num__parser Numeric Parser
Namespace yycc::num::parse is served for the convertion from string to number.
\section num__parser__supported_types Supported Types
Functions located in this namespace support the convertion from string to following types:
\li Integral types (except \c bool): \c int, \c uint32_t, \c char and etc.
\li Floating point types: \c float, \c double and etc.
\li \c bool
Please note in C++, \c bool is integral type but we list it individually because parser will treat it specially.
For \c bool type, parser will try doing convertion between it and \c "true" \c "false" string.
(\b case-insensitive. It means that \c "true", \c "True" and \c "TRUE", all of them can be converted into \c true.)
\section num__parser__usage Usage
This namespace provide a uniform parser function #parse with various overloads.
All of them accept an UTF8 string view at first argument,
and following argument is different required by different overloads which may change parser behavior.
For example, for floating point type, this function allows caller to specify extra argument providing the format of given number string (\c std::chars_format).
or for integral type, this function allows caller to specify extra argument providing the base of given number string.
The return value is a result type, containing converted value or error occurs.
There are some examples:
\code
auto rv = parse::parse<uint32_t>(u8"123");
assert(rv.has_value());
auto converted = rv.value();
\endcode
\section num__parser__stringify Stringify
Namespace yycc::num::stringify provide the opposite function of namespace yycc::num::parse.
They convert given number into their string representation.
There is an example:
\code
auto showcase = stringify::stringify<uint32_t>(UINT32_C(114));
\endcode
Same as parse::parse, stringify::stringify also has same overloads and different second arguments.
For floating point type, this function allows caller to specify extra arguments
which provides the format (\c std::chars_format) and precision when getting string representation.
For integral type, this function allows caller to specify extra argument
providing the base of number when getting string representation.
However, the result value of stringify::stringify is just the result, not a result type.
Because it is mostly impossible to occur error in stringify::stringify.
\section num__parser__notes Notes
All functions located in yycc::num::parse and yycc::num::stringify namespace are implementated by standard library functions.
These functions just make a good wrapper for complex standard library functions.
And give you a experience like Rust \c parse functions.
Basically, all functions located in this helper have possibility to throw exception.
But this possibility are more close to the possibility that \c new statement throw \c std::bad_alloc.
So in most cases you can assume these functions will not throw any exception.
All functions are template functions.
The argument of template is the type these functions need to be processed.
Although C++ have \e smart template type deduction,
it would be better to specify template argument manually to explicitly specify your desired type.
*/
}

88
doc/src/num/parser_helper.dox
View File

@@ -1,88 +0,0 @@
namespace YYCC::ParserHelper {
/**
\page parser_helper Parser Helper
This helper is served for the convertion between number and string.
\section parser_helper_supported_types Supported Types
Functions located in this helper support the convertion between string and following types:
\li Integral types (except \c bool): \c int, \c uint32_t, \c char and etc.
\li Floating point types: \c float, \c double and etc.
\li \c bool
Please note in C++, \c bool is integral type but we list it individually because parser will treat it specially.
For \c bool type, parser will try doing convertion between it and \c "true" \c "false" string.
(\b case-insensitive. It means that \c true can be converted from \c "true", \c "True" or \c "TRUE".)
\section parser_helper__try_parse Try Parse
#TryParse will try to parse string into caller specified type.
All of them accept an UTF8 string view at first argument,
require that you provide a container receiving converted result in the second argument,
and return a bool value to indicate whether the convertion is successful.
There are some examples:
\code
uint32_t val;
YYCC::ParserHelper::TryParse<uint32_t>(YYCC_U8("123"), val);
YYCC::ParserHelper::TryParse<uint32_t>(YYCC_U8("7fff"), val, 16);
\endcode
For floating point type, this function allows caller to specify extra argument providing the format of given number string (\c std::chars_format).
For integral type, this function allows caller to specify extra argument providing the base of given number string.
\section parser_helper__parse Parse
#Parse is similar to #TryParse.
But it will not return bool value to indicate success and doesn't have the argument receiving result.
It only accepts an UTF8 string view as the only one argument, and return result directly.
If the convertion failed, the return value is \b undefined (but usually is the default value of given type).
There is an example:
\code
uint32_t val = YYCC::ParserHelper::Parse<uint32_t>(YYCC_U8("123"));
\endcode
For integral and floating point value,
it has same extra argument with #TryParse to provide more number infomation.
Using this function is dangerous if the validation of your input is important.
In this case, please use #TryParse instead.
\section parser_helper__to_string To String
#ToString basically is the reversed operation of #Parse.
It gets the string representation of given type.
The only argument of these functions is the type which need to be converted to its string representation.
And they will return yycc_u8string as result.
There is an example:
\code
auto result = YYCC::ParserHelper::ToString<uint32_t>(UINT32_C(114));
\endcode
For floating point type, this function allows caller to specify extra arguments
which provides the format (\c std::chars_format) and precision when getting string representation.
For integral type, this function allows caller to specify extra argument
providing the base of number when getting string representation.
\section parser_helper__notes Notes
All functions within this helper are implementated by standard library functions.
These functions just make a good wrapper for complex standard library functions.
And give you a experience like C\# parser functions.
Basically, all functions located in this helper have possibility to throw exception.
But this possibility are more close to the possibility that \c new statement throw \c std::bad_alloc.
So in most cases you can assume these functions will not throw any exception.
All functions are template functions.
The argument of template is the type these functions need to be processed.
Although C++ have \e smart template type deduction,
it would be better to specify template argument manually to explicitly specify your desired type.
*/
}