This statement searches for the item SearchExpression, inside ArrayExpression. The ArrayFindNext statement uses the index parameters returned by a previous ArrayFind statement as the place to start searching from.

SearchOrderExpression can take one of the following values:

• 0 The array is sorted in ascending order. ArrayFind uses a binary chop search.
• 1 The array is sorted in descending order. ArrayFind uses a binary chop search.
• 2 ArrayFind assumes the array is unsorted and searches from the beginning forwards.
• 3 ArrayFind assumes the array is unsorted and searches from the end backwards.
• +4 Ignore case in string searches.
• +8 Return IndexItems as the place to insert a new item, rather than zeroes for the IndexItems.

ColumnExpression specifies the element in the rightmost dimension that is searched in multi-dimensional arrays. If omitted or zero, every element is searched.

If a case insensitive search on a string array is required, add 4 to SearchOrderExpression.

V6 further allows the option to return the place in a sorted array where the test item would be inserted, rather than zeroes in the IndexItem parameters. Add 8 to the SearchOrderExpression parameter. SysError is returned as 1 if the array does not contain the item, otherwise zero.

If the item is not found, SysError is set to a nonzero value and zero is returned in the four final parameters if supplied. Otherwise, SysError is set to zero, and the index in each array dimension is returned in the four final parameters. Note that in order for ArrayFindNext to work, you must supply an argument to receive the array index for each significant dimension in the array.

ArrayFindNext only works in unsorted arrays, and otherwise returns not found.

This is useful in order to find out where to insert a new item in a sorted array.

The following example finds all instances of "hello" in any case. The SearchOrderExpression has a value of 6, 2 for the search order + 4 so that the search is case insensitive:

string s[], target

| populate s[]

target = "hello"
ArrayFind s, target, 6, idx

while not SysError

print idx
ArrayFindNext s, target, 6, idx

end while

The following example searches in the second column of the two dimensional array for 42:

number values[100][2]
int col1, col2, i

RndStart 3, 20

| populate values[][]

for i = 1 to 100

values[i] = i, Rnd(40)

next

ArraySort values, 2
ArrayFind values, 42, 0, 2, col1, col2

If SysError then print "Not found" else print "Found at [";col1;"][";col2;"]",values[col1][col2]

The following example shows how to use the 2 new additions to SearchOrderExpression:

procedure InsertIntoSortedArray int array[], int value, logical descending

int idx, n

ArrayFind array, value, 8 + descending,, idx

| Would create a de-duplicated array
| if SysError = 0 then return
ArrayGetDimensions array, n
n += 1
ArraySetDimensions 1, array, n

if idx <= n then Vector(array, idx + 1) = Vector(array, idx, n - idx)
array[idx] = value

end procedure | InsertIntoSortedArray