Reviewed April 2021
xcall STRTOK, opcode, subject, fdelim, fld1 {, rdelim, fld2, ...fldn}
STRTOK.SBR is both convenient and very efficient (compared to the equivalent logic in BASIC) for parsing string data, but may take a little practice to get used to. See the following topics for a couple of real examples of using it.
STRTOK parses the subject variable according to the delimiters specified, and returns one or more fields in the fld1...fldn variables. You can call it once for each field (and change the field delimiter characters as you go), or have it return several parsed fields in one call, ending either when it hits a delimiter in the rdelim field or runs out of subject or of fldx parameters.
Two examples, Almost Comma Delimited and Large Packets, Multiple Delimiters are provided.
opcode (Num) [in/out]
should be set to 0 for the initial call, and 1 for subsequent calls using the original subject. It will be updated automatically from 0 to 1 to make this easy. In addition, you may specify one or more of the following values for variations of the behavior:
|
Value |
Search Type |
|
&h0002 |
Ignore delimiters in subject if they are inside pairs of quotes ("). Quotes surrounding a field are removed. |
|
&h0004 |
Ignore quotes in the middle of fields in subject. For example, in a CSV list (comma delimited) containing { 6" wrench, 2" screw, "foo,bar", ... }, the quotes in the first two items would be treated as normal characters. |
subject (String) [in/out]
is the string to be parsed. Must be null terminated! subject will be modified by the routine, which will replace the delimiter characters with null bytes.
fdelim (String) [in]
is a list of one or more field delimiter characters.
rdelim (String) [in/out]
is a list of one or more "record" delimiter characters.
(The subroutine will terminate when it hits one of these, whereas it will keep going after each field delimiter until all the FLDx parameters are used up.) Parameter is irrelevant if you just want to get one field. Even in the case of multiple fields, you can set it to "". Note, however, that if specified, it will be returned updated with the actual last delimiter character processed (i.e. the one that terminated the subroutine). This can be very useful when there are more than one possible delimiter, or when you want to determine whether you got a complete record or just ran out of FLDx parameters. If you do not care about record delimiters, then specify it as a literal "" (in which case it cannot be updated) or remember to clear it prior to each XCALL STRTOK. Otherwise, it will get updated to match the field delimiter. The subroutine should be smart enough to ignore record delimiters that are also field delimiters, but it could nonetheless lead to confusion.
Note that prior to Build 905.3, rdelim was assumed to be 2 or more bytes and the second byte was getting cleared, which would have clobbered the next variable if rdelim only mapped as one byte.
fld1...fldn (String) [out]
will return the parsed fields or tokens from subject, according to the specified delimiters.