include/ecoli_htable.h

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