Apache Portable Runtime
Main Page
Related Pages
Modules
Namespaces
Data Structures
Files
File List
Globals
All
Data Structures
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
usr
include
apr-1
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 by
1.8.4