The Basic Idea

Basically, a table is an object which maps strings to almost arbitrary user-defined data. (If you know Perl, a table is very much like a Perl hash table. Alternatively, if you know Unix shells, a table is like the set of all environment variables. As yet another analogy, if you know Awk, a table is like an Awk associative array.)^part171

More formally, a table is an object which stores a set of keys and a corresponding set of values. We refer to a (key,value) pair as a table entry.

Keys are C-style null-terminated character strings, with the slash character `/' reserved for future expansion.^part172

Values are 1-dimensional arrays of any of the usual Cactus data types described in Section B10.8. A string can be stored by treating it as a 1-dimensional array of CCTK_CHAR (there's an example of this below).

The basic ``life cycle'' of a table looks like this:

1. Some code creates it with Util_TableCreate() or Util_TableClone().
2. Some code (often the same piece of code, but maybe some other piece) sets entries in it using one or more of the Util_TableSet*(), Util_TableSet*Array(), Util_TableSetGeneric(), Util_TableSetGenericArray(), and/or Util_TableSetString() functions.
3. Some other piece or pieces of code can get (copies of) the values which were set, using one or more of the Util_TableGet*(), Util_TableGet*Array(), Util_TableGetGeneric(), Util_TableGetGenericArray(), and/or Util_TableGetString() functions.
4. When everyone is through with a table, some (single) piece of code should destroy it with Util_TableDestroy().

There are also convenience functions Util_TableSetFromString() to set entries in a table based on a parameter-file-style string, and Util_TableCreateFromString() to create a table and then set entries in it based on a parameter-file-style string.

As well, there are ``table iterator'' functions Util_TableIt*() to allow manipulation of a table even if you don't know its keys.

A table has an integer ``flags word'' which may be used to specify various options, via bit flags defined in util_Table.h. For example, the flags word can be used to control whether keys should be compared as case sensitive or case insensitive strings. See the detailed function description of Util_TableCreate() in the Reference Manual for a list of the possible bit flags and their semantics.