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