Set Hash Function
=================
-.. index:: object: hashkit_st
-.. index:: object: hashkit_hash_fn
-
-Set hash functions to use for calculating values for keys
-
SYNOPSIS
--------
.. type:: uint32_t (*hashkit_hash_fn)(const char *key, size_t key_length, void *context)
+ :param key: the key to generate a hash of
+ :param key_length: the length of the `key` without any terminating zero byte
+ :param context: the custom hash function context set through `hashkit_set_custom_function` or `hashkit_set_custom_distribution_function`
+ :returns: the custom hash function should return a hash value for `key` as an unsigned 32bit integer
+
+.. c:type:: enum hashkit_return_t hashkit_return_t
+
+.. enum:: hashkit_return_t
+
+ .. enumerator:: HASHKIT_SUCCESS
+
+ Operation succeeded.
+
+ .. enumerator:: HASHKIT_FAILURE
+
+ Operation failed.
+
+ .. enumerator:: HASHKIT_MEMORY_ALLOCATION_FAILURE
+
+ Memory allocation failed.
+
+ .. enumerator:: HASHKIT_INVALID_HASH
+
+ Invalid `hashkit_hash_algorithm_t` passed.
+
+ .. enumerator:: HASHKIT_INVALID_ARGUMENT
+
+ Invalid argument passed.
+
+.. c:type:: enum hashkit_hash_algorithm_t hashkit_hash_algorithm_t
+
+.. enum:: hashkit_hash_algorithm_t
+
+ .. enumerator:: HASHKIT_HASH_DEFAULT
+
+ Default hash algorithm (one_at_a_time).
+
+ .. enumerator:: HASHKIT_HASH_MD5
+ .. enumerator:: HASHKIT_HASH_CRC
+ .. enumerator:: HASHKIT_HASH_FNV1_64
+ .. enumerator:: HASHKIT_HASH_FNV1A_64
+ .. enumerator:: HASHKIT_HASH_FNV1_32
+ .. enumerator:: HASHKIT_HASH_FNV1A_32
+ .. enumerator:: HASHKIT_HASH_HSIEH
+
+ Only available if `libhashkit` hash been built with HSIEH support.
+
+ .. enumerator:: HASHKIT_HASH_MURMUR
+
+ Only available if `libhashkit` has been built with MURMUR support.
+
+ .. enumerator:: HASHKIT_HASH_MURMUR3
+
+ Only available if `libhashkit` has been built with MURMUR support.
+
+ .. enumerator:: HASHKIT_HASH_JENKINS
+ .. enumerator:: HASHKIT_HASH_CUSTOM
+
+ Use custom `hashkit_hash_fn` function set through `hashkit_set_custom_function` or `hashkit_set_custom_distribution_function`.
+
.. function:: hashkit_return_t hashkit_set_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm)
+ :param hash: pointer to an initialized `hashkit_st` struct
+ :param hash_algorithm: valid `hashkit_hash_algorithm_t` constant
+ :returns: `hashkit_return_t` indicating success or failure
+
.. function:: hashkit_return_t hashkit_set_custom_function(hashkit_st *hash, hashkit_hash_fn function, void *context)
+ :param hash: pointer to initialized `hashkit_st` struct
+ :param function: `hashkit_hash_fn` function pointer to use as hash function for `HASHKIT_HASH_CUSTOM`
+ :param context: pointer to an opaque user managed context for the custom hash function
+ :returns: `hashkit_return_t` indicating success or failure
+
.. function:: hashkit_hash_algorithm_t hashkit_get_function(const hashkit_st *hash)
+ :param hash: pointer to an initialized `hashkit_st` struct
+ :returns: `hashkit_hash_algorithm_t` indicating the currently set hash algorithm to use
+
.. function:: hashkit_return_t hashkit_set_distribution_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm)
-.. function:: hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st *self, hashkit_hash_fn function, void *context)
+ :param hash: pointer to an initialized `hashkit_st` struct
+ :param hash_algorithm: valid `hashkit_hash_algrothm_t` constant
+ :returns: `hashkit_return_t` indicating success or failure
+
+.. function:: hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st *hash, hashkit_hash_fn function, void *context)
+
+ :param hash: pointer to initialized `hashkit_st` struct
+ :param function: `hashkit_hash_fn` function pointer to use as distribution hash function for `HASHKIT_HASH_CUSTOM`
+ :param context: pointer to an opaque user managed context for the custom distribution hash function
+
+.. function:: hashkit_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *hash)
-.. function:: hashkit_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *self)
+ :param hash: pointer to an initialized `hashkit_st` struct
+ :returns: `hashkit_hash_algorithm_t` indicating the currently set distribution hash algorithm to use
DESCRIPTION
-----------
RETURN VALUE
------------
-:func:`hashkit_set_function`, :func:`hashkit_set_custom_function` and the distribution equivalents
-return :type:`hashkit_return_t` `HASHKIT_SUCCESS` on success.
+`hashkit_set_function`, `hashkit_set_custom_function` and the distribution
+equivalents return `hashkit_return_t::HASHKIT_SUCCESS` on success.
-:func:`hashkit_get_function` and :func:`hashkit_get_distribution_function` return :type:`hashkit_hash_algorithm_t`
-indicating the hash function used.
+`hashkit_get_function` and `hashkit_get_distribution_function` return
+`hashkit_hash_algorithm_t` indicating the hash function used.
SEE ALSO
--------