MATCHESS()

The MATCHESS() function compares each element of a dynamic array with a pattern template, returning an equivalently structured dynamic array of True/False values. Note the spelling of this function name with the trailing S to "pluralise" the name in common with other multivalue function names.

Format

MATCHESS(dyn.arr, pattern)

where

dyn.arr

is the dynamic array to be processed.

pattern

evaluates to a template as described below.

The MATCHESS() function matches each element of dyn.arr against pattern and returns a dynamic array of True/False values indicating the result of each comparison.

The pattern string consists of one or more concatenated items from the following list.

...	Zero or more characters of any type

0X	Zero or more characters of any type

nX	Exactly n characters of any type

n-mX	Between n and m characters of any type

0A	Zero or more alphabetic characters

nA	Exactly n alphabetic characters

n-mA	Between n and m alphabetic characters

0N	Zero or more numeric characters

nN	Exactly n numeric characters

n-mN	Between n and m numeric characters

"string"

A literal string which must match exactly. Either single or double quotation marks may be used.

The values n and m are integers with any number of digits. m must be greater than or equal to n.

The 0A, nA, 0N, nN and "string" patterns may be preceded by a tilde (~) to invert the match condition. For example, ~4N matches four non-numeric characters such as ABCD (not a string which is not four numeric characters such as 12C4).

A null string matches patterns ..., 0A, 0X, 0N, their inverses (~0A, etc) and "".

The 0X and n-mX patterns match against as few characters as necessary before control passes to the next pattern. For example, the string ABC123DEF matched against the pattern 0X2N0X matches the pattern components as ABC, 12 and 3DEF.

The 0N, n-mN, 0A, and n-mA patterns match against as many characters as possible. For example, the string ABC123DEF matched against the pattern 0X2-3N0X matches the pattern components as ABC, 123 and DEF.

The pattern string may contain alternative templates separated by value marks. The MATCHESS() function tries each template in turn until one is a successful match against string. If a match is found, the INMAT() function can be used to retrieve the value position within the pattern that matched.

Example

VAR = "123":@VM:"ABC:@FM:"456"

X = MATCHESS(VAR, "3N")

The variable X will be returned as

1VM0FM1