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_keyval_elt_free_t)(void *);
21 struct ec_keyval_iter;
24 * Create a hash table.
27 * The hash table, or NULL on error (errno is set).
29 struct ec_keyval *ec_keyval(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_keyval_get(const struct ec_keyval *keyval, const char *key);
45 * Check if the hash table contains this key.
52 * true if it contains the key, else false.
54 bool ec_keyval_has_key(const struct ec_keyval *keyval, 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_keyval_del(struct ec_keyval *keyval, 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_keyval_del() or ec_keyval_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_keyval_set(struct ec_keyval *keyval, const char *key, void *val,
85 ec_keyval_elt_free_t free_cb);
88 * Free a hash table an all its objects.
93 void ec_keyval_free(struct ec_keyval *keyval);
96 * Get the length of a hash table.
101 * The length of the hash table.
103 size_t ec_keyval_len(const struct ec_keyval *keyval);
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_keyval *ec_keyval_dup(const struct ec_keyval *keyval);
123 * The stream where the dump is sent.
127 void ec_keyval_dump(FILE *out, const struct ec_keyval *keyval);
130 * Iterate the elements in the hash table.
132 * The typical usage is as below:
135 * for (iter = ec_keyval_iter(keyval);
136 * ec_keyval_iter_valid(iter);
137 * ec_keyval_iter_next(iter)) {
138 * printf(" %s: %p\n",
139 * ec_keyval_iter_get_key(iter),
140 * ec_keyval_iter_get_val(iter));
142 * ec_keyval_iter_free(iter);
147 * An iterator, or NULL on error (errno is set).
149 struct ec_keyval_iter *
150 ec_keyval_iter(const struct ec_keyval *keyval);
153 * Make the iterator point to the next element in the hash table.
156 * The hash table iterator.
158 void ec_keyval_iter_next(struct ec_keyval_iter *iter);
164 * The hash table iterator.
166 void ec_keyval_iter_free(struct ec_keyval_iter *iter);
169 * Check if the iterator points to a valid element.
172 * The hash table iterator.
174 * true if the element is valid, else false.
177 ec_keyval_iter_valid(const struct ec_keyval_iter *iter);
180 * Get the key of the current element.
183 * The hash table iterator.
185 * The current element key, or NULL if the iterator points to an
189 ec_keyval_iter_get_key(const struct ec_keyval_iter *iter);
192 * Get the value of the current element.
195 * The hash table iterator.
197 * The current element value, or NULL if the iterator points to an
201 ec_keyval_iter_get_val(const struct ec_keyval_iter *iter);