MATPARSE

MATPARSE

Top  Previous  Next

 

The MATPARSE statement breaks a delimited string into component substrings, assigning each to an element of a matrix.

 

 

Format

 

MATPARSE mat FROM string {, delimiter} {SETTING var}

MATPARSE mat FROM string {USING delimiter} {SETTING var}

 

where

 

matis the matrix into which the substrings are to be assigned. This matrix must already have been dimensioned.

 

stringis the string to be parsed.

 

delimiterevaluates to the delimiter that separates substrings within string. If omitted, a field mark is used.

 

varis a variable to receive the count of items.

 

 

The MATPARSE statement operates in one of three ways depending on the length of the delimiter string.

 

If delimiter is a null string, each character of string is assigned to a separate element of mat. If both string and delimiter are null, no elements are assigned.

 

If delimiter is a one character string, each substring of string delimited by delimiter is assigned to a separate element of mat. The delimiter character is not stored in mat.

 

If delimiter is more than one character long, each substring of string delimited by any character of delimiter is assigned to a separate element of mat. The next element is assigned the character that delimited the items. Where two or more occurrences of the same delimiter character occur within string with no other intervening characters, only a single element of mat is used to receive the multiple delimiters.

 

If mat is two dimensional, its elements are assigned row by row.

 

The optional SETTING clause sets var to the number of elements assigned. Alternatively, the INMAT() function after a MATPARSE returns the same value. Unused elements are set to null strings.

 

With the default style of matrix, where there are insufficient elements in mat to receive the parsed string, the remaining unparsed data is stored in the zero element of mat. In this case, the INMAT() function will return zero.

 

Pick style matrices do not have a zero element. Any excess data is stored in the final element of the matrix and the INMAT() function returns zero to indicate this condition. See the COMMON and DIMENSION statements for more details.

 

 

Example

 

DIM A(30)

MATPARSE A FROM S, @FM

IF INMAT() THEN DISPLAY INMAT() : ' elements used'

ELSE DISPLAY 'Data overflows available space'

 

This program fragment assigns successive fields of string S to elements of matrix A and displays the actual number of elements used. If there are more than 30 fields, the remaining fields and delimiting mark characters are stored in A(0).

 

 

See also:

MATBUILD