X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..7bf2b0881a6bf28138f258504e88b2643daa854e:/interface/list.h diff --git a/interface/list.h b/interface/list.h index 6988f7feb8..3e2f5a95b9 100644 --- a/interface/list.h +++ b/interface/list.h @@ -7,18 +7,17 @@ ///////////////////////////////////////////////////////////////////////////// /** - @class wxListT @wxheader{list.h} - The wxListT class provides linked list functionality. It has been rewritten + The wxList 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 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 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 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 @@ -31,13 +30,60 @@ 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 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_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 wxArrayT(), wxVectorT() + @see wxArray, wxVector */ class wxList { @@ -46,20 +92,20 @@ public: /** Constructors. */ - wxListT(); - wxListT(size_t count, T* elements[]); + wxList(); + wxList(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(); /** Appends the pointer to @a object to the list. */ - wxListT::compatibility_iterator Append(T* object); + wxList::compatibility_iterator Append(T* object); /** Clears the list, but does not delete the objects stored in the list @@ -95,7 +141,7 @@ public: /** Returns the iterator refering to @a object or @NULL if none found. */ - wxListT::compatibility_iterator Find(T* object) const; + wxList::compatibility_iterator Find(T* object) const; /** Returns the number of elements in the list. @@ -105,12 +151,12 @@ public: /** Returns the first iterator in the list (@NULL if the list is empty). */ - wxListT::compatibility_iterator GetFirst() const; + wxList::compatibility_iterator GetFirst() const; /** Returns the last iterator in the list (@NULL if the list is empty). */ - wxListT::compatibility_iterator GetLast() const; + wxList::compatibility_iterator GetLast() const; /** Returns the index of @a obj within the list or @c wxNOT_FOUND if @@ -122,10 +168,10 @@ public: /** Inserts the object before the object refered to be @e iter. */ - wxListT::compatibility_iterator Insert(T* object); - wxListT::compatibility_iterator Insert(size_t position, + wxList::compatibility_iterator Insert(T* object); + wxList::compatibility_iterator Insert(size_t position, T* object); - wxListT::compatibility_iterator Insert(compatibility_iterator iter, + wxList::compatibility_iterator Insert(compatibility_iterator iter, T* object); //@} @@ -138,23 +184,23 @@ public: Returns the iterator refering to the object at the given @c index in the list. */ - wxListT::compatibility_iterator Item(size_t index) const; + wxList::compatibility_iterator Item(size_t index) const; /** - @b NB: This function is deprecated, use wxList::Find instead. + @note This function is deprecated, use wxList::Find instead. */ - wxListT::compatibility_iterator Member(T* object) const; + wxList::compatibility_iterator Member(T* object) const; /** - @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead. + @note 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). */ - wxListT::compatibility_iterator Nth(int n) const; + wxList::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() const; @@ -174,21 +220,25 @@ public: void assign(size_type n); //@} - //@{ /** 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 a (const) iterator pointing to the beginning of the list. + 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. @@ -200,40 +250,52 @@ public: */ 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; const_iterator end() const; - //@} - //@{ /** - Erases the items from @a 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; + + /** + 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. @@ -251,42 +313,45 @@ public: 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. + */ 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; + + /** + 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. */ @@ -319,7 +384,7 @@ public: 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. @@ -327,9 +392,9 @@ public: @library{wxbase} @category{FIXME} - @see wxList, wxHashTable + @see wxList, wxHashTable */ -class wxNode +class wxNode { public: /** @@ -340,12 +405,12 @@ public: /** Retrieves the next node or @NULL if this node is the last one. */ - wxNodeT* GetNext() const; + wxNode* GetNext() const; /** Retrieves the previous node or @NULL if this node is the first one in the list. */ - wxNodeT* GetPrevious(); + wxNode* GetPrevious(); /** Returns the zero-based index of this node within the list. The return value