From e161dafac544c2f566e39369a5b8a9a92972b252 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Tue, 20 Jan 2026 13:57:09 +0800 Subject: [PATCH] doc: add new added carton doc --- doc/src/carton/fft.dox | 93 +++++++++++++++++++++++++++++++ doc/src/carton/lexer61.dox | 102 ++++++++++++++++++++++++++++++++++ doc/src/carton/tabulate.dox | 107 ++++++++++++++++++++++++++++++++++++ doc/src/carton/wcwidth.dox | 103 ++++++++++++++++++++++++++++++++++ doc/src/index.dox | 8 +++ 5 files changed, 413 insertions(+) create mode 100644 doc/src/carton/fft.dox create mode 100644 doc/src/carton/lexer61.dox create mode 100644 doc/src/carton/tabulate.dox create mode 100644 doc/src/carton/wcwidth.dox diff --git a/doc/src/carton/fft.dox b/doc/src/carton/fft.dox new file mode 100644 index 0000000..9486967 --- /dev/null +++ b/doc/src/carton/fft.dox @@ -0,0 +1,93 @@ +namespace yycc::carton::fft { +/** + +\page fft Homemade FFT + +This namespace provides a fast Fourier transform (FFT) implementation for signal processing applications. +It includes classes for performing FFT computations on complex and real-valued signals, along with +window functions to reduce spectral leakage. + +\section fft__basic_usage Basic Usage + +To use the FFT functionality for general purposes, use the FriendlyFft class: + +\code +#include "yycc/carton/fft.hpp" +using namespace yycc::carton::fft; + +// Create FFT instance for 8-point transform +FriendlyFft fft; + +// Prepare input data (must be power of 2 in length) +float time_scope[8] = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f}; +float freq_scope[4]; // Output is half the input size + +// Create window function to reduce spectral leakage +Window window(WindowType::HanningWindow); + +// Perform FFT transformation +fft.easy_compute(time_scope, freq_scope, window); + +// freq_scope now contains frequency domain data +\endcode + +\section fft__window_functions Window Functions + +The library provides window functions to reduce spectral leakage: + +\code +// Create a Hanning window for 16-point data +Window hanning_window(WindowType::HanningWindow); + +// Apply window to your data +float data[16]; +// ... initialize data ... +hanning_window.apply_window(data); +\endcode + +\section fft__direct_fft Direct FFT Computation + +For more control over the FFT computation, use the core Fft class: + +\code +#include "yycc/carton/fft.hpp" + +// Create FFT instance for 16-point transform +Fft fft; + +// Prepare complex input data +std::complex data[16]; +// ... initialize complex data ... + +// Perform FFT transformation +fft.compute(data); +// data now contains transformed values +\endcode + +\section fft__predefined_types Predefined Types + +The library provides commonly used FFT types for convenience: + +\code +// Float precision FFTs +Fft4F fft4f; // 4-point float FFT +Fft8F fft8f; // 8-point float FFT +Fft16F fft16f; // 16-point float FFT +Fft256F fft256f; // 256-point float FFT + +// Double precision FFTs +Fft4 fft4; // 4-point double FFT +Fft8 fft8; // 8-point double FFT +Fft16 fft16; // 16-point double FFT +Fft256 fft256; // 256-point double FFT +\endcode + +\section fft__requirements Requirements + +- Template parameters must satisfy certain constraints: + - \c TIndex: The index type used by FFT which must be an unsigned integral type. + - \c TFloat: The float point type used by FFT. + - \c VN: The point of FFT which must be a power of 2 and >= 2. + +*/ +} \ No newline at end of file diff --git a/doc/src/carton/lexer61.dox b/doc/src/carton/lexer61.dox new file mode 100644 index 0000000..8d85206 --- /dev/null +++ b/doc/src/carton/lexer61.dox @@ -0,0 +1,102 @@ +namespace yycc::carton::lexer61 { +/** + +\page lexer61 Homemade Command Line Lexer + +This namespace provides a lexer for parsing command-line arguments, supporting various quoting mechanisms, +escape sequences, and Unicode characters. It follows the standard shell parsing rules for handling +arguments containing spaces and special characters. + +\section lexer61__basic_usage Basic Usage + +To parse command line arguments, create a Lexer61 instance and call the Lexer61::lex() method: + +\code +#include "yycc/carton/lexer61.hpp" +using namespace yycc::carton::lexer61; + +Lexer61 lexer; +auto result = lexer.lex(u8"program arg1 arg2 arg3"); + +if (result.has_value()) { + auto args = std::move(result.value()); + // args contains: [u8"program", u8"arg1", u8"arg2", u8"arg3"] + for (const auto& arg : args) { + std::wcout << reinterpret_cast(arg.c_str()) << std::endl; + } +} +\endcode + +\section lexer61__quoting_support Quoting Support + +The lexer supports both single and double quotes for grouping arguments with spaces: + +\code +Lexer61 lexer; + +// Double quotes +auto result1 = lexer.lex(u8R"(program "argument with spaces" end)"); +// Result: [u8"program", u8"argument with spaces", u8"end"] + +// Single quotes +auto result2 = lexer.lex(u8"program 'another argument' end"); +// Result: [u8"program", u8"another argument", u8"end"] + +// Mixed quotes +auto result3 = lexer.lex(u8R"(program "double quoted 'single inside'" 'single quoted "double inside"')"); +// Result: [u8"program", u8"double quoted 'single inside'", u8"single quoted \"double inside\""] +\endcode + +\section lexer61__escape_sequences Escape Sequences + +The lexer supports escape sequences for including special characters: + +\code +Lexer61 lexer; +auto result = lexer.lex(u8R"(program escaped\ space "quoted with \" quote" 'single with \' quote')"); + +// Result: [u8"program", u8"escaped space", u8"quoted with \" quote", u8"single with \' quote"] +\endcode + +\section lexer61__unicode_support Unicode Support + +The lexer fully supports Unicode characters in command line arguments: + +\code +Lexer61 lexer; +auto result = lexer.lex(u8"程序 中文 参数"); +// Result: [u8"程序", u8"中文", u8"参数"] + +// With quotes +auto result2 = lexer.lex(u8R"(程序 "中文 参数" '另一个"引号"参数')"); +// Result: [u8"程序", u8"中文 参数", u8"另一个\"引号\"参数"] +\endcode + +\section lexer61__empty_arguments Empty Arguments + +Empty arguments can be represented with empty quotes: + +\code +Lexer61 lexer; +auto result = lexer.lex(u8R"(program "" '')"); + +// Result: [u8"program", u8"", u8""] +\endcode + +\section lexer61__error_handling Error Handling + +The lexer uses \c std::expected for error handling: + +\code +Lexer61 lexer; +auto result = lexer.lex(u8R"(program "unclosed quote)"); + +if (!result.has_value()) { + // Handle error - in this case, unclosed quote + std::cerr << "Error: unclosed quote" << std::endl; + std::abort(); +} +\endcode + +*/ +} \ No newline at end of file diff --git a/doc/src/carton/tabulate.dox b/doc/src/carton/tabulate.dox new file mode 100644 index 0000000..6cf4991 --- /dev/null +++ b/doc/src/carton/tabulate.dox @@ -0,0 +1,107 @@ +namespace yycc::carton::tabulate { +/** + +\page tabulate Tabulate Utilities + +This namespace provides utilities for creating formatted tables in console output. +It supports Unicode text, automatic column width calculation, customizable headers, +and flexible display options. + +\section tabulate__basic_usage Basic Usage + +To create a simple table with headers and data rows: + +\code +#include "yycc/carton/tabulate.hpp" +using namespace yycc::carton::tabulate; + +// Create a table with 3 columns +Tabulate table(3); + +// Set the header +table.set_header({u8"Name", u8"Age", u8"City"}); + +// Add data rows +table.add_row({u8"Alice", u8"30", u8"New York"}); +table.add_row({u8"Bob", u8"25", u8"Los Angeles"}); +table.add_row({u8"Charlie", u8"35", u8"Chicago"}); + +// Print the table +table.print(); +\endcode + +This will output: +\verbatim +Name Age City +----- --- --------- +Alice 30 New York +Bob 25 Los Angeles +Charlie 35 Chicago +\endverbatim + +\section tabulate__customization Customization Options + +You can customize various aspects of the table: + +\code +Tabulate table(3); + +// Set a custom separator bar +table.set_bar(u8"==="); + +// Add a prefix (useful for indentation) +table.set_prefix(u8"> "); + +// Control header and bar visibility +table.show_header(false); // Hide header +table.show_bar(true); // Show separator bar + +// Set header +table.set_header({u8"Col1", u8"Col2", u8"Col3"}); + +// Add data +table.add_row({u8"data1", u8"data2", u8"data3"}); + +table.print(); +\endcode + +\section tabulate__unicode_support Unicode Support + +The library fully supports Unicode text in tables: + +\code +Tabulate table(3); + +// Set Unicode header +table.set_header({u8"姓名", u8"年龄", u8"城市"}); + +// Add Unicode data +table.add_row({u8"张三", u8"30", u8"北京"}); +table.add_row({u8"李四", u8"25", u8"上海"}); + +table.print(); +\endcode + +\section tabulate__stream_output Stream Output + +You can print to any output stream, not just stdout: + +\code +#include + +Tabulate table(2); +table.set_header({u8"Key", u8"Value"}); +table.add_row({u8"temp", u8"25C"}); + +// Print to file +std::ofstream file("table.txt"); +table.print(file); + +// Or print to stringstream +std::stringstream ss; +table.print(ss); +std::string table_str = ss.str(); +\endcode + +*/ +} \ No newline at end of file diff --git a/doc/src/carton/wcwidth.dox b/doc/src/carton/wcwidth.dox new file mode 100644 index 0000000..f0e94c6 --- /dev/null +++ b/doc/src/carton/wcwidth.dox @@ -0,0 +1,103 @@ +namespace yycc::carton::wcwidth { +/** + +\page wcwidth Cross-platform Wcwidth + +This namespace provides cross-platform implementations of character width calculation functions, +similar to the Linux-specific \c wcswidth function. It supports Unicode text and ANSI escape sequences, +making it suitable for calculating display widths of text in terminals across different platforms. + +\section wcwidth__basic_usage Basic Usage + +To calculate the display width of a string in a terminal: + +\code +#include +using namespace yycc::carton::wcwidth; + +// Calculate width of ASCII text +size_t width1 = wcwidth(U'a'); // Returns 1 +auto width2 = wcswidth(u8"Hello"); // Returns 5 + +// Calculate width of Unicode text +auto width3 = wcswidth(u8"你好世界"); // Returns 8 (Chinese chars typically take 2 spaces each) +auto width4 = wcswidth(u8"ありがとう"); // Returns 10 (Japanese katakana) +\endcode + +\section wcwidth__ansi_support ANSI Escape Sequence Support + +The library can handle ANSI escape sequences (like color codes) in text +which is not supported by Linux \c wcswidth. + +\code +#include "yycc/carton/termcolor.hpp" +using namespace yycc::carton::termcolor; + +// Calculate width of colored text +auto colored_text = colored(u8"Hello World", Color::Red); +auto width = wcswidth(colored_text); +// Returns the width of "Hello World" (ignoring the ANSI escape sequences) +\endcode + +\section wcwidth__error_handling Error Handling + +The functions use \c std::expected for error handling: + +\code +#include "yycc/carton/wcwidth.hpp" + +// Safe way to handle potential errors +auto result = wcswidth(u8"\033?"); // Invalid ANSI sequence + +if (result.has_value()) { + size_t width = result.value(); + std::cout << "Width: " << width << std::endl; +} else { + std::cout << "Invalid string" << std::endl; +} +\endcode + +\section wcwidth__character_types Supported Character Types + +The library provides two main functions: + +- wcwidth(): Calculate width of a single character. +- wcswidth(): Calculate width of a string. + +\code +// Using wcwidth for single characters +size_t char_width = wcwidth(U'A'); // Returns 1 +size_t emoji_width = wcwidth(U'😀'); // Returns width of emoji + +// Using wcswidth for strings +auto str_width1 = wcswidth(u8"Hello"); // Returns 5 +auto str_width2 = wcswidth(U"Unicode String"); // Returns string length in display width +\endcode + +\section wcwidth__platform_differences Platform Considerations + +This library addresses platform differences in wide character handling: + +\li On Linux, \c whar_t is 4 bytes and can represent any Unicode character +\li On Windows, \c whar_t is 2 bytes and may require surrogate pairs for some characters + +So this library uses \c char32_t internally to ensure consistent behavior across platforms, +and expose functions with \c char32_t and \c char8_t string container respectively for user. + +\section wcwidth__unicode_support Unicode and East Asian Widths + +The library properly handles East Asian character widths: + +\code +// Chinese characters typically occupy 2 terminal spaces +auto chinese_width = wcswidth(u8"中文"); // Returns 4 (2 chars × 2 spaces each) + +// Japanese characters +auto kana_width = wcswidth(u8"ありがとう"); // Returns 10 (5 kana × 2 spaces each) + +// Mixed text +auto mixed_width = wcswidth(u8"Hello 世界"); // Returns 8 (5 ASCII + 1 space + 2 Chinese chars × 2 spaces) +\endcode + +*/ +} \ No newline at end of file diff --git a/doc/src/index.dox b/doc/src/index.dox index d1cc1dd..db95975 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -70,6 +70,14 @@ \li \subpage binstore + \li \subpage fft + + \li \subpage lexer61 + + \li \subpage wcwidth + + \li \subpage tabulate + Windows Specific Features \li \subpage windows__import_guard