| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== INSTRING (return substring position) ====== | [[instance return variable s thread instance address  1.htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[int  truncate fraction .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

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

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

{{blk2blue.jpg|blk2blue.jpg}}

| **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 //step//s 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  truncate fraction .htm|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:**

<code>
! 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

</code>

**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)

<code>
! 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 
</code>

**See Also:**

[[strpos_return_matching_value_position_.htm|STRPOS]]

[[sub  return substring of string .htm|SUB]]

[[string  fixed length string .htm|STRING]]

[[cstring  fixed length null terminated string .htm|CSTRING]]

[[pstring  embedded length byte string .htm|PSTRING]]

[[implicit string arrays and string slicing.htm|String Slicing]]

[[inlist  return entry in list .htm|INLIST]]