| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: arrstr.h |
| 3 | // Purpose: interface of wxArrayString |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | @class wxArrayString |
| 11 | |
| 12 | wxArrayString is an efficient container for storing wxString objects. |
| 13 | |
| 14 | It has the same features as all wxArray classes, i.e. it dynamically expands |
| 15 | when new items are added to it (so it is as easy to use as a linked list), |
| 16 | but the access time to the elements is constant, instead of being linear in |
| 17 | number of elements as in the case of linked lists. It is also very size |
| 18 | efficient and doesn't take more space than a C array @e wxString[] type |
| 19 | (wxArrayString uses its knowledge of internals of wxString class to achieve this). |
| 20 | |
| 21 | This class is used in the same way as other dynamic arrays(), except that no |
| 22 | ::WX_DEFINE_ARRAY declaration is needed for it. |
| 23 | When a string is added or inserted in the array, a copy of the string is created, |
| 24 | so the original string may be safely deleted (e.g. if it was a @e wxChar * |
| 25 | pointer the memory it was using can be freed immediately after this). |
| 26 | In general, there is no need to worry about string memory deallocation when using |
| 27 | this class - it will always free the memory it uses itself. |
| 28 | |
| 29 | The references returned by wxArrayString::Item, wxArrayString::Last or |
| 30 | wxArrayString::operator[] are not constant, so the array elements may |
| 31 | be modified in place like this: |
| 32 | |
| 33 | @code |
| 34 | array.Last().MakeUpper(); |
| 35 | @endcode |
| 36 | |
| 37 | @note none of the methods of wxArrayString is virtual including its |
| 38 | destructor, so this class should not be used as a base class. |
| 39 | |
| 40 | Although this is not true strictly speaking, this class may be considered as |
| 41 | a specialization of wxArray class for the wxString member data: it is not |
| 42 | implemented like this, but it does have all of the wxArray functions. |
| 43 | |
| 44 | It also has the full set of <tt>std::vector<wxString></tt> compatible |
| 45 | methods, including nested @c iterator and @c const_iterator classes which |
| 46 | should be used in the new code for forward compatibility with the future |
| 47 | wxWidgets versions. |
| 48 | |
| 49 | @library{wxbase} |
| 50 | @category{containers} |
| 51 | |
| 52 | @see wxArray<T>, wxString, @ref overview_string |
| 53 | */ |
| 54 | class wxArrayString : public wxArray |
| 55 | { |
| 56 | public: |
| 57 | /** |
| 58 | The function type used with wxArrayString::Sort function. |
| 59 | */ |
| 60 | typedef int (*CompareFunction)(const wxString& first, const wxString& second); |
| 61 | |
| 62 | /** |
| 63 | Default constructor. |
| 64 | */ |
| 65 | wxArrayString(); |
| 66 | |
| 67 | /** |
| 68 | Copy constructor. |
| 69 | */ |
| 70 | wxArrayString(const wxArrayString& array); |
| 71 | |
| 72 | //@{ |
| 73 | /** |
| 74 | Constructor from a C string array. Pass a size @a sz and an array @a arr. |
| 75 | **/ |
| 76 | wxArrayString(size_t sz, const char** arr); |
| 77 | wxArrayString(size_t sz, const wchar_t** arr); |
| 78 | //@} |
| 79 | |
| 80 | /** |
| 81 | Constructor from a wxString array. Pass a size @a sz and array @a arr. |
| 82 | */ |
| 83 | wxArrayString(size_t sz, const wxString* arr); |
| 84 | |
| 85 | /** |
| 86 | Destructor frees memory occupied by the array strings. For performance |
| 87 | reasons it is not virtual, so this class should not be derived from. |
| 88 | */ |
| 89 | ~wxArrayString(); |
| 90 | |
| 91 | /** |
| 92 | Appends the given number of @a copies of the new item @a str to the |
| 93 | array and returns the index of the first new item in the array. |
| 94 | |
| 95 | @see Insert() |
| 96 | */ |
| 97 | size_t Add(const wxString& str, size_t copies = 1); |
| 98 | |
| 99 | /** |
| 100 | Preallocates enough memory to store @a nCount items. |
| 101 | |
| 102 | This function may be used to improve array class performance before |
| 103 | adding a known number of items consecutively. |
| 104 | */ |
| 105 | void Alloc(size_t nCount); |
| 106 | |
| 107 | /** |
| 108 | Clears the array contents and frees memory. |
| 109 | |
| 110 | @see Empty() |
| 111 | */ |
| 112 | void Clear(); |
| 113 | |
| 114 | /** |
| 115 | Empties the array: after a call to this function GetCount() will return 0. |
| 116 | However, this function does not free the memory used by the array and so |
| 117 | should be used when the array is going to be reused for storing other strings. |
| 118 | Otherwise, you should use Clear() to empty the array and free memory. |
| 119 | */ |
| 120 | void Empty(); |
| 121 | |
| 122 | /** |
| 123 | Returns the number of items in the array. |
| 124 | */ |
| 125 | size_t GetCount() const; |
| 126 | |
| 127 | /** |
| 128 | Search the element in the array, starting from the beginning if @a bFromEnd |
| 129 | is @false or from end otherwise. If @a bCase, comparison is case sensitive |
| 130 | (default), otherwise the case is ignored. |
| 131 | |
| 132 | This function uses linear search for wxArrayString. |
| 133 | Returns index of the first item matched or @c wxNOT_FOUND if there is no match. |
| 134 | */ |
| 135 | int Index(const wxString& sz, bool bCase = true, bool bFromEnd = false) const; |
| 136 | |
| 137 | /** |
| 138 | Insert the given number of @a copies of the new element in the array before the |
| 139 | position @a nIndex. Thus, for example, to insert the string in the beginning of |
| 140 | the array you would write: |
| 141 | |
| 142 | @code |
| 143 | Insert("foo", 0); |
| 144 | @endcode |
| 145 | |
| 146 | If @a nIndex is equal to GetCount() this function behaves as Add(). |
| 147 | */ |
| 148 | void Insert(wxString lItem, size_t nIndex, size_t copies = 1); |
| 149 | |
| 150 | /** |
| 151 | Returns @true if the array is empty, @false otherwise. This function returns the |
| 152 | same result as GetCount() == 0 but is probably easier to read. |
| 153 | */ |
| 154 | bool IsEmpty() const; |
| 155 | |
| 156 | /** |
| 157 | Return the array element at position @a nIndex. An assert failure will |
| 158 | result from an attempt to access an element beyond the end of array in debug |
| 159 | mode, but no check is done in release mode. |
| 160 | |
| 161 | @see operator[] for the operator version. |
| 162 | */ |
| 163 | wxString& Item(size_t nIndex) const; |
| 164 | |
| 165 | /** |
| 166 | Returns the last element of the array. Attempt to access the last element of |
| 167 | an empty array will result in assert failure in debug build, however no checks |
| 168 | are done in release mode. |
| 169 | */ |
| 170 | wxString& Last() const; |
| 171 | |
| 172 | /** |
| 173 | Removes the first item matching this value. An assert failure is provoked by |
| 174 | an attempt to remove an element which does not exist in debug build. |
| 175 | |
| 176 | @see Index() |
| 177 | */ |
| 178 | void Remove(const wxString& sz); |
| 179 | |
| 180 | /** |
| 181 | Removes @a count items starting at position @a nIndex from the array. |
| 182 | */ |
| 183 | void RemoveAt(size_t nIndex, size_t count = 1); |
| 184 | |
| 185 | /** |
| 186 | Releases the extra memory allocated by the array. |
| 187 | This function is useful to minimize the array memory consumption. |
| 188 | |
| 189 | @see Alloc() |
| 190 | */ |
| 191 | void Shrink(); |
| 192 | |
| 193 | /** |
| 194 | Sorts the array in alphabetical order or in reverse alphabetical order if |
| 195 | @a reverseOrder is @true. The sort is case-sensitive. |
| 196 | */ |
| 197 | void Sort(bool reverseOrder = false); |
| 198 | |
| 199 | /** |
| 200 | Sorts the array using the specified @a compareFunction for item comparison. |
| 201 | @a CompareFunction is defined as a function taking two <em>const wxString&</em> |
| 202 | parameters and returning an @e int value less than, equal to or greater |
| 203 | than 0 if the first string is less than, equal to or greater than the |
| 204 | second one. |
| 205 | |
| 206 | Example: |
| 207 | The following example sorts strings by their length. |
| 208 | |
| 209 | @code |
| 210 | static int CompareStringLen(const wxString& first, const wxString& second) |
| 211 | { |
| 212 | return first.length() - second.length(); |
| 213 | } |
| 214 | |
| 215 | ... |
| 216 | |
| 217 | wxArrayString array; |
| 218 | |
| 219 | array.Add("one"); |
| 220 | array.Add("two"); |
| 221 | array.Add("three"); |
| 222 | array.Add("four"); |
| 223 | |
| 224 | array.Sort(CompareStringLen); |
| 225 | @endcode |
| 226 | */ |
| 227 | void Sort(CompareFunction compareFunction); |
| 228 | |
| 229 | /** |
| 230 | Compares 2 arrays respecting the case. Returns @true if the arrays have |
| 231 | different number of elements or if the elements don't match pairwise. |
| 232 | */ |
| 233 | bool operator !=(const wxArrayString& array) const; |
| 234 | |
| 235 | /** |
| 236 | Assignment operator. |
| 237 | */ |
| 238 | wxArrayString& operator=(const wxArrayString&); |
| 239 | |
| 240 | /** |
| 241 | Compares 2 arrays respecting the case. Returns @true only if the arrays have |
| 242 | the same number of elements and the same strings in the same order. |
| 243 | */ |
| 244 | bool operator ==(const wxArrayString& array) const; |
| 245 | |
| 246 | /** |
| 247 | Return the array element at position @a nIndex. An assert failure will |
| 248 | result from an attempt to access an element beyond the end of array in |
| 249 | debug mode, but no check is done in release mode. |
| 250 | |
| 251 | This is the operator version of the Item() method. |
| 252 | */ |
| 253 | wxString& operator[](size_t nIndex) const; |
| 254 | }; |
| 255 | |
| 256 | |
| 257 | /** |
| 258 | @class wxSortedArrayString |
| 259 | |
| 260 | wxSortedArrayString is an efficient container for storing wxString objects |
| 261 | which always keeps the string in alphabetical order. |
| 262 | |
| 263 | wxSortedArrayString uses binary search in its wxArrayString::Index() function |
| 264 | (instead of linear search for wxArrayString::Index()) which makes it much more |
| 265 | efficient if you add strings to the array rarely (because, of course, you have |
| 266 | to pay for Index() efficiency by having Add() be slower) but search for them |
| 267 | often. Several methods should not be used with sorted array (basically, all |
| 268 | those which break the order of items) which is mentioned in their description. |
| 269 | |
| 270 | @todo what about STL? who does it integrates? |
| 271 | |
| 272 | @library{wxbase} |
| 273 | @category{containers} |
| 274 | |
| 275 | @see wxArray, wxString, @ref overview_string |
| 276 | */ |
| 277 | class wxSortedArrayString : public wxArrayString |
| 278 | { |
| 279 | public: |
| 280 | |
| 281 | /** |
| 282 | Conversion constructor. |
| 283 | |
| 284 | Constructs a sorted array with the same contents as the (possibly |
| 285 | unsorted) "array" argument. |
| 286 | */ |
| 287 | wxSortedArrayString(const wxArrayString& array); |
| 288 | |
| 289 | /** |
| 290 | @copydoc wxArrayString::Add() |
| 291 | |
| 292 | @warning |
| 293 | For sorted arrays, the index of the inserted item will not be, in general, |
| 294 | equal to GetCount() - 1 because the item is inserted at the correct position |
| 295 | to keep the array sorted and not appended. |
| 296 | */ |
| 297 | size_t Add(const wxString& str, size_t copies = 1); |
| 298 | |
| 299 | |
| 300 | /** |
| 301 | @copydoc wxArrayString::Index() |
| 302 | |
| 303 | This function uses binary search for wxSortedArrayString, but it ignores |
| 304 | the @a bCase and @a bFromEnd parameters. |
| 305 | */ |
| 306 | int Index(const wxString& sz, bool bCase = true, |
| 307 | bool bFromEnd = false) const; |
| 308 | |
| 309 | /** |
| 310 | @warning This function should not be used with sorted arrays because it |
| 311 | could break the order of items and, for example, subsequent calls |
| 312 | to Index() would then not work! |
| 313 | |
| 314 | @warning In STL mode, Insert is private and simply invokes wxFAIL_MSG. |
| 315 | */ |
| 316 | void Insert(const wxString& str, size_t nIndex, |
| 317 | size_t copies = 1); |
| 318 | |
| 319 | //@{ |
| 320 | /** |
| 321 | @warning This function should not be used with sorted array because it could |
| 322 | break the order of items and, for example, subsequent calls to Index() |
| 323 | would then not work! Also, sorting a wxSortedArrayString doesn't make |
| 324 | sense because its elements are always already sorted. |
| 325 | |
| 326 | @warning In STL mode, Sort is private and simply invokes wxFAIL_MSG. |
| 327 | */ |
| 328 | void Sort(bool reverseOrder = false); |
| 329 | void Sort(CompareFunction compareFunction); |
| 330 | //@} |
| 331 | }; |
| 332 | |
| 333 | |
| 334 | // ============================================================================ |
| 335 | // Global functions/macros |
| 336 | // ============================================================================ |
| 337 | |
| 338 | /** @addtogroup group_funcmacro_string */ |
| 339 | //@{ |
| 340 | |
| 341 | /** |
| 342 | Splits the given wxString object using the separator @a sep and returns the |
| 343 | result as a wxArrayString. |
| 344 | |
| 345 | If the @a escape character is non-@NULL, then the occurrences of @a sep |
| 346 | immediately prefixed with @a escape are not considered as separators. |
| 347 | Note that empty tokens will be generated if there are two or more adjacent |
| 348 | separators. |
| 349 | |
| 350 | @see wxJoin() |
| 351 | |
| 352 | @header{wx/arrstr.h} |
| 353 | */ |
| 354 | wxArrayString wxSplit(const wxString& str, const wxChar sep, |
| 355 | const wxChar escape = '\\'); |
| 356 | |
| 357 | /** |
| 358 | Concatenate all lines of the given wxArrayString object using the separator |
| 359 | @a sep and returns the result as a wxString. |
| 360 | |
| 361 | If the @a escape character is non-@NULL, then it's used as prefix for each |
| 362 | occurrence of @a sep in the strings contained in @a arr before joining them |
| 363 | which is necessary in order to be able to recover the original array |
| 364 | contents from the string later using wxSplit(). |
| 365 | |
| 366 | @see wxSplit() |
| 367 | |
| 368 | @header{wx/arrstr.h} |
| 369 | */ |
| 370 | wxString wxJoin(const wxArrayString& arr, const wxChar sep, |
| 371 | const wxChar escape = '\\'); |
| 372 | |
| 373 | //@} |
| 374 | |