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     @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     @see wxArrayT(), wxVectorT()
  41 */
  42 class wxList<T>
  43 {
  44 public:
  45     //@{
  46     /**
  47         Constructors.
  48     */
  49     wxListT();
  50     wxListT(size_t count, T* elements[]);
  51     //@}
  52
  53     /**
  54         Destroys the list, but does not delete the objects stored in the list
  55         unless you called DeleteContents(@true ).
  56     */
  57     ~wxListT();
  58
  59     /**
  60         Appends the pointer to @a object to the list.
  61     */
  62     wxListT::compatibility_iterator Append(T* object);
  63
  64     /**
  65         Clears the list, but does not delete the objects stored in the list
  66         unless you called DeleteContents(@true ).
  67     */
  68     void Clear();
  69
  70     /**
  71         If @a destroy is @true, instructs the list to call @e delete
  72         on objects stored in the list whenever they are removed.
  73         The default is @false.
  74     */
  75     void DeleteContents(bool destroy);
  76
  77     /**
  78         Deletes the given element refered to by @c iter from the list,
  79         returning @true if successful.
  80     */
  81     bool DeleteNode(const compatibility_iterator& iter);
  82
  83     /**
  84         Finds the given @a object and removes it from the list, returning
  85         @true if successful. The application must delete the actual object
  86         separately.
  87     */
  88     bool DeleteObject(T* object);
  89
  90     /**
  91         Removes element refered to be @c iter.
  92     */
  93     void Erase(const compatibility_iterator& iter);
  94
  95     /**
  96         Returns the iterator refering to @a object or @NULL if none found.
  97     */
  98     wxListT::compatibility_iterator Find(T* object) const;
  99
 100     /**
 101         Returns the number of elements in the list.
 102     */
 103     size_t GetCount() const;
 104
 105     /**
 106         Returns the first iterator in the list (@NULL if the list is empty).
 107     */
 108     wxListT::compatibility_iterator GetFirst() const;
 109
 110     /**
 111         Returns the last iterator in the list (@NULL if the list is empty).
 112     */
 113     wxListT::compatibility_iterator GetLast() const;
 114
 115     /**
 116         Returns the index of @a obj within the list or @c wxNOT_FOUND if
 117         @a obj is not found in the list.
 118     */
 119     int IndexOf(T* obj) const;
 120
 121     //@{
 122     /**
 123         Inserts the object before the object refered to be @e iter.
 124     */
 125     wxListT::compatibility_iterator Insert(T* object);
 126     wxListT::compatibility_iterator Insert(size_t position,
 127                                            T* object);
 128     wxListT::compatibility_iterator Insert(compatibility_iterator iter,
 129                                            T* object);
 130     //@}
 131
 132     /**
 133         Returns @true if the list is empty, @false otherwise.
 134     */
 135     bool IsEmpty() const;
 136
 137     /**
 138         Returns the iterator refering to the object at the given
 139         @c index in the list.
 140     */
 141     wxListT::compatibility_iterator Item(size_t index) const;
 142
 143     /**
 144         @b NB: This function is deprecated, use wxList::Find instead.
 145     */
 146     wxListT::compatibility_iterator Member(T* object) const;
 147
 148     /**
 149         @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead.
 150         Returns the @e nth node in the list, indexing from zero (@NULL if the list is
 151         empty
 152         or the nth node could not be found).
 153     */
 154     wxListT::compatibility_iterator Nth(int n) const;
 155
 156     /**
 157         @b NB: This function is deprecated, use wxList::GetCount instead.
 158         Returns the number of elements in the list.
 159     */
 160     int Number() const;
 161
 162     /**
 163         Allows the sorting of arbitrary lists by giving a function to compare
 164         two list elements. We use the system @b qsort function for the actual
 165         sorting process.
 166     */
 167     void Sort(wxSortCompareFunction compfunc);
 168
 169     //@{
 170     /**
 171         )
 172     */
 173     void assign(const_iterator first, const const_iterator& last);
 174     void assign(size_type n);
 175     //@}
 176
 177     //@{
 178     /**
 179         Returns the last item of the list.
 180     */
 181     reference back() const;
 182     const_reference back() const;
 183     //@}
 184
 185     //@{
 186     /**
 187         Returns a (const) iterator pointing to the beginning of the list.
 188     */
 189     iterator begin() const;
 190     const_iterator begin() const;
 191     //@}
 192
 193     /**
 194         Removes all items from the list.
 195     */
 196     void clear();
 197
 198     /**
 199         Returns @e @true if the list is empty.
 200     */
 201     bool empty() const;
 202
 203     //@{
 204     /**
 205         Returns a (const) iterator pointing at the end of the list.
 206     */
 207     iterator end() const;
 208     const_iterator end() const;
 209     //@}
 210
 211     //@{
 212     /**
 213         Erases the items from @a first to @e last.
 214     */
 215     iterator erase(const iterator& it);
 216     iterator erase(const iterator& first,
 217                    const iterator& last);
 218     //@}
 219
 220     //@{
 221     /**
 222         Returns the first item in the list.
 223     */
 224     reference front() const;
 225     const_reference front() const;
 226     //@}
 227
 228     //@{
 229     /**
 230         Inserts an item (or several) at the given position.
 231     */
 232     iterator insert(const iterator& it);
 233     void insert(const iterator& it, size_type n);
 234     void insert(const iterator& it, const_iterator first,
 235                 const const_iterator& last);
 236     //@}
 237
 238     /**
 239         Returns the largest possible size of the list.
 240     */
 241     size_type max_size() const;
 242
 243     /**
 244         Removes the last item from the list.
 245     */
 246     void pop_back();
 247
 248     /**
 249         Removes the first item from the list.
 250     */
 251     void pop_front();
 252
 253     /**
 254         )
 255         Adds an item to end of the list.
 256     */
 257     void push_back();
 258
 259     /**
 260         )
 261         Adds an item to the front of the list.
 262     */
 263     void push_front();
 264
 265     //@{
 266     /**
 267         Returns a (const) reverse iterator pointing to the beginning of the
 268         reversed list.
 269     */
 270     reverse_iterator rbegin() const;
 271     const_reverse_iterator rbegin() const;
 272     //@}
 273
 274     /**
 275         Removes an item from the list.
 276     */
 277     void remove(const_reference v);
 278
 279     //@{
 280     /**
 281         Returns a (const) reverse iterator pointing to the end of the
 282         reversed list.
 283     */
 284     reverse_iterator rend() const;
 285     const_reverse_iterator rend() const;
 286     //@}
 287
 288     /**
 289         )
 290         Resizes the list. If the the list is enlarges items with
 291         the value @e v are appended to the list.
 292     */
 293     void resize(size_type n);
 294
 295     /**
 296         Reverses the list.
 297     */
 298     void reverse();
 299
 300     /**
 301         Returns the size of the list.
 302     */
 303     size_type size() const;
 304 };
 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     @see wxList, wxHashTable
 331 */
 332 class wxNode
 333 {
 334 public:
 335     /**
 336         Retrieves the client data pointer associated with the node.
 337     */
 338     T* GetData() const;
 339
 340     /**
 341         Retrieves the next node or @NULL if this node is the last one.
 342     */
 343     wxNodeT* GetNext() const;
 344
 345     /**
 346         Retrieves the previous node or @NULL if this node is the first one in the list.
 347     */
 348     wxNodeT* GetPrevious();
 349
 350     /**
 351         Returns the zero-based index of this node within the list. The return value
 352         will be @c wxNOT_FOUND if the node has not been added to a list yet.
 353     */
 354     int IndexOf();
 355
 356     /**
 357         Sets the data associated with the node (usually the pointer will have been
 358         set when the node was created).
 359     */
 360     void SetData(T* data);
 361 };
 362