Pos

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

Purpose

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

Integer

Syntax

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

Where:

• {sub-string} is the string value that Pos searches for in {host-string}.

• {host-string} is the string value Pos searches for an occurrence of {sub-string} in.

• {StartingPosition} (optional) specifies the starting (left-most) position in {host-string} where the search is to begin. The position is 1-based, where the first position in {host-string} is 1.
  
  If less than 1, it is adjusted to 1. If greater than last valid position in range, the function fails and returns 0. If not specified, 1 is used.

• {length} (optional) specifies the maximum number of code points that should be searched in {host-string}.
  
  If less than 1, the function fails and returns 0. If greater than valid length within the range, it is adjusted to the longest valid length in range.  If not specified, the longest valid length in range is used.

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}.

 Sample

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

Assuming

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

Sample

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

    Loop

End_Procedure

Sample

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

        End

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

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

    Loop

    Function_Return Words

End_Function

Procedure OnClick

    String sText

    String[] Words

    Move "Split this text into words" to sText

    Get SplitStringIntoWords sText to Words

End_Procedure

Notes

• If {sub-string} or {host-string} are of type other than string, its value will be converted to a string for output.