PARSE statement   

Purpose

Parse an entire string and extract all delimited fields into an array.

Syntax

PARSE main$, array$() [, {[ANY] delim$ | BINARY}]

Remarks

PARSE parses the entire string or string expression specified by main$, assigning each delimited sub-string to successive elements of array$.  The array specified by array$ may be a dynamic string array, a fixed-length string array, an ASCIIZ string array, or a user-defined type.

The field delimiter is defined by delim$, which may be one or more characters long.  To be valid, the entire delimiter must match exactly, but the delimiter itself is never assigned as a part of the delimited field. 

 If delim$ is not specified or is null (zero-length), standard comma-delimited (optionally quoted) fields are presumed. In this case only, the following parsing rules apply.  If a standard field is enclosed in optional quotes, they are removed.  If any characters appear between a quoted field and the next comma delimiter, they are discarded.  If no leading quote is found, any leading or trailing blank spaces are trimmed before the field is returned.

ANY

If the ANY option is chosen, each appearance of any single character comprising delim$ is considered a valid delimiter.

BINARY

The BINARY option presumes that the string_expr was created with the JOIN$/BINARY function, or its equivalent, which creates a string as a binary image or in the PowerBASIC and/or Visual Basic packed string format:  If a string is shorter than 65535 bytes, it starts with a 2-byte length WORD followed by the string data.  Otherwise it will start a 2-byte value of 65535, followed by a DWORD indicating the string length, then finally the string data itself.

It is usually advantageous to dimension array$ to the correct size with the use of the PARSECOUNT function.  The PARSE statement is typically much more efficient, as a whole, than repeated use of the PARSE$ function when it is necessary to parse an entire string expression.

The JOIN$ function is the natural complement to the PARSE statement.

See also

JOIN$, PARSE$, PARSECOUNT

Example

a$ = "Trevor, Bob, Bruce, Dan, Simon, Jenny"

DIM b$(1 TO PARSECOUNT(a$))

PARSE a$, b$()

ARRAY SORT b$()

Result

b$(1) = "Bob"

b$(2) = "Bruce"

b$(3) = "Dan"

b$(4) = "Jenny"

b$(5) = "Simon"

b$(6) = "Trevor"