# 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

[中文文档](README.md)

This repository contains a simple implementation of a hashmap using hash buckets in C. It provides efficient key-value storage with dynamic resizing capabilities.

## Features

- **Dynamic Resizing**: Automatically resizes the hashmap based on load factor.
- **Collision Handling**: Uses linked lists to handle collisions.
- **Memory Management**: Functions for initializing, deinitializing, and clearing the hashmap.
- **Basic Operations**: Supports insertion, removal, retrieval, and checking for keys.

## Installation

To use this hashmap implementation, include the header file `hashmap.h` after you add this item to your project.

## Functions

### Initialization and Destruction

- `int hashmap_init(HashMap_t *map, size_t capacity, float load_factor)`: Initializes the hashmap.
- `void hashmap_deinit(HashMap_t *map)`: Deinitializes the hashmap.
- `HashMap_t *hashmap_new(size_t capacity, float load_factor)`: Creates a new hashmap.
- `void hashmap_del(HashMap_t *map)`: Destroys the hashmap.

### Basic Operations

- `int hashmap_insert(HashMap_t *map, uint32_t key, void *value)`: Inserts a key-value pair into the hashmap.
- `void *hashmap_remove(HashMap_t *map, uint32_t key)`: Removes a key from the hashmap and returns its value.
- `void *hashmap_get(HashMap_t *map, uint32_t key)`: Retrieves the value associated with the given key.
- `bool hashmap_contains_key(HashMap_t *map, uint32_t key)`: Checks if the hashmap contains a specific key.

### Utility Functions

- `void hashmap_clear(HashMap_t *map)`: Clears all entries in the hashmap.
- `size_t hashmap_len(HashMap_t *map)`: Returns the number of elements in the hashmap.
- `bool hashmap_is_empty(HashMap_t *map)`: Checks if the hashmap is empty.
- `size_t hashmap_capacity(HashMap_t *map)`: Returns the capacity of the hashmap.
- `int hashmap_reserve(HashMap_t *map, size_t reserve_size)`: Reserves space in the hashmap.
- `int hashmap_shrink_to(HashMap_t *map, size_t capacity)`: Shrinks the hashmap to the specified capacity.
- `int hashmap_shrink_to_fit(HashMap_t *map)`: Shrinks the hashmap to fit its current number of elements.

### Hashing Function

- `uint32_t hash_string(const char *str)`: Calculates the hash value of a string using the djb2 algorithm.

## Simple Example

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

int main(void) {
    /* Create a hashmap with an initial capacity of 10 and a load factor of 0.75 (i.e. automatically expanded when the load reaches 7.5) */
    HashMap_t *map = hashmap_new(10, 0.75);

    /* Insert key-value pair 1 = "value1" */
    hashmap_insert(map, 1, "value1");

    /* Gets a key-value pair */
    void *value = hashmap_get(map, 1);
    printf("Key 1: %s\n", (char *)value);

    /* Delete the hashmap */
    hashmap_del(map);
    return 0;
}
```

## License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

## Author

(c) 2024, MacRsh