See Also: String Functions, RightPos, Left, Length, Mid, Right


Returns the ordinal position of the first occurrence a substring in a host string or 0 (zero) if the substring is not found.

Return Type



(Pos( {sub-string}, {host-string} [, {StartingPosition}] [, {length} ] ))


What It Does

Pos finds the first (left-most) occurrence of {sub-string} in {host-string} and returns the position in code points of the first character of {sub-string} as it stands in {host-string}.


This sample shows how to search a string for a substring using different search lengths and starting positions.


String sTest

Integer iPos


Move "12341234" to sTest

The following code returns position 3, the left-most occurrence of '3'.

Move (Pos("3", sTest)) to iPos

The following code returns position 7, the left-most occurrence of '3' following starting position 4.

This means that the portion of the host string in blue is searched: "12341234".

Move (Pos("3", sTest, 4, 0)) to iPos

The following code returns position 0, since '3' does not occur in the substring of sTest between positions 4 (starting position) and 5 (starting position + length 2).

This means that the portion of the host string in blue is searched: "12341234".

Move (Pos("3", sTest, 4, 2)) to iPos


This sample demonstrates how to use the optional {position} argument to search a String array for a substring where the starting position of the substring being searched for in each array element is known.

Procedure OnClick

    String[] sCollection

    String sTarget

    Integer i iStartingPos iPos


    Move "This ball is red" to sCollection[0]

    Move "This ball is blue" to sCollection[1]

    Move "This ball is purple" to sCollection[2]

    Move "This ball is green" to sCollection[3]

    Move "This ball is yellow" to sCollection[4]

    Move "This ball is white" to sCollection[5]


    // look for the element with the green ball

    Move "green" to sTarget

    // we know the first 13 characters are always the same, so skip them

    Move 13 to iStartingPos


    For i from 0 to (SizeOfArray(sCollection)-1)

        Move (Pos(sTarget, sCollection[i], iStartingPos, 0)) to iPos

        If (iPos > 0) Showln ("Found target in element " + String(i) + ": " + sCollection[i])




This sample separates a string into words by separating character groups (words) before and after any space in the text.

Function SplitStringIntoWords String sText returns String[]

    String sWord

    String[] Words

    Integer iWordCount iPos iPrev


    Move 1 to iPos  // initialize to non-zero

    Move 1 to iPrev


    // loop while there is a space found

    While (iPos > 0)

        Move (Pos (" ", sText, iPrev, 0)) to iPos

        If (iPos > 0) Begin

            // move current word to array

            Move (Mid(sText, iPos-iPrev, iPrev)) to sWord

            Move sWord to Words[iWordCount]

            Increment iWordCount


            // store current space marker as previous space marker

            Move (iPos+1) to iPrev



        // once no spaces are left, move word after last space into array

        Move (Right(sText, Length(sText)-(iPrev-1))) to Words[iWordCount]



    Function_Return Words



Procedure OnClick

    String sText

    String[] Words


    Move "Split this text into words" to sText

    Get SplitStringIntoWords sText to Words