interface/wx/arrstr.h

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