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