]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/tokenizr.tex
fixed bug #890430, parameter documented twice
[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'.}
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