FUNCTIONPublished

ACopy

ACopy( <aOrigem>, <aDestino>, [nInicio], [nCont], [nPosDestino] )

Copies elements from one array to another compatible destination array.

ArraysMatrizesCópiaFunçõesTDN

01 · OVERVIEW

Overview

ACopy() copies elements from a source array into a destination array. It can define the starting source position, the number of copied elements and the starting destination position. Unlike AClone(), it assumes the destination array already has a compatible structure; it does not automatically resize the destination to make the copy possible.

02 · SYNTAX

Syntax

ACopy( <aOrigem>, <aDestino>, [nInicio], [nCont], [nPosDestino] )

Parameters

aOrigem

ArrayRequired

Source array from which elements are copied.

aDestino

ArrayRequired

Destination array that receives the copied elements. It must have a compatible structure.

nInicio

NumericOptional

Initial source-array position from which elements are copied.

Default: 1

nCont

NumericOptional

Number of elements copied. When omitted, the source array is considered through its last element.

nPosDestino

NumericOptional

Initial destination-array position where elements are written.

Default: 1

Return value

Returns aDestino, a reference to the destination array that received the copied elements.

03 · PRACTICAL EXAMPLE

Copying into a prepared array

#Define CRLF Chr(13)+Chr(10)

User Function ACopy1()
    Local aExample := {1, 2, {11, 22, 33}}
    Local aBackup := {Nil, Nil, {Nil, Nil, Nil}}
    Local cMessage := ""

    ACopy(aExample, aBackup)

    cMessage += "Copy[1] = " + CValToChar(aBackup[1]) + CRLF
    cMessage += "Copy[2] = " + CValToChar(aBackup[2]) + CRLF
    cMessage += "Copy[3][1] = " + CValToChar(aBackup[3][1]) + CRLF
    cMessage += "Copy[3][2] = " + CValToChar(aBackup[3][2]) + CRLF
    cMessage += "Copy[3][3] = " + CValToChar(aBackup[3][3])

    MsgInfo(cMessage, "ACopy example")
Return

Expected result

The elements from aExample are copied to aBackup, which was already created with a compatible structure.

04 · PRACTICAL EXAMPLE

Partial copy with destination position

User Function ACopy2()
    Local aSource := {"A", "B", "C", "D"}
    Local aTarget := {"", "", "", ""}

    ACopy(aSource, aTarget, 2, 2, 3)

    MsgInfo("Target: " + aTarget[1] + "," + ;
        aTarget[2] + "," + aTarget[3] + "," + aTarget[4])
Return

Expected result

Copies two elements starting at source position 2 and writes them starting at destination position 3.

BEST PRACTICES

Use ACopy() quando já existe um array de destino preparado e você quer copiar todos ou parte dos elementos de outro array.
Use nInicio, nCont e nPosDestino para cópias parciais e reposicionamento dos elementos.
Para duplicar um array inteiro, especialmente com subarrays ou matrizes multidimensionais, avalie AClone().
A referência TDN informa abrangência histórica em Microsiga Protheus 8.11 e Protheus 10.

COMMON PITFALLS

ACopy() does not automatically change the destination array structure to make the copy possible.
If the destination does not have compatible positions, the result may not be as expected or may raise an error depending on the case.
Copying nested arrays may preserve internal references depending on the structure; when the intention is an independent copy of multidimensional structures, prefer AClone().

ACopy

Overview

Syntax

Parameters

Return value

Copying into a prepared array

Partial copy with destination position

Related content

Comments