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.