feat(d3d12): 新增纹理资源类，修复 Surface 重复释放问题
核心变更： - 新增 d3d12_texture 和 d3d12_render_texture 类 - 新增 d3d12_texture_init_info 结构，支持三种资源创建方式 - 新增 D3D12Helpers.h，提供堆属性辅助结构 - 改用 utl::free_list 管理 surface，解决重复释放问题 - 为 d3d12_surface 添加移动语义，支持撕裂检测 文档完善： - 为 FreeList.h 和 Vector.h 添加完整 Doxygen 中文注释 - 更新 D3D12 学习 Wiki，添加 SRV、资源创建方式、纹理资源类章节 - 新增变更记录文档
This commit is contained in:
SpecialX
@@ -1,11 +1,97 @@
|
||||
/**
|
||||
* @file FreeList.h
|
||||
* @brief 带复用槽位的稀疏对象容器模板。
|
||||
* @brief 带槽位复用机制的稀疏对象容器模板
|
||||
*
|
||||
* @details
|
||||
* free_list 维护“已使用槽位 + 空闲链”结构，支持：
|
||||
* - O(1) 近似开销的新增与删除；
|
||||
* - 删除后槽位复用，降低频繁分配释放成本；
|
||||
* - 以索引作为外部句柄，与 id 系统协同使用。
|
||||
* free_list 是一种特殊的容器，维护"已使用槽位 + 空闲链表"结构，
|
||||
* 特别适合需要频繁增删元素且使用索引作为外部句柄的场景。
|
||||
*
|
||||
* ## 核心特性
|
||||
*
|
||||
* - **O(1) 增删操作**：新增和删除操作近似常数时间复杂度
|
||||
* - **槽位复用**：删除后的槽位会被回收并重新利用，避免频繁内存分配
|
||||
* - **索引句柄**：使用 u32 索引作为外部句柄，与 id 系统完美配合
|
||||
* - **内存紧凑**：底层使用连续内存，缓存友好
|
||||
*
|
||||
* ## 数据结构原理
|
||||
*
|
||||
* ```
|
||||
* 初始状态:
|
||||
* _array: [ 空 | 空 | 空 | 空 ]
|
||||
* _next_free_index = invalid_id
|
||||
* _size = 0
|
||||
*
|
||||
* 添加元素 A、B、C 后:
|
||||
* _array: [ A | B | C | 空 ]
|
||||
* _next_free_index = invalid_id
|
||||
* _size = 3
|
||||
*
|
||||
* 删除元素 B 后（槽位 1 被标记为空闲）:
|
||||
* _array: [ A | ->2 | C | 空 ] // 槽位 1 存储下一个空闲索引 2
|
||||
* _next_free_index = 1 // 指向第一个空闲槽位
|
||||
* _size = 2
|
||||
*
|
||||
* 再删除元素 A 后:
|
||||
* _array: [ ->1 | ->2 | C | 空 ] // 槽位 0 存储下一个空闲索引 1
|
||||
* _next_free_index = 0
|
||||
* _size = 1
|
||||
*
|
||||
* 添加新元素 D 时（复用槽位 0）:
|
||||
* _array: [ D | ->2 | C | 空 ]
|
||||
* _next_free_index = 1 // 指向下一个空闲槽位
|
||||
* _size = 2
|
||||
* ```
|
||||
*
|
||||
* ## 空闲链表机制
|
||||
*
|
||||
* 删除元素时，该槽位被加入空闲链表：
|
||||
* 1. 调用元素的析构函数
|
||||
* 2. 将当前 `_next_free_index` 值写入该槽位（作为链表下一个节点）
|
||||
* 3. 更新 `_next_free_index` 指向该槽位
|
||||
*
|
||||
* 添加元素时，优先从空闲链表获取槽位：
|
||||
* 1. 如果 `_next_free_index` 有效，复用该槽位
|
||||
* 2. 从槽位中读取下一个空闲索引，更新 `_next_free_index`
|
||||
* 3. 否则，在数组末尾追加新元素
|
||||
*
|
||||
* ## 类型要求
|
||||
*
|
||||
* 由于空闲槽位需要存储 u32 索引，要求：
|
||||
* - `sizeof(T) >= sizeof(u32)`（至少 4 字节）
|
||||
*
|
||||
* ## 使用场景
|
||||
*
|
||||
* - 游戏对象管理（实体 ID 系统）
|
||||
* - 资源句柄管理（纹理、网格等）
|
||||
* - 渲染表面管理（多窗口场景）
|
||||
* - 任何需要稳定索引句柄的系统
|
||||
*
|
||||
* ## 注意事项
|
||||
*
|
||||
* - 删除后的索引可能被新元素复用，外部系统需要处理这种情况
|
||||
* - 不保证元素在内存中的顺序
|
||||
* - 与 std::vector 配合使用时可能触发重复构造（见 USE_STL_VECTOR 宏）
|
||||
*
|
||||
* @example
|
||||
* @code
|
||||
* utl::free_list<game_object> objects;
|
||||
*
|
||||
* // 添加对象
|
||||
* u32 id1 = objects.add(player_data);
|
||||
* u32 id2 = objects.add(enemy_data);
|
||||
*
|
||||
* // 访问对象
|
||||
* objects[id1].update();
|
||||
*
|
||||
* // 删除对象（槽位被回收）
|
||||
* objects.remove(id1);
|
||||
*
|
||||
* // 新对象可能复用 id1 的槽位
|
||||
* u32 id3 = objects.add(new_data); // id3 可能等于 id1
|
||||
* @endcode
|
||||
*
|
||||
* @see utl::vector
|
||||
* @see DEFINE_TYPED_ID
|
||||
*/
|
||||
#pragma once
|
||||
#include "CommonHeader.h"
|
||||
@@ -13,23 +99,42 @@
|
||||
namespace XEngine::utl {
|
||||
|
||||
#if USE_STL_VECTOR
|
||||
#pragma message("WARNING: using utl::free_list with std::vector result in duplicate calls to class constructor!");
|
||||
#pragma message("WARNING: using utl::free_list with std::vector result in duplicate calls to class constructor!")
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @class free_list
|
||||
* @brief 带槽位复用机制的稀疏对象容器
|
||||
*
|
||||
* @tparam T 元素类型，必须满足 `sizeof(T) >= sizeof(u32)`
|
||||
*
|
||||
* @details
|
||||
* 该容器使用空闲链表管理已删除的槽位，实现 O(1) 的增删操作。
|
||||
* 特别适合需要稳定索引句柄的场景，如游戏对象管理、资源句柄等。
|
||||
*/
|
||||
template<typename T>
|
||||
class free_list
|
||||
{
|
||||
static_assert(sizeof(T) >= sizeof(u32));
|
||||
static_assert(sizeof(T) >= sizeof(u32), "Type T must be at least 4 bytes to store free list indices");
|
||||
|
||||
public:
|
||||
/**
|
||||
* @brief 构造空容器。
|
||||
* @brief 默认构造函数，创建空容器
|
||||
*
|
||||
* @details
|
||||
* 创建一个空的 free_list，不预分配任何内存。
|
||||
* 首次添加元素时会触发内存分配。
|
||||
*/
|
||||
free_list() = default;
|
||||
|
||||
/**
|
||||
* @brief 预留底层存储容量。
|
||||
* @param count 预留元素数量。
|
||||
* @brief 预留容量的构造函数
|
||||
*
|
||||
* @param count 预留的元素槽位数量
|
||||
*
|
||||
* @details
|
||||
* 预分配指定数量的槽位，避免后续添加元素时的多次扩容。
|
||||
* 适用于已知大概元素数量的场景。
|
||||
*/
|
||||
explicit free_list(u32 count)
|
||||
{
|
||||
@@ -37,7 +142,11 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 销毁容器并校验无存活元素。
|
||||
* @brief 析构函数，销毁容器
|
||||
*
|
||||
* @details
|
||||
* 断言检查容器为空（_size == 0），确保所有元素已被正确移除。
|
||||
* 在 DEBUG 模式下使用 USE_STL_VECTOR 时，会清空内存以便检测悬空引用。
|
||||
*/
|
||||
~free_list()
|
||||
{
|
||||
@@ -49,10 +158,23 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 新增一个元素并返回槽位 ID。
|
||||
* @tparam params 构造参数类型。
|
||||
* @param p 构造参数。
|
||||
* @return 新元素 ID。
|
||||
* @brief 添加新元素并返回其槽位 ID
|
||||
*
|
||||
* @tparam params 构造参数类型包
|
||||
* @param p 传递给元素构造函数的参数
|
||||
* @return 新分配的槽位 ID（u32 索引）
|
||||
*
|
||||
* @details
|
||||
* 添加元素的策略：
|
||||
* 1. **有空闲槽位**：从空闲链表头部取出一个槽位复用
|
||||
* 2. **无空闲槽位**：在数组末尾追加新元素
|
||||
*
|
||||
* 复用槽位时：
|
||||
* - 从该槽位读取下一个空闲索引，更新 `_next_free_index`
|
||||
* - 使用 placement new 在该槽位构造新元素
|
||||
*
|
||||
* @note 返回的 ID 在元素被删除前保持有效
|
||||
* @note 删除后该 ID 可能被新元素复用
|
||||
*/
|
||||
template<class ... params>
|
||||
constexpr u32 add(params&&... p)
|
||||
@@ -76,8 +198,19 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 删除指定 ID 的元素并回收到空闲链。
|
||||
* @param id 元素 ID。
|
||||
* @brief 移除指定 ID 的元素并回收其槽位
|
||||
*
|
||||
* @param id 要移除元素的槽位 ID
|
||||
*
|
||||
* @details
|
||||
* 移除元素的步骤：
|
||||
* 1. 调用元素的析构函数
|
||||
* 2. DEBUG 模式下填充 0xcc 标记已删除
|
||||
* 3. 将当前 `_next_free_index` 写入该槽位（链表链接）
|
||||
* 4. 更新 `_next_free_index` 指向该槽位
|
||||
*
|
||||
* @pre id 必须是有效的已分配槽位
|
||||
* @pre 该槽位未被删除（不能重复删除）
|
||||
*/
|
||||
constexpr void remove(u32 id)
|
||||
{
|
||||
@@ -91,28 +224,35 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 获取当前有效元素数量。
|
||||
* @return 元素数量。
|
||||
* @brief 获取当前有效元素数量
|
||||
*
|
||||
* @return 容器中有效元素的个数
|
||||
*
|
||||
* @note 这与 capacity() 不同，size() 返回实际存储的元素数
|
||||
*/
|
||||
constexpr u32 size() const
|
||||
{
|
||||
return _size;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 获取当前已分配槽位总数。
|
||||
* @return 容量值。
|
||||
* @brief 获取已分配槽位总数
|
||||
*
|
||||
* @return 底层数组的大小（包括空闲槽位）
|
||||
*
|
||||
* @details
|
||||
* 返回值 >= size()，因为可能存在已删除但未释放的槽位。
|
||||
* 这些槽位会在后续添加元素时被复用。
|
||||
*/
|
||||
constexpr u32 capacity() const
|
||||
{
|
||||
return _array.size();
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 判断容器是否为空。
|
||||
* @return 空返回 true。
|
||||
* @brief 检查容器是否为空
|
||||
*
|
||||
* @return 如果容器中没有有效元素则返回 true
|
||||
*/
|
||||
constexpr bool empty() const
|
||||
{
|
||||
@@ -120,9 +260,12 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 按 ID 访问元素。
|
||||
* @param id 元素 ID。
|
||||
* @return 元素引用。
|
||||
* @brief 通过 ID 访问元素（可修改）
|
||||
*
|
||||
* @param id 元素的槽位 ID
|
||||
* @return 元素的引用
|
||||
*
|
||||
* @pre id 必须有效且指向未删除的元素
|
||||
*/
|
||||
[[nodiscard]] constexpr T& operator[](u32 id)
|
||||
{
|
||||
@@ -131,9 +274,12 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 按 ID 访问常量元素。
|
||||
* @param id 元素 ID。
|
||||
* @return 常量元素引用。
|
||||
* @brief 通过 ID 访问元素（只读）
|
||||
*
|
||||
* @param id 元素的槽位 ID
|
||||
* @return 元素的常量引用
|
||||
*
|
||||
* @pre id 必须有效且指向未删除的元素
|
||||
*/
|
||||
[[nodiscard]] constexpr const T& operator[](u32 id) const
|
||||
{
|
||||
@@ -142,6 +288,18 @@ public:
|
||||
}
|
||||
|
||||
private:
|
||||
/**
|
||||
* @brief 检查指定槽位是否已被删除
|
||||
*
|
||||
* @param id 要检查的槽位 ID
|
||||
* @return 如果槽位已被删除则返回 true
|
||||
*
|
||||
* @details
|
||||
* 通过检查槽位内容是否被 0xcc 填充来判断是否已删除。
|
||||
* 仅在 sizeof(T) > sizeof(u32) 时有效，否则直接返回 true。
|
||||
*
|
||||
* @note 仅用于断言检查，确保不会访问已删除的元素
|
||||
*/
|
||||
constexpr bool already_removed(u32 id) const
|
||||
{
|
||||
if constexpr (sizeof(T) > sizeof(u32))
|
||||
|
||||
@@ -1,11 +1,66 @@
|
||||
/**
|
||||
* @file Vector.h
|
||||
* @brief 自定义动态数组容器实现。
|
||||
* @brief 自定义动态数组容器实现
|
||||
*
|
||||
* @details
|
||||
* 该容器提供接近 std::vector 的常用能力，并支持可选析构策略：
|
||||
* - 动态扩容、插入、删除与无序删除；
|
||||
* - 连续内存访问与迭代器接口；
|
||||
* - 在性能敏感场景下复用底层内存分配行为。
|
||||
* 该容器提供与 std::vector 相似的功能，同时支持可选的析构策略。
|
||||
* 设计目标是在性能敏感场景下提供更精细的内存管理控制。
|
||||
*
|
||||
* ## 核心特性
|
||||
*
|
||||
* - **动态扩容**：自动管理内存，支持预留容量避免频繁分配
|
||||
* - **连续内存**：元素在内存中连续存储，缓存友好
|
||||
* - **可选析构**：通过模板参数控制是否在删除时调用元素析构函数
|
||||
* - **迭代器支持**：提供 begin()/end() 支持范围 for 循环
|
||||
*
|
||||
* ## 与 std::vector 的区别
|
||||
*
|
||||
* | 特性 | utl::vector | std::vector |
|
||||
* |------|-------------|-------------|
|
||||
* | 析构控制 | 可选模板参数 | 始终析构 |
|
||||
* | 内存分配 | realloc | allocator |
|
||||
* | 无序删除 | erase_unordered | 无 |
|
||||
*
|
||||
* ## 析构策略
|
||||
*
|
||||
* 模板参数 `destruct` 控制元素析构行为：
|
||||
* - `destruct = true`（默认）：删除元素时调用析构函数
|
||||
* - `destruct = false`：跳过析构，适用于 POD 类型或外部管理生命周期
|
||||
*
|
||||
* ## 扩容策略
|
||||
*
|
||||
* 当容量不足时，按 `(capacity + 1) * 1.5` 扩容：
|
||||
* - 初始容量 0 → 1
|
||||
* - 容量 4 → 6
|
||||
* - 容量 10 → 15
|
||||
*
|
||||
* ## 无序删除优化
|
||||
*
|
||||
* `erase_unordered()` 通过将末尾元素移动到删除位置实现 O(1) 删除，
|
||||
* 适用于元素顺序不重要的场景。
|
||||
*
|
||||
* @example
|
||||
* @code
|
||||
* // 基本使用
|
||||
* utl::vector<int> nums;
|
||||
* nums.push_back(1);
|
||||
* nums.push_back(2);
|
||||
* nums.emplace_back(3);
|
||||
*
|
||||
* // 遍历
|
||||
* for (int& n : nums) {
|
||||
* n *= 2;
|
||||
* }
|
||||
*
|
||||
* // 无序删除（高效但不保证顺序）
|
||||
* nums.erase_unordered(0); // 用末尾元素替换位置 0
|
||||
*
|
||||
* // POD 类型优化（跳过析构）
|
||||
* utl::vector<float, false> vertices;
|
||||
* vertices.resize(1000); // 不调用析构函数
|
||||
* @endcode
|
||||
*
|
||||
* @see utl::free_list
|
||||
*/
|
||||
#pragma once
|
||||
#include "CommonHeader.h"
|
||||
@@ -13,24 +68,40 @@
|
||||
namespace XEngine::utl {
|
||||
|
||||
/**
|
||||
* @brief 自定义连续内存动态数组。
|
||||
* @tparam T 元素类型。
|
||||
* @tparam destruct 是否在删除时调用析构。
|
||||
* @class vector
|
||||
* @brief 自定义连续内存动态数组
|
||||
*
|
||||
* @tparam T 元素类型
|
||||
* @tparam destruct 是否在删除时调用析构函数，默认为 true
|
||||
*
|
||||
* @details
|
||||
* 提供动态数组的完整功能，包括动态扩容、插入、删除等操作。
|
||||
* 通过模板参数控制析构行为，适用于不同性能需求场景。
|
||||
*/
|
||||
template<typename T, bool destruct = true>
|
||||
class vector
|
||||
{
|
||||
|
||||
public:
|
||||
// Default constructor. Doesn~t allocate memory.
|
||||
/**
|
||||
* @brief 构造空容器。
|
||||
* @brief 默认构造函数，创建空容器
|
||||
*
|
||||
* @details
|
||||
* 创建一个空的 vector，不分配任何内存。
|
||||
* 首次添加元素时会触发内存分配。
|
||||
*/
|
||||
vector() = default;
|
||||
|
||||
/**
|
||||
* @brief 构造并调整到指定元素数量。
|
||||
* @param count 目标元素数量。
|
||||
* @brief 构造并调整到指定元素数量
|
||||
*
|
||||
* @param count 目标元素数量
|
||||
*
|
||||
* @details
|
||||
* 创建包含 count 个默认构造元素的容器。
|
||||
* 要求类型 T 必须可默认构造。
|
||||
*
|
||||
* @pre T 必须满足 is_default_constructible
|
||||
*/
|
||||
constexpr explicit vector(u64 count)
|
||||
{
|
||||
@@ -38,20 +109,45 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 构造并填充指定数量元素。
|
||||
* @param count 目标元素数量。
|
||||
* @param value 填充值。
|
||||
* @brief 构造并填充指定数量元素
|
||||
*
|
||||
* @param count 目标元素数量
|
||||
* @param value 用于填充的值
|
||||
*
|
||||
* @details
|
||||
* 创建包含 count 个元素副本的容器。
|
||||
* 要求类型 T 必须可拷贝构造。
|
||||
*
|
||||
* @pre T 必须满足 is_copy_constructible
|
||||
*/
|
||||
constexpr explicit vector(u64 count, const T& value)
|
||||
{
|
||||
resize(count, value);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 拷贝构造函数
|
||||
*
|
||||
* @param o 要拷贝的源容器
|
||||
*
|
||||
* @details
|
||||
* 创建源容器的深拷贝，包括所有元素。
|
||||
* 新容器具有独立的内存空间。
|
||||
*/
|
||||
constexpr vector(const vector& o)
|
||||
{
|
||||
*this = o;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 移动构造函数
|
||||
*
|
||||
* @param o 要移动的源容器
|
||||
*
|
||||
* @details
|
||||
* 转移源容器的所有权，不进行元素拷贝。
|
||||
* 移动后源容器处于空状态。
|
||||
*/
|
||||
constexpr vector(vector&& o)
|
||||
:_capacity{o._capacity},
|
||||
_size{o._size},
|
||||
@@ -60,7 +156,15 @@ public:
|
||||
o.reset();
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 拷贝赋值运算符
|
||||
*
|
||||
* @param o 要拷贝的源容器
|
||||
* @return 当前容器的引用
|
||||
*
|
||||
* @details
|
||||
* 清空当前容器，然后深拷贝源容器的所有元素。
|
||||
*/
|
||||
constexpr vector& operator=(const vector& o)
|
||||
{
|
||||
assert(this != std::addressof(o));
|
||||
@@ -78,6 +182,15 @@ public:
|
||||
return *this;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 移动赋值运算符
|
||||
*
|
||||
* @param o 要移动的源容器
|
||||
* @return 当前容器的引用
|
||||
*
|
||||
* @details
|
||||
* 销毁当前容器的资源，然后转移源容器的所有权。
|
||||
*/
|
||||
constexpr vector& operator=(vector&& o)
|
||||
{
|
||||
assert(this != std::addressof(o));
|
||||
@@ -90,11 +203,19 @@ public:
|
||||
return *this;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 析构函数，释放所有资源
|
||||
*/
|
||||
~vector() { destroy(); }
|
||||
|
||||
/**
|
||||
* @brief 追加拷贝元素。
|
||||
* @param value 元素值。
|
||||
* @brief 在末尾追加元素的拷贝
|
||||
*
|
||||
* @param value 要追加的元素值
|
||||
*
|
||||
* @details
|
||||
* 如果容量不足，会自动扩容。
|
||||
* 内部调用 emplace_back 实现。
|
||||
*/
|
||||
constexpr void push_back(const T& value)
|
||||
{
|
||||
@@ -102,8 +223,12 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 追加右值元素。
|
||||
* @param value 元素值。
|
||||
* @brief 在末尾追加元素的右值引用
|
||||
*
|
||||
* @param value 要追加的元素值（右值）
|
||||
*
|
||||
* @details
|
||||
* 使用移动语义追加元素，避免不必要的拷贝。
|
||||
*/
|
||||
constexpr void push_back(const T&& value)
|
||||
{
|
||||
@@ -111,17 +236,24 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 原位构造并追加元素。
|
||||
* @tparam params 构造参数类型。
|
||||
* @param p 构造参数。
|
||||
* @return 新元素引用。
|
||||
* @brief 原位构造并追加元素
|
||||
*
|
||||
* @tparam params 构造参数类型包
|
||||
* @param p 传递给元素构造函数的参数
|
||||
* @return 新构造元素的引用
|
||||
*
|
||||
* @details
|
||||
* 在容器末尾原位构造新元素，避免额外的拷贝或移动操作。
|
||||
* 如果容量不足，按 1.5 倍扩容。
|
||||
*
|
||||
* @note 扩容公式：`new_capacity = (old_capacity + 1) * 3 / 2`
|
||||
*/
|
||||
template<typename... params>
|
||||
constexpr decltype(auto) emplace_back(params&&... p)
|
||||
{
|
||||
if (_size == _capacity)
|
||||
{
|
||||
reserve(((_capacity + 1) * 3) >> 1); // reserve 50% more
|
||||
reserve(((_capacity + 1) * 3) >> 1);
|
||||
}
|
||||
assert(_size < _capacity);
|
||||
|
||||
@@ -131,8 +263,15 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 调整元素数量，新增元素默认构造。
|
||||
* @param new_size 新大小。
|
||||
* @brief 调整元素数量，新增元素默认构造
|
||||
*
|
||||
* @param new_size 目标元素数量
|
||||
*
|
||||
* @details
|
||||
* - 如果 new_size > 当前大小，在末尾默认构造新元素
|
||||
* - 如果 new_size < 当前大小，删除末尾多余元素
|
||||
*
|
||||
* @pre T 必须满足 is_default_constructible
|
||||
*/
|
||||
constexpr void resize(u64 new_size)
|
||||
{
|
||||
@@ -161,11 +300,17 @@ public:
|
||||
assert(new_size == _size);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 调整元素数量，新增元素使用给定值填充。
|
||||
* @param new_size 新大小。
|
||||
* @param value 填充值。
|
||||
* @brief 调整元素数量，新增元素使用给定值填充
|
||||
*
|
||||
* @param new_size 目标元素数量
|
||||
* @param value 用于填充新元素的值
|
||||
*
|
||||
* @details
|
||||
* - 如果 new_size > 当前大小，在末尾拷贝构造新元素
|
||||
* - 如果 new_size < 当前大小，删除末尾多余元素
|
||||
*
|
||||
* @pre T 必须满足 is_copy_constructible
|
||||
*/
|
||||
constexpr void resize(u64 new_size, const T& value)
|
||||
{
|
||||
@@ -194,17 +339,21 @@ public:
|
||||
assert(new_size == _size);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 预留最小容量。
|
||||
* @param new_capacity 目标容量。
|
||||
* @brief 预留最小容量
|
||||
*
|
||||
* @param new_capacity 目标容量
|
||||
*
|
||||
* @details
|
||||
* 如果 new_capacity > 当前容量，重新分配更大的内存块。
|
||||
* 使用 realloc 实现，会自动复制原有数据。
|
||||
*
|
||||
* @note 此函数只会增加容量，不会减少
|
||||
*/
|
||||
constexpr void reserve(u64 new_capacity)
|
||||
{
|
||||
if (new_capacity > _capacity)
|
||||
{
|
||||
// NOTE: realoc() will automatically copy the data in the buffer
|
||||
// if a new region of memory iss allocated.
|
||||
void* new_buffer{ realloc(_data, new_capacity * sizeof(T)) };
|
||||
assert(new_buffer);
|
||||
if (new_buffer)
|
||||
@@ -216,9 +365,16 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 删除指定下标元素并保持顺序。
|
||||
* @param index 删除下标。
|
||||
* @return 指向删除位置的指针。
|
||||
* @brief 删除指定下标元素并保持顺序
|
||||
*
|
||||
* @param index 要删除元素的下标
|
||||
* @return 指向删除位置后一个元素的指针
|
||||
*
|
||||
* @details
|
||||
* 删除元素后，将后续所有元素向前移动一位。
|
||||
* 时间复杂度 O(n)。
|
||||
*
|
||||
* @pre index 必须小于当前元素数量
|
||||
*/
|
||||
constexpr T *const erase(u64 index)
|
||||
{
|
||||
@@ -227,9 +383,16 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 删除指定位置元素并保持顺序。
|
||||
* @param item 待删除元素指针。
|
||||
* @return 指向删除位置的指针。
|
||||
* @brief 删除指定位置元素并保持顺序
|
||||
*
|
||||
* @param item 指向要删除元素的指针
|
||||
* @return 指向删除位置后一个元素的指针
|
||||
*
|
||||
* @details
|
||||
* 删除元素后，将后续所有元素向前移动一位。
|
||||
* 时间复杂度 O(n)。
|
||||
*
|
||||
* @pre item 必须指向容器内的有效元素
|
||||
*/
|
||||
constexpr T *const erase(T *const item)
|
||||
{
|
||||
@@ -247,9 +410,18 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 无序删除指定下标元素。
|
||||
* @param index 删除下标。
|
||||
* @return 指向删除位置的指针。
|
||||
* @brief 无序删除指定下标元素
|
||||
*
|
||||
* @param index 要删除元素的下标
|
||||
* @return 指向删除位置的指针
|
||||
*
|
||||
* @details
|
||||
* 用末尾元素替换被删除元素，然后减少大小。
|
||||
* 时间复杂度 O(1)，但不保证元素顺序。
|
||||
*
|
||||
* @pre index 必须小于当前元素数量
|
||||
*
|
||||
* @note 适用于元素顺序不重要的场景
|
||||
*/
|
||||
constexpr T *const erase_unordered(u64 index)
|
||||
{
|
||||
@@ -258,9 +430,18 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 无序删除指定位置元素。
|
||||
* @param item 待删除元素指针。
|
||||
* @return 指向删除位置的指针。
|
||||
* @brief 无序删除指定位置元素
|
||||
*
|
||||
* @param item 指向要删除元素的指针
|
||||
* @return 指向删除位置的指针
|
||||
*
|
||||
* @details
|
||||
* 用末尾元素替换被删除元素，然后减少大小。
|
||||
* 时间复杂度 O(1)，但不保证元素顺序。
|
||||
*
|
||||
* @pre item 必须指向容器内的有效元素
|
||||
*
|
||||
* @note 适用于元素顺序不重要的场景
|
||||
*/
|
||||
constexpr T *const erase_unordered(T *const item)
|
||||
{
|
||||
@@ -279,7 +460,11 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 清空容器中的有效元素。
|
||||
* @brief 清空容器中的所有元素
|
||||
*
|
||||
* @details
|
||||
* 调用所有元素的析构函数（如果 destruct = true），
|
||||
* 然后将大小设为 0。不释放底层内存。
|
||||
*/
|
||||
constexpr void clear()
|
||||
{
|
||||
@@ -290,10 +475,14 @@ public:
|
||||
_size = 0;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 与另一个容器交换内容。
|
||||
* @param o 目标容器。
|
||||
* @brief 与另一个容器交换内容
|
||||
*
|
||||
* @param o 目标容器
|
||||
*
|
||||
* @details
|
||||
* 交换两个容器的所有权，不进行元素拷贝。
|
||||
* 时间复杂度 O(1)。
|
||||
*/
|
||||
constexpr void swap(vector& o)
|
||||
{
|
||||
@@ -305,20 +494,20 @@ public:
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 返回底层数据指针。
|
||||
* @return 数据首地址。
|
||||
* @brief 返回底层数据指针
|
||||
*
|
||||
* @return 指向第一个元素的指针
|
||||
*/
|
||||
[[nodiscard]] constexpr T* data()
|
||||
{
|
||||
return _data;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 返回只读底层数据指针。
|
||||
* @return 数据首地址。
|
||||
* @brief 返回只读底层数据指针
|
||||
*
|
||||
* @return 指向第一个元素的常量指针
|
||||
*/
|
||||
[[nodiscard]] constexpr T *const data() const
|
||||
{
|
||||
@@ -326,8 +515,9 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 判断容器是否为空。
|
||||
* @return 空返回 true。
|
||||
* @brief 判断容器是否为空
|
||||
*
|
||||
* @return 如果容器中没有元素则返回 true
|
||||
*/
|
||||
[[nodiscard]] constexpr bool empty() const
|
||||
{
|
||||
@@ -335,87 +525,160 @@ public:
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 获取元素个数。
|
||||
* @return 元素数量。
|
||||
* @brief 获取元素个数
|
||||
*
|
||||
* @return 容器中当前存储的元素数量
|
||||
*/
|
||||
[[nodiscard]] constexpr u64 size() const
|
||||
{
|
||||
return _size;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 获取当前容量。
|
||||
* @return 容量值。
|
||||
* @brief 获取当前容量
|
||||
*
|
||||
* @return 容器当前分配的存储空间可容纳的元素数量
|
||||
*/
|
||||
[[nodiscard]] constexpr u64 capacity() const
|
||||
{
|
||||
return _capacity;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 下标访问运算符（可修改）
|
||||
*
|
||||
* @param index 元素下标
|
||||
* @return 元素的引用
|
||||
*
|
||||
* @pre index 必须小于当前元素数量
|
||||
*/
|
||||
[[nodiscard]] constexpr T& operator [](u64 index)
|
||||
{
|
||||
assert(_data && index < _size);
|
||||
return _data[index];
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 下标访问运算符（只读）
|
||||
*
|
||||
* @param index 元素下标
|
||||
* @return 元素的常量引用
|
||||
*
|
||||
* @pre index 必须小于当前元素数量
|
||||
*/
|
||||
[[nodiscard]] constexpr const T& operator [](u64 index) const
|
||||
{
|
||||
assert(_data && index < _size);
|
||||
return _data[index];
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 访问第一个元素（可修改）
|
||||
*
|
||||
* @return 第一个元素的引用
|
||||
*
|
||||
* @pre 容器必须非空
|
||||
*/
|
||||
[[nodiscard]] constexpr T& front()
|
||||
{
|
||||
assert(_data && _size);
|
||||
return _data[0];
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 访问第一个元素（只读）
|
||||
*
|
||||
* @return 第一个元素的常量引用
|
||||
*
|
||||
* @pre 容器必须非空
|
||||
*/
|
||||
[[nodiscard]] constexpr const T& front() const
|
||||
{
|
||||
assert(_data && _size);
|
||||
return _data[0];
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 访问最后一个元素（可修改）
|
||||
*
|
||||
* @return 最后一个元素的引用
|
||||
*
|
||||
* @pre 容器必须非空
|
||||
*/
|
||||
[[nodiscard]] constexpr T& back()
|
||||
{
|
||||
assert(_data && _size);
|
||||
return _data[_size -1];
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 访问最后一个元素（只读）
|
||||
*
|
||||
* @return 最后一个元素的常量引用
|
||||
*
|
||||
* @pre 容器必须非空
|
||||
*/
|
||||
[[nodiscard]] constexpr const T& back() const
|
||||
{
|
||||
assert(_data && _size);
|
||||
return _data[_size - 1];
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 返回指向首元素的迭代器
|
||||
*
|
||||
* @return 指向第一个元素的指针
|
||||
*
|
||||
* @details 支持范围 for 循环
|
||||
*/
|
||||
[[nodiscard]] constexpr T* begin()
|
||||
{
|
||||
return std::addressof(_data[0]);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* @brief 返回指向首元素的常量迭代器
|
||||
*
|
||||
* @return 指向第一个元素的常量指针
|
||||
*/
|
||||
[[nodiscard]] constexpr const T* begin() const
|
||||
{
|
||||
return std::addressof(_data[0]);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 返回指向尾后位置的迭代器
|
||||
*
|
||||
* @return 指向最后一个元素之后位置的指针
|
||||
*
|
||||
* @details 支持范围 for 循环
|
||||
*/
|
||||
[[nodiscard]] constexpr T* end()
|
||||
{
|
||||
assert(!(_data == nullptr && _size > 0));
|
||||
return std::addressof(_data[_size]);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 返回指向尾后位置的常量迭代器
|
||||
*
|
||||
* @return 指向最后一个元素之后位置的常量指针
|
||||
*/
|
||||
[[nodiscard]] constexpr const T* end() const
|
||||
{
|
||||
assert(!(_data == nullptr && _size > 0));
|
||||
return std::addressof(_data[_size]);
|
||||
}
|
||||
private:
|
||||
|
||||
private:
|
||||
/**
|
||||
* @brief 从另一个容器转移所有权
|
||||
*
|
||||
* @param o 源容器
|
||||
*
|
||||
* @details
|
||||
* 复制源容器的成员变量，然后将源容器重置为空状态。
|
||||
*/
|
||||
constexpr void move(vector& o)
|
||||
{
|
||||
_capacity = o._capacity;
|
||||
@@ -424,6 +687,12 @@ private:
|
||||
o.reset();
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 重置容器为空状态
|
||||
*
|
||||
* @details
|
||||
* 将所有成员变量设为初始值，不释放内存。
|
||||
*/
|
||||
constexpr void reset()
|
||||
{
|
||||
_capacity = 0;
|
||||
@@ -431,6 +700,16 @@ private:
|
||||
_data = nullptr;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 析构指定范围内的元素
|
||||
*
|
||||
* @param first 起始索引
|
||||
* @param last 结束索引（不包含）
|
||||
*
|
||||
* @details
|
||||
* 对 [first, last) 范围内的每个元素调用析构函数。
|
||||
* 仅在 destruct = true 时有效。
|
||||
*/
|
||||
constexpr void destruct_range(u64 first, u64 last)
|
||||
{
|
||||
assert(destruct);
|
||||
@@ -444,6 +723,12 @@ private:
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief 销毁容器，释放所有资源
|
||||
*
|
||||
* @details
|
||||
* 清空所有元素，释放底层内存，重置容量为 0。
|
||||
*/
|
||||
constexpr void destroy()
|
||||
{
|
||||
assert([&] {return _capacity ? _data != nullptr : _data == nullptr; }());
|
||||
@@ -458,6 +743,4 @@ private:
|
||||
T* _data{ nullptr };
|
||||
};
|
||||
|
||||
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user