Busca em um array até que o bloco retorne verdadeiro .T.
Sintaxe
ASCAN( aOrigem, expSearch, [ nStart ], [ nCount ]) –> nStoppedAt
Argumento/Descrição
<aOrigem> Obrigatório, Array. É o array onde será executada a expressão.
<expSearch> Obrigatório, Qualquer Tipo. Casis 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 thelast element scanned. If <expSearch> is a simple value, ASCAN() returnsthe position of the first matching element, or zero if a match is notfound. If <expSearch> is a code block, ASCAN() returns the position ofthe element where the block returned true (.T.).
Description
ASCAN() is an array function that scans an array for a specified valueand operates like SEEK when searching for a simple value. The<expSearch> value is compared to the target array element beginning withthe leftmost character in the target element and proceeding until thereare 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 issensitive to the status of EXACT. If EXACT is ON, the target arrayelement 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 isencountered, ASCAN() passes the element’s value as an argument to thecode block, and then performs an EVAL() on the block. The scanningoperation 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
See Also