$instr function

$instr(start,string,find)

The $instr function returns the 1-based index of the first occurrence of find in string starting from position start, or 0 (zero) if find is not found or an error occurs. The search for find is case-insensitive.

If start is negative, the search takes place from the end of string rather than from the start, goes backward, and finds the last occurrence of find at or before position length(string) + (start + 1) in the string (i.e., counting from the end of string).

The return value is the first that applies from the following:

If string is empty or abs(start) is greater than the length of string, the result is 0 (zero);
If find is empty, the result is start if start is positive, or length(string) + (start + 1) if start is negative;
If find is not found, the result is 0 (zero);
The 1-based index of the first occurrence of find in string at or after position start if start is positive, or the 1-based index of the last occurrence of find in string at or before position length(string) + (start + 1) if start is negative.

Tip: Because an unmatched search returns 0 (zero), you can use the $instr function as part of conditional expressions. An unmatched search will then evaluate to False; a matched search (in any position) to True.

Parameters

All parameters may contain symbolic references; these are resolved before the function is applied. See Examples below.

start: The 1-based starting position for the search. Missing values and 0 are treated as 1 (one); negative values cause the search to go backward from the end of string instead of the beginning.
string: String to search for occurrence of find.
find: Substring to search for in string.

Examples

Here are some usage examples for this function:

<$instr(1, C:\Program Files\InstallMate\Bin\Tin.exe, in)>: Returns 18, the starting index of the first occurrence of in in the path (i.e., the start of InstallMate; the search is not case sensitive).
<$instr(, C:\Program Files\InstallMate\Bin\Tin.exe, in)>: Same as previous one; the missing starting index defaults to 1 (note the comma at the start, which is required even if you don't provide a value for start).
<$instr(18, C:\Program Files\InstallMate\Bin\Tin.exe, in)>: Still returns 18, because the search really starts at the start index.
<$instr(19, C:\Program Files\InstallMate\Bin\Tin.exe, in)>: Returns 31, the starting index of in in the Bin portion of the path.
<$instr(40, C:\Program Files\InstallMate\Bin\Tin.exe, in)>: Returns 0, because there are no occurrences of in in the path from index 40 onwards.
<$instr(50, C:\Program Files\InstallMate\Bin\Tin.exe, in)>: Returns 0, because the path is not even as long as 50 characters.
<$instr(-1, C:\Program Files\InstallMate\Bin\Tin.exe, in)>: Returns 35, the first occurrence of in (in Tin.exe) searching backward from the first character from the end of the path.
<$instr(, C:\Program Files\InstallMate\Bin\Tin.exe, micro)>: Returns 0, because the path does not contain the string micro.
<$instr(, C:\Program Files\InstallMate\Bin\Tin.exe, <NoneSuch>)>: Probably returns 1, the first occurrence of the empty search string in the path. This assumes that <NoneSuch> refers to a non-existing or empty symbolic variable. It is not a very useful example, but it illustrates what may happen if the find argument is a symbolic expression that resolves to an empty string (which includes undefined variables).
<$instr(16, C:\Program Files\InstallMate\Bin\Tin.exe, <NoneSuch>)>: Returns 16, the first occurrence of the empty search string in the path from position 16 onwards. This shows that the search for an empty string either yields the start index, or 0 (zero) if the start index exceeds the length of the string in which to search. It illustrates that you should be careful about the find argument, because accidentally using an empty string for that argument might lead to a false positive.