Apache Portable Runtime
apr_hash.h
Go to the documentation of this file.
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  */
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  */
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  */
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  */
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. The key is stored as is,
106  * and so must have a lifetime at least as long as the hash table's pool.
107  */
108 APR_DECLARE(void) apr_hash_set(apr_hash_t *ht, const void *key,
109  apr_ssize_t klen, const void *val);
110 
111 /**
112  * Look up the value associated with a key in a hash table.
113  * @param ht The hash table
114  * @param key Pointer to the key
115  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string length.
116  * @return Returns NULL if the key is not present.
117  */
118 APR_DECLARE(void *) apr_hash_get(apr_hash_t *ht, const void *key,
119  apr_ssize_t klen);
120 
121 /**
122  * Start iterating over the entries in a hash table.
123  * @param p The pool to allocate the apr_hash_index_t iterator. If this
124  * pool is NULL, then an internal, non-thread-safe iterator is used.
125  * @param ht The hash table
126  * @return The iteration state
127  * @remark There is no restriction on adding or deleting hash entries during
128  * an iteration (although the results may be unpredictable unless all you do
129  * is delete the current entry) and multiple iterations can be in
130  * progress at the same time.
131  *
132  * @par Example:
133  *
134  * @code
135  * int sum_values(apr_pool_t *p, apr_hash_t *ht)
136  * {
137  * apr_hash_index_t *hi;
138  * void *val;
139  * int sum = 0;
140  * for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) {
141  * apr_hash_this(hi, NULL, NULL, &val);
142  * sum += *(int *)val;
143  * }
144  * return sum;
145  * }
146  * @endcode
147  */
149 
150 /**
151  * Continue iterating over the entries in a hash table.
152  * @param hi The iteration state
153  * @return a pointer to the updated iteration state. NULL if there are no more
154  * entries.
155  */
157 
158 /**
159  * Get the current entry's details from the iteration state.
160  * @param hi The iteration state
161  * @param key Return pointer for the pointer to the key.
162  * @param klen Return pointer for the key length.
163  * @param val Return pointer for the associated value.
164  * @remark The return pointers should point to a variable that will be set to the
165  * corresponding data, or they may be NULL if the data isn't interesting.
166  */
167 APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key,
168  apr_ssize_t *klen, void **val);
169 
170 /**
171  * Get the current entry's key from the iteration state.
172  * @param hi The iteration state
173  * @return The pointer to the key
174  */
176 
177 /**
178  * Get the current entry's key length from the iteration state.
179  * @param hi The iteration state
180  * @return The key length
181  */
183 
184 /**
185  * Get the current entry's value from the iteration state.
186  * @param hi The iteration state
187  * @return The pointer to the value
188  */
190 
191 /**
192  * Get the number of key/value pairs in the hash table.
193  * @param ht The hash table
194  * @return The number of key/value pairs in the hash table.
195  */
196 APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht);
197 
198 /**
199  * Clear any key/value pairs in the hash table.
200  * @param ht The hash table
201  */
203 
204 /**
205  * Merge two hash tables into one new hash table. The values of the overlay
206  * hash override the values of the base if both have the same key. Both
207  * hash tables must use the same hash function.
208  * @param p The pool to use for the new hash table
209  * @param overlay The table to add to the initial table
210  * @param base The table that represents the initial values of the new table
211  * @return A new hash table containing all of the data from the two passed in
212  */
214  const apr_hash_t *overlay,
215  const apr_hash_t *base);
216 
217 /**
218  * Merge two hash tables into one new hash table. If the same key
219  * is present in both tables, call the supplied merge function to
220  * produce a merged value for the key in the new table. Both
221  * hash tables must use the same hash function.
222  * @param p The pool to use for the new hash table
223  * @param h1 The first of the tables to merge
224  * @param h2 The second of the tables to merge
225  * @param merger A callback function to merge values, or NULL to
226  * make values from h1 override values from h2 (same semantics as
227  * apr_hash_overlay())
228  * @param data Client data to pass to the merger function
229  * @return A new hash table containing all of the data from the two passed in
230  */
232  const apr_hash_t *h1,
233  const apr_hash_t *h2,
234  void * (*merger)(apr_pool_t *p,
235  const void *key,
236  apr_ssize_t klen,
237  const void *h1_val,
238  const void *h2_val,
239  const void *data),
240  const void *data);
241 
242 /**
243  * Declaration prototype for the iterator callback function of apr_hash_do().
244  *
245  * @param rec The data passed as the first argument to apr_hash_[v]do()
246  * @param key The key from this iteration of the hash table
247  * @param klen The key length from this iteration of the hash table
248  * @param value The value from this iteration of the hash table
249  * @remark Iteration continues while this callback function returns non-zero.
250  * To export the callback function for apr_hash_do() it must be declared
251  * in the _NONSTD convention.
252  */
253 typedef int (apr_hash_do_callback_fn_t)(void *rec, const void *key,
254  apr_ssize_t klen,
255  const void *value);
256 
257 /**
258  * Iterate over a hash table running the provided function once for every
259  * element in the hash table. The @param comp function will be invoked for
260  * every element in the hash table.
261  *
262  * @param comp The function to run
263  * @param rec The data to pass as the first argument to the function
264  * @param ht The hash table to iterate over
265  * @return FALSE if one of the comp() iterations returned zero; TRUE if all
266  * iterations returned non-zero
267  * @see apr_hash_do_callback_fn_t
268  */
270  void *rec, const apr_hash_t *ht);
271 
272 /**
273  * Get a pointer to the pool which the hash table was created in
274  */
276 
277 /** @} */
278 
279 #ifdef __cplusplus
280 }
281 #endif
282 
283 #endif /* !APR_HASH_H */
apr_hash_index_t * apr_hash_first(apr_pool_t *p, apr_hash_t *ht)
void * apr_hash_get(apr_hash_t *ht, const void *key, apr_ssize_t klen)
apr_hash_t * apr_hash_merge(apr_pool_t *p, const apr_hash_t *h1, const apr_hash_t *h2, void *(*merger)(apr_pool_t *p, const void *key, apr_ssize_t klen, const void *h1_val, const void *h2_val, const void *data), const void *data)
void apr_hash_set(apr_hash_t *ht, const void *key, apr_ssize_t klen, const void *val)
struct apr_hash_index_t apr_hash_index_t
Definition: apr_hash.h:57
apr_hash_index_t * apr_hash_next(apr_hash_index_t *hi)
void apr_hash_this(apr_hash_index_t *hi, const void **key, apr_ssize_t *klen, void **val)
apr_hash_t * apr_hash_copy(apr_pool_t *pool, const apr_hash_t *h)
unsigned int(* apr_hashfunc_t)(const char *key, apr_ssize_t *klen)
Definition: apr_hash.h:65
int( apr_hash_do_callback_fn_t)(void *rec, const void *key, apr_ssize_t klen, const void *value)
Definition: apr_hash.h:253
void apr_hash_clear(apr_hash_t *ht)
const void * apr_hash_this_key(apr_hash_index_t *hi)
apr_hash_t * apr_hash_make_custom(apr_pool_t *pool, apr_hashfunc_t hash_func)
APR memory allocation.
#define APR_DECLARE(type)
Definition: apr.h:480
struct apr_hash_t apr_hash_t
Definition: apr_hash.h:52
unsigned int apr_hashfunc_default(const char *key, apr_ssize_t *klen)
void * apr_hash_this_val(apr_hash_index_t *hi)
int apr_hash_do(apr_hash_do_callback_fn_t *comp, void *rec, const apr_hash_t *ht)
#define APR_DECLARE_NONSTD(type)
Definition: apr.h:493
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
unsigned int apr_hash_count(apr_hash_t *ht)
apr_hash_t * apr_hash_make(apr_pool_t *pool)
apr_ssize_t apr_hash_this_key_len(apr_hash_index_t *hi)
apr_hash_t * apr_hash_overlay(apr_pool_t *p, const apr_hash_t *overlay, const apr_hash_t *base)
#define APR_POOL_DECLARE_ACCESSOR(type)
Definition: apr_pools.h:81