EXTRACT$ function

Purpose | Extract characters from a string up to a character or group of characters.
Syntax | x$ = EXTRACT$([start,] MainStr, [ANY] MatchStr)

Remarks

EXTRACT$ returns a sub-string of MainStr, starting with its first character (or the character specified by start) and up to (but not including) the first occurrence of MatchStr. If MatchStr is not present in MainStr, or either string parameter is nul, all of MainStr is returned.

start is the optional starting position to begin extracting. If start is not specified, it will start at position 1. If start is zero, or beyond the length of MainStr, a nul string is returned. If start is negative, the starting position is counted from right to left: if -1, the search begins at the last character; if -2, the second to last, and so forth.

MainStr is the string expression from which to extract. MatchStr is the string expression to extract up to. EXTRACT$ is case-sensitive.

If the ANY keyword is included, MatchStr specifies a list of single characters to be searched for individually, a match on any one of which will cause the extract operation to be performed up to that character.

EXTRACT$ is especially useful when parsing a string containing arguments to a program, or when manipulating nul-terminated or delimited strings received from a routine written in another language.

The complementary function to EXTRACT$ is REMAIN$, which returns the part of the string that EXTRACT$ leaves behind. A similar function to EXTRACT$ is PARSE$, which extracts delimited substrings from a string.

See also | CLIP$, INSTR, JOIN$, LEFT$, LTRIM$, MID$, PARSE, PARSE$, PARSECOUNT, REMAIN$, REMOVE$, RETAIN$, RIGHT$, RTRIM$, TALLY, TRIM$, UNWRAP$, VERIFY

Example

' x$ = first command-line argument, assuming spaces,

' commas, periods, and tabs are valid delimiters

x$ = EXTRACT$(COMMAND$, ANY " ,."+CHR$(9))

' the following line returns "aba" (match on "cad")

x$ = EXTRACT$("abacadabra","cad")

' the following line returns nothing (match on first character "a")

x$ = EXTRACT$("abacadabra", ANY "cad")