include/wx/dynarray.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        dynarray.h
   3 // Purpose:     auto-resizable (i.e. dynamic) array support
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     12.09.97
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows license
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef   _DYNARRAY_H
  13 #define   _DYNARRAY_H
  14
  15 #ifdef __GNUG__
  16 #pragma interface "dynarray.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20
  21 /** @name Dynamic arrays and object arrays (array which own their elements)
  22     @memo Arrays which grow on demand and do range checking (only in debug)
  23   */
  24 //@{
  25
  26 // ----------------------------------------------------------------------------
  27 // constants
  28 // ----------------------------------------------------------------------------
  29
  30 /**
  31  the initial size by which an array grows when an element is added
  32  default value avoids allocate one or two bytes when the array is created
  33  which is rather inefficient
  34 */
  35 #define   WX_ARRAY_DEFAULT_INITIAL_SIZE    (16)
  36
  37 // ----------------------------------------------------------------------------
  38 // types
  39 // ----------------------------------------------------------------------------
  40
  41 /**
  42  callback compare function for quick sort
  43  must return negative value, 0 or positive value if pItem1 <, = or > pItem2
  44  */
  45 typedef int (wxCMPFUNC_CONV *CMPFUNC)(const void* pItem1, const void* pItem2);
  46
  47 // ----------------------------------------------------------------------------
  48 /**
  49  base class managing data having size of type 'long' (not used directly)
  50
  51  NB: for efficiency this often used class has no virtual functions (hence no
  52      VTBL), even dtor is <B>not</B> virtual. If used as expected it won't
  53      create any problems because ARRAYs from DEFINE_ARRAY have no dtor at all,
  54      so it's not too important if it's not called (this happens when you cast
  55      "SomeArray *" as "BaseArray *" and then delete it)
  56
  57   @memo Base class for template array classes
  58 */
  59 // ----------------------------------------------------------------------------
  60 class WXDLLEXPORT wxBaseArray
  61 {
  62 public:
  63   /** @name ctors and dtor */
  64   //@{
  65     /// default ctor
  66   wxBaseArray();
  67     /// copy ctor
  68   wxBaseArray(const wxBaseArray& array);
  69     /// assignment operator
  70   wxBaseArray& operator=(const wxBaseArray& src);
  71     /// not virtual, see above
  72   ~wxBaseArray();
  73   //@}
  74
  75   /** @name memory management */
  76   //@{
  77     /// empties the array, but doesn't release memory
  78   void Empty() { m_nCount = 0; }
  79     /// empties the array and releases memory
  80   void Clear();
  81     /// preallocates memory for given number of items
  82   void Alloc(size_t uiSize);
  83     /// minimizes the memory used by the array (frees unused memory)
  84   void Shrink();
  85   //@}
  86
  87   /** @name simple accessors */
  88   //@{
  89     /// number of elements in the array
  90   size_t  Count() const   { return m_nCount;      }
  91   size_t  GetCount() const   { return m_nCount;      }
  92     /// is it empty?
  93   bool  IsEmpty() const { return m_nCount == 0; }
  94   //@}
  95
  96 protected:
  97   // these methods are protected because if they were public one could
  98   // mistakenly call one of them instead of DEFINE_ARRAY's or OBJARRAY's
  99   // type safe methods
 100
 101   /** @name items access */
 102   //@{
 103     /// get item at position uiIndex (range checking is done in debug version)
 104   long& Item(size_t uiIndex) const
 105     { wxASSERT( uiIndex < m_nCount ); return m_pItems[uiIndex]; }
 106     /// same as Item()
 107   long& operator[](size_t uiIndex) const { return Item(uiIndex); }
 108   //@}
 109
 110   /** @name item management */
 111   //@{
 112     /**
 113       Search the element in the array, starting from the either side
 114       @param bFromEnd if TRUE, start from the end
 115       @return index of the first item matched or wxNOT_FOUND
 116       @see wxNOT_FOUND
 117      */
 118   int Index(long lItem, bool bFromEnd = FALSE) const;
 119     /// search for an item using binary search in a sorted array
 120   int Index(long lItem, CMPFUNC fnCompare) const;
 121     /// search for a place to insert the element into a sorted array
 122   size_t IndexForInsert(long lItem, CMPFUNC fnCompare) const;
 123     /// add new element at the end
 124   void Add(long lItem);
 125     /// add item assuming the array is sorted with fnCompare function
 126   void Add(long lItem, CMPFUNC fnCompare);
 127     /// add new element at given position (it becomes Item[uiIndex])
 128   void Insert(long lItem, size_t uiIndex);
 129     /// remove first item matching this value
 130   void Remove(long lItem);
 131     /// remove item by index
 132   void RemoveAt(size_t uiIndex);
 133   //@}
 134
 135   /// sort array elements using given compare function
 136   void Sort(CMPFUNC fnCompare);
 137
 138 private:
 139   void    Grow();     // makes array bigger if needed
 140
 141   size_t  m_nSize,    // current size of the array
 142           m_nCount;   // current number of elements
 143
 144   long   *m_pItems;   // pointer to data
 145 };
 146
 147 // ============================================================================
 148 // template classes
 149 // ============================================================================
 150
 151 // resolves the name conflict between the wxT() macor and T typedef: we can't
 152 // use wxT() inside WX_DEFINE_ARRAY!
 153 #define _WX_ERROR_SIZEOF   wxT("illegal use of DEFINE_ARRAY")
 154 #define _WX_ERROR_REMOVE   wxT("removing inexisting element in wxArray::Remove")
 155
 156 // ----------------------------------------------------------------------------
 157 // This macro generates a new array class. It is intended for storage of simple
 158 // types of sizeof()<=sizeof(long) or pointers if sizeof(pointer)<=sizeof(long)
 159 //
 160 // NB: it has only inline functions => takes no space at all
 161 // Mod by JACS: Salford C++ doesn't like 'var->operator=' syntax, as in:
 162 //    { ((wxBaseArray *)this)->operator=((const wxBaseArray&)src);
 163 // so using a temporary variable instead.
 164 // ----------------------------------------------------------------------------
 165 // __MAC_X__ added min ~name() below for compiling Mac X
 166 #define  _WX_DEFINE_ARRAY(T, name, classexp)                        \
 167 typedef int (CMPFUNC_CONV *CMPFUNC##T)(T *pItem1, T *pItem2);       \
 168 classexp name : public wxBaseArray                                  \
 169 {                                                                   \
 170 public:                                                             \
 171   name()                                                            \
 172   {                                                                 \
 173     size_t type = sizeof(T);                                        \
 174     size_t sizelong = sizeof(long);                                 \
 175     if ( type > sizelong )                                          \
 176       { wxFAIL_MSG( _WX_ERROR_SIZEOF ); }                           \
 177   }                                                                 \
 178   ~name() {}                                                        \
 179                                                                     \
 180   name& operator=(const name& src)                                  \
 181     { wxBaseArray* temp = (wxBaseArray*) this;                      \
 182       (*temp) = ((const wxBaseArray&)src);                          \
 183       return *this; }                                               \
 184                                                                     \
 185   T& operator[](size_t uiIndex) const                               \
 186     { return (T&)(wxBaseArray::Item(uiIndex)); }                    \
 187   T& Item(size_t uiIndex) const                                     \
 188     { return (T&)(wxBaseArray::Item(uiIndex)); }                    \
 189   T& Last() const                                                   \
 190     { return (T&)(wxBaseArray::Item(Count() - 1)); }                \
 191                                                                     \
 192   int Index(T Item, bool bFromEnd = FALSE) const                    \
 193     { return wxBaseArray::Index((long)Item, bFromEnd); }            \
 194                                                                     \
 195   void Add(T Item)                                                  \
 196     { wxBaseArray::Add((long)Item); }                               \
 197   void Insert(T Item, size_t uiIndex)                               \
 198     { wxBaseArray::Insert((long)Item, uiIndex) ; }                  \
 199                                                                     \
 200   void RemoveAt(size_t uiIndex) { wxBaseArray::RemoveAt(uiIndex); } \
 201   void Remove(T Item)                                               \
 202     { int iIndex = Index(Item);                                     \
 203       wxCHECK2_MSG( iIndex != wxNOT_FOUND, return,                  \
 204          _WX_ERROR_REMOVE);                                         \
 205       wxBaseArray::RemoveAt((size_t)iIndex); }                      \
 206                                                                     \
 207   void Sort(CMPFUNC##T fCmp) { wxBaseArray::Sort((CMPFUNC)fCmp); }  \
 208 }
 209
 210 // ----------------------------------------------------------------------------
 211 // This is the same as the previous macro, but it defines a sorted array.
 212 // Differences:
 213 //  1) it must be given a COMPARE function in ctor which takes 2 items of type
 214 //     T* and should return -1, 0 or +1 if the first one is less/greater
 215 //     than/equal to the second one.
 216 //  2) the Add() method inserts the item in such was that the array is always
 217 //     sorted (it uses the COMPARE function)
 218 //  3) it has no Sort() method because it's always sorted
 219 //  4) Index() method is much faster (the sorted arrays use binary search
 220 //     instead of linear one), but Add() is slower.
 221 //  5) there is no Insert() method because you can't insert an item into the
 222 //     given position in a sorted array but there is IndexForInsert()/AddAt()
 223 //     pair which may be used to optimize a common operation of "insert only if
 224 //     not found"
 225 //
 226 // Summary: use this class when the speed of Index() function is important, use
 227 // the normal arrays otherwise.
 228 //
 229 // NB: it has only inline functions => takes no space at all
 230 // Mod by JACS: Salford C++ doesn't like 'var->operator=' syntax, as in:
 231 //    { ((wxBaseArray *)this)->operator=((const wxBaseArray&)src);
 232 // so using a temporary variable instead.
 233 // ----------------------------------------------------------------------------
 234 #define  _WX_DEFINE_SORTED_ARRAY(T, name, classexp)                 \
 235 typedef int (CMPFUNC_CONV *SCMPFUNC##T)(T pItem1, T pItem2);        \
 236 classexp name : public wxBaseArray                                  \
 237 {                                                                   \
 238 public:                                                             \
 239   name(SCMPFUNC##T fn)                                              \
 240   { size_t type = sizeof(T);                                        \
 241     size_t sizelong = sizeof(long);                                 \
 242     if ( type > sizelong )                                          \
 243       { wxFAIL_MSG( _WX_ERROR_SIZEOF ); }                           \
 244     m_fnCompare = fn;                                               \
 245   }                                                                 \
 246                                                                     \
 247   name& operator=(const name& src)                                  \
 248     { wxBaseArray* temp = (wxBaseArray*) this;                      \
 249       (*temp) = ((const wxBaseArray&)src);                          \
 250       m_fnCompare = src.m_fnCompare;                                \
 251       return *this; }                                               \
 252                                                                     \
 253   T& operator[](size_t uiIndex) const                               \
 254     { return (T&)(wxBaseArray::Item(uiIndex)); }                    \
 255   T& Item(size_t uiIndex) const                                     \
 256     { return (T&)(wxBaseArray::Item(uiIndex)); }                    \
 257   T& Last() const                                                   \
 258     { return (T&)(wxBaseArray::Item(Count() - 1)); }                \
 259                                                                     \
 260   int Index(T Item) const                                           \
 261     { return wxBaseArray::Index((long)Item, (CMPFUNC)m_fnCompare); }\
 262                                                                     \
 263   size_t IndexForInsert(T Item) const                               \
 264     { return wxBaseArray::IndexForInsert((long)Item,                \
 265                                          (CMPFUNC)m_fnCompare); }   \
 266                                                                     \
 267   void AddAt(T item, size_t index)                                  \
 268     { wxBaseArray::Insert((long)item, index); }                     \
 269                                                                     \
 270   void Add(T Item)                                                  \
 271     { wxBaseArray::Add((long)Item, (CMPFUNC)m_fnCompare); }         \
 272                                                                     \
 273   void RemoveAt(size_t uiIndex) { wxBaseArray::RemoveAt(uiIndex); } \
 274   void Remove(T Item)                                               \
 275     { int iIndex = Index(Item);                                     \
 276       wxCHECK2_MSG( iIndex != wxNOT_FOUND, return,                  \
 277         _WX_ERROR_REMOVE );                                         \
 278       wxBaseArray::RemoveAt((size_t)iIndex); }                      \
 279                                                                     \
 280 private:                                                            \
 281   SCMPFUNC##T m_fnCompare;                                          \
 282 }
 283
 284 // ----------------------------------------------------------------------------
 285 // see WX_DECLARE_OBJARRAY and WX_DEFINE_OBJARRAY
 286 // ----------------------------------------------------------------------------
 287 #define _WX_DECLARE_OBJARRAY(T, name, classexp)                     \
 288 typedef int (CMPFUNC_CONV *CMPFUNC##T)(T** pItem1, T** pItem2);     \
 289 classexp name : public wxBaseArray                                  \
 290 {                                                                   \
 291 public:                                                             \
 292   name() { }                                                        \
 293   name(const name& src);                                            \
 294   name& operator=(const name& src);                                 \
 295                                                                     \
 296   ~name();                                                          \
 297                                                                     \
 298   T& operator[](size_t uiIndex) const                               \
 299     { return *(T*)wxBaseArray::Item(uiIndex); }                     \
 300   T& Item(size_t uiIndex) const                                     \
 301     { return *(T*)wxBaseArray::Item(uiIndex); }                     \
 302   T& Last() const                                                   \
 303     { return *(T*)(wxBaseArray::Item(Count() - 1)); }               \
 304                                                                     \
 305   int Index(const T& Item, bool bFromEnd = FALSE) const;            \
 306                                                                     \
 307   void Add(const T& Item);                                          \
 308   void Add(const T* pItem)                                          \
 309     { wxBaseArray::Add((long)pItem); }                              \
 310                                                                     \
 311   void Insert(const T& Item,  size_t uiIndex);                      \
 312   void Insert(const T* pItem, size_t uiIndex)                       \
 313     { wxBaseArray::Insert((long)pItem, uiIndex); }                  \
 314                                                                     \
 315   void Empty() { DoEmpty(); wxBaseArray::Empty(); }                 \
 316   void Clear() { DoEmpty(); wxBaseArray::Clear(); }                 \
 317                                                                     \
 318   T*   Detach(size_t uiIndex)                                       \
 319     { T* p = (T*)wxBaseArray::Item(uiIndex);                        \
 320       wxBaseArray::RemoveAt(uiIndex); return p; }                   \
 321   void RemoveAt(size_t uiIndex);                                    \
 322                                                                     \
 323   void Sort(CMPFUNC##T fCmp) { wxBaseArray::Sort((CMPFUNC)fCmp); }  \
 324                                                                     \
 325 private:                                                            \
 326   void DoEmpty();                                                   \
 327   void DoCopy(const name& src);                                     \
 328 }
 329
 330 // ----------------------------------------------------------------------------
 331 /** @name Macros for definition of dynamic arrays and objarrays
 332
 333   These macros are ugly (especially if you look in the sources ;-), but they
 334   allow us to define 'template' classes without actually using templates.
 335   <BR>
 336   <BR>
 337   Range checking is performed in debug build for both arrays and objarrays.
 338   Type checking is done at compile-time. Warning: arrays <I>never</I> shrink,
 339   they only grow, so loading 10 millions in an array only to delete them 2
 340   lines below is <I>not</I> recommended. However, it does free memory when
 341   it's destroyed, so if you destroy array also, it's ok.
 342   */
 343 // ----------------------------------------------------------------------------
 344
 345 //@{
 346   /**
 347    This macro generates a new array class. It is intended for storage of simple
 348    types of sizeof()<=sizeof(long) or pointers if sizeof(pointer)<=sizeof(long)
 349    <BR>
 350    NB: it has only inline functions => takes no space at all
 351    <BR>
 352
 353    @memo declare and define array class 'name' containing elements of type 'T'
 354   */
 355 #define WX_DEFINE_ARRAY(T, name)                \
 356     typedef T _A##name;                         \
 357     _WX_DEFINE_ARRAY(_A##name, name, class)
 358
 359   /**
 360    This macro does the same as WX_DEFINE_ARRAY except that the array will be
 361    sorted with the specified compare function.
 362    */
 363 #define WX_DEFINE_SORTED_ARRAY(T, name)             \
 364     typedef T _A##name;                             \
 365     _WX_DEFINE_SORTED_ARRAY(_A##name, name, class)
 366
 367   /**
 368    This macro generates a new objarrays class which owns the objects it
 369    contains, i.e. it will delete them when it is destroyed. An element is of
 370    type T*, but arguments of type T& are taken (see below!) and T& is
 371    returned. <BR>
 372    Don't use this for simple types such as "int" or "long"!
 373    You _may_ use it for "double" but it's awfully inefficient.
 374    <BR>
 375    <BR>
 376    Note on Add/Insert functions:
 377    <BR>
 378     1) function(T*) gives the object to the array, i.e. it will delete the
 379        object when it's removed or in the array's dtor
 380    <BR>
 381     2) function(T&) will create a copy of the object and work with it
 382    <BR>
 383    <BR>
 384    Also:
 385    <BR>
 386     1) Remove() will delete the object after removing it from the array
 387    <BR>
 388     2) Detach() just removes the object from the array (returning pointer to it)
 389    <BR>
 390    <BR>
 391    NB1: Base type T should have an accessible copy ctor  if  Add(T&) is used,
 392    <BR>
 393    NB2: Never ever cast a array to it's base type: as dtor is <B>not</B> virtual
 394         it will provoke memory leaks
 395    <BR>
 396    <BR>
 397    some functions of this class are not inline, so it takes some space to
 398    define new class from this template.
 399
 400    @memo declare objarray class 'name' containing elements of type 'T'
 401   */
 402 #define WX_DECLARE_OBJARRAY(T, name)            \
 403     typedef T _L##name;                         \
 404     _WX_DECLARE_OBJARRAY(_L##name, name, class)
 405
 406   /**
 407     To use an objarray class you must
 408     <ll>
 409     <li>#include "dynarray.h"
 410     <li>WX_DECLARE_OBJARRAY(element_type, list_class_name)
 411     <li>#include "arrimpl.cpp"
 412     <li>WX_DEFINE_OBJARRAY(list_class_name)   // same as above!
 413     </ll>
 414     <BR><BR>
 415     This is necessary because at the moment of DEFINE_OBJARRAY class
 416     element_type must be fully defined (i.e. forward declaration is not
 417     enough), while WX_DECLARE_OBJARRAY may be done anywhere. The separation of
 418     two allows to break cicrcular dependencies with classes which have member
 419     variables of objarray type.
 420
 421     @memo define (must include arrimpl.cpp!) objarray class 'name'
 422    */
 423 #define WX_DEFINE_OBJARRAY(name)       "don't forget to include arrimpl.cpp!"
 424 //@}
 425
 426 // these macros do the same thing as the WX_XXX ones above, but should be used
 427 // inside the library for user visible classes because otherwise they wouldn't
 428 // be visible from outside (when using wxWindows as DLL under Windows)
 429 #define WX_DEFINE_EXPORTED_ARRAY(T, name)               \
 430     typedef T _A##name;                                 \
 431     _WX_DEFINE_ARRAY(_A##name, name, class WXDLLEXPORT)
 432
 433 #define WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name)        \
 434     typedef T _A##name;                                 \
 435     _WX_DEFINE_SORTED_ARRAY(_A##name, name, class WXDLLEXPORT)
 436
 437 #define WX_DEFINE_EXPORTED_OBJARRAY(name)   WX_DEFINE_OBJARRAY(name)
 438 #define WX_DECLARE_EXPORTED_OBJARRAY(T, name)           \
 439     typedef T _L##name;                                 \
 440     _WX_DECLARE_OBJARRAY(_L##name, name, class WXDLLEXPORT)
 441
 442 // ..and likewise these macros do very same thing as the ones above them too,
 443 // but allow the user to specify the export spec.  Needed if you have a dll
 444 // that wants to export a wxArray daubed with your own import/export goo.
 445 #define WX_DEFINE_USER_EXPORTED_ARRAY(T, name, usergoo)         \
 446     typedef T _A##name;                                         \
 447     _WX_DEFINE_ARRAY(_A##name, name, class usergoo)
 448
 449 #define WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name, usergoo)  \
 450     typedef T _A##name;                                         \
 451     _WX_DEFINE_SORTED_ARRAY(_A##name, name, class usergoo)
 452
 453 #define WX_DEFINE_USER_EXPORTED_OBJARRAY(name)   WX_DEFINE_OBJARRAY(name)
 454 #define WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name, usergoo)     \
 455     typedef T _L##name;                                         \
 456     _WX_DECLARE_OBJARRAY(_L##name, name, class usergoo)
 457
 458 // ----------------------------------------------------------------------------
 459 /** @name Some commonly used predefined arrays */
 460 // ----------------------------------------------------------------------------
 461
 462 //@{
 463   /** @name ArrayInt */
 464 WX_DEFINE_EXPORTED_ARRAY(int, wxArrayInt);
 465   /** @name ArrayLong */
 466 WX_DEFINE_EXPORTED_ARRAY(long, wxArrayLong);
 467   /** @name ArrayPtrVoid */
 468 WX_DEFINE_EXPORTED_ARRAY(void *, wxArrayPtrVoid);
 469 //@}
 470
 471 //@}
 472
 473 // -----------------------------------------------------------------------------
 474 // convenience macros
 475 // -----------------------------------------------------------------------------
 476
 477 // append all element of one array to another one
 478 #define WX_APPEND_ARRAY(array, other)                                         \
 479     {                                                                         \
 480         size_t count = (other).Count();                                       \
 481         for ( size_t n = 0; n < count; n++ )                                  \
 482         {                                                                     \
 483             (array).Add((other)[n]);                                          \
 484         }                                                                     \
 485     }
 486
 487 // delete all array elements
 488 //
 489 // NB: the class declaration of the array elements must be visible from the
 490 //     place where you use this macro, otherwise the proper destructor may not
 491 //     be called (a decent compiler should give a warning about it, but don't
 492 //     count on it)!
 493 #define WX_CLEAR_ARRAY(array)                                                 \
 494     {                                                                         \
 495         size_t count = (array).Count();                                       \
 496         for ( size_t n = 0; n < count; n++ )                                  \
 497         {                                                                     \
 498             delete (array)[n];                                                \
 499         }                                                                     \
 500                                                                               \
 501         (array).Empty();                                                      \
 502     }
 503
 504 #endif // _DYNARRAY_H
 505