src/hashtable.h

   1 /*
   2  * Copyright (c) 2009 Petri Lehtinen <petri@digip.org>
   3  *
   4  * This library is free software; you can redistribute it and/or modify
   5  * it under the terms of the MIT license. See LICENSE for details.
   6  */
   7
   8 #ifndef HASHTABLE_H
   9 #define HASHTABLE_H
  10
  11 typedef struct hashtable hashtable_t;
  12
  13 typedef unsigned int (*key_hash_fn)(const void *key);
  14 typedef int (*key_cmp_fn)(const void *key1, const void *key2);
  15 typedef void (*free_fn)(void *key);
  16
  17 /**
  18  * hashtable_new - Create a hashtable object
  19  *
  20  * @hash_key: The key hashing function
  21  * @cmp_keys: The key compare function. Returns non-zero for equal and
  22  *     zero for unequal unequal keys
  23  * @free_key: If non-NULL, called for a key that is no longer referenced.
  24  * @free_value: If non-NULL, called for a value that is no longer referenced.
  25  *
  26  * Returns a new hashtable object that should be freed with
  27  * hashtable_free when it's no longer used.
  28  */
  29 hashtable_t *hashtable_new(key_hash_fn hash_key, key_cmp_fn cmp_keys,
  30                            free_fn free_key, free_fn free_value);
  31
  32 /**
  33  * hashtable_free - Destroy a hashtable object
  34  *
  35  * @hashtable: The hashtable
  36  */
  37 void hashtable_free(hashtable_t *hashtable);
  38
  39 /**
  40  * hashtable_set - Add/modify value in hashtable
  41  *
  42  * @hashtable: The hashtable object
  43  * @key: The key
  44  * @value: The value
  45  *
  46  * If a value with the given key already exists, its value is replaced
  47  * with the new value.
  48  *
  49  * Key and value are "stealed" in the sense that hashtable frees them
  50  * automatically when they are no longer used. The freeing is
  51  * accomplished by calling free_key and free_value functions that were
  52  * supplied to hashtable_new. In case one or both of the free
  53  * functions is NULL, the corresponding item is not "stealed".
  54  *
  55  * Returns 0 on success, -1 on failure (out of memory).
  56  */
  57 int hashtable_set(hashtable_t *hashtable, void *key, void *value);
  58
  59 /**
  60  * hashtable_get - Get a value associated with a key
  61  *
  62  * @hashtable: The hashtable object
  63  * @key: The key
  64  *
  65  * Returns value if it is found, or NULL otherwise.
  66  */
  67 void *hashtable_get(hashtable_t *hashtable, const void *key);
  68
  69 /**
  70  * hashtable_del - Remove a value from the hashtable
  71  *
  72  * @hashtable: The hashtable object
  73  * @key: The key
  74  *
  75  * Returns 0 on success, or -1 if the key was not found.
  76  */
  77 int hashtable_del(hashtable_t *hashtable, const void *key);
  78
  79 /**
  80  * hashtable_iter - Iterate over hashtable
  81  *
  82  * @hashtable: The hashtable object
  83  *
  84  * Returns an opaque iterator to the first element in the hashtable.
  85  * The iterator should be passed to hashtable_iter_* functions.
  86  * The hashtable items are not iterated over in any particular order.
  87  *
  88  * There's no need to free the iterator in any way. The iterator is
  89  * valid as long as the item that is referenced by the iterator is not
  90  * deleted. Other values may be added or deleted. In particular,
  91  * hashtable_iter_next() may be called on an iterator, and after that
  92  * the key/value pair pointed by the old iterator may be deleted.
  93  */
  94 void *hashtable_iter(hashtable_t *hashtable);
  95
  96 /**
  97  * hashtable_iter_next - Advance an iterator
  98  *
  99  * @hashtable: The hashtable object
 100  * @iter: The iterator
 101  *
 102  * Returns a new iterator pointing to the next element in the
 103  * hashtable or NULL if the whole hastable has been iterated over.
 104  */
 105 void *hashtable_iter_next(hashtable_t *hashtable, void *iter);
 106
 107 /**
 108  * hashtable_iter_key - Retrieve the key pointed by an iterator
 109  *
 110  * @iter: The iterator
 111  */
 112 void *hashtable_iter_key(void *iter);
 113
 114 /**
 115  * hashtable_iter_value - Retrieve the value pointed by an iterator
 116  *
 117  * @iter: The iterator
 118  */
 119 void *hashtable_iter_value(void *iter);
 120
 121 #endif