Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 2001 - 2007 Pekka Riikonen
+ Copyright (C) 2001 - 2008 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
*/
-/****h* silcutil/SILC Hash Table Interface
+/****h* silcutil/Hash Table Interface
*
* DESCRIPTION
*
- * Implementation of collision resistant hash table. This is a hash table
- * that provides a reliable (what you add there stays there, and duplicate
- * keys are allowed) with as fast reference to the key as possible. If
- * there are a lot of duplicate keys in the hash table the lookup slows down.
- * However, this is reliable and no data is lost at any point. If you know
- * that you never have duplicate keys then this is as fast as any simple hash
- * table.
+ * A collision resistant hash table API. This is a hash table that provides
+ * a reliable hash table (what you add there stays there, and duplicate keys
+ * are allowed) with as fast reference to the key as possible. If there are
+ * a lot of duplicate keys in the hash table the lookup slows down. However,
+ * this is reliable and no data is lost at any point. If you know that you
+ * never have duplicate keys then this is as fast as any simple hash table.
*
* The interface provides many ways to search the hash table including
- * an extended interface where caller can specify its own hash and comparison
+ * an extended interface where caller can specify their own hash and comparison
* functions. The interface also supports SilcStack and all memory allocated
* by the hash table can be allocated from SilcStack.
*
* SilcHashTableList structure and traverse the hash table inside while()
* using the list structure. Both are equally fast.
*
+ * The interface also provides many utility hashing and comparison functions
+ * that caller may use with SilcHashTable.
+ *
* The hash table is not thread safe. If same SilcHashtable context is used
* in multi thread environment concurrency control must be employed.
*
#ifndef SILCHASHTABLE_H
#define SILCHASHTABLE_H
-/****s* silcutil/SilcHashTableAPI/SilcHashTable
+/****s* silcutil/SilcHashTable
*
* NAME
*
***/
typedef struct SilcHashTableStruct *SilcHashTable;
-/****s* silcutil/SilcHashTableAPI/SilcHashTableList
+/****s* silcutil/SilcHashTableList
*
* NAME
*
};
/***/
-/****f* silcutil/SilcHashTableAPI/SilcHashFunction
+/****f* silcutil/SilcHashFunction
*
* SYNOPSIS
*
***/
typedef SilcUInt32 (*SilcHashFunction)(void *key, void *user_context);
-/****f* silcutil/SilcHashTableAPI/SilcHashCompare
+/****f* silcutil/SilcHashCompare
*
* SYNOPSIS
*
typedef SilcBool (*SilcHashCompare)(void *key1, void *key2,
void *user_context);
-/****f* silcutil/SilcHashTableAPI/SilcHashDestructor
+/****f* silcutil/SilcHashDestructor
*
* SYNOPSIS
*
typedef void (*SilcHashDestructor)(void *key, void *context,
void *user_context);
-/****f* silcutil/SilcHashTableAPI/SilcHashForeach
+/****f* silcutil/SilcHashForeach
*
* SYNOPSIS
*
/* Simple hash table interface */
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_alloc
+/****f* silcutil/silc_hash_table_alloc
*
* SYNOPSIS
*
* it should be a prime. The `hash', `compare' and `destructor' are
* the hash function, the key comparison function and key and context
* destructor function, respectively. The `hash' is mandatory, the others
- * are optional.
+ * are optional. Returns NULL if system is out of memory.
*
***/
SilcHashTable silc_hash_table_alloc(SilcStack stack,
void *destructor_user_context,
SilcBool auto_rehash);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_free
+/****f* silcutil/silc_hash_table_free
*
* SYNOPSIS
*
***/
void silc_hash_table_free(SilcHashTable ht);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_size
+/****f* silcutil/silc_hash_table_size
*
* SYNOPSIS
*
***/
SilcUInt32 silc_hash_table_size(SilcHashTable ht);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_count
+/****f* silcutil/silc_hash_table_count
*
* SYNOPSIS
*
***/
SilcUInt32 silc_hash_table_count(SilcHashTable ht);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_add
+/****f* silcutil/silc_hash_table_add
*
* SYNOPSIS
*
***/
SilcBool silc_hash_table_add(SilcHashTable ht, void *key, void *context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_set
+/****f* silcutil/silc_hash_table_set
*
* SYNOPSIS
*
***/
SilcBool silc_hash_table_set(SilcHashTable ht, void *key, void *context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_del
+/****f* silcutil/silc_hash_table_del
*
* SYNOPSIS
*
***/
SilcBool silc_hash_table_del(SilcHashTable ht, void *key);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_del_by_context
+/****f* silcutil/silc_hash_table_del_by_context
*
* SYNOPSIS
*
SilcBool silc_hash_table_del_by_context(SilcHashTable ht, void *key,
void *context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_find
+/****f* silcutil/silc_hash_table_find
*
* SYNOPSIS
*
SilcBool silc_hash_table_find(SilcHashTable ht, void *key,
void **ret_key, void **ret_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_find_by_context
+/****f* silcutil/silc_hash_table_find_by_context
*
* SYNOPSIS
*
SilcBool silc_hash_table_find_by_context(SilcHashTable ht, void *key,
void *context, void **ret_key);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_find_foreach
+/****f* silcutil/silc_hash_table_find_foreach
*
* SYNOPSIS
*
void silc_hash_table_find_foreach(SilcHashTable ht, void *key,
SilcHashForeach foreach, void *user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_foreach
+/****f* silcutil/silc_hash_table_foreach
*
* SYNOPSIS
*
void silc_hash_table_foreach(SilcHashTable ht, SilcHashForeach foreach,
void *user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_rehash
+/****f* silcutil/silc_hash_table_rehash
*
* SYNOPSIS
*
***/
void silc_hash_table_rehash(SilcHashTable ht, SilcUInt32 new_size);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_list
+/****f* silcutil/silc_hash_table_list
*
* SYNOPSIS
*
***/
void silc_hash_table_list(SilcHashTable ht, SilcHashTableList *htl);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_list_reset
+/****f* silcutil/silc_hash_table_list_reset
*
* SYNOPSIS
*
***/
void silc_hash_table_list_reset(SilcHashTableList *htl);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_get
+/****f* silcutil/silc_hash_table_get
*
* SYNOPSIS
*
/* Extended hash table interface (same as above but with specific
hash and comparison functions). */
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_add_ext
+/****f* silcutil/silc_hash_table_add_ext
*
* SYNOPSIS
*
SilcHashFunction hash,
void *hash_user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_set_ext
+/****f* silcutil/silc_hash_table_set_ext
*
* SYNOPSIS
*
SilcHashFunction hash,
void *hash_user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_del_ext
+/****f* silcutil/silc_hash_table_del_ext
*
* SYNOPSIS
*
SilcHashDestructor destructor,
void *destructor_user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_del_by_context_ext
+/****f* silcutil/silc_hash_table_del_by_context_ext
*
* SYNOPSIS
*
SilcHashDestructor destructor,
void *destructor_user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_find_ext
+/****f* silcutil/silc_hash_table_find_ext
*
* SYNOPSIS
*
SilcHashCompare compare,
void *compare_user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_find_by_context_ext
+/****f* silcutil/silc_hash_table_find_by_context_ext
*
* SYNOPSIS
*
SilcHashCompare compare,
void *compare_user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_find_foreach_ext
+/****f* silcutil/silc_hash_table_find_foreach_ext
*
* SYNOPSIS
*
SilcHashForeach foreach,
void *foreach_user_context);
-/****f* silcutil/SilcHashTableAPI/silc_hash_table_rehash_ext
+/****f* silcutil/silc_hash_table_rehash_ext
*
* SYNOPSIS
*
SilcHashFunction hash,
void *hash_user_context);
+/* Hash functions */
+
+/****f* silcutil/silc_hash_string
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_hash_string(void *key, void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Basic hash function to hash strings. May be used with the SilcHashTable.
+ * This uses Bob Jenkin's one-at-a-time (described in Wikipedia) hash
+ * function.
+ *
+ ***/
+SilcUInt32 silc_hash_string(void *key, void *user_context);
+
+/****f* silcutil/silc_hash_string_case
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_hash_string_case(void *key, void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Basic hash function to hash strings. May be used with the SilcHashTable.
+ * This ignores the string's case, ie. 'Foo' and 'foo' will hash to same
+ * value. This uses Bob Jenkin's one-at-a-time (described in Wikipedia)
+ * hash function.
+ *
+ ***/
+SilcUInt32 silc_hash_string_case(void *key, void *user_context);
+
+/****f* silcutil/silc_hash_utf8_string
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Basic has function to hash UTF-8 strings. May be used with the
+ * SilcHashTable. Used with identifier strings. The key is
+ * expected to be casefolded.
+ *
+ ***/
+SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
+
+/****f* silcutil/silc_hash_uint
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_hash_uint(void *key, void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Basic hash function to hash integers. May be used with the SilcHashTable.
+ * Comparison function is not needed, the SilcHashTable will automatically
+ * compare integer values.
+ *
+ ***/
+SilcUInt32 silc_hash_uint(void *key, void *user_context);
+
+/****f* silcutil/silc_hash_ptr
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_hash_ptr(void *key, void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Basic hash funtion to hash pointers. May be used with the SilcHashTable.
+ * Comparison function is not needed, the SilcHashTable will automatically
+ * compare pointer values.
+ *
+ ***/
+SilcUInt32 silc_hash_ptr(void *key, void *user_context);
+
+/****f* silcutil/silc_hash_data
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_hash_data(void *key, void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Hash binary data. The `user_context' is the data length. This uses Bob
+ * Jenkin's one-at-a-time (described in Wikipedia) hash function.
+ *
+ ***/
+SilcUInt32 silc_hash_data(void *key, void *user_context);
+
+/* Comparison functions */
+
+/****f* silcutil/silc_hash_string_compare
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_hash_string_compare(void *key1, void *key2,
+ * void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Compares two strings. It may be used as SilcHashTable comparison
+ * function.
+ *
+ ***/
+SilcBool silc_hash_string_compare(void *key1, void *key2, void *user_context);
+
+/****f* silcutil/silc_hash_string_case_compare
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_hash_string_case_compare(void *key1, void *key2,
+ * void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Compares two strings. This ignores the case while comparing. It may
+ * be used as SilcHashTable comparison function.
+ *
+ ***/
+SilcBool silc_hash_string_case_compare(void *key1, void *key2,
+ void *user_context);
+
+/****f* silcutil/silc_hash_utf8_compare
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_hash_utf8_compare(void *key1, void *key2,
+ * void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Compares UTF-8 strings. Casefolded and NULL terminated strings are
+ * expected. May be used as SilcHashTable comparison function.
+ *
+ ***/
+SilcBool silc_hash_utf8_compare(void *key1, void *key2, void *user_context);
+
+/****f* silcutil/silc_hash_data_compare
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_hash_data_compare(void *key1, void *key2,
+ * void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * Compares binary data. May be used as SilcHashTable comparison function.
+ *
+ ***/
+SilcBool silc_hash_data_compare(void *key1, void *key2, void *user_context);
+
+/* Destructor functions */
+
+/****f* silcutil/silc_hash_destructor
+ *
+ * SYNOPSIS
+ *
+ * void silc_hash_destructor(void *key, void *context, void *user_context);
+ *
+ * DESCRIPTION
+ *
+ * A generic destructor for SilcHashTable. This will call silc_free for
+ * `key' and `context'.
+ *
+ ***/
+void silc_hash_destructor(void *key, void *context, void *user_context);
+
#endif
projects / runtime.git / blobdiff