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

8
doc/src/index.dox
View File

@@ -41,13 +41,13 @@
\li \subpage string__op
\li \subpage num__parser
\li \subpage patch
<!--
\li \subpage encoding_helper
\li \subpage parser_helper
\li \subpage console_helper
-->
@@ -67,9 +67,9 @@
<B>Windows Specific Features</B>
<!--
\li \subpage win_import
\li \subpage windows__import_guard
<!--
\li \subpage com_helper
\li \subpage dialog_helper

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.
*/
}

20
doc/src/windows/win_import.dox → doc/src/windows/import_guard.dox
View File

@@ -1,25 +1,27 @@
namespace YYCC {
namespace yycc::windows {
/**
\page win_import Windows Import Guard
\page windows__import_guard Windows Import Guard
Windows is shitty for the programmer who is familiar with UNIX programming.
Due to legacy reason, Windows defines various things which are not compatible with UNIX or standard C++ programming.
\section win_import__usage Usage
\section windows__import_guard__usage Usage
YYCC has a way to solve the issue introduced above.
\code
#include <yycc/macro/os_detector.hpp>
#if defined(YYCC_OS_WINDOWS)
#include <WinImportPrefix.hpp>
#include <yycc/windows/import_guard_head.hpp>
#include <Windows.h>
#include "other_header_depend_on_windows.h"
#include <WinImportSuffix.hpp>
#include <yycc/windows/import_guard_tail.hpp>
#endif
\endcode
The including of WinImportPrefix.hpp and WinImportSuffix.hpp is a pair.
The including of import_guard_head.hpp and import_guard_tail.hpp is a pair.
They just like a guard bracket the include operation of Windows related headers,
to keep all Windows shitty contents will not be leaked outside.
@@ -30,7 +32,7 @@ This guard can solve following issues:
Programmer can not use \c std::max and \c std::min normally.
<UL>
<LI>Windows defines \c MAX and \c MIN as macros for personal use. This is why this happened.</LI>
<LI>Guard defines some special macros to tell Windows do not create these 2 macros.</LI>
<LI>This is actually resolved by CMake defined 2 public build macros which tell Windows do not create these 2 macros. But I simply conclude this feature in there.</LI>
</UL>
</LI>
<LI>
@@ -44,12 +46,12 @@ This guard can solve following issues:
Compiler throw annoy warnings and errors when using specific standard library functions.
<UL>
<LI>MSVC will throw warnings and errors when you are using Microsoft so-called \e depracted or \e unsafe standard library functions.</LI>
<LI>YYCCInternal.hpp, which has been included by this pair, defines some macros to purge these warnings and errors out.</LI>
<LI>This is also done by CMake public build macros.</LI>
</UL>
</LI>
</UL>
\section win_import__notes Notes
\section windows__import_guard__notes Notes
If you have other header files which are strongly depend on Windows header,
you should put them into this bracket at the same time like example did.