xHarbour Reference Documentation > Function Reference

Token()

Retrieves the n-th token from a string.

Syntax

Token( <cString>        , ;
      [<cDelimiter>]    , ;
      [<nTokenPos>]     , ;
      [<nSkipWidth>]    , ;
      [@<cPreTokenSep>] , ;
      [@<cPostTokenSep>]  ) --> cToken

Arguments

<cString>

This is a character string to find a token in.

<cDelimiter>

This character string holds a list of characters recognized as delimiters between tokens. The default list of delimiters consist of non-printable characters having the ASCII codes 0, 9, 10, 13, 26, 32, 138 and 141, and the following punctuation characters: ,.;:!?/\<>()!HSH&%+-*

<nTokenPos>

A numeric value indicating the ordinal position of the token to retrieve. It defaults to the last token.

<nSkipWidth>

This optional numeric value defaults to zero. This causes the function to find empty tokens. To suppress this behavior, set <nSkipWidth> to 1.

@<cPreTokenSep> and @<cPostTokenSep>

If passed by reference, these parameters receive the pre- and post delimiters of the found token, making an extra call to TokenSep() obsolete.

Return

The function returns the token found at <nTokenPos> in a character string. When no more tokens can be found, the return value is a null string ("").

Note:  Token() does not use the tokenizer environment. Therefore, TokenInit() does not need to be called. However, when large strings are tokenized, it is recommended to take advantage of the tokenizer environment for achieving best performance.

Info

See also:	AtToken(), HB_ATokens(), NumToken(), TokenInit(), TokenLower(), TokenSep(), TokenUpper()
Category:	CT:String manipulation , Character functions , Token functions
Source:	ct\token1.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example extracts all directories from the PATH
// environment variable.

   PROCEDURE Main
      LOCAL cPath := GetEnv( "PATH" )
      LOCAL cDirectory, nCount := 0

      // Last token
      ? Token( cPath, ";" )

      // All tokens
      DO WHILE .T.
         cDirectory := Token( cPath, ";", ++nCount )

         IF Empty( cDirectory )
            EXIT
         ENDIF

         ? nCount, cDirectory
      ENDDO

   RETURN