interface/list.h

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