2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Name: tokenzr.h
|
2008-03-10 11:24:38 -04:00
|
|
|
// Purpose: interface of wxStringTokenizer
|
2008-03-08 08:52:38 -05:00
|
|
|
// Author: wxWidgets team
|
2010-07-13 09:29:13 -04:00
|
|
|
// Licence: wxWindows licence
|
2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
2008-05-06 03:06:08 -04:00
|
|
|
/**
|
|
|
|
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,
|
2009-12-20 10:07:08 -05:00
|
|
|
i.e. @c "a::b:" will be tokenized in three tokens @c 'a', @c '' and @c 'b'.
|
|
|
|
Notice that all trailing delimiters are ignored in this mode, not just the last one,
|
2008-05-06 03:06:08 -04:00
|
|
|
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
|
|
|
|
};
|
|
|
|
|
2012-03-03 19:29:07 -05:00
|
|
|
/// Default wxStringTokenizer delimiters are the usual white space characters.
|
|
|
|
#define wxDEFAULT_DELIMITERS " \t\r\n"
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxStringTokenizer
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-05-06 03:06:08 -04:00
|
|
|
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
|
2008-03-08 08:52:38 -05:00
|
|
|
number of ways.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
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).
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-05-06 03:06:08 -04:00
|
|
|
Then wxStringTokenizer::GetNextToken() may be called repeatedly until
|
|
|
|
wxStringTokenizer::HasMoreTokens() returns @false.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
For example:
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@code
|
2008-05-06 03:06:08 -04:00
|
|
|
wxStringTokenizer tokenizer("first:second:third:fourth", ":");
|
|
|
|
while ( tokenizer.HasMoreTokens() )
|
2008-03-08 08:52:38 -05:00
|
|
|
{
|
2008-05-06 03:06:08 -04:00
|
|
|
wxString token = tokenizer.GetNextToken();
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
// process token here
|
|
|
|
}
|
|
|
|
@endcode
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxbase}
|
|
|
|
@category{data}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2010-05-26 19:05:04 -04:00
|
|
|
@see ::wxStringTokenize()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxStringTokenizer : public wxObject
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
2008-05-06 03:06:08 -04:00
|
|
|
Default constructor. You must call SetString() before calling any other
|
|
|
|
methods.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
wxStringTokenizer();
|
2008-05-06 03:06:08 -04:00
|
|
|
/**
|
|
|
|
Constructor. Pass the string to tokenize, a string containing
|
|
|
|
delimiters, and the @a mode specifying how the string should be
|
|
|
|
tokenized.
|
|
|
|
|
|
|
|
@see SetString()
|
|
|
|
*/
|
2008-03-08 09:43:31 -05:00
|
|
|
wxStringTokenizer(const wxString& str,
|
2012-03-03 19:29:07 -05:00
|
|
|
const wxString& delims = wxDEFAULT_DELIMITERS,
|
2008-03-08 09:43:31 -05:00
|
|
|
wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-05-06 03:06:08 -04:00
|
|
|
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.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-10-28 11:36:26 -04:00
|
|
|
size_t CountTokens() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-03-08 09:43:31 -05:00
|
|
|
Returns the delimiter which ended scan for the last token returned by
|
2008-05-06 03:06:08 -04:00
|
|
|
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.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-04-21 06:34:23 -04:00
|
|
|
@since 2.7.0
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
wxChar GetLastDelimiter() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the next token or empty string if the end of string was reached.
|
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
wxString GetNextToken();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2012-11-30 19:14:07 -05:00
|
|
|
Returns the current position (i.e.\ one index after the last returned
|
2008-03-08 08:52:38 -05:00
|
|
|
token or 0 if GetNextToken() has never been called) in the original
|
|
|
|
string.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
size_t GetPosition() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2015-10-20 13:44:06 -04:00
|
|
|
Returns the part of the initial string which is yet to be tokenized.
|
|
|
|
|
|
|
|
That is, the substring from the current position up to the end,
|
|
|
|
possibly empty if there are no more tokens left.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxString GetString() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the tokenizer has further tokens, @false if none are left.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
bool HasMoreTokens() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-05-06 03:06:08 -04:00
|
|
|
Initializes the tokenizer. Pass the string to tokenize, a string
|
|
|
|
containing delimiters, and the @a mode specifying how the string
|
|
|
|
should be tokenized.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2012-03-03 19:29:07 -05:00
|
|
|
void SetString(const wxString& str,
|
|
|
|
const wxString& delims = wxDEFAULT_DELIMITERS,
|
2008-03-08 08:52:38 -05:00
|
|
|
wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
|
|
|
|
};
|
2010-05-26 19:05:04 -04:00
|
|
|
|
|
|
|
|
|
|
|
/** @addtogroup group_funcmacro_string */
|
|
|
|
//@{
|
|
|
|
|
|
|
|
/**
|
|
|
|
This is a convenience function wrapping wxStringTokenizer which simply
|
|
|
|
returns all tokens found in the given @a str as an array.
|
|
|
|
|
|
|
|
Please see wxStringTokenizer::wxStringTokenizer for the description
|
|
|
|
of the other parameters.
|
|
|
|
|
|
|
|
@return The array with the parsed tokens.
|
|
|
|
|
2013-03-30 21:12:04 -04:00
|
|
|
@header{wx/tokenzr.h}
|
2010-05-26 19:05:04 -04:00
|
|
|
*/
|
|
|
|
wxArrayString
|
|
|
|
wxStringTokenize(const wxString& str,
|
|
|
|
const wxString& delims = wxDEFAULT_DELIMITERS,
|
|
|
|
wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
|
2012-03-03 19:29:07 -05:00
|
|
|
|
2010-05-26 19:05:04 -04:00
|
|
|
//@}
|