home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / include / xp_hash.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  5.0 KB  |  155 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. #ifndef _XP_HASH_
  20. #define _XP_HASH_
  21.  
  22. #include "xp_list.h"
  23.  
  24. XP_BEGIN_PROTOS
  25.  
  26. typedef uint32 (*XP_HashingFunction) (const void *ele);
  27.  
  28. /* A hash compare function is like strcmp - it should return negative, zero,
  29.    or positive depending on the ordering and equality of its arguments.
  30.  */
  31. typedef int (*XP_HashCompFunction) (const void *ele1, const void *ele2);
  32.  
  33. /* get hash number from a string */
  34. extern uint32 XP_StringHash (const void *xv);
  35. /* Phong's linear congruential hash  */
  36. extern uint32 XP_StringHash2 (const char *ubuf);
  37.  
  38. /* Hash Tables.
  39.  */
  40.  
  41. typedef struct xp_HashTable *XP_HashTable;   /* opaque */
  42.  
  43. typedef XP_Bool (*XP_HashTableMapper) (XP_HashTable table,
  44.                        const void *key, void *value, 
  45.                        void *closure);
  46.  
  47. /* Create a new, empty hash table object.
  48.    SIZE should be your best guess at how many items will go into this
  49.    table; if SIZE is too small, that's ok, but there will be a small
  50.    performance hit.  The size need not be prime.
  51.  */
  52. extern XP_HashTable XP_HashTableNew (uint32 size,
  53.                      XP_HashingFunction  hash_fn, 
  54.                      XP_HashCompFunction compare_fn);
  55.  
  56. /* Clear and free the hash table.
  57.  */
  58. extern void XP_HashTableDestroy (XP_HashTable table);
  59.  
  60. /* Remove all entries from the hash table.
  61.  */
  62. extern void XP_Clrhash (XP_HashTable table);
  63.  
  64. /* Add an association between KEY and VALUE to the hash table.
  65.    An existing association will be replaced.
  66.    (Note that 0 is a legal value.)
  67.    This can only fail if we run out of memory.
  68.  */
  69. extern int XP_Puthash (XP_HashTable table, const void *key, void *value);
  70.  
  71. /* Remove the for KEY in the table, if it exists.
  72.    Returns FALSE if the key wasn't in the table.
  73.  */
  74. extern XP_Bool XP_Remhash (XP_HashTable table, const void *key);
  75.  
  76. /* Looks up KEY in the table and returns the corresponding value.
  77.    If KEY is not in the table, `default_value' will be returned instead.
  78.    (This is necessary since 0 is a valid value with which a key can be
  79.    associated.)
  80.  */
  81. extern void *XP_Gethash (XP_HashTable table, const void *key,
  82.              void *default_value);
  83.  
  84. /* Apply a function to each pair of elements in the hash table.
  85.    If that function returns FALSE, then the mapping stops prematurely.
  86.    The mapping function may call XP_Remhash() on the *current* key, but
  87.    not on any other key in this table.  It also may not clear or destroy
  88.    the table.
  89.  */
  90. extern void XP_Maphash (XP_HashTable table, XP_HashTableMapper mapper,
  91.             void *closure);
  92.  
  93. /* Apply a function to each pair of elements in the hash table.
  94.    After calling the function, that pair will be removed from the table.
  95.    If the function returns FALSE, then the mapping stops prematurely.
  96.    Any items which were not mapped over will still remain in the table,
  97.    but those items which were mapped over will have been freed.
  98.  
  99.    This could also be done by having the mapper function unconditionally
  100.    call XP_Remhash(), but using this function will be slightly more efficient.
  101.  */
  102. extern void XP_MapRemhash (XP_HashTable table, XP_HashTableMapper mapper,
  103.                void *closure);
  104.  
  105.  
  106. /* ===========================================================================
  107.    Hash Lists, which aren't really hash tables.
  108.  */
  109.  
  110.  
  111. #define XP_HASH_DUPLICATE_OBJECT -99
  112.  
  113. typedef struct _XP_HashList {
  114.     XP_List             **list;
  115.     int                  size;
  116.     XP_HashingFunction  hash_func;
  117.     XP_HashCompFunction comp_func;
  118. } XP_HashList;
  119.  
  120. /* create a hash list
  121.  */
  122. extern XP_HashList *
  123. XP_HashListNew (int size, XP_HashingFunction hash_func, XP_HashCompFunction comp_func);
  124.  
  125. /* free a hash list
  126.  */
  127. extern void
  128. XP_HashListDestroy (XP_HashList * hash_struct);
  129.  
  130. /* add an element to a hash list
  131.  *
  132.  * returns positive on success and negative on failure
  133.  *
  134.  * ERROR return codes
  135.  *
  136.  *  XP_HASH_DUPLICATE_OBJECT
  137.  */
  138. extern int
  139. XP_HashListAddObject (XP_HashList * hash_struct, void * new_ele);
  140.  
  141. /* finds an object by name in the hash list
  142.  */
  143. extern void *
  144. XP_HashListFindObject (XP_HashList * hash_struct, void * ele);
  145.  
  146. /* removes an object by name from the hash list
  147.  * and returns the object if found
  148.  */
  149. extern void *
  150. XP_HashListRemoveObject (XP_HashList * hash_struct, void * ele);
  151.  
  152. XP_END_PROTOS
  153.  
  154. #endif /* _XP_HASH_ */
  155.