1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
6 * @defgroup htable Hash table
9 * @brief Simple hash table API (any key)
11 * This file provides functions to store objects in hash tables,
12 * using arbitrary data as keys.
21 typedef void (*ec_htable_elt_free_t)(void *);
24 struct ec_htable_elt_ref;
27 * Create a hash table.
30 * The hash table, or NULL on error (errno is set).
32 struct ec_htable *ec_htable(void);
35 * Get a value from the hash table.
44 * The element if it is found, or NULL on error (errno is set).
45 * In case of success but the element is NULL, errno is set to 0.
47 void *ec_htable_get(const struct ec_htable *htable,
48 const void *key, size_t key_len);
51 * Check if the hash table contains this key.
60 * true if it contains the key, else false.
62 bool ec_htable_has_key(const struct ec_htable *htable,
63 const void *key, size_t key_len);
66 * Delete an object from the hash table.
75 * 0 on success, or -1 on error (errno is set).
77 int ec_htable_del(struct ec_htable *htable, const void *key, size_t key_len);
80 * Add/replace an object in the hash table.
89 * The pointer to be saved in the hash table.
91 * An optional pointer to a destructor function called when an
92 * object is destroyed (ec_htable_del() or ec_htable_free()).
94 * 0 on success, or -1 on error (errno is set).
95 * On error, the passed value is freed (free_cb(val) is called).
97 int ec_htable_set(struct ec_htable *htable, const void *key, size_t key_len,
98 void *val, ec_htable_elt_free_t free_cb);
101 * Free a hash table an all its objects.
106 void ec_htable_free(struct ec_htable *htable);
109 * Get the length of a hash table.
114 * The length of the hash table.
116 size_t ec_htable_len(const struct ec_htable *htable);
119 * Duplicate a hash table
121 * A reference counter is shared between the clones of
122 * hash tables so that the objects are freed only when
123 * the last reference is destroyed.
128 * The duplicated hash table, or NULL on error (errno is set).
130 struct ec_htable *ec_htable_dup(const struct ec_htable *htable);
136 * The stream where the dump is sent.
140 void ec_htable_dump(FILE *out, const struct ec_htable *htable);
143 * Iterate the elements in the hash table.
145 * The typical usage is as below:
148 * for (iter = ec_htable_iter(htable);
150 * iter = ec_htable_iter_next(iter)) {
151 * printf(" %s: %p\n",
152 * ec_htable_iter_get_key(iter),
153 * ec_htable_iter_get_val(iter));
159 * An iterator element, or NULL if the dict is empty.
161 struct ec_htable_elt_ref *
162 ec_htable_iter(const struct ec_htable *htable);
165 * Make the iterator point to the next element in the hash table.
168 * The hash table iterator.
170 * An iterator element, or NULL there is no more element.
172 struct ec_htable_elt_ref *
173 ec_htable_iter_next(struct ec_htable_elt_ref *iter);
176 * Get the key of the current element.
179 * The hash table iterator.
181 * The current element key, or NULL if the iterator points to an
185 ec_htable_iter_get_key(const struct ec_htable_elt_ref *iter);
188 * Get the key length of the current element.
191 * The hash table iterator.
193 * The current element key length, or 0 if the iterator points to an
197 ec_htable_iter_get_key_len(const struct ec_htable_elt_ref *iter);
200 * Get the value of the current element.
203 * The hash table iterator.
205 * The current element value, or NULL if the iterator points to an
209 ec_htable_iter_get_val(const struct ec_htable_elt_ref *iter);