AScan Function (Array, Usual, Usual, Usual) |  |
Scan an array until a value is found or a code block returns TRUE.
Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.19
SyntaxFUNCTION AScan( aTarget AS ARRAY, uSearch AS USUAL, nStart AS USUAL, nCount AS USUAL ) AS DWORD
Parameters
- aTarget
- Type: Array
The array to scan. - uSearch
- Type: Usual
The value to scan for.
Unless this argument is a code block, it must match the data type of the elements in aTarget. - nStart
- Type: Usual
The starting element.
A negative value starts from the end.
If nCount is positive, the default value is 1; if nCount is negative, the default value is the length of the array. - nCount
- Type: Usual
The number of elements to process from nStart.
A negative value starts from the end.
The default is all elements to the end of the array.
Return Value
Type: DWordIf uSearch is a code block, AScan() returns the position of the first element for which the code block returns TRUE.
Otherwise, AScan() returns the position of the first matching element.
AScan() returns 0 if no match is found
Remarks
If uSearch is not a code block, its value is compared to the first target element.
If there is no match, AScan() proceeds to the next element in the array.
This process continues until either a match is found or the range of elements to scan is exhausted.
If uSearch is a code block, AScan() scans aTarget, executing the code block for each element accessed.
As each element is encountered, AScan() passes the element's value as an argument to the code block, then performs an Eval() on the code block.
The scanning operation stops when the code block returns TRUE or when the range of elements to scan is exhausted.
If there is no match, AScan() proceeds to the next element in the array.
This process continues until either a match is found or the range of elements to scan is exhausted.
If uSearch is a code block, AScan() scans aTarget, executing the code block for each element accessed.
As each element is encountered, AScan() passes the element's value as an argument to the code block, then performs an Eval() on the code block.
The scanning operation stops when the code block returns TRUE or when the range of elements to scan is exhausted.
 Tip |
|---|
|
Values are compared using the = operator. For exact matching (that is, using the == operator), use AScanExact(). |
Examples
This example demonstrates scanning a 3-element array, using both a string and a code block as search criteria.
The code block criteria shows how to perform a case-insensitive search:
This example demonstrates scanning for multiple instances of a search argument after a match is found:
This example scans a 2-dimensional array using a code block. Note that the argument aVal in the code block is an array:
The code block criteria shows how to perform a case-insensitive search:
X#
1aArray := {"Tom", "Mary", "Sue"} 2? AScan(aArray, "Mary") // 2 3? AScan(aArray, "mary") // 0 4? AScan(aArray, ; 5 {|x| Upper(x) = "MARY"}) // 2
X#
1LOCAL aArray := {"Tom", "Mary", "Sue", "Mary"} 2LOCAL nStart := 1 3LOCAL iAtEnd, iPos AS INT 4// Get last array element position 5iAtEnd := 4 6DO WHILE (iPos := AScan(aArray, "Mary", nStart)) > 0 7 ? iPos, aArray[iPos] 8 // Get new starting position and test boundary condition 9 IF (nStart += iPos) > iAtEnd 10 EXIT 11 ENDIF 12ENDDO
X#
1LOCAL aArr := {} 2AAdd(aArr,{"one", "two"}) 3AAdd(aArr,{"three", "four"}) 4AAdd(aArr,{"five", "six"}) 5? AScan(aArr, {|aVal| aVal[2] = "four"}) // 2
See Also