Function ARemove() Foundation

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>) 

LOCAL myStack 

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

Removing versus deleting array elements
// The example demonstrates the difference between 
// ADel() and ARemove(). 

   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" } 

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.