Hash Function

UCX implements the MurmurHash2 algorithm for computing hashes that are primarily used for CxMap. But it can be used for arbitrary custom scenarios, too.

Overview

#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 nonintegers 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

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

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.

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)

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().

31 December 2025