Apache Portable Runtime
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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.
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
275 
276 /** @} */
277 
278 #ifdef __cplusplus
279 }
280 #endif
281 
282 #endif /* !APR_HASH_H */