GME  13
Classes | Defines | Typedefs | Functions | Variables
Table and Array Functions

Classes

struct  apr_array_header_t
struct  apr_table_entry_t

Defines

#define APR_ARRAY_IDX(ary, i, type)   (((type *)(ary)->elts)[i])
#define APR_ARRAY_PUSH(ary, type)   (*((type *)apr_array_push(ary)))
#define APR_OVERLAP_TABLES_SET   (0)
#define APR_OVERLAP_TABLES_MERGE   (1)

Typedefs

typedef struct apr_table_t apr_table_t
typedef struct apr_array_header_t apr_array_header_t
typedef struct apr_table_entry_t apr_table_entry_t
typedef intapr_table_do_callback_fn_t )(void *rec, const char *key, const char *value)

Functions

 APR_DECLARE (const apr_array_header_t *) apr_table_elts(const apr_table_t *t)
 APR_DECLARE (int) apr_is_empty_table(const apr_table_t *t)
 APR_DECLARE (apr_array_header_t *) apr_array_make(apr_pool_t *p
 APR_DECLARE (void *) apr_array_push(apr_array_header_t *arr)
 APR_DECLARE (void) apr_array_clear(apr_array_header_t *arr)
 APR_DECLARE (char *) apr_array_pstrcat(apr_pool_t *p
 APR_DECLARE (apr_table_t *) apr_table_make(apr_pool_t *p
 APR_DECLARE (const char *) apr_table_get(const apr_table_t *t
 APR_DECLARE_NONSTD (int) apr_table_do(apr_table_do_callback_fn_t *comp

Variables

int nelts
int int elt_size
const apr_array_header_tsrc
const apr_array_header_tarr
const apr_array_header_tfirst
const apr_array_header_t const
apr_array_header_t
second
const apr_array_header_t const char sep
const apr_table_tt
const char * key
const char const char * val
const apr_table_toverlay
const apr_table_t const
apr_table_t
base
void * rec
void const apr_table_t void
const apr_table_t va_list 
vp
const apr_table_tb
const apr_table_t unsigned flags

Detailed Description

Arrays are used to store data which is referenced sequentially or as a stack. Functions are provided to push and pop individual elements as well as to operate on the entire array.

Tables are used to store data which can be referenced by key. Limited capabilities are provided for tables with multiple elements which share a key; while key lookup will return only a single element, iteration is available. Additionally, a table can be compressed to resolve duplicates.

Both arrays and tables may store string or binary data; some features, such as concatenation or merging of elements, work only for string data.


Define Documentation

#define APR_ARRAY_IDX (   ary,
  i,
  type 
)    (((type *)(ary)->elts)[i])

A helper macro for accessing a member of an APR array.

Parameters:
arythe array
ithe index into the array to return
typethe type of the objects stored in the array
Returns:
the item at index i

Definition at line 141 of file apr_tables.h.

#define APR_ARRAY_PUSH (   ary,
  type 
)    (*((type *)apr_array_push(ary)))

A helper macro for pushing elements into an APR array.

Parameters:
arythe array
typethe type of the objects stored in the array
Returns:
the location where the new object should be placed

Definition at line 150 of file apr_tables.h.

#define APR_OVERLAP_TABLES_MERGE   (1)

flag for overlap to use apr_table_mergen

Definition at line 426 of file apr_tables.h.

#define APR_OVERLAP_TABLES_SET   (0)

flag for overlap to use apr_table_setn

Definition at line 424 of file apr_tables.h.


Typedef Documentation

See also:
apr_array_header_t

Definition at line 59 of file apr_tables.h.

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:
recThe data passed as the first argument to apr_table_[v]do()
keyThe key from this iteration of the table
valueThe 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.

Definition at line 372 of file apr_tables.h.

The (opaque) structure for string-content tables.

Definition at line 78 of file apr_tables.h.

typedef struct apr_table_t apr_table_t

the table abstract data type

Definition at line 56 of file apr_tables.h.


Function Documentation

APR_DECLARE ( const apr_array_header_t ) const

Get the elements from a table.

Parameters:
tThe table
Returns:
An array containing the contents of the table
APR_DECLARE ( int  ) const

Determine if the table is empty (either NULL or having no elements).

Parameters:
tThe table to check
Returns:
True if empty, False otherwise

Determine if the array is empty (either NULL or having no elements).

Parameters:
aThe array to check
Returns:
True if empty, False otherwise

Iterate over a table running the provided function once for every element in the table. The

Parameters:
vpvarargs parameter must be a list of zero or more (char *) keys followed by a NULL pointer. If zero keys are given, the
compfunction will be invoked for every element in the table. Otherwise, the function is invoked only for those elements matching the keys specified.

If an invocation of the

Parameters:
compfunction returns zero, iteration will continue using the next specified key, if any.
compThe function to run
recThe data to pass as the first argument to the function
tThe table to iterate over
vpList of zero or more (char *) keys followed by NULL
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

Create an array.

Parameters:
pThe pool to allocate the memory out of
neltsthe number of elements in the initial array
elt_sizeThe size of each element in the array.
Returns:
The new array

Copy the entire array.

Parameters:
pThe pool to allocate the copy of the array out of
arrThe 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.

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:
pThe pool to allocate the copy of the array out of
arrThe array to copy
Returns:
An exact copy of the array passed in
Remarks:
The alternate apr_array_copy copies the *entire* array.

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

Parameters:
pThe pool to allocate the new array out of
firstThe array to put first in the new array.
secondThe array to put second in the new array.
Returns:
A new array containing the data from the two arrays passed in.
APR_DECLARE ( void *  )

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

Parameters:
arrThe 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.

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

Parameters:
arrThe 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.

Look up the value associated with a key in a hash table.

Parameters:
htThe hash table
keyPointer to the key
klenLength of the key. Can be APR_HASH_KEY_STRING to use the string length.
Returns:
Returns NULL if the key is not present.

Allocate a block of memory from a pool

Parameters:
pThe pool to allocate from
sizeThe amount of memory to allocate
Returns:
The allocated memory

Debug version of apr_palloc

Parameters:
pSee: apr_palloc
sizeSee: apr_palloc
file_lineWhere the function is called from. This is usually APR_POOL__FILE_LINE__.
Returns:
See: apr_palloc

Debug version of apr_pcalloc

Parameters:
pSee: apr_pcalloc
sizeSee: apr_pcalloc
file_lineWhere the function is called from. This is usually APR_POOL__FILE_LINE__.
Returns:
See: apr_pcalloc

Duplicate a block of memory.

Parameters:
pThe pool to allocate from
mThe memory to duplicate
nThe number of bytes to duplicate
Returns:
The new block of memory
APR_DECLARE ( void  )

Remove all elements from an array.

Parameters:
arrThe array to remove all elements from.
Remarks:
As the underlying storage is allocated from a pool, no memory is freed by this operation, but is available for reuse.

Concatenate two arrays together.

Parameters:
dstThe destination array, and the one to go first in the combined array
srcThe source array to add to the destination array

Delete all of the elements from a table.

Parameters:
tThe table to clear

Add a key/value pair to a table. If another element already exists with the same key, this will overwrite the old data.

Parameters:
tThe table to add the data to.
keyThe key to use (case does not matter)
valThe value to add
Remarks:
When adding data, this function makes a copy of both the key and the value.

Add a key/value pair to a table. If another element already exists with the same key, this will overwrite the old data.

Parameters:
tThe table to add the data to.
keyThe key to use (case does not matter)
valThe 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..

Remove data from the table.

Parameters:
tThe table to remove data from
keyThe key of the data being removed (case does not matter)

Add data to a table by merging the value with data that has already been stored. The merging is done by concatenating the two values, separated by the string ", ".

Parameters:
tThe table to search for the data
keyThe key to merge data for (case does not matter)
valThe data to add
Remarks:
If the key is not found, then this function acts like apr_table_add

Add data to a table by merging the value with data that has already been stored. The merging is done by concatenating the two values, separated by the string ", ".

Parameters:
tThe table to search for the data
keyThe key to merge data for (case does not matter)
valThe data to add
Remarks:
If the key is not found, then this function acts like apr_table_addn

Add data to a table, regardless of whether there is another element with the same key.

Parameters:
tThe table to add to
keyThe key to use
valThe value to add.
Remarks:
When adding data, this function makes a copy of both the key and the value.

Add data to a table, regardless of whether there is another element with the same key.

Parameters:
tThe table to add to
keyThe key to use
valThe 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.

For each element in table b, either use setn or mergen to add the data to table a. Which method is used is determined by the flags passed in.

Parameters:
aThe table to add the data to.
bThe table to iterate over, adding its data to table a
flagsHow 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
Remarks:
When merging duplicates, the two values are concatenated, separated by the string ", ".
This function is highly optimized, and uses less memory and CPU cycles than a function that just loops through table b calling other functions. 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.

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

Parameters:
tTable.
flagsAPR_OVERLAP_TABLES_MERGE to merge, or APR_OVERLAP_TABLES_SET to overwrite
Remarks:
When merging duplicates, the two values are concatenated, separated by the string ", ".
APR_DECLARE ( char *  )

Generate 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:
pThe pool to allocate the string out of
arrThe array to generate the string from
sepThe separator to use
Returns:
A string containing all of the data in the array.

Make a new table.

Parameters:
pThe pool to allocate the pool out of
neltsThe number of elements in the initial table.
Returns:
The new table.
Warning:
This table can only store text data

Create a new table and copy another table into it.

Parameters:
pThe pool to allocate the new table out of
tThe table to copy
Returns:
A copy of the table passed in
Warning:
The table keys and respective values are not copied

Create a new table whose contents are deep copied from the given table. A deep copy operation copies all fields, and makes copies of dynamically allocated memory pointed to by the fields.

Parameters:
pThe pool to allocate the new table out of
tThe table to clone
Returns:
A deep copy of the table passed in

Merge two tables into one new table.

Parameters:
pThe pool to use for the new table
overlayThe first table to put in the new table
baseThe table to add at the end of the new table
Returns:
A new table containing all of the data from the two passed in
APR_DECLARE ( const char *  ) const

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

Parameters:
tThe table to search for the key
keyThe key to search for (case does not matter)
Returns:
The value associated with the key, or NULL if the key does not exist.

Iterate over a table running the provided function once for every element in the table. The varargs array must be a list of zero or more (char *) keys followed by a NULL pointer. If zero keys are given, the

Parameters:
compfunction will be invoked for every element in the table. Otherwise, the function is invoked only for those elements matching the keys specified.

If an invocation of the

Parameters:
compfunction returns zero, iteration will continue using the next specified key, if any.
compThe function to run
recThe data to pass as the first argument to the function
tThe table to iterate over
...A varargs array of zero or more (char *) keys followed by NULL
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

Variable Documentation

Definition at line 187 of file apr_tables.h.

const apr_table_t* b

Definition at line 466 of file apr_tables.h.

Definition at line 359 of file apr_tables.h.

Definition at line 122 of file apr_tables.h.

Definition at line 207 of file apr_tables.h.

unsigned flags

Definition at line 466 of file apr_tables.h.

const char* key

Definition at line 268 of file apr_tables.h.

Definition at line 122 of file apr_tables.h.

Definition at line 359 of file apr_tables.h.

void const apr_table_t void* rec

Definition at line 395 of file apr_tables.h.

Definition at line 207 of file apr_tables.h.

const apr_array_header_t const char sep

Definition at line 222 of file apr_tables.h.

Definition at line 175 of file apr_tables.h.

void const apr_table_t void const apr_table_t* t

Definition at line 242 of file apr_tables.h.

const char const char* val

Definition at line 279 of file apr_tables.h.

void const apr_table_t void const apr_table_t va_list vp

Definition at line 421 of file apr_tables.h.