lib/hash.h

   1 #ifndef H_HASH
   2 #define H_HASH
   3
   4 /** \file lib/hash.h
   5  * Hash table implemenation.
   6  */
   7
   8 typedef struct hashTable_s * hashTable;
   9
  10 #ifdef __cplusplus
  11 extern "C" {
  12 #endif
  13
  14 /** */
  15 typedef unsigned int (*hashFunctionType) (const void * string) /*@*/;
  16 /** */
  17 typedef int (*hashEqualityType) (const void * key1, const void * key2) /*@*/;
  18
  19 /**
  20  * Return hash value of a string
  21  * @param string  string on which to calculate hash value
  22  * @return hash value
  23  */
  24 unsigned int hashFunctionString(const void * string) /*@*/;
  25
  26 /**
  27  * Compare two hash table entries for equality.
  28  * @param key1          entry 1
  29  * @param key2          entry 2
  30  * @return 0 if entries are equal
  31  */
  32 int hashEqualityString(const void * key1, const void * key2) /*@*/;
  33
  34 /**
  35  * Create hash table.
  36  * If keySize > 0, the key is duplicated within the table (which costs
  37  * memory, but may be useful anyway.
  38  * @param numBuckets    number of hash buckets
  39  * @param keySize       size of key (0 if unknown)
  40  * @param freeData      should data be freed when table is destroyed?
  41  * @param fn            function to generate hash value for key
  42  * @param eq            function to compare hash keys for equality
  43  * @return pointer to initialized hash table
  44  */
  45 hashTable htCreate(int numBuckets, int keySize, int freeData,
  46                 hashFunctionType fn, hashEqualityType eq) /*@*/;
  47
  48 /**
  49  * Destroy hash table.
  50  * @param ht            pointer to hash table
  51  */
  52 void htFree( /*@only@*/ hashTable ht);
  53
  54 /**
  55  * Add item to hash table.
  56  * @param ht            pointer to hash table
  57  * @param key           pointer to key
  58  * @param data          pointer to data value
  59  */
  60 void htAddEntry(hashTable ht, /*@owned@*/ const void * key,
  61         /*@owned@*/ const void * data) /*@modifies ht */;
  62
  63 /**
  64  * Retrieve item from hash table.
  65  * @param ht            pointer to hash table
  66  * @param key           pointer to key value
  67  * @retval data         address to store data value from bucket
  68  * @retval dataCount    address to store data value size from bucket
  69  * @retval tableKey     address to store key value from bucket (may be NULL)
  70  * @return 0 on success, 1 if the item is not found.
  71  */
  72 int htGetEntry(hashTable ht, const void * key, /*@out@*/ const void *** data,
  73                 /*@out@*/ int * dataCount, /*@out@*/ const void ** tableKey)
  74                         /*@modifies *data, *dataCount, *tableKey @*/;
  75
  76 /**
  77  * Check for key in hash table.
  78  * @param ht            pointer to hash table
  79  * @param key           pointer to key value
  80  * @return 1 if the key is present, 0 otherwise
  81  */
  82 int htHasEntry(hashTable ht, const void * key) /*@*/;
  83
  84 #ifdef __cplusplus
  85 }
  86 #endif
  87
  88 #endif