X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/954b8ae60391d18b87a604e7919c87c0c6ae208b..8b6e6947fc8fb946391740d66b140413eccb6b6c:/docs/latex/wx/tokenizr.tex?ds=sidebyside diff --git a/docs/latex/wx/tokenizr.tex b/docs/latex/wx/tokenizr.tex index 23a98634e7..0b8490ce1d 100644 --- a/docs/latex/wx/tokenizr.tex +++ b/docs/latex/wx/tokenizr.tex @@ -1,6 +1,60 @@ \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 +(by default, white space characters will be used). + +Then \helpref{GetNextToken}{wxstringtokenizergetnexttoken} may be called +repeatedly until it \helpref{HasMoreTokens}{wxstringtokenizerhasmoretokens} +returns FALSE. + +For example: + +\begin{verbatim} + +wxStringTokenizer tkz("first:second:third:fourth", ":"); +while ( tkz.HasMoreTokens() ) +{ + wxString token = tkz.GetNextToken(); + + // process token here +} +\end{verbatim} + +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'.} +\twocolitem{{\tt wxTOKEN\_RET\_EMPTY\_ALL}}{In this mode, empty trailing token +(after the last delimiter character) will be returned as well. The string as +above will contain four tokens: the already mentioned ones and another empty +one as the last one.} +\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 +{\tt wxTOKEN\_RET\_EMPTY}.} +\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} @@ -14,40 +68,55 @@ wxStringTokenizer helps you to break a string up into a number of tokens. \membersection{wxStringTokenizer::wxStringTokenizer}\label{wxstringtokenizerwxstringtokenizer} -\func{}{wxStringTokenizer}{\param{const wxString\& }{to\_tokenize}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{bool }{ret\_delim = FALSE}} +\func{}{wxStringTokenizer}{\void} -Constructor. Pass the string to tokenze, a string containing delimiters, -a flag specifying whether delimiters are retained. +Default constructor. You must call +\helpref{SetString}{wxstringtokenizersetstring} before calling any other +methods. -\membersection{wxStringTokenizer::\destruct{wxStringTokenizer}}\label{wxstringtokenizerdtor} +\func{}{wxStringTokenizer}{\param{const wxString\& }{str}, \param{const wxString\& }{delims = " $\backslash$t$\backslash$r$\backslash$n"}, \param{wxStringTokenizerMode }{mode = wxTOKEN\_DEFAULT}} -\func{}{\destruct{wxStringTokenizer}}{\void} - -Destructor. +Constructor. Pass the string to tokenize, a string containing delimiters +and the mode specifying how the string should be tokenized. \membersection{wxStringTokenizer::CountTokens}\label{wxstringtokenizercounttokens} -\constfunc{virtual int}{CountTokens}{\void} +\constfunc{int}{CountTokens}{\void} Returns the number of tokens in the input string. -\membersection{wxStringTokenizer::HasMoreToken}\label{wxstringtokenizerhasmoretoken} +\membersection{wxStringTokenizer::HasMoreTokens}\label{wxstringtokenizerhasmoretokens} + +\constfunc{bool}{HasMoreTokens}{\void} + +Returns TRUE if the tokenizer has further tokens, FALSE if none are left. -\constfunc{virtual bool}{HasMoreToken}{\void} +\membersection{wxStringTokenizer::GetNextToken}\label{wxstringtokenizergetnexttoken} -Returns TRUE if the tokenizer has further tokens. +\func{wxString}{GetNextToken}{\void} -\membersection{wxStringTokenizer::NextToken}\label{wxstringtokenizernexttoken} +Returns the next token or empty string if the end of string was reached. -\constfunc{virtual wxString}{NextToken}{\void} +\membersection{wxStringTokenizer::GetPosition}\label{wxstringtokenizergetposition} -Returns the next token. +\constfunc{size\_t}{GetPosition}{\void} + +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{virtual wxString}{GetString}{\void} +\constfunc{wxString}{GetString}{\void} + +Returns the part of the starting string without all token already extracted. + +\membersection{wxStringTokenizer::SetString}\label{wxstringtokenizersetstring} -Returns the input string. +\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, +and the mode specifying how the string should be tokenized.