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