diff --git a/doc/src/encoding_helper.dox b/doc/src/encoding_helper.dox new file mode 100644 index 0000000..765004b --- /dev/null +++ b/doc/src/encoding_helper.dox @@ -0,0 +1,11 @@ +/** + +\page encoding_helper Encoding Helper + +YYCC::EncodingHelper namespace include all encoding related functions: + +\li The convertion between native string and UTF8 string which has been introduced in chapter \ref library_encoding. +\li Windows specific convertion between \c WCHAR, UTF8 string and string encoded by other encoding. +\li The convertion among UTF8, UTF16 and UTF32. + +*/ \ No newline at end of file diff --git a/doc/src/index.dox b/doc/src/index.dox index 2bad68c..2779413 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -1,11 +1,45 @@ /** -\mainpage YYCCommonplace Library Manual +\mainpage YYCCommonplace Programming Manual -This manual is organized into the following chapters and appendices: + + + + + +
+ \image html yycc_icon.png +
+ YYCCommonplace Programming Manual -\li \subpage intro + Copyright 2024 by yyc12345. +
+ + + + +
+ This software and manual are provided under the terms of the MIT License. +
+ + + + + +
-\li \subpage library_encoding + \subpage intro + + \subpage library_encoding + + \subpage encoding_helper + + \subpage string_helper + + + + placeholder + +
*/ diff --git a/doc/src/intro.dox b/doc/src/intro.dox index cfbf0ca..aa43b28 100644 --- a/doc/src/intro.dox +++ b/doc/src/intro.dox @@ -2,10 +2,75 @@ \page intro Introduction to YYCCommonplace -work in progress +YYCCommonplace, or YYC Commonplace (abbr. YYCC), is a static library providing various useful C++ functions when programming with standard library or Windows environment. -\section intro_wip Work in Progress +Actually YYCC provides the functions which I frequently used in my personal projects. +Thus I do not need copy these functions from one project to another project. +I can write them once and use them everywhere. +It's also good for bug fix. +If I found bug in these code, I only need to fix it in this project. +Otherwise I need to fix them one by one in each project because they share the same code. -work in progress +\section intro_why Why YYCCommonplace + +\subsection intro_why_windows Windows Issues + +I frequently program on Windows environment because the software I programming for, Virtools, is Windows-only software. +During programming, I found Windows is super lack in UTF8 supports. +Programmer loves UTF8, because it can handle all charcaters over the world in one encoding and is still compatible with C-Style string. +However, Windows use a weird way to achieve internationalization, 2 different function trailing, A and W for legacy code and modern code respectively. +The worst things is that the char type W trailing function used, \c WCHAR, is defined as 2 bytes long, not 4 bytes long as Linux does (\c wchar_t). +It mean that one emoji charcater will be torn into 2 \c WCHAR on Windows because emoji code unit is higher than the manimum value of \c WCHAR. + +Also, there are various issues which should not be presented. +For example, Microsoft invents various \e safe standard library functions to prevent possible overflow issues raised by \c std::fgets and etc. +also, MSVC may throw weird error when you using some specific standard library functions. +You need to define some weird macro to disable this shitty behavior. + +There are various non-standard issue you may faced on Windows programming. +All in all, programming on Windows is a tough work. +This is one of the reasons why I create this library. +I create much wrappers for these weird Windows functions. +Thus I can have a similar Linux C++ programming experience on Windows. + +\subsection intro_why_std Standard Library Issues + +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 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. + +That's why I create this library. +I bring these function in this library. +Not industrial level, but easy to use and have enough performance in my project. + +\subsection intro_why_boost Boost Issues + +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. + +The functions belonging to Boost is industrial level. +But what I want is not industrial level functions. +I only need a function which can barely finish my work. That's enough. +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. +Otherwise you may make mistake during using this library. +I suggest you read this manual from top to bottom in the left tree panel, one by one. + +This library is a static library. */ diff --git a/doc/src/library_encoding.dox b/doc/src/library_encoding.dox index 0d19472..1b10d8c 100644 --- a/doc/src/library_encoding.dox +++ b/doc/src/library_encoding.dox @@ -32,7 +32,7 @@ That's unacceptable! So I create my own UTF8 type to avoid the scenario that sta \section library_encoding_utf8_literal UTF8 Literal -C++ standard allows programmer declare a UTF8 literal explicitly by writing code like this: +C++ standard allows programmer declare an UTF8 literal explicitly by writing code like this: \code u8"foo bar" @@ -41,11 +41,10 @@ u8"foo bar" This is okey. But it may incompatible with YYCC UTF8 char type. According to C++ standard, this UTF8 literal syntax will only return \c const \c char8_t* if your C++ standard higher or equal to C++ 20, otherwise it will return \c const \c char*. -This behavior cause that you can not assign this UTF8 literal to yycc_u8string if you are in the environment which do not support \c char8_t, +This behavior cause that you can not assign this UTF8 literal to \c yycc_u8string if you are in the environment which do not support \c char8_t, because their types are different. Thereas you can not use the functions provided by this library because they are all use YYCC defined UTF8 char type. - -So I will tell you how to create UTF8 literal in following content of this section. +So I will tell you how to correctly create UTF8 literal in the following content. YYCC provides a macro \c YYCC_U8 to resolve this issue. You can declare UTF8 literal like this: @@ -58,11 +57,12 @@ You don't need add extra \c u8 prefix in string given to the macro. This macro will do this automatically. In detail, this macro do a \c reinterpret_cast to change the type of given argument to \c const \c yycc_char8_t* forcely. -This ensure that declared UTF8 literal is compatible with YYCC defined UTF8 types. +This ensure that declared UTF8 literal is compatible with YYCC UTF8 types. \section library_encoding_utf8_pointer UTF8 String Pointer -Besides UTF8 literal, another issue you may be faced is how to convert native UTF8 string pointer to YYCC UTF8 type. +Besides UTF8 literal, another issue you may be faced is how to convert native UTF8 string pointer to YYCC UTF8 type +(\e native means \c const \c char* or \c char*, the string using char as its char type). Many legacy code assume \c char* is encoded with UTF8 (the exception is Windows). But \c char* is incompatible with yycc_char8_t. YYCC provides YYCC::EncodingHelper::ToUTF8 to resolve this issue. There is an exmaple: @@ -75,7 +75,7 @@ char* mutable_utf8 = const_cast(absolutely_is_utf8); // This is not safe. yycc_char8_t* mutable_converted = YYCC::EncodingHelper::ToUTF8(mutable_utf8); \endcode -YYCC::EncodingHelper::ToUTF8 has 2 overloads which can handle const and non-const stirng pointer convertion respectively. +YYCC::EncodingHelper::ToUTF8 has 2 overloads which can handle const and mutable stirng pointer convertion respectively. YYCC also provide ability that convert YYCC UTF8 char type to native char type by YYCC::EncodingHelper::ToNative. Here is an exmaple: @@ -88,12 +88,12 @@ yycc_char8_t* mutable_yycc_utf8 = const_cast(yycc_utf8); // Not safe. Als char* mutable_converted = YYCC::EncodingHelper::ToNative(mutable_yycc_utf8); \endcode -Same as YYCC::EncodingHelper::ToUTF8, YYCC::EncodingHelper::ToNative also has 2 overloads to handle const and non-const string pointer. +Same as YYCC::EncodingHelper::ToUTF8, YYCC::EncodingHelper::ToNative also has 2 overloads to handle const and mutable string pointer. \section library_encoding_utf8_container UTF8 String Container The final issue you faced is string container. -In many personal project, you may use \c std::string everywhere because \c std::u8string may not be presented when you writing your peoject. +In many personal project, programmer may use \c std::string everywhere because \c std::u8string may not be presented when writing peoject. How to do convertion between native string container and YYCC UTF8 string container? It is definitely illegal that directly do force convertion. Because they may have different class layout. @@ -108,12 +108,12 @@ yycc_u8string yycc_string = YYCC::EncodingHelper::ToUTF8(native_string); auto result = YYCC::EncodingHelper::UTF8ToUTF32(yycc_string); \endcode -Actually, YYCC::EncodingHelper::ToUTF8 accept one \c std::string_view as argument. +Actually, YYCC::EncodingHelper::ToUTF8 accepts a reference to \c std::string_view as argument. However, there is a implicit convertion from \c std::string to \c std::string_view, so you can directly pass a \c std::string instance to it. String view will reduce unnecessary memory copy. -If you just want to pass native string container to function, and this function accept yycc_u8string_view as its argument, +If you just want to pass native string container to function, and this function accepts \c yycc_u8string_view as its argument, you can use alternative YYCC::EncodingHelper::ToUTF8View. \code @@ -126,6 +126,8 @@ Comparing with previous one, this example use less memory. The reduced memory is the content of \c yycc_string because string view is a view, not the copy of original string. Same as UTF8 string pointer, we also have YYCC::EncodingHelper::ToNative and YYCC::EncodingHelper::ToNativeView do correspondant reverse convertion. +Try to do your own research and figure out how to use them. +It's pretty easy. \section library_encoding_windows Warnings to Windows Programmer diff --git a/doc/src/string_helper.dox b/doc/src/string_helper.dox new file mode 100644 index 0000000..bfd93c5 --- /dev/null +++ b/doc/src/string_helper.dox @@ -0,0 +1,6 @@ +/** + +\page string_helper String Helper + + +*/ diff --git a/doc/src/yycc_icon.png b/doc/src/yycc_icon.png new file mode 100644 index 0000000..81a207c Binary files /dev/null and b/doc/src/yycc_icon.png differ