git.ozlabs.org Git - ccan/blob - 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 */