InStr

Searches for a given occurrence of a string, from the left or the right.

FoundPos := InStr(Haystack, Needle , CaseSense := false, StartingPos := 1, Occurrence := 1)

Parameters

Haystack

Type: String

The string whose content is searched.

Needle

Type: String

The string to search for.

CaseSense

Type: Integer or String

One of the following values (defaults to 0 if omitted):

"On" or 1 (True): The search is case sensitive.

"Off" or 0 (False): The letters A-Z are considered identical to their lowercase counterparts.

"Locale": The search is case insensitive according to the rules of the current user's locale. For example, most English and Western European locales treat not only the letters A-Z as identical to their lowercase counterparts, but also non-ASCII letters like Ä and Ü as identical to theirs. Locale is 1 to 8 times slower than Off depending on the nature of the strings being compared.

StartingPos

Type: Integer

If StartingPos is omitted, it defaults to 1 (the beginning of Haystack). Otherwise, specify 2 to start at the second character, 3 to start at the third, and so on.

If StartingPos is negative, the search is conducted in reverse (right-to-left), starting at that position from the right. For example, -1 starts at the last character. If StartingPos is 0 or beyond the length of Haystack, 0 is returned.

Regardless of the value of StartingPos, the return value is always relative to the first character of Haystack. For example, the position of "abc" in "123abc789" is always 4.

Occurrence

Type: Integer

If Occurrence is omitted, it defaults to the first match of the Needle in Haystack. Specify 2 for Occurrence to return the position of the second match, 3 for the third match, etc.

Return Value

Type: Integer

This function returns the position of an occurrence of the string Needle in the string Haystack. Position 1 is the first character; this is because 0 is synonymous with "false", making it an intuitive "not found" indicator.

Conventionally, an occurrence of an empty string ("") can be found at any position. However, as a blank Needle would typically only by passed by mistake, it is treated as an error (an exception is thrown).

Remarks

RegExMatch can be used to search for a pattern (regular expression) within a string, making it much more flexible than InStr. However, InStr is generally faster than RegExMatch when searching for a simple substring.

InStr searches only up to the first binary zero (null-terminator), whereas RegExMatch searches the entire length of the string even if it includes binary zero.

Related

RegExMatch, Is functions

Examples

#1

MsgBox InStr("123abc789", "abc") ; Returns 4

#2

Haystack := "The Quick Brown Fox Jumps Over the Lazy Dog"
Needle := "Fox"
If InStr(Haystack, Needle)
    MsgBox "The string was found."
Else
    MsgBox "The string was not found."

#3

Haystack := "The Quick Brown Fox Jumps Over the Lazy Dog"
Needle := "the"
MsgBox InStr(Haystack, Needle, false, 1, 2) ; case insensitive search, return start position of second occurence
MsgBox InStr(Haystack, Needle, true) ; case sensitive search, return start position of first occurence, same result as above