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