# HashMap

**Repository Path**: MacRsh/hash-map

## Basic Information

- **Project Name**: HashMap
- **Description**: 基于哈希桶的哈希表实现，提供高效的键值存储和动态调整功能。它支持基本操作如插入、删除和检索，并通过链表处理哈希碰撞。适合需要快速数据存取的应用场景。
- **Primary Language**: C/C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2024-08-04
- **Last Updated**: 2025-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HashMap

[English document](README_EN.md)

这个项目包含一个使用哈希桶的哈希表简单实现。提供了高效的键值存储和动态调整能力。

## 特性

- **动态调整大小**：根据负载因子自动调整哈希表大小。
- **碰撞处理**：使用链表处理哈希碰撞。
- **内存管理**：提供初始化、去初始化和清空哈希表的函数。
- **基本操作**：支持插入、删除、检索和检查键。

## 使用

要使用此哈希表实现，将此项目到您的工程中后，包含头文件 `hashmap.h`。

## 函数

### 初始化和销毁

- `int hashmap_init(HashMap_t *map, size_t capacity, float load_factor)`：初始化哈希表。
- `void hashmap_deinit(HashMap_t *map)`：去初始化哈希表。
- `HashMap_t *hashmap_new(size_t capacity, float load_factor)`：创建新的哈希表。
- `void hashmap_del(HashMap_t *map)`：销毁哈希表。

### 基本操作

- `int hashmap_insert(HashMap_t *map, uint32_t key, void *value)`：插入键值对到哈希表。
- `void *hashmap_remove(HashMap_t *map, uint32_t key)`：从哈希表中移除键并返回其值。
- `void *hashmap_get(HashMap_t *map, uint32_t key)`：获取与指定键关联的值。
- `bool hashmap_contains_key(HashMap_t *map, uint32_t key)`：检查哈希表是否包含特定键。

### 工具函数

- `void hashmap_clear(HashMap_t *map)`：清空哈希表中的所有条目。
- `size_t hashmap_len(HashMap_t *map)`：返回哈希表中的元素数量。
- `bool hashmap_is_empty(HashMap_t *map)`：检查哈希表是否为空。
- `size_t hashmap_capacity(HashMap_t *map)`：返回哈希表的容量。
- `int hashmap_reserve(HashMap_t *map, size_t reserve_size)`：在哈希表中保留空间。
- `int hashmap_shrink_to(HashMap_t *map, size_t capacity)`：将哈希表缩小到指定容量。
- `int hashmap_shrink_to_fit(HashMap_t *map)`：将哈希表缩小到适应当前元素数量。

### 哈希函数

- `uint32_t hash_string(const char *str)`：使用 djb2 算法计算字符串的哈希值。

## 简单示例

```c
#include <hashmap.h>
#include <stdio.h>

int main(void) {
    /* 创建哈希表，初始容量为10，负载因子为0.75（即当负载达到7.5时，将自动扩容）*/
    HashMap_t *map = hashmap_new(10, 0.75);

    /* 插入键值对 1 = “value1" */
    hashmap_insert(map, 1, "value1");

    /* 获取键值对 */
    void *value = hashmap_get(map, 1);
    printf("键 1: %s\n", (char *)value);

    /* 删除哈希表 */
    hashmap_del(map);
    return 0;
}
```

## 许可证

本项目使用 Apache-2.0 许可证许可。有关详细信息，请参阅 LICENSE 文件。

## 作者

(c) 2024, MacRsh