PARSE$ function

Purpose

Return a delimited field from a string expression.

Syntax

a$ = PARSE$(string_expr [, {[ANY] string_delimiter | BINARY}], index&)

Remarks

PARSE$ uses the following parameters:

string_expr

The string to parse.  If string_expr is empty (a null string) or contains no delimiter character(s), the string is considered to contain exactly one field.  In this case, PARSE$ will return string_expr.

string_delimiter

Contains delimiter character(s).  A delimiter is a character, list of characters, or string, that is used to mark the end of a field in string_expr.  For example, if you consider a sentence to be a list of words, the delimiter between the works is a space (or perhaps punctuation).  Text files typically consist of lines that are delimited by CR/LF ($CRLF or CHR$(13,10)) characters; a database file may consist of items separated by commas; etc.  A delimiter is not considered part of a field, but as the divider between fields, so the delimiter is never returned by PARSE$.

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.

Delimiters are case-sensitive, so capitalization may be a consideration.

ANY

If the ANY keyword is used, string_delimiter contains a set of characters, any of which may act as a delimiter character.  If the ANY keyword is omitted, the entire string_delimiter string acts as a single delimiter.

BINARY

The BINARY option presumes that 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.

index&

An integer-class variable or expression that specifies the delimited field number to return.  The first field is 1, and so on up to the maximum number of fields contained in string_expr, which may be determined with the PARSECOUNT function.  If index& is negative, string_expr is parsed from right to left.  In this case, index& = -1 returns the last field in string_expr, -2 returns the second to last, etc.  If index& evaluates to zero, or is outside of the actual field count, an empty string is returned.

See also

JOIN$, PARSE, PARSECOUNT, PATHNAME$, PATHSCAN$

Example

a$ = PARSE$("one,two,three", 2)   ' returns "two"

a$ = PARSE$("one;two,three", 2)   ' returns "three"

a$ = PARSE$("one",2)              ' returns ""

a$ = PARSE$("xyz",1)              ' returns "xyz"

a$ = PARSE$("xx1x","x",3)         ' returns "1"

a$ = PARSE$("1;2,3", ANY ",;", 2) ' returns "2"