/////////////////////////////////////////////////////////////////////////////
// Name: list.h
-// Purpose: documentation for wxList<T> class
+// Purpose: interface of wxList<T>
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
- @class wxListT
@wxheader{list.h}
- The wxListT class provides linked list functionality. It has been rewritten
+ The wxList<T> class provides linked list functionality. It has been rewritten
to be type safe and to provide the full API of the STL std::list container and
- should be used like it. The exception is that wxListT actually stores
+ should be used like it. The exception is that wxList<T> actually stores
pointers and therefore its iterators return pointers and not references
to the actual objets in the list (see example below) and @e value_type
- is defined as @e T*. wxListT destroys an object after removing it only
+ is defined as @e T*. wxList<T> destroys an object after removing it only
if wxList::DeleteContents has been called.
- wxListT is not a real template and it requires that you declare and define
+ wxList<T> is not a real template and it requires that you declare and define
each wxListT class in your program. This is done with @e WX_DECLARE_LIST
and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able
to provide a proper template class providing both the STL std::list
the the same class.
Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1)
- then wxListT will actually derive from std::list and just add a legacy
+ then wxList<T> will actually derive from std::list and just add a legacy
compatibility layer for the old wxList class.
+ @code
+ // this part might be in a header or source (.cpp) file
+ class MyListElement
+ {
+ ... // whatever
+ };
+
+ // this macro declares and partly implements MyList class
+ WX_DECLARE_LIST(MyListElement, MyList);
+
+ ...
+
+ // the only requirement for the rest is to be AFTER the full declaration of
+ // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
+ // usually it will be found in the source file and not in the header
+
+ #include <wx/listimpl.cpp>
+ WX_DEFINE_LIST(MyList);
+
+
+ MyList list;
+ MyListElement element;
+ list.Append(&element); // ok
+ list.Append(17); // error: incorrect type
+
+ // let's iterate over the list in STL syntax
+ MyList::iterator iter;
+ for (iter = list.begin(); iter != list.end(); ++iter)
+ {
+ MyListElement *current = *iter;
+
+ ...process the current element...
+ }
+
+ // the same with the legacy API from the old wxList class
+ MyList::compatibility_iterator node = list.GetFirst();
+ while (node)
+ {
+ MyListElement *current = node->GetData();
+
+ ...process the current element...
+
+ node = node->GetNext();
+ }
+ @endcode
+
+
@library{wxbase}
@category{FIXME}
- @seealso
- wxArrayT, wxVectorT
+ @see wxArray<T>, wxVector<T>
*/
class wxList<T>
{
public:
- //@{
/**
- Constructors.
+ Default constructor.
*/
- wxListT();
- wxListT(size_t count, T * elements[]);
- //@}
+ wxList<T>();
+
+ /**
+ Constructor which initialized the list with an array of @count elements.
+ */
+ wxList<T>(size_t count, T* elements[]);
/**
Destroys the list, but does not delete the objects stored in the list
unless you called DeleteContents(@true ).
*/
- ~wxListT();
+ ~wxList<T>();
/**
- Appends the pointer to @e object to the list.
+ Appends the pointer to @a object to the list.
*/
- wxListT::compatibility_iterator Append(T * object);
+ wxList<T>::compatibility_iterator Append(T* object);
/**
- Clears the list, but does not delete the objects stored in the list
- unless you called DeleteContents(@true ).
+ Clears the list.
+ Deletes the actual objects if DeleteContents( @true ) was called previously.
*/
void Clear();
/**
- If @e destroy is @true, instructs the list to call @e delete
+ If @a destroy is @true, instructs the list to call @e delete
on objects stored in the list whenever they are removed.
The default is @false.
*/
void DeleteContents(bool destroy);
/**
- Deletes the given element refered to by @c iter from the list,
- returning @true if successful.
+ Deletes the given element refered to by @a iter from the list
+ if @a iter is a valid iterator. Returns @true if successful.
+
+ Deletes the actual object if DeleteContents( @true ) was called previously.
*/
bool DeleteNode(const compatibility_iterator& iter);
/**
- Finds the given @e object and removes it from the list, returning
- @true if successful. The application must delete the actual object
- separately.
+ Finds the given @a object and removes it from the list, returning
+ @true if successful.
+
+ Deletes @a object if DeleteContents( @true ) was called previously.
*/
- bool DeleteObject(T * object);
+ bool DeleteObject(T* object);
/**
- Removes element refered to be @c iter.
+ Removes element refered to be @a iter.
+
+ Deletes the actualy object if DeleteContents( @true ) was called previously.
*/
void Erase(const compatibility_iterator& iter);
/**
- Returns the iterator refering to @e object or @NULL if none found.
+ Returns the iterator refering to @a object or @NULL if none found.
*/
- wxListT::compatibility_iterator Find(T * object);
+ wxList<T>::compatibility_iterator Find(T* object) const;
/**
Returns the number of elements in the list.
*/
- size_t GetCount();
+ size_t GetCount() const;
/**
Returns the first iterator in the list (@NULL if the list is empty).
*/
- wxListT::compatibility_iterator GetFirst();
+ wxList<T>::compatibility_iterator GetFirst() const;
/**
Returns the last iterator in the list (@NULL if the list is empty).
*/
- wxListT::compatibility_iterator GetLast();
+ wxList<T>::compatibility_iterator GetLast() const;
+
+ /**
+ Returns the index of @a obj within the list or @c wxNOT_FOUND if
+ @a obj is not found in the list.
+ */
+ int IndexOf(T* obj) const;
+
+ /**
+ Inserts @a object at the beginning of the list.
+ */
+ wxList<T>::compatibility_iterator Insert(T* object);
/**
- Returns the index of @e obj within the list or @c wxNOT_FOUND if
- @e obj is not found in the list.
+ Inserts @a object at @a position.
*/
- int IndexOf(T* obj);
+ wxList<T>::compatibility_iterator Insert(size_t position,
+ T* object);
- //@{
/**
- Inserts the object before the object refered to be @e iter.
+ Inserts @a object before the object refered to be @a iter.
*/
- wxListT::compatibility_iterator Insert(T * object);
- wxListT::compatibility_iterator Insert(size_t position,
- T * object);
- wxListT::compatibility_iterator Insert(compatibility_iterator iter,
- T * object);
- //@}
+ wxList<T>::compatibility_iterator Insert(compatibility_iterator iter,
+ T* object);
/**
Returns @true if the list is empty, @false otherwise.
*/
- bool IsEmpty();
+ bool IsEmpty() const;
/**
Returns the iterator refering to the object at the given
- @c index in the list.
+ @a index in the list.
*/
- wxListT::compatibility_iterator Item(size_t index);
+ wxList<T>::compatibility_iterator Item(size_t index) const;
/**
- @b NB: This function is deprecated, use wxList::Find instead.
+ @note This function is deprecated, use Find() instead.
*/
- wxListT::compatibility_iterator Member(T * object);
+ wxList<T>::compatibility_iterator Member(T* object) const;
/**
- @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead.
-
- Returns the @e nth node in the list, indexing from zero (@NULL if the list is
- empty
- or the nth node could not be found).
+ @note This function is deprecated, use Item() instead.
*/
-#define wxListT::compatibility_iterator Nth(int n) /* implementation is private */
+ wxList<T>::compatibility_iterator Nth(int n) const;
/**
- @b NB: This function is deprecated, use wxList::GetCount instead.
-
+ @note This function is deprecated, use wxList::GetCount instead.
Returns the number of elements in the list.
*/
- int Number();
+ int Number() const;
/**
Allows the sorting of arbitrary lists by giving a function to compare
*/
void Sort(wxSortCompareFunction compfunc);
- //@{
/**
- )
+ Clears the list and item from @a first to @a last from another list to it.
*/
void assign(const_iterator first, const const_iterator& last);
- void assign(size_type n);
- //@}
- //@{
+ /**
+ Clears the list and adds @a n items with value @a v to it.
+ */
+ void assign(size_type n, const_reference v = value_type()) \
+
/**
Returns the last item of the list.
*/
- reference back();
- const_reference back();
- //@}
+ reference back() const;
+
+ /**
+ Returns the last item of the list as a const reference.
+ */
+ const_reference back() const;
- //@{
/**
- Returns a (const) iterator pointing to the beginning of the list.
+ Returns an iterator pointing to the beginning of the list.
*/
- iterator begin();
- const_iterator begin();
- //@}
+ iterator begin() const;
+
+ /**
+ Returns a const iterator pointing to the beginning of the list.
+ */
+ const_iterator begin() const;
/**
Removes all items from the list.
/**
Returns @e @true if the list is empty.
*/
- bool empty();
+ bool empty() const;
- //@{
/**
- Returns a (const) iterator pointing at the end of the list.
+ Returns a const iterator pointing at the end of the list.
*/
- iterator end();
- const_iterator end();
- //@}
+ const_iterator end() const;
- //@{
/**
- Erases the items from @e first to @e last.
+ Returns a iterator pointing at the end of the list.
+ */
+ iterator end() const;
+
+ /**
+ Erases the given item
*/
iterator erase(const iterator& it);
+
+ /**
+ Erases the items from @e first to @e last.
+ */
iterator erase(const iterator& first,
const iterator& last);
- //@}
- //@{
/**
Returns the first item in the list.
*/
- reference front();
- const_reference front();
- //@}
+ reference front() const;
+
+ /**
+ Returns the first item in the list as a const reference.
+ */
+ const_reference front() const;
- //@{
/**
- Inserts an item (or several) at the given position.
+ Inserts an item at the head of the list
*/
iterator insert(const iterator& it);
+
+ /**
+ Inserts an item at the given position
+ */
void insert(const iterator& it, size_type n);
+
+ /**
+ Inserts several items at the given position.
+ */
void insert(const iterator& it, const_iterator first,
const const_iterator& last);
- //@}
/**
Returns the largest possible size of the list.
*/
- size_type max_size();
+ size_type max_size() const;
/**
Removes the last item from the list.
void pop_front();
/**
- )
-
Adds an item to end of the list.
*/
void push_back();
/**
- )
-
Adds an item to the front of the list.
*/
void push_front();
- //@{
/**
- Returns a (const) reverse iterator pointing to the beginning of the
+ Returns a reverse iterator pointing to the beginning of the
+ reversed list.
+ */
+ reverse_iterator rbegin() const;
+
+ /**
+ Returns a const reverse iterator pointing to the beginning of the
reversed list.
*/
- reverse_iterator rbegin();
- const_reverse_iterator rbegin();
- //@}
+ const_reverse_iterator rbegin() const;
/**
Removes an item from the list.
*/
void remove(const_reference v);
- //@{
/**
- Returns a (const) reverse iterator pointing to the end of the
+ Returns a reverse iterator pointing to the end of the
reversed list.
*/
- reverse_iterator rend();
- const_reverse_iterator rend();
- //@}
+ reverse_iterator rend() const;
+
+ /**
+ Returns a const reverse iterator pointing to the end of the
+ reversed list.
+ */
+ const_reverse_iterator rend() const;
/**
- )
-
Resizes the list. If the the list is enlarges items with
the value @e v are appended to the list.
*/
/**
Returns the size of the list.
*/
- size_type size();
+ size_type size() const;
};
+
/**
@class wxNode
@wxheader{list.h}
compatibility only and usage of this class is strongly deprecated.
In the documentation below, the type @c T should be thought of as a
- "template'' parameter: this is the type of data stored in the linked list or,
+ "template" parameter: this is the type of data stored in the linked list or,
in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is
written as wxNodeT even though it isn't really a template class -- but it
helps to think of it as if it were.
@library{wxbase}
@category{FIXME}
- @seealso
- wxList, wxHashTable
+ @see wxList<T>, wxHashTable
*/
-class wxNode
+class wxNode<T>
{
public:
/**
Retrieves the client data pointer associated with the node.
*/
- T * GetData();
+ T* GetData() const;
/**
Retrieves the next node or @NULL if this node is the last one.
*/
- wxNodeT * GetNext();
+ wxNode<T>* GetNext() const;
/**
Retrieves the previous node or @NULL if this node is the first one in the list.
*/
- wxNodeT * GetPrevious();
+ wxNode<T>* GetPrevious();
/**
Returns the zero-based index of this node within the list. The return value
Sets the data associated with the node (usually the pointer will have been
set when the node was created).
*/
- void SetData(T * data);
+ void SetData(T* data);
};
+
projects / wxWidgets.git / blobdiff