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