]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/tokenizr.tex
cleanup
[wxWidgets.git] / 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 \wxheading{Library}
78
79 \helpref{wxBase}{librarieslist}
80
81 \latexignore{\rtfignore{\wxheading{Members}}}
82
83
84 \membersection{wxStringTokenizer::wxStringTokenizer}\label{wxstringtokenizerwxstringtokenizer}
85
86 \func{}{wxStringTokenizer}{\void}
87
88 Default constructor. You must call
89 \helpref{SetString}{wxstringtokenizersetstring} before calling any other
90 methods.
91
92 \func{}{wxStringTokenizer}{\param{const wxString\& }{str}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
93
94 Constructor. Pass the string to tokenize, a string containing delimiters
95 and the mode specifying how the string should be tokenized.
96
97
98 \membersection{wxStringTokenizer::CountTokens}\label{wxstringtokenizercounttokens}
99
100 \constfunc{int}{CountTokens}{\void}
101
102 Returns the number of tokens remaining in the input string. The number of
103 tokens returned by this function is decremented each time
104 \helpref{GetNextToken}{wxstringtokenizergetnexttoken} is called and when it
105 reaches $0$ \helpref{HasMoreTokens}{wxstringtokenizerhasmoretokens} returns
106 \false.
107
108
109 \membersection{wxStringTokenizer::HasMoreTokens}\label{wxstringtokenizerhasmoretokens}
110
111 \constfunc{bool}{HasMoreTokens}{\void}
112
113 Returns \true if the tokenizer has further tokens, \false if none are left.
114
115
116 \membersection{wxStringTokenizer::GetLastDelimiter}\label{wxstringtokenizergetlastdelimiter}
117
118 \func{wxChar}{GetLastDelimiter}{\void}
119
120 Returns the delimiter which ended scan for the last token returned by
121 \helpref{GetNextToken()}{wxstringtokenizergetnexttoken} or \texttt{NUL} if
122 there had been no calls to this function yet or if it returned the trailing
123 empty token in \texttt{wxTOKEN\_RET\_EMPTY\_ALL} mode.
124
125 \newsince{2.7.0}
126
127
128 \membersection{wxStringTokenizer::GetNextToken}\label{wxstringtokenizergetnexttoken}
129
130 \constfunc{wxString}{GetNextToken}{\void}
131
132 Returns the next token or empty string if the end of string was reached.
133
134
135 \membersection{wxStringTokenizer::GetPosition}\label{wxstringtokenizergetposition}
136
137 \constfunc{size\_t}{GetPosition}{\void}
138
139 Returns the current position (i.e. one index after the last returned
140 token or 0 if GetNextToken() has never been called) in the original
141 string.
142
143
144 \membersection{wxStringTokenizer::GetString}\label{wxstringtokenizergetstring}
145
146 \constfunc{wxString}{GetString}{\void}
147
148 Returns the part of the starting string without all token already extracted.
149
150
151 \membersection{wxStringTokenizer::SetString}\label{wxstringtokenizersetstring}
152
153 \func{void}{SetString}{\param{const wxString\& }{to\_tokenize}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}}
154
155 Initializes the tokenizer.
156
157 Pass the string to tokenize, a string containing delimiters,
158 and the mode specifying how the string should be tokenized.
159