TutPtrAryClear

Name

TutPtrAryClear — clear a pointer array

Synopsis

T_BOOL TutPtrAryClear(ptr_ary, user_func, user_arg) 
T_PTR_ARY ptr_ary; 
T_PTR_ARY_USER_FUNC user_func; 
T_PTR user_arg; 

Arguments

ptr_ary — pointer array to be cleared.

user_func — optional function that is called once for every element in the array. This argument may be NULL.

user_arg — argument that is passed to user_func.

Return Values

Returns TRUE if operation is a success, FALSE otherwise.

Diagnostics

None

Description

TutPtrAryClear clears ptr_ary of all elements. It does not free the memory allocated to the array, it merely resets the internal array counters to their initial values, so that the array appears to be empty. After the array is cleared, all pointers that were stored in the array become inaccessible, so it is up to you to free the memory that was pointed to by these pointers either before the array is cleared, or while it is being cleared using user_func.

If specified, user_func is called by TutPtrAryClear for every item in the array before the internal array counters are reset. It is called with three arguments. The first argument is the index of the item, the second argument is item, and the third argument is the user_arg TutPtrAryClear was called with.

TutPtrAryClear calls the pointer array change callbacks with the reason T_PA_ITEM_CLEARED.

Caution

Clearing the pointer array without freeing the memory pointed to by its items may create a memory leak.

See Also

TutPtrAryDestroy, TutPtrAryCreate

Examples

This example clears a pointer array:

void *clear_func(index, item, arg) 
T_INT4 index; 
T_PTR item; 
T_PTR arg; 
 
{ 
 T_FREE((T_STR)item); 
} 
 
T_PTR_ARY ptr_ary; 
T_INT4 i, *int_ptr; 
 
/* create the pointer array with initial size of 30 */ 
 
ptr_ary = TutPtrAryCreate(30); 
/* fill it up with 25 entries */ 
for (i = 0; i < 25; i++) { 
  /* allocate the space for the next element */ 
  T_MALLOC(int_ptr, sizeof(T_INT4), T_INT4 *); 
  *int_ptr = i; 
  /* append the item to the array, ignore the index */ 
  TutPtrAryAppend(ptr_ary, int_ptr, NULL); 
}  
 
/* perform various operations on the array */ 
. 
. 
. 
 
/* now, clear the array of all elements */ 
TutPtrAryClear(ptr_ary, clear_func, NULL);