Page tree
Skip to end of metadata
Go to start of metadata

Percorre um array procurando por um valor especificado. Pode ser especificado um valor a ser buscado, ou pode ser informada uma condição de busca através de um bloco de código.

Sintaxe

AScan( < aDest >, < xExpr >, [ nStart ], [ nCount ] )

Parâmetros

Nome

Tipo

Descrição

Obrigatório

Referência

aDest

vetor

Indica o array a ser avaliado.

X

 

xExpr

qualquer

Indica a expressão de busca. Para um array de dimensão simples, pode ser colocado diretamente um valor a ser procurado. Para uma busca mais complexa ou para uma busca em array muti-dimensional, deve ser especificado um bloco de código.

X

 

nStart

numérico

Indica a partir de qual elemento será realizada busca. Por padrão a pesquisa inicia no elemento 1.

 

 

nCount

numérico

Indica por quantos elementos serão considerados na operação de busca. Caso não especificado, todos os elementos do array a partir da posição inicial de busca serão considerados.

 

 

Retorno

Nome

Tipo

Descrição

nRet

numérico

Caso o valor procurado seja encontrado, será retornado o número do elemento do array correspondente. Caso contrário, é retornado o valor 0 (zero).

Observações

Em uma busca utilizando um array de dimensão simples, a expressão de busca <xExpr> pode ser do tipo "C" (Caractere), "N" (Numérico), "D" (Data) ou "L" (Lógico). O array pode conter elementos de tipos variados, as comparações somente serão realizadas quando o elemento do array em questão for do mesmo tipo do conteúdo informado para busca. Quando realizada a busca por uma string, a determinação da igualdade entre a string informada para busca e a string do elemento do array está sujeita ao estado da definição SET EXACT do AdvPL, por padrão desligada – veja comportamento do operador "=" (igualdade simples) entre strings do AdvPL.

Caso a busca em questão seja feita em um array multi-dimensional (array de array(s)), ou a condição de busca seja mais complexa ou específica, até mesmo uma condição composta, podemos especificar em <xExpr> um bloco de código, que receberá como parâmetro um elemento por vez do array aDest, a partir da posição inicial de busca. O code-block deve retornar um valor lógico .T. (Verdadeiro) caso o elemento em questão seja o elemento desejado, e a condição de busca seja satisfeita, e quando isto acontecer, a função AScan retornará o número do elemento do array aDest que foi informado ao bloco de código que atendeu a condição de busca. Caso o bloco de código retorne .F. (Falso), indicando que o elemento informado não atende a condição de busca, será fornecido o proximo elemento do array e o bloco de código é avaliado novamente. A operação de busca é encerrada até que todos os elementos compreendidos pela parametrização nStart / nCount sejam vasculhados. Se nenhuma chamada do bloco de código retornar .T., a função AScan retornará 0, indicando que nenhum elemento pesquisado satisfez a condição de busca.

Exemplos

Exemplo 1
#DEFINE CRLF Chr(13)+Chr(10)
user function ascan1()
  Local aExemplo := { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }
  Local cMensagem := ""
  
  //+----------------------------------------------------------------------------+
  //|Exemplifica o uso da função AScan                                           |
  //+----------------------------------------------------------------------------+
  
  cMensagem += "Elemento 5 " + CRLF
  cMensagem += "Em " + cValToChar( AScan( aExemplo, 5 ) ) + CRLF
  cMensagem += "A partir da posição 6 em " + ;
               cValToChar( AScan( aExemplo, 5, 6 ) ) + CRLF
  cMensagem += "A partir da posição 1 procurados em 3 em " + ;
               cValToChar( AScan( aExemplo, 5, 6, 3 ) ) + CRLF
  //+----------------------------------------------------------------------------+
  //|Apresenta uma mensagem com os resultados obtidos                            |
  //+----------------------------------------------------------------------------+
Return MsgInfo( cMensagem, "Exemplo do AScan" )

Resultado do Exemplo

Abrangência

Microsiga Protheus 8.11, Protheus 10

Veja também

 

  • No labels