Apache Portable Runtime: Table and Array Functions

#define APR_OVERLAP_TABLES_MERGE (1)

flag for overlap to use apr_table_mergen

#define APR_OVERLAP_TABLES_SET (0)

flag for overlap to use apr_table_setn

typedef struct apr_array_header_t apr_array_header_t

See also:: apr_array_header_t

typedef int( apr_table_do_callback_fn_t)(void *rec, const char *key, const char *value)

Declaration prototype for the iterator callback function of apr_table_do() and apr_table_vdo().

Parameters:

	rec	The data passed as the first argument to apr_table_[v]do()
	key	The key from this iteration of the table
	value	The value from this iteration of the table

Remarks:: Iteration continues while this callback function returns non-zero. To export the callback function for apr_table_[v]do() it must be declared in the _NONSTD convention.

typedef struct apr_table_entry_t apr_table_entry_t

The (opaque) structure for string-content tables.

typedef struct apr_table_t apr_table_t

the table abstract data type

apr_array_header_t* apr_array_append	(	apr_pool_t *	p,
		const apr_array_header_t *	first,
		const apr_array_header_t *	second
	)

Append one array to the end of another, creating a new array in the process.

Parameters:

	p	The pool to allocate the new array out of
	first	The array to put first in the new array.
	second	The array to put second in the new array.

Returns:: A new array containing the data from the two arrays passed in.

void apr_array_cat	(	apr_array_header_t *	dst,
		const apr_array_header_t *	src
	)

Concatenate two arrays together

Parameters:

	dst	The destination array, and the one to go first in the combined array
	src	The source array to add to the destination array

apr_array_header_t* apr_array_copy	(	apr_pool_t *	p,
		const apr_array_header_t *	arr
	)

Copy the entire array

Parameters:

	p	The pool to allocate the copy of the array out of
	arr	The array to copy

Returns:: An exact copy of the array passed in

Remarks:: The alternate apr_array_copy_hdr copies only the header, and arranges for the elements to be copied if (and only if) the code subsequently does a push or arraycat.

apr_array_header_t* apr_array_copy_hdr	(	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.

Parameters:

	p	The pool to allocate the copy of the array out of
	arr	The array to copy

Returns:: An exact copy of the array passed in

Remarks:: The alternate apr_array_copy copies the *entire* array.

apr_array_header_t* apr_array_make	(	apr_pool_t *	p,
		int	nelts,
		int	elt_size
	)

Create an array

Parameters:

	p	The pool to allocate the memory out of
	nelts	the number of elements in the initial array
	elt_size	The size of each element in the array.

Returns:: The new array

void* apr_array_pop ( apr_array_header_t * arr )

Remove an element from an array (as a first-in, last-out stack)

Parameters:

arr

The array to remove an element from.

Returns:: Location of the element in the array.

Remarks:: If there are no elements in the array, NULL is returned.

char* apr_array_pstrcat	(	apr_pool_t *	p,
		const apr_array_header_t *	arr,
		const char	sep
	)

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.

Parameters:

	p	The pool to allocate the string out of
	arr	The array to generate the string from
	sep	The separator to use

Returns:: A string containing all of the data in the array.

void* apr_array_push ( apr_array_header_t * arr )

Add a new element to an array (as a first-in, last-out stack)

Parameters:

arr

The array to add an element to.

Returns:: Location for the new element in the array.

Remarks:: If there are no free spots in the array, then this function will allocate new space for the new element.

int apr_is_empty_array ( const apr_array_header_t * a )

Determine if the array is empty

Parameters:

a

The array to check

Returns:: True if empty, False otherwise

int apr_is_empty_table ( const apr_table_t * t )

Determine if the table is empty

Parameters:

t

The table to check

Returns:: True if empty, False otherwise

void apr_table_add	(	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.

Parameters:

	t	The table to add to
	key	The key to use
	val	The value to add.

Remarks:: When adding data, this function makes a copy of both the key and the value.

void apr_table_addn	(	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.

Parameters:

	t	The table to add to
	key	The key to use
	val	The value to add.

Remarks:: 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..

void apr_table_clear ( apr_table_t * t )

Delete all of the elements from a table

Parameters:

t

The table to clear

void apr_table_compress	(	apr_table_t *	t,
		unsigned	flags
	)

Eliminate redundant entries in a table by either overwriting or merging duplicates

Parameters:

	t	Table.
	flags	APR_OVERLAP_TABLES_MERGE to merge, or APR_OVERLAP_TABLES_SET to overwrite

apr_table_t* apr_table_copy	(	apr_pool_t *	p,
		const apr_table_t *	t
	)

Create a new table and copy another table into it

Parameters:

	p	The pool to allocate the new table out of
	t	The table to copy

Returns:: A copy of the table passed in

int apr_table_do	(	apr_table_do_callback_fn_t *	comp,
		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 elements whose key matches something in the vararg. If the vararg is NULL, then every element is run through the function. Iteration continues while the function returns non-zero.

Parameters:

	comp	The function to run
	rec	The data to pass as the first argument to the function
	t	The table to iterate over
	...	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.

Returns:: FALSE if one of the comp() iterations returned zero; TRUE if all iterations returned non-zero

See also:: apr_table_do_callback_fn_t

const apr_array_header_t* apr_table_elts ( const apr_table_t * t )

Get the elements from a table

Parameters:

t

The table

Returns:: An array containing the contents of the table

const char* apr_table_get	(	const apr_table_t *	t,
		const char *	key
	)

Get the value associated with a given key from the table. After this call, The data is still in the table

Parameters:

	t	The table to search for the key
	key	The key to search for

Returns:: The value associated with the key, or NULL if the key does not exist.

apr_table_t* apr_table_make	(	apr_pool_t *	p,
		int	nelts
	)

Make a new table

Parameters:

	p	The pool to allocate the pool out of
	nelts	The number of elements in the initial table.

Returns:: The new table.

Warning:: This table can only store text data

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

Parameters:

	t	The table to search for the data
	key	The key to merge data for
	val	The data to add

Remarks:: If the key is not found, then this function acts like apr_table_add

void apr_table_mergen	(	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

Parameters:

	t	The table to search for the data
	key	The key to merge data for
	val	The data to add

Remarks:: If the key is not found, then this function acts like apr_table_addn

void apr_table_overlap	(	apr_table_t *	a,
		const apr_table_t *	b,
		unsigned	flags
	)

 Conceptually, apr_table_overlap does this:

  apr_array_header_t *barr = apr_table_elts(b);
  apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
  int i;

  for (i = 0; i < barr->nelts; ++i) {
      if (flags & APR_OVERLAP_TABLES_MERGE) {
          apr_table_mergen(a, belt[i].key, belt[i].val);
      }
      else {
          apr_table_setn(a, belt[i].key, belt[i].val);
      }
  }

  Except that it is more efficient (less space and cpu-time) especially
  when b has many elements.

  Notice the assumptions on the keys and values in b -- they must be
  in an ancestor of a's pool.  In practice b and a are usually from
  the same pool.

apr_table_t* apr_table_overlay	(	apr_pool_t *	p,
		const apr_table_t *	overlay,
		const apr_table_t *	base
	)

Merge two tables into one new table

Parameters:

	p	The pool to use for the new table
	overlay	The first table to put in the new table
	base	The table to add at the end of the new table

Returns:: A new table containing all of the data from the two passed in

void apr_table_set	(	apr_table_t *	t,
		const char *	key,
		const char *	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.

Parameters:

	t	The table to add the data to.
	key	The key fo use
	val	The value to add

Remarks:: When adding data, this function makes a copy of both the key and the value.

void apr_table_setn	(	apr_table_t *	t,
		const char *	key,
		const char *	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.

Parameters:

	t	The table to add the data to.
	key	The key to use
	val	The value to add

Warning:: 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..

void apr_table_unset	(	apr_table_t *	t,
		const char *	key
	)

Remove data from the table

Parameters:

	t	The table to remove data from
	key	The key of the data being removed

int apr_table_vdo	(	apr_table_do_callback_fn_t *	comp,
		void *	rec,
		const apr_table_t *	t,
		va_list	vp
	)

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. Iteration continues while the function returns non-zero.

Parameters:

	comp	The function to run
	rec	The data to pass as the first argument to the function
	t	The table to iterate over
	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.

Returns:: FALSE if one of the comp() iterations returned zero; TRUE if all iterations returned non-zero

See also:: apr_table_do_callback_fn_t

Table and Array Functions
[Apache Portability Runtime library]

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation


Data Structures
struct	apr_array_header_t
struct	apr_table_entry_t
Defines
#define	APR_OVERLAP_TABLES_SET (0)
#define	APR_OVERLAP_TABLES_MERGE (1)
Typedefs
typedef apr_table_t	apr_table_t
typedef apr_array_header_t	apr_array_header_t
typedef apr_table_entry_t	apr_table_entry_t
typedef int(	apr_table_do_callback_fn_t )(void rec, const char key, const char *value)
Functions
const apr_array_header_t *	apr_table_elts (const apr_table_t *t)
int	apr_is_empty_table (const apr_table_t *t)
int	apr_is_empty_array (const apr_array_header_t *a)
apr_array_header_t *	apr_array_make (apr_pool_t *p, int nelts, int elt_size)
void *	apr_array_push (apr_array_header_t *arr)
void *	apr_array_pop (apr_array_header_t *arr)
void	apr_array_cat (apr_array_header_t dst, const apr_array_header_t src)
apr_array_header_t *	apr_array_copy (apr_pool_t p, const apr_array_header_t arr)
apr_array_header_t *	apr_array_copy_hdr (apr_pool_t p, const apr_array_header_t arr)
apr_array_header_t *	apr_array_append (apr_pool_t p, const apr_array_header_t first, const apr_array_header_t *second)
char *	apr_array_pstrcat (apr_pool_t p, const apr_array_header_t arr, const char sep)
apr_table_t *	apr_table_make (apr_pool_t *p, int nelts)
apr_table_t *	apr_table_copy (apr_pool_t p, const apr_table_t t)
void	apr_table_clear (apr_table_t *t)
const char *	apr_table_get (const apr_table_t t, const char key)
void	apr_table_set (apr_table_t t, const char key, const char *val)
void	apr_table_setn (apr_table_t t, const char key, const char *val)
void	apr_table_unset (apr_table_t t, const char key)
void	apr_table_merge (apr_table_t t, const char key, const char *val)
void	apr_table_mergen (apr_table_t t, const char key, const char *val)
void	apr_table_add (apr_table_t t, const char key, const char *val)
void	apr_table_addn (apr_table_t t, const char key, const char *val)
apr_table_t *	apr_table_overlay (apr_pool_t p, const apr_table_t overlay, const apr_table_t *base)
int	apr_table_do (apr_table_do_callback_fn_t comp, void rec, const apr_table_t *t,...)
int	apr_table_vdo (apr_table_do_callback_fn_t comp, void rec, const apr_table_t *t, va_list vp)
void	apr_table_overlap (apr_table_t a, const apr_table_t b, unsigned flags)
void	apr_table_compress (apr_table_t *t, unsigned flags)

Table and Array Functions [Apache Portability Runtime library]

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation

Table and Array Functions
[Apache Portability Runtime library]