diff --git a/doc/src/index.dox b/doc/src/index.dox
index 2449c97..87511d5 100644
--- a/doc/src/index.dox
+++ b/doc/src/index.dox
@@ -29,6 +29,9 @@
\li \subpage intro
+ \li \subpage premise_and_principle
+
+
Advanced Features
+
Windows Specific Features
+
|
diff --git a/doc/src/intro.dox b/doc/src/intro.dox
index e915fd2..d5f99de 100644
--- a/doc/src/intro.dox
+++ b/doc/src/intro.dox
@@ -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.
+
*/
diff --git a/doc/src/premise_and_principle.dox b/doc/src/premise_and_principle.dox
new file mode 100644
index 0000000..fea3959
--- /dev/null
+++ b/doc/src/premise_and_principle.dox
@@ -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 "Exception is Error".
+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.
+
+*/
diff --git a/src/yycc/num/parse.hpp b/src/yycc/num/parse.hpp
index 795f91d..de71757 100644
--- a/src/yycc/num/parse.hpp
+++ b/src/yycc/num/parse.hpp
@@ -31,8 +31,7 @@ namespace yycc::num::parse {
using ParseResult = std::expected;
/**
- * @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 containing either the parsed value or a ParseError
diff --git a/src/yycc/num/safe_op.hpp b/src/yycc/num/safe_op.hpp
index 169bd0c..9ce687f 100644
--- a/src/yycc/num/safe_op.hpp
+++ b/src/yycc/num/safe_op.hpp
@@ -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
requires std::integral
using OverflowingPair = std::pair;
+ /**
+ * @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
requires std::integral
OverflowingPair 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
requires std::integral
OverflowingPair 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
requires std::integral
OverflowingPair 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
requires std::integral
OverflowingPair overflowing_div(T a, T b) {
diff --git a/src/yycc/num/stringify.hpp b/src/yycc/num/stringify.hpp
index 3e05e5b..f93d86b 100644
--- a/src/yycc/num/stringify.hpp
+++ b/src/yycc/num/stringify.hpp
@@ -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.