include/wx/arrstr.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        include/wx/arrstr.h
   3 // Purpose:     wxArrayString class
   4 // Author:      Mattia Barbon and Vadim Zeitlin
   5 // Modified by:
   6 // Created:     07/07/03
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2003 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_ARRSTR_H
  13 #define _WX_ARRSTR_H
  14
  15 #include "wx/defs.h"
  16 #include "wx/string.h"
  17
  18 int WXDLLIMPEXP_BASE wxStringSortAscending(wxString*, wxString*);
  19 int WXDLLIMPEXP_BASE wxStringSortDescending(wxString*, wxString*);
  20
  21 #if wxUSE_STL
  22
  23 #include "wx/dynarray.h"
  24
  25 typedef int (*CMPFUNCwxString)(wxString*, wxString*);
  26 WX_DECLARE_EXPORTED_BASEARRAY(wxString, wxBaseArrayStringBase);
  27 WX_DEFINE_EXPORTED_TYPEARRAY(wxString, wxArrayStringBase,
  28                              wxBaseArrayStringBase);
  29 _WX_DEFINE_SORTED_TYPEARRAY_2(wxString, wxSortedArrayStringBase,
  30                               wxBaseArrayStringBase, = wxStringSortAscending,
  31                               class WXDLLIMPEXP_BASE, CMPFUNCwxString);
  32
  33 class WXDLLIMPEXP_BASE wxArrayString : public wxArrayStringBase
  34 {
  35 public:
  36     wxArrayString() { }
  37     wxArrayString(const wxArrayString& a) : wxArrayStringBase(a) { }
  38 };
  39
  40 class WXDLLIMPEXP_BASE wxSortedArrayString : public wxSortedArrayStringBase
  41 {
  42 public:
  43     wxSortedArrayString() : wxSortedArrayStringBase(wxStringSortAscending)
  44         { }
  45     wxSortedArrayString(const wxSortedArrayString& array)
  46         : wxSortedArrayStringBase(array)
  47         { }
  48     wxSortedArrayString(const wxArrayString& src)
  49         : wxSortedArrayStringBase(wxStringSortAscending)
  50     {
  51         reserve(src.size());
  52
  53         for ( size_t n = 0; n < src.size(); n++ )
  54             Add(src[n]);
  55     }
  56 };
  57
  58 #else // if !wxUSE_STL
  59
  60 // ----------------------------------------------------------------------------
  61 // The string array uses it's knowledge of internal structure of the wxString
  62 // class to optimize string storage. Normally, we would store pointers to
  63 // string, but as wxString is, in fact, itself a pointer (sizeof(wxString) is
  64 // sizeof(char *)) we store these pointers instead. The cast to "wxString *" is
  65 // really all we need to turn such pointer into a string!
  66 //
  67 // Of course, it can be called a dirty hack, but we use twice less memory and
  68 // this approach is also more speed efficient, so it's probably worth it.
  69 //
  70 // Usage notes: when a string is added/inserted, a new copy of it is created,
  71 // so the original string may be safely deleted. When a string is retrieved
  72 // from the array (operator[] or Item() method), a reference is returned.
  73 // ----------------------------------------------------------------------------
  74
  75 class WXDLLIMPEXP_BASE wxArrayString
  76 {
  77 public:
  78   // type of function used by wxArrayString::Sort()
  79   typedef int (*CompareFunction)(const wxString& first,
  80                                  const wxString& second);
  81   // type of function used by wxArrayString::Sort(), for compatibility with
  82   // wxArray
  83   typedef int (*CompareFunction2)(wxString* first,
  84                                   wxString* second);
  85
  86   // constructors and destructor
  87     // default ctor
  88   wxArrayString()
  89       : m_nSize(0), m_nCount(0), m_pItems(NULL), m_autoSort(FALSE)
  90       { Init(FALSE); }
  91     // if autoSort is TRUE, the array is always sorted (in alphabetical order)
  92     //
  93     // NB: the reason for using int and not bool is that like this we can avoid
  94     //     using this ctor for implicit conversions from "const char *" (which
  95     //     we'd like to be implicitly converted to wxString instead!)
  96     //
  97     //     of course, using explicit would be even better - if all compilers
  98     //     supported it...
  99   wxArrayString(int autoSort)
 100       : m_nSize(0), m_nCount(0), m_pItems(NULL), m_autoSort(FALSE)
 101       { Init(autoSort != 0); }
 102     // copy ctor
 103   wxArrayString(const wxArrayString& array);
 104     // assignment operator
 105   wxArrayString& operator=(const wxArrayString& src);
 106     // not virtual, this class should not be derived from
 107  ~wxArrayString();
 108
 109   // memory management
 110     // empties the list, but doesn't release memory
 111   void Empty();
 112     // empties the list and releases memory
 113   void Clear();
 114     // preallocates memory for given number of items
 115   void Alloc(size_t nCount);
 116     // minimzes the memory usage (by freeing all extra memory)
 117   void Shrink();
 118
 119   // simple accessors
 120     // number of elements in the array
 121   size_t GetCount() const { return m_nCount; }
 122     // is it empty?
 123   bool IsEmpty() const { return m_nCount == 0; }
 124     // number of elements in the array (GetCount is preferred API)
 125   size_t Count() const { return m_nCount; }
 126
 127   // items access (range checking is done in debug version)
 128     // get item at position uiIndex
 129   wxString& Item(size_t nIndex) const
 130     {
 131         wxASSERT_MSG( nIndex < m_nCount,
 132                       _T("wxArrayString: index out of bounds") );
 133
 134         return *(wxString *)&(m_pItems[nIndex]);
 135     }
 136
 137     // same as Item()
 138   wxString& operator[](size_t nIndex) const { return Item(nIndex); }
 139     // get last item
 140   wxString& Last() const
 141   {
 142       wxASSERT_MSG( !IsEmpty(),
 143                     _T("wxArrayString: index out of bounds") );
 144       return Item(Count() - 1);
 145   }
 146
 147 #if WXWIN_COMPATIBILITY_2_4
 148     // return a wxString[], useful for the controls which
 149     // take one in their ctor.  You must delete[] it yourself
 150     // once you are done with it.  Will return NULL if the
 151     // ArrayString was empty.
 152   wxString* GetStringArray() const;
 153 #endif
 154
 155   // item management
 156     // Search the element in the array, starting from the beginning if
 157     // bFromEnd is FALSE or from end otherwise. If bCase, comparison is case
 158     // sensitive (default). Returns index of the first item matched or
 159     // wxNOT_FOUND
 160   int  Index (const wxChar *sz, bool bCase = TRUE, bool bFromEnd = FALSE) const;
 161     // add new element at the end (if the array is not sorted), return its
 162     // index
 163   size_t Add(const wxString& str, size_t nInsert = 1);
 164     // add new element at given position
 165   void Insert(const wxString& str, size_t uiIndex, size_t nInsert = 1);
 166     // expand the array to have count elements
 167   void SetCount(size_t count);
 168     // remove first item matching this value
 169   void Remove(const wxChar *sz);
 170     // remove item by index
 171 #if WXWIN_COMPATIBILITY_2_4
 172   void Remove(size_t nIndex, size_t nRemove = 1) { RemoveAt(nIndex, nRemove); }
 173 #endif
 174   void RemoveAt(size_t nIndex, size_t nRemove = 1);
 175
 176   // sorting
 177     // sort array elements in alphabetical order (or reversed alphabetical
 178     // order if reverseOrder parameter is TRUE)
 179   void Sort(bool reverseOrder = FALSE);
 180     // sort array elements using specified comparaison function
 181   void Sort(CompareFunction compareFunction);
 182   void Sort(CompareFunction2 compareFunction);
 183
 184   // comparison
 185     // compare two arrays case sensitively
 186   bool operator==(const wxArrayString& a) const;
 187     // compare two arrays case sensitively
 188   bool operator!=(const wxArrayString& a) const { return !(*this == a); }
 189
 190   // STL-like interface
 191   typedef wxString value_type;
 192   typedef value_type* pointer;
 193   typedef const value_type* const_pointer;
 194   typedef value_type* iterator;
 195   typedef const value_type* const_iterator;
 196   typedef value_type& reference;
 197   typedef const value_type& const_reference;
 198   typedef int difference_type;
 199   typedef size_t size_type;
 200
 201   // FIXME: same in dynarray.h
 202   class reverse_iterator
 203   {
 204     typedef wxArrayString name;
 205     typedef name::reference reference;
 206     typedef name::pointer pointer;
 207     typedef reverse_iterator itor;
 208     friend itor operator+(int o, const itor& it);
 209     friend itor operator+(const itor& it, int o);
 210     friend itor operator-(const itor& it, int o);
 211     friend difference_type operator -(const itor& i1, const itor& i2);
 212   public:
 213     pointer m_ptr;
 214     reverse_iterator() : m_ptr(NULL) { }
 215     reverse_iterator(pointer ptr) : m_ptr(ptr) { }
 216     reverse_iterator(const itor& it) : m_ptr(it.m_ptr) { }
 217     reference operator*() const { return *m_ptr; }
 218     pointer operator->() const { return m_ptr; }
 219     itor operator++() { --m_ptr; return *this; }
 220     itor operator++(int)
 221       { reverse_iterator tmp = *this; --m_ptr; return tmp; }
 222     itor operator--() { ++m_ptr; return *this; }
 223     itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 224     bool operator ==(const itor& it) { return m_ptr == it.m_ptr; }
 225     bool operator !=(const itor& it) { return m_ptr != it.m_ptr; }
 226   };
 227
 228   class const_reverse_iterator
 229   {
 230     typedef wxArrayString name;
 231     typedef name::const_reference reference;
 232     typedef name::const_pointer pointer;
 233     typedef const_reverse_iterator itor;
 234     friend itor operator+(int o, const itor& it);
 235     friend itor operator+(const itor& it, int o);
 236     friend itor operator-(const itor& it, int o);
 237     friend difference_type operator -(const itor& i1, const itor& i2);
 238   public:
 239     pointer m_ptr;
 240     const_reverse_iterator() : m_ptr(NULL) { }
 241     const_reverse_iterator(pointer ptr) : m_ptr(ptr) { }
 242     const_reverse_iterator(const itor& it) : m_ptr(it.m_ptr) { }
 243     const_reverse_iterator(const reverse_iterator& it) : m_ptr(it.m_ptr) { }
 244     reference operator*() const { return *m_ptr; }
 245     pointer operator->() const { return m_ptr; }
 246     itor operator++() { --m_ptr; return *this; }
 247     itor operator++(int)
 248       { itor tmp = *this; --m_ptr; return tmp; }
 249     itor operator--() { ++m_ptr; return *this; }
 250     itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 251     bool operator ==(const itor& it) { return m_ptr == it.m_ptr; }
 252     bool operator !=(const itor& it) { return m_ptr != it.m_ptr; }
 253   };
 254
 255   void assign(const_iterator first, const_iterator last);
 256   void assign(size_type n, const_reference v)
 257     { clear(); Add(v, n); }
 258   reference back() { return *(end() - 1); }
 259   const_reference back() const { return *(end() - 1); }
 260   iterator begin() { return (wxString *)&(m_pItems[0]); }
 261   const_iterator begin() const { return (wxString *)&(m_pItems[0]); }
 262   size_type capacity() const { return m_nSize; }
 263   void clear() { Clear(); }
 264   bool empty() const { return IsEmpty(); }
 265   iterator end() { return begin() + GetCount(); }
 266   const_iterator end() const { return begin() + GetCount(); }
 267   iterator erase(iterator first, iterator last)
 268   {
 269       size_t idx = first - begin();
 270       RemoveAt(idx, last - first);
 271       return begin() + idx;
 272   }
 273   iterator erase(iterator it) { return erase(it, it + 1); }
 274   reference front() { return *begin(); }
 275   const_reference front() const { return *begin(); }
 276   void insert(iterator it, size_type n, const_reference v)
 277     { Insert(v, it - begin(), n); }
 278   iterator insert(iterator it, const_reference v = value_type())
 279     { size_t idx = it - begin(); Insert(v, idx); return begin() + idx; }
 280   void insert(iterator it, const_iterator first, const_iterator last);
 281   size_type max_size() const { return INT_MAX; }
 282   void pop_back() { RemoveAt(GetCount() - 1); }
 283   void push_back(const_reference v) { Add(v); }
 284   reverse_iterator rbegin() { return reverse_iterator(end() - 1); }
 285   const_reverse_iterator rbegin() const;
 286   reverse_iterator rend() { return reverse_iterator(begin() - 1); }
 287   const_reverse_iterator rend() const;
 288   void reserve(size_type n) /* base::reserve*/;
 289   void resize(size_type n, value_type v = value_type());
 290   size_type size() const { return GetCount(); }
 291
 292 protected:
 293   void Init(bool autoSort);             // common part of all ctors
 294   void Copy(const wxArrayString& src);  // copies the contents of another array
 295
 296 private:
 297   void Grow(size_t nIncrement = 0);     // makes array bigger if needed
 298   void Free();                          // free all the strings stored
 299
 300   void DoSort();                        // common part of all Sort() variants
 301
 302   size_t  m_nSize,    // current size of the array
 303           m_nCount;   // current number of elements
 304
 305   wxChar  **m_pItems; // pointer to data
 306
 307   bool    m_autoSort; // if TRUE, keep the array always sorted
 308 };
 309
 310 class WXDLLIMPEXP_BASE wxSortedArrayString : public wxArrayString
 311 {
 312 public:
 313   wxSortedArrayString() : wxArrayString(TRUE)
 314     { }
 315   wxSortedArrayString(const wxArrayString& array) : wxArrayString(TRUE)
 316     { Copy(array); }
 317 };
 318
 319 #endif // !wxUSE_STL
 320
 321 #endif