FUNCTIONPublished

AClone

AClone( <aArray> )

Duplicates an array, including nested arrays in multidimensional structures.

ArraysMatrizesCópiaFunçõesTDN

01 · OVERVIEW

Overview

AClone() creates an independent copy of the supplied array. Unlike a simple assignment, which makes two variables point to the same structure, AClone() replicates the elements and nested arrays. Use it when the routine must change the copy without changing the original array.

02 · SYNTAX

Syntax

AClone( <aArray> )

Parameters

aArray

ArrayRequired

Array to be duplicated. It may contain one or more dimensions.

Return value

Returns a new array with the same content as the supplied array, preserving nested arrays when they exist.

03 · PRACTICAL EXAMPLE

Cloning a simple array

User Function AClone1()
    Local aArray1 := { 10, 20, 30 }
    Local aArray2 := AClone(aArray1)
    Local nIndex := 0

    For nIndex := 1 To Len(aArray2)
        MsgInfo( CValToChar(aArray2[nIndex]) )
    Next nIndex
Return

Expected result

The cloned array contains the same values as the original array: 10, 20 and 30.

04 · PRACTICAL EXAMPLE

Independent copy of a multidimensional array

User Function AClone2()
    Local aOriginal := { {"Product", 10}, {"Service", 20} }
    Local aCopy := AClone(aOriginal)

    aCopy[1][2] := 99

    MsgInfo("Original: " + CValToChar(aOriginal[1][2]))
    MsgInfo("Copy: " + CValToChar(aCopy[1][2]))
Return

Expected result

Changing the copy does not change the original array value, including nested arrays.

BEST PRACTICES

Use AClone() quando a cópia será modificada e o array original precisa permanecer intacto.
AClone() é especialmente útil em arrays multidimensionais, pois também replica subarrays.
A referência TDN compara AClone() com ACopy(): ACopy() é voltada a arrays unidimensionais, enquanto AClone() atende estruturas multidimensionais.

COMMON PITFALLS

Assigning aCopy := aOriginal does not clone the array; both variables point to the same structure.
Cloning very large arrays may increase memory usage.
When cloning sensitive or temporary data, manage the copy lifecycle to avoid keeping unnecessary information in memory.