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  * Look up the value associated with a key in a hash table, or if none exists
123  * associate a value.
124  * @param ht The hash table
125  * @param key Pointer to the key
126  * @param klen Length of the key. Can be APR_HASH_KEY_STRING to use the string
127  * length.
128  * @param val Value to associate with the key (if none exists).
129  * @return Returns the existing value if any, the given value otherwise.
130  * @remark If the given value is NULL and a hash entry exists, nothing is done.
131  */
132 APR_DECLARE(void *) apr_hash_get_or_set(apr_hash_t *ht, const void *key,
133  apr_ssize_t klen, const void *val);
134 
135 /**
136  * Start iterating over the entries in a hash table.
137  * @param p The pool to allocate the apr_hash_index_t iterator. If this
138  * pool is NULL, then an internal, non-thread-safe iterator is used.
139  * @param ht The hash table
140  * @return The iteration state
141  * @remark There is no restriction on adding or deleting hash entries during
142  * an iteration (although the results may be unpredictable unless all you do
143  * is delete the current entry) and multiple iterations can be in
144  * progress at the same time.
145  *
146  * @par Example:
147  *
148  * @code
149  * int sum_values(apr_pool_t *p, apr_hash_t *ht)
150  * {
151  * apr_hash_index_t *hi;
152  * void *val;
153  * int sum = 0;
154  * for (hi = apr_hash_first(p, ht); hi; hi = apr_hash_next(hi)) {
155  * apr_hash_this(hi, NULL, NULL, &val);
156  * sum += *(int *)val;
157  * }
158  * return sum;
159  * }
160  * @endcode
161  */
163 
164 /**
165  * Continue iterating over the entries in a hash table.
166  * @param hi The iteration state
167  * @return a pointer to the updated iteration state. NULL if there are no more
168  * entries.
169  */
171 
172 /**
173  * Get the current entry's details from the iteration state.
174  * @param hi The iteration state
175  * @param key Return pointer for the pointer to the key.
176  * @param klen Return pointer for the key length.
177  * @param val Return pointer for the associated value.
178  * @remark The return pointers should point to a variable that will be set to the
179  * corresponding data, or they may be NULL if the data isn't interesting.
180  */
181 APR_DECLARE(void) apr_hash_this(apr_hash_index_t *hi, const void **key,
182  apr_ssize_t *klen, void **val);
183 
184 /**
185  * Get the current entry's key from the iteration state.
186  * @param hi The iteration state
187  * @return The pointer to the key
188  */
190 
191 /**
192  * Get the current entry's key length from the iteration state.
193  * @param hi The iteration state
194  * @return The key length
195  */
197 
198 /**
199  * Get the current entry's value from the iteration state.
200  * @param hi The iteration state
201  * @return The pointer to the value
202  */
204 
205 /**
206  * Get the number of key/value pairs in the hash table.
207  * @param ht The hash table
208  * @return The number of key/value pairs in the hash table.
209  */
210 APR_DECLARE(unsigned int) apr_hash_count(apr_hash_t *ht);
211 
212 /**
213  * Clear any key/value pairs in the hash table.
214  * @param ht The hash table
215  */
217 
218 /**
219  * Merge two hash tables into one new hash table. The values of the overlay
220  * hash override the values of the base if both have the same key. Both
221  * hash tables must use the same hash function.
222  * @param p The pool to use for the new hash table
223  * @param overlay The table to add to the initial table
224  * @param base The table that represents the initial values of the new table
225  * @return A new hash table containing all of the data from the two passed in
226  */
228  const apr_hash_t *overlay,
229  const apr_hash_t *base);
230 
231 /**
232  * Merge two hash tables into one new hash table. If the same key
233  * is present in both tables, call the supplied merge function to
234  * produce a merged value for the key in the new table. Both
235  * hash tables must use the same hash function.
236  * @param p The pool to use for the new hash table
237  * @param h1 The first of the tables to merge
238  * @param h2 The second of the tables to merge
239  * @param merger A callback function to merge values, or NULL to
240  * make values from h1 override values from h2 (same semantics as
241  * apr_hash_overlay())
242  * @param data Client data to pass to the merger function
243  * @return A new hash table containing all of the data from the two passed in
244  */
246  const apr_hash_t *h1,
247  const apr_hash_t *h2,
248  void * (*merger)(apr_pool_t *p,
249  const void *key,
250  apr_ssize_t klen,
251  const void *h1_val,
252  const void *h2_val,
253  const void *data),
254  const void *data);
255 
256 /**
257  * Declaration prototype for the iterator callback function of apr_hash_do().
258  *
259  * @param rec The data passed as the first argument to apr_hash_[v]do()
260  * @param key The key from this iteration of the hash table
261  * @param klen The key length from this iteration of the hash table
262  * @param value The value from this iteration of the hash table
263  * @remark Iteration continues while this callback function returns non-zero.
264  * To export the callback function for apr_hash_do() it must be declared
265  * in the _NONSTD convention.
266  */
267 typedef int (apr_hash_do_callback_fn_t)(void *rec, const void *key,
268  apr_ssize_t klen,
269  const void *value);
270 
271 /**
272  * Iterate over a hash table running the provided function once for every
273  * element in the hash table. The @param comp function will be invoked for
274  * every element in the hash table.
275  *
276  * @param comp The function to run
277  * @param rec The data to pass as the first argument to the function
278  * @param ht The hash table to iterate over
279  * @return FALSE if one of the comp() iterations returned zero; TRUE if all
280  * iterations returned non-zero
281  * @see apr_hash_do_callback_fn_t
282  */
284  void *rec, const apr_hash_t *ht);
285 
286 /**
287  * Get a pointer to the pool which the hash table was created in
288  */
290 
291 /** @} */
292 
293 #ifdef __cplusplus
294 }
295 #endif
296 
297 #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:267
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:500
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:513
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
void * apr_hash_get_or_set(apr_hash_t *ht, const void *key, apr_ssize_t klen, const void *val)