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

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


     <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.


     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.).


     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.


     .  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

     .  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:={}
        ? ASCAN(aArr, {|aVal| aVal[2] == "four"})         // Returns 2

 Files   Library is CLIPPER.LIB.

See Also: AEVAL() EVAL()


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.