aDestinoArrayObrigatório
Array que receberá o novo elemento. A estrutura é alterada e passa a ter Len(aDestino) + 1 posições.
FUNçãOPublicado
AAdd
AAdd( <aDestino>, <xExpressao> ) → xExpressaoAdiciona um elemento ao final de um array e aumenta seu tamanho em uma posição.
Visão geral
AAdd() inclui um novo elemento na última posição de um array. O elemento recebe o valor de qualquer expressão AdvPL válida, inclusive outro array, e a função retorna o próprio valor adicionado. É especialmente útil para montar listas, filas, linhas de uma matriz e estruturas dinâmicas cujo tamanho não é conhecido antecipadamente.
Sintaxe
AAdd( <aDestino>, <xExpressao> ) → xExpressaoParâmetros
xExpressaoQualquerObrigatório
Valor atribuído à nova última posição. Pode ser caractere, número, data, lógico, objeto, bloco ou outro array.
Retorno
Retorna o valor informado em xExpressao. O retorno não é necessariamente o array de destino.
Adição de elementos em um vetor
User Function ExAAddNomes()
Local aNomes := {}
AAdd(aNomes, "Ana")
AAdd(aNomes, "Bruno")
AAdd(aNomes, "Carla")
MsgInfo(aNomes[3], "Terceiro nome")
ReturnResultado esperado
O array passa a conter três elementos; a posição 3 contém “Carla”.
Construção de uma matriz
User Function ExAAddPessoas()
Local aPessoas := {}
Local nPessoa := 0
AAdd(aPessoas, {"Ana", 29})
AAdd(aPessoas, {"Bruno", 34})
AAdd(aPessoas, {"Carla", 27})
For nPessoa := 1 To Len(aPessoas)
ConOut(aPessoas[nPessoa][1] + ;
" tem " + cValToChar(aPessoas[nPessoa][2]) + " anos")
Next nPessoa
ReturnResultado esperado
Cada elemento do array principal é uma linha com nome e idade, formando uma matriz de três linhas.
Valor retornado e referência de array
User Function ExAAddReferencia()
Local aDestino := {}
Local aLinha := {"Produto", 10}
Local xRetorno := AAdd(aDestino, aLinha)
aLinha[2] := 20
ConOut(xRetorno[2]) // 20
ConOut(aDestino[1][2]) // 20
ReturnResultado esperado
O retorno é a linha adicionada. Como aLinha foi armazenada por referência, a alteração também é observada em aDestino[1].
- Use Len(aDestino) depois da inclusão para obter a nova quantidade de elementos.
- Quando xExpressao é outro array, AAdd() armazena uma referência a ele. Alterações posteriores no array de origem podem aparecer dentro do array de destino.
- Se precisar de uma cópia independente do array inserido, avalie AClone() antes de adicioná-lo.
- AAdd() sempre acrescenta no final. Para inserir em uma posição existente, estude AIns(); para redimensionar diretamente, use ASize().
- Arrays AdvPL começam na posição 1.
- Não atribua aDestino := AAdd(aDestino, xValor). Como AAdd() retorna xValor, essa atribuição substituiria a variável do array pelo elemento adicionado.
- Adicionar linhas com formatos diferentes cria uma matriz irregular. Defina e documente a estrutura esperada para cada posição.
- Crescimento ilimitado dentro de loops pode consumir muita memória. Quando possível, filtre na origem, processe em lotes ou dimensione a estrutura previamente.
- AAdd() altera o array recebido. Considere esse efeito quando a mesma referência for compartilhada entre funções.