Clarion Community Help

Navigation: Language Reference > 13 - Built-in Functions >====== INSTRING (return substring position) ======

INSTRING(substring,string [,step] [,start])

Returns an unsigned integer value from zero to the length of the search string.

INSTRING	Searches for a substring in a string.
substring	A string constant, variable, or expression that contains the string for which to search. You should CLIP a variable substring so INSTRING will not look for a match that contains the trailing spaces in the variable.
string	A string constant, or the label of the STRING, CSTRING, or PSTRING variable to be searched.
step	A numeric constant, variable, or expression which specifies the step length of the search. A step of 1 will search for the substring beginning at every character in the string, a step of 2 starts at every other character, and so on. A negative step value (-1) will search from right to left within the string. If step is omitted, the step length defaults to the length of the substring.
start	A numeric constant, variable, or expression which specifies where to begin the search of the string. If omitted, the search starts at the first character position. ClarionWin32 The first character position is one (1) Clarion# The first character position is zero (0)

Remarks:

The INSTRING procedure steps through a string, searching for the occurrence of a substring. If the substring is found, the procedure returns the step number on which the substring was found.

ClarionWin32

If the substring is not found in the string, INSTRING returns zero.

Clarion#

In Clarion# indexing starts with 0, so if the substring is not found then -1 is returned.

INSTRING starts to search for substring from the start position in the string and moves from right to left if the step is a positive number, or from left to right if step is a negative number until the substring is found. If the length of the unchecked portion of the string is less than length of the search substring the search stops.

If the search substring is not found INSTRING returns zero.

If the search substring is found, the result is equal to the number of steps from the origin of the string to the found position. If the value of step is not equal to 1, the result is rounded up to the whole number of steps as follows:

INT ¹⁾

¹⁾

found position - 1) / step) + 1 The only negative step value allowed is -1, and the search string must be 1 character long in this case. In other words, a negative step is not allowed with any substring greater than 1 character.

Return Data Type:

UNSIGNED

Clarion Win32 examples:

! find the colon character searching from Right to Left using step of -1
! the 4th parameter is our start position, which must be the last character of the clipped string
s = '123:567:9'
i = INSTRING(':',s,-1,LEN(CLIP(s)))
!! i will be equal to 8

! find the colon character searching from Left to Right using step of 1
s = '123:567:9'
i = INSTRING(':',s,1,1)
!! i will be equal to 4

! find the string '567' searching from Left to Right using step of 1
s = '123:567:9'
i = INSTRING('567',s,1,1)
!! i will be equal to 5 
 
! if the search string is not found the return value is 0
s = '123:567:9'
i = INSTRING('X',s,1,1)
!! i will be equal to 0 

! Search in reverse for the last backslash
ExePath=COMMAND('0')
BS=INSTRING('\',ExePath,-1,SIZE(ExePath))
ExePath=SUB(ExePath,1,BS-1)

! If Step parameters is not specified it is the Len of the SubString
X= instring('**', '1234 **Yes')
! X = 0 because Step is 2 (the length of '**') and the ** is in position 6

Clarion# example: In Clarion#, following the standard for all .Net languages the first character position in any string is Zero (not 1 as it is in Clarion Win32)

! find the colon character searching from Right to Left using step of -1
s = '123:567:9'
i = INSTRING(':',s,-1,LEN(CLIP(s)))
!! i will be equal to 7

! find the colon character searching from Left to Right using step of 1
s = '123:567:9'
i = INSTRING(':',s,1,0)
!! i will be equal to 3 

! find the string '567' searching from Left to Right using step of 1
s = '123:567:9'
i = INSTRING('567',s,1,0)
!! i will be equal to 4 

! if the search string is not found the return value is -1
s = '123:567:9'
i = INSTRING('X',s,1,1)
!! i will be equal to -1

See Also: STRPOS SUB STRING CSTRING PSTRING String Slicing INLIST