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