docs/latex/wx/tokenizr.tex

   1 \section{\class{wxStringTokenizer}}\label{wxstringtokenizer}
   2
   3 wxStringTokenizer helps you to break a string up into a number of tokens. It
   4 replaces the standard C function {\tt strtok()} and also extends it in a
   5 number of ways.
   6
   7 To use this class, you should create a wxStringTokenizer object, give it the
   8 string to tokenize and also the delimiters which separate tokens in the string
   9 (by default, white space characters will be used).
  10
  11 Then \helpref{GetNextToken}{wxstringtokenizergetnexttoken} may be called
  12 repeatedly until it \helpref{HasMoreTokens}{wxstringtokenizerhasmoretokens}
  13 returns FALSE.
  14
  15 For example:
  16
  17 \begin{verbatim}
  18
  19 wxStringTokenizer tkz("first:second:third:fourth", ":");
  20 while ( tkz.HasMoreTokens() )
  21 {
  22     wxString token = tkz.GetNextToken();
  23
  24     // process token here
  25 }
  26 \end{verbatim}
  27
  28 By default, wxStringTokenizer will behave in the same way as {\tt strtok()} if
  29 the delimiters string only contains white space characters but, unlike the
  30 standard function, it will return empty tokens if this is not the case. This
  31 is helpful for parsing strictly formatted data where the number of fields is
  32 fixed but some of them may be empty (i.e. {\tt TAB} or comma delimited text
  33 files).
  34
  35 The behaviour is governed by the last
  36 \helpref{constructor}{wxstringtokenizerwxstringtokenizer}/\helpref{SetString}{wxstringtokenizersetstring}
  37 parameter {\tt mode} which may be one of the following:
  38
  39 \twocolwidtha{5cm}%
  40 \begin{twocollist}\itemsep=0pt
  41 \twocolitem{{\tt wxTOKEN\_DEFAULT}}{Default behaviour (as described above):
  42 same as {\tt wxTOKEN\_STRTOK} if the delimiter string contains only
  43 whitespaces, same as {\tt wxTOKEN\_RET\_EMPTY} otherwise}
  44 \twocolitem{{\tt wxTOKEN\_RET\_EMPTY}}{In this mode, the empty tokens in the
  45 middle of the string will be returned, i.e. {\tt "a::b:"} will be tokenized in
  46 three tokens `a', `' and `b'.}
  47 \twocolitem{{\tt wxTOKEN\_RET\_EMPTY\_ALL}}{In this mode, empty trailing token
  48 (after the last delimiter character) will be returned as well. The string as
  49 above will contain four tokens: the already mentioned ones and another empty
  50 one as the last one.}
  51 \twocolitem{{\tt wxTOKEN\_RET\_DELIMS}}{In this mode, the delimiter character
  52 after the end of the current token (there may be none if this is the last
  53 token) is returned appended to the token. Otherwise, it is the same mode as
  54 {\tt wxTOKEN\_RET\_EMPTY}.}
  55 \twocolitem{{\tt wxTOKEN\_STRTOK}}{In this mode the class behaves exactly like
  56 the standard {\tt strtok()} function. The empty tokens are never returned.}
  57 \end{twocollist}
  58
  59 \wxheading{Derived from}
  60
  61 \helpref{wxObject}{wxobject}
  62
  63 \wxheading{Include files}
  64
  65 <wx/tokenzr.h>
  66
  67 \latexignore{\rtfignore{\wxheading{Members}}}
  68
  69 \membersection{wxStringTokenizer::wxStringTokenizer}\label{wxstringtokenizerwxstringtokenizer}
  70
  71 \func{}{wxStringTokenizer}{\void}
  72
  73 Default constructor. You must call
  74 \helpref{SetString}{wxstringtokenizersetstring} before calling any other
  75 methods.
  76
  77 \func{}{wxStringTokenizer}{\param{const wxString\& }{str}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
  78
  79 Constructor. Pass the string to tokenize, a string containing delimiters
  80 and the mode specifying how the string should be tokenized.
  81
  82 \membersection{wxStringTokenizer::CountTokens}\label{wxstringtokenizercounttokens}
  83
  84 \constfunc{int}{CountTokens}{\void}
  85
  86 Returns the number of tokens in the input string.
  87
  88 \membersection{wxStringTokenizer::HasMoreTokens}\label{wxstringtokenizerhasmoretokens}
  89
  90 \constfunc{bool}{HasMoreTokens}{\void}
  91
  92 Returns TRUE if the tokenizer has further tokens, FALSE if none are left.
  93
  94 \membersection{wxStringTokenizer::GetNextToken}\label{wxstringtokenizergetnexttoken}
  95
  96 \func{wxString}{GetNextToken}{\void}
  97
  98 Returns the next token or empty string if the end of string was reached.
  99
 100 \membersection{wxStringTokenizer::GetPosition}\label{wxstringtokenizergetposition}
 101
 102 \constfunc{size\_t}{GetPosition}{\void}
 103
 104 Returns the current position (i.e. one index after the last returned
 105 token or 0 if GetNextToken() has never been called) in the original
 106 string.
 107
 108 \membersection{wxStringTokenizer::GetString}\label{wxstringtokenizergetstring}
 109
 110 \constfunc{wxString}{GetString}{\void}
 111
 112 Returns the part of the starting string without all token already extracted.
 113
 114 \membersection{wxStringTokenizer::SetString}\label{wxstringtokenizersetstring}
 115
 116 \func{void}{SetString}{\param{const wxString\& }{to\_tokenize}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
 117
 118 Initializes the tokenizer.
 119
 120 Pass the string to tokenize, a string containing delimiters,
 121 and the mode specifying how the string should be tokenized.
 122