# `hash` #include "hash.h" This is the internal module for doing hash tables. A hash table uses a hash function to compute an index. On each index there is a separate linked list of entries. Create a hash table. Add items. Retrieve items. Remove items. Destroy table. ## `Curl_hash_init` ~~~c void Curl_hash_init(struct Curl_hash *h, size_t slots, Curl_hash_type type, Curl_hash_dtor dtor); ~~~ The call initializes a `struct Curl_hash`. - `slots` is the number of entries to create in the hash table. Larger is better (faster lookups) but also uses more memory. - `type` selects how keys are hashed and compared. `CURL_HASH_TYPE_BYTES` treats keys as exact-length byte sequences. `CURL_HASH_TYPE_SOCKET` treats keys as native `curl_socket_t` values and requires `key_len` to equal `sizeof(curl_socket_t)`. - `dtor` is a function pointer to a destructor called when an entry is removed from the table. ## `Curl_hash_add` ~~~c void * Curl_hash_add(struct Curl_hash *h, void *key, size_t key_len, void *p) ~~~ This call adds an entry to the hash. `key` points to the hash key and `key_len` is the length of the hash key. `p` is a custom pointer. If there already was a match in the hash, that data is replaced with this new entry. This function also lazily allocates the table if needed, as it is not done in the `Curl_hash_init` function. Returns NULL on error, otherwise it returns a pointer to `p`. ## `Curl_hash_add2` ~~~c void *Curl_hash_add2(struct Curl_hash *h, void *key, size_t key_len, void *p, Curl_hash_elem_dtor dtor) ~~~ This works like `Curl_hash_add` but has an extra argument: `dtor`, which is a destructor call for this specific entry. When this entry is removed, this function is called instead of the function stored for the whole hash table. ## `Curl_hash_delete` ~~~c int Curl_hash_delete(struct Curl_hash *h, void *key, size_t key_len); ~~~ This function removes an entry from the hash table. If successful, it returns zero. If the entry was not found, it returns 1. ## `Curl_hash_pick` ~~~c void *Curl_hash_pick(struct Curl_hash *h, void *key, size_t key_len); ~~~ If there is an entry in the hash that matches the given `key` with size of `key_len`, that its custom pointer is returned. The pointer that was called `p` when the entry was added. It returns NULL if there is no matching entry in the hash. ## `Curl_hash_destroy` ~~~c void Curl_hash_destroy(struct Curl_hash *h); ~~~ This function destroys a hash and cleanups up all its related data. Calling it multiple times is fine. ## `Curl_hash_clean` ~~~c void Curl_hash_clean(struct Curl_hash *h); ~~~ This function removes all the entries in the given hash. ## `Curl_hash_clean_with_criterium` ~~~c void Curl_hash_clean_with_criterium(struct Curl_hash *h, void *user, int (*comp)(void *, void *)) ~~~ This function removes all the entries in the given hash that matches the criterion. The provided `comp` function determines if the criteria is met by returning non-zero. ## `Curl_hash_count` ~~~c size_t Curl_hash_count(struct Curl_hash *h) ~~~ Returns the number of entries stored in the hash.