XCEngine/docs/api/XCEngine/Core/Containers/Containers.md

Containers

命名空间: XCEngine::Containers

类型: submodule

头文件: XCEngine/Core/Containers/Containers.h

描述: 定义引擎自定义字符串、动态数组和哈希表等基础容器。

概览

Core/Containers 是当前引擎最底层的数据结构层之一。它提供的不是一整套 STL 替代品，而是一组在引擎内部频繁出现、接口风格统一的基础容器：

• String
• Array
• HashMap

从设计方向看，这和商业引擎里常见的“自定义基础容器层”很像。这样做的好处是：

• 对外 API 风格统一
• 可以逐步引入引擎自己的分配器和调试支持
• 跨模块时不必把标准库类型直接暴露到所有接口里

但按当前实现，它们仍然是轻量容器，而不是 fully-featured STL 等价物。

umbrella header

Containers.h 当前只是一个聚合头文件，负责包含：

• Array.h
• String.h
• HashMap.h

它自身没有新增独立类型，所以这里直接把它并入模块页说明，不再保留一份重复的 Containers/Containers.md 类型页。

设计要点

• Array 和 HashMap 当前都是头文件模板实现。
• String 采用单独 .cpp，用堆分配维护可变字符缓冲。
• 三个容器都使用值语义，但当前都偏“简单直接实现”，而不是“最大化性能和异常安全”的成熟版本。
• Array::SetAllocator() 和 HashMap::SetAllocator() 当前只是记录指针，没有真正接管底层分配。

当前实现现状

• String 已覆盖最常用的拼接、子串、前后缀和大小写转换能力。
• Array 已可覆盖大部分顺序容器用途，但没有边界检查，也没有完整 allocator 接入。
• HashMap 已可用于基本查找和插入，但迭代器语义与 operator[] 的扩容返回路径都还存在当前实现问题。

头文件

• Array - Array.h
• HashMap - HashMap.h
• String - String.h

推荐阅读顺序

1. 先读 String，理解当前项目里最常见的自定义字符串约定。
2. 再读 Array，这是其他模块最常用的顺序容器。
3. 最后读 HashMap，注意它当前的迭代和扩容边界。

相关指南

• Custom Containers, Value Semantics, And Interop

相关文档

• 上级目录
• API 总索引