Pointer Arrays

Another class of functions provided by the utility library is the pointer array functions. Pointer arrays are used to manage arrays of pointers. They are similar to hash tables in some ways but they provide these differences:

Two typedefs are provided for use with pointer arrays, the pointer array user function, and the pointer array compare function.

The pointer array user function is defined in this way:

void (*T_PTR_ARY_USER_FUNC) 
(T_INT4 index, T_PTR item, T_PTR arg); 

This function typedef is used by TutPtrAryDestroy and TutPtrAryClear. It is called when the items in a pointer array are removed and allows you to perform cleanup actions as required.

The pointer array compare function is used when sorting the items in a pointer array. It is used by TutPtrArySort and is defined in this way:

T_INT4 (*T_PTR_ARY_CMP_FUNC)(T_PTR item1, T_PTR item2); 

It returns a negative value if the first item is less than the second, zero if the two items are equal, or a positive value if the first is greater than the second.

Occasionally, you may want to receive notification when an item in a pointer array is changed, such as inserted or removed. This is accomplished using a pointer array change callback. There can be multiple pointer array change callbacks for a pointer array. The callback function is called with a pointer array change callback data structure, defined in this way:

struct T_PTR_ARY_CHANGE_CB_DATA_STRUCT { 
T_CB cb; 
T_PA_REASON reason; 
T_PTR item;    /* item changed. NULL if reason = T_PA_CLEARED */ 
T_INT4 index;  /* index of item above. -1 if item is NULL */ 
T_PTR item2;   /* item changed. NULL if reason != T_PA_ITEMS_SWAPPED */ 
T_INT4 index2; /* index of item above. -1 if item is NULL */ 
} T_PTR_ARY_CHANGE_CB_DATA_STRUCT, *T_PTR_ARY_CHANGE_CB_DATA; 

The pointer array callback reasons are:

Pointer array change callbacks are managed with the functions TutPtrAryChangeCbCreate and TutPtrAryChangeCbLookup.