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.
- x
- An expression that specifies the target array that would be searched within. x must be a one-dimensional array of scalars 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.