lib/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
  22 /**
  23  * Create a hash table.
  24  *
  25  * @return
  26  *   The hash table, or NULL on error (errno is set).
  27  */
  28 struct ec_keyval *ec_keyval(void);
  29
  30 /**
  31  * Get a value from the hash table.
  32  *
  33  * @param keyval
  34  *   The hash table.
  35  * @param key
  36  *   The key string.
  37  * @return
  38  *   The element if it is found, or NULL on error (errno is set).
  39  *   In case of success but the element is NULL, errno is set to 0.
  40  */
  41 void *ec_keyval_get(const struct ec_keyval *keyval, const char *key);
  42
  43 /**
  44  * Check if the hash table contains this key.
  45  *
  46  * @param keyval
  47  *   The hash table.
  48  * @param key
  49  *   The key string.
  50  * @return
  51  *   true if it contains the key, else false.
  52  */
  53 bool ec_keyval_has_key(const struct ec_keyval *keyval, const char *key);
  54
  55 /**
  56  * Delete an object from the hash table.
  57  *
  58  * @param keyval
  59  *   The hash table.
  60  * @param key
  61  *   The key string.
  62  * @return
  63  *   0 on success, or -1 on error (errno is set).
  64  */
  65 int ec_keyval_del(struct ec_keyval *keyval, const char *key);
  66
  67 /**
  68  * Add/replace an object in the hash table.
  69  *
  70  * @param keyval
  71  *   The hash table.
  72  * @param key
  73  *   The key string.
  74  * @param val
  75  *   The pointer to be saved in the hash table.
  76  * @param free_cb
  77  *   An optional pointer to a destructor function called when an
  78  *   object is destroyed (ec_keyval_del() or ec_keyval_free()).
  79  * @return
  80  *   0 on success, or -1 on error (errno is set).
  81  *   On error, the passed value is freed (free_cb(val) is called).
  82  */
  83 int ec_keyval_set(struct ec_keyval *keyval, const char *key, void *val,
  84         ec_keyval_elt_free_t free_cb);
  85
  86 /**
  87  * Free a hash table an all its objects.
  88  *
  89  * @param keyval
  90  *   The hash table.
  91  */
  92 void ec_keyval_free(struct ec_keyval *keyval);
  93
  94 /**
  95  * Get the length of a hash table.
  96  *
  97  * @param keyval
  98  *   The hash table.
  99  * @return
 100  *   The length of the hash table.
 101  */
 102 size_t ec_keyval_len(const struct ec_keyval *keyval);
 103
 104 /**
 105  * Duplicate a hash table
 106  *
 107  * A reference counter is shared between the clones of
 108  * hash tables so that the objects are freed only when
 109  * the last reference is destroyed.
 110  *
 111  * @param keyval
 112  *   The hash table.
 113  * @return
 114  *   The duplicated hash table, or NULL on error (errno is set).
 115  */
 116 struct ec_keyval *ec_keyval_dup(const struct ec_keyval *keyval);
 117
 118 /**
 119  * Dump a hash table.
 120  *
 121  * @param out
 122  *   The stream where the dump is sent.
 123  * @param keyval
 124  *   The hash table.
 125  */
 126 void ec_keyval_dump(FILE *out, const struct ec_keyval *keyval);
 127
 128 #endif