ASCAN()

Sintaxis

ASCAN( <array>, <expresión>   [ , <expresión numérica 1> ]   [ , <expresión numérica 2> ... ] )

Propósito

Busca un determinado valor o evalúa un bloque de código por los elementos de un array.

Argumentos

< array >

Define el nombre del array que se buscará.

< expresión  >

Define el valor que se buscará o el bloque de código que se evaluará.

Puede ser una expresión que resulta en cualquier tipo de dato.

< expresión numérica 1 >

Define el número del primer elemento que se buscará. Si no se especifica, se asumirá el primer elemento del array.

< expresión numérica 2 >

Define la cantidad de elementos que se buscarán a partir del elemento definido por la expresión numérica 1. Si no se especifica este argumento, se buscarán todos los elementos del array a partir del elemento inicial definido por la expresión numérica 1.

Utilización

Se utiliza la función ASCAN() cuando es necesario descubrir el número del elemento de un array que tiene un determinado contenido o para el cual un bloque de código resulte verdadero (.T.).

La función ASCAN() suministra el número del primer elemento que tiene el contenido consultado o para el cual se vuelva verdadero el bloque de código especificado. Si no se encuentra ningún elemento con el valor especificado, o si el bloque de código no se vuelve verdadero, la función ASCAN() suministra el valor cero.

Cuando se consulta un valor, la función ASCAN() tiene el comportamiento de una función dbSeek() sobre un array. El valor especificado por la expresión se compara con el contenido de cada elemento del array. Si se encuentra un elemento que contenga un valor coincidente, se suministra su posición. Si no se encuentra, se suministra el valor cero.

Si el argumento de búsqueda es un bloque de código, la función ASCAN() ejecuta el bloque de código para cada elemento del array dentro del intervalo especificado. El valor del elemento se pasa al bloque de código, ejecutándose entonces una evaluación del bloque de código para este valor. La búsqueda termina cuando el bloque de código se evalúa como verdadero para un elemento, suministrando su número, o cuando se alcanza el último elemento especificado, suministrando el valor cero.

Sugerencias

La función ASCAN() equivale a la siguiente función de usuario:

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

Ejemplos

El siguiente ejemplo muestra la búsqueda del contenido “AdvPL” en un array:

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

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

// Muestra el número del elemento en el cual se encontró la expresión. Es decir, muestra 2

MSGALERT( “Posición: “ + STR(nPos) )

// Muestra el contenido del elemento en el cual se encontró la expresión. Es decir, muestra AdvPL

MSGALERT( “Contenido: “ + aVetor[nPos] )

El siguiente ejemplo muestra la búsqueda en un array de tres elementos utilizando valores simples y un bloque de código como criterio de búsqueda. Los criterios del bloque de código ilustran cómo ejecutar una búsqueda sin hacer diferencia entre mayúsculas y 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.