Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_tables.h

Go to the documentation of this file.
00001 /* Copyright 2000-2004 The Apache Software Foundation 00002 * 00003 * Licensed under the Apache License, Version 2.0 (the "License"); 00004 * you may not use this file except in compliance with the License. 00005 * You may obtain a copy of the License at 00006 * 00007 * http://www.apache.org/licenses/LICENSE-2.0 00008 * 00009 * Unless required by applicable law or agreed to in writing, software 00010 * distributed under the License is distributed on an "AS IS" BASIS, 00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00012 * See the License for the specific language governing permissions and 00013 * limitations under the License. 00014 */ 00015 00016 #ifndef APR_TABLES_H 00017 #define APR_TABLES_H 00018 00019 /** 00020 * @file apr_tables.h 00021 * @brief APR Table library 00022 */ 00023 00024 #include "apr.h" 00025 #include "apr_pools.h" 00026 00027 #if APR_HAVE_STDARG_H 00028 #include <stdarg.h> /* for va_list */ 00029 #endif 00030 00031 #ifdef __cplusplus 00032 extern "C" { 00033 #endif /* __cplusplus */ 00034 00035 /** 00036 * @defgroup apr_tables Table and Array Functions 00037 * @ingroup APR 00038 * Tables are used to store entirely opaque structures 00039 * for applications, while Arrays are usually used to 00040 * deal with string lists. 00041 * @{ 00042 */ 00043 00044 /** the table abstract data type */ 00045 typedef struct apr_table_t apr_table_t; 00046 00047 /** @see apr_array_header_t */ 00048 typedef struct apr_array_header_t apr_array_header_t; 00049 00050 /** An opaque array type */ 00051 struct apr_array_header_t { 00052 /** The pool the array is allocated out of */ 00053 apr_pool_t *pool; 00054 /** The amount of memory allocated for each element of the array */ 00055 int elt_size; 00056 /** The number of active elements in the array */ 00057 int nelts; 00058 /** The number of elements allocated in the array */ 00059 int nalloc; 00060 /** The elements in the array */ 00061 char *elts; 00062 }; 00063 00064 /** 00065 * The (opaque) structure for string-content tables. 00066 */ 00067 typedef struct apr_table_entry_t apr_table_entry_t; 00068 00069 /** The type for each entry in a string-content table */ 00070 struct apr_table_entry_t { 00071 /** The key for the current table entry */ 00072 char *key; /* maybe NULL in future; 00073 * check when iterating thru table_elts 00074 */ 00075 /** The value for the current table entry */ 00076 char *val; 00077 00078 /** A checksum for the key, for use by the apr_table internals */ 00079 apr_uint32_t key_checksum; 00080 }; 00081 00082 /** 00083 * Get the elements from a table 00084 * @param t The table 00085 * @return An array containing the contents of the table 00086 */ 00087 APR_DECLARE(const apr_array_header_t *) apr_table_elts(const apr_table_t *t); 00088 00089 /** 00090 * Determine if the table is empty 00091 * @param t The table to check 00092 * @return True if empty, False otherwise 00093 */ 00094 APR_DECLARE(int) apr_is_empty_table(const apr_table_t *t); 00095 00096 /** 00097 * Determine if the array is empty 00098 * @param a The array to check 00099 * @return True if empty, False otherwise 00100 */ 00101 APR_DECLARE(int) apr_is_empty_array(const apr_array_header_t *a); 00102 00103 /** 00104 * Create an array 00105 * @param p The pool to allocate the memory out of 00106 * @param nelts the number of elements in the initial array 00107 * @param elt_size The size of each element in the array. 00108 * @return The new array 00109 */ 00110 APR_DECLARE(apr_array_header_t *) apr_array_make(apr_pool_t *p, 00111 int nelts, int elt_size); 00112 00113 /** 00114 * Add a new element to an array (as a first-in, last-out stack) 00115 * @param arr The array to add an element to. 00116 * @return Location for the new element in the array. 00117 * @remark If there are no free spots in the array, then this function will 00118 * allocate new space for the new element. 00119 */ 00120 APR_DECLARE(void *) apr_array_push(apr_array_header_t *arr); 00121 00122 /** 00123 * Remove an element from an array (as a first-in, last-out stack) 00124 * @param arr The array to remove an element from. 00125 * @return Location of the element in the array. 00126 * @remark If there are no elements in the array, NULL is returned. 00127 */ 00128 APR_DECLARE(void *) apr_array_pop(apr_array_header_t *arr); 00129 00130 /** 00131 * Concatenate two arrays together 00132 * @param dst The destination array, and the one to go first in the combined 00133 * array 00134 * @param src The source array to add to the destination array 00135 */ 00136 APR_DECLARE(void) apr_array_cat(apr_array_header_t *dst, 00137 const apr_array_header_t *src); 00138 00139 /** 00140 * Copy the entire array 00141 * @param p The pool to allocate the copy of the array out of 00142 * @param arr The array to copy 00143 * @return An exact copy of the array passed in 00144 * @remark The alternate apr_array_copy_hdr copies only the header, and arranges 00145 * for the elements to be copied if (and only if) the code subsequently 00146 * does a push or arraycat. 00147 */ 00148 APR_DECLARE(apr_array_header_t *) apr_array_copy(apr_pool_t *p, 00149 const apr_array_header_t *arr); 00150 /** 00151 * Copy the headers of the array, and arrange for the elements to be copied if 00152 * and only if the code subsequently does a push or arraycat. 00153 * @param p The pool to allocate the copy of the array out of 00154 * @param arr The array to copy 00155 * @return An exact copy of the array passed in 00156 * @remark The alternate apr_array_copy copies the *entire* array. 00157 */ 00158 APR_DECLARE(apr_array_header_t *) apr_array_copy_hdr(apr_pool_t *p, 00159 const apr_array_header_t *arr); 00160 00161 /** 00162 * Append one array to the end of another, creating a new array in the process. 00163 * @param p The pool to allocate the new array out of 00164 * @param first The array to put first in the new array. 00165 * @param second The array to put second in the new array. 00166 * @return A new array containing the data from the two arrays passed in. 00167 */ 00168 APR_DECLARE(apr_array_header_t *) apr_array_append(apr_pool_t *p, 00169 const apr_array_header_t *first, 00170 const apr_array_header_t *second); 00171 00172 /** 00173 * Generates a new string from the apr_pool_t containing the concatenated 00174 * sequence of substrings referenced as elements within the array. The string 00175 * will be empty if all substrings are empty or null, or if there are no 00176 * elements in the array. If sep is non-NUL, it will be inserted between 00177 * elements as a separator. 00178 * @param p The pool to allocate the string out of 00179 * @param arr The array to generate the string from 00180 * @param sep The separator to use 00181 * @return A string containing all of the data in the array. 00182 */ 00183 APR_DECLARE(char *) apr_array_pstrcat(apr_pool_t *p, 00184 const apr_array_header_t *arr, 00185 const char sep); 00186 00187 /** 00188 * Make a new table 00189 * @param p The pool to allocate the pool out of 00190 * @param nelts The number of elements in the initial table. 00191 * @return The new table. 00192 * @warning This table can only store text data 00193 */ 00194 APR_DECLARE(apr_table_t *) apr_table_make(apr_pool_t *p, int nelts); 00195 00196 /** 00197 * Create a new table and copy another table into it 00198 * @param p The pool to allocate the new table out of 00199 * @param t The table to copy 00200 * @return A copy of the table passed in 00201 */ 00202 APR_DECLARE(apr_table_t *) apr_table_copy(apr_pool_t *p, 00203 const apr_table_t *t); 00204 00205 /** 00206 * Delete all of the elements from a table 00207 * @param t The table to clear 00208 */ 00209 APR_DECLARE(void) apr_table_clear(apr_table_t *t); 00210 00211 /** 00212 * Get the value associated with a given key from the table. After this call, 00213 * The data is still in the table 00214 * @param t The table to search for the key 00215 * @param key The key to search for 00216 * @return The value associated with the key 00217 */ 00218 APR_DECLARE(const char *) apr_table_get(const apr_table_t *t, const char *key); 00219 00220 /** 00221 * Add a key/value pair to a table, if another element already exists with the 00222 * same key, this will over-write the old data. 00223 * @param t The table to add the data to. 00224 * @param key The key fo use 00225 * @param val The value to add 00226 * @remark When adding data, this function makes a copy of both the key and the 00227 * value. 00228 */ 00229 APR_DECLARE(void) apr_table_set(apr_table_t *t, const char *key, 00230 const char *val); 00231 00232 /** 00233 * Add a key/value pair to a table, if another element already exists with the 00234 * same key, this will over-write the old data. 00235 * @param t The table to add the data to. 00236 * @param key The key to use 00237 * @param val The value to add 00238 * @warning When adding data, this function does not make a copy of the key or 00239 * the value, so care should be taken to ensure that the values will 00240 * not change after they have been added.. 00241 */ 00242 APR_DECLARE(void) apr_table_setn(apr_table_t *t, const char *key, 00243 const char *val); 00244 00245 /** 00246 * Remove data from the table 00247 * @param t The table to remove data from 00248 * @param key The key of the data being removed 00249 */ 00250 APR_DECLARE(void) apr_table_unset(apr_table_t *t, const char *key); 00251 00252 /** 00253 * Add data to a table by merging the value with data that has already been 00254 * stored 00255 * @param t The table to search for the data 00256 * @param key The key to merge data for 00257 * @param val The data to add 00258 * @remark If the key is not found, then this function acts like apr_table_add 00259 */ 00260 APR_DECLARE(void) apr_table_merge(apr_table_t *t, const char *key, 00261 const char *val); 00262 00263 /** 00264 * Add data to a table by merging the value with data that has already been 00265 * stored 00266 * @param t The table to search for the data 00267 * @param key The key to merge data for 00268 * @param val The data to add 00269 * @remark If the key is not found, then this function acts like apr_table_addn 00270 */ 00271 APR_DECLARE(void) apr_table_mergen(apr_table_t *t, const char *key, 00272 const char *val); 00273 00274 /** 00275 * Add data to a table, regardless of whether there is another element with the 00276 * same key. 00277 * @param t The table to add to 00278 * @param key The key to use 00279 * @param val The value to add. 00280 * @remark When adding data, this function makes a copy of both the key and the 00281 * value. 00282 */ 00283 APR_DECLARE(void) apr_table_add(apr_table_t *t, const char *key, 00284 const char *val); 00285 00286 /** 00287 * Add data to a table, regardless of whether there is another element with the 00288 * same key. 00289 * @param t The table to add to 00290 * @param key The key to use 00291 * @param val The value to add. 00292 * @remark When adding data, this function does not make a copy of the key or the 00293 * value, so care should be taken to ensure that the values will not 00294 * change after they have been added.. 00295 */ 00296 APR_DECLARE(void) apr_table_addn(apr_table_t *t, const char *key, 00297 const char *val); 00298 00299 /** 00300 * Merge two tables into one new table 00301 * @param p The pool to use for the new table 00302 * @param overlay The first table to put in the new table 00303 * @param base The table to add at the end of the new table 00304 * @return A new table containing all of the data from the two passed in 00305 */ 00306 APR_DECLARE(apr_table_t *) apr_table_overlay(apr_pool_t *p, 00307 const apr_table_t *overlay, 00308 const apr_table_t *base); 00309 00310 /** 00311 * Declaration prototype for the iterator callback function of apr_table_do() 00312 * and apr_table_vdo(). 00313 * @param rec The data passed as the first argument to apr_table_[v]do() 00314 * @param key The key from this iteration of the table 00315 * @param value The value from this iteration of the table 00316 * @remark Iteration continues while this callback function returns non-zero. 00317 * To export the callback function for apr_table_[v]do() it must be declared 00318 * in the _NONSTD convention. 00319 */ 00320 typedef int (apr_table_do_callback_fn_t)(void *rec, const char *key, 00321 const char *value); 00322 00323 /** 00324 * Iterate over a table running the provided function once for every 00325 * element in the table. If there is data passed in as a vararg, then the 00326 * function is only run on those elements whose key matches something in 00327 * the vararg. If the vararg is NULL, then every element is run through the 00328 * function. Iteration continues while the function returns non-zero. 00329 * @param comp The function to run 00330 * @param rec The data to pass as the first argument to the function 00331 * @param t The table to iterate over 00332 * @param ... The vararg. If this is NULL, then all elements in the table are 00333 * run through the function, otherwise only those whose key matches 00334 * are run. 00335 * @return FALSE if one of the comp() iterations returned zero; TRUE if all 00336 * iterations returned non-zero 00337 * @see apr_table_do_callback_fn_t 00338 */ 00339 APR_DECLARE_NONSTD(int) apr_table_do(apr_table_do_callback_fn_t *comp, 00340 void *rec, const apr_table_t *t, ...); 00341 00342 /** 00343 * Iterate over a table running the provided function once for every 00344 * element in the table. If there is data passed in as a vararg, then the 00345 * function is only run on those element's whose key matches something in 00346 * the vararg. If the vararg is NULL, then every element is run through the 00347 * function. Iteration continues while the function returns non-zero. 00348 * @param comp The function to run 00349 * @param rec The data to pass as the first argument to the function 00350 * @param t The table to iterate over 00351 * @param vp The vararg table. If this is NULL, then all elements in the 00352 * table are run through the function, otherwise only those 00353 * whose key matches are run. 00354 * @return FALSE if one of the comp() iterations returned zero; TRUE if all 00355 * iterations returned non-zero 00356 * @see apr_table_do_callback_fn_t 00357 */ 00358 APR_DECLARE(int) apr_table_vdo(apr_table_do_callback_fn_t *comp, 00359 void *rec, const apr_table_t *t, va_list vp); 00360 00361 /** flag for overlap to use apr_table_setn */ 00362 #define APR_OVERLAP_TABLES_SET (0) 00363 /** flag for overlap to use apr_table_mergen */ 00364 #define APR_OVERLAP_TABLES_MERGE (1) 00365 /** 00366 * For each element in table b, either use setn or mergen to add the data 00367 * to table a. Which method is used is determined by the flags passed in. 00368 * @param a The table to add the data to. 00369 * @param b The table to iterate over, adding its data to table a 00370 * @param flags How to add the table to table a. One of: 00371 * APR_OVERLAP_TABLES_SET Use apr_table_setn 00372 * APR_OVERLAP_TABLES_MERGE Use apr_table_mergen 00373 * @remark This function is highly optimized, and uses less memory and CPU cycles 00374 * than a function that just loops through table b calling other functions. 00375 */ 00376 /** 00377 *<PRE> 00378 * Conceptually, apr_table_overlap does this: 00379 * 00380 * apr_array_header_t *barr = apr_table_elts(b); 00381 * apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts; 00382 * int i; 00383 * 00384 * for (i = 0; i < barr->nelts; ++i) { 00385 * if (flags & APR_OVERLAP_TABLES_MERGE) { 00386 * apr_table_mergen(a, belt[i].key, belt[i].val); 00387 * } 00388 * else { 00389 * apr_table_setn(a, belt[i].key, belt[i].val); 00390 * } 00391 * } 00392 * 00393 * Except that it is more efficient (less space and cpu-time) especially 00394 * when b has many elements. 00395 * 00396 * Notice the assumptions on the keys and values in b -- they must be 00397 * in an ancestor of a's pool. In practice b and a are usually from 00398 * the same pool. 00399 * </PRE> 00400 */ 00401 00402 APR_DECLARE(void) apr_table_overlap(apr_table_t *a, const apr_table_t *b, 00403 unsigned flags); 00404 00405 /** 00406 * Eliminate redundant entries in a table by either overwriting 00407 * or merging duplicates 00408 * 00409 * @param t Table. 00410 * @param flags APR_OVERLAP_TABLES_MERGE to merge, or 00411 * APR_OVERLAP_TABLES_SET to overwrite 00412 */ 00413 APR_DECLARE(void) apr_table_compress(apr_table_t *t, unsigned flags); 00414 00415 /** @} */ 00416 00417 #ifdef __cplusplus 00418 } 00419 #endif 00420 00421 #endif /* ! APR_TABLES_H */

Generated on Thu Sep 16 13:47:10 2004 for Apache Portable Runtime by doxygen 1.3.7