summaryrefslogtreecommitdiff
path: root/utils/hashtable.h
diff options
context:
space:
mode:
Diffstat (limited to 'utils/hashtable.h')
-rw-r--r--utils/hashtable.h46
1 files changed, 42 insertions, 4 deletions
diff --git a/utils/hashtable.h b/utils/hashtable.h
index 432ccfe2a..b0e7392c6 100644
--- a/utils/hashtable.h
+++ b/utils/hashtable.h
@@ -16,8 +16,10 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/** \file
- * Write-Once hash table for string to string mappings */
+/**
+ * \file
+ * Interface to Write-Once hash table for string to string mapping
+ */
#ifndef _NETSURF_UTILS_HASHTABLE_H_
#define _NETSURF_UTILS_HASHTABLE_H_
@@ -26,11 +28,47 @@
struct hash_table;
+/**
+ * Create a new hash table, and return a context for it. The memory consumption
+ * of a hash table is approximately 8 + (nchains * 12) bytes if it is empty.
+ *
+ * \param chains Number of chains/buckets this hash table will have. This
+ * should be a prime number, and ideally a prime number just
+ * over a power of two, for best performance and distribution.
+ * \return struct hash_table containing the context of this hash table or NULL
+ * if there is insufficent memory to create it and its chains.
+ */
struct hash_table *hash_create(unsigned int chains);
+
+/**
+ * Destroys a hash table, freeing all memory associated with it.
+ *
+ * \param ht Hash table to destroy. After the function returns, this
+ * will nolonger be valid.
+ */
void hash_destroy(struct hash_table *ht);
+
+/**
+ * Adds a key/value pair to a hash table. If the key you're adding is already
+ * in the hash table, it does not replace it, but it does take precedent over
+ * it. The old key/value pair will be inaccessable but still in memory until
+ * hash_destroy() is called on the hash table.
+ *
+ * \param ht The hash table context to add the key/value pair to.
+ * \param key The key to associate the value with. A copy is made.
+ * \param value The value to associate the key with. A copy is made.
+ * \return true if the add succeeded, false otherwise. (Failure most likely
+ * indicates insufficent memory to make copies of the key and value.
+ */
bool hash_add(struct hash_table *ht, const char *key, const char *value);
+
+/**
+ * Looks up a the value associated with with a key from a specific hash table.
+ *
+ * \param ht The hash table context to look up the key in.
+ * \param key The key to search for.
+ * \return The value associated with the key, or NULL if it was not found.
+ */
const char *hash_get(struct hash_table *ht, const char *key);
-const char *hash_iterate(struct hash_table *ht, unsigned int *c1,
- unsigned int **c2);
#endif