/* ******************************************************************************* * * * COPYRIGHT: * * (C) Copyright Taligent, Inc., 1997 * * (C) Copyright International Business Machines Corporation, 1997-1999 * * Licensed Material - Program-Property of IBM - All Rights Reserved. * * US Government Users Restricted Rights - Use, duplication, or disclosure * * restricted by GSA ADP Schedule Contract with IBM Corp. * * * ******************************************************************************* * * File uhash.h * * Modification History: * * Date Name Description * 03/12/99 stephen Creation. ******************************************************************************* */ #ifndef UHASH_H #define UHASH_H #include "utypes.h" /* * Hashtable stores key-value pairs and does efficient lookup based on keys. * It also provides a protocol for enumerating through the key-value pairs * (although it does so in no particular order). * Values are stored as void* pointers. */ /** * A hashing function. * @param parm A pointer to the data to be hashed. * @return A NON-NEGATIVE hash code for parm. */ typedef int32_t (*UHashFunction)(const void*); /** * A function called when performing a uhash_remove or a uhash_close * and uhash_put * @param parm A pointer to the data to be hashed. */ typedef void (*ValueDeleter)(void* valuePtr); /** The UHashtable struct */ struct UHashtable { /* Internals - DO NOT TOUCH! */ int32_t primeIndex; /* Index into our prime table for length */ int32_t highWaterMark; /* Used for determiningg rehashing time */ int32_t lowWaterMark; float highWaterFactor; float lowWaterFactor; int32_t count; /* The number of items in this table */ int32_t *hashes; /* Hash codes associated with values */ void **values; /* The stored values */ int32_t length; /* The physical size of hashes and values */ ValueDeleter valueDelete; /*Function deletes values when required, if NULL won't do anything*/ UHashFunction hashFunction; /* Hashing function */ int32_t toBeDeletedCount; void** toBeDeleted; bool_t isGrowable; }; typedef struct UHashtable UHashtable; /** * Initialize a new UHashtable. * @param func A pointer to the hashing function to be used by this hash table. * @param status A pointer to an UErrorCode to receive any errors. * @return A pointer to a UHashtable, or 0 if an error occurred. * @see uhash_openSize */ U_CAPI UHashtable* uhash_open(UHashFunction func, UErrorCode *status); /** * Initialize a new UHashtable with a given size. If after a sequence of uhash_put the table runs out of space * An error will be signalled by uhash_put. * @param hash A pointer to the UHashtable to be initialized. * @param func A pointer to the hashing function to be used by this hash table. * @param size The maximal capacity of this hash table. * @param status A pointer to an UErrorCode to receive any errors. * @return A pointer to a UHashtable, or 0 if an error occurred. * @see uhash_open */ U_CAPI UHashtable* uhash_openSize(UHashFunction func, int32_t size, UErrorCode *status); /** * Close a UHashtable, releasing the memory used. * @param hash The UHashtable to close. */ U_CAPI void uhash_close(UHashtable *hash); U_CAPI void uhash_setValueDeleter(UHashtable *hash, ValueDeleter del); /** * Get the number of items stored in a UHashtable. * @param hash The UHashtable to query. * @return The number of items stored in hash. */ U_CAPI int32_t uhash_size(const UHashtable *hash); /** * Put an item in a UHashtable. * @param hash The target UHashtable. * @param value The value to store. * @param status A pointer to an UErrorCode to receive any errors. * @return The hash code associated with value. * @see uhash_get */ U_CAPI int32_t uhash_put(UHashtable *hash, void *value, UErrorCode *status); /** * Put an item in a UHashtable. * @param hash The target UHashtable. * @param value The value to store. * @param status A pointer to an UErrorCode to receive any errors. * @return The hash code associated with value. * @see uhash_get */ U_CAPI int32_t uhash_putKey(UHashtable *hash, int32_t valueKey, void *value, UErrorCode *status); /** * Get an item from a UHashtable. * @param hash The target UHashtable. * @param key The hash code of the desired value. * @return The requested item, or 0 if not found. */ U_CAPI void* uhash_get(const UHashtable *hash, int32_t key); /** * Remove an item from a UHashtable. * @param hash The target UHashtable. * @param key The hash code of the value to be removed. * @param status A pointer to an UErrorCode to receive any errors. * @return The item removed, or 0 if not found. */ U_CAPI void* uhash_remove(UHashtable *hash, int32_t key, UErrorCode *status); /** * Iterate through the elements of a UHashtable. * @param hash The target UHashtable. * @param pos A pointer to an integer. This should be set to -1 to retrieve * the first value, and should subsequently not be changed by the caller. * @return The next item in the hash table, or 0 if no items remain. */ U_CAPI void* uhash_nextElement(const UHashtable *hash, int32_t *pos); /* Predefined hashing functions */ /** Indicates an invalid hash code */ #define UHASH_INVALID 0 /** Indicates a value is empty or 0 */ #define UHASH_EMPTY 1 /** * Generate a hash code for a null-terminated ustring. * If the string is not null-terminated the behavior of this * function is undefined. * @param parm The ustring (const UChar*) to hash. * @return A hash code for parm. */ U_CAPI int32_t uhash_hashUString(const void *parm); /** * Generate a hash code for a null-terminated string. * If the string is not null-terminated the behavior of this * function is undefined. * @param parm The string (const char*) to hash. * @return A hash code for parm. */ U_CAPI int32_t uhash_hashString(const void *parm); /** * Generate a hash code for long integer. * @param parm The long (cast to void*) to hash. * @return A hash code for parm. */ U_CAPI int32_t uhash_hashLong(const void *parm); #endif