1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
6 * @defgroup dict Dictionary
9 * @brief Simple hash table API (string keys)
11 * This file provides functions to store objects in hash tables, using strings
21 typedef void (*ec_dict_elt_free_t)(void *);
24 struct ec_dict_elt_ref;
27 * Create a hash table.
30 * The hash table, or NULL on error (errno is set).
32 struct ec_dict *ec_dict(void);
35 * Get a value from the hash table.
42 * The element if it is found, or NULL on error (errno is set).
43 * In case of success but the element is NULL, errno is set to 0.
45 void *ec_dict_get(const struct ec_dict *dict, const char *key);
48 * Check if the hash table contains this key.
55 * true if it contains the key, else false.
57 bool ec_dict_has_key(const struct ec_dict *dict, const char *key);
60 * Delete an object from the hash table.
67 * 0 on success, or -1 on error (errno is set).
69 int ec_dict_del(struct ec_dict *dict, const char *key);
72 * Add/replace an object in the hash table.
79 * The pointer to be saved in the hash table.
81 * An optional pointer to a destructor function called when an
82 * object is destroyed (ec_dict_del() or ec_dict_free()).
84 * 0 on success, or -1 on error (errno is set).
85 * On error, the passed value is freed (free_cb(val) is called).
87 int ec_dict_set(struct ec_dict *dict, const char *key, void *val,
88 ec_dict_elt_free_t free_cb);
91 * Free a hash table an all its objects.
96 void ec_dict_free(struct ec_dict *dict);
99 * Get the length of a hash table.
104 * The length of the hash table.
106 size_t ec_dict_len(const struct ec_dict *dict);
109 * Duplicate a hash table
111 * A reference counter is shared between the clones of
112 * hash tables so that the objects are freed only when
113 * the last reference is destroyed.
118 * The duplicated hash table, or NULL on error (errno is set).
120 struct ec_dict *ec_dict_dup(const struct ec_dict *dict);
126 * The stream where the dump is sent.
130 void ec_dict_dump(FILE *out, const struct ec_dict *dict);
133 * Iterate the elements in the hash table.
135 * The typical usage is as below:
138 * for (iter = ec_dict_iter(dict);
140 * iter = ec_dict_iter_next(iter)) {
141 * printf(" %s: %p\n",
142 * ec_dict_iter_get_key(iter),
143 * ec_dict_iter_get_val(iter));
149 * An iterator element, or NULL if the dict is empty.
151 struct ec_dict_elt_ref *
152 ec_dict_iter(const struct ec_dict *dict);
155 * Make the iterator point to the next element in the hash table.
158 * The hash table iterator.
160 * An iterator element, or NULL there is no more element.
162 struct ec_dict_elt_ref *
163 ec_dict_iter_next(struct ec_dict_elt_ref *iter);
166 * Get a pointer to the key of the current element.
169 * The hash table iterator.
171 * The current element key, or NULL if the iterator points to an
175 ec_dict_iter_get_key(const struct ec_dict_elt_ref *iter);
178 * Get the value of the current element.
181 * The hash table iterator.
183 * The current element value, or NULL if the iterator points to an
187 ec_dict_iter_get_val(const struct ec_dict_elt_ref *iter);