interface/wx/tokenzr.h

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