TutPtrAryRemoveAll

Name

TutPtrAryRemoveAll — remove all instances of the specified item from a pointer array

Synopsis

T_BOOL TutPtrAryRemoveAll(ptr_ary, item, counter) 
T_PTR_ARY ptr_ary; 
T_PTR item; 
T_INT4 *counter; 

Arguments

ptr_ary — pointer array to operate on

item — item that is removed from the array

counter — pointer to count of the number of instances of the item removed

Return Values

TRUE if at least one instance of the item was found in the array and removed, FALSE otherwise.

Diagnostics

None

Description

TutPtrAryRemoveAll removes all instances of the specified item from the pointer array. Because array compaction is performed after every removal, TutPtrAryRemoveAll is not very efficient while performing operations on very large arrays. Note that the removal operation may cause item indices to change.

TutPtrAryRemoveAll calls the pointer array change callbacks with the reason T_PA_ALL_ITEMS_REMOVED.

Caution

It is up to you to allocate the space for the counter. The value stored in the counter is always modified after the call to TutPtrAryRemoveAll.

TutPtrAryRemoveAll does not free the items removed from the array. If these items do need to be deallocated, then use TutPtrAryRemove.

See Also

TutPtrAryRemove, TutPtrAryRemoveAll

Examples

This example removes all instances of an item from the pointer array:

T_PTR_ARY ptr_ary; 
T_INT4 i, *int_ptr, *save_ptr, counter; 
 
/* 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(int), int*); 
  *int_ptr = i; 
  /* append the item to the array, ignore the index */ 
  TutPtrAryAppend(ptr_ary, int_ptr, NULL); 
  if (i == 7) { 
    /* insert a second copy of the same item in the array */ 
    TutPtrAryAppend(ptr_ary, int_ptr, NULL); 
    save_ptr = int_ptr; 
  } 
}  
 
. 
. 
. 
/* remove all instances of the saved item from the array */ 
if (TutPtrAryRemoveAll(ptr_ary, save_ptr, &counter)) { 
  TutOut("Removed %d instances of item containing", counter); 
  TutOut(" %d from the array\n", *save_ptr); 
}