Xbase++ - Function ARemove()

Removes one or more elements from an array.

ARemove( <aArray>    , ;
        [<nStartPos>], ;
        [<nCount>]     ) --> aRemoved

<aArray> is the array from which an element is removed. If <aArray> is empty, ARemove() returns an empty array.

<nStartPos> is a numeric value specifying the starting position of elements to remove. The default value is the position of the last element which is equivalent to the expression Len(aArray). If <aArray> is not empty and <nStartPos> is greater than Len( <aArray>) a runtime error is raised.

<nCount> is a numeric value specifying the number of elements to remove. It defaults to 1. If <nCount> is greater than the number of elements that can be removed starting at <nStartPos>, only the number of available elements is removed.

The function returns the removed elements of <aArray> as an array.

The array function ARemove() removes one or more elements from an array. Subsequent elements are shifted up the respective number of elements. The array is finally truncated at the end by the number of removed elements. The function returns the removed array elements of <aArray> as a new array for further processing.

ARemove() is a combination of ADel() and ASize() so that array elements are removed physically from an array within one function call. This is the recommended technique of removing elements in multi-threaded programs since ARemove() is an atomic operation and implicitly thread-safe.

Stack implementation using arrays

// The example shows how to use arrays to emulate a stack 
// using ARemove() and AAdd() 

#xtrans SInit(<s>)      => <s>:={} 
#xtrans SPush(<s>, <x>) => AAdd(<s>, <x>) 
#xtrans SPop(<s>)       => ARemove(<s>) 

PROCEDURE Main 
LOCAL myStack 

   SInit(myStack) 
   SPush(myStack, "Slice 1") 
   SPush(myStack, "Slice 2") 
   ? SPop(myStack)            // {"Slice 2"} 
   ? SPop(myStack)            // {"Slice 1"} 
   ? SPop(myStack)            // {} 
   WAIT 
RETURN

Removing versus deleting array elements

// The example demonstrates the difference between 
// ADel() and ARemove(). 

PROCEDURE Main 
   LOCAL a1 := { "A", "B", "C" } 
   LOCAL a2 := { "A", "B", "C" } 

   ADel( a1, 2 ) 
   ? a1                      // Result: { "A", "C", NIL } 

   ARemove( a2, 2 ) 
   ? a2                      // Result: { "A", "C" } 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function ARemove() Foundation