[prev] [prev-tail] [tail] [up]

Chapter B4
Full Descriptions of Table Functions

Util_TableClone

Creates a new table which is a “clone” (exact copy) of an existing table

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int clone_handle = Util_TableClone(int handle);


Fortran
call Util_TableClone(clone_handle, handle)  
integer clone_handle, handle


Result

clone_handle (≥ 0) A handle to the clone table

Parameters

handle Handle to the table to be cloned

Discussion

Viewing a table as a set of key/value pairs, this function creates a new table (with the same flags word as the original) containing copies of all the original table’s key/value pairs. The two tables are completely independent, i.e. future changes to one won’t affect the other.

Note that if there are any CCTK_POINTER and/or CCTK_FPOINTER values in the table, they are “shallow copied”, i.e. the (pointer) values in the table are copied. This results in the clone table’s pointer values pointing to the same places as the original table’s pointer values. Be careful with this! In particular, if you’re using pointer values in the table to keep track of malloc() memory, be careful not to free() the same block of memory twice!

Note that table iterators are not guaranteed to sequence through the original and clone tables in the same order. (This is a special case of the more general “non-guarantee” in the Section of table iterators in the Users’ Guide: the order of table iterators may differ even between different tables with identical key/value contents.)

See Also

Util_TableCreate() [B57] create a table
Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableDestroy() [B67] destroy a table

Errors

UTIL_ERROR_NO_MEMORY unable to allocate memory
UTIL_ERROR_TABLE_BAD_FLAGS flags word is negative in the to-be-cloned table (this indicates an internal error in the table routines, and should never happen)

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
/*  
 * This function is passed (a handle to) a table containing some entries.  
 * It needs to set some additional entries and pass the table to some  
 * other function(s), but it also needs to leave the original table  
 * intact for other use by the caller.  The solution is to clone the  
 * original table and work on the clone, leaving the original table  
 * unchanged.  
 */  
int my_function(int handle, int x, int y)  
{  
int status;  
 
/* clone the table */  
const int clone_handle = Util_TableClone(handle)  
if (clone_handle < 0)  
        return clone_handle;               /* error in cloning table */  
 
/* now set our entries in the clone table */  
status = Util_TableSetInt(clone_handle, x, "x");  
if (status < 0)  
        return status;                     /* error in setting x */  
status = Util_TableSetInt(clone_handle, y, "y");  
if (status < 0)  
        return status;                     /* error in setting y */  
 
/* ... code to use the clone table ... */  
/* ... eg pass clone_handle to other functions ... */  
 
/* we’re done with the clone now */  
Util_TableDestroy(clone_handle);  
return 0;  
}


Util_TableCreate

Creates a new (empty) table

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int handle = Util_TableCreate(int flags);


Fortran
call Util_TableCreate(handle, flags)  
integer handle, flags


Result

handle (≥ 0) A handle to the newly-created table

Parameters

flags (≥ 0) A flags word for the table. This should be the inclusive-or of zero or more of the UTIL_TABLE_FLAGS_* bit masks (defined in "util_Table.h"). For Fortran users, note that inclusive-or is the same as sum here, since the bit masks are all disjoint.

Discussion

We require the flags word to be non-negative so that other functions can distinguish flags from (negative) error codes.

Any User-defined flag words should use only bit positions at or above
UTIL_TABLE_FLAGS_USER_DEFINED_BASE, i.e. all bit positions below this are reserved for present of future Cactus use.

At present there is only a single flags-word bit mask defined in "util_Table.h":

UTIL_TABLE_FLAGS_CASE_INSENSITIVE

By default keys are treated as C-style character strings, and the table functions compare them with the standard C strcmp function. However, by setting the
UTIL_TABLE_FLAGS_CASE_INSENSITIVE bit in the flags word, this table’s keys may be made case-insensitive, i.e. the table routines then compare this table’s keys with Util_StrCmpi(). Note that keys are still stored exactly as the caller specifies them (i.e. they are not forced into a canonical case); it’s only their comparison that’s affected by this flag.

See Also

Util_StrCmpi() [B27] compare two strings, ignoring upper/lower case
Util_TableClone() [B52] create a new table which is a “clone” (exact copy) of an existing table
Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableDestroy() [B67] destroy a table

Errors

UTIL_ERROR_NO_MEMORY unable to allocate memory
UTIL_ERROR_TABLE_BAD_FLAGS flags word is negative

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
/* create a table, simplest case */  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
/* create a table whose keys will be treated as case-insensitive */  
int handle2 = Util_TableCreate(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);


Util_TableCreateFromString

Creates a new table (with the case-insensitive flag set) and sets values in it based on a string argument (interpreted with “parameter-file” semantics)

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int handle = Util_TableCreateFromString(const char *string);


Fortran
call Util_TableCreateFromString(handle, string)  
integer       handle  
character*(*) string


Result

handle (≥ 0) a handle to the newly-created table

Parameters

string a pointer to a C-style null-terminated string specifying the table contents; see the description for Util_TableSetFromString() for a full description of the syntax and semantics of this string

See Also

Util_TableClone() [B52] Create a new table which is a “clone” (exact copy) of an existing table
Util_TableCreate() [B57] create a table
Util_TableSetFromString() [B139] sets values in a table based on a string argument

Errors

UTIL_ERROR_NO_MEMORY unable to allocate memory
UTIL_ERROR_BAD_KEY invalid input: key contains invalid character
UTIL_ERROR_BAD_INPUT invalid input: can’t parse input string
other error codes this function may also return any error codes returned by Util_TableCreate() or Util_TableSetFromString()

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
int handle = Util_TableCreateFromString("order = 3\t"  
                                        "myreal = 42.314159\t"  
                                        "mystring = ’hello’\t"  
                                        "myarray = { 0 1 2 3 }");  
 
/* equivalent code to the above */  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);  
Util_TableSetFromString(handle, "order = 3\t"  
                                "myreal = 42.314159\t"  
                                "mystring = ’hello’"  
                                "myarray = { 0 1 2 3 }");  
 
/* also equivalent to the above */  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);  
CCTK_INT array[] = {0, 1, 2, 3};  
 
Util_TableSetInt(handle, 3, "order");  
Util_TableSetReal(handle, 42.314159, "myreal");  
Util_TableSetString(handle, "hello", "mystring");  
Util_TableSetIntArray(handle, 4, array, "myarray");


Util_TableDeleteKey

Deletes a specified key/value entry from a table

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int key_exists = Util_TableDeleteKey(int handle, const char *key);


Fortran
call Util_TableDeleteKey(key_exists, handle, key)  
integer        key_exists, handle  
character*(*)  key


Result

0 ok (key existed before this call, and has now been deleted)

Parameters

handle (≥ 0) handle to the table
key a pointer to the key (a C-style null-terminated string)

Discussion

This function invalidates any iterators for the table which are not in the “null-pointer” state.

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_TABLE_NO_SUCH_KEY no such key in table

Util_TableDestroy

Destroys a table

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableDestroy(int handle);


Fortran
call Util_TableDestroy(status, handle)  
integer status, handle


Result

0 ok

Parameters

handle (≥ 0) handle to the table

Discussion

Of course, this function invalidates any and all iterators for the table. :)

See Also

Util_TableClone() [B52] Create a new table which is a “clone” (exact copy) of an existing table
Util_TableCreate() [B57] create a table
Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
/* create a table */  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
/* do things with the table: put values in it, */  
/* pass its handle to other functions, etc etc */  
/* ... */  
 
/* at this point we (and all other functions we */  
/* may call in the future) are done with the table */  
Util_TableDestroy(handle);


Util_TableGet*

This is a family of functions, one for each Cactus data type, to get the single (1-element array) value, or more generally the first array element of the value, associated with a specified key in a key/value table.

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int N_elements = Util_TableGetXxx(int handle,  
                                  CCTK_XXX *value,  
                                  const char *key);

where XXX is one of POINTER, FPOINTER1, CHAR, BYTE, INT, INT1, INT2, INT4, INT8, REAL, REAL4, REAL8, REAL16, COMPLEX, COMPLEX8, COMPLEX16, COMPLEX32 (not all of these may be supported on any given system)


Fortran
call Util_TableGetXxx(N_elements, handle, value, key)  
integer        N_elements, handle  
CCTK_XXX       value  
character*(*)  key

where CCTK_XXX may be any data type supported by C (above) except CCTK_CHAR (Fortran doesn’t have a separate “character” data type; use CCTK_BYTE instead)


Result

N_elements the number of array elements in the value

Parameters

handle (≥ 0) handle to the table
value a pointer to where this function should store a copy of the value (or more generally the first array element of the value) associated with the specified key, or NULL pointer to skip storing this
key a pointer to the key (a C-style null-terminated string)

Discussion

Note that it is not an error for the value to actually have > 1 array elements; in this case only the first element is stored. The rationale for this design is that the caller may know or suspect that the value is a large array, but may only want the first array element; in this case this design avoids the caller having to allocate a large buffer unnecessarily.

In contrast, it is an error for the value to actually be an empty (0-length) array, because then there is no “first array element” to get.

It is also an error for the value to actually have a different type than CCTK_XXX.

If any error code is returned, the user’s value buffer (pointed to by value if this is non-NULL) is unchanged.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*Array() get an array value
Util_TableGetString() [B87] get a character-string value
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_TABLE_NO_SUCH_KEY no such key in table
UTIL_ERROR_TABLE_WRONG_DATA_TYPE value has data type other than CCTK_TYPE
UTIL_ERROR_TABLE_VALUE_IS_EMPTY value is an empty (0-element) array

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
#define N_DIGITS        5  
static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979};  
 
int N;  
CCTK_INT x;  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi");  
Util_TableSetIntArray(handle, 0, pi_digits, "empty array");  
 
/* gets N = 5, x = 3 */  
N = Util_TableGetInt(handle, &x, "digits of pi");  
 
/* gets N = UTIL_ERROR_TABLE_VALUE_IS_EMPTY */  
N = Util_TableGetInt(handle, &x, "empty array");


Util_TableGet*Array

This is a family of functions, one for each Cactus data type, to get a copy of the value associated with a specified key, and store it (more accurately, as much of it as will fit) in a specified array

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int N_elements = Util_TableGetXxxArray(int handle,  
                                       int N_array, CCTK_XXX array[],  
                                       const char *key);

where XXX is one of POINTER, FPOINTER2, CHAR, BYTE, INT, INT1, INT2, INT4, INT8, REAL, REAL4, REAL8, REAL16, COMPLEX, COMPLEX8, COMPLEX16, COMPLEX32 (not all of these may be supported on any given system)


Fortran
call Util_TableGetXxxArray(N_elements, handle, N_array, array, key)  
integer        N_elements, handle, N_array  
CCTK_XXX(*)    array  
character*(*)  key

where CCTK_XXX may be any data type supported by C (above)


Result

N_elements the number of array elements in the value

Parameters

handle (≥ 0) handle to the table
N_array the number of array elements in array[] (must be ≥ 0 if array != NULL)
array a pointer to where this function should store (up to N_array elements of) a copy of the value associated with the specified key, or NULL pointer to skip storing this
key a pointer to the key (a C-style null-terminated string)

Discussion

Note that it is not an error for the value to actually have > N_array array elements; in this case only the first N_array elements are stored. The caller can detect this by comparing the return value with N_array. The rationale for this design is that the caller may know or suspect that the value is a large array, but may only want the first few array elements; in this case this design avoids the caller having to allocate a large buffer unnecessarily.

It is also not an error for the value to actually have < N_array array elements; again the caller can detect this by comparing the return value with N_array.

It is an error for the value to actually have a different type than CCTK_XXX.

If any error code is returned, the user’s value buffer (pointed to by array if this is non-NULL) is unchanged.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_BAD_INPUT array != NULL and N_array < 0
UTIL_ERROR_TABLE_NO_SUCH_KEY no such key in table
UTIL_ERROR_TABLE_WRONG_DATA_TYPE value has data type other than CCTK_TYPE

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
#define N_STUFF         3  
static const CCTK_REAL stuff[N_STUFF] = {42.0, 69.0, 105.5};  
 
#define N_OUTPUT        2  
CCTK_INT output[N_OUTPUT];  
 
int N;  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetRealArray(handle, N_STUFF, stuff, "blah blah blah");  
 
/* gets N = 3, output[0] = 42.0, output[1] = 69.0 */  
N = Util_TableGetRealArray(handle, N_OUTPUT, output, "blah blah blah");


Util_TableGetGeneric

Get the single (1-element array) value, or more generally the first array element of the value, associated with a specified key in a key/value table; the value’s data type is generic. That is, the value is specified by a CCTK_VARIABLE_* type code and a void * pointer.

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int N_elements = Util_TableGetGeneric(int handle,  
                                      int type_code,  
                                      void *value,  
                                      const char *key);


Fortran
call Util_TableGetGeneric(N_elements, handle, type_code, value, key)  
integer        N_elements, handle, type_code  
CCTK_POINTER   value  
character*(*)  key


Result

N_elements the number of array elements in the value

Parameters

handle (≥ 0) handle to the table
type_code the value’s type code (one of the CCTK_VARIABLE_* constants from "cctk_Constants.h")
value a pointer to where this function should store a copy of the value (or more generally the first array element of the value) associated with the specified key, or NULL pointer to skip storing this
key a pointer to the key (a C-style null-terminated string)

Discussion

Note that it is not an error for the value to actually have > 1 array elements; in this case only the first element is stored. The rationale for this design is that the caller may know or suspect that the value is a large array, but may only want the first array element; in this case this design avoids the caller having to allocate a large buffer unnecessarily.

In contrast, it is an error for the value to actually be an empty (0-length) array, because then there is no “first array element” to get.

It is also an error for the value to actually have a different type than that specified by type_code.

If any error code is returned, the user’s value buffer (pointed to by value if this is non-NULL) is unchanged.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value
Util_TableGet*Array() get an array value
Util_TableGetString() [B87] get a character-string value
Util_TableQueryValueInfo() [B121] query key present/absent in table, and optionally type and/or number of elements
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_TABLE_NO_SUCH_KEY no such key in table
UTIL_ERROR_TABLE_WRONG_DATA_TYPE value has data type other than CCTK_TYPE
UTIL_ERROR_TABLE_VALUE_IS_EMPTY value is an empty (0-element) array

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
#include "cctk_Constants.h"  
 
#define N_DIGITS        5  
static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979};  
 
int N;  
CCTK_INT x;  
void *xptr = (void *) &x;  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi");  
Util_TableSetIntArray(handle, 0, pi_digits, "empty array");  
 
/* gets N = 5, x = 3 */  
N = Util_TableGetGeneric(handle, CCTK_VARIABLE_INT, &x, "the answer");  
 
/* gets N = UTIL_ERROR_TABLE_VALUE_IS_EMPTY, leaves x unchanged */  
N = Util_TableGetGeneric(handle, CCTK_VARIABLE_INT, &x, "empty array");


Util_TableGetGenericArray

Get a copy of the value associated with a specified key, and store it (more accurately, as much of it as will fit) in a specified array; the array’s data type is generic. That is the array is specified by a CCTK_VARIABLE_* type code, a count of the number of array elements, and a void * pointer.

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int N_elements = Util_TableGetGenericArray(int handle,  
                                           int type_code,  
                                           int N_array, void *array,  
                                           const char *key);


Fortran
call Util_TableGetGenericArray(N_elements,  
.                              handle,  
.                              type_code,  
.                              N_array, array,  
.                              key)  
integer        N_elements, handle, type_code, N_array  
CCTK_POINTER   array  
character*(*)  key


Result

N_elements the number of array elements in the value

Parameters

handle (≥ 0) handle to the table
type_code the value’s type code (one of the CCTK_VARIABLE_* constants from "cctk_Constants.h")
N_array the number of array elements in array[] (must be ≥ 0 if array != NULL)
array a pointer to where this function should store (up to N_array elements of) a copy of the value associated with the specified key, or NULL pointer to skip storing this
key a pointer to the key (a C-style null-terminated string)

Discussion

Note that it is not an error for the value to actually have > N_array array elements; in this case only the first N_array elements are stored. The caller can detect this by comparing the return value with N_array. The rationale for this design is that the caller may know or suspect that the value is a large array, but may only want the first few array elements; in this case this design avoids the caller having to allocate a large buffer unnecessarily.

It is also not an error for the value to actually have < N_array array elements; again the caller can detect this by comparing the return value with N_array.

It is an error for the value to actually have a different type than that specified by type_code.

If any error code is returned, the user’s value buffer (pointed to by array if this is non-NULL) is unchanged.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableQueryValueInfo() [B121] query key present/absent in table, and optionally type and/or number of elements
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_BAD_INPUT array != NULL and N_array < 0
UTIL_ERROR_TABLE_NO_SUCH_KEY no such key in table
UTIL_ERROR_TABLE_WRONG_DATA_TYPE value has data type other than CCTK_TYPE

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
#define N_STUFF         3  
static const CCTK_REAL stuff[N_STUFF] = {42.0, 69.0, 105.5};  
 
#define N_OUTPUT        2  
CCTK_INT output[N_OUTPUT];  
 
int N;  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetRealArray(handle, N_STUFF, stuff, "stuff");  
 
/* gets N = UTIL_ERROR_TABLE_WRONG_DATA_TYPE, output[] unchanged */  
N = Util_TableGetGenericArray(handle,  
                              CCTK_VARIABLE_INT,  
                              N_OUTPUT, output,  
                              "stuff");  
/* gets N = 3, output[0] = 42.0, output[1] = 69.0 */  
N = Util_TableGetGenericArray(handle,  
                              CCTK_VARIABLE_REAL,  
                              N_OUTPUT, output,  
                              "stuff");


Util_TableGetString

Gets a copy of the character-string value associated with a specified key in a table, and stores it (more accurately, as much of it as will fit) in a specified character string

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int length = Util_TableGetString(int handle,  
                                 int buffer_length, char buffer[],  
                                 const char *key);


Result

Results are the same as all the other Util_TableGet*() functions: length the length of the string (C strlen semantics, i.e. not including the terminating null character)

Parameters

handle (≥ 0) handle to the table
buffer_length the length (sizeof) of buffer[] (must be ≥ 1 if buffer != NULL)
buffer a pointer to a buffer into which this function should store (at most buffer_length-1 characters of) the value, terminated by a null character as usual for C strings, or NULL pointer to skip storing this
key a pointer to the key (a C-style null-terminated string)

Discussion

This function assumes that the string is stored as an array of CCTK_CHARs, not including a terminating null character.

This function differs from Util_TableGetCharArray() in two ways: It explicitly provides a terminating null character for C-style strings, and it explicitly checks for the string being too long to fit in the buffer (in which case it returns UTIL_ERROR_TABLE_STRING_TRUNCATED).

If the error code UTIL_ERROR_TABLE_STRING_TRUNCATED is returned, then the first buffer_length-1 characters of the string are returned in the user’s buffer (assuming buffer is non-NULL), followed by a null character to properly terminate the string in the buffer. If any other error code is returned, the user’s value buffer (pointed to by buffer if this is non-NULL) is unchanged.

To find out how long the string is (and thus how big of a buffer you need to allocate to avoid having the string truncated), you can call this function with buffer_length = 0 and buffer = NULL (or actually anything you want); the return result will give the string length.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGet*Array() get an array value
Util_TableGetCharArray() [B75] get an array-of-CCTK_CHAR value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetString() [B152] set a character-string value
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetCharArray() [B135] set an array-of-CCTK_CHAR value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_BAD_INPUT buffer != NULL and buffer_length ≤ 0
UTIL_ERROR_TABLE_NO_SUCH_KEY no such key in table
UTIL_ERROR_TABLE_WRONG_DATA_TYPE value has data type other than CCTK_CHAR
UTIL_ERROR_TABLE_STRING_TRUNCATED buffer != NULL and value was truncated to fit in buffer[]

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
#define N_BUFFER        100  
char buffer[N_BUFFER];  
 
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
Util_TableSetString(handle, "relativity", "Einstein");  
 
/* get length of string (= 10 here) */  
int length = Util_TableGetString(handle, 0, NULL, "Einstein");  
 
/* get null-terminated string into buffer, also returns 10 */  
Util_TableGetString(handle, N_BUFFER, buffer, "Einstein");


Util_TableItAdvance

Advance a table iterator to the next entry in the table

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int is_nonnull = Util_TableItAdvance(int ihandle);


Result

1 ok (iterator now points to some table entry)
0 ok (iterator has just advanced past the last table entry, and is now in the ”null-pointer” state)

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

If we view an iterator as an abstraction of a pointer into the table, then this function is the abstraction of the C “++” operation applied to the pointer, except that this function automagically sets the iterator to the ”null-pointer” state when it advances past the last table entry.

Note that bad things (garbage results, core dumps) may happen if you call this function on an iterator which has been invalidated by a change in the table’s contents.

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid

Examples

C
/* walk through all entries of a table */  
int ihandle;  
 
        for ( ihandle = Util_TableItCreate(handle) ;  
              Util_TableItQueryIsNonNull(ihandle) > 0 ;  
              Util_TableItAdvance(ihandle) )  
        {  
        /* do something with the table entry */  
        }  
 
Util_TableItDestroy(ihandle);


Util_TableItClone

Creates a new table iterator which is a “clone” (exact copy) of an existing table iterator

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int clone_ihandle = Util_TableItClone(int ihandle);


Result

clone_ihandle (≥ 0) A handle to the clone table iterator

Parameters

ihandle handle to the table iterator to be cloned

Discussion

This function creates a new iterator which points to the same place in the same table as the original iterator. If the original iterator is in the “null-pointer” state, then the clone is also in this state.

Note that bad things (garbage results, core dumps) may happen if you call this function on an iterator which has been invalidated by a change in the table’s contents.

See Also

Util_TableClone() [B52] create a new table which is a “clone” (exact copy) of an existing table
Util_TableItCreate() [B96] create a table iterator
Util_TableItDestroy() [B98] destroy a table iterator

Errors

UTIL_ERROR_BAD_HANDLE iterator handle to be cloned, is invalid
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
/*  
 * Apart from efficiency and slight differences in error return codes,  
 * Util_TableItClone() could be simulated by the following code.  
 */  
int Util_TableItClone(int ihandle)  
{  
int status;  
 
/* to what table does the to-be-cloned iterator point? */  
const int handle = Util_TableQueryTableHandle(ihandle);  
if (handle < 0)  
        return handle;                /* error in querying table handle */  
 
/* create the to-be-cloned iterator */  
/* (pointing into the same table as the original iterator) */  
  {  
const int clone_ihandle = Util_TableItCreate(handle);  
if (clone_ihandle < 0)  
        return clone_ihandle;       /* error in creating clone iterator */  
 
/* how long is the key to which the to-be-cloned iterator points? */  
  {  
const int key_length = Util_TableItQueryKeyValueInfo(ihandle,  
                                                     0, NULL,  
                                                     NULL, NULL);  
if (key_length == UTIL_TABLE_ITERATOR_IS_NULL)  
        {  
        /* to-be-cloned iterator is in "null-pointer" state */  
        Util_TableItSetToNull(clone_ihandle);  
        return clone_ihandle;                          /* normal return */  
        }  
if (key_length < 0)  
        return key_length;   /* error in querying to-be-cloned iterator */  
 
/* to what key does the to-be-cloned iterator point? */  
  {  
const int key_buffer_length = key_length + 1;  
char *const key_buffer = (char *) malloc(key_buffer_length);  
if (key_buffer == NULL)  
        return UTIL_ERROR_NO_MEMORY;  
status = Util_TableItQueryKeyValueInfo(ihandle,  
                                       key_buffer_length, key_buffer);  
if (status < 0)  
        return status;       /* error in querying to-be-cloned iterator */  
 
/* set the clone iterator to point to the same key as the original */  
status = Util_TableItSetToKey(clone_ihandle, key_buffer);  
free(key_buffer);  
return clone_ihandle;                                  /* normal return */  
  }  
  }  
  }  
}


Util_TableItCreate

Create a new table iterator

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int ihandle = Util_TableItCreate(int handle);


Result

ihandle (≥ 0) handle to the table iterator

Parameters

handle (≥ 0) handle to the table over which the iterator should iterate

Discussion

This function creates a new table iterator. The iterator initially points at the starting table entry.

See Also

Util_TableItDestroy() [B98] destroy a table iterator

Errors

UTIL_ERROR_BAD_HANDLE table handle is invalid
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
/* walk through all entries of a table */  
int ihandle;  
 
        for ( ihandle = Util_TableItCreate(handle) ;  
              Util_TableItQueryIsNonNull(ihandle) > 0 ;  
              Util_TableItAdvance(ihandle) )  
        {  
        /* do something with the table entry */  
        }  
 
Util_TableItDestroy(ihandle);


Util_TableItDestroy

Destroy a table iterator

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableItDestroy(int ihandle);


Result

0 ok

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

See Also

Util_TableItCreate() [B96] create a table iterator

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
/* walk through all entries of a table */  
int ihandle;  
 
        for ( ihandle = Util_TableItCreate(handle) ;  
              Util_TableItQueryIsNonNull(ihandle) > 0 ;  
              Util_TableItAdvance(ihandle) )  
        {  
        /* do something with the table entry */  
        }  
 
Util_TableItDestroy(ihandle);


Util_TableItQueryIsNonNull

Query whether a table iterator is not in the “null-pointer” state

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableItQueryIsNonNull(int ihandle);


Result

1 iterator is not in the “null-pointer” state, i.e. iterator points to some table entry
0 iterator is in the “null-pointer” state

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

If no errors occur, Util_TableItQueryIsNonNull(ihandle) is the same as
1 - Util_TableItQueryIsNull(ihandle).

Note that bad things (garbage results, core dumps) may happen if you call this function on an iterator which has been invalidated by a change in the table’s contents.

See Also

Util_TableItQueryIsNull() [B103] query whether a table iterator is in the “null-pointer” state

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid

Examples

C
/* walk through all entries of a table */  
int ihandle;  
 
        for ( ihandle = Util_TableItCreate(handle) ;  
              Util_TableItQueryIsNonNull(ihandle) > 0 ;  
              Util_TableItAdvance(ihandle) )  
        {  
        /* do something with the table entry */  
        }  
 
Util_TableItDestroy(ihandle);


Util_TableItQueryIsNull

Query whether a table iterator is in the “null-pointer” state

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableItQueryIsNull(int ihandle);


Result

1 iterator is in the “null-pointer” state
0 iterator is not in the “null-pointer” state, i.e. iterator points to some table entry

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

If no errors occur, Util_TableItQueryIsNull(ihandle) is the same as 1 - Util_TableItQueryIsNonNull(ihandle).

Note that bad things (garbage results, core dumps) may happen if you call this function on an iterator which has been invalidated by a change in the table’s contents.

See Also

Util_TableItQueryIsNonNull() [B100] query whether a table iterator is not in the “null-pointer” state, i.e. whether the iterator points to some table entry

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid

Examples

C
/* variant code to walk through all entries of a table */  
int ihandle;  
 
        for ( ihandle = Util_TableItCreate(handle) ;  
              Util_TableItQueryIsNull(ihandle) == 0 ;  
              Util_TableItAdvance(ihandle) )  
        {  
        /* do something with the table entry */  
        }  
 
Util_TableItDestroy(ihandle);


Util_TableItQueryKeyValueInfo

Query the key and the type and number of elements of the value corresponding to that key, of the table entry to which an iterator points

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int key_length =  
 Util_TableItQueryKeyValueInfo(int ihandle,  
                               int key_buffer_length, char key_buffer[],  
                               CCTK_INT *type_code, CCTK_INT *N_elements)


Result

key_length The string length of the key (this has C strlen semantics, i.e. it does not include a terminating null character)

Parameters

ihandle (≥ 0) handle to the table iterator
key_buffer_length the length (sizeof) of key_buffer[] (must be ≥ 1 if key_buffer != NULL)
key_buffer a pointer to a buffer into which this function should store (at most key_buffer_length-1 characters of) the key, terminated by a null character as usual for C strings, or NULL pointer to skip storing this
type_code a pointer to where this function should store the value’s type code (one of the CCTK_VARIABLE_* constants from "cctk_Constants.h"), or a NULL pointer to skip storing this.
N_elements a pointer to where this function should store the number of array elements in the value, or a NULL pointer to skip storing this.

Discussion

The usual use of an iterator is to iterate through all the entries of a table, calling this function on each entry, then taking further action based on the results.

Note that bad things (garbage results, core dumps) may happen if you call this function on an iterator which has been invalidated by a change in the table’s contents.

If the error code UTIL_ERROR_TABLE_STRING_TRUNCATED is returned, then the first key_buffer_length-1 characters of the key are returned in the user’s key buffer (assuming key_buffer is non-NULL), followed by a null character to properly terminate the string in the buffer. If any other error code is returned, the user’s key buffer (pointed to by key_buffer if this is non-NULL) is unchanged.

See Also

Util_TableQueryValueInfo() [B121] query key present/absent in table, and optionally type and/or number of elements, but using the key instead of an iterator

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_ITERATOR_IS_NULL iterator is in ”null-pointer” state
UTIL_ERROR_TABLE_STRING_TRUNCATED key_buffer != NULL and key was truncated to fit in key_buffer

Examples

C
/* print out all entries in a table */  
/* return 0 for ok, type code for any types we can’t handle, */  
/*                  -ve for other errors */  
#include <stdio.h>  
#include <stdlib.h>  
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
#include "cctk.h"  
 
int print_table(int handle)  
{  
int max_key_length, N_key_buffer, ihandle;  
char *key_buffer;  
 
max_key_length = Util_TableQueryMaxKeyLength(handle);  
if (max_key_length < 0)  
        return max_key_length;  
 
N_key_buffer = max_key_length + 1;  
key_buffer = (char *) malloc(N_key_buffer);  
if (key_buffer == NULL)  
        return UTIL_ERROR_NO_MEMORY;  
 
        for ( ihandle = Util_TableItCreate(handle) ;  
              Util_TableItQueryIsNonNull(ihandle) > 0 ;  
              Util_TableItAdvance(ihandle) )  
        {  
        CCTK_INT type_code, N_elements;  
        CCTK_INT value_int;  
        CCTK_REAL value_real;  
 
        Util_TableItQueryKeyValueInfo(ihandle,  
                                      N_key_buffer, key_buffer,  
                                      &type_code, &N_elements);  
        printf("key = \"%s\"\n", key_buffer);  
 
        switch  (type_code)  
                {  
        case CCTK_VARIABLE_INT:  
                Util_TableGetInt(handle, &value_int, key_buffer);  
                printf("value[int] = %d\n", (int)value_int);  
                break;  
        case CCTK_VARIABLE_REAL:  
                Util_TableGetReal(handle, &value_real, key_buffer);  
                printf("value[real] = %g\n", (double)value_real);  
                break;  
        default:  
                /* we don’t know how to handle this type */  
                Util_TableItDestroy(ihandle);  
                free(key_buffer);  
                return type_code;  
                }  
        }  
 
Util_TableItDestroy(ihandle);  
free(key_buffer);  
return 0;  
}


Util_TableItQueryTableHandle

Query what table a table iterator iterates over

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int handle = Util_TableItQueryTableHandle(int ihandle);


Result

handle (≥ 0) handle to the table over which the iterator iterates

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

Note that it is always ok to call this function, regardless of whether or not the iterator is in the “null-pointer” state.

It’s also ok to call this function even when the iterator has been invalidated by a change in the table’s contents.

See Also

Util_TableItCreate() [B96] create an iterator (which iterates over a specified table)

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid

Util_TableItResetToStart

Reset a table iterator to point to the starting table entry

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableItResetToStart(int ihandle);


Result

Results are the same as calling Util_TableItQueryIsNonNull() on the iterator after the reset: 1 iterator is not in the “null-pointer” state, i.e. iterator points to some table entry
0 iterator is in the “null-pointer” state (this happens if and only if the table is empty)

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

Note that it is always ok to call this function, regardless of whether or not the iterator is in the “null-pointer” state.

It’s also ok to call this function even when the iterator has been invalidated by a change in the table’s contents.

See Also

Util_TableItSetToNull() [B116] set an iterator to the “null-pointer” state
Util_TableItSetToKey() [B114] set an iterator to point to a specified table entry

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid

Util_TableItSetToKey

Set a table iterator to point to a specified table entry

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableItSetToKey(int ihandle, const char *key);


Result

0 ok

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

This function has the same effect as calling Util_TableItResetToStart() followed by calling Util_TableItAdvance() zero or more times to make the iterator point to the desired table entry. However, this function will typically be (much) more efficient than that sequence.

Note that it is always ok to call this function, regardless of whether or not the iterator is in the “null-pointer” state.

It’s also ok to call this function even when the iterator has been invalidated by a change in the table’s contents.

See Also

Util_TableItResetToStart() [B112] reset an iterator to point to the starting table entry
Util_TableItSetToNull() [B116] set a table iterator to the ”null-pointer” state

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_TABLE_NO_SUCH_KEY no such key in table

Util_TableItSetToNull

Set a table iterator to the ”null-pointer” state

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int handle = Util_TableItSetToNull(int ihandle);


Result

0 ok

Parameters

ihandle (≥ 0) handle to the table iterator

Discussion

Note that it is always ok to call this function, regardless of whether or not the iterator is already in the “null-pointer” state.

It’s also ok to call this function even when the iterator has been invalidated by a change in the table’s contents.

See Also

Util_TableItResetToStart() [B112] reset an iterator to point to the starting table entry
Util_TableItSetToKey() [B114] set an iterator to point to a specified table entry

Errors

UTIL_ERROR_BAD_HANDLE iterator handle is invalid

Util_TableQueryFlags

Query a table’s flags word

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int flags = Util_TableQueryFlags(int handle);


Fortran
call Util_TableQueryFlags(flags, handle)  
integer  flags, handle


Result

flags (≥ 0) the flags word

Parameters

handle (≥ 0) handle to the table

Discussion

See Util_TableCreate() for further discussion of the semantics of flag words.

See Also

Util_TableClone() [B52] create a new table which is a “clone” (exact copy) of an existing table
Util_TableCreate() [B57] create a table (flags word specified explicitly)
Util_TableCreateFromString() [B61] convenience routine to create a table (with certain default flags) and set key/value entries in it based on a parameter-file–like character string

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid

Examples

C
#include <string.h>  
#include "util_ErrorCodes.h"  
#include "util_String.h"  
#include "util_Table.h"  
 
/* compare two strings, doing the comparison with the same */  
/* case-sensitive/insensitive semantics as a certain table uses */  
int compare_strings(int handle, const char *str1, const char *str2)  
{  
int flags = Util_TableQueryFlags(handle);  
return (flags & UTIL_TABLE_FLAGS_CASE_INSENSITIVE)  
       ? Util_StrCmpi(str1, str2)  
       :      strcmp (str1, str2);  
}


Util_TableQueryValueInfo

Query whether or not a specified key is in the table, and optionally the type and/or number of elements of the value corresponding to this key

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int key_exists =  
 Util_TableQueryValueInfo(int handle,  
                          CCTK_INT *type_code, CCTK_INT *N_elements,  
                          const char *key);


Fortran
call Util_TableQueryValueInfo(key_exists,  
.                             handle,  
.                             type_code, N_elements,  
.                             key)  
integer        key_exists, handle  
CCTK_INT       type_code, N_elements  
character*(*)  key


Result

1 ok (key is in table)
0 ok (no such key in table)
(in this case nothing is stored in *type_code and *N_elements)

Parameters

handle (≥ 0) handle to the table
type_code a pointer to where this function should store the value’s type code (one of the CCTK_VARIABLE_* constants from "cctk_Constants.h"), or a NULL pointer to skip storing this.
N_elements a pointer to where this function should store the number of array elements in the value, or a NULL pointer to skip storing this.
key a pointer to the key (a C-style null-terminated string)

Discussion

Unlike all the other table query functions, this function returns 0 for “no such key in table”. The rationale for this design is that by passing NULL pointers for type_code and N_elements, this function is then a Boolean “is key in table?” predicate.

If any error code is returned, the user’s buffers (pointed to by type_code and N_elements if these are non-NULL) are unchanged.

See Also

Util_TableItQueryKeyValueInfo() [B106] query key present/absent in table, and optionally type and/or number of elements, but using an iterator instead of the key

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ‘/’ character

Examples

C
#include <stdio.h>  
#include <assert.h>  
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
static const int data[] = {314, 159, 265};  
#define N_DATA  (sizeof(data) / sizeof(data[0]))  
 
CCTK_INT type_code, N_elements;  
 
/* see whether or not "key" is in table */  
if (Util_TableQueryValueInfo(handle, NULL, NULL, "key"))  
        {  
        /* key is in the table */  
        }  
   else {  
        /* key is not in the table */  
        }  
 
/* put "data" in table as 3-element integer array */  
Util_TableSetIntArray(handle, N_DATA, data, "data");  
 
/* query info about "data" value */  
assert( Util_TableQueryValueInfo(handle,  
                                 &type_code, &N_elements,  
                                 "data") == 1 );  
assert( type_code == CCTK_VARIABLE_INT );  
assert( N_elements == N_DATA );


Util_TableQueryMaxKeyLength

Query the maximum key length in a table

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int max_key_length = Util_TableQueryMaxKeyLength(int handle);


Fortran
call Util_TableQueryMaxKeyLength(max_key_length, handle)  
integer  max_key_length, handle


Result

max_key_length (≥ 0) The string length of the longest key in the table (this has C strlen semantics, i.e. it does not include a terminating null character)

Parameters

handle (≥ 0) handle to the table

Discussion

This function is useful if you’re going to iterate through a table, and you want to allocate a buffer which is guaranteed to be big enough to hold any key in the table.

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid

Examples

C
#include <stdlib.h>  
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
#include "cctk.h"  
 
int max_key_length = Util_TableQueryMaxKeyLength(handle);  
int N_buffer = max_key_length + 1;  
char *const buffer = (char *) malloc(N_buffer);  
if (buffer == NULL)  
        {  
        CCTK_WARN(CCTK_WARN_ABORT, "couldn’t allocate memory for table key buffer!");  
        abort();        /* CCTK_Abort() would be better */  
                        /* if we have a cGH* available */  
        }  
 
/* now buffer is guaranteed to be */  
/* big enough for any key in the table */


Util_TableQueryNKeys

Query the number of key/value entries in a table

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int N_Keys = Util_TableQueryNKeys(int handle);


Fortran
call Util_TableQueryNKeys(N_Keys, handle)  
integer  N_Keys, handle


Result

N_Keys (≥ 0) the number of key/value entries in the table

Parameters

handle (≥ 0) handle to the table

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid

Util_TableSet*

This is a family of functions, one for each Cactus data type, to set the value associated with a specified key to be a specified single (1-element array) value

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableSetXxx(int handle,  
                              CCTK_XXX value,  
                              const char *key);

where XXX is one of POINTER, FPOINTER3, CHAR, BYTE, INT, INT1, INT2, INT4, INT8, REAL, REAL4, REAL8, REAL16, COMPLEX, COMPLEX8, COMPLEX16, COMPLEX32 (not all of these may be supported on any given system)


Fortran
call Util_TableSetXxx(status, handle, value, key)  
integer        status, handle  
CCTK_XXX       value  
character*(*)  key

where CCTK_XXX may be any data type supported by C (above) except CCTK_CHAR (Fortran doesn’t have a separate “character” data type; use CCTK_BYTE instead)


Result

1 ok (key was already in table before this call, old value was replaced)
(it doesn’t matter what the old value’s type_code and N_elements were, i.e. these do not have to match the new value)
0 ok (key was not in table before this call)

Parameters

handle (≥ 0) handle to the table
value the value to be associated with the key
key a pointer to the key (a C-style null-terminated string)

Discussion

The key may be any C character string which does not contain a slash character (’/’).

The value is stored as a 1-element array.

This function invalidates any iterators for the table which are not in the “null-pointer” state.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGet*Array() get an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
#include <math.h>  
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
CCTK_COMPLEX16 z;  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetInt(handle, 42, "the answer");  
Util_TableSetReal(handle, 299792458.0, "speed of light");  
 
z.Re = cos(0.37);       z.Im = sin(0.37);  
Util_TableSetComplex16(handle, z, "my complex number");


Util_TableSet*Array

This is a family of functions, one for each Cactus data type, to set the value associated with a specified key to be a copy of a specified array

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableSetXxxArray(int handle,  
                                   int N_elements,  
                                   const CCTK_XXX array[],  
                                   const char *key);

where XXX is one of POINTER, FPOINTER4, CHAR, BYTE, INT, INT1, INT2, INT4, INT8, REAL, REAL4, REAL8, REAL16, COMPLEX, COMPLEX8, COMPLEX16, COMPLEX32 (not all of these may be supported on any given system)


Fortran
call Util_TableSetXxxArray(status, handle, N_elements, array, key)  
integer        status, handle, N_elements  
CCTK_XXX(*)    array  
character*(*)  key

where CCTK_XXX may be any data type supported by C (above)


Result

1 ok (key was already in table before this call, old value was replaced)
(it doesn’t matter what the old value’s type_code and N_elements were, i.e. these do not have to match the new value)
0 ok (key was not in table before this call)

Parameters

handle (≥ 0) handle to the table
N_elements (≥ 0) the number of array elements in array[]
array a pointer to the array (a copy of which) is to be associated with the key
key a pointer to the key (a C-style null-terminated string)

Discussion

The key may be any C character string which does not contain a slash character (’/’).

Note that empty (0-element) arrays are ok.

This function invalidates any iterators for the table which are not in the “null-pointer” state.

Note that the table makes (stores) a copy of the array you pass in, so it’s somewhat inefficient to store a large array (e.g. a grid function) this way. If this is a problem, consider storing a CCTK_POINTER (pointing to the array) in the table instead. (Of course, this requires that you ensure that the pointed-to data is still valid whenever that CCTK_POINTER is used.)

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGet*Array() get an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableSet*() set a single (1-element array) value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_BAD_INPUT N_elements < 0
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
#define N_DIGITS        5  
static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979};  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi");


Util_TableSetFromString

Sets values in a table based on a string argument, which is interpreted with “parameter-file” semantics

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int count = Util_TableSetFromString(int handle, const char *string);


Fortran
call Util_TableSetFromString(count, handle, string)  
integer        count, handle  
character*(*)  string


Result

count (≥ 0) the number of key/value entries set

Parameters

string a pointer to a C-style null-terminated string specifying the table entries to be set (see below for details on the string contents)

Discussion

The string should contain a sequence of zero or more key=value “assignments”, separated by whitespace. This function processes these assignments in left-to-right order, setting corresponding key/value entries in the table.

The present implementation only recognises integer, real, and character-string values (not complex), and integer and real arrays. To be precise, the string must match the following BNF:

string →

assign*

assign →

whitespace*

assign →

whitespace* key whitespace* = whitespace* value delimiter
key →

any string not containing ’/’ or ’=’ or whitespace

value →

array || int_value || real_value || string_value

array →

{ int_value* }||{ real_value }

int_value →

anything recognized as a valid integer by strdol(3) in base 10

real_value →

anything not recognized as a valid integer by strtol(3) but recognized as valid by strdod(3)

string_value →

a C-style string enclosed in ”double quotes” (C-style character escape codes are allowed, i.e. bell (’\a’), backspace (’\b’), form-feed (’\f’), newline (’\n’), carriage-return (’\r’), tab (’\t’), vertical-tab (’\v’), backslash (’\\’), single-quote (’\’’), double-quote (’\"’), question-mark (’\?’))

string_value →

a C-style string enclosed in ’single quotes’ (C-style character escape codes are not allowed, i.e. every character within the string is interpreted literally)

delimiter →

end-of-string || whitespace

whitespace →

blank (’ ’) || tab (’\t’) || newline (’\n’) || carriage-return (’\r’) || form-feed (’\f’) || vertical-tab (’\v’)


where * denotes 0 or more repetitions and | | denotes logical or.

Notice also that the keys allowed by this function are somewhat more restricted than those allowed by the other Util_TableSet*() functions, in that this function disallows keys containing ’=’ and/or whitespace.

If any error code is returned, assignments lexicographically earlier in the input string than where the error was detected will already have been made in the table. Unfortunately, there is no easy way to find out where the error was detected. :(

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGet*Array() get an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_NO_MEMORY unable to allocate memory
UTIL_ERROR_BAD_KEY invalid input: key contains invalid character
UTIL_ERROR_BAD_INPUT invalid input: can’t parse input string
UTIL_ERROR_NO_MIXED_TYPE_ARRAY invalid input: different array values have different datatypes
other error codes this function may also return any error codes returned by Util_TableSetString(), Util_TableSetInt(), Util_TableSetReal(), Util_TableSetIntArray(), or Util_TableSetRealArray().

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
/* suppose we have a table referred to by  handle */  
 
/* then the call... */  
int count = Util_TableSetFromString(handle, "n = 6\t"  
                                            "dx = 4.0e-5\t"  
                                            "pi = 3.1\t"  
                                            "s = ’my string’\t"  
                                            "array = { 1 2 3 }");  
/* ... will return count=5 ... */  
 
/* ... and is otherwise equivalent to the five calls ... */  
CCTK_INT array[] = {1, 2, 3};  
 
Util_TableSetInt(handle, 6, "n");  
Util_TableSetReal(handle, 4.0e-5, "dx");  
Util_TableSetReal(handle, 3.1, "pi");  
Util_TableSetString(handle, "my string", "s");  
Util_TableSetIntArray(handle, 3, array, "array");


Util_TableSetGeneric

Set the value associated with a specified key to be a specified single (1-element array) value, whose data type is generic. That is, the value is specified by a CCTK_VARIABLE_* type code and a void * pointer.

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableSetGeneric(int handle,  
                                  int type_code, const void *value,  
                                  const char *key);


Fortran
call Util_TableSetGeneric(status, handle, type_code, value, key)  
integer        status, handle, type_code  
CCTK_POINTER   value  
character*(*)  key


Result

1 ok (key was already in table before this call, old value was replaced)
(it doesn’t matter what the old value’s type_code and N_elements were, i.e. these do not have to match the new value)
0 ok (key was not in table before this call)

Parameters

handle (≥ 0) handle to the table
type_code the array elements’ type code (one of the CCTK_VARIABLE_* constants from "cctk_Constants.h")
value_ptr a pointer to the value to be associated with the key
key a pointer to the key (a C-style null-terminated string)

Discussion

The key may be any C character string which does not contain a slash character (’/’).

The value is stored as a 1-element array.

This function invalidates any iterators for the table which are not in the “null-pointer” state.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGet*Array() get an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_BAD_INPUT type_code is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
#include "util_Table.h"  
#include "cctk_Constants.h"  
 
const CCTK_INT i = 42;  
const void *iptr = (void *) &i;  
CCTK_INT icopy;  
 
const CCTK_REAL x = 299792458.0;  
const void *xptr = (void *) &x;  
CCTK_REAL xcopy;  
 
const int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetGeneric(handle, CCTK_VARIABLE_INT, iptr, "the answer");  
Util_TableSetGeneric(handle, CCTK_VARIABLE_REAL, xptr, "speed of light");  
 
/* gets icopy to 42 */  
Util_TableGetInt(handle, &icopy, "the answer");  
 
/* gets xcopy to 299792458.0 */  
Util_TableGetReal(handle, &xcopy, "speed of light");


Util_TableSetGenericArray

Set the value associated with a specified key to be a copy of a specified array, whose data type is generic. That is, the array is specified by a CCTK_VARIABLE_* type code, a count of the number of array elements, and a void * pointer.

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableSetGenericArray(int handle,  
                                       int type_code,  
                                       int N_elements, const void *array,  
                                       const char *key);


Fortran
call Util_TableSetGenericArray(status,  
.                              handle,  
.                              type_code,  
.                              N_elements, array,  
.                              key)  
integer           status, handle, type_code, N_elements  
CCTK_POINTER(*)   array  
character*(*)     key


Result

1 ok (key was already in table before this call, old value was replaced)
(it doesn’t matter what the old value’s type_code and N_elements were, i.e. these do not have to match the new value)
0 ok (key was not in table before this call)

Parameters

handle (≥ 0) handle to the table
type_code the array elements’ type code (one of the CCTK_VARIABLE_* constants from "cctk_Constants.h")
N_elements (≥ 0) the number of array elements in array[]
value_ptr a pointer to the value to be associated with the key
key a pointer to the key (a C-style null-terminated string)

Discussion

The key may be any C character string which does not contain a slash character (’/’).

The value is stored as a 1-element array.

This function invalidates any iterators for the table which are not in the “null-pointer” state.

Note that the table makes (stores) a copy of the array you pass in, so it’s somewhat inefficient to store a large array (e.g. a grid function) this way. If this is a problem, consider storing a CCTK_POINTER (pointing to the array) in the table instead. (Of course, this requires that you ensure that the pointed-to data is still valid whenever that CCTK_POINTER is used.)

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGet*Array() get an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetFromString() [B139] convenience routine to set key/value entries in a table based on a parameter-file–like character string
Util_TableSetString() [B152] set a character-string value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_BAD_INPUT type_code is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
#include "util_Table.h"  
#include "cctk_Constants.h"  
 
#define N_IARRAY    3  
const CCTK_INT iarray[N_IARRAY] = {42, 69, 105};  
const void *iarray_ptr = (void *) iarray;  
CCTK_INT iarray2[N_IARRAY];  
 
#define N_XARRAY    2  
const CCTK_REAL xarray[N_XARRAY] = {6.67e-11, 299792458.0};  
const void *xarray_ptr = (void *) xarray;  
CCTK_REAL xarray2[N_XARRAY];  
 
const int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetGenericArray(handle,  
                          CCTK_VARIABLE_INT,  
                          N_IARRAY, iarray_ptr,  
                          "my integer array");  
Util_TableSetGenericArray(handle,  
                          CCTK_VARIABLE_REAL,  
                          N_XARRAY, xarray_ptr,  
                          "my real array");  
 
/* gets iarray2[0] = 42, iarray2[1] = 69, iarray2[2] = 105 */  
Util_TableGetIntArray(handle, N_IARRAY, iarray2, "my integer array");  
 
/* gets xarray2[0] = 6.67e-11, xarray2[1] = 299792458.0 */  
Util_TableGetRealArray(handle, N_XARRAY, xarray2, "my real array");


Util_TableSetString

Sets the value associated with a specified key in a table, to be a copy of a specified C-style null-terminated character string

Synopsis

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
int status = Util_TableSetString(int handle,  
                                 const char *string,  
                                 const char *key);


Fortran
call Util_TableSetString(status, handle, string, key)  
integer           status, handle  
character*(*)     string, key


Result

Results are the same as all the other Util_TableSet*() functions: 1 ok (key was already in table before this call, old value was replaced)
(it doesn’t matter what the old value’s type_code and N_elements were, i.e. these do not have to match the new value)
0 ok (key was not in table before this call)

Parameters

handle (≥ 0) handle to the table
string a pointer to the string (a C-style null-terminated string)
key a pointer to the key (a C-style null-terminated string)

Discussion

The key may be any C character string which does not contain a slash character (’/’).

The string is stored as an array of strlen(string) CCTK_CHARs. It does not include a terminating null character.

This function is very similar to Util_TableSetCharArray().

This function invalidates any iterators for the table which are not in the “null-pointer” state.

See Also

Util_TableCreateFromString() [B61] convenience routine to create a table and set key/value entries in it based on a parameter-file–like character string
Util_TableGet*() get a single (1-element array) value, or more generally the first array element of an array value
Util_TableGet*Array() get an array value
Util_TableGetGeneric() [B79] get a single (1-element array) value with generic data type
Util_TableGetGenericArray() [B83] get an array value with generic data type
Util_TableGetString() [B87] get a character-string value
Util_TableSetCharArray() [B135] get an array-of-CCTK_CHAR value
Util_TableSet*() set a single (1-element array) value
Util_TableSet*Array() set an array value
Util_TableSetGeneric() [B144] set a single (1-element array) value with generic data type
Util_TableSetGenericArray() [B148] set an array value with generic data type
Util_TableSetCharArray() [B135] set an array-of-CCTK_CHAR value

Errors

UTIL_ERROR_BAD_HANDLE handle is invalid
UTIL_ERROR_TABLE_BAD_KEY key contains ’/’ character
UTIL_ERROR_NO_MEMORY unable to allocate memory

Examples

C
#include "util_ErrorCodes.h"  
#include "util_Table.h"  
 
static const CCTK_CHAR array[]  
        = {’r’, ’e’, ’l’, ’a’, ’t’, ’i’, ’v’, ’i’, ’t’, ’y’};  
#define N_ARRAY (sizeof(array) / sizeof(array[0]))  
int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);  
 
Util_TableSetString(handle, "relativity", "Einstein");  
 
/* this produces the same table entry as the Util_TableSetString() */  
Util_TableSetCharArray(handle, N_ARRAY, array, "Einstein");


1For backwards compatability the function Util_TableGetFnPointer() is also provided as an alias for Util_TableGetFPointer(). This is deprecated as of Cactus 4.0 beta 13.

2For backwards compatability the function Util_TableGetFnPointerArray() is also provided as an alias for Util_TableGetFPointerArray(). This is deprecated as of Cactus 4.0 beta 13.

3For backwards compatability the function Util_TableSetFnPointer() is also provided as an alias for Util_TableSetFPointer(). This is deprecated as of Cactus 4.0 beta 13.

4For backwards compatability the function Util_TableSetFnPointerArray() is also provided as an alias for Util_TableSetFPointerArray(). This is deprecated as of Cactus 4.0 beta 13.

[prev] [prev-tail] [front] [up]