| 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 | /** |
| 63 | @class wxStringTokenizer |
| 64 | |
| 65 | wxStringTokenizer helps you to break a string up into a number of tokens. |
| 66 | It replaces the standard C function @c strtok() and also extends it in a |
| 67 | number of ways. |
| 68 | |
| 69 | To use this class, you should create a wxStringTokenizer object, give it the |
| 70 | string to tokenize and also the delimiters which separate tokens in the string |
| 71 | (by default, white space characters will be used). |
| 72 | |
| 73 | Then wxStringTokenizer::GetNextToken() may be called repeatedly until |
| 74 | wxStringTokenizer::HasMoreTokens() returns @false. |
| 75 | |
| 76 | For example: |
| 77 | |
| 78 | @code |
| 79 | wxStringTokenizer tokenizer("first:second:third:fourth", ":"); |
| 80 | while ( tokenizer.HasMoreTokens() ) |
| 81 | { |
| 82 | wxString token = tokenizer.GetNextToken(); |
| 83 | |
| 84 | // process token here |
| 85 | } |
| 86 | @endcode |
| 87 | |
| 88 | @library{wxbase} |
| 89 | @category{data} |
| 90 | |
| 91 | @see ::wxStringTokenize() |
| 92 | */ |
| 93 | class wxStringTokenizer : public wxObject |
| 94 | { |
| 95 | public: |
| 96 | /** |
| 97 | Default constructor. You must call SetString() before calling any other |
| 98 | methods. |
| 99 | */ |
| 100 | wxStringTokenizer(); |
| 101 | /** |
| 102 | Constructor. Pass the string to tokenize, a string containing |
| 103 | delimiters, and the @a mode specifying how the string should be |
| 104 | tokenized. |
| 105 | |
| 106 | @see SetString() |
| 107 | */ |
| 108 | wxStringTokenizer(const wxString& str, |
| 109 | const wxString& delims = " \t\r\n", |
| 110 | wxStringTokenizerMode mode = wxTOKEN_DEFAULT); |
| 111 | |
| 112 | /** |
| 113 | Returns the number of tokens remaining in the input string. The number |
| 114 | of tokens returned by this function is decremented each time |
| 115 | GetNextToken() is called and when it reaches 0, HasMoreTokens() |
| 116 | returns @false. |
| 117 | */ |
| 118 | size_t CountTokens() const; |
| 119 | |
| 120 | /** |
| 121 | Returns the delimiter which ended scan for the last token returned by |
| 122 | GetNextToken() or @c NUL if there had been no calls to this function |
| 123 | yet or if it returned the trailing empty token in |
| 124 | ::wxTOKEN_RET_EMPTY_ALL mode. |
| 125 | |
| 126 | @since 2.7.0 |
| 127 | */ |
| 128 | wxChar GetLastDelimiter() const; |
| 129 | |
| 130 | /** |
| 131 | Returns the next token or empty string if the end of string was reached. |
| 132 | */ |
| 133 | wxString GetNextToken(); |
| 134 | |
| 135 | /** |
| 136 | Returns the current position (i.e. one index after the last returned |
| 137 | token or 0 if GetNextToken() has never been called) in the original |
| 138 | string. |
| 139 | */ |
| 140 | size_t GetPosition() const; |
| 141 | |
| 142 | /** |
| 143 | Returns the part of the starting string without all token already extracted. |
| 144 | */ |
| 145 | wxString GetString() const; |
| 146 | |
| 147 | /** |
| 148 | Returns @true if the tokenizer has further tokens, @false if none are left. |
| 149 | */ |
| 150 | bool HasMoreTokens() const; |
| 151 | |
| 152 | /** |
| 153 | Initializes the tokenizer. Pass the string to tokenize, a string |
| 154 | containing delimiters, and the @a mode specifying how the string |
| 155 | should be tokenized. |
| 156 | */ |
| 157 | void SetString(const wxString& to_tokenize, |
| 158 | const wxString& delims = " \t\r\n", |
| 159 | wxStringTokenizerMode mode = wxTOKEN_DEFAULT); |
| 160 | }; |
| 161 | |
| 162 | |
| 163 | /** @addtogroup group_funcmacro_string */ |
| 164 | //@{ |
| 165 | |
| 166 | /** |
| 167 | This is a convenience function wrapping wxStringTokenizer which simply |
| 168 | returns all tokens found in the given @a str as an array. |
| 169 | |
| 170 | Please see wxStringTokenizer::wxStringTokenizer for the description |
| 171 | of the other parameters. |
| 172 | |
| 173 | @return The array with the parsed tokens. |
| 174 | |
| 175 | @header{wx/string.h} |
| 176 | */ |
| 177 | wxArrayString |
| 178 | wxStringTokenize(const wxString& str, |
| 179 | const wxString& delims = wxDEFAULT_DELIMITERS, |
| 180 | wxStringTokenizerMode mode = wxTOKEN_DEFAULT); |
| 181 | |
| 182 | //@} |