aMatrizArrayObrigatório
Variável que armazena a coleção.
FUNDAMENTOPublicado
Matrizes (arrays) em AdvPL
aMatriz := { <elemento1>, <elemento2>, ... } · aMatriz[nÍndice]Organize valores em listas simples ou multidimensionais, acesse posições e altere a estrutura dinamicamente.
Visão geral
Matrizes, também chamadas arrays, são coleções ordenadas de valores. Em AdvPL, o primeiro elemento ocupa a posição 1, e uma mesma matriz pode reunir caracteres, números, datas, lógicos, objetos, outros arrays e demais tipos. Arrays aninhados permitem representar linhas, colunas e estruturas compostas.
Sintaxe
aMatriz := { <elemento1>, <elemento2>, ... } · aMatriz[nÍndice]Parâmetros
nÍndiceNuméricoObrigatório
Posição do elemento, iniciada em 1 e limitada ao tamanho atual da matriz.
elementoQualquerOpcional
Valor armazenado; elementos da mesma matriz podem possuir tipos diferentes.
Criação, acesso e tamanho
User Function ExMatriz()
Local aLetras := {"A", "B", "C"}
MsgInfo("Segundo elemento: " + aLetras[2])
MsgInfo("Quantidade: " + CValToChar(Len(aLetras)))
ReturnResultado esperado
O índice 2 retorna B e Len() informa que a matriz possui três elementos.
Inclusão dinâmica com AAdd
User Function ExAdicionar()
Local aLetras := {"A", "B", "C"}
AAdd(aLetras, "D")
MsgInfo("Último elemento: " + aLetras[Len(aLetras)])
ReturnResultado esperado
AAdd() acrescenta D ao final; Len() fornece a posição atual do último elemento.
Estrutura com tipos diferentes
#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
ReturnResultado esperado
As constantes identificam semanticamente as posições que guardam nome, idade e situação.
Matriz multidimensional
#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
ReturnResultado esperado
Cada array interno representa uma linha. O laço percorre as pessoas e acessa cada coluna por uma constante.
Acesso protegido por índice
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
ReturnResultado esperado
A condição impede o acesso fora dos limites atuais da matriz.
- Use chaves para criar um array literal e colchetes para acessar uma posição.
- Len(aMatriz) informa a quantidade de elementos da dimensão consultada.
- AAdd(aMatriz, xValor) acrescenta um elemento ao final da matriz.
- Arrays multidimensionais podem ser acessados como aDados[nLinha, nColuna] ou aDados[nLinha][nColuna].
- Constantes #define podem dar nomes às posições de uma estrutura e tornar o código mais legível.
- Acessar uma posição menor que 1 ou maior que Len(aMatriz) provoca erro; valide o índice antes do acesso.
- Arrays muito grandes ou profundamente aninhados podem consumir memória significativa. Para volumes elevados, considere tabelas temporárias ou processamento em partes.
- A referência histórica menciona até 100.000 elementos nas versões listadas entre 5.07 e 8.11. Não trate esse número como limite universal: confirme-o no AppServer e na LIB utilizados.
- Ao representar registros por posições numéricas, mantenha constantes e documentação sincronizadas para evitar a leitura da coluna errada.
- Arrays podem conter tipos mistos, mas essa flexibilidade exige validação quando a rotina espera uma estrutura específica.