Caché Basic Reference
InStr
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Returns the position of the first occurrence of one string within another.
Synopsis
InStr([start,]string1,string2[,compare])
Arguments
start Optional — Numeric expression that sets the starting position for each search. If omitted, search begins at the first character position. The start argument is required if compare is specified.
string1 String expression being searched.
string2 String expression being searched for.
compare Optional — Numeric value indicating the kind of comparison to use when evaluating substrings. See Description section for values. If omitted, a binary comparison is performed.
Note:
The order of the arguments in the syntax for the InStr function is not the same as the InStrRev function syntax.
Description
The InStr function searches a string from left-to-right, and returns the location of the first occurrence of string2 encountered. The location returned is a positive integer counting from left-to-right, with the first (leftmost) character of the string being location 1.
If the start value is equal to or less than the location of the first (leftmost) character of string2, InStr finds the first instance of string2, searching forewards from that point, and returns the location of the first (leftmost) character of string2. If the start value is greater than the location of the first (leftmost) character of string2, InStr returns 0. If the start value is omitted, InStr searches the entire string and returns the first string2 location found. If the start value is greater than the string1 length, InStr returns 0. If the start value is a negative number, InStr returns 0.
The compare argument can have the following values:
Constant Value Description
vbBinaryCompare 0 Perform a binary comparison.
vbTextCompare 1 Perform a textual comparison.
The InStr function returns the following values:
If InStr Returns
string1 is zero-length 0
string2 is zero-length start
string2 is not found 0
string2 is found within string1 Position at which match is found
start > Len(string2) 0
Examples
The following examples use InStr to search a string:
Dim SearchString, SearchChar
SearchString ="XXpXXpXXPXXP"        ' String to search in.
SearchChar = "P"                    ' Search for "P".

' A textual comparison starting at position 4. Returns 6.
PRintln Instr(4, SearchString, SearchChar, 1)   

' A binary comparison starting at position 1. Returns 9.
Println Instr(1, SearchString, SearchChar, 0)

' Comparison is binary by default (last argument is omitted).
Println Instr(SearchString, SearchChar)    ' Returns 9.

' A binary comparison starting at position 1. Returns 0 ("W" is not found).
Println Instr(1, SearchString, "W")
 
The following example shows the use of the start argument.
Println "-1: ",InStr(-1,"abcdefg","bc")  ' Returns 2
Println "0: ",InStr(0,"abcdefg","bc")    ' Returns 2
Println "1: ",InStr(1,"abcdefg","bc")    ' Returns 2
Println "2: ",InStr(2,"abcdefg","bc")    ' Returns 2
Println "3: ",InStr(3,"abcdefg","bc")    ' Returns 0
Println "6: ",InStr(6,"abcdefg","bc")    ' Returns 0
Println "7: ",InStr(7,"abcdefg","bc")    ' Returns 0
Println "8: ",InStr(8,"abcdefg","bc")    ' Returns 0
 
See Also