BINSEARCH

BINSEARCH performs a binary search of an array for a specified key value by using a simple compare and returns a size_t value.


>>-BINSEARCH(x,y-+-----------+-)-------------------------------><
                 '-,n-+----+-'     
                      '-,m-'

x: An expression that specifies the target array that would be searched within. x must be a one-dimensional array and the elements of x must be in ascending order. If x is an array of NONVARYING BIT, it must be aligned.
y: An expression that specifies the key value to be searched for.
n: An expression that specifies the index of the first array element to be examined. It defaults to LBOUND(x).
m: An expression that specifies the number of to-be-examined array elements. The counting starts with the nth and defaults to HBOUND(x) – n + 1.

The elements of the array x and the key value must satisfy one of the following:

Both must be computational and neither are COMPLEX
Both must be POINTERs
Both must be HANDLEs to the same structure type
Both must be ORDINALs of the same type

The returned value is the relative index of the key value in this array. If the key value y is not found in the array, the returned size_t value is zero.

The relative index is the index if the array has a lower bound of 1. Therefore, the true index would be calculated as: the returned value + LBOUND(x) – 1. For example:

If the array x has a lower bound of 0 and upper bound of 11, then the returned value will range from 0 to 12 inclusive. If the returned value is non-zero, then the true index of the found value is the returned value minus 1.
If the array x has a lower bound of -12 and an upper bound of 12, then the returned value will range from 0 to 25 inclusive. If the returned value is non-zero, the true index of the found value is the returned value minus 13.