yyc12345/YYCCommonplace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: add documentation for ConsoleHelper

Browse Source
This commit is contained in:
yyc12345
2024-07-16 10:41:09 +08:00
parent 81fe72c425
commit b13bb445e4
3 changed files with 182 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
src/ConsoleHelper.hpp
View File

@ -7,60 +7,7 @@
/**
* @brief The namespace providing universal Console visiting functions like C-Sharp Console class.
* @details
* \par Why this Namespace
* Windows console doesn't support UTF8 very well.
* The standard input output functions can not work properly on Windows with UTF8.
* So we create this namespace and provide various console-related functions
* to patch Windows console and let it more like the console in other platforms.
* \par
* The function provided in this function can be called in any platforms.
* In Windows, the implementation will use Windows native function,
* and in other platform, the implementation will redirect request to standard C function
* like std::fputs and etc.
* So the programmer do not need to be worried about which function should they use,
* and don't need to use macro to use different IO function in different platforms.
* It is just enough that fully use the functions provided in this namespace.
* \par
* All IO functions this namespace provided are UTF8-based.
* It also means that input output string should always be UTF8 encoded.
*
* \par Input Functions
* Please note that EOL will automatically converted into LF on Windows platform, not CRLF.
* This action actually is removing all CR chars in result string.
* This behavior affect nothing in most cases but it still is possible break something in some special case.
* \par
* Due to implementation, if you decide to use this function,
* you should give up using any other function to read stdin stream,
* such as std::gets() and std::cin.
* Because this function may read chars which is more than needed.
* These extra chars will be stored in this function and can be used next calling.
* But these chars can not be visited by stdin again.
* This behavior may cause bug.
* So if you decide using this function, stick on it and do not change.
* \par
* Due to implementation, this function do not support hot switch of stdin.
* It means that stdin can be redirected before first calling of this function,
* but it should not be redirected during program running.
* The reason is the same one introduced above.
*
* \par Output Functions
* In current implementation, EOL will not be converted automatically to CRLF.
* This is different with other stream read functions provided in this namespace.
* \par
* Comparing with other stream read functions provided in this namespace,
* stream write function support hot switch of stdout and stderr.
* Because they do not have internal buffer storing something.
* \par
* In this namespace, there are various stream write function.
* There is a list telling you how to choose one from them for using:
* \li Functions with leading "Err" will write data into stderr,
* otherwise they will write data into stdout.
* \li Functions with embedded "Format" are output functions with format feature
* like std::fprintf(), otherwise the functions with embedded "Write" will
* only write plain string like std::fputs().
* \li Functions with trailing "Line" will write extra EOL to break current line.
* This is commonly used, otherwise functions will only write the text provided by arguments,
* without adding something.
* \ref console_helper
*/
namespace YYCC::ConsoleHelper {