SCAN - extract delimited substring of a string.

Alternate Entry Name: .SCAN

Usage:

B:
   newpos = scan( arg, string, pos [, skipstr, stopstr] );

C:
   int scan(char *arg, const char *string, int pos,
            [const char *skipstr, const char *stopstr]);

Where:

arg: points to a string where the extracted substring is to be placed.
string: is the string to be scanned.
pos: is the position in string where the scan is to start. If "pos" is zero, the scan starts with the character at the beginning of "string". If "pos" is one, the scan starts with the next character, and so on.
skipstr: is a string containing a set of characters which may be skipped before beginning to collect the substring. If "skipstr" is not specified, the default is " *t" so that SCAN skips over spaces and tab characters.
stopstr: is a string containing a set of characters which may be considered to terminate a substring. This set always implicitly includes a '*0'. If "stopstr" is not specified, it defaults to "skipstr".
newpos: is the position of the character that stopped the scan.

Description:

SCAN is used to parse a string into substrings. Beginning at character position "pos" in "string", characters are skipped until a character is found which is not in "skipstr". Characters are then copied one at a time into string "arg" until a character is found which is in string "stopstr". '*0' is considered to be an element of "stopstr" but not of "skipstr". That is, the end-of-string is not skipped in the initial scan, but will stop the copying of characters into "arg".

The value returned, "newpos", is the index of the character that stopped the scan. If you are making successive calls to SCAN in order to break "string" up into separate tokens, you should be a little careful when passing the "newpos" from one call as the "pos" for the next call. If the character in "newpos" is in "stopstr" but not in "skipstr", it may be necessary to add one to the old "newpos" before passing it as a "pos".