Locate

(Engine-Level Function)

Description:	Locates a text string, returning the offset of the first matching string in a buffer.
Returns:	Numeric
Usage:	Script or steady state.
Function Groups:	String and Buffer
Related to:	CharCount \| BuffWrite
Format:	Locate(Buffer, Offset, Search [, Method])
Parameters:

Buffer

Required. The text expression to search.

Offset

Required. Any numeric expression giving the buffer offset (in characters or bytes), from which to start searching (i.e. to start at the beginning of the buffer, set this parameter to 0).

Required. Any text expression for which to search.

Method

An optional numeric expression that controls how the Search parameter is interpreted as per the following table. The default value for Method is "0".

Method	Description
0	Treat Search as the exact string for which to search (strstr).
1	Treat Search as the case-insensitive string for which to search (stristr).
2	Treat Search as a set of characters to match against (strpbrk).
3	Treat Search as a case-insensitive set of characters to match against.

Comments:

This function returns the buffer offset of the first string matching Search. If no match is found, or if the length of Search plus Offset is larger than the length of Buffer, -1 is returned. The return value could be used in the Offset parameter to perform successive searches.

This function can be used to perform fast table searches. Build a table in a text variable using BuffWrite. Make sure that all entries in the table are the same length. You can now use Locate to find the buffer offset of a matching text string.

Examples:

w = Locate("abcABCabc", 0, "bc"); 
x = Locate("abcABCabc", 2, "bc"); 
y = Locate("abcABCabc", 0, "Bc"); 
z = Locate("abcABCabc", 0, "X");

The values of w, x, y and z will be 1, 7, -1 and -1 respectively.