YYCCommonplace/doc/src/intro.dox

/**

\page intro Introduction to YYCCommonplace

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, 
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.
After this, I do not need to write these duplicated code in each project. 
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 project mainly is served for my personal use. 
But I would be honored if you would like to use this in your project. 
Almost of my projects will gradually adapt to this project and drop their own individual implementations.

\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 maximum 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 macros 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.

YYCC library self provides some build scripts for convenient use which are located in \c script directory.
Please note all of these script should be executed in the root of YYCC project, not the script directory
(i.e. work directory is the root directory of YYCC).
All scripts will try to do a simple check about this if you accidently execute them in a wrong place.

If you are not willing to use our build script, or our build script went wrong,
you can create your personal build script by viewing our build script.

\subsection intro__usage__linux Linux

Building YYCC on Linux is easy to do by executing <TT>script/linux_build.sh</TT>.
After script done, you will find installation result in directory <TT>bin/install</TT>.
Then other CMake project can utilize it (non-CMake project also can utilize this).

\subsection intro__usage__win Windows

For building on Windows, there are 2 distribution types which YYCC can create.
First is CMake distribution, this distribution is served for other CMake project using.
Another one is MSVC distribution, this distribution is served for other MSVC project using.
These have different directory layout which is specifically designed for corresponding build tools.
See following section for more details.

\subsubsection intro__usage__win__cmake CMake Distribution

For creating CMake distribution, please execute script <TT>script/win_build.bat</TT>.
After script done, you will find CMake distribution in directory <TT>bin/install</TT> with following structure.
In default, building process will build documentation automatically.
If you don't want built documentation, please execute with extra argument \c NODOC, i.e. <TT>script/win_build.bat NODOC</TT>.

\verbatim
YYCC
├─Win32_Debug: Win32 Debug package
│  ├─include: Headers
│  └─lib: Library for linking and CMake package file
├─Win32_Release: Win32 Release package
│  ├─bin: Executable testbench
│  ├─include: Headers
│  └─lib: Library for linking and CMake package file
├─x64_Debug: x64 Debug package
│  ├─include: Headers
│  └─lib: Library for linking and CMake package file
└─x64_Release: x64 Release package
    ├─bin: Executable testbench
    ├─include: Headers
    ├─lib: Library for linking and CMake package file
    └─share: Documentation
\endverbatim

Every different architecture and build type have a single and full directory.
CMake project can use one of by adding their build type in \c find_package path.
So that CMake will automatically utilize correct package when switching build type.

\subsubsection intro__usage__win__msvc MSVC Distribution

Before creating MSVC distribution, you should create CMake distribution first,
because MSVC distribution depend on CMake distribution.

After creating CMake distribution, you can simply create MSVC distribution by executing <TT>script/win_msvc_build.bat</TT>.
Then you will find your MSVC distribution in directory <TT>bin/msvc_install</TT> with following structure.
Same as CMake distribution, if you don't want built documentation, 
please execute <TT>script/win_msvc_build.bat NODOC</TT>.

\verbatim
YYCC
├─bin
│  ├─Win32: Win32 Release testbench
│  └─x64: x64 Release testbench
├─include: Headers
├─lib
│  ├─Win32
│  │  ├─Debug: Win32 Debug library for linking
│  │  └─Release: Win32 Release library for linking
│  └─x64
│      ├─Debug: x64 Debug library for linking
│      └─Release: x64 Release library for linking
└─share: Documentation
\endverbatim

The different between MSVC distribution and CMake distribution is
that MSVC distribution places all static library under one director \c lib.
Thus in MSVC project user can simply spcify the install path of YYCC,
and use MSVC macros in path to choose correct static library for linking

\section intro__debug Debug Tips

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.

*/