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 char** a);
  46     wxArrayString(size_t sz, const wchar_t** a);
  47     wxArrayString(size_t sz, const wxString* a);
  48
  49     int Index(const wxString& str, bool bCase = true, bool bFromEnd = false) const;
  50
  51     void Sort(bool reverseOrder = false);
  52     void Sort(CompareFunction function);
  53     void Sort(CMPFUNCwxString function) { wxArrayStringBase::Sort(function); }
  54
  55     size_t Add(const wxString& string, size_t copies = 1)
  56     {
  57         wxArrayStringBase::Add(string, copies);
  58         return size() - copies;
  59     }
  60 };
  61
  62 class WXDLLIMPEXP_BASE wxSortedArrayString : public wxSortedArrayStringBase
  63 {
  64 public:
  65     wxSortedArrayString() : wxSortedArrayStringBase(wxStringSortAscending)
  66         { }
  67     wxSortedArrayString(const wxSortedArrayString& array)
  68         : wxSortedArrayStringBase(array)
  69         { }
  70     wxSortedArrayString(const wxArrayString& src)
  71         : wxSortedArrayStringBase(wxStringSortAscending)
  72     {
  73         reserve(src.size());
  74
  75         for ( size_t n = 0; n < src.size(); n++ )
  76             Add(src[n]);
  77     }
  78
  79     int Index(const wxString& str, bool bCase = true, bool bFromEnd = false) const;
  80 };
  81
  82 #else // if !wxUSE_STL
  83
  84 class WXDLLIMPEXP_BASE wxArrayString
  85 {
  86 public:
  87   // type of function used by wxArrayString::Sort()
  88   typedef int (wxCMPFUNC_CONV *CompareFunction)(const wxString& first,
  89                                  const wxString& second);
  90   // type of function used by wxArrayString::Sort(), for compatibility with
  91   // wxArray
  92   typedef int (wxCMPFUNC_CONV *CompareFunction2)(wxString* first,
  93                                   wxString* second);
  94
  95   // constructors and destructor
  96     // default ctor
  97   wxArrayString() { Init(false); }
  98     // if autoSort is true, the array is always sorted (in alphabetical order)
  99     //
 100     // NB: the reason for using int and not bool is that like this we can avoid
 101     //     using this ctor for implicit conversions from "const char *" (which
 102     //     we'd like to be implicitly converted to wxString instead!)
 103     //
 104     //     of course, using explicit would be even better - if all compilers
 105     //     supported it...
 106   wxArrayString(int autoSort) { Init(autoSort != 0); }
 107     // C string array ctor
 108   wxArrayString(size_t sz, const char** a);
 109   wxArrayString(size_t sz, const wchar_t** a);
 110     // wxString string array ctor
 111   wxArrayString(size_t sz, const wxString* a);
 112     // copy ctor
 113   wxArrayString(const wxArrayString& array);
 114     // assignment operator
 115   wxArrayString& operator=(const wxArrayString& src);
 116     // not virtual, this class should not be derived from
 117  ~wxArrayString();
 118
 119   // memory management
 120     // empties the list, but doesn't release memory
 121   void Empty();
 122     // empties the list and releases memory
 123   void Clear();
 124     // preallocates memory for given number of items
 125   void Alloc(size_t nCount);
 126     // minimzes the memory usage (by freeing all extra memory)
 127   void Shrink();
 128
 129   // simple accessors
 130     // number of elements in the array
 131   size_t GetCount() const { return m_nCount; }
 132     // is it empty?
 133   bool IsEmpty() const { return m_nCount == 0; }
 134     // number of elements in the array (GetCount is preferred API)
 135   size_t Count() const { return m_nCount; }
 136
 137   // items access (range checking is done in debug version)
 138     // get item at position uiIndex
 139   wxString& Item(size_t nIndex) const
 140     {
 141         wxASSERT_MSG( nIndex < m_nCount,
 142                       _T("wxArrayString: index out of bounds") );
 143
 144         return m_pItems[nIndex];
 145     }
 146
 147     // same as Item()
 148   wxString& operator[](size_t nIndex) const { return Item(nIndex); }
 149     // get last item
 150   wxString& Last() const
 151   {
 152       wxASSERT_MSG( !IsEmpty(),
 153                     _T("wxArrayString: index out of bounds") );
 154       return Item(GetCount() - 1);
 155   }
 156
 157
 158   // item management
 159     // Search the element in the array, starting from the beginning if
 160     // bFromEnd is false or from end otherwise. If bCase, comparison is case
 161     // sensitive (default). Returns index of the first item matched or
 162     // wxNOT_FOUND
 163   int  Index (const wxString& str, bool bCase = true, bool bFromEnd = false) const;
 164     // add new element at the end (if the array is not sorted), return its
 165     // index
 166   size_t Add(const wxString& str, size_t nInsert = 1);
 167     // add new element at given position
 168   void Insert(const wxString& str, size_t uiIndex, size_t nInsert = 1);
 169     // expand the array to have count elements
 170   void SetCount(size_t count);
 171     // remove first item matching this value
 172   void Remove(const wxString& sz);
 173     // remove item by index
 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   // TODO: this code duplicates the one in dynarray.h
 202   class reverse_iterator
 203   {
 204     typedef wxString value_type;
 205     typedef value_type* pointer;
 206     typedef value_type& reference;
 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     const itor operator++(int)
 221       { reverse_iterator tmp = *this; --m_ptr; return tmp; }
 222     itor& operator--() { ++m_ptr; return *this; }
 223     const itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 224     bool operator ==(const itor& it) const { return m_ptr == it.m_ptr; }
 225     bool operator !=(const itor& it) const { return m_ptr != it.m_ptr; }
 226   };
 227
 228   class const_reverse_iterator
 229   {
 230     typedef wxString value_type;
 231     typedef const value_type* pointer;
 232     typedef const value_type& reference;
 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     const itor operator++(int)
 248       { itor tmp = *this; --m_ptr; return tmp; }
 249     itor& operator--() { ++m_ptr; return *this; }
 250     const itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 251     bool operator ==(const itor& it) const { return m_ptr == it.m_ptr; }
 252     bool operator !=(const itor& it) const { return m_ptr != it.m_ptr; }
 253   };
 254
 255   wxArrayString(const_iterator first, const_iterator last)
 256     { Init(false); assign(first, last); }
 257   wxArrayString(size_type n, const_reference v) { Init(false); assign(n, v); }
 258   void assign(const_iterator first, const_iterator last);
 259   void assign(size_type n, const_reference v)
 260     { clear(); Add(v, n); }
 261   reference back() { return *(end() - 1); }
 262   const_reference back() const { return *(end() - 1); }
 263   iterator begin() { return m_pItems; }
 264   const_iterator begin() const { return m_pItems; }
 265   size_type capacity() const { return m_nSize; }
 266   void clear() { Clear(); }
 267   bool empty() const { return IsEmpty(); }
 268   iterator end() { return begin() + GetCount(); }
 269   const_iterator end() const { return begin() + GetCount(); }
 270   iterator erase(iterator first, iterator last)
 271   {
 272       size_t idx = first - begin();
 273       RemoveAt(idx, last - first);
 274       return begin() + idx;
 275   }
 276   iterator erase(iterator it) { return erase(it, it + 1); }
 277   reference front() { return *begin(); }
 278   const_reference front() const { return *begin(); }
 279   void insert(iterator it, size_type n, const_reference v)
 280     { Insert(v, it - begin(), n); }
 281   iterator insert(iterator it, const_reference v = value_type())
 282     { size_t idx = it - begin(); Insert(v, idx); return begin() + idx; }
 283   void insert(iterator it, const_iterator first, const_iterator last);
 284   size_type max_size() const { return INT_MAX; }
 285   void pop_back() { RemoveAt(GetCount() - 1); }
 286   void push_back(const_reference v) { Add(v); }
 287   reverse_iterator rbegin() { return reverse_iterator(end() - 1); }
 288   const_reverse_iterator rbegin() const;
 289   reverse_iterator rend() { return reverse_iterator(begin() - 1); }
 290   const_reverse_iterator rend() const;
 291   void reserve(size_type n) /* base::reserve*/;
 292   void resize(size_type n, value_type v = value_type());
 293   size_type size() const { return GetCount(); }
 294
 295 protected:
 296   void Init(bool autoSort);             // common part of all ctors
 297   void Copy(const wxArrayString& src);  // copies the contents of another array
 298
 299 private:
 300   void Grow(size_t nIncrement = 0);     // makes array bigger if needed
 301
 302   void DoSort();                        // common part of all Sort() variants
 303
 304   size_t  m_nSize,    // current size of the array
 305           m_nCount;   // current number of elements
 306
 307   wxString *m_pItems; // pointer to data
 308
 309   bool    m_autoSort; // if true, keep the array always sorted
 310 };
 311
 312 class WXDLLIMPEXP_BASE wxSortedArrayString : public wxArrayString
 313 {
 314 public:
 315   wxSortedArrayString() : wxArrayString(true)
 316     { }
 317   wxSortedArrayString(const wxArrayString& array) : wxArrayString(true)
 318     { Copy(array); }
 319 };
 320
 321 #endif // !wxUSE_STL
 322
 323 // this class provides a temporary wxString* from a
 324 // wxArrayString
 325 class WXDLLIMPEXP_BASE wxCArrayString
 326 {
 327 public:
 328     wxCArrayString( const wxArrayString& array )
 329         : m_array( array ), m_strings( NULL )
 330     { }
 331     ~wxCArrayString() { delete[] m_strings; }
 332
 333     size_t GetCount() const { return m_array.GetCount(); }
 334     wxString* GetStrings()
 335     {
 336         if( m_strings ) return m_strings;
 337         size_t count = m_array.GetCount();
 338         m_strings = new wxString[count];
 339         for( size_t i = 0; i < count; ++i )
 340             m_strings[i] = m_array[i];
 341         return m_strings;
 342     }
 343 private:
 344     const wxArrayString& m_array;
 345     wxString* m_strings;
 346 };
 347
 348
 349 // ----------------------------------------------------------------------------
 350 // helper functions for working with arrays
 351 // ----------------------------------------------------------------------------
 352
 353 // by default, these functions use the escape character to escape the
 354 // separators occuring inside the string to be joined, this can be disabled by
 355 // passing '\0' as escape
 356
 357 WXDLLIMPEXP_BASE wxString wxJoin(const wxArrayString& arr,
 358                                  const wxChar sep,
 359                                  const wxChar escape = wxT('\\'));
 360
 361 WXDLLIMPEXP_BASE wxArrayString wxSplit(const wxString& str,
 362                                        const wxChar sep,
 363                                        const wxChar escape = wxT('\\'));
 364
 365
 366 // ----------------------------------------------------------------------------
 367 // This helper class allows to pass both C array of wxStrings or wxArrayString
 368 // using the same interface.
 369 //
 370 // Use it when you have two methods taking wxArrayString or (int, wxString[]),
 371 // that do the same thing. This class lets you iterate over input data in the
 372 // same way whether it is a raw array of strings or wxArrayString.
 373 //
 374 // The object does not take ownership of the data -- internally it keeps
 375 // pointers to the data, therefore the data must be disposed of by user
 376 // and only after this object is destroyed. Usually it is not a problem as
 377 // only temporary objects of this class are used.
 378 // ----------------------------------------------------------------------------
 379
 380 class wxArrayStringsAdapter
 381 {
 382 public:
 383     // construct an adapter from a wxArrayString
 384     wxArrayStringsAdapter(const wxArrayString& strings)
 385         : m_type(wxSTRING_ARRAY), m_size(strings.size())
 386     {
 387         m_data.array = &strings;
 388     }
 389
 390     // construct an adapter from a wxString[]
 391     wxArrayStringsAdapter(unsigned int n, const wxString *strings)
 392         : m_type(wxSTRING_POINTER), m_size(n)
 393     {
 394         m_data.ptr = strings;
 395     }
 396
 397     // construct an adapter from a single wxString
 398     wxArrayStringsAdapter(const wxString& s)
 399         : m_type(wxSTRING_POINTER), m_size(1)
 400     {
 401         m_data.ptr = &s;
 402     }
 403
 404     // default copy constructor is ok
 405
 406     // iteration interface
 407     size_t GetCount() const { return m_size; }
 408     bool IsEmpty() const { return GetCount() == 0; }
 409     const wxString& operator[] (unsigned int i) const
 410     {
 411         wxASSERT_MSG( i < GetCount(), wxT("index out of bounds") );
 412         if(m_type == wxSTRING_POINTER)
 413             return m_data.ptr[i];
 414         return m_data.array->Item(i);
 415     }
 416     wxArrayString AsArrayString() const
 417     {
 418         if(m_type == wxSTRING_ARRAY)
 419             return *m_data.array;
 420         return wxArrayString(GetCount(), m_data.ptr);
 421     }
 422
 423 private:
 424     // type of the data being held
 425     enum wxStringContainerType
 426     {
 427         wxSTRING_ARRAY,  // wxArrayString
 428         wxSTRING_POINTER // wxString[]
 429     };
 430
 431     wxStringContainerType m_type;
 432     size_t m_size;
 433     union
 434     {
 435         const wxString *      ptr;
 436         const wxArrayString * array;
 437     } m_data;
 438
 439     DECLARE_NO_ASSIGN_CLASS(wxArrayStringsAdapter)
 440 };
 441
 442 #endif // _WX_ARRSTR_H