aMatrizArrayRequired
Variable that stores the collection.
FOUNDATIONPublished
Arrays in AdvPL
aMatriz := { <elemento1>, <elemento2>, ... } · aMatriz[nÍndice]Organize values in simple or multidimensional lists, access positions and change the structure dynamically.
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.
Syntax
aMatriz := { <elemento1>, <elemento2>, ... } · aMatriz[nÍndice]Parameters
nÍndiceNuméricoRequired
Element position, starting at 1 and limited by the current array size.
elementoQualquerOptional
Stored value; elements in the same array may have different types.
Creation, access and size
User Function ExArray()
Local aLetters := {"A", "B", "C"}
MsgInfo("Second element: " + aLetters[2])
MsgInfo("Count: " + CValToChar(Len(aLetters)))
ReturnExpected result
Index 2 returns B and Len() reports three elements.
Dynamic inclusion with AAdd
User Function ExAppend()
Local aLetters := {"A", "B", "C"}
AAdd(aLetters, "D")
MsgInfo("Last element: " + aLetters[Len(aLetters)])
ReturnExpected result
AAdd() appends D and Len() supplies the current last position.
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
ReturnExpected result
Constants give semantic names to the positions holding name, age and status.
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
ReturnExpected result
Each inner array is a row. The loop iterates over people and accesses columns through constants.
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
ReturnExpected result
The condition prevents access outside the current array bounds.
- 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.
- 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.