# Containers

**命名空间**: `XCEngine::Containers`

**类型**: `submodule`

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

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

## 概览

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

- [String](String/String.md)
- [Array](Array/Array.md)
- [HashMap](HashMap/HashMap.md)

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

- 对外 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/Array.md) - `Array.h`
- [HashMap](HashMap/HashMap.md) - `HashMap.h`
- [String](String/String.md) - `String.h`

## 推荐阅读顺序

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

## 相关指南

- [Custom Containers, Value Semantics, And Interop](../../../_guides/Core/Containers/Custom-Containers-Value-Semantics-And-Interop.md)

## 相关文档

- [上级目录](../Core.md)
- [API 总索引](../../../main.md)