apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@locus.apache.org
Subject cvs commit: apr/include apr_tables.h
Date Mon, 04 Dec 2000 14:51:32 GMT
rbb         00/12/04 06:51:32

  Modified:    include  apr_tables.h
  Log:
  Add documentation to APR's tables interface
  
  Revision  Changes    Path
  1.10      +324 -10   apr/include/apr_tables.h
  
  Index: apr_tables.h
  ===================================================================
  RCS file: /home/cvs/apr/include/apr_tables.h,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- apr_tables.h	2000/11/26 03:00:04	1.9
  +++ apr_tables.h	2000/12/04 14:51:31	1.10
  @@ -172,22 +172,63 @@
       apr_item_t *val;
   };
   
  -/* XXX: these know about the definition of struct apr_table_t in alloc.c.  That
  - * definition is not here because it is supposed to be private, and by not
  - * placing it here we are able to get compile-time diagnostics from modules
  - * written which assume that a apr_table_t is the same as an
  - * apr_array_header_t. -djg
  +/**
  + * Get the elements from a table
  + * @param t The table
  + * @return An array containing the contents of the table
  + * @deffunc apr_array_header_t *apr_table_elts(apr_table_t *t)
    */
   #define apr_table_elts(t) ((apr_array_header_t *)(t))
  +/**
  + * Get the elements from a binary table
  + * @param t The table
  + * @return An array containing the contents of the table
  + * @deffunc apr_array_header_t *apr_table_elts(apr_table_t *t)
  + */
   #define apr_btable_elts(t) apr_table_elts(t)
   
  +/**
  + * Determine if the table is empty
  + * @param t The table to check
  + * @return True if empty, Falso otherwise
  + */
   #define apr_is_empty_table(t) (((t) == NULL) \
                                  || (((apr_array_header_t *)(t))->nelts == 0))
  +/**
  + * Determine if the binary table is empty
  + * @param t The table to check
  + * @return True if empty, Falso otherwise
  + */
   #define apr_is_empty_btable(t) apr_is_empty_table(t)
   
  +/**
  + * Create an array
  + * @param p The pool to allocate the memory out of
  + * @param nelts the number of elements in the initial array
  + * @param elt_size The size of each element in the array.
  + * @return The new array
  + * #deffunc apr_array_header_t *apr_make_array(struct apr_pool_t *p, int nelts, int elt_size)
  + */
   APR_DECLARE(apr_array_header_t *) apr_make_array(struct apr_pool_t *p,
   						int nelts, int elt_size);
  +
  +/**
  + * Add a new element to an array
  + * @param arr The array to add an element to.
  + * @return Location for the new element in the array.
  + * @tip If there are no free spots in the array, then this function will
  + *      allocate new space for the new element.
  + * @deffunc void *apr_push_array(apr_array_header_t *arr)
  + */
   APR_DECLARE(void *) apr_push_array(apr_array_header_t *arr);
  +
  +/**
  + * Concatenate two arrays together
  + * @param dst The destination array, and the one to go first in the combined 
  + *            array
  + * @param src The source array to add to the destination array
  + * @deffunc void apr_array_cat(apr_array_header_t *dst, const apr_array_header_t *src)
  + */
   APR_DECLARE(void) apr_array_cat(apr_array_header_t *dst,
   			       const apr_array_header_t *src);
   
  @@ -195,67 +236,328 @@
    * the header, and arranges for the elements to be copied if (and only
    * if) the code subsequently does a push or arraycat.
    */
  +/**
  + * Copy the entire array
  + * @param p The pool to allocate the copy of the array out of
  + * @param arr The array to copy
  + * @return An exact copy of the array passed in
  + * @deffunc apr_array_header_t *apr_copy_array(apr_pool_t *p, const apr_array_header_t
*arr)
  + */
   APR_DECLARE(apr_array_header_t *) apr_copy_array(struct apr_pool_t *p,
   						const apr_array_header_t *arr);
  +/**
  + * Copy the headers of the array, and arrange for the elements to be copied if
  + * and only if the code subsequently does a push or arraycat.
  + * @param p The pool to allocate the copy of the array out of
  + * @param arr The array to copy
  + * @return An exact copy of the array passed in
  + * @deffunc apr_array_header_t *apr_copy_array_hdr(apr_pool_t *p, const apr_array_header_t
*arr)
  + */
   APR_DECLARE(apr_array_header_t *)
   	apr_copy_array_hdr(struct apr_pool_t *p,
   			   const apr_array_header_t *arr);
  +
  +/**
  + * Append one array to the end of another, creating a new array in the process.
  + * @param p The pool to allocate the new array out of
  + * @param first The array to put first in the new array.
  + * @param second The array to put second in the new array.
  + * @param return A new array containing the data from the two arrays passed in.
  + * @deffunc apr_array_header_t *apr_append_arrays(apr_pool_t *p, const apr_array_header_t
*first, const apr_array_header_t *second)
  +*/
   APR_DECLARE(apr_array_header_t *)
   	apr_append_arrays(struct apr_pool_t *p,
   			  const apr_array_header_t *first,
   			  const apr_array_header_t *second);
   
  -/* apr_array_pstrcat generates a new string from the apr_pool_t containing
  - * the concatenated sequence of substrings referenced as elements within
  - * the array.  The string will be empty if all substrings are empty or null,
  - * or if there are no elements in the array.
  - * If sep is non-NUL, it will be inserted between elements as a separator.
  +/**
  + * Generates a new string from the apr_pool_t containing the concatenated 
  + * sequence of substrings referenced as elements within the array.  The string 
  + * will be empty if all substrings are empty or null, or if there are no 
  + * elements in the array.  If sep is non-NUL, it will be inserted between 
  + * elements as a separator.
  + * @param p The pool to allocate the string out of
  + * @param arr The array to generate the string from
  + * @param sep The separator to use
  + * @return A string containing all of the data in the array.
  + * @deffuncchar *apr_array_pstrcat(apr_pool_t *p, const apr_array_header_t *arr, const
char sep)
    */
   APR_DECLARE(char *) apr_array_pstrcat(struct apr_pool_t *p,
   				     const apr_array_header_t *arr,
   				     const char sep);
  +
  +/**
  + * Make a new table
  + * @param p The pool to allocate the pool out of
  + * @param nelts The number of elements in the initial table.
  + * @return The new table.
  + * @warning This table can only store text data
  + * @deffunc apr_table_t *apr_make_table(apr_pool_t *p, int nelts)
  + */
   APR_DECLARE(apr_table_t *) apr_make_table(struct apr_pool_t *p, int nelts);
  +
  +/**
  + * Make a new table capable of storing binary data
  + * @param p The pool to allocate the pool out of
  + * @param nelts The number of elements in the initial table.
  + * @return The new table.
  + * @deffunc apr_table_t *apr_make_btable(apr_pool_t *p, int nelts)
  + */
   APR_DECLARE(apr_btable_t *) apr_make_btable(struct apr_pool_t *p, int nelts);
  +
  +/**
  + * Create a new table and copy another table into it
  + * @param p The pool to allocate the new table out of
  + * @param t The table to copy
  + * @return A copy of the table passed in
  + * @deffunc apr_table_t *) apr_copy_table(apr_pool_t *p, const apr_table_t *t)
  + */
   APR_DECLARE(apr_table_t *) apr_copy_table(struct apr_pool_t *p,
   					 const apr_table_t *t);
  +/**
  + * Create a new binary table and copy another table into it
  + * @param p The pool to allocate the new table out of
  + * @param t The table to copy
  + * @return A copy of the table passed in
  + * @deffunc apr_table_t *) apr_copy_btable(apr_pool_t *p, const apr_btable_t *t)
  + */
   APR_DECLARE(apr_btable_t *) apr_copy_btable(struct apr_pool_t *p,
   					   const apr_btable_t *t);
  +
  +/**
  + * Delete all of the elements from a table
  + * @param t The table to clear
  + * @deffunc void apr_clear_table(apr_table_t *t)
  + */
   APR_DECLARE(void) apr_clear_table(apr_table_t *t);
  +/**
  + * Delete all of the elements from a binary table
  + * @param t The table to clear
  + * @deffunc void apr_clear_btable(apr_btable_t *t)
  + */
   APR_DECLARE(void) apr_clear_btable(apr_btable_t *t);
  +
  +/**
  + * Get the value associated with a given key from the table.  After this call,
  + * The data is still in the table
  + * @param t The table to search for the key
  + * @param key The key to search for
  + * @return The value associated with the key
  + * @deffunc const char *apr_table_get(const apr_table_t *t, const char *key)
  + */
   APR_DECLARE(const char *) apr_table_get(const apr_table_t *t, const char *key);
  +/**
  + * Get the value associated with a given key from a binary table.  After this
  + * call, the data is still in the table.
  + * @param t The table to search for the key
  + * @param key The key to search for
  + * @return The value associated with the key
  + * @deffunc const apr_item_t *apr_btable_get(const apr_btable_t *t, const char *key)
  + */
   APR_DECLARE(const apr_item_t *) apr_btable_get(const apr_btable_t *t,
   					      const char *key);
  +
  +/**
  + * Add a key/value pair to a table, if another element already exists with the
  + * same key, this will over-write the old data.
  + * @param t The table to add the data to.
  + * @param key The key fo use
  + * @param val The value to add
  + * @tip When adding data, this function makes a copy of both the key and the
  + *      value.
  + * @deffunc void apr_table_set(apr_table_t *t, const char *key, const char *val)
  + */
   APR_DECLARE(void) apr_table_set(apr_table_t *t, const char *key,
   			       const char *val);
  +/**
  + * Add a key/value pair to a binary table if another element already exists 
  + * with the same key, this will over-write the old data.
  + * @param t The table to add the data to.
  + * @param key The key fo use
  + * @param size The size of the data to add
  + * @param val The value to add
  + * @tip When adding data, this function makes a copy of both the key and the
  + *      value.
  + * @deffunc void apr_btable_set(apr_btable_t *t, const char *key, size_t size, const void
*val)
  + */
   APR_DECLARE(void) apr_btable_set(apr_btable_t *t, const char *key,
   				size_t size, const void *val);
  +
  +/**
  + * Add a key/value pair to a table, if another element already exists with the
  + * same key, this will over-write the old data.
  + * @param t The table to add the data to.
  + * @param key The key fo use
  + * @param val The value to add
  + * @tip When adding data, this function does not make a copy of the key or the
  + *      value, so care should be taken to ensure that the values will not 
  + *      change after they have been added..
  + * @deffunc void apr_table_setn(apr_table_t *t, const char *key, const char *val)
  + */
   APR_DECLARE(void) apr_table_setn(apr_table_t *t, const char *key,
   				const char *val);
  +/**
  + * Add a key/value pair to a binary table if another element already exists 
  + * with the same key, this will over-write the old data.
  + * @param t The table to add the data to.
  + * @param key The key fo use
  + * @param size The size of the data to add
  + * @param val The value to add
  + * @tip When adding data, this function does not make a copy of the key or the
  + *      value, so care should be taken to ensure that the values will not 
  + *      change after they have been added..
  + * @deffunc void apr_btable_setn(apr_btable_t *t, const char *key, size_t size, const void
*val)
  + */
   APR_DECLARE(void) apr_btable_setn(apr_btable_t *t, const char *key,
   				 size_t size, const void *val);
  +
  +/**
  + * Remove data from the table
  + * @param t The table to remove data from
  + * @param key The key of the data being removed
  + * @deffunc void apr_table_unset(apr_table_t *t, const char *key)
  + */
   APR_DECLARE(void) apr_table_unset(apr_table_t *t, const char *key);
  +/**
  + * Remove data from a binary table
  + * @param t The table to remove data from
  + * @param key The key of the data being removed
  + * @deffunc void apr_btable_unset(apr_btable_t *t, const char *key)
  + */
   APR_DECLARE(void) apr_btable_unset(apr_btable_t *t, const char *key);
  +
  +/**
  + * Add data to a table by merging the value with data that has already been 
  + * stored
  + * @param t The table to search for the data
  + * @param key The key to merge data for
  + * @param val The data to add
  + * @tip If the key is not found, then this function acts like apr_table_add
  + * @deffunc void apr_table_merge(apr_table_t *t, const char *key, const char *val)
  + */
   APR_DECLARE(void) apr_table_merge(apr_table_t *t, const char *key,
   				 const char *val);
  +/**
  + * Add data to a table by merging the value with data that has already been 
  + * stored
  + * @param t The table to search for the data
  + * @param key The key to merge data for
  + * @param val The data to add
  + * @tip If the key is not found, then this function acts like apr_table_addn
  + * @deffunc void apr_table_mergen(apr_table_t *t, const char *key, const char *val)
  + */
   APR_DECLARE(void) apr_table_mergen(apr_table_t *t, const char *key,
   				  const char *val);
  +
  +/**
  + * Add data to a table, regardless of whether there is another element with the
  + * same key.
  + * @param t The table to add to
  + * @param key The key to use
  + * @param val The value to add.
  + * @tip When adding data, this function makes a copy of both the key and the
  + *      value.
  + * @deffunc void apr_table_add(apr_table_t *t, const char *key, const char *val)
  + */
   APR_DECLARE(void) apr_table_add(apr_table_t *t, const char *key,
   			       const char *val);
  +/**
  + * Add data to a binary table, regardless of whether there is another element 
  + * with the same key.
  + * @param t The table to add to
  + * @param key The key to use
  + * @param size The size of the value to add
  + * @param val The value to add.
  + * @tip When adding data, this function makes a copy of both the key and the
  + *      value.
  + * @deffunc void apr_btable_add(apr_btable_t *t, const char *key, size_t size, const char
*val)
  + */
   APR_DECLARE(void) apr_btable_add(apr_btable_t *t, const char *key,
   				size_t size, const void *val);
  +
  +/**
  + * Add data to a table, regardless of whether there is another element with the
  + * same key.
  + * @param t The table to add to
  + * @param key The key to use
  + * @param val The value to add.
  + * @tip When adding data, this function does not make a copy of the key or the
  + *      value, so care should be taken to ensure that the values will not 
  + *      change after they have been added..
  + * @deffunc void apr_table_addn(apr_table_t *t, const char *key, const char *val)
  + */
   APR_DECLARE(void) apr_table_addn(apr_table_t *t, const char *key,
   				const char *val);
  +/**
  + * Add data to a binary table, regardless of whether there is another element 
  + * with the same key.
  + * @param t The table to add to
  + * @param key The key to use
  + * @param size The size of the value to add
  + * @param val The value to add.
  + * @tip When adding data, this function does not make a copy of the key or the
  + *      value, so care should be taken to ensure that the values will not 
  + *      change after they have been added..
  + * @deffunc void apr_btable_addn(apr_btable_t *t, const char *key, size_t size, const char
*val)
  + */
   APR_DECLARE(void) apr_btable_addn(apr_btable_t *t, const char *key,
   				 size_t size, const void *val);
  +
  +/**
  + * Merge two tables into one new table
  + * @param p The pool to use for the new table
  + * @param overlay The first table to put in the new table
  + * @param base The table to add at the end of the new table
  + * @return A new table containing all of the data from the two passed in
  + * @deffunc apr_table_t *apr_overlay_tables(apr_pool_t *p, const apr_table_t *overlay,
const apr_table_t *base);
  + */
   APR_DECLARE(apr_table_t *) apr_overlay_tables(struct apr_pool_t *p,
   					     const apr_table_t *overlay,
   					     const apr_table_t *base);
  +/**
  + * Merge two binary tables into one new table
  + * @param p The pool to use for the new table
  + * @param overlay The first table to put in the new table
  + * @param base The table to add at the end of the new table
  + * @return A new table containing all of the data from the two passed in
  + * @deffunc apr_btable_t *apr_overlay_tables(apr_pool_t *p, const apr_btable_t *overlay,
const apr_btable_t *base);
  + */
   APR_DECLARE(apr_btable_t *) apr_overlay_btables(struct apr_pool_t *p,
   					       const apr_btable_t *overlay,
   					       const apr_btable_t *base);
  +
  +/** 
  + * Iterate over a table running the provided function once for every
  + * element in the table.  If there is data passed in as a vararg, then the 
  + * function is only run on those element's whose key matches something in 
  + * the vararg.  If the vararg is NULL, then every element is run through the
  + * function.
  + * @param comp The function to run
  + * @param rec The data to pass as the first argument to the function
  + * @param t The table to iterate over
  + * @param ... The vararg.  If this is NULL, then all elements in the table are
  + *            run through the function, otherwise only those whose key matches
  + *            are run.
  + * @deffunc void apr_table_do(int (*comp) (void *, const char *, const char *), void *rec,
const apr_table_t *t, ...)
  + */
   APR_DECLARE(void)
   	apr_table_do(int (*comp) (void *, const char *, const char *),
   		     void *rec, const apr_table_t *t, ...);
  +
  +/** 
  + * Iterate over a table running the provided function once for every
  + * element in the table.  If there is data passed in as a vararg, then the 
  + * function is only run on those element's whose key matches something in 
  + * the vararg.  If the vararg is NULL, then every element is run through the
  + * function.
  + * @param comp The function to run
  + * @param rec The data to pass as the first argument to the function
  + * @param t The table to iterate over
  + * @param vp The vararg table.  If this is NULL, then all elements in the 
  + *                table are run through the function, otherwise only those 
  + *                whose key matches are run.
  + * @deffunc void apr_table_vdo(int (*comp) (void *, const char *, const char *), void *rec,
const apr_table_t *t, va_list vp)
  + */
   APR_DECLARE(void)
           apr_table_vdo(int (*comp) (void *, const char *, const char *),
                        void *rec, const apr_table_t *t, va_list);                  
  @@ -284,6 +586,18 @@
    */
   #define APR_OVERLAP_TABLES_SET   (0)
   #define APR_OVERLAP_TABLES_MERGE (1)
  +/**
  + * For each element in table b, either use setn or mergen to add the data
  + * to table a.  Wich method is used is determined by the flags passed in.
  + * @param a The table to add the data to.
  + * @param b The table to iterate over, adding it's data to table a
  + * @param flags How to add the table to table a.  One of:
  + *          APR_OVERLAP_TABLES_SET        Use apr_table_setn
  + *          APR_OVERLAP_TABLES_MERGE      Use apr_table_mergen
  + * @tip This function is highly optimized, and uses less memory and CPU cycles
  + *      than a function that just loops through table b calling other functions.
  + * @deffunc void apr_overlap_tables(apr_table_t *a, const apr_table_t *b, unsigned flags)
  + */
   APR_DECLARE(void) apr_overlap_tables(apr_table_t *a, const apr_table_t *b,
   				    unsigned flags);
   
  
  
  

Mime
View raw message