include/wx/arrstr.h

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