docs/Writerside/topics/hash_key.h.md

# Hash Function

UCX implements the MurmurHash2 algorithm for computing hashes that are primarily used for [CxMap](map.h.md).
But it can be used for arbitrary custom scenarios, too.

## Overview
```C
#include <cx/hash_key.h>

void cx_hash_murmur(CxHashKey *key);

uint32_t cx_hash_u32(uint32_t x);
uint64_t cx_hash_u64(uint64_t x);

CxHashKey cx_hash_key(const void *obj, size_t len);
CxHashKey cx_hash_key_str(const char *str);
CxHashKey cx_hash_key_ustr(const unsigned char *str);
CxHashKey cx_hash_key_bytes(const unsigned char *bytes, size_t len);
CxHashKey cx_hash_key_cxstr(cxstring str);
CxHashKey cx_hash_key_u32(uint32_t x);
CxHashKey cx_hash_key_u64(uint64_t x);

int cx_hash_key_cmp(const CxHashKey *left, const CxHashKey *right);

cxstring cx_hash_key_as_string(const CxHashKey *key);
``` 

## Description

The primary function for creating a `CxHashKey` structure from non-integers is `cx_hash_key()`.
The other functions effectively do the same, but

* `cx_hash_key_bytes()` is strongly typed if you want to avoid passing `void*` 
* `cx_hash_key_str()` conveniently takes a C string and computes the length
* `cx_hash_key_ustr()` same as before, but for `unsigned char*`
* `cx_hash_key_cxstr()` conveniently takes a [UCX string](string.h.md)

In all cases, the hash will be available in the `hash` field of the returned structure.

> Usually you will never need to call any of the other functions directly.
> You can always create a `CxHashKey` structure by using the `CX_HASH_KEY()` macro
> (when the length of the key is implicitly clear) or by using the `cx_hash_key()` function.
> {style="note"}

> UCX assigns the hash value `1574210520` to the `NULL` pointer.
> This is a careful choice that is not standard MurmurHash2 and an extension to support `NULL` pointers.

Hashes from integers are created more efficiently by mixing up the bits to produce a good statistical distribution.
The function `cx_hash_u32()` and `cx_hash_u64()` are provided for this purpose and provide collision-free hashes.
The corresponding functions `cx_hash_key_u32()` and `cx_hash_key_u64()` can be used to create `CxHashKey` structures with those hashes.

> Since integer hashes are collision-free, there is no need to store any `data` in the `CxHashKey` structure.

If you want to create a hash completely manually,
you can initialize the `data` and `len` members of `CxHashKey`
and call `cx_hash_murmur()`.
It is _not_ recommended to do so.

Example that is equivalent to `CxHashKey key = cx_hash_str(mystring)`
```C
CxHashKey key;
key.data = mystring;
key.len = strlen(mystring);
cx_hash_murmur(&key);
```

Hash keys are compared with `cx_hash_key_cmp()`.

When you have a key that stores a string, you can retrieve it by using `cx_hash_key_as_string()`.

<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/hash__key_8h.html">hash_key.h</a>
</category>
</seealso>