1 | /* Licensed to the Apache Software Foundation (ASF) under one or more |
2 | * contributor license agreements. See the NOTICE file distributed with |
3 | * this work for additional information regarding copyright ownership. |
4 | * The ASF licenses this file to You under the Apache License, Version 2.0 |
5 | * (the "License"); you may not use this file except in compliance with |
6 | * the License. You may obtain a copy of the License at |
7 | * |
8 | * http://www.apache.org/licenses/LICENSE-2.0 |
9 | * |
10 | * Unless required by applicable law or agreed to in writing, software |
11 | * distributed under the License is distributed on an "AS IS" BASIS, |
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
13 | * See the License for the specific language governing permissions and |
14 | * limitations under the License. |
15 | */ |
16 | |
17 | #ifndef APR_HASH_H |
18 | #define APR_HASH_H |
19 | |
20 | /** |
21 | * @file apr_hash.h |
22 | * @brief APR Hash Tables |
23 | */ |
24 | |
25 | #include "apr_pools.h" |
26 | |
27 | #ifdef __cplusplus |
28 | extern "C" { |
29 | #endif |
30 | |
31 | /** |
32 | * @defgroup apr_hash Hash Tables |
33 | * @ingroup APR |
34 | * @{ |
35 | */ |
36 | |
37 | /** |
38 | * When passing a key to apr_hash_set or apr_hash_get, this value can be |
39 | * passed to indicate a string-valued key, and have apr_hash compute the |
40 | * length automatically. |
41 | * |
42 | * @remark apr_hash will use strlen(key) for the length. The NUL terminator |
43 | * is not included in the hash value (why throw a constant in?). |
44 | * Since the hash table merely references the provided key (rather |
45 | * than copying it), apr_hash_this() will return the NUL-term'd key. |
46 | */ |
47 | #define APR_HASH_KEY_STRING (-1) |
48 | |
49 | /** |
50 | * Abstract type for hash tables. |
51 | */ |
52 | typedef struct apr_hash_t apr_hash_t; |
53 | |
54 | /** |
55 | * Abstract type for scanning hash tables. |
56 | */ |
57 | typedef struct apr_hash_index_t apr_hash_index_t; |
58 | |
59 | /** |
60 | * Callback functions for calculating hash values. |
61 | * @param key The key. |
62 | * @param klen The length of the key, or APR_HASH_KEY_STRING to use the string |
63 | * length. If APR_HASH_KEY_STRING then returns the actual key length. |
64 | */ |
65 | typedef unsigned int (*apr_hashfunc_t)(const char *key, apr_ssize_t *klen); |
66 | |
67 | /** |
68 | * The default hash function. |
69 | */ |
70 | APR_DECLARE_NONSTD(unsigned int) apr_hashfunc_default(const char *key, |
71 | apr_ssize_t *klen); |
72 | |
73 | /** |
74 | * Create a hash table. |
75 | * @param pool The pool to allocate the hash table out of |
76 | * @return The hash table just created |
77 | */ |
78 | APR_DECLARE(apr_hash_t *) apr_hash_make(apr_pool_t *pool); |
79 | |
80 | /** |
81 | * Create a hash table with a custom hash function |
82 | * @param pool The pool to allocate the hash table out of |
83 | * @param hash_func A custom hash function. |
84 | * @return The hash table just created |
85 | */ |
86 | APR_DECLARE(apr_hash_t *) apr_hash_make_custom(apr_pool_t *pool, |
87 | apr_hashfunc_t hash_func); |
88 | |
89 | /** |
90 | * Make a copy of a hash table |
91 | * @param pool The pool from which to allocate the new hash table |
92 | * @param h The hash table to clone |
93 | * @return The hash table just created |
94 | * @remark Makes a shallow copy |
95 | */ |
96 | APR_DECLARE(apr_hash_t *) apr_hash_copy(apr_pool_t *pool, |
97 | const apr_hash_t *h); |
98 | |
99 | /** |
100 | * Associate a value with a key in a hash table. |
101 | * @param ht The hash table |
102 | * @param key Pointer to the key |
103 | * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length. |
104 | * @param val Value to associate with the key |
105 | * @remark If the value is NULL the hash entry is deleted. |
106 | */ |
107 | APR_DECLARE(void) apr_hash_set(apr_hash_t *ht, const void *key, |
108 | apr_ssize_t klen, const void *val); |
109 | |
110 | /** |
111 | * Look up the value associated with a key in a hash table. |
112 | * @param ht The hash table |
113 | * @param key Pointer to the key |
114 | * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length. |
115 | * @return Returns NULL if the key is not present. |
116 | */ |
117 | APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key, |
118 | apr_ssize_t klen); |
119 | |
120 | /** |
121 | * Start iterating over the entries in a hash table. |
122 | * @param p The pool to allocate the apr_hash_index_t iterator. If this |
123 | * pool is NULL, then an internal, non-thread-safe iterator is used. |
124 | * @param ht The hash table |
125 | * @return The iteration state |
126 | * @remark There is no restriction on adding or deleting hash entries during |
127 | * an iteration (although the results may be unpredictable unless all you do |
128 | * is delete the current entry) and multiple iterations can be in |
129 | * progress at the same time. |
130 | * |
131 | * @par Example: |
132 | * |
133 | * @code |
134 | * int sum_values(apr_pool_t *p, apr_hash_t *ht) |
135 | * { |
136 | * apr_hash_index_t *hi; |
137 | * void *val; |
138 | * int sum = 0; |
139 | * for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) { |
140 | * apr_hash_this(hi, NULL, NULL, &val); |
141 | * sum += *(int *)val; |
142 | * } |
143 | * return sum; |
144 | * } |
145 | * @endcode |
146 | */ |
147 | APR_DECLARE(apr_hash_index_t *) apr_hash_first(apr_pool_t *p, apr_hash_t *ht); |
148 | |
149 | /** |
150 | * Continue iterating over the entries in a hash table. |
151 | * @param hi The iteration state |
152 | * @return a pointer to the updated iteration state. NULL if there are no more |
153 | * entries. |
154 | */ |
155 | APR_DECLARE(apr_hash_index_t *) apr_hash_next(apr_hash_index_t *hi); |
156 | |
157 | /** |
158 | * Get the current entry's details from the iteration state. |
159 | * @param hi The iteration state |
160 | * @param key Return pointer for the pointer to the key. |
161 | * @param klen Return pointer for the key length. |
162 | * @param val Return pointer for the associated value. |
163 | * @remark The return pointers should point to a variable that will be set to the |
164 | * corresponding data, or they may be NULL if the data isn't interesting. |
165 | */ |
166 | APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key, |
167 | apr_ssize_t *klen, void **val); |
168 | |
169 | /** |
170 | * Get the current entry's key from the iteration state. |
171 | * @param hi The iteration state |
172 | * @return The pointer to the key |
173 | */ |
174 | APR_DECLARE(const void*) apr_hash_this_key(apr_hash_index_t *hi); |
175 | |
176 | /** |
177 | * Get the current entry's key length from the iteration state. |
178 | * @param hi The iteration state |
179 | * @return The key length |
180 | */ |
181 | APR_DECLARE(apr_ssize_t) apr_hash_this_key_len(apr_hash_index_t *hi); |
182 | |
183 | /** |
184 | * Get the current entry's value from the iteration state. |
185 | * @param hi The iteration state |
186 | * @return The pointer to the value |
187 | */ |
188 | APR_DECLARE(void*) apr_hash_this_val(apr_hash_index_t *hi); |
189 | |
190 | /** |
191 | * Get the number of key/value pairs in the hash table. |
192 | * @param ht The hash table |
193 | * @return The number of key/value pairs in the hash table. |
194 | */ |
195 | APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht); |
196 | |
197 | /** |
198 | * Clear any key/value pairs in the hash table. |
199 | * @param ht The hash table |
200 | */ |
201 | APR_DECLARE(void) apr_hash_clear(apr_hash_t *ht); |
202 | |
203 | /** |
204 | * Merge two hash tables into one new hash table. The values of the overlay |
205 | * hash override the values of the base if both have the same key. Both |
206 | * hash tables must use the same hash function. |
207 | * @param p The pool to use for the new hash table |
208 | * @param overlay The table to add to the initial table |
209 | * @param base The table that represents the initial values of the new table |
210 | * @return A new hash table containing all of the data from the two passed in |
211 | */ |
212 | APR_DECLARE(apr_hash_t *) apr_hash_overlay(apr_pool_t *p, |
213 | const apr_hash_t *overlay, |
214 | const apr_hash_t *base); |
215 | |
216 | /** |
217 | * Merge two hash tables into one new hash table. If the same key |
218 | * is present in both tables, call the supplied merge function to |
219 | * produce a merged value for the key in the new table. Both |
220 | * hash tables must use the same hash function. |
221 | * @param p The pool to use for the new hash table |
222 | * @param h1 The first of the tables to merge |
223 | * @param h2 The second of the tables to merge |
224 | * @param merger A callback function to merge values, or NULL to |
225 | * make values from h1 override values from h2 (same semantics as |
226 | * apr_hash_overlay()) |
227 | * @param data Client data to pass to the merger function |
228 | * @return A new hash table containing all of the data from the two passed in |
229 | */ |
230 | APR_DECLARE(apr_hash_t *) apr_hash_merge(apr_pool_t *p, |
231 | const apr_hash_t *h1, |
232 | const apr_hash_t *h2, |
233 | void * (*merger)(apr_pool_t *p, |
234 | const void *key, |
235 | apr_ssize_t klen, |
236 | const void *h1_val, |
237 | const void *h2_val, |
238 | const void *data), |
239 | const void *data); |
240 | |
241 | /** |
242 | * Declaration prototype for the iterator callback function of apr_hash_do(). |
243 | * |
244 | * @param rec The data passed as the first argument to apr_hash_[v]do() |
245 | * @param key The key from this iteration of the hash table |
246 | * @param klen The key length from this iteration of the hash table |
247 | * @param value The value from this iteration of the hash table |
248 | * @remark Iteration continues while this callback function returns non-zero. |
249 | * To export the callback function for apr_hash_do() it must be declared |
250 | * in the _NONSTD convention. |
251 | */ |
252 | typedef int (apr_hash_do_callback_fn_t)(void *rec, const void *key, |
253 | apr_ssize_t klen, |
254 | const void *value); |
255 | |
256 | /** |
257 | * Iterate over a hash table running the provided function once for every |
258 | * element in the hash table. The @param comp function will be invoked for |
259 | * every element in the hash table. |
260 | * |
261 | * @param comp The function to run |
262 | * @param rec The data to pass as the first argument to the function |
263 | * @param ht The hash table to iterate over |
264 | * @return FALSE if one of the comp() iterations returned zero; TRUE if all |
265 | * iterations returned non-zero |
266 | * @see apr_hash_do_callback_fn_t |
267 | */ |
268 | APR_DECLARE(int) apr_hash_do(apr_hash_do_callback_fn_t *comp, |
269 | void *rec, const apr_hash_t *ht); |
270 | |
271 | /** |
272 | * Get a pointer to the pool which the hash table was created in |
273 | */ |
274 | APR_POOL_DECLARE_ACCESSOR(hash); |
275 | |
276 | /** @} */ |
277 | |
278 | #ifdef __cplusplus |
279 | } |
280 | #endif |
281 | |
282 | #endif /* !APR_HASH_H */ |
283 | |