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 @e 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 @e 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 @e 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 @e object or @NULL if none found.
  98     */
  99     wxListT::compatibility_iterator Find(T * object);
 100
 101     /**
 102         Returns the number of elements in the list.
 103     */
 104     size_t GetCount();
 105
 106     /**
 107         Returns the first iterator in the list (@NULL if the list is empty).
 108     */
 109     wxListT::compatibility_iterator GetFirst();
 110
 111     /**
 112         Returns the last iterator in the list (@NULL if the list is empty).
 113     */
 114     wxListT::compatibility_iterator GetLast();
 115
 116     /**
 117         Returns the index of @e obj within the list or @c wxNOT_FOUND if
 118         @e obj is not found in the list.
 119     */
 120     int IndexOf(T* obj);
 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();
 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);
 143
 144     /**
 145         @b NB: This function is deprecated, use wxList::Find instead.
 146     */
 147     wxListT::compatibility_iterator Member(T * object);
 148
 149     /**
 150         @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead.
 151
 152         Returns the @e nth node in the list, indexing from zero (@NULL if the list is
 153         empty
 154         or the nth node could not be found).
 155     */
 156 #define wxListT::compatibility_iterator Nth(int n)     /* implementation is private */
 157
 158     /**
 159         @b NB: This function is deprecated, use wxList::GetCount instead.
 160
 161         Returns the number of elements in the list.
 162     */
 163     int Number();
 164
 165     /**
 166         Allows the sorting of arbitrary lists by giving a function to compare
 167         two list elements. We use the system @b qsort function for the actual
 168         sorting process.
 169     */
 170     void Sort(wxSortCompareFunction compfunc);
 171
 172     //@{
 173     /**
 174         )
 175     */
 176     void assign(const_iterator first, const const_iterator& last);
 177     void assign(size_type n);
 178     //@}
 179
 180     //@{
 181     /**
 182         Returns the last item of the list.
 183     */
 184     reference back();
 185     const_reference back();
 186     //@}
 187
 188     //@{
 189     /**
 190         Returns a (const) iterator pointing to the beginning of the list.
 191     */
 192     iterator begin();
 193     const_iterator begin();
 194     //@}
 195
 196     /**
 197         Removes all items from the list.
 198     */
 199     void clear();
 200
 201     /**
 202         Returns @e @true if the list is empty.
 203     */
 204     bool empty();
 205
 206     //@{
 207     /**
 208         Returns a (const) iterator pointing at the end of the list.
 209     */
 210     iterator end();
 211     const_iterator end();
 212     //@}
 213
 214     //@{
 215     /**
 216         Erases the items from @e first to @e last.
 217     */
 218     iterator erase(const iterator& it);
 219     iterator erase(const iterator& first,
 220                    const iterator& last);
 221     //@}
 222
 223     //@{
 224     /**
 225         Returns the first item in the list.
 226     */
 227     reference front();
 228     const_reference front();
 229     //@}
 230
 231     //@{
 232     /**
 233         Inserts an item (or several) at the given position.
 234     */
 235     iterator insert(const iterator& it);
 236     void insert(const iterator& it, size_type n);
 237     void insert(const iterator& it, const_iterator first,
 238                 const const_iterator& last);
 239     //@}
 240
 241     /**
 242         Returns the largest possible size of the list.
 243     */
 244     size_type max_size();
 245
 246     /**
 247         Removes the last item from the list.
 248     */
 249     void pop_back();
 250
 251     /**
 252         Removes the first item from the list.
 253     */
 254     void pop_front();
 255
 256     /**
 257         )
 258
 259         Adds an item to end of the list.
 260     */
 261     void push_back();
 262
 263     /**
 264         )
 265
 266         Adds an item to the front of the list.
 267     */
 268     void push_front();
 269
 270     //@{
 271     /**
 272         Returns a (const) reverse iterator pointing to the beginning of the
 273         reversed list.
 274     */
 275     reverse_iterator rbegin();
 276     const_reverse_iterator rbegin();
 277     //@}
 278
 279     /**
 280         Removes an item from the list.
 281     */
 282     void remove(const_reference v);
 283
 284     //@{
 285     /**
 286         Returns a (const) reverse iterator pointing to the end of the
 287         reversed list.
 288     */
 289     reverse_iterator rend();
 290     const_reverse_iterator rend();
 291     //@}
 292
 293     /**
 294         )
 295
 296         Resizes the list. If the the list is enlarges items with
 297         the value @e v are appended to the list.
 298     */
 299     void resize(size_type n);
 300
 301     /**
 302         Reverses the list.
 303     */
 304     void reverse();
 305
 306     /**
 307         Returns the size of the list.
 308     */
 309     size_type size();
 310 };
 311
 312
 313 /**
 314     @class wxNode
 315     @wxheader{list.h}
 316
 317     wxNodeBase is the node structure used in linked lists (see
 318     wxList) and derived classes. You should never use wxNodeBase
 319     class directly, however, because it works with untyped (@c void *) data and
 320     this is unsafe. Use wxNodeBase-derived classes which are automatically defined
 321     by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in
 322     wxList documentation (see example there). Also note that
 323     although there is a class called wxNode, it is defined for backwards
 324     compatibility only and usage of this class is strongly deprecated.
 325
 326     In the documentation below, the type @c T should be thought of as a
 327     "template'' parameter: this is the type of data stored in the linked list or,
 328     in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is
 329     written as wxNodeT even though it isn't really a template class -- but it
 330     helps to think of it as if it were.
 331
 332     @library{wxbase}
 333     @category{FIXME}
 334
 335     @seealso
 336     wxList, wxHashTable
 337 */
 338 class wxNode
 339 {
 340 public:
 341     /**
 342         Retrieves the client data pointer associated with the node.
 343     */
 344     T * GetData();
 345
 346     /**
 347         Retrieves the next node or @NULL if this node is the last one.
 348     */
 349     wxNodeT * GetNext();
 350
 351     /**
 352         Retrieves the previous node or @NULL if this node is the first one in the list.
 353     */
 354     wxNodeT * GetPrevious();
 355
 356     /**
 357         Returns the zero-based index of this node within the list. The return value
 358         will be @c wxNOT_FOUND if the node has not been added to a list yet.
 359     */
 360     int IndexOf();
 361
 362     /**
 363         Sets the data associated with the node (usually the pointer will have been
 364         set when the node was created).
 365     */
 366     void SetData(T * data);
 367 };