1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
6 * Simple hash table API
8 * This file provides functions to store objects in hash tables,
9 * using arbitrary data as keys.
18 typedef void (*ec_htable_elt_free_t)(void *);
21 struct ec_htable_elt_ref;
24 * Create a hash table.
27 * The hash table, or NULL on error (errno is set).
29 struct ec_htable *ec_htable(void);
32 * Get a value from the hash table.
41 * The element if it is found, or NULL on error (errno is set).
42 * In case of success but the element is NULL, errno is set to 0.
44 void *ec_htable_get(const struct ec_htable *htable,
45 const void *key, size_t key_len);
48 * Check if the hash table contains this key.
57 * true if it contains the key, else false.
59 bool ec_htable_has_key(const struct ec_htable *htable,
60 const void *key, size_t key_len);
63 * Delete an object from the hash table.
72 * 0 on success, or -1 on error (errno is set).
74 int ec_htable_del(struct ec_htable *htable, const void *key, size_t key_len);
77 * Add/replace an object in the hash table.
86 * The pointer to be saved in the hash table.
88 * An optional pointer to a destructor function called when an
89 * object is destroyed (ec_htable_del() or ec_htable_free()).
91 * 0 on success, or -1 on error (errno is set).
92 * On error, the passed value is freed (free_cb(val) is called).
94 int ec_htable_set(struct ec_htable *htable, const void *key, size_t key_len,
95 void *val, ec_htable_elt_free_t free_cb);
98 * Free a hash table an all its objects.
103 void ec_htable_free(struct ec_htable *htable);
106 * Get the length of a hash table.
111 * The length of the hash table.
113 size_t ec_htable_len(const struct ec_htable *htable);
116 * Duplicate a hash table
118 * A reference counter is shared between the clones of
119 * hash tables so that the objects are freed only when
120 * the last reference is destroyed.
125 * The duplicated hash table, or NULL on error (errno is set).
127 struct ec_htable *ec_htable_dup(const struct ec_htable *htable);
133 * The stream where the dump is sent.
137 void ec_htable_dump(FILE *out, const struct ec_htable *htable);
140 * Iterate the elements in the hash table.
142 * The typical usage is as below:
145 * for (iter = ec_htable_iter(htable);
147 * iter = ec_htable_iter_next(iter)) {
148 * printf(" %s: %p\n",
149 * ec_htable_iter_get_key(iter),
150 * ec_htable_iter_get_val(iter));
156 * An iterator element, or NULL if the dict is empty.
158 struct ec_htable_elt_ref *
159 ec_htable_iter(const struct ec_htable *htable);
162 * Make the iterator point to the next element in the hash table.
165 * The hash table iterator.
167 * An iterator element, or NULL there is no more element.
169 struct ec_htable_elt_ref *
170 ec_htable_iter_next(struct ec_htable_elt_ref *iter);
173 * Get the key of the current element.
176 * The hash table iterator.
178 * The current element key, or NULL if the iterator points to an
182 ec_htable_iter_get_key(const struct ec_htable_elt_ref *iter);
185 * Get the key length of the current element.
188 * The hash table iterator.
190 * The current element key length, or 0 if the iterator points to an
194 ec_htable_iter_get_key_len(const struct ec_htable_elt_ref *iter);
197 * Get the value of the current element.
200 * The hash table iterator.
202 * The current element value, or NULL if the iterator points to an
206 ec_htable_iter_get_val(const struct ec_htable_elt_ref *iter);