yyc12345/YYCCommonplace
1
0
Fork 0
Code Issues Pull Requests Releases Activity

doc: start to refactor doc

Browse Source
This commit is contained in:
yyc12345
2025-08-14 21:33:17 +08:00
parent 734cd01da8
commit 00c8f09907
6 changed files with 99 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/index.dox
View File

@ -29,6 +29,9 @@
\li \subpage intro
\li \subpage premise_and_principle
<!--
\li \subpage library_macros
\li \subpage library_encoding
@ -46,20 +49,24 @@
\li \subpage std_patch
\li \subpage enum_helper
-->
<B>Advanced Features</B>
<!--
\li \subpage constraints
\li \subpage config_manager
\li \subpage arg_parser
-->
</TD>
<TD ALIGN="LEFT" VALIGN="TOP">
<B>Windows Specific Features</B>
<!--
\li \subpage win_import
\li \subpage com_helper
@ -69,6 +76,7 @@
\li \subpage win_fct_helper
\li \subpage exception_helper
-->
</TD>
</TR>

24
doc/src/intro.dox
View File

@ -6,7 +6,7 @@ YYCCommonplace, or YYC Commonplace (abbr. YYCC),
is a static library providing various useful C++ functions
when programming with standard library or Windows environment.
During the development of a few projects,
At the beginning, during the development of a few projects,
I gradually understand how Windows make the compromise with the code written by its old developers,
and what is developer wanted in contemporary C++ standard library under Windows environment.
So I create this static library for all of my C++ project.
@ -15,6 +15,16 @@ I can use a clear and easy way to manage these codes.
I can easily fix issues found in project using this library by updating a single project,
rather than fixing these duplicated code in each project one by one
because all of them share the same implementations.
This is the origin of the 1.x version of YYCC.
After a few years ago, I start to write in Rust and more complicated codes.
I was allured by Rust and hope all these feature Rust holded can be adapted into C++,
so I start to refactor this library in modern way.
However, the compatibility with low C++ standard version is now become the shortcoming of this library.
I was forced to considering the compatibility with C++ 17 and it cause a huge work.
So, after think twice, I decide to drop the support of C++ 17, which the higest C++ standard I can used for Virtools project.
And increase the standard to C++ 23 directly to have better experience.
That's the origin of the 2.x version of YYCC.
This project mainly is served for my personal use.
But I would be honored if you would like to use this in your project.
@ -46,17 +56,18 @@ Thus I can have a similar Linux C++ programming experience on Windows.
The eccentric decision of standard commission also is the reason why I create this library.
\li C++ standard commission loves to bring one feature with N concepts and P assistant classes.
\li C++ standard commission prefer to provide one function with very fundamental classes and functions
and programmer need to write too much code to achieve a simple work.
\li C++ standard commission seems doesn't want to bring any features the programmer urgent needed.
\li C++ standard commission loves delete programmer loved convenient functions and classes.
\li etc...
There is not a proper way to \e format a string in C++ until C++ 20 (\c std::format).
String related functions, such as split, lower, higher, replace, now still not be included in standard library.
Programmer loved, easy to used UTF8 procession functions and classes was deprecate now and will be removed in future.
Programmer loved, easy to used encoding convertion functions and classes are deprecate now and will be removed in future.
That's why I create this library.
I bring these function in this library.
I bring these functions in this library.
Not industrial level, but easy to use and have enough performance in my project.
\subsection intro__why__boost Boost Issues
@ -65,7 +76,7 @@ Bosst is a powerful C++ library. But the shortcoming is overt. It's tooooo big.
This drawback will be more obvious considering the bad dependency mechanism of C++.
Although the most of Boost sub-library is header-only, but some library still need to link with Boost.
It order you download the whole Boost library and extract it in your hard disk.
Cost more than half hours, 5+ GB disk space and the life time of your disk.
Cost more than half hour of your life, 5+ GB disk space and the life time of your disk.
The functions belonging to Boost is industrial level.
But what I want is not industrial level functions.
@ -74,6 +85,7 @@ I don't need extreme performance. I just want my code works.
So I create this library, bring some Boost functions with ordinary but not bad implementation.
<!--
\section intro__usage Library Usage
Before using this library, I suggest you read this manual fully to have a full overview of this library.
@ -187,5 +199,5 @@ YYCC CMake build script contains a special option called \c YYCC_DEBUG_UE_FILTER
If you set it to true, it will add a public macro \c YYCC_DEBUG_UE_FILTER to YYCC project.
This macro will enable special code path for the convenience of debugging \ref exception_helper related features.
So in common use, user should not enable this option.
-->
*/

38
doc/src/premise_and_principle.dox Normal file
View File

@ -0,0 +1,38 @@
/**
\page premise_and_principle Premise and Principle
When programming with this library, there is some premise and principle you should noticed.
\section premise_and_principle__exception_is_error Exception is Error
The most crucial spot of this library is <B>"Exception is Error"</B>.
When some functions throw exception, it should cause program paniked, rather than recover from it.
This is inspired from Rust, and also the compromise with STL.
Most functions this library provided has Rust-Result-like return value.
It means that programmer can handle error correctly.
However, this library is based on STL, another library that may throw C++ exception to indicate error.
We can not control this behavior of STL, so I forcely apply this rule.
\section premise_and_principle__os_encoding OS Encoding
This library has special treat with Windows to make it works on Windows.
However, for other operating system, it do not have too much care.
We brutally make a premise that other operating systems are UNIX-liked and use UTF8 as its encoding.
\section premise_and_principle__string_encoding String Encoding
Before using this library, you should know the encoding strategy of this library first.
In short words, this library use UTF8 encoding everywhere except some special cases list following (not all).
\li Traditional format function in yycc::string::op.
Traditional format function provide some overloads for ordinary string formatting.
That's because this feature is so common to use in some cases.
\li The message of Rust panic in yycc::rust::panic.
Due to the limitation of \c std::format, we only can use ordinary string as its message content.
\li The message of standard library exception.
For the compatibility with C++ standard library exception,
we only can use ordinary string as the message of exception.
*/

9
src/yycc/num/parse.hpp
View File

@ -31,8 +31,7 @@ namespace yycc::num::parse {
using ParseResult = std::expected<T, ParseError>;
/**
* @private
* @brief Internal parsing function for floating point types
* @brief Parse given string into floating point types
* @tparam T Floating point type (float, double, etc)
* @param strl The UTF-8 string view to parse
* @param fmt The floating point format to use
@ -66,8 +65,7 @@ namespace yycc::num::parse {
}
/**
* @private
* @brief Internal parsing function for integral types (except bool)
* @brief Parse given string into integral types (except bool)
* @tparam T Integral type (int, long, etc)
* @param strl The UTF-8 string view to parse
* @param base Numeric base (2-36)
@ -101,8 +99,7 @@ namespace yycc::num::parse {
}
/**
* @private
* @brief Internal parsing function for boolean type
* @brief Parse given string into boolean type
* @tparam T Must be bool type
* @param strl The UTF-8 string view to parse ("true" or "false", case insensitive)
* @return ParseResult<bool> containing either the parsed value or a ParseError

31
src/yycc/num/safe_op.hpp
View File

@ -491,12 +491,19 @@ namespace yycc::num::safe_op {
* @brief The result returned by the overflow function family.
* @details
* The first item is the operation result.
* The second item indicates whether an overflow has occurred. true means overflow, otherwise false.
* The second item indicating whether an overflow has occurred. True means overflow, otherwise false.
*/
template<typename T>
requires std::integral<T>
using OverflowingPair = std::pair<T, bool>;
/**
* @brief Performs an addition operation with overflow detection.
* @tparam T Integer type.
* @param[in] a The left operand of the addition.
* @param[in] b The right operand of the addition.
* @return A pair holding result and overflow flag.
*/
template<typename T>
requires std::integral<T>
OverflowingPair<T> overflowing_add(T a, T b) {
@ -505,6 +512,13 @@ namespace yycc::num::safe_op {
return std::make_pair(result, overflow);
}
/**
* @brief Performs a subtraction operation with overflow detection.
* @tparam T Integer type.
* @param[in] a The left operand of the subtraction.
* @param[in] b The right operand of the subtraction.
* @return A pair holding result and overflow flag.
*/
template<typename T>
requires std::integral<T>
OverflowingPair<T> overflowing_sub(T a, T b) {
@ -513,6 +527,13 @@ namespace yycc::num::safe_op {
return std::make_pair(result, overflow);
}
/**
* @brief Performs a multiplication operation with overflow detection.
* @tparam T Integer type.
* @param[in] a The left operand of the multiplication.
* @param[in] b The right operand of the multiplication.
* @return A pair holding result and overflow flag.
*/
template<typename T>
requires std::integral<T>
OverflowingPair<T> overflowing_mul(T a, T b) {
@ -521,6 +542,14 @@ namespace yycc::num::safe_op {
return std::make_pair(result, overflow);
}
/**
* @brief Performs a division operation with overflow detection.
* @tparam T Integer type.
* @param[in] a The left operand of the division.
* @param[in] b The right operand of the division.
* @return A pair holding result and overflow flag.
* @exception std::logic_error If division by zero occurs.
*/
template<typename T>
requires std::integral<T>
OverflowingPair<T> overflowing_div(T a, T b) {

2
src/yycc/num/stringify.hpp
View File

@ -55,6 +55,7 @@ namespace yycc::num::stringify {
throw std::runtime_error("unreachable code.");
}
}
/**
* @brief Return the string representation of given integral value.
* @tparam T The type derived from integral type except bool type.
@ -82,6 +83,7 @@ namespace yycc::num::stringify {
throw std::runtime_error("unreachable code.");
}
}
/**
* @brief Return the string representation of given bool value.
* @tparam T The type derived from bool type.