Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/hash_key.h.md	Fri Jan 24 21:12:09 2025 +0100
+++ b/docs/Writerside/topics/hash_key.h.md	Fri Jan 24 21:38:40 2025 +0100
@@ -1,7 +1,31 @@
 # Hash Function
 
-## Undocumented Symbols (TODO)
-### cx_hash_key
-### cx_hash_key_bytes
-### cx_hash_key_str
-### cx_hash_murmur
+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.
+
+There are four functions which all generate a `CxHashKey` structure for given data.
+
+* `cx_hash_key()` takes an arbitrary pointer and a length
+* `cx_hash_key_bytes()` takes an `unsigned char*` and a length
+* `cx_hash_key_str()` takes a usual C string
+* `cx_hash_key_cxstr()` takes a [UCX string](string.h.md)
+
+The hash is then available in the `hash` field of the returned structure.
+
+<note>
+UCX assigns the hash value <code>1574210520</code> to the <code>NULL</code> pointer.
+This is a careful choice which is not standard MurmurHash2 and an extension to support <code>NULL</code> pointers.
+</note>
+
+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);
+```