include/ecoli_dict.h

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