/jansson/src/hashtable.h

http://github.com/nicolasff/webdis · C Header · 207 lines · 47 code · 22 blank · 138 comment · 0 complexity · f76887273f80646abf95a6fe36a92827 MD5 · raw file

  1. /*
  2. * Copyright (c) 2009, 2010 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. #ifndef HASHTABLE_H
  8. #define HASHTABLE_H
  9. typedef size_t (*key_hash_fn)(const void *key);
  10. typedef int (*key_cmp_fn)(const void *key1, const void *key2);
  11. typedef void (*free_fn)(void *key);
  12. struct hashtable_list {
  13. struct hashtable_list *prev;
  14. struct hashtable_list *next;
  15. };
  16. struct hashtable_pair {
  17. void *key;
  18. void *value;
  19. size_t hash;
  20. struct hashtable_list list;
  21. };
  22. struct hashtable_bucket {
  23. struct hashtable_list *first;
  24. struct hashtable_list *last;
  25. };
  26. typedef struct hashtable {
  27. size_t size;
  28. struct hashtable_bucket *buckets;
  29. size_t num_buckets; /* index to primes[] */
  30. struct hashtable_list list;
  31. key_hash_fn hash_key;
  32. key_cmp_fn cmp_keys; /* returns non-zero for equal keys */
  33. free_fn free_key;
  34. free_fn free_value;
  35. } hashtable_t;
  36. /**
  37. * hashtable_create - Create a hashtable object
  38. *
  39. * @hash_key: The key hashing function
  40. * @cmp_keys: The key compare function. Returns non-zero for equal and
  41. * zero for unequal unequal keys
  42. * @free_key: If non-NULL, called for a key that is no longer referenced.
  43. * @free_value: If non-NULL, called for a value that is no longer referenced.
  44. *
  45. * Returns a new hashtable object that should be freed with
  46. * hashtable_destroy when it's no longer used, or NULL on failure (out
  47. * of memory).
  48. */
  49. hashtable_t *hashtable_create(key_hash_fn hash_key, key_cmp_fn cmp_keys,
  50. free_fn free_key, free_fn free_value);
  51. /**
  52. * hashtable_destroy - Destroy a hashtable object
  53. *
  54. * @hashtable: The hashtable
  55. *
  56. * Destroys a hashtable created with hashtable_create().
  57. */
  58. void hashtable_destroy(hashtable_t *hashtable);
  59. /**
  60. * hashtable_init - Initialize a hashtable object
  61. *
  62. * @hashtable: The (statically allocated) hashtable object
  63. * @hash_key: The key hashing function
  64. * @cmp_keys: The key compare function. Returns non-zero for equal and
  65. * zero for unequal unequal keys
  66. * @free_key: If non-NULL, called for a key that is no longer referenced.
  67. * @free_value: If non-NULL, called for a value that is no longer referenced.
  68. *
  69. * Initializes a statically allocated hashtable object. The object
  70. * should be cleared with hashtable_close when it's no longer used.
  71. *
  72. * Returns 0 on success, -1 on error (out of memory).
  73. */
  74. int hashtable_init(hashtable_t *hashtable,
  75. key_hash_fn hash_key, key_cmp_fn cmp_keys,
  76. free_fn free_key, free_fn free_value);
  77. /**
  78. * hashtable_close - Release all resources used by a hashtable object
  79. *
  80. * @hashtable: The hashtable
  81. *
  82. * Destroys a statically allocated hashtable object.
  83. */
  84. void hashtable_close(hashtable_t *hashtable);
  85. /**
  86. * hashtable_set - Add/modify value in hashtable
  87. *
  88. * @hashtable: The hashtable object
  89. * @key: The key
  90. * @value: The value
  91. *
  92. * If a value with the given key already exists, its value is replaced
  93. * with the new value.
  94. *
  95. * Key and value are "stealed" in the sense that hashtable frees them
  96. * automatically when they are no longer used. The freeing is
  97. * accomplished by calling free_key and free_value functions that were
  98. * supplied to hashtable_new. In case one or both of the free
  99. * functions is NULL, the corresponding item is not "stealed".
  100. *
  101. * Returns 0 on success, -1 on failure (out of memory).
  102. */
  103. int hashtable_set(hashtable_t *hashtable, void *key, void *value);
  104. /**
  105. * hashtable_get - Get a value associated with a key
  106. *
  107. * @hashtable: The hashtable object
  108. * @key: The key
  109. *
  110. * Returns value if it is found, or NULL otherwise.
  111. */
  112. void *hashtable_get(hashtable_t *hashtable, const void *key);
  113. /**
  114. * hashtable_del - Remove a value from the hashtable
  115. *
  116. * @hashtable: The hashtable object
  117. * @key: The key
  118. *
  119. * Returns 0 on success, or -1 if the key was not found.
  120. */
  121. int hashtable_del(hashtable_t *hashtable, const void *key);
  122. /**
  123. * hashtable_clear - Clear hashtable
  124. *
  125. * @hashtable: The hashtable object
  126. *
  127. * Removes all items from the hashtable.
  128. */
  129. void hashtable_clear(hashtable_t *hashtable);
  130. /**
  131. * hashtable_iter - Iterate over hashtable
  132. *
  133. * @hashtable: The hashtable object
  134. *
  135. * Returns an opaque iterator to the first element in the hashtable.
  136. * The iterator should be passed to hashtable_iter_* functions.
  137. * The hashtable items are not iterated over in any particular order.
  138. *
  139. * There's no need to free the iterator in any way. The iterator is
  140. * valid as long as the item that is referenced by the iterator is not
  141. * deleted. Other values may be added or deleted. In particular,
  142. * hashtable_iter_next() may be called on an iterator, and after that
  143. * the key/value pair pointed by the old iterator may be deleted.
  144. */
  145. void *hashtable_iter(hashtable_t *hashtable);
  146. /**
  147. * hashtable_iter_at - Return an iterator at a specific key
  148. *
  149. * @hashtable: The hashtable object
  150. * @key: The key that the iterator should point to
  151. *
  152. * Like hashtable_iter() but returns an iterator pointing to a
  153. * specific key.
  154. */
  155. void *hashtable_iter_at(hashtable_t *hashtable, const void *key);
  156. /**
  157. * hashtable_iter_next - Advance an iterator
  158. *
  159. * @hashtable: The hashtable object
  160. * @iter: The iterator
  161. *
  162. * Returns a new iterator pointing to the next element in the
  163. * hashtable or NULL if the whole hastable has been iterated over.
  164. */
  165. void *hashtable_iter_next(hashtable_t *hashtable, void *iter);
  166. /**
  167. * hashtable_iter_key - Retrieve the key pointed by an iterator
  168. *
  169. * @iter: The iterator
  170. */
  171. void *hashtable_iter_key(void *iter);
  172. /**
  173. * hashtable_iter_value - Retrieve the value pointed by an iterator
  174. *
  175. * @iter: The iterator
  176. */
  177. void *hashtable_iter_value(void *iter);
  178. /**
  179. * hashtable_iter_set - Set the value pointed by an iterator
  180. *
  181. * @iter: The iterator
  182. * @value: The value to set
  183. */
  184. void hashtable_iter_set(hashtable_t *hashtable, void *iter, void *value);
  185. #endif