fix: improve doc link navigation and tree display

- Fix link resolution with proper relative/absolute path handling
- Improve link styling with underline decoration
- Hide leaf nodes from tree, only show directories
- Fix log file path for packaged app

docs/api/containers/array/array.md

@@ -0,0 +1,67 @@
+# Array
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class` (template)
+
+**描述**: 模板动态数组容器，提供自动扩容的数组实现。
+
+## 概述
+
+`Array<T>` 是一个模板动态数组容器，提供了类似 `std::vector` 的功能，但针对游戏引擎进行了优化。
+
+## 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Iterator` | `T*` | 迭代器类型 |
+| `ConstIterator` | `const T*` | 常量迭代器类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造数组实例 |
+| [Copy/Move Constructor](copy-move-constructor.md) | 拷贝或移动构造 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+| [operator[]](operator-subscript.md) | 下标访问 |
+| [Data](data.md) | 获取原始数据指针 |
+| [Front/Back](front-back.md) | 获取首/尾元素引用 |
+| [Size/Capacity/Empty](size.md) | 获取尺寸信息 |
+| [Clear](clear.md) | 清空所有元素 |
+| [Reserve](reserve.md) | 预留容量 |
+| [Resize](resize.md) | 调整大小 |
+| [PushBack](pushback.md) | 尾部添加（拷贝/移动） |
+| [EmplaceBack](emplaceback.md) | 就地构造尾部添加 |
+| [PopBack](popback.md) | 尾部移除 |
+| [begin/end](iterator.md) | 获取迭代器 |
+| [SetAllocator](setallocator.md) | 设置内存分配器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/Array.h>
+
+// 基本用法
+XCEngine::Containers::Array<int> arr;
+arr.PushBack(1);
+arr.PushBack(2);
+arr.PushBack(3);
+
+// 使用 initializer_list
+XCEngine::Containers::Array<int> arr2 = {1, 2, 3, 4, 5};
+
+// 迭代
+for (auto& elem : arr) {
+    printf("%d\n", elem);
+}
+
+// 使用 EmplaceBack
+arr.EmplaceBack(4);
+```
+
+## 相关文档
+
+- [HashMap](../hashmap/hashmap.md) - 哈希表容器
+- [Memory 模块](../../memory/memory.md) - 内存分配器

docs/api/containers/array/clear.md

@@ -0,0 +1,36 @@
+# Array::Clear()
+
+```cpp
+void Clear();
+```
+
+清空数组中的所有元素。
+
+**行为：**
+- 调用所有元素的析构函数
+- 将 `Size()` 设为 0
+- **不释放底层内存**，`Capacity()` 保持不变
+
+**线程安全：** ❌ 清空期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {1, 2, 3, 4, 5};
+
+arr.Size();      // 5
+arr.Capacity();  // 8（假设自动扩容到 8）
+
+arr.Clear();
+
+arr.Size();      // 0
+arr.Capacity();  // 8（内存未被释放）
+
+// 可继续添加元素，不会重新分配内存
+arr.PushBack(10);
+arr.PushBack(20);
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/constructor.md

@@ -0,0 +1,44 @@
+# Array::Array()
+
+```cpp
+Array() = default;
+explicit Array(size_t capacity);
+Array(size_t count, const T& value);
+Array(std::initializer_list<T> init);
+```
+
+构造一个 `Array<T>` 实例。
+
+**默认构造**：构造空数组，不分配内存。
+
+**容量构造**：预分配指定容量的内存，但不设置元素数量。适用于已知大致元素数量时减少重新分配。
+
+**数量构造**：创建 `count` 个元素，每个元素都是 `value` 的拷贝。使用拷贝构造，不调用默认构造。
+
+**初始化列表构造**：使用 C++ initializer_list 语法创建数组。
+
+**参数：**
+- `capacity` - 预分配的容量大小
+- `count` - 元素数量
+- `value` - 每个元素的初始值
+- `init` - initializer_list 初始化列表
+
+**示例：**
+
+```cpp
+// 默认构造
+Containers::Array<int> arr1;
+
+// 预分配容量（不设置元素）
+Containers::Array<int> arr2(100);
+
+// 创建 10 个元素，初始值为 42
+Containers::Array<int> arr3(10, 42);
+
+// 使用 initializer_list
+Containers::Array<int> arr4 = {1, 2, 3, 4, 5};
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/copy-move-constructor.md

@@ -0,0 +1,44 @@
+# Array::Array() - 拷贝/移动构造
+
+```cpp
+Array(const Array& other);
+Array(Array&& other) noexcept;
+```
+
+拷贝或移动构造一个新数组。
+
+**拷贝构造：**
+- 分配与 `other` 相同容量的内存
+- 拷贝 `other` 中所有元素
+
+**移动构造：**
+- 接管 `other` 的所有资源（数据指针、容量、大小）
+- 将 `other` 置为空状态（`m_data = nullptr, m_size = 0, m_capacity = 0`）
+- 不拷贝、不移动任何元素数据，性能 O(1)
+
+**参数：**
+- `other` - 源数组
+
+**异常：**
+- 拷贝构造：元素拷贝可能抛出异常
+- 移动构造：`noexcept`，不抛出异常
+
+**线程安全：** ❌ 构造期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr1 = {1, 2, 3};
+
+// 拷贝构造
+Containers::Array<int> arr2(arr1);    // arr2 = {1, 2, 3}
+
+// 移动构造
+Containers::Array<int> arr3(std::move(arr1));
+// arr3 = {1, 2, 3}
+// arr1 现在为空，Size() == 0
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/data.md

@@ -0,0 +1,30 @@
+# Array::Data()
+
+```cpp
+T* Data();
+const T* Data() const;
+```
+
+获取指向底层数组数据的原始指针。
+
+**用途：** 用于与 C 风格 API 或需要直接访问内存的场景（如与 GPU 通信）。
+
+**返回：** 指向底层连续内存块的指针。如果数组为空，返回 `nullptr`。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Containers::Array<float> arr = {1.0f, 2.0f, 3.0f};
+
+float* raw = arr.Data();
+size_t count = arr.Size();
+
+// 可用于与 C API 交互
+// memcpy(dst, arr.Data(), arr.Size() * sizeof(float));
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/destructor.md

@@ -0,0 +1,28 @@
+# Array::~Array()
+
+```cpp
+~Array();
+```
+
+销毁数组，释放所有已分配的元素并释放内存。
+
+**行为：**
+- 调用所有元素的析构函数
+- 释放底层数据缓冲区内存
+
+**注意：** 使用 RAII 模式，无需手动调用析构。
+
+**线程安全：** ❌ 析构期间不可并发访问
+
+**示例：**
+
+```cpp
+{
+    Containers::Array<int> arr = {1, 2, 3};
+    // 使用 arr...
+} // arr 在此自动销毁，析构函数被调用
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/emplaceback.md

@@ -0,0 +1,47 @@
+# Array::EmplaceBack()
+
+```cpp
+template<typename... Args>
+T& EmplaceBack(Args&&... args);
+```
+
+在数组末尾就地构造一个元素，直接在内存中构造，不产生临时对象。
+
+**优势：**
+- 避免拷贝或移动开销
+- 直接在底层缓冲区末尾构造元素
+- 参数完美转发，支持任意构造参数
+
+**参数：**
+- `args` - 转发给 `T` 构造函数的参数包
+
+**返回：** 新构造元素的引用
+
+**复杂度：** 均摊 O(1)
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+struct Vertex {
+    float x, y, z;
+    Vertex(float x_, float y_, float z_) : x(x_), y(y_), z(z_) {}
+};
+
+Containers::Array<Vertex> vertices;
+
+// EmplaceBack 直接构造，不产生临时 Vertex 对象
+vertices.EmplaceBack(1.0f, 2.0f, 3.0f);
+vertices.EmplaceBack(4.0f, 5.0f, 6.0f);
+
+// 对比 PushBack（需要先构造临时对象）
+Vertex v(7.0f, 8.0f, 9.0f);
+vertices.PushBack(v);  // 产生拷贝或移动
+
+// EmplaceBack 更高效，始终优先使用
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/front-back.md

@@ -0,0 +1,38 @@
+# Array::Front() / Back()
+
+```cpp
+T& Front();
+const T& Front() const;
+T& Back();
+const T& Back() const;
+```
+
+获取数组首尾元素的引用。
+
+**Front()：** 返回第一个元素（`index == 0`）的引用。
+
+**Back()：** 返回最后一个元素（`index == Size() - 1`）的引用。
+
+**前置条件：** 数组必须非空，否则行为未定义。
+
+**返回：** 首/尾元素的引用
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 访问期间不可并发修改
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30};
+
+int& first = arr.Front();   // first == 10
+int& last = arr.Back();     // last == 30
+
+arr.Front() = 5;            // arr 现在是 {5, 20, 30}
+arr.Back() = 100;           // arr 现在是 {5, 20, 100}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/iterator.md

@@ -0,0 +1,45 @@
+# Array::begin() / end()
+
+```cpp
+Iterator begin();
+Iterator end();
+ConstIterator begin() const;
+ConstIterator end() const;
+```
+
+获取数组的迭代器，用于范围遍历。
+
+**begin()：** 返回指向第一个元素的迭代器。如果数组为空，返回值等于 `end()`。
+
+**end()：** 返回指向"最后一个元素之后"位置的迭代器（哨兵）。这是一个越界位置，不可解引用。
+
+**迭代器类型：** `Iterator = T*`（原始指针），因此支持指针算术运算。
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 迭代期间不可并发修改数组
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30, 40, 50};
+
+// 范围 for 循环（推荐）
+for (int val : arr) {
+    printf("%d\n", val);
+}
+
+// 手动迭代器
+for (auto it = arr.begin(); it != arr.end(); ++it) {
+    printf("%d\n", *it);
+}
+
+// 指针算术（因为迭代器就是指针）
+int* ptr = arr.begin();
+ptr += 2;  // 指向第三个元素
+*ptr;       // 30
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/operator-assign.md

@@ -0,0 +1,44 @@
+# Array::operator=
+
+```cpp
+Array& operator=(const Array& other);
+Array& operator=(Array&& other) noexcept;
+```
+
+赋值运算符，用另一个数组的内容替换当前数组的内容。
+
+**拷贝赋值（`=`）：**
+- 先销毁当前所有元素
+- 分配与 `other` 相同大小的内存
+- 拷贝 `other` 中所有元素
+
+**移动赋值（`=`）：**
+- 先销毁当前所有元素
+- 接管 `other` 的所有资源（数据指针、容量）
+- 将 `other` 置为空状态
+
+**参数：**
+- `other` - 源数组
+
+**返回：** 引用自身（`*this`）
+
+**异常：**
+- 拷贝赋值：`other` 元素拷贝可能抛出异常
+
+**线程安全：** ❌ 赋值期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr1 = {1, 2, 3};
+Containers::Array<int> arr2;
+
+arr2 = arr1;      // 拷贝赋值，arr2 现在是 {1, 2, 3}
+
+Containers::Array<int> arr3 = {4, 5};
+arr2 = std::move(arr3); // 移动赋值，arr2 现在是 {4, 5}，arr3 为空
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/operator-subscript.md

@@ -0,0 +1,39 @@
+# Array::operator[]
+
+```cpp
+T& operator[](size_t index);
+const T& operator[](size_t index) const;
+```
+
+按下标访问数组元素，不进行边界检查。
+
+**行为：**
+- 返回指定索引处元素的引用
+- 不进行下标越界检查，性能最优
+- 可用于读取和修改元素（非常量版本）
+
+**参数：**
+- `index` - 元素下标，从 0 开始
+
+**返回：** 元素的引用（常量版本返回常量引用）
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 访问元素期间不可并发修改
+
+**注意：** 不会进行边界检查。如果 `index >= Size()`，行为未定义。如需边界检查，请使用 `At()` 方法（如果存在）或自行检查。
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30};
+
+int first = arr[0];     // first == 10
+int last = arr[2];       // last == 30
+
+arr[1] = 25;            // arr 现在是 {10, 25, 30}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/popback.md

@@ -0,0 +1,38 @@
+# Array::PopBack()
+
+```cpp
+void PopBack();
+```
+
+移除数组末尾的元素，并调用其析构函数。
+
+**前置条件：** 数组必须非空（`Size() > 0`）。如果数组为空，行为未定义。
+
+**行为：**
+- 将 `Size()` 减 1
+- 调用被移除元素的析构函数
+- **不释放底层内存**
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30, 40, 50};
+
+arr.Size();  // 5
+
+arr.PopBack();  // 移除 50
+
+arr.Size();  // 4
+// arr = {10, 20, 30, 40}
+
+arr.PopBack();
+arr.PopBack();
+// arr = {10, 20}
+// Capacity() 仍为之前的值（如 8）
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/pushback.md

@@ -0,0 +1,43 @@
+# Array::PushBack()
+
+```cpp
+void PushBack(const T& value);
+void PushBack(T&& value);
+```
+
+在数组末尾添加一个元素。
+
+**拷贝版本（`const T&`）：**
+- 如果容量不足（`Size() >= Capacity()`），先扩容（容量翻倍）
+- 在末尾位置拷贝构造 `value`
+
+**移动版本（`T&&`）：**
+- 行为同拷贝版本，但使用移动构造
+- 适用于临时对象或右值，避免拷贝开销
+
+**参数：**
+- `value` - 要添加的元素（拷贝或移动）
+
+**复杂度：** 均摊 O(1)。每次添加的摊销成本为常数，因为扩容是翻倍策略。
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<std::string> arr;
+
+// 拷贝添加
+std::string s = "hello";
+arr.PushBack(s);           // s 被拷贝
+
+// 移动添加（更高效）
+arr.PushBack(std::string("world"));  // 直接移动构造
+
+// 临时对象会被隐式移动
+arr.PushBack("temporary"); // 字符串字面量构造后移动
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/reserve.md

@@ -0,0 +1,39 @@
+# Array::Reserve()
+
+```cpp
+void Reserve(size_t capacity);
+```
+
+预分配底层内存容量，确保能容纳至少 `capacity` 个元素而不重新分配。
+
+**行为：**
+- 如果 `capacity > Capacity()`，分配新的内存（容量翻倍策略）
+- 如果 `capacity <= Capacity()`，什么都不做
+- 不改变 `Size()`
+
+**参数：**
+- `capacity` - 目标容量
+
+**用途：** 当已知大致元素数量时，提前分配可以避免多次重新分配带来的性能开销和迭代器失效。
+
+**复杂度：** O(n)，其中 n 为当前元素数量（需要拷贝现有元素到新内存）
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr;
+
+// 预分配 1000 个元素的容量
+arr.Reserve(1000);
+
+// 之后添加 500 个元素不会触发重新分配
+for (int i = 0; i < 500; ++i) {
+    arr.PushBack(i);
+}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/resize.md

@@ -0,0 +1,46 @@
+# Array::Resize()
+
+```cpp
+void Resize(size_t newSize);
+void Resize(size_t newSize, const T& value);
+```
+
+调整数组大小。
+
+**Resize(newSize)：**
+- 如果 `newSize > Size()`：在末尾构造 `newSize - Size()` 个默认构造的元素
+- 如果 `newSize < Size()`：销毁末尾多出的元素
+- 如果 `newSize == Size()`：什么都不做
+
+**Resize(newSize, value)：**
+- 行为同上述，但扩展时使用 `value` 拷贝构造新元素，而非默认构造
+
+**参数：**
+- `newSize` - 新的元素数量
+- `value` - 扩展时用作填充值的元素
+
+**复杂度：** O(n)，涉及元素构造/析构和可能的内存重新分配
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {1, 2, 3};
+
+// 扩展到 5 个元素，新元素默认构造为 0
+arr.Resize(5);
+// arr = {1, 2, 3, 0, 0}
+
+// 缩减到 2 个元素
+arr.Resize(2);
+// arr = {1, 2}
+
+// 扩展到 4 个，填充为 -1
+arr.Resize(4, -1);
+// arr = {1, 2, -1, -1}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/setallocator.md

@@ -0,0 +1,38 @@
+# Array::SetAllocator()
+
+```cpp
+void SetAllocator(Memory::IAllocator* allocator);
+```
+
+设置数组使用的内存分配器。
+
+**用途：** 允许自定义内存分配策略，如使用对象池、固定大小分配器或调试分配器。
+
+**参数：**
+- `allocator` - 指向 `Memory::IAllocator` 接口的指针。如果为 `nullptr`，使用默认 `::operator new/delete`。
+
+**注意：**
+- 如果数组已有元素，设置新的分配器后，**不会**迁移现有元素
+- 仅影响后续的内存分配操作
+- 通常在构造后立即调用，或在数组为空时调用
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+// 使用线性分配器（适合帧分配）
+auto* linear = new Memory::LinearAllocator(1024 * 1024);
+
+Containers::Array<int> arr;
+arr.SetAllocator(linear);
+
+// 使用对象池分配器
+auto* pool = new Memory::PoolAllocator(sizeof(MyObject), 100);
+Containers::Array<MyObject> objects;
+objects.SetAllocator(pool);
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/size.md

@@ -0,0 +1,47 @@
+# Array::Size() / Capacity() / Empty()
+
+```cpp
+size_t Size() const;
+size_t Capacity() const;
+bool Empty() const;
+```
+
+获取数组的尺寸信息。
+
+**Size()：** 返回数组中的实际元素数量。
+
+**Capacity()：** 返回底层内存缓冲区能容纳的元素数量，不一定等于 `Size()`。
+
+**Empty()：** 返回数组是否为空（`Size() == 0`）。等价于 `Size() == 0`，但更语义化。
+
+**返回：**
+- `Size()` - 元素数量
+- `Capacity()` - 底层缓冲区容量
+- `Empty()` - 是否为空
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr;
+
+arr.Size();      // 0
+arr.Capacity();  // 0
+arr.Empty();     // true
+
+arr.PushBack(1);
+arr.PushBack(2);
+
+arr.Size();      // 2
+arr.Capacity();  // 4（自动扩容）
+arr.Empty();     // false
+
+arr.Reserve(100);
+arr.Size();      // 2（元素数量不变）
+arr.Capacity();  // 100（容量增加）
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/containers.md

@@ -0,0 +1,57 @@
+# Containers 容器模块概览
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `module`
+
+**描述**: XCEngine 的容器模块，提供常用的数据结构实现。
+
+## 概述
+
+Containers 模块提供了图形引擎常用的数据结构，包括动态数组、字符串和哈希表。这些容器都使用自定义内存分配器接口，支持内存跟踪和优化。
+
+## 模块内容
+
+### 容器类
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Array](array/array.md) | `Array.h` | 模板动态数组，支持自动扩容 |
+| [String](string/string.md) | `String.h` | 动态字符串类 |
+| [HashMap](hashmap/hashmap.md) | `HashMap.h` | 模板哈希表 |
+
+## 设计特点
+
+1. **自定义内存分配器支持** - 所有容器都支持通过 `IAllocator` 接口分配内存
+2. **迭代器支持** - Array 和 HashMap 都提供 STL 风格的迭代器
+3. **移动语义** - 完整支持 C++11 移动语义
+4. **异常安全** - 内存分配失败时提供良好的错误处理
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/Array.h>
+#include <XCEngine/Containers/String.h>
+#include <XCEngine/Containers/HashMap.h>
+
+// 使用 Array
+XCEngine::Containers::Array<int> arr;
+arr.PushBack(1);
+arr.PushBack(2);
+arr.PushBack(3);
+
+// 使用 String
+XCEngine::Containers::String str;
+str = "Hello, ";
+str += "World!";
+
+// 使用 HashMap
+XCEngine::Containers::HashMap<XCEngine::Containers::String, int> map;
+map.Insert("key1", 100);
+map.Insert("key2", 200);
+int* value = map.Find("key1");
+```
+
+## 相关文档
+
+- [Memory 模块](../memory/memory.md) - 内存分配器接口

docs/api/containers/hashmap/clear.md

@@ -0,0 +1,34 @@
+# HashMap::Clear
+
+```cpp
+void Clear();
+```
+
+清空哈希表中的所有元素，将元素数量置为 0。桶的数量保持不变。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(m_bucketCount)，需要清空所有桶
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+std::cout << "Size before clear: " << map.Size() << std::endl; // 输出 3
+
+map.Clear();
+
+std::cout << "Size after clear: " << map.Size() << std::endl; // 输出 0
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes"
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Erase](erase.md) - 删除单个元素

docs/api/containers/hashmap/constructor.md

@@ -0,0 +1,31 @@
+# HashMap::HashMap
+
+```cpp
+HashMap();
+explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr);
+```
+
+构造哈希表实例。
+
+**参数：**
+- `bucketCount` - 初始桶的数量，默认为 16。若传入 0，则自动调整为 16。
+- `allocator` - 内存分配器指针，默认为 `nullptr`（使用默认分配器）。
+
+**返回：** 无
+
+**复杂度：** O(bucketCount)，需要初始化所有桶
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map1;
+
+XCEngine::Containers::HashMap<int, const char*> map2(32);
+
+auto customAllocator = XCEngine::Memory::GetDefaultAllocator();
+XCEngine::Containers::HashMap<int, const char*> map3(64, customAllocator);
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

docs/api/containers/hashmap/contains.md

@@ -0,0 +1,35 @@
+# HashMap::Contains
+
+```cpp
+bool Contains(const Key& key) const;
+```
+
+检查哈希表中是否包含指定的键。
+
+**参数：**
+- `key` - 要检查的键
+
+**返回：** 如果键存在返回 `true`，否则返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+if (map.Contains(1)) {
+    std::cout << "Key 1 exists" << std::endl; // 输出 "Key 1 exists"
+}
+
+if (!map.Contains(99)) {
+    std::cout << "Key 99 does not exist" << std::endl; // 输出 "Key 99 does not exist"
+}
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Find](find.md) - 查找键对应的值

docs/api/containers/hashmap/copy-move.md

@@ -0,0 +1,34 @@
+# HashMap::Copy/Move 构造
+
+```cpp
+HashMap(const HashMap& other);
+HashMap(HashMap&& other) noexcept;
+```
+
+拷贝构造和移动构造。
+
+**参数：**
+- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用）
+
+**返回：** 无（构造函数）
+
+**复杂度：**
+- 拷贝构造：O(m_bucketCount + other.m_size)
+- 移动构造：O(m_bucketCount)，移动构造需要遍历所有桶以重新建立桶的指针关系
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map1;
+map1.Insert(1, "hello");
+map1.Insert(2, "world");
+
+XCEngine::Containers::HashMap<int, std::string> map2(map1); // 拷贝构造
+
+XCEngine::Containers::HashMap<int, std::string> map3(std::move(map1)); // 移动构造，map1 在此调用后状态不确定
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [operator=](operator-assign.md) - 赋值运算符

docs/api/containers/hashmap/destructor.md

@@ -0,0 +1,27 @@
+# HashMap::~HashMap
+
+```cpp
+~HashMap();
+```
+
+析构函数，清空所有元素并释放资源。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)，需要清空所有桶中的元素
+
+**示例：**
+
+```cpp
+{
+    XCEngine::Containers::HashMap<int, std::string> map;
+    map.Insert(1, "hello");
+    map.Insert(2, "world");
+} // map 在此自动析构，所有资源被正确释放
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

docs/api/containers/hashmap/erase.md

@@ -0,0 +1,37 @@
+# HashMap::Erase
+
+```cpp
+bool Erase(const Key& key);
+```
+
+删除指定键对应的元素。
+
+**参数：**
+- `key` - 要删除的键
+
+**返回：** 如果元素被删除返回 `true`，如果键不存在返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+bool erased = map.Erase(2); // 返回 true
+
+if (!map.Contains(2)) {
+    std::cout << "Key 2 removed" << std::endl; // 输出 "Key 2 removed"
+}
+
+bool notErased = map.Erase(99); // 返回 false，键不存在
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Insert](insert.md) - 插入键值对
+- [Clear](clear.md) - 清空所有元素

docs/api/containers/hashmap/find.md

@@ -0,0 +1,39 @@
+# HashMap::Find
+
+```cpp
+Value* Find(const Key& key);
+const Value* Find(const Key& key) const;
+```
+
+根据键查找对应的值指针。
+
+**参数：**
+- `key` - 要查找的键
+
+**返回：** 如果找到，返回指向值的指针；否则返回 `nullptr`。
+
+**复杂度：** O(1) 平均，最坏 O(n)（同一桶中有多个键发生哈希冲突）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+const char* value1 = map.Find(1);
+if (value1) {
+    std::cout << "Found: " << value1 << std::endl; // 输出 "Found: one"
+}
+
+const char* value2 = map.Find(99);
+if (!value2) {
+    std::cout << "Not found" << std::endl; // 输出 "Not found"
+}
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Contains](contains.md) - 检查是否包含键
+- [operator[]](./operator-subscript.md) - 下标访问

docs/api/containers/hashmap/hashmap.md

@@ -0,0 +1,80 @@
+# HashMap
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class` (template)
+
+**描述**: 模板哈希表容器，提供键值对存储和快速查找。
+
+## 概述
+
+`HashMap<Key, Value>` 是一个模板哈希表容器，使用动态数组作为桶来解决哈希冲突，支持键值对的插入、查找和删除操作。
+
+## 公共类型
+
+### Pair
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `first` | `Key` | 键 |
+| `second` | `Value` | 值 |
+
+### 迭代器
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Iterator` | `typename Array<Pair>::Iterator` | 迭代器类型 |
+| `ConstIterator` | `typename Array<Pair>::ConstIterator` | 常量迭代器类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造哈希表实例 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+| [Copy/Move](copy-move.md) | 拷贝/移动构造 |
+| [operator[]](operator-subscript.md) | 下标访问（不存在时插入） |
+| [Find](find.md) | 查找键对应的值指针 |
+| [Contains](contains.md) | 检查是否包含键 |
+| [Insert](insert.md) | 插入键值对 |
+| [Erase](erase.md) | 删除键对应的元素 |
+| [Clear](clear.md) | 清空所有元素 |
+| [Size/Empty](size.md) | 获取元素数量 |
+| [begin/end](iterator.md) | 获取迭代器 |
+| [SetAllocator](setallocator.md) | 设置内存分配器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/HashMap.h>
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::HashMap<int, const char*> map;
+
+    map.Insert(1, "one");
+    map.Insert(2, "two");
+    map.Insert(3, "three");
+
+    if (const char* value = map.Find(1)) {
+        std::cout << "Key 1: " << value << std::endl;
+    }
+
+    std::cout << "Size: " << map.Size() << std::endl;
+
+    for (auto it = map.begin(); it != map.end(); ++it) {
+        std::cout << it->first << " -> " << it->second << std::endl;
+    }
+
+    map.Erase(2);
+    std::cout << "Contains 2: " << (map.Contains(2) ? "yes" : "no") << std::endl;
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Array](../array/array.md) - 动态数组
+- [Memory 模块](../../memory/memory.md) - 内存分配器

docs/api/containers/hashmap/insert.md

@@ -0,0 +1,38 @@
+# HashMap::Insert
+
+```cpp
+bool Insert(const Key& key, const Value& value);
+bool Insert(const Key& key, Value&& value);
+bool Insert(Pair&& pair);
+```
+
+插入键值对。如果键已存在，则更新其值并返回 `false`；否则插入新元素并返回 `true`。
+
+**参数：**
+- `key` - 要插入的键
+- `value` - 要插入的值（const 版本为拷贝，&& 版本为移动）
+- `pair` - 包含键值对的 `Pair` 结构（右值）
+
+**返回：** 如果插入成功（键不存在）返回 `true`，如果键已存在（更新值）返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)（包括可能的 rehash）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map;
+
+bool inserted1 = map.Insert(1, "one");   // 返回 true
+bool inserted2 = map.Insert(1, "ONE");   // 返回 false，更新现有值
+
+bool inserted3 = map.Insert(2, std::string("two")); // 移动语义版本
+
+XCEngine::Containers::HashMap<int, std::string>::Pair p{3, "three"};
+bool inserted4 = map.Insert(std::move(p)); // Pair 移动版本
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [operator[]](./operator-subscript.md) - 下标访问（总是插入）
+- [Erase](erase.md) - 删除键对应的元素

docs/api/containers/hashmap/iterator.md

@@ -0,0 +1,34 @@
+# HashMap::begin / end
+
+```cpp
+Iterator begin();
+Iterator end();
+ConstIterator begin() const;
+ConstIterator end() const;
+```
+
+获取哈希表的迭代器。迭代器遍历所有桶中的元素。
+
+**参数：** 无
+
+**返回：** 返回指向第一个元素和末尾（最后一个元素之后）位置的迭代器。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+for (auto it = map.begin(); it != map.end(); ++it) {
+    std::cout << it->first << " -> " << it->second << std::endl;
+}
+// 输出顺序不确定，取决于哈希桶的内部布局
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

docs/api/containers/hashmap/operator-assign.md

@@ -0,0 +1,36 @@
+# HashMap::operator=
+
+```cpp
+HashMap& operator=(const HashMap& other);
+HashMap& operator=(HashMap&& other) noexcept;
+```
+
+赋值运算符，用另一个 HashMap 的内容替换当前内容。
+
+**参数：**
+- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用）
+
+**返回：** 对当前对象的引用 (`*this`)
+
+**复杂度：**
+- 拷贝赋值：O(m_bucketCount + other.m_size)
+- 移动赋值：O(m_size)，需要先清空当前内容
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map1;
+map1.Insert(1, "one");
+map1.Insert(2, "two");
+
+XCEngine::Containers::HashMap<int, const char*> map2;
+map2 = map1; // 拷贝赋值
+
+XCEngine::Containers::HashMap<int, const char*> map3;
+map3 = std::move(map1); // 移动赋值，map1 在此调用后状态不确定
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Copy/Move](copy-move.md) - 拷贝/移动构造

docs/api/containers/hashmap/operator-subscript.md

@@ -0,0 +1,33 @@
+# HashMap::operator[]
+
+```cpp
+Value& operator[](const Key& key);
+```
+
+按下标访问键对应的值。如果键不存在，则插入一个默认构造的值并返回引用。
+
+**参数：**
+- `key` - 要访问的键
+
+**返回：** 对应值的引用。如果键不存在，则返回一个默认构造的 `Value` 的引用。
+
+**复杂度：** O(1) 平均，最坏 O(n)（发生 rehash 时）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map;
+
+map[1] = "one";          // 插入键 1，值 "one"
+map[2] = "two";          // 插入键 2，值 "two"
+
+std::string& value = map[1]; // 获取键 1 对应的值，结果为 "one"
+
+map[3];                  // 插入键 3，值为 std::string 的默认构造值
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Find](find.md) - 查找键对应的值（不插入）
+- [Insert](insert.md) - 插入键值对（不覆盖已存在的键）

docs/api/containers/hashmap/setallocator.md

@@ -0,0 +1,28 @@
+# HashMap::SetAllocator
+
+```cpp
+void SetAllocator(Memory::IAllocator* allocator);
+```
+
+设置哈希表的内存分配器。
+
+**参数：**
+- `allocator` - 内存分配器指针，可以为 `nullptr`（使用默认分配器）
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+
+// 设置自定义分配器（如果使用内存分配器接口）
+// map.SetAllocator(customAllocator);
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Memory 模块](../../memory/memory.md) - 内存分配器

docs/api/containers/hashmap/size.md

@@ -0,0 +1,35 @@
+# HashMap::Size / Empty
+
+```cpp
+size_t Size() const;
+bool Empty() const;
+```
+
+获取哈希表的元素数量或判断是否为空。
+
+**参数：** 无
+
+**返回：**
+- `Size()` - 返回元素数量
+- `Empty()` - 容器为空返回 `true`，否则返回 `false`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes"
+std::cout << "Size: " << map.Size() << std::endl; // 输出 0
+
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "no"
+std::cout << "Size: " << map.Size() << std::endl; // 输出 2
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览

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) - 内存管理

docs/api/containers/string/constructor.md

@@ -0,0 +1,48 @@
+# String::String
+
+```cpp
+String();
+String(const char* str);
+String(const char* str, SizeType len);
+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) - 返回类总览

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) - 获取长度

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) - 返回类总览

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) - 查找子串

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) - 检查后缀

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) - 返回类总览

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) - 返回类总览

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) - 返回类总览

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) - 追加操作

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) - 获取长度

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) - 清空字符串

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) - 内存管理

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) - 查找子串

docs/api/containers/string/string.md

@@ -0,0 +1,105 @@
+# 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+](../string/operator-plus.md) | 字符串连接 |
+| [operator==](../string/operator-equal.md) | 判断两个字符串是否相等 |
+| [operator!=](../string/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) - 哈希表

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) - 返回类总览

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) - 返回类总览

docs/api/containers/string/trim.md

@@ -0,0 +1,35 @@
+# String::Trim
+
+```cpp
+String Trim() const;
+```
+
+移除字符串两端的空白字符（空格、制表符、换行符、回车符），返回一个新的 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) - 返回类总览