interface/wx/tokenzr.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        tokenzr.h
   3 // Purpose:     interface of wxStringTokenizer
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     The behaviour of wxStringTokenizer is governed by the
  11     wxStringTokenizer::wxStringTokenizer() or wxStringTokenizer::SetString()
  12     with the parameter @e mode, which may be one of the following:
  13 */
  14 enum wxStringTokenizerMode
  15 {
  16     wxTOKEN_INVALID = -1,   ///< Invalid tokenizer mode.
  17
  18     /**
  19         Default behaviour: wxStringTokenizer will behave in the same way as
  20         @c strtok() (::wxTOKEN_STRTOK) if the delimiters string only contains
  21         white space characters but, unlike the standard function, it will
  22         behave like ::wxTOKEN_RET_EMPTY, returning empty tokens if this is not
  23         the case. This is helpful for parsing strictly formatted data where
  24         the number of fields is fixed but some of them may be empty (i.e.
  25         @c TAB or comma delimited text files).
  26     */
  27     wxTOKEN_DEFAULT,
  28
  29     /**
  30         In this mode, the empty tokens in the middle of the string will be returned,
  31         i.e. @c "a::b:" will be tokenized in three tokens @c 'a', @c '' and @c 'b'.
  32         Notice that all trailing delimiters are ignored in this mode, not just the last one,
  33         i.e. a string @c "a::b::" would still result in the same set of tokens.
  34     */
  35     wxTOKEN_RET_EMPTY,
  36
  37     /**
  38         In this mode, empty trailing tokens (including the one after the last delimiter
  39         character) will be returned as well. The string @c "a::b:" will be tokenized in
  40         four tokens: the already mentioned ones and another empty one as the last one
  41         and a string @c "a::b::" will have five tokens.
  42     */
  43     wxTOKEN_RET_EMPTY_ALL,
  44
  45     /**
  46         In this mode, the delimiter character after the end of the current token (there
  47         may be none if this is the last token) is returned appended to the token.
  48         Otherwise, it is the same mode as ::wxTOKEN_RET_EMPTY. Notice that there is no
  49         mode like this one but behaving like ::wxTOKEN_RET_EMPTY_ALL instead of
  50         ::wxTOKEN_RET_EMPTY, use ::wxTOKEN_RET_EMPTY_ALL and
  51         wxStringTokenizer::GetLastDelimiter() to emulate it.
  52     */
  53     wxTOKEN_RET_DELIMS,
  54
  55     /**
  56         In this mode the class behaves exactly like the standard @c strtok() function:
  57         the empty tokens are never returned.
  58     */
  59     wxTOKEN_STRTOK
  60 };
  61
  62 /// Default wxStringTokenizer delimiters are the usual white space characters.
  63 #define wxDEFAULT_DELIMITERS " \t\r\n"
  64
  65 /**
  66     @class wxStringTokenizer
  67
  68     wxStringTokenizer helps you to break a string up into a number of tokens.
  69     It replaces the standard C function @c strtok() and also extends it in a
  70     number of ways.
  71
  72     To use this class, you should create a wxStringTokenizer object, give it the
  73     string to tokenize and also the delimiters which separate tokens in the string
  74     (by default, white space characters will be used).
  75
  76     Then wxStringTokenizer::GetNextToken() may be called repeatedly until
  77     wxStringTokenizer::HasMoreTokens() returns @false.
  78
  79     For example:
  80
  81     @code
  82     wxStringTokenizer tokenizer("first:second:third:fourth", ":");
  83     while ( tokenizer.HasMoreTokens() )
  84     {
  85         wxString token = tokenizer.GetNextToken();
  86
  87         // process token here
  88     }
  89     @endcode
  90
  91     @library{wxbase}
  92     @category{data}
  93
  94     @see ::wxStringTokenize()
  95 */
  96 class wxStringTokenizer : public wxObject
  97 {
  98 public:
  99     /**
 100         Default constructor. You must call SetString() before calling any other
 101         methods.
 102     */
 103     wxStringTokenizer();
 104     /**
 105         Constructor. Pass the string to tokenize, a string containing
 106         delimiters, and the @a mode specifying how the string should be
 107         tokenized.
 108
 109         @see SetString()
 110    */
 111     wxStringTokenizer(const wxString& str,
 112                       const wxString& delims = wxDEFAULT_DELIMITERS,
 113                       wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
 114
 115     /**
 116         Returns the number of tokens remaining in the input string. The number
 117         of tokens returned by this function is decremented each time
 118         GetNextToken() is called and when it reaches 0, HasMoreTokens()
 119         returns @false.
 120     */
 121     size_t CountTokens() const;
 122
 123     /**
 124         Returns the delimiter which ended scan for the last token returned by
 125         GetNextToken() or @c NUL if there had been no calls to this function
 126         yet or if it returned the trailing empty token in
 127         ::wxTOKEN_RET_EMPTY_ALL mode.
 128
 129         @since 2.7.0
 130     */
 131     wxChar GetLastDelimiter() const;
 132
 133     /**
 134         Returns the next token or empty string if the end of string was reached.
 135     */
 136     wxString GetNextToken();
 137
 138     /**
 139         Returns the current position (i.e.\ one index after the last returned
 140         token or 0 if GetNextToken() has never been called) in the original
 141         string.
 142     */
 143     size_t GetPosition() const;
 144
 145     /**
 146         Returns the part of the starting string without all token already extracted.
 147     */
 148     wxString GetString() const;
 149
 150     /**
 151         Returns @true if the tokenizer has further tokens, @false if none are left.
 152     */
 153     bool HasMoreTokens() const;
 154
 155     /**
 156         Initializes the tokenizer. Pass the string to tokenize, a string
 157         containing delimiters, and the @a mode specifying how the string
 158         should be tokenized.
 159     */
 160     void SetString(const wxString& str,
 161                    const wxString& delims = wxDEFAULT_DELIMITERS,
 162                    wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
 163 };
 164
 165
 166 /** @addtogroup group_funcmacro_string */
 167 //@{
 168
 169 /**
 170     This is a convenience function wrapping wxStringTokenizer which simply
 171     returns all tokens found in the given @a str as an array.
 172
 173     Please see wxStringTokenizer::wxStringTokenizer for the description
 174     of the other parameters.
 175
 176     @return The array with the parsed tokens.
 177
 178     @header{wx/tokenzr.h}
 179 */
 180 wxArrayString
 181 wxStringTokenize(const wxString& str,
 182                  const wxString& delims = wxDEFAULT_DELIMITERS,
 183                  wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
 184
 185 //@}