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 #include "wx/debug.h"
  21
  22 /** @name Dynamic arrays and object arrays (array which own their elements)
  23     @memo Arrays which grow on demand and do range checking (only in debug)
  24   */
  25 //@{
  26
  27 // ----------------------------------------------------------------------------
  28 // constants
  29 // ----------------------------------------------------------------------------
  30
  31 /**
  32  the initial size by which an array grows when an element is added
  33  default value avoids allocate one or two bytes when the array is created
  34  which is rather inefficient
  35 */
  36 #define   WX_ARRAY_DEFAULT_INITIAL_SIZE    (16)
  37
  38 // ----------------------------------------------------------------------------
  39 // types
  40 // ----------------------------------------------------------------------------
  41
  42 /**
  43  callback compare function for quick sort
  44  must return negative value, 0 or positive value if pItem1 <, = or > pItem2
  45  */
  46
  47 #if defined(__VISUALC__)
  48   #define   CMPFUNC_CONV    _cdecl
  49 #elif defined(__VISAGECPP__)
  50   #define   CMPFUNC_CONV    _Optlink
  51 #else   // !Visual C++
  52   #define   CMPFUNC_CONV
  53 #endif  // compiler
  54 typedef int (CMPFUNC_CONV *CMPFUNC)(const void* pItem1, const void* pItem2);
  55
  56 // ----------------------------------------------------------------------------
  57 /**
  58  base class managing data having size of type 'long' (not used directly)
  59
  60  NB: for efficiency this often used class has no virtual functions (hence no
  61      VTBL), even dtor is <B>not</B> virtual. If used as expected it won't
  62      create any problems because ARRAYs from DEFINE_ARRAY have no dtor at all,
  63      so it's not too important if it's not called (this happens when you cast
  64      "SomeArray *" as "BaseArray *" and then delete it)
  65
  66   @memo Base class for template array classes
  67 */
  68 // ----------------------------------------------------------------------------
  69 class WXDLLEXPORT wxBaseArray
  70 {
  71 public:
  72   /** @name ctors and dtor */
  73   //@{
  74     /// default ctor
  75   wxBaseArray();
  76     /// copy ctor
  77   wxBaseArray(const wxBaseArray& array);
  78     /// assignment operator
  79   wxBaseArray& operator=(const wxBaseArray& src);
  80     /// not virtual, see above
  81     /// EXCEPT for Gnu compiler to reduce warnings...
  82 #ifdef __GNUG__
  83  virtual
  84 #endif
  85   ~wxBaseArray();
  86   //@}
  87
  88   /** @name memory management */
  89   //@{
  90     /// empties the array, but doesn't release memory
  91   void Empty() { m_nCount = 0; }
  92     /// empties the array and releases memory
  93   void Clear();
  94     /// preallocates memory for given number of items
  95   void Alloc(size_t uiSize);
  96     /// minimizes the memory used by the array (frees unused memory)
  97   void Shrink();
  98   //@}
  99
 100   /** @name simple accessors */
 101   //@{
 102     /// number of elements in the array
 103   size_t  Count() const   { return m_nCount;      }
 104   size_t  GetCount() const   { return m_nCount;      }
 105     /// is it empty?
 106   bool  IsEmpty() const { return m_nCount == 0; }
 107   //@}
 108
 109 protected:
 110   // these methods are protected because if they were public one could
 111   // mistakenly call one of them instead of DEFINE_ARRAY's or OBJARRAY's
 112   // type safe methods
 113
 114   /** @name items access */
 115   //@{
 116     /// get item at position uiIndex (range checking is done in debug version)
 117   long& Item(size_t uiIndex) const
 118     { wxASSERT( uiIndex < m_nCount ); return m_pItems[uiIndex]; }
 119     /// same as Item()
 120   long& operator[](size_t uiIndex) const { return Item(uiIndex); }
 121   //@}
 122
 123   /** @name item management */
 124   //@{
 125     /**
 126       Search the element in the array, starting from the either side
 127       @param bFromEnd if TRUE, start from the end
 128       @return index of the first item matched or wxNOT_FOUND
 129       @see wxNOT_FOUND
 130      */
 131   int Index(long lItem, bool bFromEnd = FALSE) const;
 132     /// search for an item using binary search in a sorted array
 133   int Index(long lItem, CMPFUNC fnCompare) const;
 134     /// add new element at the end
 135   void Add(long lItem);
 136     /// add item assuming the array is sorted with fnCompare function
 137   void Add(long lItem, CMPFUNC fnCompare);
 138     /// add new element at given position (it becomes Item[uiIndex])
 139   void Insert(long lItem, size_t uiIndex);
 140     /// remove first item matching this value
 141   void Remove(long lItem);
 142     /// remove item by index
 143   void Remove(size_t uiIndex);
 144   //@}
 145
 146   /// sort array elements using given compare function
 147   void Sort(CMPFUNC fnCompare);
 148
 149 private:
 150   void    Grow();     // makes array bigger if needed
 151
 152   size_t  m_nSize,    // current size of the array
 153           m_nCount;   // current number of elements
 154
 155   long   *m_pItems;   // pointer to data
 156 };
 157
 158 // ============================================================================
 159 // template classes
 160 // ============================================================================
 161
 162 // ----------------------------------------------------------------------------
 163 // This macro generates a new array class. It is intended for storage of simple
 164 // types of sizeof()<=sizeof(long) or pointers if sizeof(pointer)<=sizeof(long)
 165 //
 166 // NB: it has only inline functions => takes no space at all
 167 // Mod by JACS: Salford C++ doesn't like 'var->operator=' syntax, as in:
 168 //    { ((wxBaseArray *)this)->operator=((const wxBaseArray&)src);
 169 // so using a temporary variable instead.
 170 // ----------------------------------------------------------------------------
 171 #define  _WX_DEFINE_ARRAY(T, name)                                  \
 172 typedef int (CMPFUNC_CONV *CMPFUNC##T)(T *pItem1, T *pItem2);       \
 173 class WXDLLEXPORT name : public wxBaseArray                         \
 174 {                                                                   \
 175 public:                                                             \
 176   name()                                                            \
 177   {                                                                 \
 178     size_t type = sizeof(T);                                        \
 179     size_t sizelong = sizeof(long);                                 \
 180     if ( type > sizelong )                                          \
 181       { wxFAIL_MSG( _T("illegal use of DEFINE_ARRAY") ); }          \
 182   }                                                                 \
 183                                                                     \
 184   name& operator=(const name& src)                                  \
 185     { wxBaseArray* temp = (wxBaseArray*) this;                      \
 186       (*temp) = ((const wxBaseArray&)src);                          \
 187       return *this; }                                               \
 188                                                                     \
 189   T& operator[](size_t uiIndex) const                               \
 190     { return (T&)(wxBaseArray::Item(uiIndex)); }                    \
 191   T& Item(size_t uiIndex) const                                     \
 192     { return (T&)(wxBaseArray::Item(uiIndex)); }                    \
 193   T& Last() const                                                   \
 194     { return (T&)(wxBaseArray::Item(Count() - 1)); }                \
 195                                                                     \
 196   int Index(T Item, bool bFromEnd = FALSE) const                    \
 197     { return wxBaseArray::Index((long)Item, bFromEnd); }            \
 198                                                                     \
 199   void Add(T Item)                                                  \
 200     { wxBaseArray::Add((long)Item); }                               \
 201   void Insert(T Item, size_t uiIndex)                               \
 202     { wxBaseArray::Insert((long)Item, uiIndex) ; }                  \
 203                                                                     \
 204   void Remove(size_t uiIndex) { wxBaseArray::Remove(uiIndex); }     \
 205   void Remove(T Item)                                               \
 206     { int iIndex = Index(Item);                                     \
 207       wxCHECK2_MSG( iIndex != wxNOT_FOUND, return,                  \
 208         _T("removing inexisting element in wxArray::Remove") );     \
 209       wxBaseArray::Remove((size_t)iIndex); }                        \
 210                                                                     \
 211   void Sort(CMPFUNC##T fCmp) { wxBaseArray::Sort((CMPFUNC)fCmp); }  \
 212 }
 213
 214 // ----------------------------------------------------------------------------
 215 // This is the same as the previous macro, but it defines a sorted array.
 216 // Differences:
 217 //  1) it must be given a COMPARE function in ctor which takes 2 items of type
 218 //     T* and should return -1, 0 or +1 if the first one is less/greater
 219 //     than/equal to the second one.
 220 //  2) the Add() method inserts the item in such was that the array is always
 221 //     sorted (it uses the COMPARE function)
 222 //  3) it has no Sort() method because it's always sorted
 223 //  4) Index() method is much faster (the sorted arrays use binary search
 224 //     instead of linear one), but Add() is slower.
 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)                           \
 235 typedef int (CMPFUNC_CONV *SCMPFUNC##T)(T pItem1, T pItem2);        \
 236 class WXDLLEXPORT 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( _T("illegal use of DEFINE_ARRAY") ); }          \
 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   void Add(T Item)                                                  \
 264     { wxBaseArray::Add((long)Item, (CMPFUNC)m_fnCompare); }         \
 265                                                                     \
 266   void Remove(size_t uiIndex) { wxBaseArray::Remove(uiIndex); }     \
 267   void Remove(T Item)                                               \
 268     { int iIndex = Index(Item);                                     \
 269       wxCHECK2_MSG( iIndex != wxNOT_FOUND, return,                  \
 270         _T("removing inexisting element in wxArray::Remove") );     \
 271       wxBaseArray::Remove((size_t)iIndex); }                        \
 272                                                                     \
 273 private:                                                            \
 274   SCMPFUNC##T m_fnCompare;                                          \
 275 }
 276
 277 // ----------------------------------------------------------------------------
 278 // see WX_DECLARE_OBJARRAY and WX_DEFINE_OBJARRAY
 279 // ----------------------------------------------------------------------------
 280 #define _WX_DECLARE_OBJARRAY(T, name)                               \
 281 typedef int (CMPFUNC_CONV *CMPFUNC##T)(T** pItem1, T** pItem2);     \
 282 class WXDLLEXPORT name : public wxBaseArray                         \
 283 {                                                                   \
 284 public:                                                             \
 285   name() { }                                                        \
 286   name(const name& src);                                            \
 287   name& operator=(const name& src);                                 \
 288                                                                     \
 289   ~name();                                                          \
 290                                                                     \
 291   T& operator[](size_t uiIndex) const                               \
 292     { return *(T*)wxBaseArray::Item(uiIndex); }                     \
 293   T& Item(size_t uiIndex) const                                     \
 294     { return *(T*)wxBaseArray::Item(uiIndex); }                     \
 295   T& Last() const                                                   \
 296     { return *(T*)(wxBaseArray::Item(Count() - 1)); }               \
 297                                                                     \
 298   int Index(const T& Item, bool bFromEnd = FALSE) const;            \
 299                                                                     \
 300   void Add(const T& Item);                                          \
 301   void Add(const T* pItem)                                          \
 302     { wxBaseArray::Add((long)pItem); }                              \
 303                                                                     \
 304   void Insert(const T& Item,  size_t uiIndex);                      \
 305   void Insert(const T* pItem, size_t uiIndex)                       \
 306     { wxBaseArray::Insert((long)pItem, uiIndex); }                  \
 307                                                                     \
 308   void Empty();                                                     \
 309                                                                     \
 310   T*   Detach(size_t uiIndex)                                       \
 311     { T* p = (T*)wxBaseArray::Item(uiIndex);                        \
 312       wxBaseArray::Remove(uiIndex); return p; }                     \
 313   void Remove(size_t uiIndex);                                      \
 314                                                                     \
 315   void Sort(CMPFUNC##T fCmp) { wxBaseArray::Sort((CMPFUNC)fCmp); }  \
 316                                                                     \
 317 private:                                                            \
 318   void DoCopy(const name& src);                                     \
 319 }
 320
 321 // ----------------------------------------------------------------------------
 322 /** @name Macros for definition of dynamic arrays and objarrays
 323
 324   These macros are ugly (especially if you look in the sources ;-), but they
 325   allow us to define 'template' classes without actually using templates.
 326   <BR>
 327   <BR>
 328   Range checking is performed in debug build for both arrays and objarrays.
 329   Type checking is done at compile-time. Warning: arrays <I>never</I> shrink,
 330   they only grow, so loading 10 millions in an array only to delete them 2
 331   lines below is <I>not</I> recommended. However, it does free memory when
 332   it's destroyed, so if you destroy array also, it's ok.
 333   */
 334 // ----------------------------------------------------------------------------
 335
 336 //@{
 337   /**
 338    This macro generates a new array class. It is intended for storage of simple
 339    types of sizeof()<=sizeof(long) or pointers if sizeof(pointer)<=sizeof(long)
 340    <BR>
 341    NB: it has only inline functions => takes no space at all
 342    <BR>
 343
 344    @memo declare and define array class 'name' containing elements of type 'T'
 345   */
 346 #define WX_DEFINE_ARRAY(T, name)  typedef T _A##name;                        \
 347                                   _WX_DEFINE_ARRAY(_A##name, name)
 348
 349   /**
 350    This macro does the same as WX_DEFINE_ARRAY except that the array will be
 351    sorted with the specified compare function.
 352    */
 353 #define WX_DEFINE_SORTED_ARRAY(T, name)  typedef T _A##name;                 \
 354                                   _WX_DEFINE_SORTED_ARRAY(_A##name, name)
 355
 356   /**
 357    This macro generates a new objarrays class which owns the objects it
 358    contains, i.e. it will delete them when it is destroyed. An element is of
 359    type T*, but arguments of type T& are taken (see below!) and T& is
 360    returned. <BR>
 361    Don't use this for simple types such as "int" or "long"!
 362    You _may_ use it for "double" but it's awfully inefficient.
 363    <BR>
 364    <BR>
 365    Note on Add/Insert functions:
 366    <BR>
 367     1) function(T*) gives the object to the array, i.e. it will delete the
 368        object when it's removed or in the array's dtor
 369    <BR>
 370     2) function(T&) will create a copy of the object and work with it
 371    <BR>
 372    <BR>
 373    Also:
 374    <BR>
 375     1) Remove() will delete the object after removing it from the array
 376    <BR>
 377     2) Detach() just removes the object from the array (returning pointer to it)
 378    <BR>
 379    <BR>
 380    NB1: Base type T should have an accessible copy ctor  if  Add(T&) is used,
 381    <BR>
 382    NB2: Never ever cast a array to it's base type: as dtor is <B>not</B> virtual
 383         it will provoke memory leaks
 384    <BR>
 385    <BR>
 386    some functions of this class are not inline, so it takes some space to
 387    define new class from this template.
 388
 389    @memo declare objarray class 'name' containing elements of type 'T'
 390   */
 391 #define WX_DECLARE_OBJARRAY(T, name)  typedef T _L##name;                 \
 392                                       _WX_DECLARE_OBJARRAY(_L##name, name)
 393   /**
 394     To use an objarray class you must
 395     <ll>
 396     <li>#include "dynarray.h"
 397     <li>WX_DECLARE_OBJARRAY(element_type, list_class_name)
 398     <li>#include "arrimpl.cpp"
 399     <li>WX_DEFINE_OBJARRAY(list_class_name)   // same as above!
 400     </ll>
 401     <BR><BR>
 402     This is necessary because at the moment of DEFINE_OBJARRAY class
 403     element_type must be fully defined (i.e. forward declaration is not
 404     enough), while WX_DECLARE_OBJARRAY may be done anywhere. The separation of
 405     two allows to break cicrcular dependencies with classes which have member
 406     variables of objarray type.
 407
 408     @memo define (must include arrimpl.cpp!) objarray class 'name'
 409    */
 410 #define WX_DEFINE_OBJARRAY(name)       "don't forget to include arrimpl.cpp!"
 411 //@}
 412
 413 // ----------------------------------------------------------------------------
 414 /** @name Some commonly used predefined arrays */
 415 // # overhead if not used?
 416 // ----------------------------------------------------------------------------
 417
 418 //@{
 419   /** @name ArrayInt */
 420 WX_DEFINE_ARRAY(int,    wxArrayInt);
 421   /** @name ArrayLong */
 422 WX_DEFINE_ARRAY(long,   wxArrayLong);
 423   /** @name ArrayPtrVoid */
 424 WX_DEFINE_ARRAY(void *, wxArrayPtrVoid);
 425 //@}
 426
 427 //@}
 428
 429 // -----------------------------------------------------------------------------
 430 // convinience macros
 431 // -----------------------------------------------------------------------------
 432
 433 // delete all array elements
 434 //
 435 // NB: the class declaration of the array elements must be visible from the
 436 //     place where you use this macro, otherwise the proper destructor may not
 437 //     be called (a decent compiler should give a warning about it, but don't
 438 //     count on it)!
 439 #define WX_CLEAR_ARRAY(array)                                                 \
 440     {                                                                         \
 441         size_t count = array.Count();                                         \
 442         for ( size_t n = 0; n < count; n++ )                                  \
 443         {                                                                     \
 444             delete array[n];                                                  \
 445         }                                                                     \
 446                                                                               \
 447         array.Empty();                                                        \
 448     }
 449 #endif // _DYNARRAY_H
 450