Click or drag to resize

AScanBin Function

X#
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
Request Example View Source

Parameters

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 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:
X#
 1aArray := {"Tom", "Mary", "Sue"}
 2ASort(aArray)
 3? AScanBin(aArray, "Mary")                // 1
 4? AScanBin(aArray, "mary")                // 0
 5? AScanBin(aArray, ;
 6        {|x| MyCompare(x, "MARY")})        // 1
 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        // ELSE defaults to the initial value of 0
15    ENDIF
16    RETURN siRet
See Also