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 licence
   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 objects 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 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{containers}
  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 referred 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 referred to be @a iter.
 152
 153         Deletes the actual 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 referred 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         Check if the object is present in the list.
 213
 214         @see Find()
 215     */
 216     bool Member(T* object) const;
 217
 218     /**
 219         @deprecated This function is deprecated, use Item() instead.
 220     */
 221     wxList<T>::compatibility_iterator Nth(int n) const;
 222
 223     /**
 224         @deprecated This function is deprecated, use wxList::GetCount instead.
 225         Returns the number of elements in the list.
 226     */
 227     int Number() const;
 228
 229     /**
 230         Allows the sorting of arbitrary lists by giving a function to compare
 231         two list elements. We use the system @b qsort function for the actual
 232         sorting process.
 233     */
 234     void Sort(wxSortCompareFunction compfunc);
 235
 236     /**
 237        Clears the list and item from @a first to @a last from another list to it.
 238     */
 239     void assign(const_iterator first, const const_iterator& last);
 240
 241     /**
 242        Clears the list and adds @a n items with value @a v to it.
 243     */
 244     void assign(size_type n, const_reference v = value_type());
 245
 246     /**
 247         Returns the last item of the list.
 248     */
 249     reference back();
 250
 251     /**
 252         Returns the last item of the list as a const reference.
 253     */
 254     const_reference back() const;
 255
 256     /**
 257         Returns an iterator pointing to the beginning of the list.
 258     */
 259     iterator begin();
 260
 261     /**
 262         Returns a const iterator pointing to the beginning of the list.
 263     */
 264     const_iterator begin() const;
 265
 266     /**
 267         Removes all items from the list.
 268     */
 269     void clear();
 270
 271     /**
 272         Returns @e @true if the list is empty.
 273     */
 274     bool empty() const;
 275
 276     /**
 277         Returns a const iterator pointing at the end of the list.
 278     */
 279     const_iterator end() const;
 280
 281     /**
 282         Returns a iterator pointing at the end of the list.
 283     */
 284     iterator end() const;
 285
 286     /**
 287         Erases the given item
 288     */
 289     iterator erase(const iterator& it);
 290
 291     /**
 292         Erases the items from @e first to @e last.
 293     */
 294     iterator erase(const iterator& first,
 295                    const iterator& last);
 296
 297     /**
 298         Returns the first item in the list.
 299     */
 300     reference front() const;
 301
 302     /**
 303         Returns the first item in the list as a const reference.
 304     */
 305     const_reference front() const;
 306
 307     /**
 308         Inserts an item at the head of the list
 309     */
 310     iterator insert(const iterator& it);
 311
 312     /**
 313         Inserts an item at the given position
 314     */
 315     void insert(const iterator& it, size_type n);
 316
 317     /**
 318         Inserts several items at the given position.
 319     */
 320     void insert(const iterator& it, const_iterator first,
 321                 const const_iterator& last);
 322
 323     /**
 324         Returns the largest possible size of the list.
 325     */
 326     size_type max_size() const;
 327
 328     /**
 329         Removes the last item from the list.
 330     */
 331     void pop_back();
 332
 333     /**
 334         Removes the first item from the list.
 335     */
 336     void pop_front();
 337
 338     /**
 339         Adds an item to end of the list.
 340     */
 341     void push_back(const_reference v = value_type());
 342
 343     /**
 344         Adds an item to the front of the list.
 345     */
 346     void push_front(const_reference v = value_type());
 347
 348     /**
 349         Returns a reverse iterator pointing to the beginning of the
 350         reversed list.
 351     */
 352     reverse_iterator rbegin();
 353
 354     /**
 355         Returns a const reverse iterator pointing to the beginning of the
 356         reversed list.
 357     */
 358     const_reverse_iterator rbegin() const;
 359
 360     /**
 361         Removes an item from the list.
 362     */
 363     void remove(const_reference v);
 364
 365     /**
 366         Returns a reverse iterator pointing to the end of the reversed list.
 367     */
 368     reverse_iterator rend();
 369
 370     /**
 371         Returns a const reverse iterator pointing to the end of the reversed list.
 372     */
 373     const_reverse_iterator rend() const;
 374
 375     /**
 376         Resizes the list.
 377
 378         If the list is longer than @a n, then items are removed until the list
 379         becomes long @a n.
 380         If the list is shorter than @a n items with the value @a v are appended
 381         to the list until the list becomes long @a n.
 382     */
 383     void resize(size_type n, value_type v = value_type());
 384
 385     /**
 386         Reverses the list.
 387     */
 388     void reverse();
 389
 390     /**
 391         Returns the size of the list.
 392     */
 393     size_type size() const;
 394 };
 395
 396
 397
 398 /**
 399     wxNode<T> is the node structure used in linked lists (see wxList) and derived
 400     classes. You should never use wxNode<T> class directly, however, because it
 401     works with untyped (@c void *) data and this is unsafe.
 402     Use wxNode<T>-derived classes which are automatically defined by WX_DECLARE_LIST
 403     and WX_DEFINE_LIST macros instead as described in wxList documentation
 404     (see example there).
 405
 406     Also note that although there is a class called wxNode, it is defined for backwards
 407     compatibility only and usage of this class is strongly deprecated.
 408
 409     In the documentation below, the type @c T should be thought of as a
 410     "template" parameter: this is the type of data stored in the linked list or,
 411     in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is
 412     written as wxNodeT even though it isn't really a template class -- but it
 413     helps to think of it as if it were.
 414
 415     @tparam T
 416         The type stored in the wxNode.
 417
 418     @library{wxbase}
 419     @category{data}
 420
 421     @see wxList<T>, wxHashTable
 422 */
 423 template<typename T>
 424 class wxNode<T>
 425 {
 426 public:
 427     /**
 428         Retrieves the client data pointer associated with the node.
 429     */
 430     T* GetData() const;
 431
 432     /**
 433         Retrieves the next node or @NULL if this node is the last one.
 434     */
 435     wxNode<T>* GetNext() const;
 436
 437     /**
 438         Retrieves the previous node or @NULL if this node is the first one in the list.
 439     */
 440     wxNode<T>* GetPrevious();
 441
 442     /**
 443         Returns the zero-based index of this node within the list. The return value
 444         will be @c wxNOT_FOUND if the node has not been added to a list yet.
 445     */
 446     int IndexOf();
 447
 448     /**
 449         Sets the data associated with the node (usually the pointer will have been
 450         set when the node was created).
 451     */
 452     void SetData(T* data);
 453 };
 454