doc: add new added carton doc

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<size_t, float, 8u> 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<size_t, float, 8u> 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<size_t, float, 16u> 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<size_t, double, 16u> fft;
+
+// Prepare complex input data
+std::complex<double> 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.
+
+*/
+}

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<const wchar_t*>(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
+
+*/
+}

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 <fstream>
+
+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
+
+*/
+}

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 <yycc/carton/wcwidth.hpp>
+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
+
+*/
+}

doc/src/index.dox

@@ -70,6 +70,14 @@
 
     \li \subpage binstore
 
+    \li \subpage fft
+
+    \li \subpage lexer61
+
+    \li \subpage wcwidth
+
+    \li \subpage tabulate
+
     <B>Windows Specific Features</B>
 
     \li \subpage windows__import_guard