TutPtrAryRemove

Name

TutPtrAryRemove — remove the specified item from a pointer array

Synopsis

T_BOOL TutPtrAryRemove(ptr_ary, item) 
T_PTR_ARY ptr_ary; 
T_PTR item; 

Arguments

ptr_ary — pointer array to perform the operation on

item — item to be removed from the pointer array

Return Values

TRUE if the specified item was found in the array and removed, or FALSE if the item was not in the array.

Diagnostics

None

Description

TutPtrAryRemove removes the specified item from the array. After the removal, array compaction is performed, thus getting rid of the hole that was created as a result of a removal. Note that the removal operation may cause item indices to change.

TutPtrAryRemove calls the pointer array change callbacks with the reason T_PA_ITEM_REMOVED.

Caution

Removal of an item from a very large array can be a time-consuming operation.

TutPtrAryRemove does not free the item removed from the array.

This function only removes the first occurrence of item. Use TutPtrAryRemoveAll to remove all occurrences.

See Also

TutPtrAryClear, TutPtrAryCreate, TutPtrAryDestroy, TutPtrAryRemove, TutPtrAryRemoveAll

Examples

This example removes an item from the pointer array:

T_PTR_ARY ptr_ary; 
T_INT4 i, *int_ptr, *mark_item, index; 
 
/* 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 */ 
. 
. 
. 
/* get the item at index 13 and remove it*/ 
if (TutPtrAryGetItemAtIndex(ptr_ary, 13, (T_PTR *)&int_ptr)) { 
  TutPtrAryRemove(ptr_ary, int_ptr); 
  TutOut("Successfully removed item at index 13 from the  
           array \n"); 
} 
else { 
  TutOut("Array has shrunk, and has less than 13 elements \n"); 
}