xHarbour Reference Documentation > Function Reference

ACopy()

Copy elements from a source array into a target array.

Syntax

ACopy( <aSource>      , ;
       <aTarget>      , ;
      [<nSourceStart>], ;
      [<nCount>]      , ;
      [<nTargetStart>]  ) --> aTarget

Arguments

<aSource>

The source array whose elements are copied.

<aTarget>

The target array recieving copied values.

<nSourceStart>

This is a numeric expression indicating the first element in the source array to begin copying with. It defaults to 1, the first element of <aSource>.

<nCount>

A numeric expression specifying the number of elements to copy from <aSource> to <aTarget>. It defaults to the maximum possible number that can be copied. This number depends on the size of source and target array, and the start elements of both arrays.

<nTargetPos>

A numeric expression indicating the first element in the target array that receives copied values. It defaults to 1.

Return

The function returns a reference to the <aTarget> array.

Description

ACopy() is an array function that iterates over the elements of a source array and copies values stored in these elements to a target array. Copying begins with the element <nSourceStart> of the source array. The value of this element is copied to the element <nTargetStart> of the target array. The function then proceeds to the next element in both arrays. The copy process is complete when either <nCount> elements are copied, or the last element in one of both arrays is reached. If the source array contains more elements than the target array, copying stops when the last element of the target array is reached, and vice versa. The number of elements in both arrays is not changed by ACopy().

The function operates in the first dimension of an array. Only values of the simple data types Character, Date, Logic, Numeric and NIL are actually copied. Values of the complex data types Array, Code block, Hash and Object are represented by references to their values. Hence, ACopy() copies the references to complex values from source to target array. As a result both arrays contain references to the same complex values. This is especially important when copying multi-dimensional array with ACopy() since both arrays contain references to the same sub-arrays when copying is complete.

Note:  use function AClone() to obtain a true "deep copy" of multi-dimensional arrays.

Info

See also:	AClone(), ADel(), AEval(), AFill(), AIns(), ASort()
Category:	Array functions
Source:	vm/arrayshb.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// This example copies the values from one array to another and
// displays the results on the screen.

   PROCEDURE Main()
      LOCAL aSource := {"xHarbour", "dot", "com"}
      LOCAL aTarget := {"xHarbour", "dot", "net"}

      ACopy( aSource, aTarget, 3, 1, 3)

      ? aSource[1], aSource[2], aSource[3]
      ? aTarget[1], aTarget[2], aTarget[3]

      AAdd( aSource, "is")
      AAdd( aSource, "great")

      ACopy(aSource, aTarget, , , 2)

      ? aSource[1], aSource[2], aSource[3], aSource[4], aSource[5]
      ? aTarget[1], aTarget[2], aTarget[3]
      ? Len( aTarget )
   RETURN