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