MATPARSE Statement

The MATPARSE statement assigns the elements of a dimensioned array from the elements of a dynamic array or string.

Format

MATPARSE array FROM string, delim [SETTING var]

Parameter(s)

array	Dimensioned array to be assigned.
string	An expression evaluating to the string or dynamic array to read the elements from.
delim	An expression evaluating to the characters used to delimit elements in string. The behavior of the MATPARSE statement is dependent on the number of characters specified as delimiters.
SETTING var	Assign to var the number of fields separated by delim in the string. The resulting var may be tested to determine if it is larger than the dimensions of the array.

Description

The MATPARSE statement separates the elements of a string expression into consecutive elements of a dimensioned array. The array must be named and dimensioned in a DIMENSION or COMMON statement before it is used in this statement.

The behavior of the MATPARSE statement is dependent on the number of characters specified as delimiters:

0 (delim = "")	Each character of string is placed into a separate element of array.
1	Each field separated by the delimiter character delim is loaded into a separate element of array. The delimiter character itself is stored.
2 or more	Fields and delimiters alternate as elements of array. Fields occupy all odd-numbered elements of the array, and delimiters occupy all even-numbered elements. Consecutive delimiters are placed in the same element if they are identical, but are placed in separate elements if they are different, with a null field element in between.

If the dimensions of the dimensioned array are too small to accommodate the parsed string, the leftover portion is appended to the last element of the array, delimiters intact.

Example

If a string STRING contained:

THIS-IS-A-STRING

and the array ARR1 were dimensioned to a 7-element vector, then:

MATPARSE ARR1 FROM STRING, ""

(0 delimiters) would produce as ARR1:

1	T
2	H
3	I
4	S
5	-
6	I
7	SA-STRING

However, if the single delimiter "-" was specified:

MATPARSE ARR1 FROM STRING, "-"

would return into ARR1:

1	THIS
2	IS
3	A
4	STRING
5
6
7

If two delimiters are specified:

MATPARSE ARR1 FROM STRING, "--"

then ARR1 would contain:

1	THIS
2	-
3	IS
4	-
5	A
6	-
7	STRING

For each of these examples, MATBUILD with the same delimiters may be used to reconstruct the string.