Main Page | Data Structures | File List | Globals

include/hash.h

00001 /* Generalized hash and string hash (sash) classes.
00002  * By Richard W.M. Jones <rich@annexia.org>
00003  *
00004  * This library is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU Library General Public
00006  * License as published by the Free Software Foundation; either
00007  * version 2 of the License, or (at your option) any later version.
00008  *
00009  * This library is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * Library General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU Library General Public
00015  * License along with this library; if not, write to the Free
00016  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00017  *
00018  * $Id: hash.h,v 1.1 2003/03/28 15:50:55 chappell Exp $
00019  */
00020 
00021 #ifndef HASH_H
00022 #define HASH_H
00023 
00024 #include <vector.h>
00025 
00026 /* Note, hash and sash are identical but for the fact that
00027  * hash maps fixed sized keys to values (eg. int -> int or
00028  * int -> struct) and sash maps nul-terminated ASCII strings
00029  * to nul-terminated ASCII strings (ie. string -> string ONLY).
00030  * shash maps nul-terminated ASCII strings to anything else.
00031  */
00032 
00033 struct hash;
00034 typedef struct hash *hash;
00035 
00036 struct sash;
00037 typedef struct sash *sash;
00038 
00039 struct shash;
00040 typedef struct shash *shash;
00041 
00042 /* Function: new_hash - allocate a new hash
00043  * Function: _hash_new
00044  *
00045  * Allocate a new hash in @code{pool} mapping
00046  * @code{key_type} to @code{value_type}. You can map both
00047  * simple types like @code{int} and also aggregate types
00048  * like structures and unions. However, beware of aggregate
00049  * types that might contain 'holes' because of alignment --
00050  * such types will probably not work as you expect, particularly
00051  * if used as keys.
00052  *
00053  * If you wish to have
00054  * a hash which maps strings to something, then calling
00055  * @code{new_hash(pool, char *, char *)} (for example) will not do what
00056  * you expect. You are better to use either a sash (string to string hash)
00057  * or a shash (string to anything hash) instead (see
00058  * @ref{new_sash(3)} and @ref{new_shash(3)}).
00059  */
00060 #define new_hash(pool,key_type,value_type) _hash_new ((pool), sizeof (key_type), sizeof (value_type))
00061 extern hash _hash_new (pool, size_t key_size, size_t value_size);
00062 
00063 /* Function: copy_hash - copy a hash
00064  *
00065  * Copy a hash into a new pool. This function copies the keys
00066  * and values, but if keys and values are pointers, then it does
00067  * not perform a 'deep' copy.
00068  */
00069 extern hash copy_hash (pool, hash);
00070 
00071 /* Function: hash_get - look up in a hash
00072  * Function: _hash_get
00073  * Function: hash_get_ptr
00074  * Function: _hash_get_ptr
00075  * Function: hash_exists
00076  *
00077  * Get the @code{value} associated with key @code{key} and return true.
00078  * If there is no @code{value} associated with @code{key}, this returns
00079  * false and @code{value} is left unchanged.
00080  *
00081  * The @code{*_ptr} variants return a pointer rather than copying
00082  * out the entire value object. The pointer is typically only
00083  * valid for a short period of time. Particularly if you insert
00084  * or remove elements from the hash, this pointer may become
00085  * invalid.
00086  *
00087  * @code{hash_exists} simply tests whether or not @code{key} exists
00088  * in the hash. If so, it returns true, otherwise false.
00089  */
00090 #define hash_get(h,key,value) _hash_get ((h), &(key), &(value))
00091 extern int _hash_get (hash, const void *key, void *value);
00092 #define hash_get_ptr(h,key,ptr) ((ptr) = ((typeof (ptr))_hash_get_ptr ((h), &(key))))
00093 extern const void *_hash_get_ptr (hash, const void *key);
00094 #define hash_exists(h,key) (_hash_get_ptr ((h), &(key)) ? 1 : 0)
00095 
00096 /* Function: hash_insert - insert a (key, value) pair into a hash
00097  * Function: _hash_insert
00098  *
00099  * Insert an element (@code{key}, @code{value}) into the hash.
00100  * If @code{key} already
00101  * exists in the hash, then the existing value is replaced by
00102  * @code{value}
00103  * and the function returns true. If there was no previous @code{key}
00104  * in the hash then this function returns false.
00105  */
00106 #define hash_insert(h,key,value) _hash_insert((h),&(key),&(value))
00107 extern int _hash_insert (hash, const void *key, const void *value);
00108 
00109 /* Function: hash_erase - erase a key from a hash
00110  * Function: _hash_erase
00111  *
00112  * Erase @code{key} from the hash. If an element was erased,
00113  * this returns true, else this returns false.
00114  */
00115 #define hash_erase(h,key) _hash_erase((h),&(key))
00116 extern int _hash_erase (hash, const void *key);
00117 
00118 /* Function: hash_keys - return a vector of the keys or values in a hash
00119  * Function: hash_keys_in_pool
00120  * Function: hash_values
00121  * Function: hash_values_in_pool
00122  * 
00123  * Return a vector containing all the keys or values of hash. The
00124  * @code{*_in_pool} variants allow you to allocate the vector in
00125  * another pool (the default is to allocate the vector in the same
00126  * pool as the hash).
00127  */
00128 extern vector hash_keys (hash);
00129 extern vector hash_keys_in_pool (hash, pool);
00130 extern vector hash_values (hash);
00131 extern vector hash_values_in_pool (hash, pool);
00132 
00133 /* Function: hash_size - return the number of (key, value) pairs in a hash
00134  *
00135  * Count the number of (key, value) pairs in the hash.
00136  */
00137 extern int hash_size (hash);
00138 
00139 /* Function: hash_get_buckets_used - return the number of buckets in a hash
00140  * Function: hash_get_buckets_allocated
00141  *
00142  * Return the number of hash buckets used and allocated. The number of
00143  * buckets allocated is always a power of 2. See also
00144  * @ref{hash_set_buckets_allocated} to change the number used
00145  * in the hash.
00146  */
00147 extern int hash_get_buckets_used (hash);
00148 extern int hash_get_buckets_allocated (hash);
00149 
00150 /* Function: hash_set_buckets_allocated - set the number of buckets
00151  *
00152  * Set the number of buckets allocated. You may ONLY do this when you
00153  * have just created the hash and before you have inserted any elements.
00154  * Otherwise the results are undefined (and probably bad). The number
00155  * of buckets MUST be a power of 2.
00156  */
00157 extern void hash_set_buckets_allocated (hash, int);
00158 
00159 /* Function: new_sash - allocate a new sash (string hash)
00160  *
00161  * Allocate a new sash in @code{pool} mapping
00162  * strings to strings.
00163  *
00164  * Use a string hash in preference to a hash of
00165  * @code{char *} -> @code{char *} which will probably not
00166  * quite work as you expect.
00167  */
00168 extern sash new_sash (pool);
00169 
00170 /* Function: copy_sash - copy a sash
00171  *
00172  * Copy a sash into a new pool. This function copies the keys
00173  * and values, but if keys and values are pointers, then it does
00174  * not perform a 'deep' copy.
00175  */
00176 extern sash copy_sash (pool, sash);
00177 
00178 /* Function: sash_get - look up in a sash
00179  * Function: _sash_get
00180  * Function: sash_exists
00181  *
00182  * Get the @code{value} associated with key @code{key} and return true.
00183  * If there is no @code{value} associated with @code{key}, this returns
00184  * false and @code{value} is left unchanged.
00185  *
00186  * @code{sash_exists} simply tests whether or not @code{key} exists
00187  * in the sash. If so, it returns true, otherwise false.
00188  */
00189 #define sash_get(sash,key,value) _sash_get((sash),(key),&(value))
00190 extern int _sash_get (sash, const char *key, const char **ptr);
00191 #define sash_exists(sash,key) _sash_get ((sash), (key), 0)
00192 
00193 /* Function: sash_insert - insert a (key, value) pair into a sash
00194  *
00195  * Insert an element (@code{key}, @code{value}) into the sash.
00196  * If @code{key} already
00197  * exists in the sash, then the existing value is replaced by
00198  * @code{value}
00199  * and the function returns true. If there was no previous @code{key}
00200  * in the sash then this function returns false.
00201  */
00202 extern int sash_insert (sash, const char *key, const char *value);
00203 
00204 /* Function: sash_erase - erase a key from a sash
00205  *
00206  * Erase @code{key} from the sash. If an element was erased,
00207  * this returns true, else this returns false.
00208  */
00209 extern int sash_erase (sash, const char *key);
00210 
00211 /* Function: sash_keys - return a vector of the keys or values in a sash
00212  * Function: sash_keys_in_pool
00213  * Function: sash_values
00214  * Function: sash_values_in_pool
00215  * 
00216  * Return a vector containing all the keys or values of sash. The
00217  * @code{*_in_pool} variants allow you to allocate the vector in
00218  * another pool (the default is to allocate the vector in the same
00219  * pool as the sash).
00220  */
00221 extern vector sash_keys (sash);
00222 extern vector sash_keys_in_pool (sash, pool);
00223 extern vector sash_values (sash);
00224 extern vector sash_values_in_pool (sash, pool);
00225 
00226 /* Function: sash_size - return the number of (key, value) pairs in a sash
00227  *
00228  * Count the number of (key, value) pairs in the sash.
00229  */
00230 extern int sash_size (sash);
00231 
00232 /* Function: sash_get_buckets_used - return the number of buckets in a sash
00233  * Function: sash_get_buckets_allocated
00234  *
00235  * Return the number of sash buckets used and allocated. The number of
00236  * buckets allocated is always a power of 2. See also
00237  * @ref{sash_set_buckets_allocated} to change the number used
00238  * in the sash.
00239  */
00240 extern int sash_get_buckets_used (sash);
00241 extern int sash_get_buckets_allocated (sash);
00242 
00243 /* Function: sash_set_buckets_allocated - set the number of buckets
00244  *
00245  * Set the number of buckets allocated. You may ONLY do this when you
00246  * have just created the sash and before you have inserted any elements.
00247  * Otherwise the results are undefined (and probably bad). The number
00248  * of buckets MUST be a power of 2.
00249  */
00250 extern void sash_set_buckets_allocated (sash, int);
00251 
00252 /* Function: new_shash - allocate a new shash (string -> something hash)
00253  *
00254  * Allocate a new shash in @code{pool} mapping
00255  * strings to strings.
00256  *
00257  * Use a shash in preference to a hash of
00258  * @code{char *} -> something which will probably not
00259  * quite work as you expect.
00260  */
00261 #define new_shash(pool,value_type) _shash_new ((pool), sizeof (value_type))
00262 extern shash _shash_new (pool, size_t value_size);
00263 
00264 /* Function: copy_shash - copy a shash
00265  *
00266  * Copy a shash into a new pool. This function copies the keys
00267  * and values, but if keys and values are pointers, then it does
00268  * not perform a 'deep' copy.
00269  */
00270 extern shash copy_shash (pool, shash);
00271 
00272 /* Function: shash_get - look up in a shash
00273  * Function: _shash_get
00274  * Function: shash_get_ptr
00275  * Function: _shash_get_ptr
00276  * Function: shash_exists
00277  *
00278  * Get the @code{value} associated with key @code{key} and return true.
00279  * If there is no @code{value} associated with @code{key}, this returns
00280  * false and @code{value} is left unchanged.
00281  *
00282  * The @code{*_ptr} variants return a pointer rather than copying
00283  * out the entire value object. The pointer is typically only
00284  * valid for a short period of time. Particularly if you insert
00285  * or remove elements from the shash, this pointer may become
00286  * invalid.
00287  *
00288  * @code{shash_exists} simply tests whether or not @code{key} exists
00289  * in the shash. If so, it returns true, otherwise false.
00290  */
00291 #define shash_get(shash,key,value) _shash_get((shash),(key),&(value))
00292 extern int _shash_get (shash, const char *key, void *value);
00293 #define shash_get_ptr(h,key,ptr) ((ptr) = ((typeof (ptr))_shash_get_ptr ((h),(key))))
00294 extern const void *_shash_get_ptr (shash, const char *key);
00295 #define shash_exists(shash,key) (_shash_get_ptr ((shash), (key)) ? 1 : 0)
00296 
00297 /* Function: shash_insert - insert a (key, value) pair into a shash
00298  * Function: _shash_insert
00299  *
00300  * Insert an element (@code{key}, @code{value}) into the shash.
00301  * If @code{key} already
00302  * exists in the shash, then the existing value is replaced by
00303  * @code{value}
00304  * and the function returns true. If there was no previous @code{key}
00305  * in the shash then this function returns false.
00306  */
00307 #define shash_insert(h,key,value) _shash_insert((h),(key),&(value))
00308 extern int _shash_insert (shash, const char *key, const void *value);
00309 
00310 /* Function: shash_erase - erase a key from a shash
00311  *
00312  * Erase @code{key} from the shash. If an element was erased,
00313  * this returns true, else this returns false.
00314  */
00315 extern int shash_erase (shash, const char *key);
00316 
00317 /* Function: shash_keys - return a vector of the keys or values in a shash
00318  * Function: shash_keys_in_pool
00319  * Function: shash_values
00320  * Function: shash_values_in_pool
00321  * 
00322  * Return a vector containing all the keys or values of shash. The
00323  * @code{*_in_pool} variants allow you to allocate the vector in
00324  * another pool (the default is to allocate the vector in the same
00325  * pool as the shash).
00326  */
00327 extern vector shash_keys (shash);
00328 extern vector shash_keys_in_pool (shash, pool);
00329 extern vector shash_values (shash);
00330 extern vector shash_values_in_pool (shash, pool);
00331 
00332 /* Function: shash_size - return the number of (key, value) pairs in a shash
00333  *
00334  * Count the number of (key, value) pairs in the shash.
00335  */
00336 extern int shash_size (shash);
00337 
00338 /* Function: shash_get_buckets_used - return the number of buckets in a shash
00339  * Function: shash_get_buckets_allocated
00340  *
00341  * Return the number of shash buckets used and allocated. The number of
00342  * buckets allocated is always a power of 2. See also
00343  * @ref{shash_set_buckets_allocated} to change the number used
00344  * in the shash.
00345  */
00346 extern int shash_get_buckets_used (shash);
00347 extern int shash_get_buckets_allocated (shash);
00348 
00349 /* Function: shash_set_buckets_allocated - set the number of buckets
00350  *
00351  * Set the number of buckets allocated. You may ONLY do this when you
00352  * have just created the shash and before you have inserted any elements.
00353  * Otherwise the results are undefined (and probably bad). The number
00354  * of buckets MUST be a power of 2.
00355  */
00356 extern void shash_set_buckets_allocated (shash, int);
00357 
00358 #endif /* HASH_H */

Generated on Fri Feb 20 15:17:47 2004 for PPR Libraries by doxygen 1.3.5