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