Add wxFileName::SetPermissions().

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

diff --git a/interface/wx/arrstr.h b/interface/wx/arrstr.h
index 34652fe1448082316bacb58c84108dd88bf343d7..d22f7a0e2ccdc842df323f99c2fa21030c8f5f6b 100644 (file)
--- a/interface/wx/arrstr.h
+++ b/interface/wx/arrstr.h
@@ -2,20 +2,11 @@
 // Name:        arrstr.h
 // Purpose:     interface of wxArrayString
 // Author:      wxWidgets team
 // Name:        arrstr.h
 // Purpose:     interface of wxArrayString
 // Author:      wxWidgets team

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

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-/**
-    @todo
-    the following functions are not documented; do they need to be?
-    WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortAscending(wxString*, wxString*);
-    WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortDescending(wxString*, wxString*);
-*/
-

 /**
     @class wxArrayString
 /**
     @class wxArrayString

-    @wxheader{arrstr.h}

 
     wxArrayString is an efficient container for storing wxString objects.
 
 
     wxArrayString is an efficient container for storing wxString objects.
 


@@ -49,16 +40,24 @@
     a specialization of wxArray class for the wxString member data: it is not
     implemented like this, but it does have all of the wxArray functions.
 
     a specialization of wxArray class for the wxString member data: it is not
     implemented like this, but it does have all of the wxArray functions.
 

-    @todo what about stl? how does it integrate?
+    It also has the full set of <tt>std::vector<wxString></tt> compatible
+    methods, including nested @c iterator and @c const_iterator classes which
+    should be used in the new code for forward compatibility with the future
+    wxWidgets versions.

 
     @library{wxbase}
     @category{containers}
 
 
     @library{wxbase}
     @category{containers}
 

-    @see wxArray, wxString, @ref overview_string
+    @see wxArray<T>, wxString, @ref overview_string

 */
 class wxArrayString : public wxArray
 {
 public:
 */
 class wxArrayString : public wxArray
 {
 public:

+    /**
+        The function type used with wxArrayString::Sort function.
+    */
+    typedef int (*CompareFunction)(const wxString& first, const wxString& second);
+

     /**
         Default constructor.
     */
     /**
         Default constructor.
     */


@@ -97,13 +96,10 @@ public:
     size_t Add(const wxString& str, size_t copies = 1);
 
     /**
     size_t Add(const wxString& str, size_t copies = 1);
 
     /**

-        Preallocates enough memory to store @a nCount items. This function may be
-        used to improve array class performance before adding a known number of items
-        consecutively.
-
-        @todo FIX THIS LINK
+        Preallocates enough memory to store @a nCount items.

 
 

-        @see @ref wxArray::memorymanagement "Dynamic array memory management"
+        This function may be used to improve array class performance before
+        adding a known number of items consecutively.

     */
     void Alloc(size_t nCount);
 
     */
     void Alloc(size_t nCount);
 


@@ -148,8 +144,7 @@ public:
 
         If @a nIndex is equal to GetCount() this function behaves as Add().
     */
 
         If @a nIndex is equal to GetCount() this function behaves as Add().
     */

-    void Insert(const wxString& str, size_t nIndex,
-                size_t copies = 1);
+    void Insert(wxString lItem, size_t nIndex, size_t copies = 1);

 
     /**
         Returns @true if the array is empty, @false otherwise. This function returns the
 
     /**
         Returns @true if the array is empty, @false otherwise. This function returns the


@@ -164,14 +159,20 @@ public:
 
         @see operator[] for the operator version.
     */
 
         @see operator[] for the operator version.
     */

-    wxString& Item(size_t nIndex) const;
+    //@{
+    wxString& Item(size_t nIndex);
+    const wxString& Item(size_t nIndex) const;
+    //@}

 
     /**
         Returns the last element of the array. Attempt to access the last element of
         an empty array will result in assert failure in debug build, however no checks
         are done in release mode.
     */
 
     /**
         Returns the last element of the array. Attempt to access the last element of
         an empty array will result in assert failure in debug build, however no checks
         are done in release mode.
     */

-    wxString& Last() const;
+    //@{
+    wxString& Last();
+    const wxString& Last() const;
+    //@}

 
     /**
         Removes the first item matching this value. An assert failure is provoked by
 
     /**
         Removes the first item matching this value. An assert failure is provoked by


@@ -187,13 +188,10 @@ public:
     void RemoveAt(size_t nIndex, size_t count = 1);
 
     /**
     void RemoveAt(size_t nIndex, size_t count = 1);
 
     /**

-        Releases the extra memory allocated by the array. This function is useful to
-        minimize the array memory consumption.
+        Releases the extra memory allocated by the array.
+        This function is useful to minimize the array memory consumption.

 
 

-        @todo FIX THIS LINK
-
-        @see Alloc(), @ref wxArray::memorymanagement "Dynamic array memory
-        management"
+        @see Alloc()

     */
     void Shrink();
 
     */
     void Shrink();
 


@@ -205,7 +203,7 @@ public:
 
     /**
         Sorts the array using the specified @a compareFunction for item comparison.
 
     /**
         Sorts the array using the specified @a compareFunction for item comparison.

-        @a CompareFunction is defined as a function taking two @e const wxString
+        @a CompareFunction is defined as a function taking two <em>const wxString&</em>

         parameters and returning an @e int value less than, equal to or greater
         than 0 if the first string is less than, equal to or greater than the
         second one.
         parameters and returning an @e int value less than, equal to or greater
         than 0 if the first string is less than, equal to or greater than the
         second one.


@@ -263,34 +261,32 @@ public:
 
 /**
     @class wxSortedArrayString
 
 /**
     @class wxSortedArrayString

-    @wxheader{arrstr.h}

 
     wxSortedArrayString is an efficient container for storing wxString objects
     which always keeps the string in alphabetical order.
 
 
     wxSortedArrayString is an efficient container for storing wxString objects
     which always keeps the string in alphabetical order.
 

-    wxSortedArrayString uses binary search in its wxArrayString::Index() function
+    wxSortedArrayString uses binary search in its wxSortedArrayString::Index() method

     (instead of linear search for wxArrayString::Index()) which makes it much more
     efficient if you add strings to the array rarely (because, of course, you have
     to pay for Index() efficiency by having Add() be slower) but search for them
     often. Several methods should not be used with sorted array (basically, all
     those which break the order of items) which is mentioned in their description.
 
     (instead of linear search for wxArrayString::Index()) which makes it much more
     efficient if you add strings to the array rarely (because, of course, you have
     to pay for Index() efficiency by having Add() be slower) but search for them
     often. Several methods should not be used with sorted array (basically, all
     those which break the order of items) which is mentioned in their description.
 

-    @todo what about STL? who does it integrates?
-

     @library{wxbase}
     @category{containers}
 
     @see wxArray, wxString, @ref overview_string
 */
     @library{wxbase}
     @category{containers}
 
     @see wxArray, wxString, @ref overview_string
 */

-class wxSortedArrayString : public wxArrayString
+class wxSortedArrayString : public wxArray

 {
 public:
 {
 public:

-

     /**
     /**

-        Copy constructor. Note that when an array is assigned to a sorted array,
-        its contents is automatically sorted during construction.
+        Conversion constructor.
+
+        Constructs a sorted array with the same contents as the (possibly
+        unsorted) "array" argument.

     */
     */

-    wxArrayString(const wxArrayString& array);
+    wxSortedArrayString(const wxArrayString& array);

 
     /**
         @copydoc wxArrayString::Add()
 
     /**
         @copydoc wxArrayString::Add()


@@ -310,22 +306,26 @@ public:
         the @a bCase and @a bFromEnd parameters.
     */
     int Index(const wxString& sz, bool bCase = true,
         the @a bCase and @a bFromEnd parameters.
     */
     int Index(const wxString& sz, bool bCase = true,

-              bool bFromEnd = false);
+              bool bFromEnd = false) const;

 
     /**
 
     /**

-        @warning this function should not be used with sorted arrays because it
+        @warning This function should not be used with sorted arrays because it

                  could break the order of items and, for example, subsequent calls
                  to Index() would then not work!
                  could break the order of items and, for example, subsequent calls
                  to Index() would then not work!

+
+        @warning In STL mode, Insert is private and simply invokes wxFAIL_MSG.

     */
     void Insert(const wxString& str, size_t nIndex,
                 size_t copies = 1);
 
     //@{
     /**
     */
     void Insert(const wxString& str, size_t nIndex,
                 size_t copies = 1);
 
     //@{
     /**

-        @warning this function should not be used with sorted array because it could
+        @warning This function should not be used with sorted array because it could

                  break the order of items and, for example, subsequent calls to Index()
                  would then not work! Also, sorting a wxSortedArrayString doesn't make
                  sense because its elements are always already sorted.
                  break the order of items and, for example, subsequent calls to Index()
                  would then not work! Also, sorting a wxSortedArrayString doesn't make
                  sense because its elements are always already sorted.

+
+        @warning In STL mode, Sort is private and simply invokes wxFAIL_MSG.

     */
     void Sort(bool reverseOrder = false);
     void Sort(CompareFunction compareFunction);
     */
     void Sort(bool reverseOrder = false);
     void Sort(CompareFunction compareFunction);


@@ -337,7 +337,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_string */
+/** @addtogroup group_funcmacro_string */

 //@{
 
 /**
 //@{
 
 /**