AScanBin Function | |
Scan a sorted array until a value is found or a code block returns 0.
Namespace:
XSharp.RT
Assembly:
XSharp.RT (in XSharp.RT.dll) Version: 2.19
Syntax FUNCTION AScanBin(
aTarget AS ARRAY,
uSearch AS USUAL
) AS DWORD
public static uint AScanBin(
Array aTarget,
Usual uSearch
)
Request Example
View SourceParameters
- aTarget
- Type: Array
The sorted 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.
If uSearch is a code block, it should return a numeric value that indicates the outcome of the comparison: a positive value indicates that uSearch is greater than the current array element, a 0 stands for equality, and a negative value indicates that uSearch is less than the current array element.
Return Value
Type:
DWord
If
uSearch is a code block, AScanBin() returns the position of the element if the code block returned a value of zero.
Otherwise, AScanBin() returns the position of a matching element.
If multiple occurrences of the same element exist, the returned match is not necessarily the lowest numbered element since AScanBin() uses a binary search algorithm.
AScanBin() returns 0 if no match is found.
Remarks
AScanBin() scans an array for a specified value.
If
uSearch is a code block, AScanBin() scans
aTarget, by using a binary search algorithm and executes the code block for each element accessed.
As each element is encountered, AScanBin() 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 a value of zero 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 AScanBinExact().
|
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:
1aArray := {"Tom", "Mary", "Sue"}
2ASort(aArray)
3? AScanBin(aArray, "Mary")
4? AScanBin(aArray, "mary")
5? AScanBin(aArray, ;
6 {|x| MyCompare(x, "MARY")})
7FUNCTION MyCompare(cElement, cSearch) AS SHORTINT
8 LOCAL siRet := 0 AS SHORTINT
9 cElement := Upper(cElement)
10 IF cSearch > cElement
11 siRet := 1
12 ELSEIF cSearch < cElement
13 siRet := -1
14
15 ENDIF
16 RETURN siRet
See Also