Type-Safe, Zero-Overhead, Robin Hood Hash Map for C/C++.

zmap.h is a single-header library that brings the ergonomics of high-level languages to C without sacrificing performance. It uses Robin Hood Hashing with Backward Shift Deletion to maintain high load factors (up to 0.9) while keeping probe lengths short and cache-friendly.

It features a unified API via C11 _Generic, strict type safety (no void* casting), and a zero-cost C++ wrapper that provides STL-compatible iterators.

• Robin Hood Hashing: Minimizes probe variance, enabling high load factors without performance degradation.
• Fibonacci Indexing: Mathematically optimal distribution ($hash \times \phi$) protects against poor hash functions.
• Two Storage Modes:
  1. Standard: Keys/Values stored inline (contiguous memory) for maximum cache locality.
  2. Stable: Values stored on the heap. Pointers to values remain valid after resizes.
• Type Safety: Compiler errors on type mismatches. No void* overhead.
• WyHash Support: Automatically uses the ultra-fast WyHash algorithm if zhash.h is present.
• C++ Interop: Zero-cost z_map::map<K,V> wrapper with RAII and STL-compatible iterators.
• Safe API: Optional zerror.h integration for stack traces and error handling.

zmap.h works best when you use the provided scanner script to manage type registrations, though it can be used manually.

1. Copy zmap.h (and zcommon.h if separated) to your project's include folder.
2. (Recommended) Copy zhash.h to the same folder for improved string hashing performance.
3. Add the z-core tools (optional but recommended):

git submodule add https://github.com/z-libs/z-core.git z-core

If you use the clib package manager, run:

clib install z-libs/zdk

If you use the Zen Development Kit, it is included automatically by including <zdk/zmap.h> (or <zdk/zworld.h>).

View Live Benchmark Results.

Comparison vs uthash (standard C hash map) managing 1,000,000 string keys:

Note: Benchmarks run on GitHub Actions (Ubuntu/Azure). Local native performance is often higher.

For C projects, you must register the map types you need. This can be done via the scanner script (which detects usage) or manually via the Registry Header.

Create a header (for example, types.h) to define your maps using X-Macros.

#ifndef TYPES_H
#define TYPES_H

// Syntax: X(KeyType, ValueType, ShortName)
#define REGISTER_ZMAP_TYPES(X)      \
    X(const char*, int, StrInt)     \
    X(uint64_t, float, IdF32)

#include "zmap.h"

#endif

#include "types.h"

// Helper: Hashing and Comparison.
uint32_t hash_str(const char* k, uint32_t seed) { return ZMAP_HASH_STR(k, seed); }
int cmp_str(const char* a, const char* b) { return strcmp(a, b); }

int main(void) 
{
    // Initialize (Name, HashFunc, CmpFunc).
    zmap_StrInt scores = zmap_init(StrInt, hash_str, cmp_str);

    // Insert (Returns Z_OK or Z_ENOMEM).
    zmap_put(&scores, "Alice", 100);
    zmap_put(&scores, "Bob", 200);

    // Retrieve (Returns pointer to value, or NULL).
    int *val = zmap_get(&scores, "Alice");
    if (val) 
    {
        printf("Alice: %d\n", *val);
    }

    // Cleanup.
    zmap_free(&scores);
    return 0;
}

If you prefer a cleaner API and don't worry about namespace collisions, define ZMAP_SHORT_NAMES before including the header.

#define ZMAP_SHORT_NAMES
#include "zmap.h"

// Now you can use:
map(StrInt) m = map_init(StrInt, ...);
map_put(&m, k, v);
map_get(&m, k);

The C++ wrapper z_map::map is a zero-overhead abstraction. It uses the same generated C code under the hood but adds RAII and iterators.

#include <iostream>

// Register types (visible to C++ compiler).
#define REGISTER_ZMAP_TYPES(X) \
    X(int, float, IntFloat)

#include "zmap.h"

int main() 
{
    // Constructor handles init and seed.
    z_map::map<int, float> data(
        [](int k, uint32_t s) { return zhash_uint32(k) ^ s; }, // Hash.
        [](int a, int b) { return a - b; }                     // Compare.
    );

    // STL-style insertion.
    data.put(42, 3.14f);
        
    // STL-compatible Iterators.
    for (auto& bucket : data) 
    {
        std::cout << bucket.key << ": " << bucket.value << "\n";
    }
        
    // Automatic cleanup (Destructor calls zmap_free).
    return 0;
}

Standard zmap stores values inline for speed. If you need pointers to values to remain valid after resizes (e.g., for graph nodes), use a Stable Map.

// In your registry:
#define REGISTER_STABLE_MAPS(X) \
    X(const char*, MyStruct, MyStable)

// Usage:
zmap_stable_MyStable m = zmap_init_stable(MyStable, hash_fn, cmp_fn);
MyStruct* ptr = zmap_get(&m, "key"); 
// 'ptr' is now valid until the key is removed, even if map resizes.

zmap.h automatically detects zhash.h.

• Without zhash.h: Uses FNV-1a (Simple, inline fallback).
• With zhash.h: Uses WyHash (SIMD-optimized, high quality).

Recommendation: Always include zhash.h when using string keys.

If zerror.h is present, zmap generates "Safe" versions of critical functions. These functions return zres (Result) types containing error information and stack traces on failure.

The library uses _Generic dispatch, so the same macro names work for all registered map types.

The C++ wrapper lives in the z_map namespace. It strictly adheres to RAII principles.

Constructors & Management

Access & Modification

Iterators

You can override the memory allocators globally or specifically for maps.

// Global Override
#define ZMAP_MALLOC  my_malloc
#define ZMAP_FREE    my_free
#define ZMAP_REALLOC my_realloc
#define ZMAP_CALLOC  my_calloc