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