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 #if wxUSE_STL
  19
  20 #include "wx/dynarray.h"
  21
  22 inline int wxCMPFUNC_CONV wxStringSortAscending(wxString* s1, wxString* s2)
  23 {
  24     return s1->Cmp(*s2);
  25 }
  26
  27 inline int wxCMPFUNC_CONV wxStringSortDescending(wxString* s1, wxString* s2)
  28 {
  29     return wxStringSortAscending(s2, s1);
  30 }
  31
  32 typedef int (wxCMPFUNC_CONV *CMPFUNCwxString)(wxString*, wxString*);
  33 typedef wxString _wxArraywxBaseArrayStringBase;
  34 _WX_DECLARE_BASEARRAY_2(_wxArraywxBaseArrayStringBase, wxBaseArrayStringBase,
  35                         wxArray_SortFunction<wxString>,
  36                         class WXDLLIMPEXP_BASE);
  37 WX_DEFINE_USER_EXPORTED_TYPEARRAY(wxString, wxArrayStringBase,
  38                                   wxBaseArrayStringBase, WXDLLIMPEXP_BASE);
  39 _WX_DEFINE_SORTED_TYPEARRAY_2(wxString, wxSortedArrayStringBase,
  40                               wxBaseArrayStringBase, = wxStringSortAscending,
  41                               class WXDLLIMPEXP_BASE, CMPFUNCwxString);
  42
  43 class WXDLLIMPEXP_BASE wxArrayString : public wxArrayStringBase
  44 {
  45 public:
  46     // type of function used by wxArrayString::Sort()
  47     typedef int (wxCMPFUNC_CONV *CompareFunction)(const wxString& first,
  48                                                   const wxString& second);
  49
  50     wxArrayString() { }
  51     wxArrayString(const wxArrayString& a) : wxArrayStringBase(a) { }
  52     wxArrayString(size_t sz, const char** a);
  53     wxArrayString(size_t sz, const wchar_t** a);
  54     wxArrayString(size_t sz, const wxString* a);
  55
  56     int Index(const wxString& str, bool bCase = true, bool bFromEnd = false) const;
  57
  58     void Sort(bool reverseOrder = false);
  59     void Sort(CompareFunction function);
  60     void Sort(CMPFUNCwxString function) { wxArrayStringBase::Sort(function); }
  61
  62     size_t Add(const wxString& string, size_t copies = 1)
  63     {
  64         wxArrayStringBase::Add(string, copies);
  65         return size() - copies;
  66     }
  67 };
  68
  69 class WXDLLIMPEXP_BASE wxSortedArrayString : public wxSortedArrayStringBase
  70 {
  71 public:
  72     wxSortedArrayString() : wxSortedArrayStringBase(wxStringSortAscending)
  73         { }
  74     wxSortedArrayString(const wxSortedArrayString& array)
  75         : wxSortedArrayStringBase(array)
  76         { }
  77     wxSortedArrayString(const wxArrayString& src)
  78         : wxSortedArrayStringBase(wxStringSortAscending)
  79     {
  80         reserve(src.size());
  81
  82         for ( size_t n = 0; n < src.size(); n++ )
  83             Add(src[n]);
  84     }
  85
  86     int Index(const wxString& str, bool bCase = true, bool bFromEnd = false) const;
  87 };
  88
  89 #else // if !wxUSE_STL
  90
  91 class WXDLLIMPEXP_BASE wxArrayString
  92 {
  93 public:
  94   // type of function used by wxArrayString::Sort()
  95   typedef int (wxCMPFUNC_CONV *CompareFunction)(const wxString& first,
  96                                  const wxString& second);
  97   // type of function used by wxArrayString::Sort(), for compatibility with
  98   // wxArray
  99   typedef int (wxCMPFUNC_CONV *CompareFunction2)(wxString* first,
 100                                   wxString* second);
 101
 102   // constructors and destructor
 103     // default ctor
 104   wxArrayString() { Init(false); }
 105     // if autoSort is true, the array is always sorted (in alphabetical order)
 106     //
 107     // NB: the reason for using int and not bool is that like this we can avoid
 108     //     using this ctor for implicit conversions from "const char *" (which
 109     //     we'd like to be implicitly converted to wxString instead!)
 110     //
 111     //     of course, using explicit would be even better - if all compilers
 112     //     supported it...
 113   wxArrayString(int autoSort) { Init(autoSort != 0); }
 114     // C string array ctor
 115   wxArrayString(size_t sz, const char** a);
 116   wxArrayString(size_t sz, const wchar_t** 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 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(GetCount() - 1);
 162   }
 163
 164
 165   // item management
 166     // Search the element in the array, starting from the beginning if
 167     // bFromEnd is false or from end otherwise. If bCase, comparison is case
 168     // sensitive (default). Returns index of the first item matched or
 169     // wxNOT_FOUND
 170   int  Index (const wxString& str, bool bCase = true, bool bFromEnd = false) const;
 171     // add new element at the end (if the array is not sorted), return its
 172     // index
 173   size_t Add(const wxString& str, size_t nInsert = 1);
 174     // add new element at given position
 175   void Insert(const wxString& str, size_t uiIndex, size_t nInsert = 1);
 176     // expand the array to have count elements
 177   void SetCount(size_t count);
 178     // remove first item matching this value
 179   void Remove(const wxString& sz);
 180     // remove item by index
 181   void RemoveAt(size_t nIndex, size_t nRemove = 1);
 182
 183   // sorting
 184     // sort array elements in alphabetical order (or reversed alphabetical
 185     // order if reverseOrder parameter is true)
 186   void Sort(bool reverseOrder = false);
 187     // sort array elements using specified comparison function
 188   void Sort(CompareFunction compareFunction);
 189   void Sort(CompareFunction2 compareFunction);
 190
 191   // comparison
 192     // compare two arrays case sensitively
 193   bool operator==(const wxArrayString& a) const;
 194     // compare two arrays case sensitively
 195   bool operator!=(const wxArrayString& a) const { return !(*this == a); }
 196
 197   // STL-like interface
 198   typedef wxString value_type;
 199   typedef value_type* pointer;
 200   typedef const value_type* const_pointer;
 201   typedef value_type* iterator;
 202   typedef const value_type* const_iterator;
 203   typedef value_type& reference;
 204   typedef const value_type& const_reference;
 205   typedef int difference_type;
 206   typedef size_t size_type;
 207
 208   // TODO: this code duplicates the one in dynarray.h
 209   class reverse_iterator
 210   {
 211     typedef wxString value_type;
 212     typedef value_type* pointer;
 213     typedef value_type& reference;
 214     typedef reverse_iterator itor;
 215     friend itor operator+(int o, const itor& it);
 216     friend itor operator+(const itor& it, int o);
 217     friend itor operator-(const itor& it, int o);
 218     friend difference_type operator -(const itor& i1, const itor& i2);
 219   public:
 220     pointer m_ptr;
 221     reverse_iterator() : m_ptr(NULL) { }
 222     reverse_iterator(pointer ptr) : m_ptr(ptr) { }
 223     reverse_iterator(const itor& it) : m_ptr(it.m_ptr) { }
 224     reference operator*() const { return *m_ptr; }
 225     pointer operator->() const { return m_ptr; }
 226     itor& operator++() { --m_ptr; return *this; }
 227     const itor operator++(int)
 228       { reverse_iterator tmp = *this; --m_ptr; return tmp; }
 229     itor& operator--() { ++m_ptr; return *this; }
 230     const itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 231     bool operator ==(const itor& it) const { return m_ptr == it.m_ptr; }
 232     bool operator !=(const itor& it) const { return m_ptr != it.m_ptr; }
 233   };
 234
 235   class const_reverse_iterator
 236   {
 237     typedef wxString value_type;
 238     typedef const value_type* pointer;
 239     typedef const value_type& reference;
 240     typedef const_reverse_iterator itor;
 241     friend itor operator+(int o, const itor& it);
 242     friend itor operator+(const itor& it, int o);
 243     friend itor operator-(const itor& it, int o);
 244     friend difference_type operator -(const itor& i1, const itor& i2);
 245   public:
 246     pointer m_ptr;
 247     const_reverse_iterator() : m_ptr(NULL) { }
 248     const_reverse_iterator(pointer ptr) : m_ptr(ptr) { }
 249     const_reverse_iterator(const itor& it) : m_ptr(it.m_ptr) { }
 250     const_reverse_iterator(const reverse_iterator& it) : m_ptr(it.m_ptr) { }
 251     reference operator*() const { return *m_ptr; }
 252     pointer operator->() const { return m_ptr; }
 253     itor& operator++() { --m_ptr; return *this; }
 254     const itor operator++(int)
 255       { itor tmp = *this; --m_ptr; return tmp; }
 256     itor& operator--() { ++m_ptr; return *this; }
 257     const itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 258     bool operator ==(const itor& it) const { return m_ptr == it.m_ptr; }
 259     bool operator !=(const itor& it) const { return m_ptr != it.m_ptr; }
 260   };
 261
 262   wxArrayString(const_iterator first, const_iterator last)
 263     { Init(false); assign(first, last); }
 264   wxArrayString(size_type n, const_reference v) { Init(false); assign(n, v); }
 265   void assign(const_iterator first, const_iterator last);
 266   void assign(size_type n, const_reference v)
 267     { clear(); Add(v, n); }
 268   reference back() { return *(end() - 1); }
 269   const_reference back() const { return *(end() - 1); }
 270   iterator begin() { return m_pItems; }
 271   const_iterator begin() const { return m_pItems; }
 272   size_type capacity() const { return m_nSize; }
 273   void clear() { Clear(); }
 274   bool empty() const { return IsEmpty(); }
 275   iterator end() { return begin() + GetCount(); }
 276   const_iterator end() const { return begin() + GetCount(); }
 277   iterator erase(iterator first, iterator last)
 278   {
 279       size_t idx = first - begin();
 280       RemoveAt(idx, last - first);
 281       return begin() + idx;
 282   }
 283   iterator erase(iterator it) { return erase(it, it + 1); }
 284   reference front() { return *begin(); }
 285   const_reference front() const { return *begin(); }
 286   void insert(iterator it, size_type n, const_reference v)
 287     { Insert(v, it - begin(), n); }
 288   iterator insert(iterator it, const_reference v = value_type())
 289     { size_t idx = it - begin(); Insert(v, idx); return begin() + idx; }
 290   void insert(iterator it, const_iterator first, const_iterator last);
 291   size_type max_size() const { return INT_MAX; }
 292   void pop_back() { RemoveAt(GetCount() - 1); }
 293   void push_back(const_reference v) { Add(v); }
 294   reverse_iterator rbegin() { return reverse_iterator(end() - 1); }
 295   const_reverse_iterator rbegin() const;
 296   reverse_iterator rend() { return reverse_iterator(begin() - 1); }
 297   const_reverse_iterator rend() const;
 298   void reserve(size_type n) /* base::reserve*/;
 299   void resize(size_type n, value_type v = value_type());
 300   size_type size() const { return GetCount(); }
 301
 302 protected:
 303   void Init(bool autoSort);             // common part of all ctors
 304   void Copy(const wxArrayString& src);  // copies the contents of another array
 305
 306 private:
 307   void Grow(size_t nIncrement = 0);     // makes array bigger if needed
 308
 309   size_t  m_nSize,    // current size of the array
 310           m_nCount;   // current number of elements
 311
 312   wxString *m_pItems; // pointer to data
 313
 314   bool    m_autoSort; // if true, keep the array always sorted
 315 };
 316
 317 class WXDLLIMPEXP_BASE wxSortedArrayString : public wxArrayString
 318 {
 319 public:
 320   wxSortedArrayString() : wxArrayString(true)
 321     { }
 322   wxSortedArrayString(const wxArrayString& array) : wxArrayString(true)
 323     { Copy(array); }
 324 };
 325
 326 #endif // !wxUSE_STL
 327
 328 // this class provides a temporary wxString* from a
 329 // wxArrayString
 330 class WXDLLIMPEXP_BASE wxCArrayString
 331 {
 332 public:
 333     wxCArrayString( const wxArrayString& array )
 334         : m_array( array ), m_strings( NULL )
 335     { }
 336     ~wxCArrayString() { delete[] m_strings; }
 337
 338     size_t GetCount() const { return m_array.GetCount(); }
 339     wxString* GetStrings()
 340     {
 341         if( m_strings ) return m_strings;
 342         size_t count = m_array.GetCount();
 343         m_strings = new wxString[count];
 344         for( size_t i = 0; i < count; ++i )
 345             m_strings[i] = m_array[i];
 346         return m_strings;
 347     }
 348 private:
 349     const wxArrayString& m_array;
 350     wxString* m_strings;
 351 };
 352
 353
 354 // ----------------------------------------------------------------------------
 355 // helper functions for working with arrays
 356 // ----------------------------------------------------------------------------
 357
 358 // by default, these functions use the escape character to escape the
 359 // separators occuring inside the string to be joined, this can be disabled by
 360 // passing '\0' as escape
 361
 362 WXDLLIMPEXP_BASE wxString wxJoin(const wxArrayString& arr,
 363                                  const wxChar sep,
 364                                  const wxChar escape = wxT('\\'));
 365
 366 WXDLLIMPEXP_BASE wxArrayString wxSplit(const wxString& str,
 367                                        const wxChar sep,
 368                                        const wxChar escape = wxT('\\'));
 369
 370
 371 // ----------------------------------------------------------------------------
 372 // This helper class allows to pass both C array of wxStrings or wxArrayString
 373 // using the same interface.
 374 //
 375 // Use it when you have two methods taking wxArrayString or (int, wxString[]),
 376 // that do the same thing. This class lets you iterate over input data in the
 377 // same way whether it is a raw array of strings or wxArrayString.
 378 //
 379 // The object does not take ownership of the data -- internally it keeps
 380 // pointers to the data, therefore the data must be disposed of by user
 381 // and only after this object is destroyed. Usually it is not a problem as
 382 // only temporary objects of this class are used.
 383 // ----------------------------------------------------------------------------
 384
 385 class wxArrayStringsAdapter
 386 {
 387 public:
 388     // construct an adapter from a wxArrayString
 389     wxArrayStringsAdapter(const wxArrayString& strings)
 390         : m_type(wxSTRING_ARRAY), m_size(strings.size())
 391     {
 392         m_data.array = &strings;
 393     }
 394
 395     // construct an adapter from a wxString[]
 396     wxArrayStringsAdapter(unsigned int n, const wxString *strings)
 397         : m_type(wxSTRING_POINTER), m_size(n)
 398     {
 399         m_data.ptr = strings;
 400     }
 401
 402     // construct an adapter from a single wxString
 403     wxArrayStringsAdapter(const wxString& s)
 404         : m_type(wxSTRING_POINTER), m_size(1)
 405     {
 406         m_data.ptr = &s;
 407     }
 408
 409     // default copy constructor is ok
 410
 411     // iteration interface
 412     size_t GetCount() const { return m_size; }
 413     bool IsEmpty() const { return GetCount() == 0; }
 414     const wxString& operator[] (unsigned int i) const
 415     {
 416         wxASSERT_MSG( i < GetCount(), wxT("index out of bounds") );
 417         if(m_type == wxSTRING_POINTER)
 418             return m_data.ptr[i];
 419         return m_data.array->Item(i);
 420     }
 421     wxArrayString AsArrayString() const
 422     {
 423         if(m_type == wxSTRING_ARRAY)
 424             return *m_data.array;
 425         return wxArrayString(GetCount(), m_data.ptr);
 426     }
 427
 428 private:
 429     // type of the data being held
 430     enum wxStringContainerType
 431     {
 432         wxSTRING_ARRAY,  // wxArrayString
 433         wxSTRING_POINTER // wxString[]
 434     };
 435
 436     wxStringContainerType m_type;
 437     size_t m_size;
 438     union
 439     {
 440         const wxString *      ptr;
 441         const wxArrayString * array;
 442     } m_data;
 443
 444     DECLARE_NO_ASSIGN_CLASS(wxArrayStringsAdapter)
 445 };
 446
 447 #endif // _WX_ARRSTR_H