TOKEN()
 Selects the nth token from a string
------------------------------------------------------------------------------
 Syntax

     TOKEN(<cString>,[<cDelimiter>],[<nNumber>],
        [<nSkipWidth>]) --> cToken

 Arguments

     <cString>  Designates the string that is searched.

     <cDelimiter>  Designates the delimiter list used by the token.

     <nNumber>  Designates which token in the <cString> is copied.

     <nSkipWidth>  Designates the number of delimiter characters or
     sequences that count as delimiters for a token, even an empty token.
     The default value indicates that empty tokens are not taken into
     account.

 Returns

     TOKEN() returns the token for which the number has been specified or
     returns the last token in the <cString>.

 Description

     The TOKEN() function allows you to break down date and time strings,
     sentences, file names and paths, etc..  When you specify a value for
     <nNumber>, the token with this number is returned.  If you do not
     specify a value for <nNumber> the function returns the last token in the
     <cString>.  The function uses the following list of delimiters as a
     standard:

     CHR 32, 0, 9, 10, 13, 26, 32, 138, 141

     and the characters ,.;:!?/\<<>>()^#&%+-*

     The list can be replaced by your own list of delimiters, <cDelimiter>.
     Here are some examples of useful delimiters:

     Table 4-4: Recommended Delimiter Sequences
     ------------------------------------------------------------------------
     Description         <cDelimiter>
     ------------------------------------------------------------------------
     Pages               CHR(12)(Form Feed)
     Sentences           ".!?"
     File Names          ":\."
     Numerical strings   ",."
     Date strings        "/."
     Time strings        ":."
     ------------------------------------------------------------------------

     The skip value designates the number of characters after which a token
     is counted again.  This also allows empty tokens within a string, like
     blanks, to be counted.

 Note

     .  When you use the skip width with NUMTOKEN() or TOKEN(), or if
        you use both functions, this value for the skip width must be equal
        in both functions.

 Examples

     .  Select the last token in the character string:

        ? TOKEN("Clipper")                     // "Clipper"
        ? TOKEN(" ,   Clipper . ")             // "Clipper"
        ? TOKEN("Clipper COMPILER!")           // "COMPILER"

     .  Select the first token in a character string:

        ? TOKEN("Clipper", 1)                  // "Clipper"
        ? TOKEN("Clipper COMPILER!", 1)        // "Clipper"

     .  Select the third token:

        ? TOKEN("This is a test.", 3)          // "a"

     .  In this example only four tokens are present:

        ? TOKEN("This is a test.", 5)          // ""

     .  This example shows how to count empty tokens.  Parameters
        separated by commas are counted, but some of the parameters are
        skipped.  Therefore, a token is counted after one delimiter (comma).
        A parameter is skipped where two delimiters (commas) appear without a
        parameter:

        cString  :=  "one,two,,four"
        nCount   :=  NUMTOKEN(cString, ",", 1)   // Result: 4
        FOR nI = 1 TO nCount
        ? TOKEN(cString, ",", nI, 1)
        NEXT nI

     .  If the string contains different delimiters in varying
        combinations, then preparation with the aid of another function is
        always important (to enhance readability, periods have been used
        instead of spaces):

        cString  :=  "one, two,,four,...,six,.,eight"
        cString  := CHARREM(".", cString)
        ? TOKEN(cString, ",", 6, 1)              // "six"

See Also: TOKENSEP() NUMTOKEN() ATTOKEN() TOKENUPPER()