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, using strings
18 typedef void (*ec_dict_elt_free_t)(void *);
21 struct ec_dict_elt_ref;
24 * Create a hash table.
27 * The hash table, or NULL on error (errno is set).
29 struct ec_dict *ec_dict(void);
32 * Get a value from the hash table.
39 * The element if it is found, or NULL on error (errno is set).
40 * In case of success but the element is NULL, errno is set to 0.
42 void *ec_dict_get(const struct ec_dict *dict, const char *key);
45 * Check if the hash table contains this key.
52 * true if it contains the key, else false.
54 bool ec_dict_has_key(const struct ec_dict *dict, const char *key);
57 * Delete an object from the hash table.
64 * 0 on success, or -1 on error (errno is set).
66 int ec_dict_del(struct ec_dict *dict, const char *key);
69 * Add/replace an object in the hash table.
76 * The pointer to be saved in the hash table.
78 * An optional pointer to a destructor function called when an
79 * object is destroyed (ec_dict_del() or ec_dict_free()).
81 * 0 on success, or -1 on error (errno is set).
82 * On error, the passed value is freed (free_cb(val) is called).
84 int ec_dict_set(struct ec_dict *dict, const char *key, void *val,
85 ec_dict_elt_free_t free_cb);
88 * Free a hash table an all its objects.
93 void ec_dict_free(struct ec_dict *dict);
96 * Get the length of a hash table.
101 * The length of the hash table.
103 size_t ec_dict_len(const struct ec_dict *dict);
106 * Duplicate a hash table
108 * A reference counter is shared between the clones of
109 * hash tables so that the objects are freed only when
110 * the last reference is destroyed.
115 * The duplicated hash table, or NULL on error (errno is set).
117 struct ec_dict *ec_dict_dup(const struct ec_dict *dict);
123 * The stream where the dump is sent.
127 void ec_dict_dump(FILE *out, const struct ec_dict *dict);
130 * Iterate the elements in the hash table.
132 * The typical usage is as below:
135 * for (iter = ec_dict_iter(dict);
137 * iter = ec_dict_iter_next(iter)) {
138 * printf(" %s: %p\n",
139 * ec_dict_iter_get_key(iter),
140 * ec_dict_iter_get_val(iter));
146 * An iterator element, or NULL if the dict is empty.
148 struct ec_dict_elt_ref *
149 ec_dict_iter(const struct ec_dict *dict);
152 * Make the iterator point to the next element in the hash table.
155 * The hash table iterator.
157 * An iterator element, or NULL there is no more element.
159 struct ec_dict_elt_ref *
160 ec_dict_iter_next(struct ec_dict_elt_ref *iter);
163 * Get the key of the current element.
166 * The hash table iterator.
168 * The current element key, or NULL if the iterator points to an
172 ec_dict_iter_get_key(const struct ec_dict_elt_ref *iter);
175 * Get the value of the current element.
178 * The hash table iterator.
180 * The current element value, or NULL if the iterator points to an
184 ec_dict_iter_get_val(const struct ec_dict_elt_ref *iter);