Advertisements
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.
See Also: AEVAL() EVAL()
Advertisements