docs: update containers API docs

docs/api/containers/array/array.md

@@ -4,6 +4,8 @@
 
 **类型**: `class` (template)
 
+**头文件**: `XCEngine/Containers/Array.h`
+
 **描述**: 模板动态数组容器，提供自动扩容的数组实现。
 
 ## 概述
@@ -35,7 +37,7 @@
 | [PushBack](pushback.md) | 尾部添加（拷贝/移动） |
 | [EmplaceBack](emplaceback.md) | 就地构造尾部添加 |
 | [PopBack](popback.md) | 尾部移除 |
-| [begin/end](iterator.md) | 获取迭代器 |
+| [begin/end](begin-end.md) | 获取迭代器 |
 | [SetAllocator](setallocator.md) | 设置内存分配器 |
 
 ## 使用示例

docs/api/containers/array/begin-end.md

@@ -22,7 +22,9 @@ ConstIterator end() const;
 **示例：**
 
 ```cpp
-Containers::Array<int> arr = {10, 20, 30, 40, 50};
+#include <XCEngine/Containers/Array.h>
+
+XCEngine::Containers::Array<int> arr = {10, 20, 30, 40, 50};
 
 // 范围 for 循环（推荐）
 for (int val : arr) {
@@ -38,8 +40,13 @@ for (auto it = arr.begin(); it != arr.end(); ++it) {
 int* ptr = arr.begin();
 ptr += 2;  // 指向第三个元素
 *ptr;       // 30
+
+// 常量迭代器
+for (const auto& val : arr) {
+    printf("%d\n", val);
+}
 ```
 
 ## 相关文档
 
-- [Array 总览](array.md) - 返回类总览
+- [Array 总览](array.md) - 返回类总览

docs/api/containers/array/clear.md

@@ -16,7 +16,7 @@ void Clear();
 **示例：**
 
 ```cpp
-Containers::Array<int> arr = {1, 2, 3, 4, 5};
+XCEngine::Containers::Array<int> arr = {1, 2, 3, 4, 5};
 
 arr.Size();      // 5
 arr.Capacity();  // 8（假设自动扩容到 8）

docs/api/containers/array/constructor.md

@@ -7,11 +7,11 @@ Array(size_t count, const T& value);
 Array(std::initializer_list<T> init);
 ```
 
-构造一个 `Array<T>` 实例。
+构造一个 `template<typename T> XCEngine::Containers::Array<T>` 实例。
 
-**默认构造**：构造空数组，不分配内存。
+**默认构造**：构造空数组，不分配内存。数组初始为空，容量为0。
 
-**容量构造**：预分配指定容量的内存，但不设置元素数量。适用于已知大致元素数量时减少重新分配。
+**容量构造（explicit）**：预分配指定容量的内存，但不设置元素数量。适用于已知大致元素数量时减少重新分配。
 
 **数量构造**：创建 `count` 个元素，每个元素都是 `value` 的拷贝。使用拷贝构造，不调用默认构造。
 
@@ -23,20 +23,26 @@ Array(std::initializer_list<T> init);
 - `value` - 每个元素的初始值
 - `init` - initializer_list 初始化列表
 
+**注意：** `Array(size_t capacity)` 是 explicit 的，防止隐式转换。
+
 **示例：**
 
 ```cpp
+#include <XCEngine/Containers/Array.h>
+
+using namespace XCEngine::Containers;
+
 // 默认构造
-Containers::Array<int> arr1;
+Array<int> arr1;
 
 // 预分配容量（不设置元素）
-Containers::Array<int> arr2(100);
+Array<int> arr2(100);
 
 // 创建 10 个元素，初始值为 42
-Containers::Array<int> arr3(10, 42);
+Array<int> arr3(10, 42);
 
 // 使用 initializer_list
-Containers::Array<int> arr4 = {1, 2, 3, 4, 5};
+Array<int> arr4 = {1, 2, 3, 4, 5};
 ```
 
 ## 相关文档

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

@@ -28,13 +28,13 @@ Array(Array&& other) noexcept;
 **示例：**
 
 ```cpp
-Containers::Array<int> arr1 = {1, 2, 3};
+XCEngine::Containers::Array<int> arr1 = {1, 2, 3};
 
 // 拷贝构造
-Containers::Array<int> arr2(arr1);    // arr2 = {1, 2, 3}
+XCEngine::Containers::Array<int> arr2(arr1);    // arr2 = {1, 2, 3}
 
 // 移动构造
-Containers::Array<int> arr3(std::move(arr1));
+XCEngine::Containers::Array<int> arr3(std::move(arr1));
 // arr3 = {1, 2, 3}
 // arr1 现在为空，Size() == 0
 ```

docs/api/containers/array/data.md

@@ -16,7 +16,7 @@ const T* Data() const;
 **示例：**
 
 ```cpp
-Containers::Array<float> arr = {1.0f, 2.0f, 3.0f};
+XCEngine::Containers::Array<float> arr = {1.0f, 2.0f, 3.0f};
 
 float* raw = arr.Data();
 size_t count = arr.Size();

docs/api/containers/array/destructor.md

@@ -18,7 +18,7 @@
 
 ```cpp
 {
-    Containers::Array<int> arr = {1, 2, 3};
+    XCEngine::Containers::Array<int> arr = {1, 2, 3};
     // 使用 arr...
 } // arr 在此自动销毁，析构函数被调用
 ```

docs/api/containers/array/emplaceback.md

@@ -7,6 +7,10 @@ T& EmplaceBack(Args&&... args);
 
 在数组末尾就地构造一个元素，直接在内存中构造，不产生临时对象。
 
+**容量管理：**
+- 如果容量不足（`m_size >= m_capacity`），先扩容
+- 当容量为0时，首次扩容至4；之后每次扩容翻倍（即 4 → 8 → 16 → ...）
+
 **优势：**
 - 避免拷贝或移动开销
 - 直接在底层缓冲区末尾构造元素
@@ -29,7 +33,7 @@ struct Vertex {
     Vertex(float x_, float y_, float z_) : x(x_), y(y_), z(z_) {}
 };
 
-Containers::Array<Vertex> vertices;
+XCEngine::Containers::Array<Vertex> vertices;
 
 // EmplaceBack 直接构造，不产生临时 Vertex 对象
 vertices.EmplaceBack(1.0f, 2.0f, 3.0f);

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

@@ -24,7 +24,7 @@ const T& Back() const;
 **示例：**
 
 ```cpp
-Containers::Array<int> arr = {10, 20, 30};
+XCEngine::Containers::Array<int> arr = {10, 20, 30};
 
 int& first = arr.Front();   // first == 10
 int& last = arr.Back();     // last == 30

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

@@ -14,7 +14,7 @@ Array& operator=(Array&& other) noexcept;
 
 **移动赋值（`=`）：**
 - 先销毁当前所有元素
-- 接管 `other` 的所有资源（数据指针、容量）
+- 接管 `other` 的所有资源（数据指针、容量、分配器）
 - 将 `other` 置为空状态
 
 **参数：**
@@ -30,12 +30,12 @@ Array& operator=(Array&& other) noexcept;
 **示例：**
 
 ```cpp
-Containers::Array<int> arr1 = {1, 2, 3};
-Containers::Array<int> arr2;
+XCEngine::Containers::Array<int> arr1 = {1, 2, 3};
+XCEngine::Containers::Array<int> arr2;
 
 arr2 = arr1;      // 拷贝赋值，arr2 现在是 {1, 2, 3}
 
-Containers::Array<int> arr3 = {4, 5};
+XCEngine::Containers::Array<int> arr3 = {4, 5};
 arr2 = std::move(arr3); // 移动赋值，arr2 现在是 {4, 5}，arr3 为空
 ```
 

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

@@ -21,12 +21,12 @@ const T& operator[](size_t index) const;
 
 **线程安全：** ❌ 访问元素期间不可并发修改
 
-**注意：** 不会进行边界检查。如果 `index >= Size()`，行为未定义。如需边界检查，请使用 `At()` 方法（如果存在）或自行检查。
+**注意：** 不会进行边界检查。如果 `index >= Size()`，行为未定义。如需边界检查，请自行先调用 `Empty()` 或检查 `Size()`。
 
 **示例：**
 
 ```cpp
-Containers::Array<int> arr = {10, 20, 30};
+XCEngine::Containers::Array<int> arr = {10, 20, 30};
 
 int first = arr[0];     // first == 10
 int last = arr[2];       // last == 30

docs/api/containers/array/popback.md

@@ -18,7 +18,7 @@ void PopBack();
 **示例：**
 
 ```cpp
-Containers::Array<int> arr = {10, 20, 30, 40, 50};
+XCEngine::Containers::Array<int> arr = {10, 20, 30, 40, 50};
 
 arr.Size();  // 5
 

docs/api/containers/array/pushback.md

@@ -8,7 +8,8 @@ void PushBack(T&& value);
 在数组末尾添加一个元素。
 
 **拷贝版本（`const T&`）：**
-- 如果容量不足（`Size() >= Capacity()`），先扩容（容量翻倍）
+- 如果容量不足（`m_size >= m_capacity`），先扩容
+- 当容量为0时，首次扩容至4；之后每次扩容翻倍（即 4 → 8 → 16 → ...）
 - 在末尾位置拷贝构造 `value`
 
 **移动版本（`T&&`）：**
@@ -25,7 +26,7 @@ void PushBack(T&& value);
 **示例：**
 
 ```cpp
-Containers::Array<std::string> arr;
+XCEngine::Containers::Array<std::string> arr;
 
 // 拷贝添加
 std::string s = "hello";

docs/api/containers/array/reserve.md

@@ -7,7 +7,7 @@ void Reserve(size_t capacity);
 预分配底层内存容量，确保能容纳至少 `capacity` 个元素而不重新分配。
 
 **行为：**
-- 如果 `capacity > Capacity()`，分配新的内存（容量翻倍策略）
+- 如果 `capacity > Capacity()`，分配新内存并拷贝现有元素
 - 如果 `capacity <= Capacity()`，什么都不做
 - 不改变 `Size()`
 
@@ -23,7 +23,7 @@ void Reserve(size_t capacity);
 **示例：**
 
 ```cpp
-Containers::Array<int> arr;
+XCEngine::Containers::Array<int> arr;
 
 // 预分配 1000 个元素的容量
 arr.Reserve(1000);

docs/api/containers/array/resize.md

@@ -26,7 +26,7 @@ void Resize(size_t newSize, const T& value);
 **示例：**
 
 ```cpp
-Containers::Array<int> arr = {1, 2, 3};
+XCEngine::Containers::Array<int> arr = {1, 2, 3};
 
 // 扩展到 5 个元素，新元素默认构造为 0
 arr.Resize(5);

docs/api/containers/array/setallocator.md

@@ -4,33 +4,24 @@
 void SetAllocator(Memory::IAllocator* allocator);
 ```
 
-设置数组使用的内存分配器。
-
-**用途：** 允许自定义内存分配策略，如使用对象池、固定大小分配器或调试分配器。
+设置数组的内存分配器指针（当前实现未使用此分配器）。
 
 **参数：**
-- `allocator` - 指向 `Memory::IAllocator` 接口的指针。如果为 `nullptr`，使用默认 `::operator new/delete`。
+- `allocator` - 指向 `Memory::IAllocator` 接口的指针
 
 **注意：**
+- 此方法仅存储分配器指针，**当前实现未使用该分配器进行内存分配**
+- 所有内存分配仍使用 `::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);
+XCEngine::Containers::Array<int> arr;
+arr.SetAllocator(customAllocator);
 ```
 
 ## 相关文档

docs/api/containers/array/size.md

@@ -24,7 +24,7 @@ bool Empty() const;
 **示例：**
 
 ```cpp
-Containers::Array<int> arr;
+XCEngine::Containers::Array<int> arr;
 
 arr.Size();      // 0
 arr.Capacity();  // 0

docs/api/containers/containers.md

@@ -4,6 +4,8 @@
 
 **类型**: `module`
 
+**头文件**: `XCEngine/Containers/Containers.h`
+
 **描述**: XCEngine 的容器模块，提供常用的数据结构实现。
 
 ## 概述

docs/api/containers/hashmap/clear.md

@@ -10,7 +10,11 @@ void Clear();
 
 **返回：** 无
 
-**复杂度：** O(m_bucketCount)，需要清空所有桶
+**复杂度：** O(bucketCount)，需要清空所有桶
+
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
 
 **示例：**
 

docs/api/containers/hashmap/constructor.md

@@ -15,6 +15,10 @@ explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr);
 
 **复杂度：** O(bucketCount)，需要初始化所有桶
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp
@@ -22,8 +26,7 @@ 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);
+XCEngine::Containers::HashMap<int, const char*> map3(64, nullptr);
 ```
 
 ## 相关文档

docs/api/containers/hashmap/contains.md

@@ -13,6 +13,10 @@ bool Contains(const Key& key) const;
 
 **复杂度：** O(1) 平均，最坏 O(n)
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

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

@@ -16,6 +16,10 @@ HashMap(HashMap&& other) noexcept;
 - 拷贝构造：O(m_bucketCount + other.m_size)
 - 移动构造：O(m_bucketCount)，移动构造需要遍历所有桶以重新建立桶的指针关系
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

docs/api/containers/hashmap/destructor.md

@@ -12,6 +12,10 @@
 
 **复杂度：** O(n)，需要清空所有桶中的元素
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

docs/api/containers/hashmap/erase.md

@@ -11,7 +11,13 @@ bool Erase(const Key& key);
 
 **返回：** 如果元素被删除返回 `true`，如果键不存在返回 `false`。
 
-**复杂度：** O(1) 平均，最坏 O(n)
+**复杂度：** O(1) 平均，最坏 O(n)（同一桶中有多个键发生哈希冲突）
+
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
+**实现备注：** 使用 swap-with-last 策略，将待删除元素与桶内最后一个元素交换，然后 popBack，避免数组元素批量移动。
 
 **示例：**
 

docs/api/containers/hashmap/find.md

@@ -14,6 +14,10 @@ const Value* Find(const Key& key) const;
 
 **复杂度：** O(1) 平均，最坏 O(n)（同一桶中有多个键发生哈希冲突）
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

docs/api/containers/hashmap/hashmap.md

@@ -4,11 +4,22 @@
 
 **类型**: `class` (template)
 
+**头文件**: `XCEngine/Containers/HashMap.h`
+
 **描述**: 模板哈希表容器，提供键值对存储和快速查找。
 
 ## 概述
 
-`HashMap<Key, Value>` 是一个模板哈希表容器，使用动态数组作为桶来解决哈希冲突，支持键值对的插入、查找和删除操作。
+`HashMap<Key, Value>` 是一个模板哈希表容器，使用分离链接法（separate chaining）解决哈希冲突，每个桶是一个动态数组。
+
+## 实现细节
+
+| 参数 | 值 | 描述 |
+|------|-----|------|
+| 默认桶数 | 16 | `DefaultBucketCount` |
+| 负载因子 | 0.75 | 当 `size / bucketCount > 0.75` 时触发扩容 |
+| 扩容策略 | ×2 | 每次扩容桶数翻倍 |
+| Erase 策略 | swap-with-last | 将待删除元素与最后一个元素交换，避免数组元素移动 |
 
 ## 公共类型
 

docs/api/containers/hashmap/insert.md

@@ -17,6 +17,10 @@ bool Insert(Pair&& pair);
 
 **复杂度：** O(1) 平均，最坏 O(n)（包括可能的 rehash）
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

docs/api/containers/hashmap/iterator.md

@@ -15,6 +15,10 @@ ConstIterator end() const;
 
 **复杂度：** O(1)
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

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

@@ -16,6 +16,10 @@ HashMap& operator=(HashMap&& other) noexcept;
 - 拷贝赋值：O(m_bucketCount + other.m_size)
 - 移动赋值：O(m_size)，需要先清空当前内容
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

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

@@ -13,6 +13,10 @@ Value& operator[](const Key& key);
 
 **复杂度：** O(1) 平均，最坏 O(n)（发生 rehash 时）
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

docs/api/containers/hashmap/setallocator.md

@@ -13,6 +13,10 @@ void SetAllocator(Memory::IAllocator* allocator);
 
 **复杂度：** O(1)
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

docs/api/containers/hashmap/size.md

@@ -15,6 +15,10 @@ bool Empty() const;
 
 **复杂度：** O(1)
 
+**线程安全：** ❌ 非线程安全
+
+**异常：** 无
+
 **示例：**
 
 ```cpp

docs/api/containers/string/string.md

@@ -4,6 +4,8 @@
 
 **类型**: `class`
 
+**头文件**: `XCEngine/Containers/String.h`
+
 **描述**: 动态字符串类，提供 UTF-8 编码的字符串操作。
 
 ## 概述
@@ -30,9 +32,9 @@
 | [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) | 判断两个字符串是否不相等 |
+| [operator+](operator-plus.md) | 字符串连接 |
+| [operator==](operator-equal.md) | 判断两个字符串是否相等 |
+| [operator!=](operator-equal.md) | 判断两个字符串是否不相等 |
 | [Substring](substring.md) | 获取子串 |
 | [Trim](trim.md) | 去除首尾空白 |
 | [ToLower/ToUpper](to-lower-upper.md) | 大小写转换 |
@@ -92,7 +94,7 @@ bool hasPrefix = str.StartsWith("Hello");
 bool hasSuffix = str.EndsWith("!");
 
 // 查找
-SizeType pos = str.Find("World");  // 返回 7
+    XCEngine::Containers::String::SizeType pos = str.Find("World");  // 返回 6
 
 // 转换
 Containers::String upper = str.ToUpper();