TextSearch

(Engine-Level Function)

Description:	Returns the array index of the first occurrence of the given text key in an alphabetically ordered array.
Returns:	Numeric
Usage:	Script or steady state.
Function Groups:	Array, String and Buffer
Related to:	ArrayStart \| ArraySize \| LookUp
Format:	TextSearch(ArrayElem, N, Text, Case, TypeText, Locale, CmpFlags)
Parameters:

ArrayElem

Required. Any array element giving the starting index for the array operation. The index for the array may be any numeric expression.

If processing a multidimensional array, the usual rules apply to decide which dimension should be used.

Required. Any numeric expression for the number of array elements to search.

If N plus the starting element is larger than the size of the remaining array, then this function will "wrap around" to restart at the first element. For this to have any useful result, the array would need to be sorted to match before running TextSearch.

Text

Required. Any text string to search for. Does not take an expression.

Case

Required. Any logical expression. If true, the search is case-sensitive. Otherwise, the search is case-insensitive.

TypeText

Optional. A numeric expression that controls the type of sort according to the following table. Defaults to zero - numeric sorting.

TypeText	Sort Performed
0	Reserved
1	Alphabetic sort
2	Reserved
3	Lingual sort
4	Reserved

Locale

Optional. A valid locale name (en-US or fr-FR). Additional modifiers are also allowed such as zh-CN_stroke (Chinese sorting using stroke order)

CmpFlags

A set of flags directing how the comparison should be done, as described in https://docs.microsoft.com/en-us/windows/desktop/api/stringapiset/nf-stringapiset-comparestringex

Supported flags include:

#NORM_IGNORECASE

#NORM_IGNORENONSPACE

#NORM_IGNORESYMBOLS

#LINGUISTIC_IGNORECASE

#LINGUISTIC_IGNOREDIACRITIC

#NORM_IGNOREKANATYPE

#NORM_IGNOREWIDTH

#NORM_LINGUISTIC_CASING

#SORT_DIGITSASNUMBERS

#SORT_STRINGSORT

Comments:

If the key is not found in the array, the function returns invalid. Notice that the array (or the elements being searched in the array) must be in ascending alphabetical order for this statement to return a valid value.

Do not mix sorting modes.
In particular, if you Sort an array and then use TextSearch on it, you must ensure that each uses the same sorting mode with the same locale.

Example:

index = TextSearch(dataArray[0] { Start of search in array },
                   ArraySize(dataArray, 0)
                   { Search all elements },
                   "green" { Text string to search for },
                   0 { Case insensitive search });

Given that dataArray is an array of text strings of various color names, index will be set to the subscript of the array element whose entry is "green".