Tcl/Tk For Programmers
The `Tfp_array*` Family

Tfp_array* is a family of C functions that implement multiple associative arrays. Each associative array created by the Tfp_array* family is of type Tfp_ArrayType which is defined this way

typedef struct { 
   Tcl_HashTable * Table; 
   Tfp_ArrayDeleteProc * cleaner; 
} Tfp_ArrayType;

As a user of the Tfp_array* family, you are not concerned with the contents of this structure.

Each of these associative arrays is meant to have a consistent range. (The range of an associative array is the set of array elements you can look up with it.) A "consistent" range is a range who elements all can be cleaned up in the same way when they are destroyed. Following standard practice when using Tcl's C library, all elements of type ClientData. When elements are pointers to dynamically allocated memory there must be a mechanism for de-allocating that memory. To use the Tfp_array* family you must implement a mechanism for deleting any one of the array elements with a function of type

typedef void (Tfp_ArrayDeleteProc)(ClientData);

Here are the functions in the Tfp_array* family. Each ARRAY argument in the table below is of type Tfp_ArrayType *. To use these functions, you declare a variable of this type for each associative array you wish to work with.

Tfp_arrayInit(CLEANER)

Creates an ARRAY and returns a pointer to it. The pointer has type Tfp_ArrayType *. ARRAY may be thought of as a function that maps strings to ClientDatas. After initialization, it is empty -- it maps nothing.

The CLEANER argument points to a function of type Tfp_ArrayDeleteType that knows how to clean up any memory asociated with a ClientData value. If no such function is needed, i.e. if array values will be stored within ClientData pointers rather than be pointed to by ClientData pointers, then this parameter may be (Tfp_ArrayDeleteType *)NULL.

Tfp_arrayDestroy(ARRAY)

De-allocates memory pointed to by ARRAY. If the CLEANER argument used to create the array was not (Tfp_ArrayDeleteType *)NULL, then memory is also de-allocated for each ClientData value in the array.

Notes: Tfp_arrayDestroy will bomb if ARRAY was not initialized with Tfp_arrayInit.

Tfp_arrayGet(PTR,ARRAY,NAME)

Where PTR of type ClientData *, and NAME is a character string. Gets the value in ARRAY associated with NAME and returns it through the ClientData pointer. Returns a boolean, true iff successful.

Tfp_arraySet(ARRAY,NAME,CLIENTDATA)

Arranges for CLIENTDATA to be the value associated with NAME in ARRAY.

NAME is a char *. CLIENTDATA is of type ClientData.

Tfp_arrayDelete(ARRAY,NAME)

Arranges for the mapping from NAME to be deleted.

If the CLEANER argument to Tfp_initArray was nonnull, the memory pointed to by the ClientData value is de-allocated as well.

NAME is a char *.

From Tcl/Tk For Programmers Author J Adrian Zimmer

Oct 18, 1997

Tcl/Tk For Programmers The Tfp_array* Family

Tcl/Tk For Programmers
The `Tfp_array*` Family