ASCAN()
 Scan an array for a value or until a block returns true (.T.)
------------------------------------------------------------------------------
 Syntax

     ASCAN(<aTarget>, <expSearch>,
        [<nStart>], [<nCount>]) --> nStoppedAt

 Arguments

     <aTarget> is the array to be scanned.

     <expSearch> is either a simple value to scan for, or a code block.
     If <expSearch> is a simple value it can be character, date, logical, or
     numeric type.

     <nStart> is the starting element of the scan.  If this argument is
     not specified, the default starting position is one.

     <nCount> is the number of elements to scan from the starting
     position.  If this argument is not specified, all elements from the
     starting element to the end of the array are scanned.

 Returns

     ASCAN() returns a numeric value representing the array position of the
     last element scanned.  If <expSearch> is a simple value, ASCAN() returns
     the position of the first matching element, or zero if a match is not
     found.  If <expSearch> is a code block, ASCAN() returns the position of
     the element where the block returned true (.T.).

 Description

     ASCAN() is an array function that scans an array for a specified value
     and operates like SEEK when searching for a simple value.  The
     <expSearch> value is compared to the target array element beginning with
     the leftmost character in the target element and proceeding until there
     are no more characters left in <expSearch>.  If there is no match,
     ASCAN() proceeds to the next element in the array.

     Since ASCAN() uses the equal operator (=) for comparisons, it is
     sensitive to the status of EXACT.  If EXACT is ON, the target array
     element must be exactly equal to the result of <expSearch> to match.

     If the <expSearch> argument is a code block, ASCAN() scans the <aTarget>
     array executing the block for each element accessed.  As each element is
     encountered, ASCAN() passes the element's value as an argument to the
     code block, and then performs an EVAL() on the block.  The scanning
     operation stops when the code block returns true (.T.), or ASCAN()
     reaches the last element in the array.

 Examples

     .  This example demonstrates scanning a three-element array using
        simple values and a code block as search criteria.  The code block
        criteria shows how to perform a case-insensitive search:

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

     .  This example demonstrates scanning for multiple instances of a
        search argument after a match is found:

        LOCAL aArray := { "Tom", "Mary", "Sue",;
                           "Mary" }, nStart := 1
        //
        // Get last array element position
        nAtEnd := LEN(aArray)
        DO WHILE (nPos := ASCAN(aArray, "Mary", ;
                     nStart)) > 0
           ? nPos, aArray[nPos]
           //
           // Get new starting position and test
           // boundary condition
           IF (nStart := ++nPos) > nAtEnd
              EXIT
           ENDIF
        ENDDO

     .  This example scans a two-dimensional array using a code block.
        Note that the parameter aVal in the code block is an array:

        LOCAL aArr:={}
        CLS
        AADD(aArr,{"one","two"})
        AADD(aArr,{"three","four"})
        AADD(aArr,{"five","six"})
        ? ASCAN(aArr, {|aVal| aVal[2] == "four"})         // Returns 2

 Files   Library is CLIPPER.LIB.