X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bbf8fc5391b2458d630d29a794df99c8e681e6eb..40131743c6b71881ec36f206f88fa2932c36925b:/docs/latex/wx/tokenizr.tex diff --git a/docs/latex/wx/tokenizr.tex b/docs/latex/wx/tokenizr.tex index b066262a52..fade99915c 100644 --- a/docs/latex/wx/tokenizr.tex +++ b/docs/latex/wx/tokenizr.tex @@ -1,6 +1,8 @@ \section{\class{wxStringTokenizer}}\label{wxstringtokenizer} -wxStringTokenizer helps you to break a string up into a number of tokens. +wxStringTokenizer helps you to break a string up into a number of tokens. It +replaces the standard C function {\tt strtok()} and also extends it in a +number of ways. To use this class, you should create a wxStringTokenizer object, give it the string to tokenize and also the delimiters which separate tokens in the string @@ -8,13 +10,13 @@ string to tokenize and also the delimiters which separate tokens in the string Then \helpref{GetNextToken}{wxstringtokenizergetnexttoken} may be called repeatedly until it \helpref{HasMoreTokens}{wxstringtokenizerhasmoretokens} -returns FALSE. +returns \false. For example: \begin{verbatim} -wxStringTokenizer tkz("first:second:third::fivth", ":"); +wxStringTokenizer tkz(wxT("first:second:third:fourth"), wxT(":")); while ( tkz.HasMoreTokens() ) { wxString token = tkz.GetNextToken(); @@ -23,53 +25,101 @@ while ( tkz.HasMoreTokens() ) } \end{verbatim} -Another feature of this class is that it may return the delimiter which -was found after the token with it. In a simple case like above, you are not -interested in this because the delimiter is always {\tt ':'}, but if the -delimiters string has several characters, you might need to know which of them -follows the current token. In this case, pass {\tt TRUE} to wxStringTokenizer -constructor or \helpref{SetString}{wxstringtokenizersetstring} method and -the delimiter will be appended to each returned token (except for the last -one). +By default, wxStringTokenizer will behave in the same way as {\tt strtok()} if +the delimiters string only contains white space characters but, unlike the +standard function, it will return empty tokens if this is not the case. This +is helpful for parsing strictly formatted data where the number of fields is +fixed but some of them may be empty (i.e. {\tt TAB} or comma delimited text +files). + +The behaviour is governed by the last +\helpref{constructor}{wxstringtokenizerwxstringtokenizer}/\helpref{SetString}{wxstringtokenizersetstring} +parameter {\tt mode} which may be one of the following: + +\twocolwidtha{5cm}% +\begin{twocollist}\itemsep=0pt +\twocolitem{{\tt wxTOKEN\_DEFAULT}}{Default behaviour (as described above): +same as {\tt wxTOKEN\_STRTOK} if the delimiter string contains only +whitespaces, same as {\tt wxTOKEN\_RET\_EMPTY} otherwise} +\twocolitem{{\tt wxTOKEN\_RET\_EMPTY}}{In this mode, the empty tokens in the +middle of the string will be returned, i.e. {\tt "a::b:"} will be tokenized in +three tokens `a', `' and `b'. Notice that all trailing delimiters are ignored +in this mode, not just the last one, i.e. a string \texttt{"a::b::"} would +still result in the same set of tokens.} +\twocolitem{{\tt wxTOKEN\_RET\_EMPTY\_ALL}}{In this mode, empty trailing tokens +(including the one after the last delimiter character) will be returned as +well. The string \texttt{"a::b:"} will be tokenized in four tokens: the already +mentioned ones and another empty one as the last one and a string +\texttt{"a::b::"} will have five tokens.} +\twocolitem{{\tt wxTOKEN\_RET\_DELIMS}}{In this mode, the delimiter character +after the end of the current token (there may be none if this is the last +token) is returned appended to the token. Otherwise, it is the same mode as +\texttt{wxTOKEN\_RET\_EMPTY}. Notice that there is no mode like this one but +behaving like \texttt{wxTOKEN\_RET\_EMPTY\_ALL} instead of +\texttt{wxTOKEN\_RET\_EMPTY}, use \texttt{wxTOKEN\_RET\_EMPTY\_ALL} and +\helpref{GetLastDelimiter()}{wxstringtokenizergetlastdelimiter} to emulate it.} +\twocolitem{{\tt wxTOKEN\_STRTOK}}{In this mode the class behaves exactly like +the standard {\tt strtok()} function: the empty tokens are never returned.} +\end{twocollist} \wxheading{Derived from} \helpref{wxObject}{wxobject} +\wxheading{See also} + +\helpref{wxStringTokenize}{wxstringtokenize} + \wxheading{Include files} \latexignore{\rtfignore{\wxheading{Members}}} + \membersection{wxStringTokenizer::wxStringTokenizer}\label{wxstringtokenizerwxstringtokenizer} \func{}{wxStringTokenizer}{\void} -Default constructor. - -\func{}{wxStringTokenizer}{\param{const wxString\& }{to\_tokenize}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{bool }{ret\_delim = FALSE}} +Default constructor. You must call +\helpref{SetString}{wxstringtokenizersetstring} before calling any other +methods. -Constructor. Pass the string to tokenize, a string containing delimiters, -a flag specifying whether to return delimiters with tokens. +\func{}{wxStringTokenizer}{\param{const wxString\& }{str}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}} -\membersection{wxStringTokenizer::\destruct{wxStringTokenizer}}\label{wxstringtokenizerdtor} +Constructor. Pass the string to tokenize, a string containing delimiters +and the mode specifying how the string should be tokenized. -\func{}{\destruct{wxStringTokenizer}}{\void} - -Destructor. \membersection{wxStringTokenizer::CountTokens}\label{wxstringtokenizercounttokens} \constfunc{int}{CountTokens}{\void} -Returns the number of tokens in the input string. +Returns the number of tokens remaining in the input string. The number of +tokens returned by this function is decremented each time +\helpref{GetNextToken}{wxstringtokenizergetnexttoken} is called and when it +reaches $0$ \helpref{HasMoreTokens}{wxstringtokenizerhasmoretokens} returns +\false. + \membersection{wxStringTokenizer::HasMoreTokens}\label{wxstringtokenizerhasmoretokens} \constfunc{bool}{HasMoreTokens}{\void} -Returns TRUE if the tokenizer has further tokens. +Returns \true if the tokenizer has further tokens, \false if none are left. + + +\membersection{wxStringTokenizer::GetLastDelimiter}\label{wxstringtokenizergetlastdelimiter} + +\func{wxChar}{GetLastDelimiter}{\void} + +Returns the delimiter which ended scan for the last token returned by +\helpref{GetNextToken()}{wxstringtokenizergetnexttoken} or \texttt{NUL} if +there had been no calls to this function yet or if it returned the trailing +empty token in \texttt{wxTOKEN\_RET\_EMPTY\_ALL} mode. + +\newsince{2.7.0} + \membersection{wxStringTokenizer::GetNextToken}\label{wxstringtokenizergetnexttoken} @@ -77,6 +127,7 @@ Returns TRUE if the tokenizer has further tokens. Returns the next token or empty string if the end of string was reached. + \membersection{wxStringTokenizer::GetPosition}\label{wxstringtokenizergetposition} \constfunc{size\_t}{GetPosition}{\void} @@ -85,18 +136,20 @@ Returns the current position (i.e. one index after the last returned token or 0 if GetNextToken() has never been called) in the original string. + \membersection{wxStringTokenizer::GetString}\label{wxstringtokenizergetstring} \constfunc{wxString}{GetString}{\void} Returns the part of the starting string without all token already extracted. + \membersection{wxStringTokenizer::SetString}\label{wxstringtokenizersetstring} -\func{void}{SetString}{\param{const wxString\& }{to\_tokenize}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{bool }{ret\_delim = FALSE}} +\func{void}{SetString}{\param{const wxString\& }{to\_tokenize}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}} Initializes the tokenizer. Pass the string to tokenize, a string containing delimiters, -a flag specifying whether to return delimiters with tokens. +and the mode specifying how the string should be tokenized.