From 1a4074fd983e5cb97c953113603c4044abec372b Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Wed, 21 Jan 2026 11:17:12 +0800 Subject: [PATCH] doc: add last lost doc --- doc/src/env.dox | 85 +++++++++++++++++++++++++++++ doc/src/index.dox | 4 ++ doc/src/rust.dox | 133 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 222 insertions(+) create mode 100644 doc/src/env.dox create mode 100644 doc/src/rust.dox diff --git a/doc/src/env.dox b/doc/src/env.dox new file mode 100644 index 0000000..248de58 --- /dev/null +++ b/doc/src/env.dox @@ -0,0 +1,85 @@ +namespace yycc::env { +/** + +\page env Environment Operations + +This namespace provide various environment operations inspired by Rust standard library. + +\section env__var Environment Variable Operations + +These functions allow manipulation of environment variables with proper error handling using \c std::expected. + +\li get_var(): Get the value of a given environment variable name +\li set_var(): Set the value of a given environment variable name +\li del_var(): Delete environment variable with given name +\li get_vars(): Get all environment variables as a list of name-value pairs + +There is an example usage of these functions below: + +\code +#include + +auto result = yycc::env::get_var(u8"PATH"); +if (result.has_value()) { + auto value = result.value(); + // Use the value... +} else { + // Handle the error +} +\endcode + +\section env__path Path Operations + +These functions provide access to various important paths in the system environment. + +\li current_dir(): Returns the current working directory +\li current_exe(): Returns the path of the current running executable +\li home_dir(): Returns the path of the current user's home directory if known +\li temp_dir(): Returns the path of a temporary directory + +There is an example usage of these functions below: + +\code +#include +#include +#include + +using namespace yycc::patch::stream; + +auto cwd_result = yycc::env::current_dir(); +if (cwd_result.has_value()) { + std::cout << "Current directory: " << cwd_result.value() << std::endl; +} + +auto exe_result = yycc::env::current_exe(); +if (exe_result.has_value()) { + std::cout << "Executable path: " << exe_result.value() << std::endl; +} +\endcode + +\section env__arg Command Line Argument Operations + +These functions provide access to command-line arguments passed to the program. + +\li get_args(): Returns the arguments that this program was started with + +There is an example usage of these functions below: + +\code +#include +#include +#include + +using namespace yycc::patch::stream; + +auto args_result = yycc::env::get_args(); +if (args_result.has_value()) { + auto args = args_result.value(); + for (auto& arg : args) { + std::cout << "Arg: " << arg << std::endl; + } +} +\endcode + +*/ +} \ No newline at end of file diff --git a/doc/src/index.dox b/doc/src/index.dox index d5fba09..a51ae8e 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -51,6 +51,10 @@ \li \subpage patch + \li \subpage env + + \li \subpage rust + Text Encoding \li \subpage encoding__stl diff --git a/doc/src/rust.dox b/doc/src/rust.dox new file mode 100644 index 0000000..ee89410 --- /dev/null +++ b/doc/src/rust.dox @@ -0,0 +1,133 @@ +namespace yycc { +/** + +\page rust Rust Facilities in C++ + +This collection of following headers brings Rust-style programming facilities to C++. + +\section rust__primitive Primitive Types + +The yycc::primitive namespace provides primitive types similar to Rust's approach. +Especially resolve the problem that the names of C++ primitive types are so long. + +There is an example of using primitive types: + +\code +#include +using namespace yycc::primitive; + +i32 value = 42; +u64 big_number = 1000000ULL; +f64 precision = 3.14159265359; +\endcode + +\section rust__option Option Type + +The yycc::option namespace reproduces Rust's Option type and its members Some and None in C++. +Considering C++ has provide \c std::optional, this namespace provided contents are just an alias to it. + +\li yycc::option::Option - Template alias for std::optional +\li yycc::option::Some - Function to create an Option with a value +\li yycc::option::None - Function to create an empty Option + +There is an example of using \c Option type: + +\code +#include +#include + +using namespace yycc::option; + +Option maybe_value = Some>(42); +if (maybe_value.has_value()) { + std::cout << "Value: " << maybe_value.value() << std::endl; +} + +auto empty_value = None>(); +if (!empty_value.has_value()) { + std::cout << "No value present" << std::endl; +} +\endcode + +\section rust__result Result Type + +The yycc::result namespace reproduces Rust's Result type and its members Ok and Err in C++. +Considering C++ has provide \c std::expected, this namespace provided contents are just an alias to it. + +\li yycc::result::Result - Template alias for std::expected +\li yycc::result::Ok - Function to create a Result with a success value +\li yycc::result::Err - Function to create a Result with an error value + +There is an example of using \c Result type: + +\code +#include +#include + +using namespace yycc::result; + +Result divide(int a, int b) { + if (b == 0) { + return Err>(-1); // Error code + } + return Ok>(a / b); +} + +auto result = divide(10, 2); +if (result.has_value()) { + std::cout << "Result: " << result.value() << std::endl; +} else { + std::cout << "Error occurred: " << result.error() << std::endl; +} +\endcode + +\section rust__panic Panic Mechanism + +The yycc::panic namespace provides Rust-style panic functionality for immediate program termination on unrecoverable errors. +This imitates Rust's panic! macro behavior, allowing the program to immediately exit with error information and stack traces. + +\li RS_PANIC: Macro equivalent to Rust's panic! macro. +This macro will help you append all filename, line and function info to the real panic trigger function. +\li yycc::panic::panic: The actual function called by the macro. +User usually does not need to call this function directly. + +There is an example of using this panic mechanism: + +\code +#include + +void critical_function(int err_code) { + // Some condition that indicates an unrecoverable error + if (err_code != 100) { + RS_PANIC("Unrecoverable error in critical function with code {}", err_code); + } +} +\endcode + +\section rust__prelude Prelude + +The yycc::prelude namespace provides a Rust-like prelude for C++. In Rust, types are automatically imported into all files by default. +This default-imported set of types is called the "prelude". +This namespace provides a similar concept for C++. + +This namespace will extract following content into \b global scope: + +\li All primitive types defined in yycc::primitive. +\li Vec: \c std::vector template alias. +\li All functionality from yycc::option and yycc::result namespaces. +\li Panic mechanism from yycc::panic. + +There is an example of using this header: + +\code +#include + +// Now all Rust-style facilities are available without prefixes: +i32 x = 42; // From primitive +Vec numbers = {1, 2, 3}; // Vector of primitive types +auto result = Ok>(x); // Result type +RS_PANIC("Something went wrong"); // Panic macro +\endcode + +*/ +} \ No newline at end of file