The APR table, like the APR itself, permeates Apache, and you see it used frequently in Apache API. Apache represents its headers as APR tables, for example. The APR table is somewhat of a unique data structure in that it is capable of working as both hashtable and array.
Table B.5, “APR Table Methods” contains the exhaustive list of methods, in alphabetical order. The documentation of each method follows.
[] is a lookup operator. It returns the value
associated with a key which is passed in the as the argument. Internally, this
function calls apr_table_get().
key: the key value.
[]= is an assignment operator. It assigns a value for
the given key argument. If another value exists for this key, it will be
overwritten. Internally, this function calls
apr_table_set().
key: the key value
add() is a non-destructive assigment operator. That
is, if there is already a value associated with the given key,
add() will keep it in place and add the new value. In
this case, there are multiple values associated with a single key.
def add(key, value)
key: the key value
value: the value corresponding to key
clear() deletes all of the elements from a
table. Internally is calls apr_table_clear().
each() is an iterator function which passes the
key/value pair of each element into the block.
get() retrieves the value corresponding to the key
provided as the argument. It is another form of the []
operator, and is included in order to be consistent with the APR table API.
def get(key)
key: the key value.
has_key?() returns true if the
table has at least one value associated with the given key.
def has_key?(key)
key: the key value.
initialize() is the constructor. It takes an APR pool
object from which to allocate its memory. This allows you to optionally control
the memory management, potentially consoidating multiple tables out of the same
pool.
For processing requests, you will rarely if ever need to create APR
tables, as all of the tables in the API will already be created for you. If and
when you do need to create a table, you can use either a new
Pool object, or better yet one of the existing pools
associated with the Request,
Connection, or Server objects.
def initialize(pool)
pool: APR pool object to associate with
table.
join() returns a string containing equality pairs for
each element in the table, delimited by the value provided as the argument.
def join(sep)
separator: delimiter
keys() returns a Ruby Array containing all keys in
the table.
merge() adds a key/value pair to the table. What
makes merge different is how it handles collisions. If there is already a value
present for the given key, merge() will string
concatenate the new value onto the present value, after adding a comma.
For example, if the table contains the value "bar" for
key "foo", and you call merge("foo",
"baz"), then the new value associated with "foo"
will be "bar, baz".
def merge(key, value)
key: the key value
value: the value corresponding to
key
set() assigns a key/value pair to the table. If there
is a value in the table corresponding to key, then it will be
overwritten. set() is another form of the
[]= operator, and is included in order to be consistent with
the APR table API.
def set(key, value)
key: the key value
value: the value corresponding to
key
size() returns the number of elements in the table.
unset() removes all values associated with the given
key.
def unset(key, value)
key: the key value.
values() returns a Ruby Array containing all values in
the table.