include/ecoli_keyval.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_keyval_elt_free_t)(void *);
  19
  20 struct ec_keyval;
  21 struct ec_keyval_iter;
  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_keyval *ec_keyval(void);
  30
  31 /**
  32  * Get a value from the hash table.
  33  *
  34  * @param keyval
  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_keyval_get(const struct ec_keyval *keyval, const char *key);
  43
  44 /**
  45  * Check if the hash table contains this key.
  46  *
  47  * @param keyval
  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_keyval_has_key(const struct ec_keyval *keyval, const char *key);
  55
  56 /**
  57  * Delete an object from the hash table.
  58  *
  59  * @param keyval
  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_keyval_del(struct ec_keyval *keyval, const char *key);
  67
  68 /**
  69  * Add/replace an object in the hash table.
  70  *
  71  * @param keyval
  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_keyval_del() or ec_keyval_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_keyval_set(struct ec_keyval *keyval, const char *key, void *val,
  85         ec_keyval_elt_free_t free_cb);
  86
  87 /**
  88  * Free a hash table an all its objects.
  89  *
  90  * @param keyval
  91  *   The hash table.
  92  */
  93 void ec_keyval_free(struct ec_keyval *keyval);
  94
  95 /**
  96  * Get the length of a hash table.
  97  *
  98  * @param keyval
  99  *   The hash table.
 100  * @return
 101  *   The length of the hash table.
 102  */
 103 size_t ec_keyval_len(const struct ec_keyval *keyval);
 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 keyval
 113  *   The hash table.
 114  * @return
 115  *   The duplicated hash table, or NULL on error (errno is set).
 116  */
 117 struct ec_keyval *ec_keyval_dup(const struct ec_keyval *keyval);
 118
 119 /**
 120  * Dump a hash table.
 121  *
 122  * @param out
 123  *   The stream where the dump is sent.
 124  * @param keyval
 125  *   The hash table.
 126  */
 127 void ec_keyval_dump(FILE *out, const struct ec_keyval *keyval);
 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_keyval_iter(keyval);
 136  *           ec_keyval_iter_valid(iter);
 137  *           ec_keyval_iter_next(iter)) {
 138  *              printf("  %s: %p\n",
 139  *                      ec_keyval_iter_get_key(iter),
 140  *                      ec_keyval_iter_get_val(iter));
 141  *      }
 142  *      ec_keyval_iter_free(iter);
 143  *
 144  * @param keyval
 145  *   The hash table.
 146  * @return
 147  *   An iterator, or NULL on error (errno is set).
 148  */
 149 struct ec_keyval_iter *
 150 ec_keyval_iter(const struct ec_keyval *keyval);
 151
 152 /**
 153  * Make the iterator point to the next element in the hash table.
 154  *
 155  * @param iter
 156  *   The hash table iterator.
 157  */
 158 void ec_keyval_iter_next(struct ec_keyval_iter *iter);
 159
 160 /**
 161  * Free the iterator.
 162  *
 163  * @param iter
 164  *   The hash table iterator.
 165  */
 166 void ec_keyval_iter_free(struct ec_keyval_iter *iter);
 167
 168 /**
 169  * Check if the iterator points to a valid element.
 170  *
 171  * @param iter
 172  *   The hash table iterator.
 173  * @return
 174  *   true if the element is valid, else false.
 175  */
 176 bool
 177 ec_keyval_iter_valid(const struct ec_keyval_iter *iter);
 178
 179 /**
 180  * Get the key of the current element.
 181  *
 182  * @param iter
 183  *   The hash table iterator.
 184  * @return
 185  *   The current element key, or NULL if the iterator points to an
 186  *   invalid element.
 187  */
 188 const char *
 189 ec_keyval_iter_get_key(const struct ec_keyval_iter *iter);
 190
 191 /**
 192  * Get the value of the current element.
 193  *
 194  * @param iter
 195  *   The hash table iterator.
 196  * @return
 197  *   The current element value, or NULL if the iterator points to an
 198  *   invalid element.
 199  */
 200 void *
 201 ec_keyval_iter_get_val(const struct ec_keyval_iter *iter);
 202
 203
 204 #endif