ArraySearch

Searches a one or two dimension array for an element that matches a value.

Syntax:

ArraySearch ( array, value [, options [, search-column [, start-sub [, end-sub ]]]])

Parameters:

(a) array: specifies an array.

(u/s/i/f) value: value to search for in "array".

(i) options: [optional] specifies a search type. See below.

(i) search-column: [optional] subscript of column to search for two-dimensional arrays. The default is zero. Always use zero when searching one dimensional arrays.

(i) start-sub: [optional] subscript of first element or row to include in search. The default is zero.

(i) end-sub: [optional] subscript of last element or row to include in search. The default is ArrInfo(array,1)-1.

Returns:

(i) index: the index of the found element of a single dimension array, the index of the row containing the found element of two dimension array , or -1 if the value is not found.

Duplicates:

This function will not necessarily locate the item with the lowest index of a set of duplicates. To find every occurrence of a duplicate value, you must search in both directions from the first found item. A linear search is the preferred method to find every occurrence of a value, unless you have a very large data set.

Options:

Option	Meaning
0	Linear search matching case (the default). A sequential search method for finding a value in an array. Checking each of its elements in sequence, until the desired one is found. If your intent is to locate all duplicate items then a linear search is recommended.
1	Fast binary search on a sorted "search-column". This function can optionally search using a fast binary search but the array must first be sorted on "search-column' using the ArraySort function.
2	Linear search ignoring case. A sequential search method for finding a value in an array. Checking each of its elements in sequence, until the desired one is found. If your intent is to locate all duplicate items then a linear search is recommended.
3	Fast binary search ignoring case. This function can optionally search using a fast binary search but the array must first be sorted on "search-column' using the ArraySort function.
@Stringsort	Search arrays pre-sorted by the ArraySort function using the @Stringsort option. With the pre-sort, all array elements were treated as text and compared character by character. Character code point values were used for comparisons without consideration of written language syntax or semantics. See ArraySort function for further details. The array must be sorted in ascending order and the search is always case-sensitive. This option cannot be combined with any other search options. The decimal place display setting for floating point numbers as set by calling the 'Decimals' function can influence the search result when searching for floating point numbers. The decimal place display setting must be kept the same for sorting and then searching an array when using these options with floating point numbers as array elements or as the searched for item.
@LogicalSort	Search arrays pre-sorted by the ArraySort function using the @Logicalsort option. With the pre-sort, all array elements were sorted using a logical string comparison. Digits in strings were treated as numerical content rather than text and comparisons are not case-sensitive. See ArraySort function for further details. The array must be sorted in ascending order and the search is not case-sensitive. The option cannot be combined with any other search options and requires Windows XP/2003 or newer. The decimal place display setting for floating point numbers as set by calling the 'Decimals' function can influence the search result when searching for floating point numbers. The decimal place display setting must be kept the same for sorting and then searching an array when using these options with floating point numbers as array elements or as the searched for item.

Multidimensional arrays in WinBatch use 'Row Major' format. For Example: arrMyArray[ row_index , column_index ]

Note: This function ignores embedded arrays and their elements.

Examples:

strList = 'a b c A B C 1 0 -1'
value = 'C' ; (uppercase letter C)
; Create an array to search
arrList = Arrayize( strList, ' ' )
; Search the array
result = Arraysearch( arrList, value, 0, 0, 0, ArrInfo(arrList,1)-1)
; Display results ( expect 5 )
Pause( 'ArraySearch of value: ' : value, 'Element number: ' : result )
Exit