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 // this shouldn't be defined for compilers not supporting template methods or
  95 // without std::distance()
  96 //
  97 // FIXME-VC6: currently it's only not defined for VC6 in DLL build as it
  98 //            doesn't export template methods from DLL correctly so even though
  99 //            it compiles them fine, we get link errors when using wxArrayString
 100 #if !defined(__VISUALC6__) || !(defined(WXMAKINGDLL) || defined(WXUSINGDLL))
 101     #define wxHAS_VECTOR_TEMPLATE_ASSIGN
 102 #endif
 103
 104 #ifdef wxHAS_VECTOR_TEMPLATE_ASSIGN
 105     #include "wx/beforestd.h"
 106     #include <iterator>
 107     #include "wx/afterstd.h"
 108 #endif // wxHAS_VECTOR_TEMPLATE_ASSIGN
 109
 110 class WXDLLIMPEXP_BASE wxArrayString
 111 {
 112 public:
 113   // type of function used by wxArrayString::Sort()
 114   typedef int (wxCMPFUNC_CONV *CompareFunction)(const wxString& first,
 115                                  const wxString& second);
 116   // type of function used by wxArrayString::Sort(), for compatibility with
 117   // wxArray
 118   typedef int (wxCMPFUNC_CONV *CompareFunction2)(wxString* first,
 119                                   wxString* second);
 120
 121   // constructors and destructor
 122     // default ctor
 123   wxArrayString() { Init(false); }
 124     // if autoSort is true, the array is always sorted (in alphabetical order)
 125     //
 126     // NB: the reason for using int and not bool is that like this we can avoid
 127     //     using this ctor for implicit conversions from "const char *" (which
 128     //     we'd like to be implicitly converted to wxString instead!)
 129     //
 130     //     of course, using explicit would be even better - if all compilers
 131     //     supported it...
 132   wxArrayString(int autoSort) { Init(autoSort != 0); }
 133     // C string array ctor
 134   wxArrayString(size_t sz, const char** a);
 135   wxArrayString(size_t sz, const wchar_t** a);
 136     // wxString string array ctor
 137   wxArrayString(size_t sz, const wxString* a);
 138     // copy ctor
 139   wxArrayString(const wxArrayString& array);
 140     // assignment operator
 141   wxArrayString& operator=(const wxArrayString& src);
 142     // not virtual, this class should not be derived from
 143  ~wxArrayString();
 144
 145   // memory management
 146     // empties the list, but doesn't release memory
 147   void Empty();
 148     // empties the list and releases memory
 149   void Clear();
 150     // preallocates memory for given number of items
 151   void Alloc(size_t nCount);
 152     // minimzes the memory usage (by freeing all extra memory)
 153   void Shrink();
 154
 155   // simple accessors
 156     // number of elements in the array
 157   size_t GetCount() const { return m_nCount; }
 158     // is it empty?
 159   bool IsEmpty() const { return m_nCount == 0; }
 160     // number of elements in the array (GetCount is preferred API)
 161   size_t Count() const { return m_nCount; }
 162
 163   // items access (range checking is done in debug version)
 164     // get item at position uiIndex
 165   wxString& Item(size_t nIndex) const
 166     {
 167         wxASSERT_MSG( nIndex < m_nCount,
 168                       _T("wxArrayString: index out of bounds") );
 169
 170         return m_pItems[nIndex];
 171     }
 172
 173     // same as Item()
 174   wxString& operator[](size_t nIndex) const { return Item(nIndex); }
 175     // get last item
 176   wxString& Last() const
 177   {
 178       wxASSERT_MSG( !IsEmpty(),
 179                     _T("wxArrayString: index out of bounds") );
 180       return Item(GetCount() - 1);
 181   }
 182
 183
 184   // item management
 185     // Search the element in the array, starting from the beginning if
 186     // bFromEnd is false or from end otherwise. If bCase, comparison is case
 187     // sensitive (default). Returns index of the first item matched or
 188     // wxNOT_FOUND
 189   int  Index (const wxString& str, bool bCase = true, bool bFromEnd = false) const;
 190     // add new element at the end (if the array is not sorted), return its
 191     // index
 192   size_t Add(const wxString& str, size_t nInsert = 1);
 193     // add new element at given position
 194   void Insert(const wxString& str, size_t uiIndex, size_t nInsert = 1);
 195     // expand the array to have count elements
 196   void SetCount(size_t count);
 197     // remove first item matching this value
 198   void Remove(const wxString& sz);
 199     // remove item by index
 200   void RemoveAt(size_t nIndex, size_t nRemove = 1);
 201
 202   // sorting
 203     // sort array elements in alphabetical order (or reversed alphabetical
 204     // order if reverseOrder parameter is true)
 205   void Sort(bool reverseOrder = false);
 206     // sort array elements using specified comparison function
 207   void Sort(CompareFunction compareFunction);
 208   void Sort(CompareFunction2 compareFunction);
 209
 210   // comparison
 211     // compare two arrays case sensitively
 212   bool operator==(const wxArrayString& a) const;
 213     // compare two arrays case sensitively
 214   bool operator!=(const wxArrayString& a) const { return !(*this == a); }
 215
 216   // STL-like interface
 217   typedef wxString value_type;
 218   typedef value_type* pointer;
 219   typedef const value_type* const_pointer;
 220   typedef value_type* iterator;
 221   typedef const value_type* const_iterator;
 222   typedef value_type& reference;
 223   typedef const value_type& const_reference;
 224   typedef int difference_type;
 225   typedef size_t size_type;
 226
 227   // TODO: this code duplicates the one in dynarray.h
 228   class reverse_iterator
 229   {
 230     typedef wxString value_type;
 231     typedef value_type* pointer;
 232     typedef value_type& reference;
 233     typedef 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     reverse_iterator() : m_ptr(NULL) { }
 241     reverse_iterator(pointer ptr) : m_ptr(ptr) { }
 242     reverse_iterator(const itor& it) : m_ptr(it.m_ptr) { }
 243     reference operator*() const { return *m_ptr; }
 244     pointer operator->() const { return m_ptr; }
 245     itor& operator++() { --m_ptr; return *this; }
 246     const itor operator++(int)
 247       { reverse_iterator tmp = *this; --m_ptr; return tmp; }
 248     itor& operator--() { ++m_ptr; return *this; }
 249     const itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 250     bool operator ==(const itor& it) const { return m_ptr == it.m_ptr; }
 251     bool operator !=(const itor& it) const { return m_ptr != it.m_ptr; }
 252   };
 253
 254   class const_reverse_iterator
 255   {
 256     typedef wxString value_type;
 257     typedef const value_type* pointer;
 258     typedef const value_type& reference;
 259     typedef const_reverse_iterator itor;
 260     friend itor operator+(int o, const itor& it);
 261     friend itor operator+(const itor& it, int o);
 262     friend itor operator-(const itor& it, int o);
 263     friend difference_type operator -(const itor& i1, const itor& i2);
 264   public:
 265     pointer m_ptr;
 266     const_reverse_iterator() : m_ptr(NULL) { }
 267     const_reverse_iterator(pointer ptr) : m_ptr(ptr) { }
 268     const_reverse_iterator(const itor& it) : m_ptr(it.m_ptr) { }
 269     const_reverse_iterator(const reverse_iterator& it) : m_ptr(it.m_ptr) { }
 270     reference operator*() const { return *m_ptr; }
 271     pointer operator->() const { return m_ptr; }
 272     itor& operator++() { --m_ptr; return *this; }
 273     const itor operator++(int)
 274       { itor tmp = *this; --m_ptr; return tmp; }
 275     itor& operator--() { ++m_ptr; return *this; }
 276     const itor operator--(int) { itor tmp = *this; ++m_ptr; return tmp; }
 277     bool operator ==(const itor& it) const { return m_ptr == it.m_ptr; }
 278     bool operator !=(const itor& it) const { return m_ptr != it.m_ptr; }
 279   };
 280
 281   wxArrayString(const_iterator first, const_iterator last)
 282     { Init(false); assign(first, last); }
 283   wxArrayString(size_type n, const_reference v) { Init(false); assign(n, v); }
 284
 285 #ifdef wxHAS_VECTOR_TEMPLATE_ASSIGN
 286   template <class Iterator>
 287   void assign(Iterator first, Iterator last)
 288   {
 289       clear();
 290       reserve(std::distance(first, last));
 291       for(; first != last; ++first)
 292           push_back(*first);
 293   }
 294 #else // !wxHAS_VECTOR_TEMPLATE_ASSIGN
 295   void assign(const_iterator first, const_iterator last)
 296   {
 297       clear();
 298       reserve(last - first);
 299       for(; first != last; ++first)
 300           push_back(*first);
 301   }
 302 #endif // wxHAS_VECTOR_TEMPLATE_ASSIGN/!wxHAS_VECTOR_TEMPLATE_ASSIGN
 303
 304   void assign(size_type n, const_reference v)
 305     { clear(); Add(v, n); }
 306   reference back() { return *(end() - 1); }
 307   const_reference back() const { return *(end() - 1); }
 308   iterator begin() { return m_pItems; }
 309   const_iterator begin() const { return m_pItems; }
 310   size_type capacity() const { return m_nSize; }
 311   void clear() { Clear(); }
 312   bool empty() const { return IsEmpty(); }
 313   iterator end() { return begin() + GetCount(); }
 314   const_iterator end() const { return begin() + GetCount(); }
 315   iterator erase(iterator first, iterator last)
 316   {
 317       size_t idx = first - begin();
 318       RemoveAt(idx, last - first);
 319       return begin() + idx;
 320   }
 321   iterator erase(iterator it) { return erase(it, it + 1); }
 322   reference front() { return *begin(); }
 323   const_reference front() const { return *begin(); }
 324   void insert(iterator it, size_type n, const_reference v)
 325     { Insert(v, it - begin(), n); }
 326   iterator insert(iterator it, const_reference v = value_type())
 327     { size_t idx = it - begin(); Insert(v, idx); return begin() + idx; }
 328   void insert(iterator it, const_iterator first, const_iterator last);
 329   size_type max_size() const { return INT_MAX; }
 330   void pop_back() { RemoveAt(GetCount() - 1); }
 331   void push_back(const_reference v) { Add(v); }
 332   reverse_iterator rbegin() { return reverse_iterator(end() - 1); }
 333   const_reverse_iterator rbegin() const
 334     { return const_reverse_iterator(end() - 1); }
 335   reverse_iterator rend() { return reverse_iterator(begin() - 1); }
 336   const_reverse_iterator rend() const
 337     { return const_reverse_iterator(begin() - 1); }
 338   void reserve(size_type n) /* base::reserve*/;
 339   void resize(size_type n, value_type v = value_type());
 340   size_type size() const { return GetCount(); }
 341   void swap(wxArrayString& other)
 342   {
 343       wxSwap(m_nSize, other.m_nSize);
 344       wxSwap(m_nCount, other.m_nCount);
 345       wxSwap(m_pItems, other.m_pItems);
 346       wxSwap(m_autoSort, other.m_autoSort);
 347   }
 348
 349 protected:
 350   void Init(bool autoSort);             // common part of all ctors
 351   void Copy(const wxArrayString& src);  // copies the contents of another array
 352
 353 private:
 354   void Grow(size_t nIncrement = 0);     // makes array bigger if needed
 355
 356   size_t  m_nSize,    // current size of the array
 357           m_nCount;   // current number of elements
 358
 359   wxString *m_pItems; // pointer to data
 360
 361   bool    m_autoSort; // if true, keep the array always sorted
 362 };
 363
 364 class WXDLLIMPEXP_BASE wxSortedArrayString : public wxArrayString
 365 {
 366 public:
 367   wxSortedArrayString() : wxArrayString(true)
 368     { }
 369   wxSortedArrayString(const wxArrayString& array) : wxArrayString(true)
 370     { Copy(array); }
 371 };
 372
 373 #endif // !wxUSE_STL
 374
 375 // this class provides a temporary wxString* from a
 376 // wxArrayString
 377 class WXDLLIMPEXP_BASE wxCArrayString
 378 {
 379 public:
 380     wxCArrayString( const wxArrayString& array )
 381         : m_array( array ), m_strings( NULL )
 382     { }
 383     ~wxCArrayString() { delete[] m_strings; }
 384
 385     size_t GetCount() const { return m_array.GetCount(); }
 386     wxString* GetStrings()
 387     {
 388         if( m_strings ) return m_strings;
 389         size_t count = m_array.GetCount();
 390         m_strings = new wxString[count];
 391         for( size_t i = 0; i < count; ++i )
 392             m_strings[i] = m_array[i];
 393         return m_strings;
 394     }
 395
 396     wxString* Release()
 397     {
 398         wxString *r = GetStrings();
 399         m_strings = NULL;
 400         return r;
 401     }
 402
 403 private:
 404     const wxArrayString& m_array;
 405     wxString* m_strings;
 406 };
 407
 408
 409 // ----------------------------------------------------------------------------
 410 // helper functions for working with arrays
 411 // ----------------------------------------------------------------------------
 412
 413 // by default, these functions use the escape character to escape the
 414 // separators occuring inside the string to be joined, this can be disabled by
 415 // passing '\0' as escape
 416
 417 WXDLLIMPEXP_BASE wxString wxJoin(const wxArrayString& arr,
 418                                  const wxChar sep,
 419                                  const wxChar escape = wxT('\\'));
 420
 421 WXDLLIMPEXP_BASE wxArrayString wxSplit(const wxString& str,
 422                                        const wxChar sep,
 423                                        const wxChar escape = wxT('\\'));
 424
 425
 426 // ----------------------------------------------------------------------------
 427 // This helper class allows to pass both C array of wxStrings or wxArrayString
 428 // using the same interface.
 429 //
 430 // Use it when you have two methods taking wxArrayString or (int, wxString[]),
 431 // that do the same thing. This class lets you iterate over input data in the
 432 // same way whether it is a raw array of strings or wxArrayString.
 433 //
 434 // The object does not take ownership of the data -- internally it keeps
 435 // pointers to the data, therefore the data must be disposed of by user
 436 // and only after this object is destroyed. Usually it is not a problem as
 437 // only temporary objects of this class are used.
 438 // ----------------------------------------------------------------------------
 439
 440 class wxArrayStringsAdapter
 441 {
 442 public:
 443     // construct an adapter from a wxArrayString
 444     wxArrayStringsAdapter(const wxArrayString& strings)
 445         : m_type(wxSTRING_ARRAY), m_size(strings.size())
 446     {
 447         m_data.array = &strings;
 448     }
 449
 450     // construct an adapter from a wxString[]
 451     wxArrayStringsAdapter(unsigned int n, const wxString *strings)
 452         : m_type(wxSTRING_POINTER), m_size(n)
 453     {
 454         m_data.ptr = strings;
 455     }
 456
 457     // construct an adapter from a single wxString
 458     wxArrayStringsAdapter(const wxString& s)
 459         : m_type(wxSTRING_POINTER), m_size(1)
 460     {
 461         m_data.ptr = &s;
 462     }
 463
 464     // default copy constructor is ok
 465
 466     // iteration interface
 467     size_t GetCount() const { return m_size; }
 468     bool IsEmpty() const { return GetCount() == 0; }
 469     const wxString& operator[] (unsigned int i) const
 470     {
 471         wxASSERT_MSG( i < GetCount(), wxT("index out of bounds") );
 472         if(m_type == wxSTRING_POINTER)
 473             return m_data.ptr[i];
 474         return m_data.array->Item(i);
 475     }
 476     wxArrayString AsArrayString() const
 477     {
 478         if(m_type == wxSTRING_ARRAY)
 479             return *m_data.array;
 480         return wxArrayString(GetCount(), m_data.ptr);
 481     }
 482
 483 private:
 484     // type of the data being held
 485     enum wxStringContainerType
 486     {
 487         wxSTRING_ARRAY,  // wxArrayString
 488         wxSTRING_POINTER // wxString[]
 489     };
 490
 491     wxStringContainerType m_type;
 492     size_t m_size;
 493     union
 494     {
 495         const wxString *      ptr;
 496         const wxArrayString * array;
 497     } m_data;
 498
 499     wxDECLARE_NO_ASSIGN_CLASS(wxArrayStringsAdapter);
 500 };
 501
 502 #endif // _WX_ARRSTR_H