BINSEARCHX

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


>>-BINSEARCHX(x,p,f-+-----------+-)----------------------------><
                    '-,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.
p: An expression that specifies the address of the key value to be searched for.
f: An expression that specifies the function that will be invoked to perform all the required comparisons.
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 function f must have the OPTLINK linkage and it is passed 2 POINTER BYVALUE arguments:

The address of an array element.
The address of the key value to be searched for (the value of p).

The function f must have the attributes RETURNS( BYVALUE FIXED BINARY(31) ), and it must return one of the values -1, 0 or +1:

If the value of the array element is less than the value of the key element, then the returned value must be -1.
If the value of the array element is equal to the value of the key element, then the returned value must be 0.
If the value of the array element is greater than the value of the key element, then the returned value must be +1.

The value returned by the BINSEARCHX built-in function itself 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.

Published: 23 December 2018