xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 重组文档目录结构: 每个模块的概述页移动到模块子目录
- 重命名 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 个断裂引用
This commit is contained in:
ssdfasd
2026-03-19 00:22:30 +08:00
parent d0e16962c8
commit dc850d7739
1012 changed files with 26673 additions and 9222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
docs/api/containers/array/array.md Normal file
View File

@@ -0,0 +1,94 @@
# 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>
// 基本用法
Containers::Array<int> arr;
arr.PushBack(1);
arr.PushBack(2);
arr.PushBack(3);
// 使用 initializer_list
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) - 内存分配器

36
docs/api/containers/array/clear.md Normal file
View File

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

44
docs/api/containers/array/constructor.md Normal file
View File

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

44
docs/api/containers/array/copy-move-constructor.md Normal file
View File

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

30
docs/api/containers/array/data.md Normal file
View File

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

28
docs/api/containers/array/destructor.md Normal file
View File

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

47
docs/api/containers/array/emplaceback.md Normal file
View File

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

38
docs/api/containers/array/front-back.md Normal file
View File

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

45
docs/api/containers/array/iterator.md Normal file
View File

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

44
docs/api/containers/array/operator-assign.md Normal file
View File

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

39
docs/api/containers/array/operator-subscript.md Normal file
View File

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

38
docs/api/containers/array/popback.md Normal file
View File

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

43
docs/api/containers/array/pushback.md Normal file
View File

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

39
docs/api/containers/array/reserve.md Normal file
View File

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

46
docs/api/containers/array/resize.md Normal file
View File

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

38
docs/api/containers/array/setallocator.md Normal file
View File

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

47
docs/api/containers/array/size.md Normal file
View File

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

116
docs/api/containers/container-array.md
View File

@@ -1,116 +0,0 @@
# Array
**命名空间**: `XCEngine::Containers`
**类型**: `class` (template)
**描述**: 模板动态数组容器，提供自动扩容的数组实现。
## 概述
`Array<T>` 是一个模板动态数组容器，提供了类似 `std::vector` 的功能，但针对游戏引擎进行了优化。
## 类型别名
| 别名 | 类型 | 描述 |
|------|------|------|
| `Iterator` | `T*` | 迭代器类型 |
| `ConstIterator` | `const T*` | 常量迭代器类型 |
## 公共方法
### 构造/析构
| 方法 | 描述 |
|------|------|
| `Array() = default` | 默认构造函数 |
| `explicit Array(size_t capacity)` | 指定容量的构造函数 |
| `Array(size_t count, const T& value)` | 初始化列表构造函数 |
| `Array(std::initializer_list<T> init)` | initializer_list 构造 |
| `~Array()` | 析构函数 |
### 拷贝/移动构造
| 方法 | 描述 |
|------|------|
| `Array(const Array& other)` | 拷贝构造函数 |
| `Array(Array&& other) noexcept` | 移动构造函数 |
| `Array& operator=(const Array& other)` | 拷贝赋值运算符 |
| `Array& operator=(Array&& other) noexcept` | 移动赋值运算符 |
### 元素访问
| 方法 | 描述 |
|------|------|
| `T& operator[](size_t index)` | 下标访问 |
| `const T& operator[](size_t index) const` | 常量下标访问 |
| `T* Data()` | 获取原始数据指针 |
| `const T* Data() const` | 获取常量数据指针 |
| `T& Front()` | 获取第一个元素 |
| `const T& Front() const` | 获取常量第一个元素 |
| `T& Back()` | 获取最后一个元素 |
| `const T& Back() const` | 获取常量最后一个元素 |
### 容量管理
| 方法 | 描述 |
|------|------|
| `size_t Size() const` | 获取元素数量 |
| `size_t Capacity() const` | 获取容量 |
| `bool Empty() const` | 检查是否为空 |
| `void Clear()` | 清空所有元素 |
| `void Reserve(size_t capacity)` | 预留容量 |
| `void Resize(size_t newSize)` | 调整大小 |
| `void Resize(size_t newSize, const T& value)` | 调整大小并填充默认值 |
### 元素操作
| 方法 | 描述 |
|------|------|
| `void PushBack(const T& value)` | 尾部添加（拷贝） |
| `void PushBack(T&& value)` | 尾部添加（移动） |
| `T& EmplaceBack(Args&&... args)` | 就地构造尾部添加 |
| `void PopBack()` | 尾部移除 |
### 迭代器
| 方法 | 描述 |
|------|------|
| `Iterator begin()` | 获取开始迭代器 |
| `Iterator end()` | 获取结束迭代器 |
| `ConstIterator begin() const` | 获取常量开始迭代器 |
| `ConstIterator end() const` | 获取常量结束迭代器 |
### 内存分配器
| 方法 | 描述 |
|------|------|
| `void SetAllocator(Memory::IAllocator* allocator)` | 设置内存分配器 |
## 使用示例
```cpp
#include <XCEngine/Containers/Array.h>
// 基本用法
Containers::Array<int> arr;
arr.PushBack(1);
arr.PushBack(2);
arr.PushBack(3);
// 使用 initializer_list
Containers::Array<int> arr2 = {1, 2, 3, 4, 5};
// 迭代
for (auto& elem : arr) {
printf("%d\n", elem);
}
// 使用 EmplaceBack
arr.EmplaceBack(4);
```
## 相关文档
- [HashMap](./container-hashmap.md) - 哈希表容器
- [Memory 模块](../memory/memory-overview.md) - 内存分配器

137
docs/api/containers/container-hashmap.md
View File

@@ -1,137 +0,0 @@
# HashMap
**命名空间**: `XCEngine::Containers`
**类型**: `class` (template)
**描述**: 模板哈希表容器，提供键值对存储和快速查找。
## 概述
`HashMap<Key, Value>` 是一个模板哈希表容器，实现了分离链接法的哈希表，支持键值对的插入、查找和删除操作。
## 公共类型
### Pair
| 成员 | 类型 | 描述 |
|------|------|------|
| `first` | `Key` | 键 |
| `second` | `Value` | 值 |
### 迭代器
| 别名 | 类型 | 描述 |
|------|------|------|
| `Iterator` | `typename Array<Pair>::Iterator` | 迭代器类型 |
| `ConstIterator` | `typename Array<Pair>::ConstIterator` | 常量迭代器类型 |
## 公共方法
### 构造/析构
| 方法 | 描述 |
|------|------|
| `HashMap()` | 默认构造（16 个桶） |
| `explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr)` | 指定桶数量和分配器 |
| `~HashMap()` | 析构函数 |
### 拷贝/移动构造
| 方法 | 描述 |
|------|------|
| `HashMap(const HashMap& other)` | 拷贝构造 |
| `HashMap(HashMap&& other) noexcept` | 移动构造 |
| `HashMap& operator=(const HashMap& other)` | 拷贝赋值 |
| `HashMap& operator=(HashMap&& other) noexcept` | 移动赋值 |
### 元素访问
| 方法 | 描述 |
|------|------|
| `Value& operator[](const Key& key)` | 下标访问（不存在时插入） |
### 查找
| 方法 | 描述 |
|------|------|
| `Value* Find(const Key& key)` | 查找键对应的值指针 |
| `const Value* Find(const Key& key) const` | 常量查找 |
| `bool Contains(const Key& key) const` | 检查是否包含键 |
### 插入/删除
| 方法 | 描述 |
|------|------|
| `bool Insert(const Key& key, const Value& value)` | 插入（拷贝值） |
| `bool Insert(const Key& key, Value&& value)` | 插入（移动值） |
| `bool Insert(Pair&& pair)` | 插入（移动键值对） |
| `bool Erase(const Key& key)` | 删除键对应的元素 |
| `void Clear()` | 清空所有元素 |
### 容量
| 方法 | 描述 |
|------|------|
| `size_t Size() const` | 获取元素数量 |
| `bool Empty() const` | 检查是否为空 |
### 迭代器
| 方法 | 描述 |
|------|------|
| `Iterator begin()` | 获取开始迭代器 |
| `Iterator end()` | 获取结束迭代器 |
| `ConstIterator begin() const` | 获取常量开始迭代器 |
| `ConstIterator end() const` | 获取常量结束迭代器 |
### 内存分配器
| 方法 | 描述 |
|------|------|
| `void SetAllocator(Memory::IAllocator* allocator)` | 设置内存分配器 |
## 实现细节
| 常量/成员 | 类型 | 描述 |
|------|------|------|
| `DefaultBucketCount` | `static constexpr size_t` | 默认桶数量（16） |
| `m_loadFactor` | `float` | 负载因子阈值（0.75） |
## 使用示例
```cpp
#include <XCEngine/Containers/HashMap.h>
// 基本用法
Containers::HashMap<Containers::String, int> map;
map.Insert("one", 1);
map.Insert("two", 2);
// 使用下标访问
map["three"] = 3;
// 查找
int* val = map.Find("one");
if (val) {
printf("Found: %d\n", *val);
}
// 使用 Contains
if (map.Contains("two")) {
printf("two exists\n");
}
// 删除
map.Erase("one");
// 迭代
for (auto& pair : map) {
printf("%s: %d\n", pair.first.CStr(), pair.second);
}
```
## 相关文档
- [Array](./container-array.md) - 动态数组
- [Memory 模块](../memory/memory-overview.md) - 内存分配器

132
docs/api/containers/container-string.md
View File

@@ -1,132 +0,0 @@
# String
**命名空间**: `XCEngine::Containers`
**类型**: `class`
**描述**: 动态字符串类，提供 UTF-8 编码的字符串操作。
## 概述
`String` 是一个自定义动态字符串类，提供常见的字符串操作功能，支持拷贝构造、移动构造和多种字符串操作方法。
## 类型别名
| 别名 | 类型 | 描述 |
|------|------|------|
| `SizeType` | `size_t` | 大小类型 |
## 常量
| 常量 | 值 | 描述 |
|------|-----|------|
| `static constexpr SizeType npos` | `static_cast<SizeType>(-1)` | 无效位置标识 |
## 公共方法
### 构造/析构
| 方法 | 描述 |
|------|------|
| `String()` | 默认构造空字符串 |
| `String(const char* str)` | 从 C 字符串构造 |
| `String(const char* str, SizeType len)` | 从指定长度的 C 字符串构造 |
| `String(const String& other)` | 拷贝构造 |
| `String(String&& other) noexcept` | 移动构造 |
| `~String()` | 析构函数 |
### 赋值运算符
| 方法 | 描述 |
|------|------|
| `String& operator=(const String& other)` | 拷贝赋值 |
| `String& operator=(String&& other) noexcept` | 移动赋值 |
| `String& operator=(const char* str)` | C 字符串赋值 |
### 连接运算符
| 方法 | 描述 |
|------|------|
| `String& operator+=(const String& other)` | 追加字符串 |
| `String& operator+=(const char* str)` | 追加 C 字符串 |
| `String& operator+=(char c)` | 追加字符 |
### 字符串操作
| 方法 | 描述 |
|------|------|
| `String Substring(SizeType pos, SizeType len = npos) const` | 获取子串 |
| `String Trim() const` | 去除首尾空白 |
| `String ToLower() const` | 转换为小写 |
| `String ToUpper() const` | 转换为大写 |
| `SizeType Find(const char* str, SizeType pos = 0) const` | 查找子串位置 |
| `bool StartsWith(const String& prefix) const` | 检查是否以指定前缀开头 |
| `bool StartsWith(const char* prefix) const` | 检查是否以指定前缀开头 |
| `bool EndsWith(const String& suffix) const` | 检查是否以指定后缀结尾 |
| `bool EndsWith(const char* suffix) const` | 检查是否以指定后缀结尾 |
### 元素访问
| 方法 | 描述 |
|------|------|
| `const char* CStr() const` | 获取 C 字符串指针 |
| `SizeType Length() const` | 获取字符串长度 |
| `SizeType Capacity() const` | 获取容量 |
| `bool Empty() const` | 检查是否为空 |
| `char& operator[](SizeType index)` | 下标访问 |
| `const char& operator[](SizeType index) const` | 常量下标访问 |
### 容量管理
| 方法 | 描述 |
|------|------|
| `void Clear()` | 清空字符串 |
| `void Reserve(SizeType capacity)` | 预留容量 |
| `void Resize(SizeType newSize)` | 调整大小 |
| `void Resize(SizeType newSize, char fillChar)` | 调整大小并填充 |
## 友元函数
| 函数 | 描述 |
|------|------|
| `operator+(const String& lhs, const String& rhs)` | 字符串连接 |
| `operator==(const String& lhs, const String& rhs)` | 相等比较 |
| `operator!=(const String& lhs, const String& rhs)` | 不等比较 |
## std::hash 特化
```cpp
namespace std {
template<>
struct hash<XCEngine::Containers::String> {
size_t operator()(const XCEngine::Containers::String& str) const noexcept;
};
}
```
## 使用示例
```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](./container-array.md) - 动态数组
- [HashMap](./container-hashmap.md) - 哈希表

8
docs/api/containers/container-overview.md → docs/api/containers/containers.md
View File

@@ -16,9 +16,9 @@ Containers 模块提供了图形引擎常用的数据结构，包括动态数组
| 组件 | 文件 | 描述 |
|------|------|------|
| [Array](./container-array.md) | `Array.h` | 模板动态数组，支持自动扩容 |
| [String](./container-string.md) | `String.h` | 动态字符串类 |
| [HashMap](./container-hashmap.md) | `HashMap.h` | 模板哈希表 |
| [Array](array/array.md) | `Array.h` | 模板动态数组，支持自动扩容 |
| [String](string/string.md) | `String.h` | 动态字符串类 |
| [HashMap](hashmap/hashmap.md) | `HashMap.h` | 模板哈希表 |
## 设计特点
@@ -52,4 +52,4 @@ int* value = map.Find("key1");
## 相关文档
- [Memory 模块](../memory/memory-overview.md) - 内存分配器接口
- [Memory 模块](../memory/memory.md) - 内存分配器接口

34
docs/api/containers/hashmap/clear.md Normal file
View File

@@ -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) - 删除单个元素

31
docs/api/containers/hashmap/constructor.md Normal file
View File

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

35
docs/api/containers/hashmap/contains.md Normal file
View File

@@ -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) - 查找键对应的值

34
docs/api/containers/hashmap/copy-move.md Normal file
View File

@@ -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(1)，直接接管源对象的内部资源
**示例：**
```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) - 赋值运算符

27
docs/api/containers/hashmap/destructor.md Normal file
View File

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

37
docs/api/containers/hashmap/erase.md Normal file
View File

@@ -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) - 清空所有元素

39
docs/api/containers/hashmap/find.md Normal file
View File

@@ -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) - 下标访问

112
docs/api/containers/hashmap/hashmap.md Normal file
View File

@@ -0,0 +1,112 @@
# 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 "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) - 内存分配器

38
docs/api/containers/hashmap/insert.md Normal file
View File

@@ -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) - 删除键对应的元素

44
docs/api/containers/hashmap/iterator.md Normal file
View File

@@ -0,0 +1,44 @@
# 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;
}
// 输出顺序不确定，取决于哈希桶的内部布局
// 范围 for 循环（需要 C++20 或手动实现 begin/end）
for (auto& [key, value] : map) {
std::cout << key << " -> " << value << std::endl;
}
// 常量迭代器
for (auto it = map.cbegin(); it != map.cend(); ++it) {
std::cout << it->first << " -> " << it->second << std::endl;
}
```
## 相关文档
- [HashMap 总览](hashmap.md) - 返回类总览

36
docs/api/containers/hashmap/operator-assign.md Normal file
View File

@@ -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) - 拷贝/移动构造

33
docs/api/containers/hashmap/operator-subscript.md Normal file
View File

@@ -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) - 插入键值对（不覆盖已存在的键）

28
docs/api/containers/hashmap/setallocator.md Normal file
View File

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

35
docs/api/containers/hashmap/size.md Normal file
View File

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

39
docs/api/containers/string/clear.md Normal file
View File

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

49
docs/api/containers/string/constructor.md Normal file
View File

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

36
docs/api/containers/string/cstr.md Normal file
View File

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

31
docs/api/containers/string/destructor.md Normal file
View File

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

39
docs/api/containers/string/ends-with.md Normal file
View File

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

47
docs/api/containers/string/find.md Normal file
View File

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

47
docs/api/containers/string/operator-assign.md Normal file
View File

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

43
docs/api/containers/string/operator-equal.md Normal file
View File

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

43
docs/api/containers/string/operator-plus-assign.md Normal file
View File

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

39
docs/api/containers/string/operator-plus.md Normal file
View File

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

51
docs/api/containers/string/operator-subscript.md Normal file
View File

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

51
docs/api/containers/string/reserve-resize.md Normal file
View File

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

44
docs/api/containers/string/size.md Normal file
View File

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

39
docs/api/containers/string/starts-with.md Normal file
View File

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

132
docs/api/containers/string/string.md Normal file
View File

@@ -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) - 哈希表

43
docs/api/containers/string/substring.md Normal file
View File

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

36
docs/api/containers/string/to-lower-upper.md Normal file
View File

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

35
docs/api/containers/string/trim.md Normal file
View File

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

14
docs/api/core/core-overview.md → docs/api/core/core.md
View File

@@ -16,26 +16,26 @@ Core 模块包含了引擎所需的基础类型和工具，是其他所有模块
| 组件 | 文件 | 描述 |
|------|------|------|
| [Types](./core-types.md) | `Types.h` | 类型别名定义 |
| [Types](types/types.md) | `Types.h` | 类型别名定义 |
### 智能指针
| 组件 | 文件 | 描述 |
|------|------|------|
| [SmartPtr](./core-smartptr.md) | `SmartPtr.h` | 智能指针别名和工厂函数 |
| [RefCounted](./core-refcounted.md) | `RefCounted.h` | 引用计数基类 |
| [SmartPtr](smartptr/smartptr.md) | `SmartPtr.h` | 智能指针别名和工厂函数 |
| [RefCounted](refcounted/refcounted.md) | `RefCounted.h` | 引用计数基类 |
### 事件系统
| 组件 | 文件 | 描述 |
|------|------|------|
| [Event](./core-event.md) | `Event.h` | 事件系统模板 |
| [Event](event/event.md) | `Event.h` | 事件系统模板 |
### 文件操作
| 组件 | 文件 | 描述 |
|------|------|------|
| [FileWriter](./core-filewriter.md) | `FileWriter.h` | 文件写入工具 |
| [FileWriter](filewriter/filewriter.md) | `FileWriter.h` | 文件写入工具 |
## 类型别名
@@ -90,5 +90,5 @@ myEvent.Invoke(42, 3.14f);
## 相关文档
- [Containers 模块](../containers/container-overview.md) - 容器类型
- [Memory 模块](../memory/memory-overview.md) - 内存管理
- [Containers 模块](../containers/containers.md) - 容器类型
- [Memory 模块](../memory/memory.md) - 内存管理

37
docs/api/core/event/Clear.md Normal file
View File

@@ -0,0 +1,37 @@
# Event::Clear
```cpp
void Clear();
```
清空所有订阅。
**描述**
移除所有已订阅的回调，清空事件。线程安全。
**复杂度：** O(n) 其中 n 为订阅数量
**示例：**
```cpp
#include <XCEngine/Core/Event.h>
Event<int> event;
// 订阅多个回调
event.Subscribe([](int v) { });
event.Subscribe([](int v) { });
event.Subscribe([](int v) { });
// 清空所有订阅
event.Clear();
// 触发（无回调被执行）
event.Invoke(42);
```
## 相关文档
- [Event 总览](event.md) - 返回类总览
- [Unsubscribe](Unsubscribe.md) - 退订单个事件

43
docs/api/core/event/Invoke.md Normal file
View File

@@ -0,0 +1,43 @@
# Event::Invoke
```cpp
void Invoke(Args... args);
```
调用所有订阅的回调。
**描述**
依次调用所有已订阅的回调函数。在调用前会自动处理待退订的回调。回调是在锁外执行的，因此可以在回调中安全地进行订阅/退订操作。线程安全。
**参数：**
- `args` - 传递给回调的参数
**复杂度：** O(n) 其中 n 为订阅数量
**示例：**
```cpp
#include <XCEngine/Core/Event.h>
// 无参数事件
Event<> frameEndEvent;
frameEndEvent.Subscribe([]() {
printf("Frame ended\n");
});
// 带参数事件
Event<int, const char*> playerDiedEvent;
playerDiedEvent.Subscribe([](int playerId, const char* reason) {
printf("Player %d died: %s\n", playerId, reason);
});
// 触发事件
frameEndEvent.Invoke();
playerDiedEvent.Invoke(1, "fell off a cliff");
```
## 相关文档
- [Event 总览](event.md) - 返回类总览
- [Subscribe](Subscribe.md) - 订阅事件

37
docs/api/core/event/ProcessUnsubscribes.md Normal file
View File

@@ -0,0 +1,37 @@
# Event::ProcessUnsubscribes
```cpp
void ProcessUnsubscribes();
```
处理积压的退订请求。
**描述**
手动处理待退订的回调，将其从订阅列表中移除。通常不需要手动调用，`Invoke` 会自动处理退订。但在某些场景下可能需要主动调用。
**复杂度：** O(n) 其中 n 为待退订数量
**示例：**
```cpp
#include <XCEngine/Core/Event.h>
Event<int> event;
// 订阅
uint64_t id = event.Subscribe([](int value) { });
// 退订请求入队
event.Unsubscribe(id);
// 主动处理退订
event.ProcessUnsubscribes();
// 此时事件列表中已无该回调
```
## 相关文档
- [Event 总览](event.md) - 返回类总览
- [Unsubscribe](Unsubscribe.md) - 退订事件

48
docs/api/core/event/Subscribe.md Normal file
View File

@@ -0,0 +1,48 @@
# Event::Subscribe
```cpp
uint64_t Subscribe(Callback callback);
```
订阅事件回调。
**描述**
将回调函数添加到事件订阅列表中，并返回一个唯一的订阅 ID。该 ID 可用于后续退订。线程安全，可在任意线程调用。
**参数：**
- `callback` - 要订阅的回调函数，类型为 `std::function<void(Args...)>`
**返回：** `uint64_t` - 订阅 ID，用于退订
**复杂度：** O(1) amortized
**示例：**
```cpp
#include <XCEngine/Core/Event.h>
// 定义事件
Event<int, float> damageEvent;
// 订阅多个回调
uint64_t id1 = damageEvent.Subscribe([](int damage, float time) {
printf("Damage taken: %d at time %f\n", damage, time);
});
uint64_t id2 = damageEvent.Subscribe([](int damage, float time) {
// 记录伤害日志
});
// 使用 lambda 表达式
auto callback = [](int damage, float time) {
// 处理伤害
};
uint64_t id3 = damageEvent.Subscribe(callback);
```
## 相关文档
- [Event 总览](event.md) - 返回类总览
- [Unsubscribe](Unsubscribe.md) - 退订事件
- [Invoke](Invoke.md) - 触发事件

41
docs/api/core/event/Unsubscribe.md Normal file
View File

@@ -0,0 +1,41 @@
# Event::Unsubscribe
```cpp
void Unsubscribe(uint64_t id);
```
退订事件。
**描述**
将指定 ID 的回调从订阅列表中移除。退订是延迟生效的，在调用 `Invoke` 时会一并处理待退订的回调。线程安全，可在任意线程调用。
**参数：**
- `id` - 订阅时返回的 ID
**复杂度：** O(n) 在 Invoke 时处理
**示例：**
```cpp
#include <XCEngine/Core/Event.h>
Event<int> someEvent;
// 订阅
uint64_t id = someEvent.Subscribe([](int value) {
printf("Value: %d\n", value);
});
// 退订
someEvent.Unsubscribe(id);
// 触发（已退订的回调不会被调用）
someEvent.Invoke(42);
```
## 相关文档
- [Event 总览](event.md) - 返回类总览
- [Subscribe](Subscribe.md) - 订阅事件
- [ProcessUnsubscribes](ProcessUnsubscribes.md) - 手动处理退订

35
docs/api/core/event/begin.md Normal file
View File

@@ -0,0 +1,35 @@
# Event::begin
```cpp
Iterator begin();
```
获取开始迭代器。
**描述**
返回订阅列表的开始迭代器，用于范围for循环遍历所有订阅的回调。
**返回：** `Iterator` - 指向第一个监听器的迭代器
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Event.h>
Event<int> event;
event.Subscribe([](int v) { printf("Callback 1: %d\n", v); });
event.Subscribe([](int v) { printf("Callback 2: %d\n", v); });
// 遍历所有订阅
for (auto& [id, callback] : event) {
callback(100);
}
```
## 相关文档
- [Event 总览](event.md) - 返回类总览
- [end](end.md) - 获取结束迭代器

34
docs/api/core/event/end.md Normal file
View File

@@ -0,0 +1,34 @@
# Event::end
```cpp
Iterator end();
```
获取结束迭代器。
**描述**
返回订阅列表的结束迭代器，用于范围for循环遍历所有订阅的回调。
**返回：** `Iterator` - 指向末尾的迭代器
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Event.h>
Event<int> event;
event.Subscribe([](int v) { printf("Callback: %d\n", v); });
// 遍历所有订阅
for (auto& [id, callback] : event) {
callback(42);
}
```
## 相关文档
- [Event 总览](event.md) - 返回类总览
- [begin](begin.md) - 获取开始迭代器

14
docs/api/core/core-event.md → docs/api/core/event/event.md
View File

@@ -48,6 +48,18 @@
| `Iterator begin()` | 获取开始迭代器 |
| `Iterator end()` | 获取结束迭代器 |
## 方法列表
| 方法 | 描述 |
|------|------|
| [Subscribe](Subscribe.md) | 订阅事件回调 |
| [Unsubscribe](Unsubscribe.md) | 退订事件 |
| [ProcessUnsubscribes](ProcessUnsubscribes.md) | 处理积压的退订请求 |
| [Invoke](Invoke.md) | 调用所有订阅的回调 |
| [Clear](Clear.md) | 清空所有订阅 |
| [begin](begin.md) | 获取开始迭代器 |
| [end](end.md) | 获取结束迭代器 |
## 使用示例
```cpp
@@ -74,4 +86,4 @@ frameStartEvent.Clear();
## 相关文档
- [Core 模块概览](./core-overview.md) - Core 模块总览
- [Core 模块总览](../core.md) - 返回模块总览

38
docs/api/core/filewriter/Close.md Normal file
View File

@@ -0,0 +1,38 @@
# FileWriter::Close
```cpp
void Close();
```
关闭文件。
**描述**
关闭当前打开的文件。如果文件未打开，则什么都不做。析构函数会自动调用此方法。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/FileWriter.h>
FileWriter writer;
if (writer.Open("data.txt")) {
writer.Write("Some data\n");
writer.Flush();
writer.Close();
}
// 文件已关闭，可再次打开其他文件
if (writer.Open("other.txt")) {
writer.Write("New content\n");
}
// 析构时自动关闭
```
## 相关文档
- [FileWriter 总览](filewriter.md) - 返回类总览
- [Open](Open.md) - 打开文件

42
docs/api/core/filewriter/Flush.md Normal file
View File

@@ -0,0 +1,42 @@
# FileWriter::Flush
```cpp
bool Flush();
```
刷新缓冲区。
**描述**
将缓冲区中的数据强制写入磁盘，确保数据持久化。在写入大量数据后应调用此方法以确保数据已保存。
**返回：** `bool` - 是否刷新成功
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/FileWriter.h>
FileWriter writer("output.txt");
if (writer.IsOpen()) {
// 写入大量数据
for (int i = 0; i < 1000; i++) {
writer.Write("Line ");
writer.Write(std::to_string(i).c_str());
writer.Write("\n");
}
// 刷新确保数据写入磁盘
writer.Flush();
// 数据已安全保存
writer.Close();
}
```
## 相关文档
- [FileWriter 总览](filewriter.md) - 返回类总览
- [Write](Write.md) - 写入数据

41
docs/api/core/filewriter/IsOpen.md Normal file
View File

@@ -0,0 +1,41 @@
# FileWriter::IsOpen
```cpp
bool IsOpen() const;
```
检查文件是否已打开。
**描述**
返回文件是否已成功打开并可用于写入。
**返回：** `bool` - 文件是否已打开
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/FileWriter.h>
FileWriter writer1;
if (writer1.IsOpen()) {
// 不会执行
writer1.Write("test");
}
// 打开文件
FileWriter writer2("output.txt");
if (writer2.IsOpen()) {
printf("File opened successfully\n");
writer2.Write("Content");
} else {
printf("Failed to open file\n");
}
```
## 相关文档
- [FileWriter 总览](filewriter.md) - 返回类总览
- [Open](Open.md) - 打开文件

51
docs/api/core/filewriter/Open.md Normal file
View File

@@ -0,0 +1,51 @@
# FileWriter::Open
```cpp
bool Open(const char* filePath, bool append = false);
```
打开文件。
**描述**
打开指定路径的文件，准备写入。如果之前已打开文件，会先关闭。返回是否成功打开文件。
**参数：**
- `filePath` - 要打开的文件路径
- `append` - 是否以追加模式打开，默认为覆盖模式
**返回：** `bool` - 是否成功打开
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/FileWriter.h>
FileWriter writer;
// 打开文件（覆盖模式）
if (writer.Open("output.txt")) {
writer.Write("Hello\n");
writer.Close();
}
// 打开文件（追加模式）
if (writer.Open("log.txt", true)) {
writer.Write("Another line\n");
writer.Flush();
}
// 检查是否成功
FileWriter writer2;
if (!writer2.Open("/invalid/path/file.txt")) {
printf("Failed to open file\n");
}
```
## 相关文档
- [FileWriter 总览](filewriter.md) - 返回类总览
- [Close](Close.md) - 关闭文件
- [IsOpen](IsOpen.md) - 检查文件状态

46
docs/api/core/filewriter/Write.md Normal file
View File

@@ -0,0 +1,46 @@
# FileWriter::Write
```cpp
bool Write(const char* data, size_t length);
bool Write(const Containers::String& str);
```
写入数据到文件。
**描述**
将数据写入文件。如果文件未打开，操作会失败。
**参数：**
- `data` - 要写入的字符数据
- `length` - 要写入的字节数
- `str` - 要写入的 String 对象
**返回：** `bool` - 是否写入成功
**复杂度：** O(n) 其中 n 为写入的字节数
**示例：**
```cpp
#include <XCEngine/Core/FileWriter.h>
#include <XCEngine/Containers/String.h>
FileWriter writer("output.txt");
if (writer.IsOpen()) {
// 写入原始字符数组
writer.Write("Hello, World!", 13);
writer.Write("\n", 1);
// 写入 String
Containers::String message = "This is a test string";
writer.Write(message);
writer.Flush();
}
```
## 相关文档
- [FileWriter 总览](filewriter.md) - 返回类总览
- [Flush](Flush.md) - 刷新缓冲区

16
docs/api/core/core-filewriter.md → docs/api/core/filewriter/filewriter.md
View File

@@ -36,6 +36,17 @@
| `bool Write(const Containers::String& str)` | 写入 String 内容 |
| `bool Flush()` | 刷新缓冲区，确保数据写入磁盘 |
## 方法列表
| 方法 | 描述 |
|------|------|
| [FileWriter](FileWriter.md) | 构造函数 |
| [Open](Open.md) | 打开文件 |
| [Close](Close.md) | 关闭文件 |
| [IsOpen](IsOpen.md) | 检查文件是否已打开 |
| [Write](Write.md) | 写入数据 |
| [Flush](Flush.md) | 刷新缓冲区 |
## 使用示例
```cpp
@@ -71,5 +82,6 @@ writer3.Write(content);
## 相关文档
- [Logger](../debug/debug-logger.md) - 日志系统
- [FileLogSink](../debug/debug-filelogsink.md) - 文件日志输出
- [Core 模块总览](../core.md) - 返回模块总览
- [Logger](../../debug/logger/logger.md) - 日志系统
- [FileLogSink](../../debug/filelogsink/filelogsink.md) - 文件日志输出

40
docs/api/core/refcounted/AddRef.md Normal file
View File

@@ -0,0 +1,40 @@
# RefCounted::AddRef
```cpp
void AddRef();
```
增加引用计数。
**描述**
原子地增加引用计数。在复制 `RefCounted` 指针或传递引用时调用此方法。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/RefCounted.h>
class MyObject : public RefCounted {
public:
void DoSomething() { /* ... */ }
};
// 创建对象（构造时 refCount = 1）
MyObject* obj = new MyObject();
// 手动增加引用
obj->AddRef(); // refCount = 2
obj->AddRef(); // refCount = 3
// 需要释放额外的引用
obj->Release(); // refCount = 2
obj->Release(); // refCount = 1
```
## 相关文档
- [RefCounted 总览](refcounted.md) - 返回类总览
- [Release](Release.md) - 减少引用计数

43
docs/api/core/refcounted/GetRefCount.md Normal file
View File

@@ -0,0 +1,43 @@
# RefCounted::GetRefCount
```cpp
uint32_t GetRefCount() const;
```
获取当前引用计数。
**描述**
返回当前的引用计数值。由于使用 `std::atomic` 实现，因此是线程安全的。
**返回：** `uint32_t` - 当前引用计数
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/RefCounted.h>
class MyObject : public RefCounted {
public:
void Debug() {
printf("RefCount: %u\n", GetRefCount());
}
};
MyObject* obj = new MyObject();
printf("After create: %u\n", obj->GetRefCount()); // 1
obj->AddRef();
printf("After AddRef: %u\n", obj->GetRefCount()); // 2
obj->Release();
printf("After Release: %u\n", obj->GetRefCount()); // 1
```
## 相关文档
- [RefCounted 总览](refcounted.md) - 返回类总览
- [AddRef](AddRef.md) - 增加引用计数
- [Release](Release.md) - 减少引用计数

39
docs/api/core/refcounted/Release.md Normal file
View File

@@ -0,0 +1,39 @@
# RefCounted::Release
```cpp
void Release();
```
减少引用计数。
**描述**
原子地减少引用计数。当引用计数归零时，对象会自动 `delete this`。这是实现自动内存管理的关键方法。
**复杂度：** O(1)（归零时为 O(n)，n 为对象大小）
**示例：**
```cpp
#include <XCEngine/Core/RefCounted.h>
class MyObject : public RefCounted {
public:
void DoSomething() { /* ... */ }
};
// 创建对象（构造时 refCount = 1）
MyObject* obj = new MyObject();
// 手动增加引用
obj->AddRef(); // refCount = 2
// 释放引用
obj->Release(); // refCount = 1
obj->Release(); // refCount = 0, 对象被自动 delete
```
## 相关文档
- [RefCounted 总览](refcounted.md) - 返回类总览
- [AddRef](AddRef.md) - 增加引用计数

12
docs/api/core/core-refcounted.md → docs/api/core/refcounted/refcounted.md
View File

@@ -27,6 +27,15 @@
| `void Release()` | 减少引用计数（归零时自动 delete this） |
| `uint32_t GetRefCount() const` | 获取当前引用计数 |
## 方法列表
| 方法 | 描述 |
|------|------|
| [RefCounted](RefCounted.md) | 构造函数 |
| [AddRef](AddRef.md) | 增加引用计数 |
| [Release](Release.md) | 减少引用计数 |
| [GetRefCount](GetRefCount.md) | 获取当前引用计数 |
## 使用示例
```cpp
@@ -47,4 +56,5 @@ obj->Release(); // refCount = 0, 自动 delete
## 相关文档
- [SmartPtr](./core-smartptr.md) - 智能指针
- [Core 模块总览](../core.md) - 返回模块总览
- [SmartPtr](../smartptr/smartptr.md) - 智能指针

51
docs/api/core/smartptr/MakeRef.md Normal file
View File

@@ -0,0 +1,51 @@
# SmartPtr::MakeRef
```cpp
template<typename T, typename... Args>
Ref<T> MakeRef(Args&&... args);
```
创建共享指针的工厂函数。
**描述**
`MakeRef` 是创建 `Ref<T>` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_shared`，代码更简洁。
**模板参数：**
- `T` - 被创建对象的类型
- `Args` - 构造函数的参数类型
**参数：**
- `args` - 转发给 T 构造函数的参数
**返回：** `Ref<T>` - 新创建的共享指针
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/SmartPtr.h>
class MyClass {
public:
MyClass(int a, int b) : m_a(a), m_b(b) {}
int GetSum() const { return m_a + m_b; }
private:
int m_a, m_b;
};
// 创建共享指针
Core::Ref<MyClass> ref = Core::MakeRef<MyClass>(10, 20);
printf("Sum: %d\n", ref->GetSum());
// 使用 lambda
Core::Ref<std::function<void()>> callback = Core::MakeRef<std::function<void()>>([]() {
printf("Callback invoked!\n");
});
```
## 相关文档
- [SmartPtr 总览](smartptr.md) - 返回类总览
- [Ref](Ref.md) - Ref 类型说明

49
docs/api/core/smartptr/MakeUnique.md Normal file
View File

@@ -0,0 +1,49 @@
# SmartPtr::MakeUnique
```cpp
template<typename T, typename... Args>
UniqueRef<T> MakeUnique(Args&&... args);
```
创建独占指针的工厂函数。
**描述**
`MakeUnique` 是创建 `UniqueRef<T>` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_unique`，代码更简洁。
**模板参数：**
- `T` - 被创建对象的类型
- `Args` - 构造函数的参数类型
**参数：**
- `args` - 转发给 T 构造函数的参数
**返回：** `UniqueRef<T>` - 新创建的独占指针
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/SmartPtr.h>
class MyClass {
public:
MyClass(int value) : m_value(value) {}
int GetValue() const { return m_value; }
private:
int m_value;
};
// 创建独占指针
Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>(42);
printf("Value: %d\n", unique->GetValue());
// 转移所有权
Core::UniqueRef<MyClass> moved = Core::MakeUnique<MyClass>(100);
```
## 相关文档
- [SmartPtr 总览](smartptr.md) - 返回类总览
- [UniqueRef](UniqueRef.md) - UniqueRef 类型说明

40
docs/api/core/smartptr/Ref.md Normal file
View File

@@ -0,0 +1,40 @@
# SmartPtr::Ref
```cpp
template<typename T>
using Ref = std::shared_ptr<T>;
```
共享引用智能指针类型别名。
**描述**
`Ref<T>` 是 `std::shared_ptr<T>` 的类型别名，提供共享所有权的智能指针。多个 `Ref` 可以指向同一个对象，通过引用计数管理生命周期。当最后一个 `Ref` 被销毁时，对象会被自动删除。
**模板参数：**
- `T` - 被托管对象的类型
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/SmartPtr.h>
class MyClass {
public:
void DoSomething() { /* ... */ }
};
Core::Ref<MyClass> ref1 = Core::MakeRef<MyClass>();
Core::Ref<MyClass> ref2 = ref1; // 共享所有权
if (ref1) {
ref1->DoSomething();
}
```
## 相关文档
- [SmartPtr 总览](smartptr.md) - 返回类总览
- [MakeRef](MakeRef.md) - 创建 Ref 的工厂函数

46
docs/api/core/smartptr/UniqueRef.md Normal file
View File

@@ -0,0 +1,46 @@
# SmartPtr::UniqueRef
```cpp
template<typename T>
using UniqueRef = std::unique_ptr<T>;
```
独占所有权的智能指针类型别名。
**描述**
`UniqueRef<T>` 是 `std::unique_ptr<T>` 的类型别名，提供独占所有权的智能指针。每个对象只能有一个 `UniqueRef` 持有，当 `UniqueRef` 被销毁时，对象会被自动删除。不能复制，只能移动。
**模板参数：**
- `T` - 被托管对象的类型
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/SmartPtr.h>
class MyClass {
public:
void DoSomething() { /* ... */ }
};
Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>();
if (unique) {
unique->DoSomething();
}
// 自定义删除器
Core::UniqueRef<FILE, decltype(&fclose)>
file(fopen("test.txt", "r"), &fclose);
// 转移所有权
Core::UniqueRef<MyClass> moved = std::move(unique);
```
## 相关文档
- [SmartPtr 总览](smartptr.md) - 返回类总览
- [MakeUnique](MakeUnique.md) - 创建 UniqueRef 的工厂函数

14
docs/api/core/core-smartptr.md → docs/api/core/smartptr/smartptr.md
View File

@@ -24,6 +24,15 @@
| `Core::MakeRef<T>(Args&&... args)` | `Ref<T>` | 创建共享指针 |
| `Core::MakeUnique<T>(Args&&... args)` | `UniqueRef<T>` | 创建独占指针 |
## 方法列表
| 方法 | 描述 |
|------|------|
| [Ref](Ref.md) | `std::shared_ptr<T>` 类型别名 |
| [UniqueRef](UniqueRef.md) | `std::unique_ptr<T>` 类型别名 |
| [MakeRef](MakeRef.md) | 创建共享指针的工厂函数 |
| [MakeUnique](MakeUnique.md) | 创建独占指针的工厂函数 |
## 使用示例
```cpp
@@ -50,5 +59,6 @@ Core::UniqueRef<FILE, decltype(&fclose)>
## 相关文档
- [RefCounted](./core-refcounted.md) - 引用计数基类
- [Types](./core-types.md) - 类型别名
- [Core 模块总览](../core.md) - 返回模块总览
- [RefCounted](../refcounted/refcounted.md) - 引用计数基类
- [Types](../../rhi/types/types.md) - 类型别名

30
docs/api/core/types/byte.md Normal file
View File

@@ -0,0 +1,30 @@
# Types::byte
```cpp
using byte = uint8_t;
```
字节类型别名，对应 `uint8_t` 类型。
**描述**
`byte` 是 1 字节无符号整数类型，专门用于表示原始字节数据。语义上比 `uint8` 更清晰，适用于二进制数据、内存缓冲区等场景。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::byte header[4] = {0x00, 0x01, 0x02, 0x03};
Core::byte flags = 0b11001010;
// 内存缓冲区
Core::byte* buffer = new Core::byte[1024];
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [uint8](uint8.md) - 底层类型

27
docs/api/core/types/int16.md Normal file
View File

@@ -0,0 +1,27 @@
# Types::int16
```cpp
using int16 = int16_t;
```
16位有符号整数类型别名，对应 C++ 标准库的 `int16_t` 类型。
**描述**
`int16` 是 16 位（2 字节）有符号整数类型，范围为 -32,768 到 32,767。该类型别名确保跨平台一致性。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::int16 shortValue = -10000;
Core::int16 maxValue = 32767;
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [uint16](uint16.md) - 对应的无符号类型

30
docs/api/core/types/int32.md Normal file
View File

@@ -0,0 +1,30 @@
# Types::int32
```cpp
using int32 = int32_t;
```
32位有符号整数类型别名，对应 C++ 标准库的 `int32_t` 类型。
**描述**
`int32` 是 32 位（4 字节）有符号整数类型，范围为 -2,147,483,648 到 2,147,483,647。该类型别名确保跨平台一致性，是最常用的整数类型。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::int32 score = 1000000;
Core::int32 negative = -500000;
// 函数参数类型
void SetHealth(Core::int32 health);
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [uint32](uint32.md) - 对应的无符号类型

30
docs/api/core/types/int64.md Normal file
View File

@@ -0,0 +1,30 @@
# Types::int64
```cpp
using int64 = int64_t;
```
64位有符号整数类型别名，对应 C++ 标准库的 `int64_t` 类型。
**描述**
`int64` 是 64 位（8 字节）有符号整数类型，范围为 -9,223,372,036,854,775,808 到 9,223,372,036,854,775,807。该类型别名用于需要大范围整数的场景，如时间戳、大文件大小等。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::int64 largeNumber = 9223372036854775807LL;
Core::int64 fileSize = 1099511627776LL; // 1TB
// 时间戳（毫秒）
Core::int64 timestamp = 1700000000000LL;
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [uint64](uint64.md) - 对应的无符号类型

28
docs/api/core/types/int8.md Normal file
View File

@@ -0,0 +1,28 @@
# Types::int8
```cpp
using int8 = int8_t;
```
8位有符号整数类型别名，对应 C++ 标准库的 `int8_t` 类型。
**描述**
`int8` 是 8 位（1 字节）有符号整数类型，范围为 -128 到 127。该类型别名确保跨平台一致性。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::int8 signedByte = -50;
Core::int8 maxValue = 127;
Core::int8 minValue = -128;
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [uint8](uint8.md) - 对应的无符号类型

18
docs/api/core/core-types.md → docs/api/core/types/types.md
View File

@@ -26,6 +26,20 @@
| `uint64` | `uint64_t` | 64位无符号整数 |
| `byte` | `uint8_t` | 字节类型 |
## 方法列表
| 方法 | 描述 |
|------|------|
| [int8](int8.md) | 8位有符号整数类型别名 |
| [int16](int16.md) | 16位有符号整数类型别名 |
| [int32](int32.md) | 32位有符号整数类型别名 |
| [int64](int64.md) | 64位有符号整数类型别名 |
| [uint8](uint8.md) | 8位无符号整数类型别名 |
| [uint16](uint16.md) | 16位无符号整数类型别名 |
| [uint32](uint32.md) | 32位无符号整数类型别名 |
| [uint64](uint64.md) | 64位无符号整数类型别名 |
| [byte](byte.md) | 字节类型别名 |
## 使用示例
```cpp
@@ -45,5 +59,5 @@ void ProcessData(Core::uint32 size, const Core::int8* data);
## 相关文档
- [SmartPtr](./core-smartptr.md) - 智能指针
- [RefCounted](./core-refcounted.md) - 引用计数基类
- [Core 模块总览](../core.md) - 返回模块总览
- [SmartPtr](../smartptr/smartptr.md) - 智能指针

30
docs/api/core/types/uint16.md Normal file
View File

@@ -0,0 +1,30 @@
# Types::uint16
```cpp
using uint16 = uint16_t;
```
16位无符号整数类型别名，对应 C++ 标准库的 `uint16_t` 类型。
**描述**
`uint16` 是 16 位（2 字节）无符号整数类型，范围为 0 到 65,535。常用于 Unicode 字符、端口号等场景。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::uint16 port = 8080;
Core::uint16 maxConnections = 65535;
// Unicode 字符
Core::uint16 unicodeChar = 0x4E2D;
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [int16](int16.md) - 对应的有符号类型

30
docs/api/core/types/uint32.md Normal file
View File

@@ -0,0 +1,30 @@
# Types::uint32
```cpp
using uint32 = uint32_t;
```
32位无符号整数类型别名，对应 C++ 标准库的 `uint32_t` 类型。
**描述**
`uint32` 是 32 位（4 字节）无符号整数类型，范围为 0 到 4,294,967,295。常用于 ID、计数、大小等场景。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::uint32 entityId = 1000000;
Core::uint32 maxItems = 4294967295U;
// 数组大小
Core::uint32 arraySize = 1000;
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [int32](int32.md) - 对应的有符号类型

30
docs/api/core/types/uint64.md Normal file
View File

@@ -0,0 +1,30 @@
# Types::uint64
```cpp
using uint64 = uint64_t;
```
64位无符号整数类型别名，对应 C++ 标准库的 `uint64_t` 类型。
**描述**
`uint64` 是 64 位（8 字节）无符号整数类型，范围为 0 到 18,446,744,073,709,551,615。用于需要极大整数范围的场景，如大文件大小、精确时间等。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::uint64 largeFileSize = 1099511627776ULL; // 1TB
Core::uint64 maxValue = 18446744073709551615ULL;
// 高精度时间戳（微秒）
Core::uint64 microseconds = 1700000000000000ULL;
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [int64](int64.md) - 对应的有符号类型

30
docs/api/core/types/uint8.md Normal file
View File

@@ -0,0 +1,30 @@
# Types::uint8
```cpp
using uint8 = uint8_t;
```
8位无符号整数类型别名，对应 C++ 标准库的 `uint8_t` 类型。
**描述**
`uint8` 是 8 位（1 字节）无符号整数类型，范围为 0 到 255。常用于字节数据、颜色分量（RGB）等场景。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Core/Types.h>
Core::uint8 flags = 0xFF;
Core::uint8 red = 255;
// 字节数组
Core::uint8 buffer[256];
```
## 相关文档
- [Types 总览](types.md) - 返回类型总览
- [int8](int8.md) - 对应的有符号类型

20
docs/api/debug/consolelogsink/consolelogsink.md Normal file
View File

@@ -0,0 +1,20 @@
# ConsoleLogSink::ConsoleLogSink
```cpp
ConsoleLogSink()
```
默认构造函数。创建一个 `ConsoleLogSink` 实例，默认启用彩色输出，最小日志级别为 `Verbose`。
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

22
docs/api/debug/consolelogsink/flush.md Normal file
View File

@@ -0,0 +1,22 @@
# ConsoleLogSink::Flush
```cpp
void Flush() override
```
刷新标准输出流（stdout），调用 `fflush(stdout)` 确保所有待输出的日志内容立即显示在控制台上。
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
// 在程序异常退出前确保日志已输出
XCEngine::Debug::Logger::Get().Flush();
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

25
docs/api/debug/consolelogsink/log.md Normal file
View File

@@ -0,0 +1,25 @@
# ConsoleLogSink::Log
```cpp
void Log(const LogEntry& entry) override
```
将日志输出到控制台。根据 `LogEntry` 的级别和分类格式化输出内容，并根据 `m_colorOutput` 设置决定是否使用 Windows 控制台颜色 API。如果日志级别低于设置的最小级别，则不输出。
**参数：**
- `entry` - 日志条目
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
// Log 方法由 Logger 在内部调用，用户无需直接调用
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Hello console");
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

24
docs/api/debug/consolelogsink/setcoloroutput.md Normal file
View File

@@ -0,0 +1,24 @@
# ConsoleLogSink::SetColorOutput
```cpp
void SetColorOutput(bool enable)
```
启用或禁用控制台彩色输出。启用后，不同日志级别使用 Windows 控制台颜色 API 输出，便于快速区分日志类型。
**参数：**
- `enable` - true 启用彩色输出，false 禁用
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
sink->SetColorOutput(false); // 禁用颜色（适合日志文件或 CI 环境）
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

24
docs/api/debug/consolelogsink/setminimumlevel.md Normal file
View File

@@ -0,0 +1,24 @@
# ConsoleLogSink::SetMinimumLevel
```cpp
void SetMinimumLevel(LogLevel level)
```
设置该 Sink 的最小输出级别。此设置仅影响当前 Sink，不会影响 Logger 的全局级别过滤。
**参数：**
- `level` - 最小日志级别
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
sink->SetMinimumLevel(XCEngine::Debug::LogLevel::Warning); // 控制台只显示警告及以上
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

13
docs/api/debug/consolelogsink/~consolelogsink.md Normal file
View File

@@ -0,0 +1,13 @@
# ConsoleLogSink::~ConsoleLogSink
```cpp
~ConsoleLogSink() override
```
析构函数。销毁 `ConsoleLogSink` 实例，释放相关资源。
**复杂度：** O(1)
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

52
docs/api/debug/debug-consolelogsink.md
View File

@@ -1,52 +0,0 @@
# ConsoleLogSink
**命名空间**: `XCEngine::Debug`
**类型**: `class`
**描述**: 控制台日志输出槽，将日志输出到标准控制台，支持彩色输出。
## 概述
`ConsoleLogSink` 是 `ILogSink` 的控制台实现。它将日志输出到 stdout/stderr，支持按日志级别设置不同颜色。
## 公共方法
### 构造/析构
| 方法 | 描述 |
|------|------|
| `ConsoleLogSink()` | 默认构造函数 |
| `~ConsoleLogSink()` | 析构函数 |
### ILogSink 实现
| 方法 | 描述 |
|------|------|
| `void Log(const LogEntry& entry) override` | 输出日志到控制台 |
| `void Flush() override` | 刷新标准输出流 |
### 配置
| 方法 | 描述 |
|------|------|
| `void SetColorOutput(bool enable)` | 启用/禁用彩色输出 |
| `void SetMinimumLevel(LogLevel level)` | 设置最小输出级别 |
## 使用示例
```cpp
// 创建并配置
auto sink = std::make_unique<ConsoleLogSink>();
sink->SetColorOutput(true);
sink->SetMinimumLevel(LogLevel::Debug);
// 添加到 Logger
Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [ILogSink](./debug-ilogsink.md) - 日志输出接口
- [FileLogSink](./debug-filelogsink.md) - 文件输出

47
docs/api/debug/debug-filelogsink.md
View File

@@ -1,47 +0,0 @@
# FileLogSink
**命名空间**: `XCEngine::Debug`
**类型**: `class`
**描述**: 文件日志输出槽，将日志持久化到磁盘文件。
## 概述
`FileLogSink` 是 `ILogSink` 的文件实现。它使用 `FileWriter` 将日志追加写入文件，支持自动换行和缓冲区刷新。
## 公共方法
### 构造/析构
| 方法 | 描述 |
|------|------|
| `FileLogSink(const Containers::String& filePath)` | 构造函数，指定文件路径 |
| `~FileLogSink()` | 析构函数 |
### ILogSink 实现
| 方法 | 描述 |
|------|------|
| `void Log(const LogEntry& entry) override` | 将日志追加写入文件 |
| `void Flush() override` | 刷新文件缓冲区 |
## 使用示例
```cpp
// 创建文件日志输出
auto fileSink = std::make_unique<FileLogSink>("logs/app.log");
// 添加到 Logger
Logger::Get().AddSink(std::move(fileSink));
// 日志将自动写入文件
XE_LOG(LogCategory::General, LogLevel::Info, "Game started");
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [ILogSink](./debug-ilogsink.md) - 日志输出接口
- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出
- [Core/FileWriter](../core/core-filewriter.md) - 文件写入工具

18
docs/api/debug/debug-overview.md → docs/api/debug/debug.md
View File

@@ -16,19 +16,19 @@ Debug 模块提供了一套完整的调试工具，包括日志系统和性能
| 组件 | 文件 | 描述 |
|------|------|------|
| [Logger](./debug-logger.md) | `Logger.h` | 日志记录器 |
| [ILogSink](./debug-ilogsink.md) | `ILogSink.h` | 日志输出接口 |
| [ConsoleLogSink](./debug-consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 |
| [FileLogSink](./debug-filelogsink.md) | `FileLogSink.h` | 文件输出 |
| [LogLevel](./debug-loglevel.md) | `LogLevel.h` | 日志级别枚举 |
| [LogCategory](./debug-logcategory.md) | `LogCategory.h` | 日志分类枚举 |
| [LogEntry](./debug-logentry.md) | `LogEntry.h` | 日志条目结构 |
| [Logger](logger/logger.md) | `Logger.h` | 日志记录器 |
| [ILogSink](ilogsink/ilogsink.md) | `ILogSink.h` | 日志输出接口 |
| [ConsoleLogSink](consolelogsink/consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 |
| [FileLogSink](filelogsink/filelogsink.md) | `FileLogSink.h` | 文件输出 |
| [LogLevel](loglevel/loglevel.md) | `LogLevel.h` | 日志级别枚举 |
| [LogCategory](logcategory/logcategory.md) | `LogCategory.h` | 日志分类枚举 |
| [LogEntry](logentry/logentry.md) | `LogEntry.h` | 日志条目结构 |
### 性能分析
| 组件 | 文件 | 描述 |
|------|------|------|
| [Profiler](./debug-profiler.md) | `Profiler.h` | 性能分析器 |
| [Profiler](profiler/profiler.md) | `Profiler.h` | 性能分析器 |
## 日志级别
@@ -80,4 +80,4 @@ if (condition) {
## 相关文档
- [Profiler](./debug-profiler.md) - 性能分析器
- [Profiler](profiler/profiler.md) - 性能分析器

23
docs/api/debug/filelogsink/filelogsink.md Normal file
View File

@@ -0,0 +1,23 @@
# FileLogSink::FileLogSink
```cpp
FileLogSink(const Containers::String& filePath)
```
构造函数，打开指定路径的文件用于日志写入。如果文件已存在，则追加写入；如果不存在，则创建新文件。
**参数：**
- `filePath` - 日志文件路径
**复杂度：** O(1)
**示例：**
```cpp
auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/engine.log");
XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
```
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

24
docs/api/debug/filelogsink/flush.md Normal file
View File

@@ -0,0 +1,24 @@
# FileLogSink::Flush
```cpp
void Flush() override
```
刷新文件缓冲区，调用底层 `FileWriter` 的 flush 方法确保所有待写入的日志数据已实际写入磁盘。
**复杂度：** O(1)
**示例：**
```cpp
auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/app.log");
XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
// 关键操作后立即刷新
XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Checkpoint saved");
// 确保写入磁盘
XCEngine::Debug::Logger::Get().Flush();
```
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

25
docs/api/debug/filelogsink/log.md Normal file
View File

@@ -0,0 +1,25 @@
# FileLogSink::Log
```cpp
void Log(const LogEntry& entry) override
```
将日志条目追加写入文件。根据 `LogEntry` 的各字段格式化日志行，包括时间戳、级别、分类、消息，并追加到文件末尾。
**参数：**
- `entry` - 日志条目
**复杂度：** O(m)，m 为消息长度
**示例：**
```cpp
auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/app.log");
XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
// Log 方法由 Logger 在内部调用
XCEngine::Debug::Logger::Get().Error(XCEngine::Debug::LogCategory::FileSystem, "File not found");
```
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

13
docs/api/debug/filelogsink/~filelogsink.md Normal file
View File

@@ -0,0 +1,13 @@
# FileLogSink::~FileLogSink
```cpp
~FileLogSink() override
```
析构函数。销毁 `FileLogSink` 实例，调用 `Flush()` 确保所有日志数据写入文件，然后关闭文件句柄。
**复杂度：** O(1)
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

Some files were not shown because too many files have changed in this diff Show More