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_tables.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_TABLES_H
18
#define APR_TABLES_H
19
20
/**
21
* @file apr_tables.h
22
* @brief APR Table library
23
*/
24
25
#include "
apr.h
"
26
#include "
apr_pools.h
"
27
28
#if APR_HAVE_STDARG_H
29
#include <stdarg.h>
/* for va_list */
30
#endif
31
32
#ifdef __cplusplus
33
extern
"C"
{
34
#endif
/* __cplusplus */
35
36
/**
37
* @defgroup apr_tables Table and Array Functions
38
* @ingroup APR
39
* Arrays are used to store data which is referenced sequentially or
40
* as a stack. Functions are provided to push and pop individual
41
* elements as well as to operate on the entire array.
42
*
43
* Tables are used to store data which can be referenced by key.
44
* Limited capabilities are provided for tables with multiple elements
45
* which share a key; while key lookup will return only a single
46
* element, iteration is available. Additionally, a table can be
47
* compressed to resolve duplicates.
48
*
49
* Both arrays and tables may store string or binary data; some features,
50
* such as concatenation or merging of elements, work only for string
51
* data.
52
* @{
53
*/
54
55
/** the table abstract data type */
56
typedef
struct
apr_table_t
apr_table_t
;
57
58
/** @see apr_array_header_t */
59
typedef
struct
apr_array_header_t
apr_array_header_t
;
60
61
/** An opaque array type */
62
struct
apr_array_header_t
{
63
/** The pool the array is allocated out of */
64
apr_pool_t
*
pool
;
65
/** The amount of memory allocated for each element of the array */
66
int
elt_size
;
67
/** The number of active elements in the array */
68
int
nelts
;
69
/** The number of elements allocated in the array */
70
int
nalloc
;
71
/** The elements in the array */
72
char
*
elts
;
73
};
74
75
/**
76
* The (opaque) structure for string-content tables.
77
*/
78
typedef
struct
apr_table_entry_t
apr_table_entry_t
;
79
80
/** The type for each entry in a string-content table */
81
struct
apr_table_entry_t
{
82
/** The key for the current table entry */
83
char
*
key
;
/* maybe NULL in future;
84
* check when iterating thru table_elts
85
*/
86
/** The value for the current table entry */
87
char
*
val
;
88
89
/** A checksum for the key, for use by the apr_table internals */
90
apr_uint32_t
key_checksum
;
91
};
92
93
/**
94
* Get the elements from a table.
95
* @param t The table
96
* @return An array containing the contents of the table
97
*/
98
APR_DECLARE
(
const
apr_array_header_t
*)
apr_table_elts
(const
apr_table_t
*t);
99
100
/**
101
* Determine if the table is empty (either NULL or having no elements).
102
* @param t The table to check
103
* @return True if empty, False otherwise
104
*/
105
APR_DECLARE
(
int
)
apr_is_empty_table
(const
apr_table_t
*t);
106
107
/**
108
* Determine if the array is empty (either NULL or having no elements).
109
* @param a The array to check
110
* @return True if empty, False otherwise
111
*/
112
APR_DECLARE
(
int
)
apr_is_empty_array
(const
apr_array_header_t
*a);
113
114
/**
115
* Create an array.
116
* @param p The pool to allocate the memory out of
117
* @param nelts the number of elements in the initial array
118
* @param elt_size The size of each element in the array.
119
* @return The new array
120
*/
121
APR_DECLARE
(
apr_array_header_t
*)
apr_array_make
(
apr_pool_t
*p,
122
int
nelts,
int
elt_size);
123
124
/**
125
* Add a new element to an array (as a first-in, last-out stack).
126
* @param arr The array to add an element to.
127
* @return Location for the new element in the array.
128
* @remark If there are no free spots in the array, then this function will
129
* allocate new space for the new element.
130
*/
131
APR_DECLARE
(
void
*)
apr_array_push
(
apr_array_header_t
*arr);
132
133
/** A helper macro for accessing a member of an APR array.
134
*
135
* @param ary the array
136
* @param i the index into the array to return
137
* @param type the type of the objects stored in the array
138
*
139
* @return the item at index i
140
*/
141
#define APR_ARRAY_IDX(ary,i,type) (((type *)(ary)->elts)[i])
142
143
/** A helper macro for pushing elements into an APR array.
144
*
145
* @param ary the array
146
* @param type the type of the objects stored in the array
147
*
148
* @return the location where the new object should be placed
149
*/
150
#define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary)))
151
152
/**
153
* Remove an element from an array (as a first-in, last-out stack).
154
* @param arr The array to remove an element from.
155
* @return Location of the element in the array.
156
* @remark If there are no elements in the array, NULL is returned.
157
*/
158
APR_DECLARE
(
void
*)
apr_array_pop
(
apr_array_header_t
*arr);
159
160
/**
161
* Remove all elements from an array.
162
* @param arr The array to remove all elements from.
163
* @remark As the underlying storage is allocated from a pool, no
164
* memory is freed by this operation, but is available for reuse.
165
*/
166
APR_DECLARE
(
void
)
apr_array_clear
(
apr_array_header_t
*arr);
167
168
/**
169
* Concatenate two arrays together.
170
* @param dst The destination array, and the one to go first in the combined
171
* array
172
* @param src The source array to add to the destination array
173
*/
174
APR_DECLARE
(
void
)
apr_array_cat
(
apr_array_header_t
*dst,
175
const
apr_array_header_t
*src);
176
177
/**
178
* Copy the entire array.
179
* @param p The pool to allocate the copy of the array out of
180
* @param arr The array to copy
181
* @return An exact copy of the array passed in
182
* @remark The alternate apr_array_copy_hdr copies only the header, and arranges
183
* for the elements to be copied if (and only if) the code subsequently
184
* does a push or arraycat.
185
*/
186
APR_DECLARE
(
apr_array_header_t
*)
apr_array_copy
(
apr_pool_t
*p,
187
const
apr_array_header_t
*arr);
188
/**
189
* Copy the headers of the array, and arrange for the elements to be copied if
190
* and only if the code subsequently does a push or arraycat.
191
* @param p The pool to allocate the copy of the array out of
192
* @param arr The array to copy
193
* @return An exact copy of the array passed in
194
* @remark The alternate apr_array_copy copies the *entire* array.
195
*/
196
APR_DECLARE
(
apr_array_header_t
*)
apr_array_copy_hdr
(
apr_pool_t
*p,
197
const
apr_array_header_t
*arr);
198
199
/**
200
* Append one array to the end of another, creating a new array in the process.
201
* @param p The pool to allocate the new array out of
202
* @param first The array to put first in the new array.
203
* @param second The array to put second in the new array.
204
* @return A new array containing the data from the two arrays passed in.
205
*/
206
APR_DECLARE
(
apr_array_header_t
*)
apr_array_append
(
apr_pool_t
*p,
207
const
apr_array_header_t
*first,
208
const
apr_array_header_t
*second);
209
210
/**
211
* Generate a new string from the apr_pool_t containing the concatenated
212
* sequence of substrings referenced as elements within the array. The string
213
* will be empty if all substrings are empty or null, or if there are no
214
* elements in the array. If sep is non-NUL, it will be inserted between
215
* elements as a separator.
216
* @param p The pool to allocate the string out of
217
* @param arr The array to generate the string from
218
* @param sep The separator to use
219
* @return A string containing all of the data in the array.
220
*/
221
APR_DECLARE
(
char
*)
apr_array_pstrcat
(
apr_pool_t
*p,
222
const
apr_array_header_t
*arr,
223
const
char
sep);
224
225
/**
226
* Make a new table.
227
* @param p The pool to allocate the pool out of
228
* @param nelts The number of elements in the initial table.
229
* @return The new table.
230
* @warning This table can only store text data
231
*/
232
APR_DECLARE
(
apr_table_t
*)
apr_table_make
(
apr_pool_t
*p,
int
nelts);
233
234
/**
235
* Create a new table and copy another table into it.
236
* @param p The pool to allocate the new table out of
237
* @param t The table to copy
238
* @return A copy of the table passed in
239
* @warning The table keys and respective values are not copied
240
*/
241
APR_DECLARE
(
apr_table_t
*)
apr_table_copy
(
apr_pool_t
*p,
242
const
apr_table_t
*t);
243
244
/**
245
* Create a new table whose contents are deep copied from the given
246
* table. A deep copy operation copies all fields, and makes copies
247
* of dynamically allocated memory pointed to by the fields.
248
* @param p The pool to allocate the new table out of
249
* @param t The table to clone
250
* @return A deep copy of the table passed in
251
*/
252
APR_DECLARE
(
apr_table_t
*)
apr_table_clone
(
apr_pool_t
*p,
253
const
apr_table_t
*t);
254
255
/**
256
* Delete all of the elements from a table.
257
* @param t The table to clear
258
*/
259
APR_DECLARE
(
void
)
apr_table_clear
(
apr_table_t
*t);
260
261
/**
262
* Get the value associated with a given key from the table. After this call,
263
* the data is still in the table.
264
* @param t The table to search for the key
265
* @param key The key to search for (case does not matter)
266
* @return The value associated with the key, or NULL if the key does not exist.
267
*/
268
APR_DECLARE
(const
char
*)
apr_table_get
(const
apr_table_t
*t, const
char
*key);
269
270
/**
271
* Add a key/value pair to a table. If another element already exists with the
272
* same key, this will overwrite the old data.
273
* @param t The table to add the data to.
274
* @param key The key to use (case does not matter)
275
* @param val The value to add
276
* @remark When adding data, this function makes a copy of both the key and the
277
* value.
278
*/
279
APR_DECLARE
(
void
)
apr_table_set
(
apr_table_t
*t, const
char
*key,
280
const
char
*val);
281
282
/**
283
* Add a key/value pair to a table. If another element already exists with the
284
* same key, this will overwrite the old data.
285
* @param t The table to add the data to.
286
* @param key The key to use (case does not matter)
287
* @param val The value to add
288
* @warning When adding data, this function does not make a copy of the key or
289
* the value, so care should be taken to ensure that the values will
290
* not change after they have been added..
291
*/
292
APR_DECLARE
(
void
)
apr_table_setn
(
apr_table_t
*t, const
char
*key,
293
const
char
*val);
294
295
/**
296
* Remove data from the table.
297
* @param t The table to remove data from
298
* @param key The key of the data being removed (case does not matter)
299
*/
300
APR_DECLARE
(
void
)
apr_table_unset
(
apr_table_t
*t, const
char
*key);
301
302
/**
303
* Add data to a table by merging the value with data that has already been
304
* stored. The merging is done by concatenating the two values, separated
305
* by the string ", ".
306
* @param t The table to search for the data
307
* @param key The key to merge data for (case does not matter)
308
* @param val The data to add
309
* @remark If the key is not found, then this function acts like apr_table_add
310
*/
311
APR_DECLARE
(
void
)
apr_table_merge
(
apr_table_t
*t, const
char
*key,
312
const
char
*val);
313
314
/**
315
* Add data to a table by merging the value with data that has already been
316
* stored. The merging is done by concatenating the two values, separated
317
* by the string ", ".
318
* @param t The table to search for the data
319
* @param key The key to merge data for (case does not matter)
320
* @param val The data to add
321
* @remark If the key is not found, then this function acts like apr_table_addn
322
*/
323
APR_DECLARE
(
void
)
apr_table_mergen
(
apr_table_t
*t, const
char
*key,
324
const
char
*val);
325
326
/**
327
* Add data to a table, regardless of whether there is another element with the
328
* same key.
329
* @param t The table to add to
330
* @param key The key to use
331
* @param val The value to add.
332
* @remark When adding data, this function makes a copy of both the key and the
333
* value.
334
*/
335
APR_DECLARE
(
void
)
apr_table_add
(
apr_table_t
*t, const
char
*key,
336
const
char
*val);
337
338
/**
339
* Add data to a table, regardless of whether there is another element with the
340
* same key.
341
* @param t The table to add to
342
* @param key The key to use
343
* @param val The value to add.
344
* @remark When adding data, this function does not make a copy of the key or the
345
* value, so care should be taken to ensure that the values will not
346
* change after they have been added.
347
*/
348
APR_DECLARE
(
void
)
apr_table_addn
(
apr_table_t
*t, const
char
*key,
349
const
char
*val);
350
351
/**
352
* Merge two tables into one new table.
353
* @param p The pool to use for the new table
354
* @param overlay The first table to put in the new table
355
* @param base The table to add at the end of the new table
356
* @return A new table containing all of the data from the two passed in
357
*/
358
APR_DECLARE
(
apr_table_t
*)
apr_table_overlay
(
apr_pool_t
*p,
359
const
apr_table_t
*overlay,
360
const
apr_table_t
*base);
361
362
/**
363
* Declaration prototype for the iterator callback function of apr_table_do()
364
* and apr_table_vdo().
365
* @param rec The data passed as the first argument to apr_table_[v]do()
366
* @param key The key from this iteration of the table
367
* @param value The value from this iteration of the table
368
* @remark Iteration continues while this callback function returns non-zero.
369
* To export the callback function for apr_table_[v]do() it must be declared
370
* in the _NONSTD convention.
371
*/
372
typedef
int
(
apr_table_do_callback_fn_t
)(
void
*rec, const
char
*key,
373
const
char
*value);
374
375
/**
376
* Iterate over a table running the provided function once for every
377
* element in the table. The varargs array must be a list of zero or
378
* more (char *) keys followed by a NULL pointer. If zero keys are
379
* given, the @param comp function will be invoked for every element
380
* in the table. Otherwise, the function is invoked only for those
381
* elements matching the keys specified.
382
*
383
* If an invocation of the @param comp function returns zero,
384
* iteration will continue using the next specified key, if any.
385
*
386
* @param comp The function to run
387
* @param rec The data to pass as the first argument to the function
388
* @param t The table to iterate over
389
* @param ... A varargs array of zero or more (char *) keys followed by NULL
390
* @return FALSE if one of the comp() iterations returned zero; TRUE if all
391
* iterations returned non-zero
392
* @see apr_table_do_callback_fn_t
393
*/
394
APR_DECLARE_NONSTD
(
int
)
apr_table_do
(
apr_table_do_callback_fn_t
*comp,
395
void
*rec, const
apr_table_t
*t, ...)
396
#if defined(__GNUC__) && __GNUC__ >= 4
397
__attribute__((sentinel))
398
#endif
399
;
400
401
/**
402
* Iterate over a table running the provided function once for every
403
* element in the table. The @param vp varargs parameter must be a
404
* list of zero or more (char *) keys followed by a NULL pointer. If
405
* zero keys are given, the @param comp function will be invoked for
406
* every element in the table. Otherwise, the function is invoked
407
* only for those elements matching the keys specified.
408
*
409
* If an invocation of the @param comp function returns zero,
410
* iteration will continue using the next specified key, if any.
411
*
412
* @param comp The function to run
413
* @param rec The data to pass as the first argument to the function
414
* @param t The table to iterate over
415
* @param vp List of zero or more (char *) keys followed by NULL
416
* @return FALSE if one of the comp() iterations returned zero; TRUE if all
417
* iterations returned non-zero
418
* @see apr_table_do_callback_fn_t
419
*/
420
APR_DECLARE
(
int
)
apr_table_vdo
(
apr_table_do_callback_fn_t
*comp,
421
void
*rec, const
apr_table_t
*t, va_list vp);
422
423
/** flag for overlap to use apr_table_setn */
424
#define APR_OVERLAP_TABLES_SET (0)
425
/** flag for overlap to use apr_table_mergen */
426
#define APR_OVERLAP_TABLES_MERGE (1)
427
/**
428
* For each element in table b, either use setn or mergen to add the data
429
* to table a. Which method is used is determined by the flags passed in.
430
* @param a The table to add the data to.
431
* @param b The table to iterate over, adding its data to table a
432
* @param flags How to add the table to table a. One of:
433
* APR_OVERLAP_TABLES_SET Use apr_table_setn
434
* APR_OVERLAP_TABLES_MERGE Use apr_table_mergen
435
* @remark When merging duplicates, the two values are concatenated,
436
* separated by the string ", ".
437
* @remark This function is highly optimized, and uses less memory and CPU cycles
438
* than a function that just loops through table b calling other functions.
439
*/
440
/**
441
* Conceptually, apr_table_overlap does this:
442
*
443
* <pre>
444
* apr_array_header_t *barr = apr_table_elts(b);
445
* apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
446
* int i;
447
*
448
* for (i = 0; i < barr->nelts; ++i) {
449
* if (flags & APR_OVERLAP_TABLES_MERGE) {
450
* apr_table_mergen(a, belt[i].key, belt[i].val);
451
* }
452
* else {
453
* apr_table_setn(a, belt[i].key, belt[i].val);
454
* }
455
* }
456
* </pre>
457
*
458
* Except that it is more efficient (less space and cpu-time) especially
459
* when b has many elements.
460
*
461
* Notice the assumptions on the keys and values in b -- they must be
462
* in an ancestor of a's pool. In practice b and a are usually from
463
* the same pool.
464
*/
465
466
APR_DECLARE
(
void
)
apr_table_overlap
(
apr_table_t
*a, const
apr_table_t
*b,
467
unsigned
flags);
468
469
/**
470
* Eliminate redundant entries in a table by either overwriting
471
* or merging duplicates.
472
*
473
* @param t Table.
474
* @param flags APR_OVERLAP_TABLES_MERGE to merge, or
475
* APR_OVERLAP_TABLES_SET to overwrite
476
* @remark When merging duplicates, the two values are concatenated,
477
* separated by the string ", ".
478
*/
479
APR_DECLARE
(
void
)
apr_table_compress
(
apr_table_t
*t,
unsigned
flags);
480
481
/** @} */
482
483
#ifdef __cplusplus
484
}
485
#endif
486
487
#endif
/* ! APR_TABLES_H */
Generated on Sun Jul 7 2013 03:35:11 for Apache Portable Runtime by
1.8.1.2