TutPtrAryDestroy

Name

TutPtrAryDestroy — destroy a pointer array

Synopsis

T_BOOL TutPtrAryDestroy(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 destroyed.

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

TutPtrAryDestroy destroys the ptr_ary. It does not necessarily free the memory allocated to the array. It may, depending on the number of previous calls to TutPtrAryDestroy and TutPtrAryCreate, add the memory to the internal memory pool, thus speeding up the next call to TutPtrAryCreate. After the array is destroyed, 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 destroyed, or while it is being destroyed using user_func.

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

Caution

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

After calling TutPtrAryDestroy, the value of ptr_ary becomes undefined and should not be used.

See Also

TutPtrAryClear, TutPtrAryCreate

Examples

This example destroys a pointer array:

void clear_func(index, item, arg) 
T_INT4 index; 
T_PTR item; 
T_PTR arg; 
{ 
  T_FREE(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, destroy the array */ 
TutPtrAryDestroy(ptr_ary, clear_func, NULL);