Histórico da Página

Sintaxe

ASCAN( <array>, <expressão>   [ , <expressão numérica 1> ]   [ , <expressão numérica 2> ... ] )

Propósito

Pesquisa um determinado valor ou avalia um bloco de código pelos elementos de um array.

Argumentos

< array >

Define o nome do array que será pesquisado.

< expressão  >

Define o valor que será pesquisado ou o bloco de código a ser avaliado.

Pode ser uma expressão que resulta em qualquer tipo de dado.

< expressão numérica 1 >

Define o número do primeiro elemento a ser pesquisado. Se não for especificado, será assumido o primeiro elemento do array.

< expressão numérica 2 >

Define a quantidade de elementos que serão pesquisados a partir do elemento definido pela expressão numérica 1. Se este argumento não for especificado, serão pesquisados todos os elementos do array a partir do elemento inicial definido pela expressão numérica 1.

Utilização

Utiliza-se a função ASCAN() quando é necessário descobrir o número do elemento de um array que possui um determinado conteúdo ou para o qual um bloco de código resulte verdadeiro (.T.).

A função ASCAN() fornece o número do primeiro elemento que possui o conteúdo pesquisado ou para o qual o bloco de código especificado torne-se verdadeiro. Se não for encontrado nenhum elemento com o valor especificado, ou se o bloco de código não se tornar verdadeiro, a função ASCAN() fornece o valor zero.

Quando estiver sendo pesquisado um valor, a função ASCAN() funciona como uma função dbSeek() sobre um array. O valor especificado pela expressão é comparado com o conteúdo de cada elemento do array. Se for encontrado um elemento que contenha um valor coincidente, a sua posição é fornecida. Se não for encontrado, é fornecido o valor zero.

Se o argumento de pesquisa for um bloco de código, a função ASCAN() executa o bloco de código para cada elemento do array dentro da faixa especificada. O valor do elemento é passado para o bloco de código, sendo executada então uma avaliação do bloco de código para esse valor. A pesquisa termina quando o bloco de código for avaliado como verdadeiro para um elemento, fornecendo o seu número, ou quando é atingido o último elemento especificado, fornecendo o valor zero.

Dicas

A função ASCAN() equivale à seguinte função de usuário:

FUNCTION PesqArr(aVetor, xDado, nInicio, nContador)

LOCAL nCont := 0

FOR nCont := nInicio To (nInicio + nContador – 1)

          IF aVetor[nCont] == xDado

                  RETURN nCont

          ENDIF

NEXT nCont

RETURN 0

Exemplos

O exemplo abaixo demonstra a pesquisa do conteúdo “AdvPL” em um array:

LOCAL aVetor := { “Java”, “AdvPL”, “C++” }

LOCAL nPos   := ASCAN(aVetor, “AdvPL” }

// Mostra o número do elemento no qual a expressão foi encontrada. Ou seja, mostra 2

MSGALERT( “Posição: “ + STR(nPos) )

// Mostra o conteúdo do elemento no qual a expressão foi encontrada. Ou seja, mostra AdvPL

MSGALERT( “Conteúdo: “ + aVetor[nPos] )

O exemplo abaixo demonstra a pesquisa em um array de três elementos utilizando valores simples e um bloco de código como critério de pesquisa. Os critérios do bloco de código ilustram como executar uma pesquisa sem fazer diferenciação entre maiúsculas e minúsculas:

LOCAL aArray := { "Tom", "Mary", "Sue" }

MSGALERT( ASCAN(aArray, "Mary") )                     // Resulta: 2

MSGALERT( ASCAN(aArray, "mary") )                     // Resulta: 0

MSGALERT( ASCAN(aArray, { |x| UPPER(x) == "MARY" }) )    // Resulta: 2