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 Sun Mar 20 19:52:26 2005 for Apache Portable Runtime by  doxygen 1.3.9.1