Patch from Utensil Candel with large improvements to the samples documentation, and...

[wxWidgets.git] / interface / list.h

/////////////////////////////////////////////////////////////////////////////
// Name:        list.h
// Purpose:     interface of wxList<T>
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @wxheader{list.h}

    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.

    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
    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}

    @see wxArray<T>, wxVector<T>
*/
class wxList<T>
{
public:
    /**
        Default constructor.
    */
    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 ).
    */
    ~wxList<T>();

    /**
        Appends the pointer to @a object to the list.
    */
    wxList<T>::compatibility_iterator Append(T* object);

    /**
        Clears the list. 
        Deletes the actual objects if DeleteContents( @true ) was called previously.
    */
    void Clear();

    /**
        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 @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. 
        
        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.
    */
    void Erase(const compatibility_iterator& iter);

    /**
        Returns the iterator refering to @a object or @NULL if none found.
    */
    wxList<T>::compatibility_iterator Find(T* object) const;

    /**
        Returns the number of elements in the list.
    */
    size_t GetCount() const;

    /**
        Returns the first iterator in the list (@NULL if the list is empty).
    */
    wxList<T>::compatibility_iterator GetFirst() const;

    /**
        Returns the last iterator in the list (@NULL if the list is empty).
    */
    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);

    /**
        Inserts @a object at @a position.
    */
    wxList<T>::compatibility_iterator Insert(size_t position,
                                           T* object);

    /**
        Inserts @a object before the object refered to be @a iter.
    */
    wxList<T>::compatibility_iterator Insert(compatibility_iterator iter,
                                           T* object);

    /**
        Returns @true if the list is empty, @false otherwise.
    */
    bool IsEmpty() const;

    /**
        Returns the iterator refering 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.
    */
    wxList<T>::compatibility_iterator Member(T* object) const;

    /**
        @note This function is deprecated, use Item() instead.
    */
    wxList<T>::compatibility_iterator Nth(int n) const;

    /**
        @note This function is deprecated, use wxList::GetCount instead.
        Returns the number of elements in the list.
    */
    int Number() const;

    /**
        Allows the sorting of arbitrary lists by giving a function to compare
        two list elements. We use the system @b qsort function for the actual
        sorting process.
    */
    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);

    /**
       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;

    /**
        Returns the last item of the list as a const reference.
    */
    const_reference back() const;

    /**
        Returns an iterator pointing to the beginning of the list.
    */
    iterator begin() const;

    /**
        Returns a const iterator pointing to the beginning of the list.
    */
    const_iterator begin() const;

    /**
        Removes all items from the list.
    */
    void clear();

    /**
        Returns @e @true if the list is empty.
    */
    bool empty() const;

    /**
        Returns a const iterator pointing at the end of the list.
    */
    const_iterator end() const;

    /**
        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;

    /**
        Returns the first item in the list as a const reference.
    */
    const_reference front() const;

    /**
        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() const;

    /**
        Removes the last item from the list.
    */
    void pop_back();

    /**
        Removes the first 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 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.
    */
    const_reverse_iterator rbegin() const;

    /**
        Removes an item from the list.
    */
    void remove(const_reference v);

    /**
        Returns a reverse iterator pointing to the end of the
        reversed list.
    */
    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.
    */
    void resize(size_type n);

    /**
        Reverses the list.
    */
    void reverse();

    /**
        Returns the size of the list.
    */
    size_type size() const;
};



/**
    @class wxNode
    @wxheader{list.h}

    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
    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,
    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}

    @see wxList<T>, wxHashTable
*/
class wxNode<T>
{
public:
    /**
        Retrieves the client data pointer associated with the node.
    */
    T* GetData() const;

    /**
        Retrieves the next node or @NULL if this node is the last one.
    */
    wxNode<T>* GetNext() const;

    /**
        Retrieves the previous node or @NULL if this node is the first one in the list.
    */
    wxNode<T>* GetPrevious();

    /**
        Returns the zero-based index of this node within the list. The return value
        will be @c wxNOT_FOUND if the node has not been added to a list yet.
    */
    int IndexOf();

    /**
        Sets the data associated with the node (usually the pointer will have been
        set when the node was created).
    */
    void SetData(T* data);
};