docs: 重构 API 文档结构并修正源码准确性

- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
2026-03-19 00:22:30 +08:00
parent d0e16962c8
commit dc850d7739
1012 changed files with 26673 additions and 9222 deletions
--- a/docs/api/containers/string/clear.md
+++ b/docs/api/containers/string/clear.md
@@ -0,0 +1,39 @@
+# String::Clear
+
+```cpp
+void Clear();
+```
+
+清空字符串内容，将长度设为 0，但不释放已分配的内存。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+    std::cout << "Before clear - Length: " << s.Length()
+              << ", Capacity: " << s.Capacity() << std::endl;
+    // 输出: Before clear - Length: 11, Capacity: 12
+
+    s.Clear();
+    std::cout << "After clear - Length: " << s.Length()
+              << ", Capacity: " << s.Capacity() << std::endl;
+    // 输出: After clear - Length: 0, Capacity: 12
+    std::cout << "Empty: " << s.Empty() << std::endl;  // 输出: Empty: 1
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Reserve / Resize](reserve-resize.md) - 内存管理
--- a/docs/api/containers/string/constructor.md
+++ b/docs/api/containers/string/constructor.md
@@ -0,0 +1,49 @@
+# String::String
+
+```cpp
+String();
+String(const char* str);
+String(const char* str, SizeType len);
+String(const char* str, size_t len);  // alias
+String(const String& other);
+String(String&& other) noexcept;
+```
+
+构造 String 对象。提供多种构造方式以适应不同的使用场景。
+
+**参数：**
+- `str` - 以 null 结尾的 C 字符串
+- `len` - 要复制的字符数量
+- `other` - 另一个 String 对象（用于拷贝构造或移动构造）
+
+**返回：** 无
+
+**复杂度：**
+- 默认构造：O(1)
+- 从 `const char*` 构造：O(n)，其中 n 为字符串长度
+- 拷贝构造：O(n)
+- 移动构造：O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1;                          // 默认构造
+    XCEngine::Containers::String s2("hello");                 // 从 C 字符串构造
+    XCEngine::Containers::String s3("world", 3);             // 从 C 字符串前 n 个字符构造
+    XCEngine::Containers::String s4(s2);                      // 拷贝构造
+    XCEngine::Containers::String s5(std::move(s4));           // 移动构造
+
+    std::cout << s2.CStr() << std::endl;  // 输出: hello
+    std::cout << s3.CStr() << std::endl;  // 输出: wor
+    std::cout << s4.CStr() << std::endl;  // 输出: hello
+    std::cout << s5.CStr() << std::endl;  // 输出: hello
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
--- a/docs/api/containers/string/cstr.md
+++ b/docs/api/containers/string/cstr.md
@@ -0,0 +1,36 @@
+# String::CStr
+
+```cpp
+const char* CStr() const;
+```
+
+返回指向以 null 结尾的 C 字符串的指针。
+
+**参数：** 无
+
+**返回：** 指向内部字符数组的指针，以 null 结尾
+
+**复杂度：** O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+#include <cstring>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    const char* cstr = s.CStr();
+    std::cout << cstr << std::endl;  // 输出: Hello World
+
+    std::cout << "Length: " << std::strlen(cstr) << std::endl;  // 输出: Length: 11
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Length](size.md) - 获取长度
--- a/docs/api/containers/string/destructor.md
+++ b/docs/api/containers/string/destructor.md
@@ -0,0 +1,31 @@
+# String::~String
+
+```cpp
+~String();
+```
+
+销毁 String 对象，释放所有动态分配的内存。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+
+int main() {
+    {
+        XCEngine::Containers::String s("hello");
+        // s 在作用域结束时自动销毁
+    }
+    // 内存已释放
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
--- a/docs/api/containers/string/ends-with.md
+++ b/docs/api/containers/string/ends-with.md
@@ -0,0 +1,39 @@
+# String::EndsWith
+
+```cpp
+bool EndsWith(const String& suffix) const;
+bool EndsWith(const char* suffix) const;
+```
+
+检查字符串是否以指定的后缀结尾。
+
+**参数：**
+- `suffix` - 要检查的后缀（String 或 const char*）
+
+**返回：** 如果字符串以指定后缀结尾则返回 `true`，否则返回 `false`
+
+**复杂度：** O(n)，其中 n 为后缀长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    std::cout << std::boolalpha;
+    std::cout << s.EndsWith("World") << std::endl;                     // 输出: true
+    std::cout << s.EndsWith(XCEngine::Containers::String("World")) << std::endl;  // 输出: true
+    std::cout << s.EndsWith("Hello") << std::endl;                      // 输出: false
+    std::cout << s.EndsWith("") << std::endl;                            // 输出: true
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [StartsWith](starts-with.md) - 检查前缀
+- [Find](find.md) - 查找子串
--- a/docs/api/containers/string/find.md
+++ b/docs/api/containers/string/find.md
@@ -0,0 +1,47 @@
+# String::Find
+
+```cpp
+SizeType Find(const char* str, SizeType pos = 0) const;
+```
+
+在字符串中查找子串 `str`，从位置 `pos` 开始搜索。
+
+**参数：**
+- `str` - 要查找的以 null 结尾的 C 字符串
+- `pos` - 开始搜索的位置，默认为 0
+
+**返回：** 子串首次出现的起始位置；如果未找到，返回 `String::npos`
+
+**复杂度：** O(n * m)，其中 n 为原字符串长度，m 为要查找的字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World, Hello Universe");
+
+    XCEngine::Containers::String::SizeType pos1 = s.Find("World");
+    std::cout << "Found at: " << pos1 << std::endl;  // 输出: Found at: 6
+
+    XCEngine::Containers::String::SizeType pos2 = s.Find("Hello", 0);
+    std::cout << "First 'Hello' at: " << pos2 << std::endl;  // 输出: First 'Hello' at: 0
+
+    XCEngine::Containers::String::SizeType pos3 = s.Find("Hello", 7);
+    std::cout << "Second 'Hello' at: " << pos3 << std::endl;  // 输出: Second 'Hello' at: 13
+
+    XCEngine::Containers::String::SizeType pos4 = s.Find("NotFound");
+    if (pos4 == XCEngine::Containers::String::npos) {
+        std::cout << "Not found" << std::endl;  // 输出: Not found
+    }
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [StartsWith](starts-with.md) - 检查前缀
+- [EndsWith](ends-with.md) - 检查后缀
--- a/docs/api/containers/string/operator-assign.md
+++ b/docs/api/containers/string/operator-assign.md
@@ -0,0 +1,47 @@
+# String::operator=
+
+```cpp
+String& operator=(const String& other);
+String& operator=(String&& other) noexcept;
+String& operator=(const char* str);
+```
+
+将新的值赋给 String 对象，替换原有的内容。
+
+**参数：**
+- `other` - 另一个 String 对象（拷贝赋值或移动赋值）
+- `str` - 以 null 结尾的 C 字符串
+
+**返回：** `*this`，支持链式调用
+
+**复杂度：**
+- 拷贝赋值：O(n)，n 为 other 的长度
+- 移动赋值：O(1)
+- 从 `const char*` 赋值：O(n)，n 为 str 的长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1;
+    XCEngine::Containers::String s2("hello");
+
+    s1 = s2;               // 拷贝赋值
+    std::cout << s1.CStr() << std::endl;  // 输出: hello
+
+    s1 = "world";          // 从 const char* 赋值
+    std::cout << s1.CStr() << std::endl;  // 输出: world
+
+    XCEngine::Containers::String s3("moved");
+    s1 = std::move(s3);    // 移动赋值
+    std::cout << s1.CStr() << std::endl;  // 输出: moved
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
--- a/docs/api/containers/string/operator-equal.md
+++ b/docs/api/containers/string/operator-equal.md
@@ -0,0 +1,43 @@
+# operator== / operator!=
+
+```cpp
+inline bool operator==(const String& lhs, const String& rhs);
+inline bool operator!=(const String& lhs, const String& rhs);
+```
+
+判断两个字符串是否相等或不相等。
+
+**operator==：** 比较两个字符串的长度是否相等，以及内容是否相同。
+
+**operator!=：** 相当于 `!(lhs == rhs)`。
+
+**参数：**
+- `lhs` - 左侧字符串
+- `rhs` - 右侧字符串
+
+**返回：** 布尔值，表示比较结果
+
+**复杂度：** O(n)，其中 n 为字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1("Hello");
+    XCEngine::Containers::String s2("Hello");
+    XCEngine::Containers::String s3("World");
+
+    std::cout << std::boolalpha;
+    std::cout << (s1 == s2) << std::endl;  // 输出: true
+    std::cout << (s1 == s3) << std::endl;  // 输出: false
+    std::cout << (s1 != s3) << std::endl;  // 输出: true
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
--- a/docs/api/containers/string/operator-plus-assign.md
+++ b/docs/api/containers/string/operator-plus-assign.md
@@ -0,0 +1,43 @@
+# String::operator+=
+
+```cpp
+String& operator+=(const String& other);
+String& operator+=(const char* str);
+String& operator+=(char c);
+```
+
+将指定的内容追加到当前 String 的末尾。
+
+**参数：**
+- `other` - 要追加的 String 对象
+- `str` - 要追加的以 null 结尾的 C 字符串
+- `c` - 要追加的单个字符
+
+**返回：** `*this`，支持链式调用
+
+**复杂度：** O(n)，其中 n 为被追加内容的长度。可能会触发重新分配，但均摊复杂度为 O(1)。
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello");
+
+    s += XCEngine::Containers::String(" World");  // 追加 String
+    std::cout << s.CStr() << std::endl;           // 输出: Hello World
+
+    s += "!";                                     // 追加 const char*
+    std::cout << s.CStr() << std::endl;           // 输出: Hello World!
+
+    s += '?';                                     // 追加 char
+    std::cout << s.CStr() << std::endl;           // 输出: Hello World!?
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
--- a/docs/api/containers/string/operator-plus.md
+++ b/docs/api/containers/string/operator-plus.md
@@ -0,0 +1,39 @@
+# operator+
+
+```cpp
+inline String operator+(const String& lhs, const String& rhs);
+```
+
+将两个 String 对象连接，返回一个新的 String 对象。
+
+**参数：**
+- `lhs` - 左侧的 String 对象
+- `rhs` - 右侧的 String 对象
+
+**返回：** 新的 String 对象，内容为 lhs 和 rhs 的拼接
+
+**复杂度：** O(n + m)，其中 n 和 m 分别为 lhs 和 rhs 的长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1("Hello");
+    XCEngine::Containers::String s2(" World");
+    XCEngine::Containers::String s3 = s1 + s2;
+
+    std::cout << s3.CStr() << std::endl;  // 输出: Hello World
+
+    XCEngine::Containers::String s4 = XCEngine::Containers::String("Foo") + "Bar";
+    std::cout << s4.CStr() << std::endl;  // 输出: FooBar
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [operator+=](operator-plus-assign.md) - 追加操作
--- a/docs/api/containers/string/operator-subscript.md
+++ b/docs/api/containers/string/operator-subscript.md
@@ -0,0 +1,51 @@
+# String::operator[]
+
+```cpp
+char& operator[](SizeType index);
+const char& operator[](SizeType index) const;
+```
+
+通过索引访问字符串中的字符。
+
+**参数：**
+- `index` - 要访问的字符位置（从 0 开始）
+
+**返回：** 位置 `index` 处字符的引用（可写或只读）
+
+**复杂度：** O(1)
+
+**注意：** 不进行边界检查。调用者需确保 `index < Length()`。
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello");
+
+    // 只读访问
+    for (XCEngine::Containers::String::SizeType i = 0; i < s.Length(); ++i) {
+        std::cout << s[i];
+    }
+    std::cout << std::endl;  // 输出: Hello
+
+    // 可写访问
+    s[0] = 'J';
+    s[1] = 'a';
+    s[4] = '!';
+    std::cout << s.CStr() << std::endl;  // 输出: Jallo!
+
+    // const 版本
+    const XCEngine::Containers::String& cs = s;
+    char first = cs[0];
+    std::cout << "First char: " << first << std::endl;  // 输出: First char: J
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Length](size.md) - 获取长度
--- a/docs/api/containers/string/reserve-resize.md
+++ b/docs/api/containers/string/reserve-resize.md
@@ -0,0 +1,51 @@
+# String::Reserve / Resize
+
+```cpp
+void Reserve(SizeType capacity);
+void Resize(SizeType newSize);
+void Resize(SizeType newSize, char fillChar);
+```
+
+管理字符串的内存和大小。
+
+**参数：**
+- `capacity` - 要预留的最小容量
+- `newSize` - 新的字符串长度
+- `fillChar` - 当扩展字符串时用于填充新增位置的字符，默认为 '\0'
+
+**返回：** 无
+
+**复杂度：**
+- `Reserve`：最坏 O(n)，仅在需要扩展容量时复制数据
+- `Resize`：O(n)，当 newSize > Length 时可能需要扩展
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hi");
+
+    // Reserve - 预分配内存
+    s.Reserve(100);
+    std::cout << "After Reserve(100), Capacity: " << s.Capacity() << std::endl;
+    // 输出: After Reserve(100), Capacity: 100
+
+    // Resize - 缩短字符串
+    s.Resize(1);
+    std::cout << "After Resize(1): " << s.CStr() << std::endl;  // 输出: H
+
+    // Resize - 扩展字符串，用 'X' 填充
+    s.Resize(5, 'X');
+    std::cout << "After Resize(5, 'X'): " << s.CStr() << std::endl;  // 输出: HXXXX
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [Length / Capacity](size.md) - 获取长度和容量
+- [Clear](clear.md) - 清空字符串
--- a/docs/api/containers/string/size.md
+++ b/docs/api/containers/string/size.md
@@ -0,0 +1,44 @@
+# String::Length / Capacity / Empty
+
+```cpp
+SizeType Length() const;
+SizeType Capacity() const;
+bool Empty() const;
+```
+
+获取字符串的长度、容量和判空状态。
+
+**参数：** 无
+
+**返回：**
+- `Length()` - 返回字符串的字符数（不包括终止 null 字符）
+- `Capacity()` - 返回已分配的存储容量
+- `Empty()` - 如果字符串为空则返回 `true`
+
+**复杂度：** 均为 O(1)
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s1;
+    std::cout << "Empty: " << s1.Empty() << std::endl;  // 输出: Empty: 1
+
+    XCEngine::Containers::String s2("Hello");
+    std::cout << "Length: " << s2.Length() << std::endl;      // 输出: Length: 5
+    std::cout << "Capacity: " << s2.Capacity() << std::endl;  // 输出: Capacity: 6 或更大
+
+    s2.Reserve(100);
+    std::cout << "After Reserve(100), Capacity: " << s2.Capacity() << std::endl;  // 输出: 100
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [CStr](cstr.md) - 获取 C 字符串
+- [Reserve / Resize](reserve-resize.md) - 内存管理
--- a/docs/api/containers/string/starts-with.md
+++ b/docs/api/containers/string/starts-with.md
@@ -0,0 +1,39 @@
+# String::StartsWith
+
+```cpp
+bool StartsWith(const String& prefix) const;
+bool StartsWith(const char* prefix) const;
+```
+
+检查字符串是否以指定的前缀开头。
+
+**参数：**
+- `prefix` - 要检查的前缀（String 或 const char*）
+
+**返回：** 如果字符串以指定前缀开头则返回 `true`，否则返回 `false`
+
+**复杂度：** O(n)，其中 n 为前缀长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    std::cout << std::boolalpha;
+    std::cout << s.StartsWith("Hello") << std::endl;                     // 输出: true
+    std::cout << s.StartsWith(XCEngine::Containers::String("Hello")) << std::endl;  // 输出: true
+    std::cout << s.StartsWith("World") << std::endl;                      // 输出: false
+    std::cout << s.StartsWith("") << std::endl;                            // 输出: true
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
+- [EndsWith](ends-with.md) - 检查后缀
+- [Find](find.md) - 查找子串
--- a/docs/api/containers/string/string.md
+++ b/docs/api/containers/string/string.md
@@ -0,0 +1,132 @@
+# String
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class`
+
+**描述**: 动态字符串类，提供 UTF-8 编码的字符串操作。
+
+## 概述
+
+`String` 是一个自定义动态字符串类，提供常见的字符串操作功能，支持拷贝构造、移动构造和多种字符串操作方法。
+
+## 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `SizeType` | `size_t` | 大小类型 |
+
+## 常量
+
+| 常量 | 值 | 描述 |
+|------|-----|------|
+| `static constexpr SizeType npos` | `static_cast<SizeType>(-1)` | 无效位置标识 |
+
+## 公共方法
+
+### 构造/析构
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造字符串实例 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+
+### 连接运算符
+
+| 方法 | 描述 |
+|------|------|
+| [operator+=](operator-plus-assign.md) | 追加字符串/字符 |
+| [operator+](operator-plus.md) | 字符串连接 |
+
+### 比较运算符
+
+| 方法 | 描述 |
+|------|------|
+| [operator==](operator-equal.md) | 判断两个字符串是否相等 |
+| [operator!=](operator-equal.md) | 判断两个字符串是否不相等 |
+
+### 字符串操作
+
+| 方法 | 描述 |
+|------|------|
+| [Substring](substring.md) | 获取子串 |
+| [Trim](trim.md) | 去除首尾空白 |
+| [ToLower/ToUpper](to-lower-upper.md) | 大小写转换 |
+| [Find](find.md) | 查找子串位置 |
+| [StartsWith](starts-with.md) | 检查前缀 |
+| [EndsWith](ends-with.md) | 检查后缀 |
+
+### 元素访问
+
+| 方法 | 描述 |
+|------|------|
+| [CStr](cstr.md) | 获取 C 字符串指针 |
+| [Length/Capacity/Empty](size.md) | 获取尺寸信息 |
+| [operator[]](./operator-subscript.md) | 下标访问 |
+
+### 容量管理
+
+| 方法 | 描述 |
+|------|------|
+| [Clear](clear.md) | 清空字符串 |
+| [Reserve/Resize](reserve-resize.md) | 预留/调整容量 |
+
+## std::hash 特化
+
+```cpp
+namespace std {
+    template<>
+    struct hash<XCEngine::Containers::String> {
+        size_t operator()(const XCEngine::Containers::String& str) const noexcept;
+    };
+}
+```
+
+提供了 `std::hash<String>` 特化，使 `String` 可以作为 unordered_map 或 unordered_set 的键使用。
+
+**实现算法：** DJB hash (Daniel J. Bernstein hash)
+
+**算法细节：**
+- 初始值：5381
+- 对每个字符：`hash = hash * 33 + c`（等价于 `(hash << 5) + hash + c`）
+
+**示例：**
+```cpp
+#include <XCEngine/Containers/String.h>
+#include <unordered_map>
+
+int main() {
+    std::unordered_map<XCEngine::Containers::String, int> map;
+    map["key1"] = 100;
+    map["key2"] = 200;
+    return 0;
+}
+```
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/String.h>
+
+// 基本用法
+Containers::String str = "Hello";
+str += ", World!";
+
+// 字符串操作
+Containers::String sub = str.Substring(0, 5);  // "Hello"
+bool hasPrefix = str.StartsWith("Hello");
+bool hasSuffix = str.EndsWith("!");
+
+// 查找
+SizeType pos = str.Find("World");  // 返回 7
+
+// 转换
+Containers::String upper = str.ToUpper();
+Containers::String lower = str.ToLower();
+```
+
+## 相关文档
+
+- [Array](../array/array.md) - 动态数组
+- [HashMap](../hashmap/hashmap.md) - 哈希表
--- a/docs/api/containers/string/substring.md
+++ b/docs/api/containers/string/substring.md
@@ -0,0 +1,43 @@
+# String::Substring
+
+```cpp
+String Substring(SizeType pos, SizeType len = npos) const;
+```
+
+返回从位置 `pos` 开始、长度为 `len` 的子字符串。如果 `len` 省略或为 `npos`，则返回从 `pos` 到字符串末尾的所有字符。
+
+**参数：**
+- `pos` - 子字符串的起始位置（从 0 开始）
+- `len` - 子字符串的长度，默认为 `npos`（即到字符串末尾）
+
+**返回：** 新的 String 对象，包含指定的子字符串
+
+**复杂度：** O(n)，其中 n 为子字符串的长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World");
+
+    XCEngine::Containers::String sub1 = s.Substring(6);        // 从位置6到末尾
+    std::cout << sub1.CStr() << std::endl;  // 输出: World
+
+    XCEngine::Containers::String sub2 = s.Substring(6, 5);      // 从位置6开始，长度5
+    std::cout << sub2.CStr() << std::endl;  // 输出: World
+
+    XCEngine::Containers::String sub3 = s.Substring(0, 5);      // 从位置0开始，长度5
+    std::cout << sub3.CStr() << std::endl;  // 输出: Hello
+
+    XCEngine::Containers::String sub4 = s.Substring(6, 100);    // len超过剩余长度，自动截断
+    std::cout << sub4.CStr() << std::endl;  // 输出: World
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
--- a/docs/api/containers/string/to-lower-upper.md
+++ b/docs/api/containers/string/to-lower-upper.md
@@ -0,0 +1,36 @@
+# String::ToLower / ToUpper
+
+```cpp
+String ToLower() const;
+String ToUpper() const;
+```
+
+将字符串转换为小写/大写形式，返回一个新的 String 对象，原字符串不变。
+
+**参数：** 无
+
+**返回：** 转换后的新 String 对象
+
+**复杂度：** O(n)，其中 n 为字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("Hello World 123");
+
+    XCEngine::Containers::String lower = s.ToLower();
+    std::cout << lower.CStr() << std::endl;  // 输出: hello world 123
+
+    XCEngine::Containers::String upper = s.ToUpper();
+    std::cout << upper.CStr() << std::endl;  // 输出: HELLO WORLD 123
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览
--- a/docs/api/containers/string/trim.md
+++ b/docs/api/containers/string/trim.md
@@ -0,0 +1,35 @@
+# String::Trim
+
+```cpp
+String Trim() const;
+```
+
+移除字符串两端的空白字符（包括空格、制表符、换行符等 isspace 识别的字符），返回一个新的 String 对象，原字符串不变。
+
+**参数：** 无
+
+**返回：** 去除两端空白后的新 String 对象
+
+**复杂度：** O(n)，其中 n 为字符串长度
+
+**示例：**
+```cpp
+#include "XCEngine/Containers/String.h"
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::String s("   Hello World   ");
+
+    XCEngine::Containers::String trimmed = s.Trim();
+    std::cout << "\"" << trimmed.CStr() << "\"" << std::endl;  // 输出: "Hello World"
+
+    XCEngine::Containers::String s2("\t\n  test  \t\n");
+    std::cout << "\"" << s2.Trim().CStr() << "\"" << std::endl;  // 输出: "test"
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [String 总览](string.md) - 返回类总览