# 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 returns 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.

Finding the Number of Fields in a String

If you have a string with a series of delimited fields (such as "a,b,c,d,e,f,"), you can figure out the number of fields in the string by using the POS function to count the number of delimiters.

> Count = POS("," = <string>,1,0)

Giving the POS function an increment of 1 with an occurrence number of 0 (zero) causes it to return the count instead of the position.

The only thing to watch for is if the string does not have a trailing delimiter (such as "a,b,c"), the number will be one too low.

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