1
/* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
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.
22
* @brief APR Table library
26
#include "apr_pools.h"
29
#include <stdarg.h> /* for va_list */
34
#endif /* __cplusplus */
37
* @defgroup apr_tables Table and Array Functions
39
* Tables are used to store entirely opaque structures
40
* for applications, while Arrays are usually used to
41
* deal with string lists.
45
/** the table abstract data type */
46
typedef struct apr_table_t apr_table_t;
48
/** @see apr_array_header_t */
49
typedef struct apr_array_header_t apr_array_header_t;
51
/** An opaque array type */
52
struct apr_array_header_t {
53
/** The pool the array is allocated out of */
55
/** The amount of memory allocated for each element of the array */
57
/** The number of active elements in the array */
59
/** The number of elements allocated in the array */
61
/** The elements in the array */
66
* The (opaque) structure for string-content tables.
68
typedef struct apr_table_entry_t apr_table_entry_t;
70
/** The type for each entry in a string-content table */
71
struct apr_table_entry_t {
72
/** The key for the current table entry */
73
char *key; /* maybe NULL in future;
74
* check when iterating thru table_elts
76
/** The value for the current table entry */
79
/** A checksum for the key, for use by the apr_table internals */
80
apr_uint32_t key_checksum;
84
* Get the elements from a table
86
* @return An array containing the contents of the table
88
APR_DECLARE(const apr_array_header_t *) apr_table_elts(const apr_table_t *t);
91
* Determine if the table is empty
92
* @param t The table to check
93
* @return True if empty, False otherwise
95
APR_DECLARE(int) apr_is_empty_table(const apr_table_t *t);
98
* Determine if the array is empty
99
* @param a The array to check
100
* @return True if empty, False otherwise
102
APR_DECLARE(int) apr_is_empty_array(const apr_array_header_t *a);
106
* @param p The pool to allocate the memory out of
107
* @param nelts the number of elements in the initial array
108
* @param elt_size The size of each element in the array.
109
* @return The new array
111
APR_DECLARE(apr_array_header_t *) apr_array_make(apr_pool_t *p,
112
int nelts, int elt_size);
115
* Add a new element to an array (as a first-in, last-out stack)
116
* @param arr The array to add an element to.
117
* @return Location for the new element in the array.
118
* @remark If there are no free spots in the array, then this function will
119
* allocate new space for the new element.
121
APR_DECLARE(void *) apr_array_push(apr_array_header_t *arr);
124
* Remove an element from an array (as a first-in, last-out stack)
125
* @param arr The array to remove an element from.
126
* @return Location of the element in the array.
127
* @remark If there are no elements in the array, NULL is returned.
129
APR_DECLARE(void *) apr_array_pop(apr_array_header_t *arr);
132
* Concatenate two arrays together
133
* @param dst The destination array, and the one to go first in the combined
135
* @param src The source array to add to the destination array
137
APR_DECLARE(void) apr_array_cat(apr_array_header_t *dst,
138
const apr_array_header_t *src);
141
* Copy the entire array
142
* @param p The pool to allocate the copy of the array out of
143
* @param arr The array to copy
144
* @return An exact copy of the array passed in
145
* @remark The alternate apr_array_copy_hdr copies only the header, and arranges
146
* for the elements to be copied if (and only if) the code subsequently
147
* does a push or arraycat.
149
APR_DECLARE(apr_array_header_t *) apr_array_copy(apr_pool_t *p,
150
const apr_array_header_t *arr);
152
* Copy the headers of the array, and arrange for the elements to be copied if
153
* and only if the code subsequently does a push or arraycat.
154
* @param p The pool to allocate the copy of the array out of
155
* @param arr The array to copy
156
* @return An exact copy of the array passed in
157
* @remark The alternate apr_array_copy copies the *entire* array.
159
APR_DECLARE(apr_array_header_t *) apr_array_copy_hdr(apr_pool_t *p,
160
const apr_array_header_t *arr);
163
* Append one array to the end of another, creating a new array in the process.
164
* @param p The pool to allocate the new array out of
165
* @param first The array to put first in the new array.
166
* @param second The array to put second in the new array.
167
* @return A new array containing the data from the two arrays passed in.
169
APR_DECLARE(apr_array_header_t *) apr_array_append(apr_pool_t *p,
170
const apr_array_header_t *first,
171
const apr_array_header_t *second);
174
* Generates a new string from the apr_pool_t containing the concatenated
175
* sequence of substrings referenced as elements within the array. The string
176
* will be empty if all substrings are empty or null, or if there are no
177
* elements in the array. If sep is non-NUL, it will be inserted between
178
* elements as a separator.
179
* @param p The pool to allocate the string out of
180
* @param arr The array to generate the string from
181
* @param sep The separator to use
182
* @return A string containing all of the data in the array.
184
APR_DECLARE(char *) apr_array_pstrcat(apr_pool_t *p,
185
const apr_array_header_t *arr,
190
* @param p The pool to allocate the pool out of
191
* @param nelts The number of elements in the initial table.
192
* @return The new table.
193
* @warning This table can only store text data
195
APR_DECLARE(apr_table_t *) apr_table_make(apr_pool_t *p, int nelts);
198
* Create a new table and copy another table into it
199
* @param p The pool to allocate the new table out of
200
* @param t The table to copy
201
* @return A copy of the table passed in
203
APR_DECLARE(apr_table_t *) apr_table_copy(apr_pool_t *p,
204
const apr_table_t *t);
207
* Delete all of the elements from a table
208
* @param t The table to clear
210
APR_DECLARE(void) apr_table_clear(apr_table_t *t);
213
* Get the value associated with a given key from the table. After this call,
214
* The data is still in the table
215
* @param t The table to search for the key
216
* @param key The key to search for
217
* @return The value associated with the key, or NULL if the key does not exist.
219
APR_DECLARE(const char *) apr_table_get(const apr_table_t *t, const char *key);
222
* Add a key/value pair to a table, if another element already exists with the
223
* same key, this will over-write the old data.
224
* @param t The table to add the data to.
225
* @param key The key fo use
226
* @param val The value to add
227
* @remark When adding data, this function makes a copy of both the key and the
230
APR_DECLARE(void) apr_table_set(apr_table_t *t, const char *key,
234
* Add a key/value pair to a table, if another element already exists with the
235
* same key, this will over-write the old data.
236
* @param t The table to add the data to.
237
* @param key The key to use
238
* @param val The value to add
239
* @warning When adding data, this function does not make a copy of the key or
240
* the value, so care should be taken to ensure that the values will
241
* not change after they have been added..
243
APR_DECLARE(void) apr_table_setn(apr_table_t *t, const char *key,
247
* Remove data from the table
248
* @param t The table to remove data from
249
* @param key The key of the data being removed
251
APR_DECLARE(void) apr_table_unset(apr_table_t *t, const char *key);
254
* Add data to a table by merging the value with data that has already been
256
* @param t The table to search for the data
257
* @param key The key to merge data for
258
* @param val The data to add
259
* @remark If the key is not found, then this function acts like apr_table_add
261
APR_DECLARE(void) apr_table_merge(apr_table_t *t, const char *key,
265
* Add data to a table by merging the value with data that has already been
267
* @param t The table to search for the data
268
* @param key The key to merge data for
269
* @param val The data to add
270
* @remark If the key is not found, then this function acts like apr_table_addn
272
APR_DECLARE(void) apr_table_mergen(apr_table_t *t, const char *key,
276
* Add data to a table, regardless of whether there is another element with the
278
* @param t The table to add to
279
* @param key The key to use
280
* @param val The value to add.
281
* @remark When adding data, this function makes a copy of both the key and the
284
APR_DECLARE(void) apr_table_add(apr_table_t *t, const char *key,
288
* Add data to a table, regardless of whether there is another element with the
290
* @param t The table to add to
291
* @param key The key to use
292
* @param val The value to add.
293
* @remark When adding data, this function does not make a copy of the key or the
294
* value, so care should be taken to ensure that the values will not
295
* change after they have been added..
297
APR_DECLARE(void) apr_table_addn(apr_table_t *t, const char *key,
301
* Merge two tables into one new table
302
* @param p The pool to use for the new table
303
* @param overlay The first table to put in the new table
304
* @param base The table to add at the end of the new table
305
* @return A new table containing all of the data from the two passed in
307
APR_DECLARE(apr_table_t *) apr_table_overlay(apr_pool_t *p,
308
const apr_table_t *overlay,
309
const apr_table_t *base);
312
* Declaration prototype for the iterator callback function of apr_table_do()
313
* and apr_table_vdo().
314
* @param rec The data passed as the first argument to apr_table_[v]do()
315
* @param key The key from this iteration of the table
316
* @param value The value from this iteration of the table
317
* @remark Iteration continues while this callback function returns non-zero.
318
* To export the callback function for apr_table_[v]do() it must be declared
319
* in the _NONSTD convention.
321
typedef int (apr_table_do_callback_fn_t)(void *rec, const char *key,
325
* Iterate over a table running the provided function once for every
326
* element in the table. If there is data passed in as a vararg, then the
327
* function is only run on those elements whose key matches something in
328
* the vararg. If the vararg is NULL, then every element is run through the
329
* function. Iteration continues while the function returns non-zero.
330
* @param comp The function to run
331
* @param rec The data to pass as the first argument to the function
332
* @param t The table to iterate over
333
* @param ... The vararg. If this is NULL, then all elements in the table are
334
* run through the function, otherwise only those whose key matches
336
* @return FALSE if one of the comp() iterations returned zero; TRUE if all
337
* iterations returned non-zero
338
* @see apr_table_do_callback_fn_t
340
APR_DECLARE_NONSTD(int) apr_table_do(apr_table_do_callback_fn_t *comp,
341
void *rec, const apr_table_t *t, ...);
344
* Iterate over a table running the provided function once for every
345
* element in the table. If there is data passed in as a vararg, then the
346
* function is only run on those element's whose key matches something in
347
* the vararg. If the vararg is NULL, then every element is run through the
348
* function. Iteration continues while the function returns non-zero.
349
* @param comp The function to run
350
* @param rec The data to pass as the first argument to the function
351
* @param t The table to iterate over
352
* @param vp The vararg table. If this is NULL, then all elements in the
353
* table are run through the function, otherwise only those
354
* whose key matches are run.
355
* @return FALSE if one of the comp() iterations returned zero; TRUE if all
356
* iterations returned non-zero
357
* @see apr_table_do_callback_fn_t
359
APR_DECLARE(int) apr_table_vdo(apr_table_do_callback_fn_t *comp,
360
void *rec, const apr_table_t *t, va_list vp);
362
/** flag for overlap to use apr_table_setn */
363
#define APR_OVERLAP_TABLES_SET (0)
364
/** flag for overlap to use apr_table_mergen */
365
#define APR_OVERLAP_TABLES_MERGE (1)
367
* For each element in table b, either use setn or mergen to add the data
368
* to table a. Which method is used is determined by the flags passed in.
369
* @param a The table to add the data to.
370
* @param b The table to iterate over, adding its data to table a
371
* @param flags How to add the table to table a. One of:
372
* APR_OVERLAP_TABLES_SET Use apr_table_setn
373
* APR_OVERLAP_TABLES_MERGE Use apr_table_mergen
374
* @remark This function is highly optimized, and uses less memory and CPU cycles
375
* than a function that just loops through table b calling other functions.
379
* Conceptually, apr_table_overlap does this:
381
* apr_array_header_t *barr = apr_table_elts(b);
382
* apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
385
* for (i = 0; i < barr->nelts; ++i) {
386
* if (flags & APR_OVERLAP_TABLES_MERGE) {
387
* apr_table_mergen(a, belt[i].key, belt[i].val);
390
* apr_table_setn(a, belt[i].key, belt[i].val);
394
* Except that it is more efficient (less space and cpu-time) especially
395
* when b has many elements.
397
* Notice the assumptions on the keys and values in b -- they must be
398
* in an ancestor of a's pool. In practice b and a are usually from
403
APR_DECLARE(void) apr_table_overlap(apr_table_t *a, const apr_table_t *b,
407
* Eliminate redundant entries in a table by either overwriting
408
* or merging duplicates
411
* @param flags APR_OVERLAP_TABLES_MERGE to merge, or
412
* APR_OVERLAP_TABLES_SET to overwrite
414
APR_DECLARE(void) apr_table_compress(apr_table_t *t, unsigned flags);
422
#endif /* ! APR_TABLES_H */
added
removed
srclib/apr/include/apr_tables.h
