MATPARSE statement

Syntax

MATPARSE array FROM dynamic.array [ ,delimiter]
MATPARSE array [ ,start [ ,end] ] FROM dynamic.array [USING 
delimiter]
 [SETTING elements]

Description

Use the MATPARSE statement to separate the fields of dynamic.array into consecutive elements of array.

array must be named and dimensioned in a DIMENSION statement or COMMON statement before it is used in this statement.

start specifies the starting position in array. If start is less than 1, it defaults to 1.

end specifies the ending position in array. If end is less than 1 or greater than the length of array, it defaults to the length of array.

delimiter is an expression evaluating to the characters used to delimit elements in dynamic.array. Use a comma or USING to separate delimiter from dynamic.array. delimiter can have no characters (an empty delimiter), one character, or more than one character with the following effects:

An empty delimiter (a pair of quotation marks) parses dynamic.array so that each character becomes one element of array (see the second example). The default delimiter is a field mark. This is different from the empty delimiter. To use the default delimiter, omit the comma or USING following dynamic.array.
A single character delimiter parses dynamic.array into fields delimited by that character by storing the substrings that are between successive delimiters as elements in the array. The delimiters are not stored in the array (see the first example).
A multicharacter delimiter parses dynamic.array by storing as elements both the substrings that are between any two successive delimiters and the substrings consisting of one or more consecutive delimiters in the following way: dynamic.array is searched until any of the delimiter characters are found. All of the characters up to but not including the delimiter character are stored as an element of array. The delimiter character and any identical consecutive delimiter characters are stored as the next element. The search then continues as at the start of dynamic.array (see the third example).
If delimiter is a system delimiter and a single CHAR(128) is extracted from dynamic.array, the corresponding element in array is set to the null value.

The characters in a multicharacter delimiter expression can be different or the same. A delimiter expression of /: might be used to separate hours, minutes, seconds and month, day, year in the formats 12:32:16 and 1/23/85. A delimiter expression of two spaces " " might be used to separate tokens on a command line that contain multiple blanks between tokens.

The SETTING clause sets the variable elements to the number of elements in array. If array overflows, elements is set to 0. The value of elements is the same as the value returned by the INMAT function after a MATPARSE statement.

If all the elements of array are filled before MATPARSE reaches the end of dynamic.array, MATPARSE puts the unprocessed part of dynamic.array in the zero element of array for IDEAL, INFORMATION, or PIOPEN flavor accounts, or in the last element of array for PICK, IN2, or REALITY flavor accounts.

Use the INMAT function after a MATPARSE statement to determine the number of elements loaded into the array. If there are more delimited fields in dynamic.array than elements in array, INMAT returns 0; otherwise, it returns the number of elements loaded.

If start is greater than end or greater than the length of array, no action is taken, and INMAT returns 0.

If start, end, dynamic.array, or delimiter evaluates to the null value, the MATPARSE statement fails and the program terminates with a run-time error message.

Examples

Source Lines

Program Output

DIM X(4) Y='1#22#3#44#5#66#7' MATPARSE X FROM Y, '#' FOR Z=0 TO 4 PRINT "X(":Z:")",X(Z) NEXT Z PRINT

X(0)   5#66#7
X(1)   1
X(2)   22
X(3)   3
X(4)   44

DIM Q(6) MATPARSE Q FROM 'ABCDEF', '' FOR P=1 TO 6 PRINT "Q(":P:")",Q(P) NEXT P PRINT

Q(1)   A
Q(2)   B
Q(3)   C
Q(4)   D
Q(5)   E
Q(6)   F

DIM A(8,2) MATPARSE A FROM 'ABCDEFGDDDHIJCK', 'CD' FOR I = 1 TO 8 FOR J = 1 TO 2 PRINT "A(":I:",":J:")=",A(I,J)," ": NEXT J PRINT NEXT I END

A(1,1)= AB A(1,2)= C
A(2,1)=    A(2,2)= D
A(3,1)= EFG  A(3,2)= DDD
A(4,1)= HIJ A(4,2)= C
A(5,1)= K   A(5,2)=
A(6,1)=    A(6,2)=
A(7,1)=    A(7,2)=
A(8,1)=    A(8,2)=