ASCAN()
 Varre um vetor procurando um valor ou até que um bloco retorne verdadeiro
 (.T.)
------------------------------------------------------------------------------

 Sintaxe

     ASCAN(<aDestino>, <ProcuraExp>,
        [<nInicio>], [<nCont>]) --> nParouEm

 Argumentos

     <aDestino> é o vetor a ser varrido.

     <ProcuraExp> pode ser um valor simples a ser procurado, ou um bloco
     de código.  Caso <ProcuraExp>  seja um valor simples, este poderá
     ser do tipo numérico, lógico, data, ou caractere.

     <nInicio> é o elemento a partir do qual terá início a pesquisa.  Se
     este argumento nao for especificado, a posiçao inicial padrao é um.

     <nCont> é a quantidade de elementos que serao varridos a partir da
     posiçao inicial.  Caso este argumento nao seja especificado, todos os
     elementos, desde o elemento inicial até o final do vetor, serao
     varridos.

 Retorno

     ASCAN() retorna um valor numérico que representa a posiçao ocupada no
     vetor pelo último elemento varrido.  Se <ProcuraExp> for um valor
     simples, ASCAN() retorna a posiçao do primeiro elemento que
     corresponder ao valor procurado, ou zero caso nao haja
     correspondência.  Se <ProcuraExp> for um bloco de código, ASCAN()
     retorna a posiçao do elemento onde o bloco retornou verdadeiro (.T.).

 Descriçao

     ASCAN() é uma funçao de tratamento de vetor que varre um vetor
     procurando um valor especificado e opera da mesma forma que o comando
     SEEK quando pesquisa um valor simples.  O valor <ProcuraExp> é
     comparado ao elemento de vetor destino que começa com o caractere mais
     à esquerda no elemento destino e prossegue até que nao haja mais nenhum
     caractere em <ProcuraExp>.  Caso nao haja correspondência, ASCAN() vai
     para o próximo elemento no vetor.

     Como ASCAN() utiliza o operador (=) para comparaçoes, ele é sensível ao
     status de EXACT.  Caso EXACT esteja ON, o elemento de vetor destino
     deve ser exatamente igual ao resultado de <ProcuraExp> para que haja
     correspondência.

     Se o argumento de <ProcuraExp> seja um bloco de código, ASCAN() varre o
     vetor <aDestino> executando o bloco para cada elemento acessado.  Ù
     medida em que cada elemento é encontrado, ASCAN() passa o valor do
     elemento como um argumento para o bloco de código, e depois executa um
     EVAL() no bloco.  A operaçao de pesquisa pára quando o bloco de código
     retorna verdadeiro (.T.), ou quando ASCAN() atinge o último elemento no
     vetor.

 Exemplos

       O exemplo a seguir demonstra a pesquisa em um vetor de três
        elementos utilizando valores simples e um bloco de código como
        critérios de pesquisa.  Os critérios do bloco de código ilustram
        como executar uma pesquisa que nao faz diferenciaçao entre
        maiúsculas e minúsculas:

        aArray := { "Tom", "Mary", "Sue" }
        ? ASCAN(aArray, "Mary")                      // Resulta: 2
        ? ASCAN(aArray, "mary")                      // Resulta: 0
        //
        ? ASCAN(aArray, { |x| UPPER(x) == "MARY" })  // Resulta: 2

       Este exemplo demonstra como continuar a pesquisa dos
        múltiplos tipos de um argumento de pesquisa após ter sido encontrada
        uma correspondência:

        LOCAL aArray := { "Tom", "Mary", "Sue", "Mary" }, nStart := 1
        //
        // Pegar ultima posicao de elemento de vetor
        nAtEnd := LEN(myVetor)
        WHILE (nPos := ASCAN(aArray, "Mary", nStart)) > 0
           ? nPos, aArray[nPos]
           //
           // Pegar nova posicao inicial e testar condicao de limite
           IF (nStart := ++nPos) > nAtEnd
              EXIT
           ENDIF
        ENDDO

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

See Also: AEVAL() EVAL()