AINS()
 Insere um elemento NIL em um vetor
------------------------------------------------------------------------------

 Sintaxe

     AINS(<aDestino>, <nPosiçao>) --> aDestino

 Argumentos

     <aDestino> é o vetor no qual um novo elemento será inserido.

     <nPosiçao> é a posiçao na qual o novo elemento será inserido.

 Retorno

     AINS() retorna uma referência ao vetor destino, <aDestino>.

 Descriçao

     AINS() é uma funçao de vetor que insere um novo elemento em um vetor
     especificado.  O elemento recém inserido é NIL até que um novo valor
     seja atribuido a ele.  Após a inserçao, o último elemento no vetor é
     descartado, e todos os elementos depois do novo elemento descem uma
     posiçao.

     -----------------------------------------------------------------------
     . Aviso

     AINS() deve ser utilizado com cuidado quando se tratar de vetores
     multi-dimensionais.  Vetores multi-dimensionais em Clipper sao
     implementados através do aninhamento de vetores dentro de outros
     vetores.  Utilizar AINS() com um vetor multi-dimensional descarta o
     último sub-vetor no vetor destino especificado, o que causa a perda de
     uma ou mais dimensoes.  Para inserir uma nova dimensao em um vetor,
     primeiramente adicione um novo elemento ao final do vetor utilizando
     AADD() ou ASIZE() antes de usar AINS().
     -----------------------------------------------------------------------

 Exemplos

     Este exemplo demonstra o efeito da utilizaçao de AINS() em um vetor:

     LOCAL aArray
     aArray := { 1, 2, 3 }          // Resulta: aArray e agora { 1, 2, 3 }
     AINS(aArray, 2)                // Resulta: aArray e agora { 1, NIL, 2 }

 Arquivos:  Biblioteca CLIPPER.LIB.
 To download this example - click here.

See Also: AADD() ACOPY() ADEL() AEVAL() AFILL() ASIZE()