interface/list.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        list.h
   3 // Purpose:     interface of wxList<T>
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @wxheader{list.h}
  11
  12     The wxList<T> class provides linked list functionality. It has been rewritten
  13     to be type safe and to provide the full API of the STL std::list container and
  14     should be used like it. The exception is that wxList<T> actually stores
  15     pointers and therefore its iterators return pointers and not references
  16     to the actual objets in the list (see example below) and @e value_type
  17     is defined as @e T*. wxList<T> destroys an object after removing it only
  18     if wxList::DeleteContents has been called.
  19
  20     wxList<T> is not a real template and it requires that you declare and define
  21     each wxListT class in your program. This is done with @e WX_DECLARE_LIST
  22     and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able
  23     to provide a proper template class providing both the STL std::list
  24     and the old wxList API in the future.
  25
  26     Please refer to the STL std::list documentation for further
  27     information on how to use the class. Below we documented both
  28     the supported STL and the legacy API that originated from the
  29     old wxList class and which can still be used alternatively for
  30     the the same class.
  31
  32     Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1)
  33     then wxList<T> will actually derive from std::list and just add a legacy
  34     compatibility layer for the old wxList class.
  35
  36     @code
  37     // this part might be in a header or source (.cpp) file
  38     class MyListElement
  39     {
  40         ... // whatever
  41     };
  42
  43     // this macro declares and partly implements MyList class
  44     WX_DECLARE_LIST(MyListElement, MyList);
  45
  46     ...
  47
  48     // the only requirement for the rest is to be AFTER the full declaration of
  49     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
  50     // usually it will be found in the source file and not in the header
  51
  52     #include <wx/listimpl.cpp>
  53     WX_DEFINE_LIST(MyList);
  54
  55
  56     MyList list;
  57     MyListElement element;
  58     list.Append(&element);     // ok
  59     list.Append(17);           // error: incorrect type
  60
  61     // let's iterate over the list in STL syntax
  62     MyList::iterator iter;
  63     for (iter = list.begin(); iter != list.end(); ++iter)
  64     {
  65         MyListElement *current = *iter;
  66
  67         ...process the current element...
  68     }
  69
  70     // the same with the legacy API from the old wxList class
  71     MyList::compatibility_iterator node = list.GetFirst();
  72     while (node)
  73     {
  74         MyListElement *current = node->GetData();
  75
  76         ...process the current element...
  77
  78         node = node->GetNext();
  79     }
  80     @endcode
  81
  82
  83     @library{wxbase}
  84     @category{FIXME}
  85
  86     @see wxArray<T>, wxVector<T>
  87 */
  88 class wxList<T>
  89 {
  90 public:
  91     //@{
  92     /**
  93         Constructors.
  94     */
  95     wxList<T>();
  96     wxList<T>(size_t count, T* elements[]);
  97     //@}
  98
  99     /**
 100         Destroys the list, but does not delete the objects stored in the list
 101         unless you called DeleteContents(@true ).
 102     */
 103     ~wxList<T>();
 104
 105     /**
 106         Appends the pointer to @a object to the list.
 107     */
 108     wxList<T>::compatibility_iterator Append(T* object);
 109
 110     /**
 111         Clears the list, but does not delete the objects stored in the list
 112         unless you called DeleteContents(@true ).
 113     */
 114     void Clear();
 115
 116     /**
 117         If @a destroy is @true, instructs the list to call @e delete
 118         on objects stored in the list whenever they are removed.
 119         The default is @false.
 120     */
 121     void DeleteContents(bool destroy);
 122
 123     /**
 124         Deletes the given element refered to by @c iter from the list,
 125         returning @true if successful.
 126     */
 127     bool DeleteNode(const compatibility_iterator& iter);
 128
 129     /**
 130         Finds the given @a object and removes it from the list, returning
 131         @true if successful. The application must delete the actual object
 132         separately.
 133     */
 134     bool DeleteObject(T* object);
 135
 136     /**
 137         Removes element refered to be @c iter.
 138     */
 139     void Erase(const compatibility_iterator& iter);
 140
 141     /**
 142         Returns the iterator refering to @a object or @NULL if none found.
 143     */
 144     wxList<T>::compatibility_iterator Find(T* object) const;
 145
 146     /**
 147         Returns the number of elements in the list.
 148     */
 149     size_t GetCount() const;
 150
 151     /**
 152         Returns the first iterator in the list (@NULL if the list is empty).
 153     */
 154     wxList<T>::compatibility_iterator GetFirst() const;
 155
 156     /**
 157         Returns the last iterator in the list (@NULL if the list is empty).
 158     */
 159     wxList<T>::compatibility_iterator GetLast() const;
 160
 161     /**
 162         Returns the index of @a obj within the list or @c wxNOT_FOUND if
 163         @a obj is not found in the list.
 164     */
 165     int IndexOf(T* obj) const;
 166
 167     //@{
 168     /**
 169         Inserts the object before the object refered to be @e iter.
 170     */
 171     wxList<T>::compatibility_iterator Insert(T* object);
 172     wxList<T>::compatibility_iterator Insert(size_t position,
 173                                            T* object);
 174     wxList<T>::compatibility_iterator Insert(compatibility_iterator iter,
 175                                            T* object);
 176     //@}
 177
 178     /**
 179         Returns @true if the list is empty, @false otherwise.
 180     */
 181     bool IsEmpty() const;
 182
 183     /**
 184         Returns the iterator refering to the object at the given
 185         @c index in the list.
 186     */
 187     wxList<T>::compatibility_iterator Item(size_t index) const;
 188
 189     /**
 190         @note This function is deprecated, use wxList::Find instead.
 191     */
 192     wxList<T>::compatibility_iterator Member(T* object) const;
 193
 194     /**
 195         @note This function is deprecated, use @ref wxList::itemfunc Item instead.
 196         Returns the @e nth node in the list, indexing from zero (@NULL if the list is
 197         empty
 198         or the nth node could not be found).
 199     */
 200     wxList<T>::compatibility_iterator Nth(int n) const;
 201
 202     /**
 203         @note This function is deprecated, use wxList::GetCount instead.
 204         Returns the number of elements in the list.
 205     */
 206     int Number() const;
 207
 208     /**
 209         Allows the sorting of arbitrary lists by giving a function to compare
 210         two list elements. We use the system @b qsort function for the actual
 211         sorting process.
 212     */
 213     void Sort(wxSortCompareFunction compfunc);
 214
 215     //@{
 216     /**
 217         )
 218     */
 219     void assign(const_iterator first, const const_iterator& last);
 220     void assign(size_type n);
 221     //@}
 222
 223     /**
 224         Returns the last item of the list.
 225     */
 226     reference back() const;
 227
 228     /**
 229         Returns the last item of the list as a const reference.
 230     */
 231     const_reference back() const;
 232
 233     /**
 234         Returns an iterator pointing to the beginning of the list.
 235     */
 236     iterator begin() const;
 237
 238     /**
 239         Returns a const iterator pointing to the beginning of the list.
 240     */
 241     const_iterator begin() const;
 242
 243     /**
 244         Removes all items from the list.
 245     */
 246     void clear();
 247
 248     /**
 249         Returns @e @true if the list is empty.
 250     */
 251     bool empty() const;
 252
 253     /**
 254         Returns a const iterator pointing at the end of the list.
 255     */
 256     const_iterator end() const;
 257
 258     /**
 259         Returns a iterator pointing at the end of the list.
 260     */
 261     iterator end() const;
 262
 263     /**
 264         Erases the given item
 265     */
 266     iterator erase(const iterator& it);
 267
 268     /**
 269         Erases the items from @e first to @e last.
 270     */
 271     iterator erase(const iterator& first,
 272                    const iterator& last);
 273
 274     /**
 275         Returns the first item in the list.
 276     */
 277     reference front() const;
 278
 279     /**
 280         Returns the first item in the list as a const reference.
 281     */
 282     const_reference front() const;
 283
 284     /**
 285         Inserts an item at the head of the list
 286     */
 287     iterator insert(const iterator& it);
 288
 289     /**
 290         Inserts an item at the given position
 291     */
 292     void insert(const iterator& it, size_type n);
 293
 294     /**
 295         Inserts several items at the given position.
 296     */
 297     void insert(const iterator& it, const_iterator first,
 298                 const const_iterator& last);
 299
 300     /**
 301         Returns the largest possible size of the list.
 302     */
 303     size_type max_size() const;
 304
 305     /**
 306         Removes the last item from the list.
 307     */
 308     void pop_back();
 309
 310     /**
 311         Removes the first item from the list.
 312     */
 313     void pop_front();
 314
 315     /**
 316         Adds an item to end of the list.
 317     */
 318     void push_back();
 319
 320     /**
 321         Adds an item to the front of the list.
 322     */
 323     void push_front();
 324
 325     /**
 326         Returns a reverse iterator pointing to the beginning of the
 327         reversed list.
 328     */
 329     reverse_iterator rbegin() const;
 330
 331     /**
 332         Returns a const reverse iterator pointing to the beginning of the
 333         reversed list.
 334     */
 335     const_reverse_iterator rbegin() const;
 336
 337     /**
 338         Removes an item from the list.
 339     */
 340     void remove(const_reference v);
 341
 342     /**
 343         Returns a reverse iterator pointing to the end of the
 344         reversed list.
 345     */
 346     reverse_iterator rend() const;
 347
 348     /**
 349         Returns a const reverse iterator pointing to the end of the
 350         reversed list.
 351     */
 352     const_reverse_iterator rend() const;
 353
 354     /**
 355         Resizes the list. If the the list is enlarges items with
 356         the value @e v are appended to the list.
 357     */
 358     void resize(size_type n);
 359
 360     /**
 361         Reverses the list.
 362     */
 363     void reverse();
 364
 365     /**
 366         Returns the size of the list.
 367     */
 368     size_type size() const;
 369 };
 370
 371
 372
 373 /**
 374     @class wxNode
 375     @wxheader{list.h}
 376
 377     wxNodeBase is the node structure used in linked lists (see
 378     wxList) and derived classes. You should never use wxNodeBase
 379     class directly, however, because it works with untyped (@c void *) data and
 380     this is unsafe. Use wxNodeBase-derived classes which are automatically defined
 381     by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in
 382     wxList documentation (see example there). Also note that
 383     although there is a class called wxNode, it is defined for backwards
 384     compatibility only and usage of this class is strongly deprecated.
 385
 386     In the documentation below, the type @c T should be thought of as a
 387     "template" parameter: this is the type of data stored in the linked list or,
 388     in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is
 389     written as wxNodeT even though it isn't really a template class -- but it
 390     helps to think of it as if it were.
 391
 392     @library{wxbase}
 393     @category{FIXME}
 394
 395     @see wxList<T>, wxHashTable
 396 */
 397 class wxNode<T>
 398 {
 399 public:
 400     /**
 401         Retrieves the client data pointer associated with the node.
 402     */
 403     T* GetData() const;
 404
 405     /**
 406         Retrieves the next node or @NULL if this node is the last one.
 407     */
 408     wxNode<T>* GetNext() const;
 409
 410     /**
 411         Retrieves the previous node or @NULL if this node is the first one in the list.
 412     */
 413     wxNode<T>* GetPrevious();
 414
 415     /**
 416         Returns the zero-based index of this node within the list. The return value
 417         will be @c wxNOT_FOUND if the node has not been added to a list yet.
 418     */
 419     int IndexOf();
 420
 421     /**
 422         Sets the data associated with the node (usually the pointer will have been
 423         set when the node was created).
 424     */
 425     void SetData(T* data);
 426 };
 427