xHarbour Reference Documentation > Function Reference

HB_ATokens()

Splits a string into tokens based on a delimiter.

Syntax

HB_ATokens( <cString>          , ;
           [<cDelimiter>]      , ;
           [<lSkipQuotes>]     , ;
           [<lDoubleQuotesOnly>] ) --> aTokens

Arguments

<cString>

This is a character string which is tokenized based on the value of <cDelimiter>.

<cDelimiter>

A single character can be specified as delimiter used to tokenize the string <cString>. It defaults to a blank space (Chr(32)).

<lSkipQuotes>

This parameter defaults to .F. (false). When it is set to .T. (true), all portions of <cString> enclosed in single or double quotes are not searched for <cDelimiter>.

<lDoubleQuoteOnly>

The parameter is only relevant when <lSkipQuotes> is .T. (true). When <lDoubleQuoteOnly> is also .T. (true), only portion sof <cString> enclosed in double quotes are not searched for <cDelimiter>.

Return

The function returns an array of character strings.

Description

HB_ATokens() function splits <cString> into substrings, based on the value of <cDelimiter>. The delimiter is removed from <cString> and the resulting substrings are collected in an array, which is returned.

If <lSkipQuotes> is .T. (true), a quoted substring within <cString> is not split if it contains the delimiter sign. If the value of <lSkipQuotes> is .F. (false), which is the default, the quoted substring will be split, regardless of the quotes. The <lDoubleQuoteOnly> argument specifies if both the double and single quote signs are interpreted as a quote sign (.F.) or only the double quote is recognized as a quote sign (.T.).

Info

See also:	At(), AtToken(), IN, Left(), Rat(), Right(), SubStr()
Category:	Array functions , Character functions , Token functions
Source:	vm\arrayshb.c

Example

// The example displays the result of HB_ATokens() using different
// combinations for <lSkipQuotes> and <lDoubleQuoteOnly>

   PROCEDURE Main
      LOCAL cString := [This\'_is\'_a_tok"e_n"ized_string]
      LOCAL aTokens := {}
      LOCAL i

      aTokens := HB_ATokens( cString, "_", .F., .F. )

      FOR i := 1 TO Len( aTokens )
         ? aTokens[i]
      NEXT
      // Result: array with 6 elements
      // This\'
      // is\'
      // a
      // tok"e
      // n"ized
      // string

      aTokens := HB_ATokens( cString, "_", .T., .F. )

      FOR i := 1 TO Len( aTokens )
         ? aTokens[i]
      NEXT
      // Result: array with 4 elements
      // This\'_is\'
      // a
      // tok"e_n"ized
      // string

      aTokens := HB_ATokens( cString, "_", .T., .T. )

      FOR i := 1 TO Len( aTokens )
         ? aTokens[i]
      NEXT
      // Result: array with 5 elements
      // This\'
      // is\'
      // a
      // tok"e_n"ized
      // string
   RETURN