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, PARSECOUNT will return the value 1.

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 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.  Delimiters are case-sensitive, so capitalization may be a consideration.

If string_delimiter is not specified, or contains an empty string, special rules apply.  The delimiter is assumed to be a comma.  Fields may optionally be enclosed in quotes.  Such quotes are considered as special field delimiters and are not returned as part of the result string.  Any characters that appear between a quote mark and the next comma delimiter character are discarded.  If no leading quote is found, any leading or trailing spaces are trimmed before the result string is returned.

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

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"