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(wxT("first:second:third:fourth"), wxT(":"));
  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'. Notice that all trailing delimiters are ignored
  47 in this mode, not just the last one, i.e. a string \texttt{"a::b::"} would
  48 still result in the same set of tokens.}
  49 \twocolitem{{\tt wxTOKEN\_RET\_EMPTY\_ALL}}{In this mode, empty trailing tokens
  50 (including the one after the last delimiter character) will be returned as
  51 well. The string \texttt{"a::b:"} will be tokenized in four tokens: the already
  52 mentioned ones and another empty one as the last one and a string
  53 \texttt{"a::b::"} will have five tokens.}
  54 \twocolitem{{\tt wxTOKEN\_RET\_DELIMS}}{In this mode, the delimiter character
  55 after the end of the current token (there may be none if this is the last
  56 token) is returned appended to the token. Otherwise, it is the same mode as
  57 \texttt{wxTOKEN\_RET\_EMPTY}. Notice that there is no mode like this one but
  58 behaving like \texttt{wxTOKEN\_RET\_EMPTY\_ALL} instead of
  59 \texttt{wxTOKEN\_RET\_EMPTY}, use \texttt{wxTOKEN\_RET\_EMPTY\_ALL} and
  60 \helpref{GetLastDelimiter()}{wxstringtokenizergetlastdelimiter} to emulate it.}
  61 \twocolitem{{\tt wxTOKEN\_STRTOK}}{In this mode the class behaves exactly like
  62 the standard {\tt strtok()} function: the empty tokens are never returned.}
  63 \end{twocollist}
  64
  65 \wxheading{Derived from}
  66
  67 \helpref{wxObject}{wxobject}
  68
  69 \wxheading{See also}
  70
  71 \helpref{wxStringTokenize}{wxstringtokenize}
  72
  73 \wxheading{Include files}
  74
  75 <wx/tokenzr.h>
  76
  77 \latexignore{\rtfignore{\wxheading{Members}}}
  78
  79
  80 \membersection{wxStringTokenizer::wxStringTokenizer}\label{wxstringtokenizerwxstringtokenizer}
  81
  82 \func{}{wxStringTokenizer}{\void}
  83
  84 Default constructor. You must call
  85 \helpref{SetString}{wxstringtokenizersetstring} before calling any other
  86 methods.
  87
  88 \func{}{wxStringTokenizer}{\param{const wxString\& }{str}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
  89
  90 Constructor. Pass the string to tokenize, a string containing delimiters
  91 and the mode specifying how the string should be tokenized.
  92
  93
  94 \membersection{wxStringTokenizer::CountTokens}\label{wxstringtokenizercounttokens}
  95
  96 \constfunc{int}{CountTokens}{\void}
  97
  98 Returns the number of tokens remaining in the input string. The number of
  99 tokens returned by this function is decremented each time
 100 \helpref{GetNextToken}{wxstringtokenizergetnexttoken} is called and when it
 101 reaches $0$ \helpref{HasMoreTokens}{wxstringtokenizerhasmoretokens} returns
 102 \false.
 103
 104
 105 \membersection{wxStringTokenizer::HasMoreTokens}\label{wxstringtokenizerhasmoretokens}
 106
 107 \constfunc{bool}{HasMoreTokens}{\void}
 108
 109 Returns \true if the tokenizer has further tokens, \false if none are left.
 110
 111
 112 \membersection{wxStringTokenizer::GetLastDelimiter}\label{wxstringtokenizergetlastdelimiter}
 113
 114 \func{wxChar}{GetLastDelimiter}{\void}
 115
 116 Returns the delimiter which ended scan for the last token returned by
 117 \helpref{GetNextToken()}{wxstringtokenizergetnexttoken} or \texttt{NUL} if
 118 there had been no calls to this function yet or if it returned the trailing
 119 empty token in \texttt{wxTOKEN\_RET\_EMPTY\_ALL} mode.
 120
 121
 122 \membersection{wxStringTokenizer::GetNextToken}\label{wxstringtokenizergetnexttoken}
 123
 124 \constfunc{wxString}{GetNextToken}{\void}
 125
 126 Returns the next token or empty string if the end of string was reached.
 127
 128
 129 \membersection{wxStringTokenizer::GetPosition}\label{wxstringtokenizergetposition}
 130
 131 \constfunc{size\_t}{GetPosition}{\void}
 132
 133 Returns the current position (i.e. one index after the last returned
 134 token or 0 if GetNextToken() has never been called) in the original
 135 string.
 136
 137
 138 \membersection{wxStringTokenizer::GetString}\label{wxstringtokenizergetstring}
 139
 140 \constfunc{wxString}{GetString}{\void}
 141
 142 Returns the part of the starting string without all token already extracted.
 143
 144
 145 \membersection{wxStringTokenizer::SetString}\label{wxstringtokenizersetstring}
 146
 147 \func{void}{SetString}{\param{const wxString\& }{to\_tokenize}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
 148
 149 Initializes the tokenizer.
 150
 151 Pass the string to tokenize, a string containing delimiters,
 152 and the mode specifying how the string should be tokenized.
 153