Skip to content

Pos

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

Purpose

Returns the ordinal position of the first occurrence of 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 the 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 the 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, their values will be converted to a string for output.