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 */