From: Bryan Petty <bryan@ibaku.net>
Date: Tue, 6 May 2008 07:06:08 +0000 (+0000)
Subject: Interface header review of wxStringTokenizer by Azriel Fasten.
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/977cf1100e5ab447308bfa035ccb3f6c991361aa
Interface header review of wxStringTokenizer by Azriel Fasten.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53464 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
diff --git a/interface/tokenzr.h b/interface/tokenzr.h
index 782f3c65cf..f576de6b5e 100644
--- a/interface/tokenzr.h
+++ b/interface/tokenzr.h
@@ -6,96 +6,86 @@
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+/**
+ The behaviour of wxStringTokenizer is governed by the
+ wxStringTokenizer::wxStringTokenizer() or wxStringTokenizer::SetString()
+ with the parameter @e mode, which may be one of the following:
+*/
+enum wxStringTokenizerMode
+{
+ wxTOKEN_INVALID = -1, ///< Invalid tokenizer mode.
+
+ /**
+ Default behaviour: wxStringTokenizer will behave in the same way as
+ @c strtok() (::wxTOKEN_STRTOK) if the delimiters string only contains
+ white space characters but, unlike the standard function, it will
+ behave like ::wxTOKEN_RET_EMPTY, returning 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.
+ @c TAB or comma delimited text files).
+ */
+ wxTOKEN_DEFAULT,
+
+ /**
+ In this mode, the empty tokens in the middle of the string will be returned,
+ i.e. @c "a::b:" will be tokenized in three tokens @c 'a', " and @c 'b'. Notice
+ that all trailing delimiters are ignored in this mode, not just the last one,
+ i.e. a string @c "a::b::" would still result in the same set of tokens.
+ */
+ wxTOKEN_RET_EMPTY,
+
+ /**
+ In this mode, empty trailing tokens (including the one after the last delimiter
+ character) will be returned as well. The string @c "a::b:" will be tokenized in
+ four tokens: the already mentioned ones and another empty one as the last one
+ and a string @c "a::b::" will have five tokens.
+ */
+ wxTOKEN_RET_EMPTY_ALL,
+
+ /**
+ 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 ::wxTOKEN_RET_EMPTY. Notice that there is no
+ mode like this one but behaving like ::wxTOKEN_RET_EMPTY_ALL instead of
+ ::wxTOKEN_RET_EMPTY, use ::wxTOKEN_RET_EMPTY_ALL and
+ wxStringTokenizer::GetLastDelimiter() to emulate it.
+ */
+ wxTOKEN_RET_DELIMS,
+
+ /**
+ In this mode the class behaves exactly like the standard @c strtok() function:
+ the empty tokens are never returned.
+ */
+ wxTOKEN_STRTOK
+};
+
/**
@class wxStringTokenizer
@wxheader{tokenzr.h}
- wxStringTokenizer helps you to break a string up into a number of tokens. It
- replaces the standard C function @c strtok() and also extends it in a
+ wxStringTokenizer helps you to break a string up into a number of tokens.
+ It replaces the standard C function @c 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 wxStringTokenizer::GetNextToken may be called
- repeatedly until it wxStringTokenizer::HasMoreTokens
- returns @false.
+ Then wxStringTokenizer::GetNextToken() may be called repeatedly until
+ wxStringTokenizer::HasMoreTokens() returns @false.
For example:
@code
- wxStringTokenizer tkz(wxT("first:second:third:fourth"), wxT(":"));
- while ( tkz.HasMoreTokens() )
+ wxStringTokenizer tokenizer("first:second:third:fourth", ":");
+ while ( tokenizer.HasMoreTokens() )
{
- wxString token = tkz.GetNextToken();
+ wxString token = tokenizer.GetNextToken();
// process token here
}
@endcode
- By default, wxStringTokenizer will behave in the same way as @c 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. @c TAB or comma delimited text
- files).
-
- The behaviour is governed by the last
- @ref wxStringTokenizer::wxstringtokenizer
- constructor/wxStringTokenizer::SetString
- parameter @c mode which may be one of the following:
-
-
-
- @c wxTOKEN_DEFAULT
-
-
- Default behaviour (as described above):
- same as @c wxTOKEN_STRTOK if the delimiter string contains only
- whitespaces, same as @c wxTOKEN_RET_EMPTY otherwise
-
-
- @c wxTOKEN_RET_EMPTY
-
-
- In this mode, the empty tokens in the
- middle of the string will be returned, i.e. @c "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 @c "a::b::" would
- still result in the same set of tokens.
-
-
- @c 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 @c "a::b:" will be tokenized in four tokens: the already
- mentioned ones and another empty one as the last one and a string
- @c "a::b::" will have five tokens.
-
-
- @c 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
- @c wxTOKEN_RET_EMPTY. Notice that there is no mode like this one but
- behaving like @c wxTOKEN_RET_EMPTY_ALL instead of
- @c wxTOKEN_RET_EMPTY, use @c wxTOKEN_RET_EMPTY_ALL and
- wxStringTokenizer::GetLastDelimiter to emulate it.
-
-
- @c wxTOKEN_STRTOK
-
-
- In this mode the class behaves exactly like
- the standard @c strtok() function: the empty tokens are never returned.
-
-
-
@library{wxbase}
@category{data}
@@ -104,31 +94,35 @@
class wxStringTokenizer : public wxObject
{
public:
- //@{
/**
- Constructor. Pass the string to tokenize, a string containing delimiters
- and the mode specifying how the string should be tokenized.
+ Default constructor. You must call SetString() before calling any other
+ methods.
*/
wxStringTokenizer();
+ /**
+ Constructor. Pass the string to tokenize, a string containing
+ delimiters, and the @a mode specifying how the string should be
+ tokenized.
+
+ @see SetString()
+ */
wxStringTokenizer(const wxString& str,
const wxString& delims = " \t\r\n",
wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
- //@}
/**
- Returns the number of tokens remaining in the input string. The number of
- tokens returned by this function is decremented each time
- GetNextToken() is called and when it
- reaches 0 HasMoreTokens() returns
- @false.
+ Returns the number of tokens remaining in the input string. The number
+ of tokens returned by this function is decremented each time
+ GetNextToken() is called and when it reaches 0, HasMoreTokens()
+ returns @false.
*/
int CountTokens() const;
/**
Returns the delimiter which ended scan for the last token returned by
- GetNextToken() or @c NUL if
- there had been no calls to this function yet or if it returned the trailing
- empty token in @c wxTOKEN_RET_EMPTY_ALL mode.
+ GetNextToken() or @c NUL if there had been no calls to this function
+ yet or if it returned the trailing empty token in
+ ::wxTOKEN_RET_EMPTY_ALL mode.
@since 2.7.0
*/
@@ -157,12 +151,11 @@ public:
bool HasMoreTokens() const;
/**
- Initializes the tokenizer.
- Pass the string to tokenize, a string containing delimiters,
- and the mode specifying how the string should be tokenized.
+ Initializes the tokenizer. Pass the string to tokenize, a string
+ containing delimiters, and the @a mode specifying how the string
+ should be tokenized.
*/
void SetString(const wxString& to_tokenize,
const wxString& delims = " \t\r\n",
wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
};
-