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     /**
 225         Returns the last item of the list.
 226     */
 227     reference back() const;
 228     const_reference back() const;
 229     //@}
 230
 231     //@{
 232     /**
 233         Returns a (const) iterator pointing to the beginning of the list.
 234     */
 235     iterator begin() const;
 236     const_iterator begin() const;
 237     //@}
 238
 239     /**
 240         Removes all items from the list.
 241     */
 242     void clear();
 243
 244     /**
 245         Returns @e @true if the list is empty.
 246     */
 247     bool empty() const;
 248
 249     //@{
 250     /**
 251         Returns a (const) iterator pointing at the end of the list.
 252     */
 253     iterator end() const;
 254     const_iterator end() const;
 255     //@}
 256
 257     //@{
 258     /**
 259         Erases the items from @a first to @e last.
 260     */
 261     iterator erase(const iterator& it);
 262     iterator erase(const iterator& first,
 263                    const iterator& last);
 264     //@}
 265
 266     //@{
 267     /**
 268         Returns the first item in the list.
 269     */
 270     reference front() const;
 271     const_reference front() const;
 272     //@}
 273
 274     //@{
 275     /**
 276         Inserts an item (or several) at the given position.
 277     */
 278     iterator insert(const iterator& it);
 279     void insert(const iterator& it, size_type n);
 280     void insert(const iterator& it, const_iterator first,
 281                 const const_iterator& last);
 282     //@}
 283
 284     /**
 285         Returns the largest possible size of the list.
 286     */
 287     size_type max_size() const;
 288
 289     /**
 290         Removes the last item from the list.
 291     */
 292     void pop_back();
 293
 294     /**
 295         Removes the first item from the list.
 296     */
 297     void pop_front();
 298
 299     /**
 300         )
 301         Adds an item to end of the list.
 302     */
 303     void push_back();
 304
 305     /**
 306         )
 307         Adds an item to the front of the list.
 308     */
 309     void push_front();
 310
 311     //@{
 312     /**
 313         Returns a (const) reverse iterator pointing to the beginning of the
 314         reversed list.
 315     */
 316     reverse_iterator rbegin() const;
 317     const_reverse_iterator rbegin() const;
 318     //@}
 319
 320     /**
 321         Removes an item from the list.
 322     */
 323     void remove(const_reference v);
 324
 325     //@{
 326     /**
 327         Returns a (const) reverse iterator pointing to the end of the
 328         reversed list.
 329     */
 330     reverse_iterator rend() const;
 331     const_reverse_iterator rend() const;
 332     //@}
 333
 334     /**
 335         )
 336         Resizes the list. If the the list is enlarges items with
 337         the value @e v are appended to the list.
 338     */
 339     void resize(size_type n);
 340
 341     /**
 342         Reverses the list.
 343     */
 344     void reverse();
 345
 346     /**
 347         Returns the size of the list.
 348     */
 349     size_type size() const;
 350 };
 351
 352
 353
 354 /**
 355     @class wxNode
 356     @wxheader{list.h}
 357
 358     wxNodeBase is the node structure used in linked lists (see
 359     wxList) and derived classes. You should never use wxNodeBase
 360     class directly, however, because it works with untyped (@c void *) data and
 361     this is unsafe. Use wxNodeBase-derived classes which are automatically defined
 362     by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in
 363     wxList documentation (see example there). Also note that
 364     although there is a class called wxNode, it is defined for backwards
 365     compatibility only and usage of this class is strongly deprecated.
 366
 367     In the documentation below, the type @c T should be thought of as a
 368     "template" parameter: this is the type of data stored in the linked list or,
 369     in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is
 370     written as wxNodeT even though it isn't really a template class -- but it
 371     helps to think of it as if it were.
 372
 373     @library{wxbase}
 374     @category{FIXME}
 375
 376     @see wxList<T>, wxHashTable
 377 */
 378 class wxNode<T>
 379 {
 380 public:
 381     /**
 382         Retrieves the client data pointer associated with the node.
 383     */
 384     T* GetData() const;
 385
 386     /**
 387         Retrieves the next node or @NULL if this node is the last one.
 388     */
 389     wxNode<T>* GetNext() const;
 390
 391     /**
 392         Retrieves the previous node or @NULL if this node is the first one in the list.
 393     */
 394     wxNode<T>* GetPrevious();
 395
 396     /**
 397         Returns the zero-based index of this node within the list. The return value
 398         will be @c wxNOT_FOUND if the node has not been added to a list yet.
 399     */
 400     int IndexOf();
 401
 402     /**
 403         Sets the data associated with the node (usually the pointer will have been
 404         set when the node was created).
 405     */
 406     void SetData(T* data);
 407 };
 408