Loading...
Searching...
No Matches
Table and Array Functions
Apache Portability Runtime library
Collaboration diagram for Table and Array Functions:

## Data Structures

struct | apr_array_header_t
struct | apr_table_entry_t

## Macros

#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)
#define | APR_OVERLAP_TABLES_ADD (2)

## 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 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_clear (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)
apr_table_t * | apr_table_clone (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)
const char * | apr_table_getm (apr_pool_t *p, 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)

## 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.

## Macro Definition Documentation

## APR_ARRAY_IDX

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

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

Parameters

  ary | the array
  i | the index into the array to return
  type | the type of the objects stored in the array

Returns
  the item at index i

## APR_ARRAY_PUSH

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

A helper macro for pushing elements into an APR array.

Parameters

  ary | the array
  type | the type of the objects stored in the array

Returns
  the location where the new object should be placed

## APR_OVERLAP_TABLES_ADD

#define APR_OVERLAP_TABLES_ADD (2)

flag for overlap to use apr_table_addn

## APR_OVERLAP_TABLES_MERGE

#define APR_OVERLAP_TABLES_MERGE (1)

flag for overlap to use apr_table_mergen

## APR_OVERLAP_TABLES_SET

#define APR_OVERLAP_TABLES_SET (0)

flag for overlap to use apr_table_setn

## Typedef Documentation

## apr_array_header_t

typedef struct apr_array_header_t apr_array_header_t

See also
  apr_array_header_t

## apr_table_do_callback_fn_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.

See also
  apr_table_do
  apr_table_vdo

## apr_table_entry_t

typedef struct apr_table_entry_t apr_table_entry_t

The (opaque) structure for string-content tables.

## apr_table_t

typedef struct apr_table_t apr_table_t

the table abstract data type

## Function Documentation

## apr_array_append()

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.

## apr_array_cat()

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_clear()

void apr_array_clear | ( | apr_array_header_t * | arr | ) |

Remove all elements from an array.

Parameters

  arr | The 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.

## apr_array_copy()

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_copy_hdr()

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_make()

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

## apr_array_pop()

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.

## apr_array_pstrcat()

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

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

  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.

## apr_array_push()

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.

## apr_is_empty_array()

int apr_is_empty_array | ( | const apr_array_header_t * | a | ) |

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

Parameters

  a | The array to check

Returns
  True if empty, False otherwise

## apr_is_empty_table()

int apr_is_empty_table | ( | const apr_table_t * | t | ) |

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

Parameters

  t | The table to check

Returns
  True if empty, False otherwise

## apr_table_add()

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.

## apr_table_addn()

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.

## apr_table_clear()

void apr_table_clear | ( | apr_table_t * | t | ) |

Delete all of the elements from a table.

Parameters

  t | The table to clear

## apr_table_clone()

apr_table_t * apr_table_clone | ( | apr_pool_t * | p,
|  | const apr_table_t * | t
| ) |  |

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

  p | The pool to allocate the new table out of
  t | The table to clone

Returns
  A deep copy of the table passed in

## apr_table_compress()

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, or APR_OVERLAP_TABLES_ADD to add

Remarks
  When merging duplicates, the two values are concatenated, separated by the string ", ".

## apr_table_copy()

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

Warning
  The table keys and respective values are not copied

## apr_table_do()

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. The varargs array must be a list of zero or more (char *) keys followed by a NULL pointer. If zero keys are given, the `comp` function 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 `comp` function returns zero, iteration will continue using the next specified key, if any.

Parameters

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

## apr_table_elts()

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

## apr_table_get()

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 (case does not matter)

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

## apr_table_getm()

const char * apr_table_getm | ( | apr_pool_t * | p,
|  | const apr_table_t * | t,
|  | const char * | key
| ) |  |

Get values associated with a given key from the table. If more than one value exists, return a comma separated list of values. After this call, the data is still in the table.

Parameters

  p | The pool to allocate the combined value from, if necessary
  t | The table to search for the key
  key | The key to search for (case does not matter)

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

## apr_table_make()

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

## apr_table_merge()

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. The merging is done by concatenating the two values, separated by the string ", ".

Parameters

  t | The table to search for the data
  key | The key to merge data for (case does not matter)
  val | The data to add

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

## apr_table_mergen()

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. The merging is done by concatenating the two values, separated by the string ", ".

Parameters

  t | The table to search for the data
  key | The key to merge data for (case does not matter)
  val | The data to add

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

## apr_table_overlap()

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

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

  a | The table to add the data to.
  b | The table to iterate over, adding its data to table a
  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 APR_OVERLAP_TABLES_ADD Use apr_table_addn

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 if (flags & APR_OVERLAP_TABLES_ADD) {
             apr_table_addn(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_overlay()

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

## apr_table_set()

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 overwrite the old data.

Parameters

  t | The table to add the data to.
  key | The key to use (case does not matter)
  val | The value to add

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

## apr_table_setn()

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 overwrite the old data.

Parameters

  t | The table to add the data to.
  key | The key to use (case does not matter)
  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..

## apr_table_unset()

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 (case does not matter)

## apr_table_vdo()

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. The `vp` varargs parameter must be a list of zero or more (char *) keys followed by a NULL pointer. If zero keys are given, the `comp` function 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 `comp` function returns zero, iteration will continue using the next specified key, if any.

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 | List 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
  apr_table_do