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