System Functions

POS( )

Scan String

Format

POS(pattern$ { = ...} string$ [ ,step [ ,instance] ] [ ,ERR=stmtref] )

Where:

{ = ...}

Relationship operator. Define the relationship for the string comparison:

:

colon

Search for first instance of any character in string$ which is in pattern$
     e.g. POS("0123456789" : X$) returns first digit in X$

^

caret

Search for first instance of any character in string$ which is not in pattern$
     e.g. POS("0123456789" ^ X$) returns first non-digit in X$

=

equals sign

Searches for pattern$ in string$

<> 

greater/less than

Search for pattern$ not in string$ (usually pattern$ is a single character)

> 

greater than

Search for position where pattern$ is greater than string$

< 

less than

Search for position where pattern$ is less than string$

instance

Numeric expression tells PxPlus which occurrence(s) to report when the pattern is found in the string.

pattern

String value or expression to scan for.

step

Increment value of the intervals. Optional. Numeric expression (defaults to 1).

stmtref

Program line number or statement label to which to transfer control.

Returns

Integer, starting position where relationship is satisfied (0 if none).

Description

The POS( ) function scans the string$ to determine where a portion of it will satisfy the relationship with the pattern string. The function returns an integer reporting the starting position in string$ where the relationship is satisfied, or 0 (zero) if no position satisfies the relationship.

Use the step value to set the logical increment for the next position to be checked. The default is to move one position at a time. If the value of the increment is negative, then the string is scanned from back to front.

Indicate the instance or occurrence for which you want to obtain the POS( ) value. If this value is omitted, the default is 1 (the first instance found). If the value is 0, the POS( ) function returns the total number of matches found.

Example

The following examples illustrate different uses for the POS( ) function:

Example 1:

Given A$="The quick brown fox":

pos("q"=A$) ! Yields 5
pos("z"=A$) ! Yields 0

Example 2: 

Given A$="The quick brown fox":

pos("q"=A$) ! Yields 5
pos("z"=A$) ! Yields 0
pos("o"=A$) ! Yields 13
pos("o"=A$,-1) ! Yields 18 - Scan from end (fox)
pos("o"=A$,1,2) ! Yields 18 - Second occurrence (fox)
pos("o"=A$,2) ! Yields 13 - Checks every 2nd position
pos("r"<A$) ! Yields 6 - "u" is first char. > "r"
pos("o"=A$,1,0) ! Yields 2 - Two occurrences of "o"

Any of the comparison operators (i.e. =, :, ^, < and >) can be used for different evaluations of the number of occurrences found within a string.