ASCAN()
 Examina una matriz, buscando un valor determinado o hasta que un bloque
 devuelva el valor verdadero (.T.)
------------------------------------------------------------------------------
 Sintaxis

     ASCAN(<aDestino>, <expBúsqueda>,
        [<nInicio>], [<nPosiciones>]) --> nParadaEn

 Argumentos

     <aDestino> es la matriz que se va a examinar.

     <expBúsqueda> es el valor de tipo simple que se va a buscar o un
     bloque de código. Si <expBúsqueda> es un valor simple, puede ser de
     tipo carácter, fecha, lógico o numérico.

     <nInicio> es el elemento donde se inicia la búsqueda. Si no se
     especifica este argumento, la posición inicial por defecto es uno.

     <nPosiciones> es el número de elementos que se van a examinar a
     partir de la posición inicial. Si no se especifica este argumento, se
     examinan todos los elementos, desde el elemento inicial hasta el final
     de la matriz.

 Devuelve

     ASCAN() devuelve un valor numérico que representa la posición en la
     matriz del último elemento examinado. Si <expBúsqueda> es un valor
     simple, ASCAN() devuelve la posición del primer elemento que coincida,
     o cero si no se encuentra ninguno. Si <expBúsqueda> es un bloque de
     código, ASCAN() devuelve la posición del elemento donde el bloque
     devuelve verdadero (.T.).

 Descripción

     ASCAN() es una función de matrices que busca un valor especificado en
     una matriz. Funciona como SEEK cuando se busca un valor simple. El
     valor de <expBúsqueda> se compara con los elementos de la matriz de
     destino, empezando por el carácter situado más a la izquierda de cada
     elemento y continuando hasta que no queden más caracteres en
     <expBúsqueda>. Si no encuentra ninguna coincidencia, ASCAN() continúa
     en el siguiente elemento de la matriz.

     Como ASCAN() utiliza el operador igual (=) para las comparaciones, su
     resultado depende del estado de EXACT. Si EXACT está activado, el
     elemento de matriz destino debe ser exactamente igual que el resultado
     de <expBúsqueda> para que sean coincidentes.

     Si el argumento <expBúsqueda> es un bloque de código, ASCAN() examina
     la matriz <aDestino> ejecutando el bloque para todos los elementos a
     los que accede. A medida que encuentra cada elemento, ASCAN() pasa como
     argumento el valor del elemento al bloque de código y ejecuta una
     función EVAL() sobre el bloque. La operación de búsqueda se detiene
     cuando el bloque de código devuelve verdadero (.T.) o cuando ASCAN()
     llega al último elemento de la matriz.

 Ejemplos

      El ejemplo siguiente muestra el examen de una matriz de tres
        elementos que contiene valores simples, con un bloque de código como
        criterio de búsqueda. El criterio del bloque de código muestra la
        forma de realizar una búsqueda que no diferencie mayúsculas y
        minúsculas:

        aMatriz := { "Tomás", "María", "Susana" }
        ? ASCAN(aMatriz, "María")                // Resultado: 2
        ? ASCAN(aMatriz, "maría")                // Resultado: 0
        //
        ? ASCAN(aMatriz, { |x| UPPER(x) ;
              == "MARIA" })                      // Resultado: 2

      El ejemplo siguiente muestra una búsqueda de apariciones
        múltiples de un argumento tras encontrar una coincidencia:

        LOCAL aMatriz := { "Tomás", "María", "Susana",;
                            "María" }, nInicio := 1
        //
        // Obtiene la posición del último elemento de la matriz
        nEnFin := LEN(aMatriz)
        DO WHILE (nPos := ASCAN(aMatriz, "María", ;
                            nInicio)) > 0
           ? nPos, aMatriz[nPos]
           //
           // Obtiene la nueva posición inicial y
           // comprueba la condición límite
           IF (nInicio := ++nPos) > nEnFin
              EXIT
           ENDIF
        ENDDO

      El ejemplo siguiente examina una matriz bidimensional
        utilizando un bloque de código. Observe que el parámetro aVal del
        bloque de código es una matriz:

        LOCAL aMat:={}
        CLS
        AADD(aMat,{"uno","dos"})
        AADD(aMat,{"tres","cuatro"})
        AADD(aMat,{"cinco","seis"})
        ? ASCAN(aMat, {|aVal| aVal[2] == "cuatro"})        // Devuelve 2

 Ficheros   La biblioteca asociada es CLIPPER.LIB.

 To download this example - click here.

See Also: AEVAL() EVAL()