Unify style

[jansson.git] / src / hashtable.h

diff --git a/src/hashtable.h b/src/hashtable.h
index 6d66383..5aed14f 100644 (file)
--- a/src/hashtable.h
+++ b/src/hashtable.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 Petri Lehtinen <petri@digip.org>
+ * Copyright (c) 2009-2011 Petri Lehtinen <petri@digip.org>
  *
  * This library is free software; you can redistribute it and/or modify
  * it under the terms of the MIT license. See LICENSE for details.
@@ -8,14 +8,41 @@
 #ifndef HASHTABLE_H
 #define HASHTABLE_H
 
-typedef struct hashtable hashtable_t;
-
-typedef unsigned int (*key_hash_fn)(const void *key);
+typedef size_t (*key_hash_fn)(const void *key);
 typedef int (*key_cmp_fn)(const void *key1, const void *key2);
 typedef void (*free_fn)(void *key);
 
+struct hashtable_list {
+    struct hashtable_list *prev;
+    struct hashtable_list *next;
+};
+
+struct hashtable_pair {
+    void *key;
+    void *value;
+    size_t hash;
+    struct hashtable_list list;
+};
+
+struct hashtable_bucket {
+    struct hashtable_list *first;
+    struct hashtable_list *last;
+};
+
+typedef struct hashtable {
+    size_t size;
+    struct hashtable_bucket *buckets;
+    size_t num_buckets;  /* index to primes[] */
+    struct hashtable_list list;
+
+    key_hash_fn hash_key;
+    key_cmp_fn cmp_keys;  /* returns non-zero for equal keys */
+    free_fn free_key;
+    free_fn free_value;
+} hashtable_t;
+
 /**
- * hashtable_new - Create a hashtable object
+ * hashtable_create - Create a hashtable object
  *
  * @hash_key: The key hashing function
  * @cmp_keys: The key compare function. Returns non-zero for equal and
@@ -24,17 +51,48 @@ typedef void (*free_fn)(void *key);
  * @free_value: If non-NULL, called for a value that is no longer referenced.
  *
  * Returns a new hashtable object that should be freed with
- * hashtable_free when it's no longer used.
+ * hashtable_destroy when it's no longer used, or NULL on failure (out
+ * of memory).
  */
-hashtable_t *hashtable_new(key_hash_fn hash_key, key_cmp_fn cmp_keys,
-                           free_fn free_key, free_fn free_value);
+hashtable_t *hashtable_create(key_hash_fn hash_key, key_cmp_fn cmp_keys,
+                              free_fn free_key, free_fn free_value);
 
 /**
- * hashtable_free - Destroy a hashtable object
+ * hashtable_destroy - Destroy a hashtable object
  *
  * @hashtable: The hashtable
+ *
+ * Destroys a hashtable created with hashtable_create().
  */
-void hashtable_free(hashtable_t *hashtable);
+void hashtable_destroy(hashtable_t *hashtable);
+
+/**
+ * hashtable_init - Initialize a hashtable object
+ *
+ * @hashtable: The (statically allocated) hashtable object
+ * @hash_key: The key hashing function
+ * @cmp_keys: The key compare function. Returns non-zero for equal and
+ *     zero for unequal unequal keys
+ * @free_key: If non-NULL, called for a key that is no longer referenced.
+ * @free_value: If non-NULL, called for a value that is no longer referenced.
+ *
+ * Initializes a statically allocated hashtable object. The object
+ * should be cleared with hashtable_close when it's no longer used.
+ *
+ * Returns 0 on success, -1 on error (out of memory).
+ */
+int hashtable_init(hashtable_t *hashtable,
+                   key_hash_fn hash_key, key_cmp_fn cmp_keys,
+                   free_fn free_key, free_fn free_value);
+
+/**
+ * hashtable_close - Release all resources used by a hashtable object
+ *
+ * @hashtable: The hashtable
+ *
+ * Destroys a statically allocated hashtable object.
+ */
+void hashtable_close(hashtable_t *hashtable);
 
 /**
  * hashtable_set - Add/modify value in hashtable
@@ -77,6 +135,15 @@ void *hashtable_get(hashtable_t *hashtable, const void *key);
 int hashtable_del(hashtable_t *hashtable, const void *key);
 
 /**
+ * hashtable_clear - Clear hashtable
+ *
+ * @hashtable: The hashtable object
+ *
+ * Removes all items from the hashtable.
+ */
+void hashtable_clear(hashtable_t *hashtable);
+
+/**
  * hashtable_iter - Iterate over hashtable
  *
  * @hashtable: The hashtable object
@@ -94,6 +161,17 @@ int hashtable_del(hashtable_t *hashtable, const void *key);
 void *hashtable_iter(hashtable_t *hashtable);
 
 /**
+ * hashtable_iter_at - Return an iterator at a specific key
+ *
+ * @hashtable: The hashtable object
+ * @key: The key that the iterator should point to
+ *
+ * Like hashtable_iter() but returns an iterator pointing to a
+ * specific key.
+ */
+void *hashtable_iter_at(hashtable_t *hashtable, const void *key);
+
+/**
  * hashtable_iter_next - Advance an iterator
  *
  * @hashtable: The hashtable object
@@ -118,4 +196,12 @@ void *hashtable_iter_key(void *iter);
  */
 void *hashtable_iter_value(void *iter);
 
+/**
+ * hashtable_iter_set - Set the value pointed by an iterator
+ *
+ * @iter: The iterator
+ * @value: The value to set
+ */
+void hashtable_iter_set(hashtable_t *hashtable, void *iter, void *value);
+
 #endif