include/ecoli_htable.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
   3  */
   4
   5 /**
   6  * @defgroup htable Hash table
   7  * @{
   8  *
   9  * @brief Simple hash table API (any key)
  10  *
  11  * This file provides functions to store objects in hash tables,
  12  * using arbitrary data as keys.
  13  */
  14
  15 #ifndef ECOLI_HTABLE_
  16 #define ECOLI_HTABLE_
  17
  18 #include <stdio.h>
  19 #include <stdbool.h>
  20
  21 typedef void (*ec_htable_elt_free_t)(void *);
  22
  23 struct ec_htable;
  24 struct ec_htable_elt_ref;
  25
  26 /**
  27  * Create a hash table.
  28  *
  29  * @return
  30  *   The hash table, or NULL on error (errno is set).
  31  */
  32 struct ec_htable *ec_htable(void);
  33
  34 /**
  35  * Get a value from the hash table.
  36  *
  37  * @param htable
  38  *   The hash table.
  39  * @param key
  40  *   The key.
  41  * @param key_len
  42  *   The key length.
  43  * @return
  44  *   The element if it is found, or NULL on error (errno is set).
  45  *   In case of success but the element is NULL, errno is set to 0.
  46  */
  47 void *ec_htable_get(const struct ec_htable *htable,
  48                 const void *key, size_t key_len);
  49
  50 /**
  51  * Check if the hash table contains this key.
  52  *
  53  * @param htable
  54  *   The hash table.
  55  * @param key
  56  *   The key.
  57  * @param key_len
  58  *   The key length.
  59  * @return
  60  *   true if it contains the key, else false.
  61  */
  62 bool ec_htable_has_key(const struct ec_htable *htable,
  63                 const void *key, size_t key_len);
  64
  65 /**
  66  * Delete an object from the hash table.
  67  *
  68  * @param htable
  69  *   The hash table.
  70  * @param key
  71  *   The key.
  72  * @param key_len
  73  *   The key length.
  74  * @return
  75  *   0 on success, or -1 on error (errno is set).
  76  */
  77 int ec_htable_del(struct ec_htable *htable, const void *key, size_t key_len);
  78
  79 /**
  80  * Add/replace an object in the hash table.
  81  *
  82  * @param htable
  83  *   The hash table.
  84  * @param key
  85  *   The key.
  86  * @param key_len
  87  *   The key length.
  88  * @param val
  89  *   The pointer to be saved in the hash table.
  90  * @param free_cb
  91  *   An optional pointer to a destructor function called when an
  92  *   object is destroyed (ec_htable_del() or ec_htable_free()).
  93  * @return
  94  *   0 on success, or -1 on error (errno is set).
  95  *   On error, the passed value is freed (free_cb(val) is called).
  96  */
  97 int ec_htable_set(struct ec_htable *htable, const void *key, size_t key_len,
  98                 void *val, ec_htable_elt_free_t free_cb);
  99
 100 /**
 101  * Free a hash table an all its objects.
 102  *
 103  * @param htable
 104  *   The hash table.
 105  */
 106 void ec_htable_free(struct ec_htable *htable);
 107
 108 /**
 109  * Get the length of a hash table.
 110  *
 111  * @param htable
 112  *   The hash table.
 113  * @return
 114  *   The length of the hash table.
 115  */
 116 size_t ec_htable_len(const struct ec_htable *htable);
 117
 118 /**
 119  * Duplicate a hash table
 120  *
 121  * A reference counter is shared between the clones of
 122  * hash tables so that the objects are freed only when
 123  * the last reference is destroyed.
 124  *
 125  * @param htable
 126  *   The hash table.
 127  * @return
 128  *   The duplicated hash table, or NULL on error (errno is set).
 129  */
 130 struct ec_htable *ec_htable_dup(const struct ec_htable *htable);
 131
 132 /**
 133  * Dump a hash table.
 134  *
 135  * @param out
 136  *   The stream where the dump is sent.
 137  * @param htable
 138  *   The hash table.
 139  */
 140 void ec_htable_dump(FILE *out, const struct ec_htable *htable);
 141
 142 /**
 143  * Iterate the elements in the hash table.
 144  *
 145  * The typical usage is as below:
 146  *
 147  *      // dump elements
 148  *      for (iter = ec_htable_iter(htable);
 149  *           iter != NULL;
 150  *           iter = ec_htable_iter_next(iter)) {
 151  *              printf("  %s: %p\n",
 152  *                      ec_htable_iter_get_key(iter),
 153  *                      ec_htable_iter_get_val(iter));
 154  *      }
 155  *
 156  * @param htable
 157  *   The hash table.
 158  * @return
 159  *   An iterator element, or NULL if the dict is empty.
 160  */
 161 struct ec_htable_elt_ref *
 162 ec_htable_iter(const struct ec_htable *htable);
 163
 164 /**
 165  * Make the iterator point to the next element in the hash table.
 166  *
 167  * @param iter
 168  *   The hash table iterator.
 169  * @return
 170  *   An iterator element, or NULL there is no more element.
 171  */
 172 struct ec_htable_elt_ref *
 173 ec_htable_iter_next(struct ec_htable_elt_ref *iter);
 174
 175 /**
 176  * Get the key of the current element.
 177  *
 178  * @param iter
 179  *   The hash table iterator.
 180  * @return
 181  *   The current element key, or NULL if the iterator points to an
 182  *   invalid element.
 183  */
 184 const void *
 185 ec_htable_iter_get_key(const struct ec_htable_elt_ref *iter);
 186
 187 /**
 188  * Get the key length of the current element.
 189  *
 190  * @param iter
 191  *   The hash table iterator.
 192  * @return
 193  *   The current element key length, or 0 if the iterator points to an
 194  *   invalid element.
 195  */
 196 size_t
 197 ec_htable_iter_get_key_len(const struct ec_htable_elt_ref *iter);
 198
 199 /**
 200  * Get the value of the current element.
 201  *
 202  * @param iter
 203  *   The hash table iterator.
 204  * @return
 205  *   The current element value, or NULL if the iterator points to an
 206  *   invalid element.
 207  */
 208 void *
 209 ec_htable_iter_get_val(const struct ec_htable_elt_ref *iter);
 210
 211 #endif
 212
 213 /** @} */