home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 6 / AACD06.ISO / AACD / Programming / ICU / src / icu / source / common / uhash.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-10-19  |  6.4 KB  |  218 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright Taligent, Inc.,  1997                                       *
  6. *   (C) Copyright International Business Machines Corporation,  1997-1999     *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  10. *                                                                             *
  11. *******************************************************************************
  12. *
  13. * File uhash.h
  14. *
  15. * Modification History:
  16. *
  17. *   Date        Name        Description
  18. *   03/12/99    stephen     Creation.
  19. *******************************************************************************
  20. */
  21.  
  22. #ifndef UHASH_H
  23. #define UHASH_H
  24.  
  25. #include "utypes.h"
  26.  
  27. /*
  28.  * Hashtable stores key-value pairs and does efficient lookup based on keys.
  29.  * It also provides a protocol for enumerating through the key-value pairs
  30.  * (although it does so in no particular order). 
  31.  * Values are stored as void* pointers.
  32.  */
  33.  
  34. /**
  35.  * A hashing function.
  36.  * @param parm A pointer to the data to be hashed.
  37.  * @return A NON-NEGATIVE hash code for parm.
  38.  */
  39. typedef int32_t (*UHashFunction)(const void*);
  40. /**
  41.  * A function called when performing a <TT>uhash_remove</TT> or a <TT>uhash_close</TT>
  42.  * and <TT>uhash_put</TT>
  43.  * @param parm A pointer to the data to be hashed.
  44.  */
  45. typedef void (*ValueDeleter)(void* valuePtr);
  46. /** The UHashtable struct */
  47. struct UHashtable {
  48.  
  49.   /* Internals - DO NOT TOUCH! */
  50.   
  51.   int32_t     primeIndex;     /* Index into our prime table for length */
  52.   int32_t     highWaterMark;     /* Used for determiningg rehashing time */
  53.   int32_t     lowWaterMark;
  54.   float     highWaterFactor;
  55.   float     lowWaterFactor;
  56.  
  57.   int32_t     count;      /* The number of items in this table */
  58.   
  59.   int32_t     *hashes;    /* Hash codes associated with values */
  60.   void         **values;      /* The stored values */
  61.   int32_t     length;     /* The physical size of hashes and values */
  62.  
  63.   ValueDeleter valueDelete; /*Function deletes values when required, if NULL won't do anything*/
  64.   UHashFunction hashFunction;      /* Hashing function */
  65.  
  66.   int32_t    toBeDeletedCount; 
  67.   void**    toBeDeleted;
  68.   bool_t isGrowable;
  69. };
  70. typedef struct UHashtable UHashtable;
  71.  
  72. /**
  73.  * Initialize a new UHashtable.
  74.  * @param func A pointer to the hashing function to be used by this hash table.
  75.  * @param status A pointer to an UErrorCode to receive any errors.
  76.  * @return A pointer to a UHashtable, or 0 if an error occurred.
  77.  * @see uhash_openSize
  78.  */
  79. U_CAPI UHashtable*
  80. uhash_open(UHashFunction func,
  81.        UErrorCode *status);
  82.  
  83. /**
  84.  * Initialize a new UHashtable with a given size. If after a sequence of uhash_put the table runs out of space
  85.  * An error will be signalled by uhash_put.
  86.  * @param hash A pointer to the UHashtable to be initialized.
  87.  * @param func A pointer to the hashing function to be used by this hash table.
  88.  * @param size The maximal capacity of this hash table.
  89.  * @param status A pointer to an UErrorCode to receive any errors.
  90.  * @return A pointer to a UHashtable, or 0 if an error occurred.
  91.  * @see uhash_open
  92.  */
  93. U_CAPI UHashtable*
  94. uhash_openSize(UHashFunction func,
  95.            int32_t size,
  96.            UErrorCode *status);
  97.  
  98. /**
  99.  * Close a UHashtable, releasing the memory used.
  100.  * @param hash The UHashtable to close.
  101.  */
  102. U_CAPI void
  103. uhash_close(UHashtable *hash);
  104.  
  105.  
  106. U_CAPI void
  107. uhash_setValueDeleter(UHashtable *hash, ValueDeleter del);
  108.  
  109. /**
  110.  * Get the number of items stored in a UHashtable.
  111.  * @param hash The UHashtable to query.
  112.  * @return The number of items stored in hash.
  113.  */
  114. U_CAPI int32_t
  115. uhash_size(const UHashtable *hash);
  116.  
  117. /**
  118.  * Put an item in a UHashtable.
  119.  * @param hash The target UHashtable.
  120.  * @param value The value to store.
  121.  * @param status A pointer to an UErrorCode to receive any errors.
  122.  * @return The hash code associated with value.
  123.  * @see uhash_get
  124.  */
  125. U_CAPI int32_t
  126. uhash_put(UHashtable *hash,
  127.       void *value,
  128.       UErrorCode *status);
  129.  
  130. /**
  131.  * Put an item in a UHashtable.
  132.  * @param hash The target UHashtable.
  133.  * @param value The value to store.
  134.  * @param status A pointer to an UErrorCode to receive any errors.
  135.  * @return The hash code associated with value.
  136.  * @see uhash_get
  137.  */
  138. U_CAPI int32_t
  139. uhash_putKey(UHashtable *hash,
  140.          int32_t valueKey,
  141.          void *value,
  142.          UErrorCode *status);
  143.  
  144. /**
  145.  * Get an item from a UHashtable.
  146.  * @param hash The target UHashtable.
  147.  * @param key The hash code of the desired value.
  148.  * @return The requested item, or 0 if not found.
  149.  */
  150. U_CAPI void*
  151. uhash_get(const UHashtable *hash, 
  152.       int32_t key);
  153.  
  154. /**
  155.  * Remove an item from a UHashtable.
  156.  * @param hash The target UHashtable.
  157.  * @param key The hash code of the value to be removed.
  158.  * @param status A pointer to an UErrorCode to receive any errors.
  159.  * @return The item removed, or 0 if not found.
  160.  */
  161. U_CAPI void*
  162. uhash_remove(UHashtable *hash,
  163.          int32_t key,
  164.          UErrorCode *status);
  165.  
  166. /**
  167.  * Iterate through the elements of a UHashtable.
  168.  * @param hash The target UHashtable.
  169.  * @param pos A pointer to an integer.  This should be set to -1 to retrieve
  170.  * the first value, and should subsequently not be changed by the caller.
  171.  * @return The next item in the hash table, or 0 if no items remain.
  172.  */
  173. U_CAPI void*
  174. uhash_nextElement(const UHashtable *hash,
  175.           int32_t *pos);
  176.  
  177.  
  178. /* Predefined hashing functions */
  179.  
  180. /** Indicates an invalid hash code */
  181. #define UHASH_INVALID 0
  182.  
  183. /** Indicates a value is empty or 0 */
  184. #define UHASH_EMPTY 1
  185.  
  186. /**
  187.  * Generate a hash code for a null-terminated ustring.
  188.  * If the string is not null-terminated the behavior of this
  189.  * function is undefined.
  190.  * @param parm The ustring (const UChar*) to hash.
  191.  * @return A hash code for parm.
  192.  */
  193. U_CAPI int32_t
  194. uhash_hashUString(const void *parm);
  195.  
  196. /**
  197.  * Generate a hash code for a null-terminated string.
  198.  * If the string is not null-terminated the behavior of this
  199.  * function is undefined.
  200.  * @param parm The string (const char*) to hash.
  201.  * @return A hash code for parm.
  202.  */
  203. U_CAPI int32_t
  204. uhash_hashString(const void *parm);
  205.  
  206. /**
  207.  * Generate a hash code for long integer.
  208.  * @param parm The long (cast to void*) to hash.
  209.  * @return A hash code for parm.
  210.  */
  211. U_CAPI int32_t
  212. uhash_hashLong(const void *parm);
  213.  
  214. #endif
  215.  
  216.  
  217.  
  218.