1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJ_HASH_H__ 21 #define __PJ_HASH_H__ 22 23 /** 24 * @file hash.h 25 * @brief Hash Table. 26 */ 27 28 #include <pj/types.h> 29 30 PJ_BEGIN_DECL 31 32 /** 33 * @defgroup PJ_HASH Hash Table 34 * @ingroup PJ_DS 35 * @{ 36 * A hash table is a dictionary in which keys are mapped to array positions by 37 * hash functions. Having the keys of more than one item map to the same 38 * position is called a collision. In this library, we will chain the nodes 39 * that have the same key in a list. 40 */ 41 42 /** 43 * If this constant is used as keylen, then the key is interpreted as 44 * NULL terminated string. 45 */ 46 #define PJ_HASH_KEY_STRING ((unsigned)-1) 47 48 /** 49 * This indicates the size of of each hash entry. 50 */ 51 #define PJ_HASH_ENTRY_BUF_SIZE (3*sizeof(void*) + 2*sizeof(pj_uint32_t)) 52 53 /** 54 * Type declaration for entry buffer, used by #pj_hash_set_np() 55 */ 56 typedef void *pj_hash_entry_buf[(PJ_HASH_ENTRY_BUF_SIZE+sizeof(void*)-1)/(sizeof(void*))]; 57 58 /** 59 * This is the function that is used by the hash table to calculate hash value 60 * of the specified key. 61 * 62 * @param hval the initial hash value, or zero. 63 * @param key the key to calculate. 64 * @param keylen the length of the key, or PJ_HASH_KEY_STRING to treat 65 * the key as null terminated string. 66 * 67 * @return the hash value. 68 */ 69 PJ_DECL(pj_uint32_t) pj_hash_calc(pj_uint32_t hval, 70 const void *key, unsigned keylen); 71 72 73 /** 74 * Convert the key to lowercase and calculate the hash value. The resulting 75 * string is stored in \c result. 76 * 77 * @param hval The initial hash value, normally zero. 78 * @param result Optional. Buffer to store the result, which must be enough 79 * to hold the string. 80 * @param key The input key to be converted and calculated. 81 * 82 * @return The hash value. 83 */ 84 PJ_DECL(pj_uint32_t) pj_hash_calc_tolower(pj_uint32_t hval, 85 char *result, 86 const pj_str_t *key); 87 88 /** 89 * Create a hash table with the specified 'bucket' size. 90 * 91 * @param pool the pool from which the hash table will be allocated from. 92 * @param size the bucket size, which will be round-up to the nearest 2^n-1 93 * 94 * @return the hash table. 95 */ 96 PJ_DECL(pj_hash_table_t*) pj_hash_create(pj_pool_t *pool, unsigned size); 97 98 99 /** 100 * Get the value associated with the specified key. 101 * 102 * @param ht the hash table. 103 * @param key the key to look for. 104 * @param keylen the length of the key, or PJ_HASH_KEY_STRING to use the 105 * string length of the key. 106 * @param hval if this argument is not NULL and the value is not zero, 107 * the value will be used as the computed hash value. If 108 * the argument is not NULL and the value is zero, it will 109 * be filled with the computed hash upon return. 110 * 111 * @return the value associated with the key, or NULL if the key is not found. 112 */ 113 PJ_DECL(void *) pj_hash_get( pj_hash_table_t *ht, 114 const void *key, unsigned keylen, 115 pj_uint32_t *hval ); 116 117 118 /** 119 * Variant of #pj_hash_get() with the key being converted to lowercase when 120 * calculating the hash value. 121 * 122 * @see pj_hash_get() 123 */ 124 PJ_DECL(void *) pj_hash_get_lower( pj_hash_table_t *ht, 125 const void *key, unsigned keylen, 126 pj_uint32_t *hval ); 127 128 129 /** 130 * Associate/disassociate a value with the specified key. If value is not 131 * NULL and entry already exists, the entry's value will be overwritten. 132 * If value is not NULL and entry does not exist, a new one will be created 133 * with the specified pool. Otherwise if value is NULL, entry will be 134 * deleted if it exists. 135 * 136 * @param pool the pool to allocate the new entry if a new entry has to be 137 * created. 138 * @param ht the hash table. 139 * @param key the key. If pool is not specified, the key MUST point to 140 * buffer that remains valid for the duration of the entry. 141 * @param keylen the length of the key, or PJ_HASH_KEY_STRING to use the 142 * string length of the key. 143 * @param hval if the value is not zero, then the hash table will use 144 * this value to search the entry's index, otherwise it will 145 * compute the key. This value can be obtained when calling 146 * #pj_hash_get(). 147 * @param value value to be associated, or NULL to delete the entry with 148 * the specified key. 149 */ 150 PJ_DECL(void) pj_hash_set( pj_pool_t *pool, pj_hash_table_t *ht, 151 const void *key, unsigned keylen, pj_uint32_t hval, 152 void *value ); 153 154 155 /** 156 * Variant of #pj_hash_set() with the key being converted to lowercase when 157 * calculating the hash value. 158 * 159 * @see pj_hash_set() 160 */ 161 PJ_DECL(void) pj_hash_set_lower( pj_pool_t *pool, pj_hash_table_t *ht, 162 const void *key, unsigned keylen, 163 pj_uint32_t hval, void *value ); 164 165 166 /** 167 * Associate/disassociate a value with the specified key. This function works 168 * like #pj_hash_set(), except that it doesn't use pool (hence the np -- no 169 * pool suffix). If new entry needs to be allocated, it will use the entry_buf. 170 * 171 * @param ht the hash table. 172 * @param key the key. 173 * @param keylen the length of the key, or PJ_HASH_KEY_STRING to use the 174 * string length of the key. 175 * @param hval if the value is not zero, then the hash table will use 176 * this value to search the entry's index, otherwise it will 177 * compute the key. This value can be obtained when calling 178 * #pj_hash_get(). 179 * @param entry_buf Buffer which will be used for the new entry, when one needs 180 * to be created. 181 * @param value value to be associated, or NULL to delete the entry with 182 * the specified key. 183 */ 184 PJ_DECL(void) pj_hash_set_np(pj_hash_table_t *ht, 185 const void *key, unsigned keylen, 186 pj_uint32_t hval, pj_hash_entry_buf entry_buf, 187 void *value); 188 189 /** 190 * Variant of #pj_hash_set_np() with the key being converted to lowercase 191 * when calculating the hash value. 192 * 193 * @see pj_hash_set_np() 194 */ 195 PJ_DECL(void) pj_hash_set_np_lower(pj_hash_table_t *ht, 196 const void *key, unsigned keylen, 197 pj_uint32_t hval, 198 pj_hash_entry_buf entry_buf, 199 void *value); 200 201 /** 202 * Get the total number of entries in the hash table. 203 * 204 * @param ht the hash table. 205 * 206 * @return the number of entries in the hash table. 207 */ 208 PJ_DECL(unsigned) pj_hash_count( pj_hash_table_t *ht ); 209 210 211 /** 212 * Get the iterator to the first element in the hash table. 213 * 214 * @param ht the hash table. 215 * @param it the iterator for iterating hash elements. 216 * 217 * @return the iterator to the hash element, or NULL if no element presents. 218 */ 219 PJ_DECL(pj_hash_iterator_t*) pj_hash_first( pj_hash_table_t *ht, 220 pj_hash_iterator_t *it ); 221 222 223 /** 224 * Get the next element from the iterator. 225 * 226 * @param ht the hash table. 227 * @param it the hash iterator. 228 * 229 * @return the next iterator, or NULL if there's no more element. 230 */ 231 PJ_DECL(pj_hash_iterator_t*) pj_hash_next( pj_hash_table_t *ht, 232 pj_hash_iterator_t *it ); 233 234 /** 235 * Get the value associated with a hash iterator. 236 * 237 * @param ht the hash table. 238 * @param it the hash iterator. 239 * 240 * @return the value associated with the current element in iterator. 241 */ 242 PJ_DECL(void*) pj_hash_this( pj_hash_table_t *ht, 243 pj_hash_iterator_t *it ); 244 245 246 /** 247 * @} 248 */ 249 250 PJ_END_DECL 251 252 #endif 253 254 255