Apache Portable Runtime
|
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_HASH_H 00018 #define APR_HASH_H 00019 00020 /** 00021 * @file apr_hash.h 00022 * @brief APR Hash Tables 00023 */ 00024 00025 #include "apr_pools.h" 00026 00027 #ifdef __cplusplus 00028 extern "C" { 00029 #endif 00030 00031 /** 00032 * @defgroup apr_hash Hash Tables 00033 * @ingroup APR 00034 * @{ 00035 */ 00036 00037 /** 00038 * When passing a key to apr_hash_set or apr_hash_get, this value can be 00039 * passed to indicate a string-valued key, and have apr_hash compute the 00040 * length automatically. 00041 * 00042 * @remark apr_hash will use strlen(key) for the length. The NUL terminator 00043 * is not included in the hash value (why throw a constant in?). 00044 * Since the hash table merely references the provided key (rather 00045 * than copying it), apr_hash_this() will return the NUL-term'd key. 00046 */ 00047 #define APR_HASH_KEY_STRING (-1) 00048 00049 /** 00050 * Abstract type for hash tables. 00051 */ 00052 typedef struct apr_hash_t apr_hash_t; 00053 00054 /** 00055 * Abstract type for scanning hash tables. 00056 */ 00057 typedef struct apr_hash_index_t apr_hash_index_t; 00058 00059 /** 00060 * Callback functions for calculating hash values. 00061 * @param key The key. 00062 * @param klen The length of the key, or APR_HASH_KEY_STRING to use the string 00063 * length. If APR_HASH_KEY_STRING then returns the actual key length. 00064 */ 00065 typedef unsigned int (*apr_hashfunc_t)(const char *key, apr_ssize_t *klen); 00066 00067 /** 00068 * The default hash function. 00069 */ 00070 APR_DECLARE_NONSTD(unsigned int) apr_hashfunc_default(const char *key, 00071 apr_ssize_t *klen); 00072 00073 /** 00074 * Create a hash table. 00075 * @param pool The pool to allocate the hash table out of 00076 * @return The hash table just created 00077 */ 00078 APR_DECLARE(apr_hash_t *) apr_hash_make(apr_pool_t *pool); 00079 00080 /** 00081 * Create a hash table with a custom hash function 00082 * @param pool The pool to allocate the hash table out of 00083 * @param hash_func A custom hash function. 00084 * @return The hash table just created 00085 */ 00086 APR_DECLARE(apr_hash_t *) apr_hash_make_custom(apr_pool_t *pool, 00087 apr_hashfunc_t hash_func); 00088 00089 /** 00090 * Make a copy of a hash table 00091 * @param pool The pool from which to allocate the new hash table 00092 * @param h The hash table to clone 00093 * @return The hash table just created 00094 * @remark Makes a shallow copy 00095 */ 00096 APR_DECLARE(apr_hash_t *) apr_hash_copy(apr_pool_t *pool, 00097 const apr_hash_t *h); 00098 00099 /** 00100 * Associate a value with a key in a hash table. 00101 * @param ht The hash table 00102 * @param key Pointer to the key 00103 * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length. 00104 * @param val Value to associate with the key 00105 * @remark If the value is NULL the hash entry is deleted. The key is stored as is, 00106 * and so must have a lifetime at least as long as the hash table's pool. 00107 */ 00108 APR_DECLARE(void) apr_hash_set(apr_hash_t *ht, const void *key, 00109 apr_ssize_t klen, const void *val); 00110 00111 /** 00112 * Look up the value associated with a key in a hash table. 00113 * @param ht The hash table 00114 * @param key Pointer to the key 00115 * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length. 00116 * @return Returns NULL if the key is not present. 00117 */ 00118 APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key, 00119 apr_ssize_t klen); 00120 00121 /** 00122 * Start iterating over the entries in a hash table. 00123 * @param p The pool to allocate the apr_hash_index_t iterator. If this 00124 * pool is NULL, then an internal, non-thread-safe iterator is used. 00125 * @param ht The hash table 00126 * @return The iteration state 00127 * @remark There is no restriction on adding or deleting hash entries during 00128 * an iteration (although the results may be unpredictable unless all you do 00129 * is delete the current entry) and multiple iterations can be in 00130 * progress at the same time. 00131 * 00132 * @par Example: 00133 * 00134 * @code 00135 * int sum_values(apr_pool_t *p, apr_hash_t *ht) 00136 * { 00137 * apr_hash_index_t *hi; 00138 * void *val; 00139 * int sum = 0; 00140 * for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) { 00141 * apr_hash_this(hi, NULL, NULL, &val); 00142 * sum += *(int *)val; 00143 * } 00144 * return sum; 00145 * } 00146 * @endcode 00147 */ 00148 APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht); 00149 00150 /** 00151 * Continue iterating over the entries in a hash table. 00152 * @param hi The iteration state 00153 * @return a pointer to the updated iteration state. NULL if there are no more 00154 * entries. 00155 */ 00156 APR_DECLARE(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi); 00157 00158 /** 00159 * Get the current entry's details from the iteration state. 00160 * @param hi The iteration state 00161 * @param key Return pointer for the pointer to the key. 00162 * @param klen Return pointer for the key length. 00163 * @param val Return pointer for the associated value. 00164 * @remark The return pointers should point to a variable that will be set to the 00165 * corresponding data, or they may be NULL if the data isn't interesting. 00166 */ 00167 APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key, 00168 apr_ssize_t *klen, void **val); 00169 00170 /** 00171 * Get the current entry's key from the iteration state. 00172 * @param hi The iteration state 00173 * @return The pointer to the key 00174 */ 00175 APR_DECLARE(const void*) apr_hash_this_key(apr_hash_index_t *hi); 00176 00177 /** 00178 * Get the current entry's key length from the iteration state. 00179 * @param hi The iteration state 00180 * @return The key length 00181 */ 00182 APR_DECLARE(apr_ssize_t) apr_hash_this_key_len(apr_hash_index_t *hi); 00183 00184 /** 00185 * Get the current entry's value from the iteration state. 00186 * @param hi The iteration state 00187 * @return The pointer to the value 00188 */ 00189 APR_DECLARE(void*) apr_hash_this_val(apr_hash_index_t *hi); 00190 00191 /** 00192 * Get the number of key/value pairs in the hash table. 00193 * @param ht The hash table 00194 * @return The number of key/value pairs in the hash table. 00195 */ 00196 APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht); 00197 00198 /** 00199 * Clear any key/value pairs in the hash table. 00200 * @param ht The hash table 00201 */ 00202 APR_DECLARE(void) apr_hash_clear(apr_hash_t *ht); 00203 00204 /** 00205 * Merge two hash tables into one new hash table. The values of the overlay 00206 * hash override the values of the base if both have the same key. Both 00207 * hash tables must use the same hash function. 00208 * @param p The pool to use for the new hash table 00209 * @param overlay The table to add to the initial table 00210 * @param base The table that represents the initial values of the new table 00211 * @return A new hash table containing all of the data from the two passed in 00212 */ 00213 APR_DECLARE(apr_hash_t *) apr_hash_overlay(apr_pool_t *p, 00214 const apr_hash_t *overlay, 00215 const apr_hash_t *base); 00216 00217 /** 00218 * Merge two hash tables into one new hash table. If the same key 00219 * is present in both tables, call the supplied merge function to 00220 * produce a merged value for the key in the new table. Both 00221 * hash tables must use the same hash function. 00222 * @param p The pool to use for the new hash table 00223 * @param h1 The first of the tables to merge 00224 * @param h2 The second of the tables to merge 00225 * @param merger A callback function to merge values, or NULL to 00226 * make values from h1 override values from h2 (same semantics as 00227 * apr_hash_overlay()) 00228 * @param data Client data to pass to the merger function 00229 * @return A new hash table containing all of the data from the two passed in 00230 */ 00231 APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p, 00232 const apr_hash_t *h1, 00233 const apr_hash_t *h2, 00234 void * (*merger)(apr_pool_t *p, 00235 const void *key, 00236 apr_ssize_t klen, 00237 const void *h1_val, 00238 const void *h2_val, 00239 const void *data), 00240 const void *data); 00241 00242 /** 00243 * Declaration prototype for the iterator callback function of apr_hash_do(). 00244 * 00245 * @param rec The data passed as the first argument to apr_hash_[v]do() 00246 * @param key The key from this iteration of the hash table 00247 * @param klen The key length from this iteration of the hash table 00248 * @param value The value from this iteration of the hash table 00249 * @remark Iteration continues while this callback function returns non-zero. 00250 * To export the callback function for apr_hash_do() it must be declared 00251 * in the _NONSTD convention. 00252 */ 00253 typedef int (apr_hash_do_callback_fn_t)(void *rec, const void *key, 00254 apr_ssize_t klen, 00255 const void *value); 00256 00257 /** 00258 * Iterate over a hash table running the provided function once for every 00259 * element in the hash table. The @param comp function will be invoked for 00260 * every element in the hash table. 00261 * 00262 * @param comp The function to run 00263 * @param rec The data to pass as the first argument to the function 00264 * @param ht The hash table to iterate over 00265 * @return FALSE if one of the comp() iterations returned zero; TRUE if all 00266 * iterations returned non-zero 00267 * @see apr_hash_do_callback_fn_t 00268 */ 00269 APR_DECLARE(int) apr_hash_do(apr_hash_do_callback_fn_t *comp, 00270 void *rec, const apr_hash_t *ht); 00271 00272 /** 00273 * Get a pointer to the pool which the hash table was created in 00274 */ 00275 APR_POOL_DECLARE_ACCESSOR(hash); 00276 00277 /** @} */ 00278 00279 #ifdef __cplusplus 00280 } 00281 #endif 00282 00283 #endif /* !APR_HASH_H */