Apache Portable Runtime
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
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
*/
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 number of key/value pairs in the hash table.
171
* @param ht The hash table
172
* @return The number of key/value pairs in the hash table.
173
*/
174
APR_DECLARE
(
unsigned
int
)
apr_hash_count
(
apr_hash_t
*ht);
175
176
/**
177
* Clear any key/value pairs in the hash table.
178
* @param ht The hash table
179
*/
180
APR_DECLARE
(
void
)
apr_hash_clear
(
apr_hash_t
*ht);
181
182
/**
183
* Merge two hash tables into one new hash table. The values of the overlay
184
* hash override the values of the base if both have the same key. Both
185
* hash tables must use the same hash function.
186
* @param p The pool to use for the new hash table
187
* @param overlay The table to add to the initial table
188
* @param base The table that represents the initial values of the new table
189
* @return A new hash table containing all of the data from the two passed in
190
*/
191
APR_DECLARE
(
apr_hash_t
*)
apr_hash_overlay
(
apr_pool_t
*p,
192
const
apr_hash_t
*overlay,
193
const
apr_hash_t
*base);
194
195
/**
196
* Merge two hash tables into one new hash table. If the same key
197
* is present in both tables, call the supplied merge function to
198
* produce a merged value for the key in the new table. Both
199
* hash tables must use the same hash function.
200
* @param p The pool to use for the new hash table
201
* @param h1 The first of the tables to merge
202
* @param h2 The second of the tables to merge
203
* @param merger A callback function to merge values, or NULL to
204
* make values from h1 override values from h2 (same semantics as
205
* apr_hash_overlay())
206
* @param data Client data to pass to the merger function
207
* @return A new hash table containing all of the data from the two passed in
208
*/
209
APR_DECLARE
(
apr_hash_t
*)
apr_hash_merge
(
apr_pool_t
*p,
210
const
apr_hash_t
*h1,
211
const
apr_hash_t
*h2,
212
void
* (*merger)(
apr_pool_t
*p,
213
const
void
*key,
214
apr_ssize_t klen,
215
const
void
*h1_val,
216
const
void
*h2_val,
217
const
void
*data),
218
const
void
*data);
219
220
/**
221
* Declaration prototype for the iterator callback function of apr_hash_do().
222
*
223
* @param rec The data passed as the first argument to apr_hash_[v]do()
224
* @param key The key from this iteration of the hash table
225
* @param klen The key length from this iteration of the hash table
226
* @param value The value from this iteration of the hash table
227
* @remark Iteration continues while this callback function returns non-zero.
228
* To export the callback function for apr_hash_do() it must be declared
229
* in the _NONSTD convention.
230
*/
231
typedef
int
(
apr_hash_do_callback_fn_t
)(
void
*rec, const
void
*key,
232
apr_ssize_t klen,
233
const
void
*value);
234
235
/**
236
* Iterate over a hash table running the provided function once for every
237
* element in the hash table. The @param comp function will be invoked for
238
* every element in the hash table.
239
*
240
* @param comp The function to run
241
* @param rec The data to pass as the first argument to the function
242
* @param ht The hash table to iterate over
243
* @return FALSE if one of the comp() iterations returned zero; TRUE if all
244
* iterations returned non-zero
245
* @see apr_hash_do_callback_fn_t
246
*/
247
APR_DECLARE
(
int
)
apr_hash_do
(
apr_hash_do_callback_fn_t
*comp,
248
void
*rec, const
apr_hash_t
*ht);
249
250
/**
251
* Get a pointer to the pool which the hash table was created in
252
*/
253
APR_POOL_DECLARE_ACCESSOR
(hash);
254
255
/** @} */
256
257
#ifdef __cplusplus
258
}
259
#endif
260
261
#endif
/* !APR_HASH_H */
Generated on Sun Jul 7 2013 03:35:10 for Apache Portable Runtime by
1.8.1.2