Make storing non-trivial data in wxThreadSpecificInfo possible.

[wxWidgets.git] / interface / wx / list.h

diff --git a/interface/wx/list.h b/interface/wx/list.h
index 44311a3d37a66f922e2fe1a31c10ec7d1ce5324e..ac88a671c452bae1028cdfbd12a1327b18aac6e9 100644 (file)
--- a/interface/wx/list.h
+++ b/interface/wx/list.h
@@ -2,36 +2,34 @@
 // Name:        list.h
 // Purpose:     interface of wxList<T>
 // Author:      wxWidgets team
 // Name:        list.h
 // Purpose:     interface of wxList<T>
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**

-    @class wxList
-

     The wxList<T> class provides linked list functionality.
 
     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
     The wxList<T> class provides linked list functionality.
 
     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 objets in the list
+    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*.
     (see example below) and @e value_type is defined as @e T*.

-    wxList<T> destroys an object after removing it only if wxList::DeleteContents
+    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
     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
+    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
     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
+    provide a proper template class providing both the STL @c std::list and the old

     wxList API in the future.
 
     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
+    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
     that originated from the old wxList class and which can still be used alternatively

-    for the the same class.
+    for 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
+    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
     compatibility layer for the old wxList class.
 
     @code


@@ -86,11 +84,15 @@
     The use of the latter is especially discouraged as it is not only unsafe but
     is also much less efficient than wxArrayString class.
 
     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}
     @library{wxbase}

-    @category{data}
+    @category{containers}

 
 

-    @see wxArray<T>, wxVector<T>
+    @see wxArray<T>, wxVector<T>, wxNode<T>

 */
 */

+template<typename T>

 class wxList<T>
 {
 public:
 class wxList<T>
 {
 public:


@@ -129,7 +131,7 @@ public:
     void DeleteContents(bool destroy);
 
     /**
     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.
         if @a iter is a valid iterator. Returns @true if successful.
 
         Deletes the actual object if DeleteContents( @true ) was called previously.


@@ -145,14 +147,14 @@ public:
     bool DeleteObject(T* object);
 
     /**
     bool DeleteObject(T* object);
 
     /**

-        Removes element refered to be @a iter.
+        Removes element referred to be @a iter.

 
 

-        Deletes the actualy object if DeleteContents( @true ) was called previously.
+        Deletes the actual object if DeleteContents( @true ) was called previously.

     */
     void Erase(const compatibility_iterator& iter);
 
     /**
     */
     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;
 
     */
     wxList<T>::compatibility_iterator Find(T* object) const;
 


@@ -189,7 +191,7 @@ public:
                                            T* object);
 
     /**
                                            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);
     */
     wxList<T>::compatibility_iterator Insert(compatibility_iterator iter,
                                            T* object);


@@ -200,15 +202,17 @@ public:
     bool IsEmpty() const;
 
     /**
     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;
 
     /**
         @a index in the list.
     */
     wxList<T>::compatibility_iterator Item(size_t index) const;
 
     /**

-        @deprecated 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;

 
     /**
         @deprecated This function is deprecated, use Item() instead.
 
     /**
         @deprecated This function is deprecated, use Item() instead.


@@ -369,9 +373,13 @@ public:
 
     /**
         Resizes the list.
 
     /**
         Resizes the list.

-        If the the list is enlarges items with the value @e v are appended to 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.
 
     /**
         Reverses the list.


@@ -382,17 +390,22 @@ public:
         Returns the size of the list.
     */
     size_type size() const;
         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
+    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.
     works with untyped (@c void *) data and this is unsafe.

-    Use wxNodeBase-derived classes which are automatically defined by WX_DECLARE_LIST
+    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).
 
     and WX_DEFINE_LIST macros instead as described in wxList documentation
     (see example there).
 


@@ -405,11 +418,15 @@ public:
     written as wxNodeT even though it isn't really a template class -- but it
     helps to think of it as if it were.
 
     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{data}
 
     @see wxList<T>, wxHashTable
 */
     @library{wxbase}
     @category{data}
 
     @see wxList<T>, wxHashTable
 */

+template<typename T>

 class wxNode<T>
 {
 public:
 class wxNode<T>
 {
 public: