MATCHFIELD(), MATCHFIELDS()

MATCHFIELD(), MATCHFIELDS()

Top  Previous  Next

 

The MATCHFIELD() function extracts a portion of a string that matches a pattern element. The MATCHFIELDS() function performs the same operation on each element of a dynamic array.

 

 

Format

 

MATCHFIELD(string, pattern, element)

 

where

 

stringevaluates to the string in which the pattern is to be located.

 

patternevaluates to a template as described below.

 

elementevaluates to an integer indicating which pattern element of string is to be returned.

 

 

The MATCHFIELD() function matches string against pattern and returns the portion of string that matches the element'th component of pattern.

 

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

 

...Zero or more characters of any type
0XZero or more characters of any type
nXExactly n characters of any type
n-mXBetween n and m characters of any type
0AZero or more alphabetic characters
nAExactly n alphabetic characters
n-mABetween n and m alphabetic characters
0NZero or more numeric characters
nNExactly n numeric characters
n-mNBetween n and m numeric characters
"string"A literal string which must match exactly. Either single or double quotation marks may be used. Unlike the MATCHES operator, string must be enclosed in quotes otherwise each character is treated as a separate component.

 

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 MATCHFIELD() 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.

 

The element argument determines which component of string is returned as the MATCHFIELD() function result. For example,

 

MATCHFIELD("ABC123DEF", "0X2N0X", 2)

 

returns the string "12".

 

The MATCHFIELD() function returns a null string if no component of pattern matches string.

 

The MATCHFIELDS() function performs the same operation on each element of a dynamic array, returning a dynamic array of the same structure in which each element contains the data extracted from the corresponding element of the input string array.

 

 

Examples

 

TEL.NO = "01604-709200"

LOCAL.NO = MATCHFIELD(TEL.NO, "0N'-'0N", 3)

 

This program fragment extracts the local part of a telephone number (709200 in this case). Note that the literal element counts as a component of the string when identifying each element.

 

If the delimiter is multiple characters but not quoted, each character is counted as a separate element:

 

MATCHFIELD("123--456", "0N'--'0N", 1)returns  123
MATCHFIELD("123--456", "0N'--'0N", 2)returns  --
MATCHFIELD("123--456", "0N'--'0N", 3)returns  456

 

MATCHFIELD("123--456", "0N--0N", 1)returns  123
MATCHFIELD("123--456", "0N--0N", 2)returns  -
MATCHFIELD("123--456", "0N--0N", 3)returns  -
MATCHFIELD("123--456", "0N--0N", 4)returns  456

 

 

 

S1 = 'AB12CD' : @VM : 'EF34GH'

S2 = MATCHFIELDS(S1, '0A0N0A', 2)

 

The above program fragment matches each element of dynamic array S1 against the '0A0N0A' pattern and returns S2 as

12VM34

 

 

See also:

Pattern Matching, PARSE()