interface/wx/list.h

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