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);
