Description: This function locates a text string, returning the offset of the first matching string in a buffer.
Returns: Numeric
Usage: Script or Steady State
Format: Locate(Buffer, Offset, Search [, Method])
Parameters: Buffer { buffer } { required } { no default }
The text expression to search.
Offset { numeric } { required } { no default }
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).
Search { text } { required } { no default }
Any text expression for which to search.
Method { numeric } { optional } { default: 0 }
An optional parameter that controls how the Search parameter is interpreted as follows:
|
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. |
The default value for Method is "0".
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.
Locate() supports case-insensitive search, which is specified by using Offset < 0. The real start is then calculated by subtracting it from –1.
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.
See Also: