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