Functions and Directives

Function ACopy() Foundation

Copies elements of an array into another array

ACopy( <aSource>, ;
       <aTarget>, ;
      [<nStartSource>], ;
      [<nCount>], ;
      [<nStartTarget>] )    --> aTarget
<aSource> is an array whose elements are copied.
<aTarget> is an array into which elements of <aSource> are copied.
<nStartSource> is a numeric value specifying the starting position in the array <aSource> to copy. The default value is 1.
<nCount> is a numeric value specifying the number of elements to copy, starting from position <nStartSource>. If <nCount> is missing, the elements are copied from <nStartSource> to the last element of <aSource>.
<nStartTarget> is a numeric value specifying the starting position in the array <aTarget> to which copies are transferred. The default value is 1.

The return value of ACopy() is a reference to <aTarget>.


The array function ACopy() copies values from the array elements in <aSource> into the target array <aTarget>. Only values in the first dimension of <aSource> are copied. If <aSource> has subarrays (is a multi-dimensional array), only the array references and not the content of the subarrays are copied into <aTarget>. In this case, both arrays have the reference to the same subarrays. To completely copy a multi-dimensional array, the function AClone() must be used.

The array <aTarget> must be large enough to hold the copied values. If <aSource> is greater than <aTarget>, all the elements are not copied.

The array <aTarget> can be identical to <aSource>. When this is the case, elements in <aSource> may be moved in blocks.

// The example performs two calls to ACopy(). The first 
// copies only two elements, and the starting position is 
// included for the copy from source array to target array. 
// The second call copies all elements into the target array. 

   LOCAL aSource, aTarget 

   aSource := { 1 , 2 , 3 , 4 , 5 } 
   aTarget := {"A","B","C","D","E"} 

   ACopy( aSource, aTarget, 3, 2, 4 ) 
                            // aTarget is: {"A","B","C", 3, 4 } 

   ACopy( aSource, aTarget ) 
                            // aTarget is: { 1 , 2 , 3 , 4 , 5 } 


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.