include/ecoli_dict.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, using strings
   9  * as keys.
  10  */
  11
  12 #ifndef ECOLI_KEYVAL_
  13 #define ECOLI_KEYVAL_
  14
  15 #include <stdio.h>
  16 #include <stdbool.h>
  17
  18 typedef void (*ec_dict_elt_free_t)(void *);
  19
  20 struct ec_dict;
  21 struct ec_dict_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_dict *ec_dict(void);
  30
  31 /**
  32  * Get a value from the hash table.
  33  *
  34  * @param dict
  35  *   The hash table.
  36  * @param key
  37  *   The key string.
  38  * @return
  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.
  41  */
  42 void *ec_dict_get(const struct ec_dict *dict, const char *key);
  43
  44 /**
  45  * Check if the hash table contains this key.
  46  *
  47  * @param dict
  48  *   The hash table.
  49  * @param key
  50  *   The key string.
  51  * @return
  52  *   true if it contains the key, else false.
  53  */
  54 bool ec_dict_has_key(const struct ec_dict *dict, const char *key);
  55
  56 /**
  57  * Delete an object from the hash table.
  58  *
  59  * @param dict
  60  *   The hash table.
  61  * @param key
  62  *   The key string.
  63  * @return
  64  *   0 on success, or -1 on error (errno is set).
  65  */
  66 int ec_dict_del(struct ec_dict *dict, const char *key);
  67
  68 /**
  69  * Add/replace an object in the hash table.
  70  *
  71  * @param dict
  72  *   The hash table.
  73  * @param key
  74  *   The key string.
  75  * @param val
  76  *   The pointer to be saved in the hash table.
  77  * @param free_cb
  78  *   An optional pointer to a destructor function called when an
  79  *   object is destroyed (ec_dict_del() or ec_dict_free()).
  80  * @return
  81  *   0 on success, or -1 on error (errno is set).
  82  *   On error, the passed value is freed (free_cb(val) is called).
  83  */
  84 int ec_dict_set(struct ec_dict *dict, const char *key, void *val,
  85         ec_dict_elt_free_t free_cb);
  86
  87 /**
  88  * Free a hash table an all its objects.
  89  *
  90  * @param dict
  91  *   The hash table.
  92  */
  93 void ec_dict_free(struct ec_dict *dict);
  94
  95 /**
  96  * Get the length of a hash table.
  97  *
  98  * @param dict
  99  *   The hash table.
 100  * @return
 101  *   The length of the hash table.
 102  */
 103 size_t ec_dict_len(const struct ec_dict *dict);
 104
 105 /**
 106  * Duplicate a hash table
 107  *
 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.
 111  *
 112  * @param dict
 113  *   The hash table.
 114  * @return
 115  *   The duplicated hash table, or NULL on error (errno is set).
 116  */
 117 struct ec_dict *ec_dict_dup(const struct ec_dict *dict);
 118
 119 /**
 120  * Dump a hash table.
 121  *
 122  * @param out
 123  *   The stream where the dump is sent.
 124  * @param dict
 125  *   The hash table.
 126  */
 127 void ec_dict_dump(FILE *out, const struct ec_dict *dict);
 128
 129 /**
 130  * Iterate the elements in the hash table.
 131  *
 132  * The typical usage is as below:
 133  *
 134  *      // dump elements
 135  *      for (iter = ec_dict_iter(dict);
 136  *           iter != NULL;
 137  *           iter = ec_dict_iter_next(iter)) {
 138  *              printf("  %s: %p\n",
 139  *                      ec_dict_iter_get_key(iter),
 140  *                      ec_dict_iter_get_val(iter));
 141  *      }
 142  *
 143  * @param dict
 144  *   The hash table.
 145  * @return
 146  *   An iterator element, or NULL if the dict is empty.
 147  */
 148 struct ec_dict_elt_ref *
 149 ec_dict_iter(const struct ec_dict *dict);
 150
 151 /**
 152  * Make the iterator point to the next element in the hash table.
 153  *
 154  * @param iter
 155  *   The hash table iterator.
 156  * @return
 157  *   An iterator element, or NULL there is no more element.
 158  */
 159 struct ec_dict_elt_ref *
 160 ec_dict_iter_next(struct ec_dict_elt_ref *iter);
 161
 162 /**
 163  * Get the key of the current element.
 164  *
 165  * @param iter
 166  *   The hash table iterator.
 167  * @return
 168  *   The current element key, or NULL if the iterator points to an
 169  *   invalid element.
 170  */
 171 const char *
 172 ec_dict_iter_get_key(const struct ec_dict_elt_ref *iter);
 173
 174 /**
 175  * Get the value of the current element.
 176  *
 177  * @param iter
 178  *   The hash table iterator.
 179  * @return
 180  *   The current element value, or NULL if the iterator points to an
 181  *   invalid element.
 182  */
 183 void *
 184 ec_dict_iter_get_val(const struct ec_dict_elt_ref *iter);
 185
 186 #endif