// Name: list.h
// Purpose: interface of wxList<T>
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
+ The wxList<T> class provides linked list functionality.
- 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 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*. wxList<T> destroys an object after removing it only
- if wxList::DeleteContents has been called.
+ This class 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 wxList<T> actually stores pointers and therefore its
+ iterators return pointers and not references to the actual objects in the list
+ (see example below) and @e value_type is defined as @e T*.
+ wxList<T> destroys an object after removing it only if wxList<T>::DeleteContents
+ has been called.
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
- and the old wxList API in the future.
-
- Please refer to the STL std::list documentation for further
- information on how to use the class. Below we documented both
- the supported STL and the legacy API that originated from the
- old wxList class and which can still be used alternatively for
- the the same class.
-
- Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1)
- then wxList<T> will actually derive from std::list and just add a legacy
+ each wxList<T> 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 @c std::list and the old
+ wxList API in the future.
+
+ Please refer to the STL @c std::list documentation (see http://www.cppreference.com/wiki/stl/list/start)
+ for further information on how to use the class.
+ Below we documented both the supported STL and the legacy API
+ that originated from the old wxList class and which can still be used alternatively
+ for the same class.
+
+ Note that if you compile wxWidgets in STL mode (@c wxUSE_STL defined as 1)
+ then wxList<T> will actually derive from @c std::list and just add a legacy
compatibility layer for the old wxList class.
@code
MyListElement *current = node->GetData();
...process the current element...
-
+
node = node->GetNext();
}
@endcode
+ For compatibility with previous versions wxList and wxStringList classes are
+ still defined, but their usage is deprecated and they will disappear in the
+ future versions completely.
+ The use of the latter is especially discouraged as it is not only unsafe but
+ is also much less efficient than wxArrayString class.
+
+ @tparam T
+ The type stored in the wxList nodes.
@library{wxbase}
- @category{FIXME}
+ @category{containers}
- @see wxArray<T>, wxVector<T>
+ @see wxArray<T>, wxVector<T>, wxNode<T>
*/
+template<typename T>
class wxList<T>
{
public:
Default constructor.
*/
wxList<T>();
-
+
/**
- Constructor which initialized the list with an array of @count elements.
+ Constructor which initialized the list with an array of @a count elements.
*/
wxList<T>(size_t count, T* elements[]);
wxList<T>::compatibility_iterator Append(T* object);
/**
- Clears the list.
+ Clears the list.
Deletes the actual objects if DeleteContents( @true ) was called previously.
*/
void Clear();
void DeleteContents(bool destroy);
/**
- Deletes the given element refered to by @a iter from the list
+ Deletes the given element referred 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 @a object and removes it from the list, returning
- @true if successful.
-
+ @true if successful.
+
Deletes @a object if DeleteContents( @true ) was called previously.
*/
bool DeleteObject(T* object);
/**
- Removes element refered to be @a iter.
-
- Deletes the actualy object if DeleteContents( @true ) was called previously.
+ Removes element referred to be @a iter.
+
+ Deletes the actual object if DeleteContents( @true ) was called previously.
*/
void Erase(const compatibility_iterator& iter);
/**
- Returns the iterator refering to @a object or @NULL if none found.
+ Returns the iterator referring to @a object or @NULL if none found.
*/
wxList<T>::compatibility_iterator Find(T* object) const;
T* object);
/**
- Inserts @a object before the object refered to be @a iter.
+ Inserts @a object before the object referred to be @a iter.
*/
wxList<T>::compatibility_iterator Insert(compatibility_iterator iter,
T* object);
bool IsEmpty() const;
/**
- Returns the iterator refering to the object at the given
+ Returns the iterator referring to the object at the given
@a index in the list.
*/
wxList<T>::compatibility_iterator Item(size_t index) const;
/**
- @note This function is deprecated, use Find() instead.
+ Check if the object is present in the list.
+
+ @see Find()
*/
- wxList<T>::compatibility_iterator Member(T* object) const;
+ bool Member(T* object) const;
/**
- @note This function is deprecated, use Item() instead.
+ @deprecated This function is deprecated, use Item() instead.
*/
wxList<T>::compatibility_iterator Nth(int n) const;
/**
- @note This function is deprecated, use wxList::GetCount instead.
+ @deprecated This function is deprecated, use wxList::GetCount instead.
Returns the number of elements in the list.
*/
int Number() const;
/**
Clears the list and adds @a n items with value @a v to it.
*/
- void assign(size_type n, const_reference v = value_type()) \
+ void assign(size_type n, const_reference v = value_type());
/**
Returns the last item of the list.
*/
- reference back() const;
+ reference back();
/**
Returns the last item of the list as a const reference.
/**
Returns an iterator pointing to the beginning of the list.
*/
- iterator begin() const;
+ iterator begin();
/**
Returns a const iterator pointing to the beginning of the list.
/**
Adds an item to end of the list.
*/
- void push_back();
+ void push_back(const_reference v = value_type());
/**
Adds an item to the front of the list.
*/
- void push_front();
+ void push_front(const_reference v = value_type());
/**
Returns a reverse iterator pointing to the beginning of the
reversed list.
*/
- reverse_iterator rbegin() const;
+ reverse_iterator rbegin();
/**
Returns a const reverse iterator pointing to the beginning of the
void remove(const_reference v);
/**
- Returns a reverse iterator pointing to the end of the
- reversed list.
+ Returns a reverse iterator pointing to the end of the reversed list.
*/
- reverse_iterator rend() const;
+ reverse_iterator rend();
/**
- Returns a const reverse iterator pointing to the end of the
- reversed list.
+ 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.
+ Resizes the list.
+
+ If the list is longer than @a n, then items are removed until the list
+ becomes long @a n.
+ If the list is shorter than @a n items with the value @a v are appended
+ to the list until the list becomes long @a n.
*/
- void resize(size_type n);
+ void resize(size_type n, value_type v = value_type());
/**
Reverses the list.
Returns the size of the list.
*/
size_type size() const;
+
+ /**
+ Returns a wxVector holding the list elements.
+
+ @since 2.9.5
+ */
+ wxVector<T> AsVector() const;
};
/**
- @class wxNode
-
- wxNodeBase is the node structure used in linked lists (see
- wxList) and derived classes. You should never use wxNodeBase
- class directly, however, because it works with untyped (@c void *) data and
- this is unsafe. Use wxNodeBase-derived classes which are automatically defined
- by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in
- wxList documentation (see example there). Also note that
- although there is a class called wxNode, it is defined for backwards
+ wxNode<T> is the node structure used in linked lists (see wxList) and derived
+ classes. You should never use wxNode<T> class directly, however, because it
+ works with untyped (@c void *) data and this is unsafe.
+ Use wxNode<T>-derived classes which are automatically defined by WX_DECLARE_LIST
+ and WX_DEFINE_LIST macros instead as described in wxList documentation
+ (see example there).
+
+ Also note that although there is a class called wxNode, it is defined for backwards
compatibility only and usage of this class is strongly deprecated.
In the documentation below, the type @c T should be thought of as a
written as wxNodeT even though it isn't really a template class -- but it
helps to think of it as if it were.
+ @tparam T
+ The type stored in the wxNode.
+
@library{wxbase}
- @category{FIXME}
+ @category{data}
@see wxList<T>, wxHashTable
*/
+template<typename T>
class wxNode<T>
{
public:
projects / wxWidgets.git / blobdiff