XCEngine/docs/api/containers/hashmap/hashmap.md

# HashMap

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

**类型**: `class` (template)

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

**描述**: 模板哈希表容器，提供键值对存储和快速查找。

## 概述

`HashMap<Key, Value>` 是一个模板哈希表容器，使用分离链接法（separate chaining）解决哈希冲突，每个桶是一个动态数组。

## 实现细节

| 参数 | 值 | 描述 |
|------|-----|------|
| 默认桶数 | 16 | `DefaultBucketCount` |
| 负载因子 | 0.75 | 当 `size / bucketCount > 0.75` 时触发扩容 |
| 扩容策略 | ×2 | 每次扩容桶数翻倍 |
| Erase 策略 | swap-with-last | 将待删除元素与最后一个元素交换，避免数组元素移动 |

## 公共类型

### 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 <XCEngine/Core/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) - 内存分配器