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