include/wx/list.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        list.h
   3 // Purpose:     wxList, wxStringList classes
   4 // Author:      Julian Smart
   5 // Modified by: VZ at 16/11/98: WX_DECLARE_LIST() and typesafe lists added
   6 // Created:     29/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Julian Smart
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 /*
  13   All this is quite ugly but serves two purposes:
  14     1. Be almost 100% compatible with old, untyped, wxList class
  15     2. Ensure compile-time type checking for the linked lists
  16
  17   The idea is to have one base class (wxListBase) working with "void *" data,
  18   but to hide these untyped functions - i.e. make them protected, so they
  19   can only be used from derived classes which have inline member functions
  20   working with right types. This achieves the 2nd goal. As for the first one,
  21   we provide a special derivation of wxListBase called wxList which looks just
  22   like the old class.
  23 */
  24
  25 #ifndef _WX_LISTH__
  26 #define _WX_LISTH__
  27
  28 #ifdef __GNUG__
  29 #pragma interface "list.h"
  30 #endif
  31
  32 // -----------------------------------------------------------------------------
  33 // headers
  34 // -----------------------------------------------------------------------------
  35
  36 #include "wx/defs.h"
  37 #include "wx/debug.h"
  38 #include "wx/object.h"
  39 #include "wx/string.h"
  40
  41 // due to circular header dependencies this function has to be declared here
  42 // (normally it's found in utils.h which includes itself list.h...)
  43 extern WXDLLEXPORT wxChar* copystring(const wxChar *s);
  44
  45 class WXDLLEXPORT wxObjectListNode;
  46 typedef wxObjectListNode wxNode;
  47
  48 // undef it to get rid of old, deprecated functions
  49 #define wxLIST_COMPATIBILITY
  50
  51 // -----------------------------------------------------------------------------
  52 // constants
  53 // -----------------------------------------------------------------------------
  54 enum wxKeyType
  55 {
  56     wxKEY_NONE,
  57     wxKEY_INTEGER,
  58     wxKEY_STRING
  59 };
  60
  61 // -----------------------------------------------------------------------------
  62 // types
  63 // -----------------------------------------------------------------------------
  64
  65 // type of compare function for list sort operation (as in 'qsort'): it should
  66 // return a negative value, 0 or positive value if the first element is less
  67 // than, equal or greater than the second
  68 typedef int (* LINKAGEMODE wxSortCompareFunction)(const void *elem1, const void *elem2);
  69
  70 //
  71 typedef int (* LINKAGEMODE wxListIterateFunction)(void *current);
  72
  73 // -----------------------------------------------------------------------------
  74 // key stuff: a list may be optionally keyed on integer or string key
  75 // -----------------------------------------------------------------------------
  76
  77 union wxListKeyValue
  78 {
  79     long integer;
  80     wxChar *string;
  81 };
  82
  83 // a struct which may contain both types of keys
  84 //
  85 // implementation note: on one hand, this class allows to have only one function
  86 // for any keyed operation instead of 2 almost equivalent. OTOH, it's needed to
  87 // resolve ambiguity which we would otherwise have with wxStringList::Find() and
  88 // wxList::Find(const char *).
  89 class WXDLLEXPORT wxListKey
  90 {
  91 public:
  92     // implicit ctors
  93     wxListKey()
  94         { m_keyType = wxKEY_NONE; }
  95     wxListKey(long i)
  96         { m_keyType = wxKEY_INTEGER; m_key.integer = i; }
  97     wxListKey(const wxChar *s)
  98         { m_keyType = wxKEY_STRING; m_key.string = wxStrdup(s); }
  99     wxListKey(const wxString& s)
 100         { m_keyType = wxKEY_STRING; m_key.string = wxStrdup(s.c_str()); }
 101
 102     // accessors
 103     wxKeyType GetKeyType() const { return m_keyType; }
 104     const wxChar *GetString() const
 105         { wxASSERT( m_keyType == wxKEY_STRING ); return m_key.string; }
 106     long GetNumber() const
 107         { wxASSERT( m_keyType == wxKEY_INTEGER ); return m_key.integer; }
 108
 109     // comparison
 110     // Note: implementation moved to list.cpp to prevent BC++ inline
 111     // expansion warning.
 112     bool operator==(wxListKeyValue value) const ;
 113
 114     // dtor
 115     ~wxListKey()
 116     {
 117         if ( m_keyType == wxKEY_STRING )
 118             free(m_key.string);
 119     }
 120
 121 private:
 122     wxKeyType m_keyType;
 123     wxListKeyValue m_key;
 124 };
 125
 126 // -----------------------------------------------------------------------------
 127 // wxNodeBase class is a (base for) node in a double linked list
 128 // -----------------------------------------------------------------------------
 129
 130 WXDLLEXPORT_DATA(extern wxListKey) wxDefaultListKey;
 131
 132 class WXDLLEXPORT wxNodeBase
 133 {
 134 friend class wxListBase;
 135 public:
 136     // ctor
 137     wxNodeBase(wxListBase *list = (wxListBase *)NULL,
 138                wxNodeBase *previous = (wxNodeBase *)NULL,
 139                wxNodeBase *next = (wxNodeBase *)NULL,
 140                void *data = NULL,
 141                const wxListKey& key = wxDefaultListKey);
 142
 143     virtual ~wxNodeBase();
 144
 145     // FIXME no check is done that the list is really keyed on strings
 146     const wxChar *GetKeyString() const { return m_key.string; }
 147     long GetKeyInteger() const { return m_key.integer; }
 148
 149     // Necessary for some existing code
 150     void SetKeyString(wxChar* s) { m_key.string = s; }
 151     void SetKeyInteger(long i) { m_key.integer = i; }
 152
 153 #ifdef wxLIST_COMPATIBILITY
 154     // compatibility methods
 155     wxNode *Next() const { return (wxNode *)GetNext(); }
 156     wxNode *Previous() const { return (wxNode *)GetPrevious(); }
 157     wxObject *Data() const { return (wxObject *)GetData(); }
 158 #endif // wxLIST_COMPATIBILITY
 159
 160 protected:
 161     // all these are going to be "overloaded" in the derived classes
 162     wxNodeBase *GetNext() const { return m_next; }
 163     wxNodeBase *GetPrevious() const { return m_previous; }
 164
 165     void *GetData() const { return m_data; }
 166     void SetData(void *data) { m_data = data; }
 167
 168     // get 0-based index of this node within the list or wxNOT_FOUND
 169     int IndexOf() const;
 170
 171     virtual void DeleteData() { }
 172
 173 private:
 174     // optional key stuff
 175     wxListKeyValue m_key;
 176
 177     void        *m_data;        // user data
 178     wxNodeBase  *m_next,        // next and previous nodes in the list
 179                 *m_previous;
 180
 181     wxListBase  *m_list;        // list we belong to
 182 };
 183
 184 // -----------------------------------------------------------------------------
 185 // a double-linked list class
 186 // -----------------------------------------------------------------------------
 187 class WXDLLEXPORT wxListBase : public wxObject
 188 {
 189 friend class wxNodeBase; // should be able to call DetachNode()
 190 public:
 191     // default ctor & dtor
 192     wxListBase(wxKeyType keyType = wxKEY_NONE) { Init(keyType); }
 193     virtual ~wxListBase();
 194
 195     // accessors
 196         // count of items in the list
 197     size_t GetCount() const { return m_count; }
 198
 199     // operations
 200
 201         // delete all nodes
 202     void Clear();
 203
 204         // instruct it to destroy user data when deleting nodes
 205     void DeleteContents(bool destroy) { m_destroy = destroy; }
 206
 207        // query if to delete
 208     bool GetDeleteContents() const
 209         { return m_destroy; }
 210
 211       // get the keytype
 212     wxKeyType GetKeyType() const
 213         { return m_keyType; }
 214
 215       // set the keytype (required by the serial code)
 216     void SetKeyType(wxKeyType keyType)
 217         { wxASSERT( m_count==0 ); m_keyType = keyType; }
 218
 219 #ifdef wxLIST_COMPATIBILITY
 220     int Number() const { return GetCount(); }
 221     wxNode *First() const { return (wxNode *)GetFirst(); }
 222     wxNode *Last() const { return (wxNode *)GetLast(); }
 223     wxNode *Nth(size_t index) const { return (wxNode *)Item(index); }
 224 #endif // wxLIST_COMPATIBILITY
 225
 226 protected:
 227
 228     // all methods here are "overloaded" in derived classes to provide compile
 229     // time type checking
 230
 231     // create a node for the list of this type
 232     virtual wxNodeBase *CreateNode(wxNodeBase *prev, wxNodeBase *next,
 233                                    void *data,
 234                                    const wxListKey& key = wxDefaultListKey) = 0;
 235
 236 // Can't access these from derived classes otherwise (bug in Salford C++?)
 237 #ifdef __SALFORDC__
 238 public:
 239 #endif
 240
 241     // ctors
 242         // from an array
 243     wxListBase(size_t count, void *elements[]);
 244         // from a sequence of objects
 245     wxListBase(void *object, ... /* terminate with NULL */);
 246
 247 protected:
 248         // copy ctor and assignment operator
 249     wxListBase(const wxListBase& list)
 250         { DoCopy(list); }
 251     wxListBase& operator=(const wxListBase& list)
 252         { Clear(); DoCopy(list); return *this; }
 253
 254         // get list head/tail
 255     wxNodeBase *GetFirst() const { return m_nodeFirst; }
 256     wxNodeBase *GetLast() const { return m_nodeLast; }
 257
 258         // by (0-based) index
 259     wxNodeBase *Item(size_t index) const;
 260
 261         // get the list item's data
 262     void *operator[](size_t index) const
 263         { wxNodeBase *node = Item(index); return node ? node->GetData() : (wxNodeBase*)NULL; }
 264
 265     // operations
 266         // append to end of list
 267     wxNodeBase *Append(void *object);
 268         // insert a new item at the beginning of the list
 269     wxNodeBase *Insert(void *object) { return Insert( (wxNodeBase*)NULL, object); }
 270         // insert a new item at the given position
 271     wxNodeBase *Insert(size_t pos, void *object)
 272         { return pos == GetCount() ? Append(object)
 273                                    : Insert(Item(pos), object); }
 274         // insert before given node or at front of list if prev == NULL
 275     wxNodeBase *Insert(wxNodeBase *prev, void *object);
 276
 277         // keyed append
 278     wxNodeBase *Append(long key, void *object);
 279     wxNodeBase *Append(const wxChar *key, void *object);
 280
 281         // removes node from the list but doesn't delete it (returns pointer
 282         // to the node or NULL if it wasn't found in the list)
 283     wxNodeBase *DetachNode(wxNodeBase *node);
 284         // delete element from list, returns FALSE if node not found
 285     bool DeleteNode(wxNodeBase *node);
 286         // finds object pointer and deletes node (and object if DeleteContents
 287         // is on), returns FALSE if object not found
 288     bool DeleteObject(void *object);
 289
 290     // search (all return NULL if item not found)
 291         // by data
 292     wxNodeBase *Find(void *object) const;
 293
 294         // by key
 295     wxNodeBase *Find(const wxListKey& key) const;
 296
 297     // get 0-based index of object or wxNOT_FOUND
 298     int IndexOf( void *object ) const;
 299
 300     // this function allows the sorting of arbitrary lists by giving
 301     // a function to compare two list elements. The list is sorted in place.
 302     void Sort(const wxSortCompareFunction compfunc);
 303
 304     // functions for iterating over the list
 305     void *FirstThat(wxListIterateFunction func);
 306     void ForEach(wxListIterateFunction func);
 307     void *LastThat(wxListIterateFunction func);
 308
 309 private:
 310     // helpers
 311         // common part of all ctors
 312     void Init(wxKeyType keyType = wxKEY_NONE);
 313         // common part of copy ctor and assignment operator
 314     void DoCopy(const wxListBase& list);
 315         // common part of all Append()s
 316     wxNodeBase *AppendCommon(wxNodeBase *node);
 317         // free node's data and node itself
 318     void DoDeleteNode(wxNodeBase *node);
 319
 320     size_t m_count;             // number of elements in the list
 321     bool m_destroy;             // destroy user data when deleting list items?
 322     wxNodeBase *m_nodeFirst,    // pointers to the head and tail of the list
 323                *m_nodeLast;
 324
 325     wxKeyType m_keyType;        // type of our keys (may be wxKEY_NONE)
 326 };
 327
 328 // -----------------------------------------------------------------------------
 329 // macros for definition of "template" list type
 330 // -----------------------------------------------------------------------------
 331
 332 // and now some heavy magic...
 333
 334 // declare a list type named 'name' and containing elements of type 'T *'
 335 // (as a by product of macro expansion you also get wx##name##Node
 336 // wxNode-derived type)
 337 //
 338 // implementation details:
 339 //  1. We define _WX_LIST_ITEM_TYPE_##name typedef to save in it the item type
 340 //     for the list of given type - this allows us to pass only the list name
 341 //     to WX_DEFINE_LIST() even if it needs both the name and the type
 342 //
 343 //  2. We redefine all non-type-safe wxList functions with type-safe versions
 344 //     which don't take any space (everything is inline), but bring compile
 345 //     time error checking.
 346 //
 347 //  3. The macro which is usually used (WX_DECLARE_LIST) is defined in terms of
 348 //     a more generic WX_DECLARE_LIST_2 macro which, in turn, uses the most
 349 //     generic WX_DECLARE_LIST_3 one. The last macro adds a sometimes
 350 //     interesting capability to store polymorphic objects in the list and is
 351 //     particularly useful with, for example, "wxWindow *" list where the
 352 //     wxWindowBase pointers are put into the list, but wxWindow pointers are
 353 //     retrieved from it.
 354
 355 #define WX_DECLARE_LIST_3(T, Tbase, name, nodetype)                         \
 356     typedef int (*wxSortFuncFor_##name)(const T **, const T **);            \
 357                                                                             \
 358     class WXDLLEXPORT nodetype : public wxNodeBase                          \
 359     {                                                                       \
 360     public:                                                                 \
 361         nodetype(wxListBase *list = (wxListBase *)NULL,                     \
 362                  nodetype *previous = (nodetype *)NULL,                     \
 363                  nodetype *next = (nodetype *)NULL,                         \
 364                  T *data = (T *)NULL,                                       \
 365                  const wxListKey& key = wxDefaultListKey)                   \
 366             : wxNodeBase(list, previous, next, data, key) { }               \
 367                                                                             \
 368         nodetype *GetNext() const                                           \
 369             { return (nodetype *)wxNodeBase::GetNext(); }                   \
 370         nodetype *GetPrevious() const                                       \
 371             { return (nodetype *)wxNodeBase::GetPrevious(); }               \
 372                                                                             \
 373         T *GetData() const                                                  \
 374             { return (T *)wxNodeBase::GetData(); }                          \
 375         void SetData(T *data)                                               \
 376             { wxNodeBase::SetData(data); }                                  \
 377                                                                             \
 378         virtual void DeleteData();                                          \
 379     };                                                                      \
 380                                                                             \
 381     class WXDLLEXPORT name : public wxListBase                              \
 382     {                                                                       \
 383     public:                                                                 \
 384         typedef nodetype Node;                                              \
 385                                                                             \
 386         name(wxKeyType keyType = wxKEY_NONE) : wxListBase(keyType)          \
 387             { }                                                             \
 388         name(size_t count, T *elements[])                                   \
 389             : wxListBase(count, (void **)elements) { }                      \
 390                                                                             \
 391         nodetype *GetFirst() const                                          \
 392             { return (nodetype *)wxListBase::GetFirst(); }                  \
 393         nodetype *GetLast() const                                           \
 394             { return (nodetype *)wxListBase::GetLast(); }                   \
 395                                                                             \
 396         nodetype *Item(size_t index) const                                  \
 397             { return (nodetype *)wxListBase::Item(index); }                 \
 398                                                                             \
 399         T *operator[](size_t index) const                                   \
 400         {                                                                   \
 401             nodetype *node = Item(index);                                   \
 402             return node ? (T*)(node->GetData()) : (T*)NULL;                 \
 403         }                                                                   \
 404                                                                             \
 405         nodetype *Append(Tbase *object)                                     \
 406             { return (nodetype *)wxListBase::Append(object); }              \
 407         nodetype *Insert(Tbase *object)                                     \
 408             { return (nodetype *)Insert((nodetype*)NULL, object); }         \
 409         nodetype *Insert(size_t pos, Tbase *object)                         \
 410             { return (nodetype *)wxListBase::Insert(pos, object); }         \
 411         nodetype *Insert(nodetype *prev, Tbase *object)                     \
 412             { return (nodetype *)wxListBase::Insert(prev, object); }        \
 413                                                                             \
 414         nodetype *Append(long key, void *object)                            \
 415             { return (nodetype *)wxListBase::Append(key, object); }         \
 416         nodetype *Append(const wxChar *key, void *object)                   \
 417             { return (nodetype *)wxListBase::Append(key, object); }         \
 418                                                                             \
 419         nodetype *DetachNode(nodetype *node)                                \
 420             { return (nodetype *)wxListBase::DetachNode(node); }            \
 421         bool DeleteNode(nodetype *node)                                     \
 422             { return wxListBase::DeleteNode(node); }                        \
 423         bool DeleteObject(Tbase *object)                                    \
 424             { return wxListBase::DeleteObject(object); }                    \
 425                                                                             \
 426         nodetype *Find(Tbase *object) const                                 \
 427             { return (nodetype *)wxListBase::Find(object); }                \
 428                                                                             \
 429         virtual nodetype *Find(const wxListKey& key) const                  \
 430             { return (nodetype *)wxListBase::Find(key); }                   \
 431                                                                             \
 432         int IndexOf(Tbase *object) const                                    \
 433             { return wxListBase::IndexOf(object); }                         \
 434                                                                             \
 435         void Sort(wxSortFuncFor_##name func)                                \
 436             { wxListBase::Sort((wxSortCompareFunction)func); }              \
 437                                                                             \
 438     protected:                                                              \
 439         wxNodeBase *CreateNode(wxNodeBase *prev, wxNodeBase *next,          \
 440                                void *data,                                  \
 441                                const wxListKey& key = wxDefaultListKey)     \
 442             {                                                               \
 443                 return new nodetype(this,                                   \
 444                                     (nodetype *)prev, (nodetype *)next,     \
 445                                     (T *)data, key);                        \
 446             }                                                               \
 447     }
 448
 449 #define WX_DECLARE_LIST_2(elementtype, listname, nodename)                  \
 450     WX_DECLARE_LIST_3(elementtype, elementtype, listname, nodename)
 451
 452 #define WX_DECLARE_LIST(elementtype, listname)                              \
 453     typedef elementtype _WX_LIST_ITEM_TYPE_##listname;                      \
 454     WX_DECLARE_LIST_2(elementtype, listname, wx##listname##Node)
 455
 456 // this macro must be inserted in your program after
 457 //      #include <wx/listimpl.cpp>
 458 #define WX_DEFINE_LIST(name)    "don't forget to include listimpl.cpp!"
 459
 460 // =============================================================================
 461 // now we can define classes 100% compatible with the old ones
 462 // =============================================================================
 463
 464 // ----------------------------------------------------------------------------
 465 // commonly used list classes
 466 // ----------------------------------------------------------------------------
 467
 468 #ifdef wxLIST_COMPATIBILITY
 469
 470 // -----------------------------------------------------------------------------
 471 // wxList compatibility class: in fact, it's a list of wxObjects
 472 // -----------------------------------------------------------------------------
 473
 474 WX_DECLARE_LIST_2(wxObject, wxObjectList, wxObjectListNode);
 475
 476 class WXDLLEXPORT wxList : public wxObjectList
 477 {
 478 public:
 479     wxList(int key_type = wxKEY_NONE) : wxObjectList((wxKeyType)key_type) { }
 480
 481     // compatibility methods
 482     void Sort(wxSortCompareFunction compfunc) { wxListBase::Sort(compfunc); }
 483
 484     wxNode *Member(wxObject *object) const { return (wxNode *)Find(object); }
 485 };
 486
 487 // -----------------------------------------------------------------------------
 488 // wxStringList class for compatibility with the old code
 489 // -----------------------------------------------------------------------------
 490
 491 WX_DECLARE_LIST_2(wxChar, wxStringListBase, wxStringListNode);
 492
 493 class WXDLLEXPORT wxStringList : public wxStringListBase
 494 {
 495 public:
 496     // ctors and such
 497         // default
 498     wxStringList() { DeleteContents(TRUE); }
 499     wxStringList(const wxChar *first ...);
 500
 501         // copying the string list: the strings are copied, too (extremely
 502         // inefficient!)
 503     wxStringList(const wxStringList& other) { DoCopy(other); }
 504     wxStringList& operator=(const wxStringList& other)
 505         { Clear(); DoCopy(other); return *this; }
 506
 507     // operations
 508         // makes a copy of the string
 509     wxNode *Add(const wxChar *s)
 510         { return (wxNode *)wxStringListBase::Append(copystring(s)); }
 511
 512     bool Delete(const wxChar *s);
 513
 514     wxChar **ListToArray(bool new_copies = FALSE) const;
 515     bool Member(const wxChar *s) const;
 516
 517     // alphabetic sort
 518     void Sort();
 519
 520 private:
 521     void DoCopy(const wxStringList&); // common part of copy ctor and operator=
 522 };
 523
 524 #endif // wxLIST_COMPATIBILITY
 525
 526 #endif
 527     // _WX_LISTH__