htable, strset: benchmarking tools.
[ccan] / ccan / htable / htable.h
1 /* Licensed under LGPLv2+ - see LICENSE file for details */
2 #ifndef CCAN_HTABLE_H
3 #define CCAN_HTABLE_H
4 #include "config.h"
5 #include <stdbool.h>
6 #include <stdlib.h>
7
8 struct htable;
9
10 /**
11  * htable_new - allocate a hash tree.
12  * @rehash: hash function to use for rehashing.
13  * @priv: private argument to @rehash function.
14  */
15 struct htable *htable_new(size_t (*hash)(const void *elem, void *priv),
16                           void *priv);
17
18 /**
19  * htable_free - dellocate a hash tree.
20  *
21  * This doesn't do anything to any pointers left in it.
22  */
23 void htable_free(const struct htable *);
24
25 /**
26  * htable_rehash - use a hashtree's rehash function
27  * @elem: the argument to rehash()
28  *
29  */
30 size_t htable_rehash(const void *elem);
31
32 /**
33  * htable_add - add a pointer into a hash tree.
34  * @ht: the htable
35  * @hash: the hash value of the object
36  * @p: the non-NULL pointer
37  *
38  * Also note that this can only fail due to allocation failure.  Otherwise, it
39  * returns true.
40  */
41 bool htable_add(struct htable *ht, size_t hash, const void *p);
42
43 /**
44  * htable_del - remove a pointer from a hash tree
45  * @ht: the htable
46  * @hash: the hash value of the object
47  * @p: the pointer
48  *
49  * Returns true if the pointer was found (and deleted).
50  */
51 bool htable_del(struct htable *ht, size_t hash, const void *p);
52
53 /**
54  * struct htable_iter - iterator or htable_first or htable_firstval etc.
55  *
56  * This refers to a location inside the hashtable.
57  */
58 struct htable_iter {
59         size_t off;
60 };
61
62 /**
63  * htable_firstval - find a candidate for a given hash value
64  * @htable: the hashtable
65  * @i: the struct htable_iter to initialize
66  * @hash: the hash value
67  *
68  * You'll need to check the value is what you want; returns NULL if none.
69  * See Also:
70  *      htable_delval()
71  */
72 void *htable_firstval(const struct htable *htable,
73                       struct htable_iter *i, size_t hash);
74
75 /**
76  * htable_nextval - find another candidate for a given hash value
77  * @htable: the hashtable
78  * @i: the struct htable_iter to initialize
79  * @hash: the hash value
80  *
81  * You'll need to check the value is what you want; returns NULL if no more.
82  */
83 void *htable_nextval(const struct htable *htable,
84                      struct htable_iter *i, size_t hash);
85
86 /**
87  * htable_get - find an entry in the hash table
88  * @ht: the hashtable
89  * @h: the hash value of the entry
90  * @cmp: the comparison function
91  * @ptr: the pointer to hand to the comparison function.
92  *
93  * Convenient inline wrapper for htable_firstval/htable_nextval loop.
94  */
95 static inline void *htable_get(const struct htable *ht,
96                                size_t h,
97                                bool (*cmp)(const void *candidate, void *ptr),
98                                const void *ptr)
99 {
100         struct htable_iter i;
101         void *c;
102
103         for (c = htable_firstval(ht,&i,h); c; c = htable_nextval(ht,&i,h)) {
104                 if (cmp(c, (void *)ptr))
105                         return c;
106         }
107         return NULL;
108 }
109
110 /**
111  * htable_first - find an entry in the hash table
112  * @ht: the hashtable
113  * @i: the struct htable_iter to initialize
114  *
115  * Get an entry in the hashtable; NULL if empty.
116  */
117 void *htable_first(const struct htable *htable, struct htable_iter *i);
118
119 /**
120  * htable_next - find another entry in the hash table
121  * @ht: the hashtable
122  * @i: the struct htable_iter to use
123  *
124  * Get another entry in the hashtable; NULL if all done.
125  * This is usually used after htable_first or prior non-NULL htable_next.
126  */
127 void *htable_next(const struct htable *htable, struct htable_iter *i);
128
129 /**
130  * htable_delval - remove an iterated pointer from a hash tree
131  * @ht: the htable
132  * @i: the htable_iter
133  *
134  * Usually used to delete a hash entry after it has been found with
135  * htable_firstval etc.
136  */
137 void htable_delval(struct htable *ht, struct htable_iter *i);
138
139 #endif /* CCAN_HTABLE_H */