FOUNDATIONPublished

Arrays in AdvPL

aMatriz := { <elemento1>, <elemento2>, ... } · aMatriz[nÍndice]

Organize values in simple or multidimensional lists, access positions and change the structure dynamically.

ArraysCollectionsData structuresMemory

01 · OVERVIEW

Overview

Arrays are ordered collections of values. In AdvPL, the first element is at position 1, and one array may contain characters, numbers, dates, logical values, objects, other arrays and other types. Nested arrays can represent rows, columns and compound structures.

02 · SYNTAX

Syntax

aMatriz := { <elemento1>, <elemento2>, ... } · aMatriz[nÍndice]

Parameters

aMatriz

ArrayRequired

Variable that stores the collection.

nÍndice

NuméricoRequired

Element position, starting at 1 and limited by the current array size.

elemento

QualquerOptional

Stored value; elements in the same array may have different types.

03 · PRACTICAL EXAMPLE

Creation, access and size

User Function ExArray()
    Local aLetters := {"A", "B", "C"}

    MsgInfo("Second element: " + aLetters[2])
    MsgInfo("Count: " + CValToChar(Len(aLetters)))
Return

Expected result

Index 2 returns B and Len() reports three elements.

04 · PRACTICAL EXAMPLE

Dynamic inclusion with AAdd

User Function ExAppend()
    Local aLetters := {"A", "B", "C"}

    AAdd(aLetters, "D")
    MsgInfo("Last element: " + aLetters[Len(aLetters)])
Return

Expected result

AAdd() appends D and Len() supplies the current last position.

05 · PRACTICAL EXAMPLE

Structure with different types

#define PESSOA_NOME   1
#define PESSOA_IDADE  2
#define PESSOA_ATIVA  3

User Function ExPessoa()
    Local aPessoa := {"Maria", 32, .T.}

    If aPessoa[PESSOA_ATIVA]
        ConOut(aPessoa[PESSOA_NOME] + " está ativa")
    EndIf
Return

Expected result

Constants give semantic names to the positions holding name, age and status.

06 · PRACTICAL EXAMPLE

Multidimensional array

#define PESSOA_NOME  1
#define PESSOA_IDADE 2

User Function ExPessoas()
    Local aPessoas := { ;
        {"Pedro", 32}, ;
        {"Maria", 22}, ;
        {"Antônio", 42} }
    Local nLinha

    For nLinha := 1 To Len(aPessoas)
        ConOut(aPessoas[nLinha, PESSOA_NOME] + ;
            " - " + CValToChar(aPessoas[nLinha, PESSOA_IDADE]))
    Next
Return

Expected result

Each inner array is a row. The loop iterates over people and accesses columns through constants.

07 · PRACTICAL EXAMPLE

Protected index access

User Function ExIndice(nIndice)
    Local aCores := {"Azul", "Verde", "Vermelho"}

    If nIndice >= 1 .And. nIndice <= Len(aCores)
        MsgInfo(aCores[nIndice])
    Else
        MsgAlert("Posição inválida")
    EndIf
Return

Expected result

The condition prevents access outside the current array bounds.

BEST PRACTICES

Use braces to create an array literal and brackets to access a position.
Len(aArray) returns the number of elements in the requested dimension.
AAdd(aArray, xValue) appends an element.
Multidimensional arrays can be accessed as aData[nRow, nColumn] or aData[nRow][nColumn].
#define constants can name structure positions and improve readability.

COMMON PITFALLS

Accessing a position below 1 or above Len(aArray) causes an error; validate the index first.
Very large or deeply nested arrays can consume significant memory. For high volumes, consider temporary tables or chunked processing.
The historical reference mentions up to 100,000 elements for versions 5.07 through 8.11. Do not treat this as a universal limit; verify it in the AppServer and LIB in use.
When records are represented by numeric positions, keep constants and documentation synchronized.
Arrays may contain mixed types, but routines expecting a particular structure must validate them.

Arrays in AdvPL

Overview

Syntax

Parameters

Creation, access and size

Dynamic inclusion with AAdd

Structure with different types

Multidimensional array

Protected index access

Related content

Comments