Add wxDictionaryStringSortAscending comparison function.

Add "dictionary sort" callbacks and document them and the already existing
wxStringSortAscending() and wxStringSortDescending().

See #16330.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@76753 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/arrstr.h

@@ -27,6 +27,22 @@ inline int wxCMPFUNC_CONV wxStringSortDescending(const wxString& s1, const wxStr
     return wxStringSortAscending(s2, s1);
 }
 
+// This comparison function ignores case when comparing strings differing not
+// in case only, i.e. this ensures that "Aa" comes before "AB", unlike with
+// wxStringSortAscending().
+inline int wxCMPFUNC_CONV
+wxDictionaryStringSortAscending(const wxString& s1, const wxString& s2)
+{
+    const int cmp = s1.CmpNoCase(s2);
+    return cmp ? cmp : s1.Cmp(s2);
+}
+
+inline int wxCMPFUNC_CONV
+wxDictionaryStringSortDescending(const wxString& s1, const wxString& s2)
+{
+    return wxDictionaryStringSortAscending(s2, s1);
+}
+
 #if wxUSE_STD_CONTAINERS
 
 #include "wx/dynarray.h"

interface/wx/arrstr.h

@@ -299,6 +299,8 @@ public:
         Constructs a sorted array using the specified @a compareFunction for
         item comparison.
 
+        @see wxStringSortAscending(), wxDictionaryStringSortAscending()
+
         @since 3.1.0
     */
     wxSortedArrayString(CompareFunction compareFunction);
@@ -355,6 +357,57 @@ public:
     //@}
 };
 
+/**
+    Comparison function comparing strings in alphabetical order.
+
+    This function can be used with wxSortedArrayString::Sort() or passed as an
+    argument to wxSortedArrayString constructor.
+
+    @see wxStringSortDescending(), wxDictionaryStringSortAscending()
+
+    @since 3.1.0
+ */
+int wxStringSortAscending(const wxString& s1, const wxString& s2);
+
+/**
+    Comparison function comparing strings in reverse alphabetical order.
+
+    This function can be used with wxSortedArrayString::Sort() or passed as an
+    argument to wxSortedArrayString constructor.
+
+    @see wxStringSortAscending(), wxDictionaryStringSortAscending()
+
+    @since 3.1.0
+ */
+int wxStringSortDescending(const wxString& s1, const wxString& s2);
+
+/**
+    Comparison function comparing strings in dictionary order.
+
+    The "dictionary order" differs from the alphabetical order in that the
+    strings differing not only in case are compared case-insensitively to
+    ensure that "Aa" comes before "AB" in the sorted array, unlike with
+    wxStringSortAscending().
+
+    This function can be used with wxSortedArrayString::Sort() or passed as an
+    argument to wxSortedArrayString constructor.
+
+    @see wxStringSortAscending(), wxDictionaryStringSortDescending()
+
+    @since 3.1.0
+ */
+int wxDictionaryStringSortAscending(const wxString& s1, const wxString& s2);
+
+/**
+    Comparison function comparing strings in reverse dictionary order.
+
+    See wxDictionaryStringSortAscending() for the dictionary sort description.
+
+    @see wxStringSortDescending()
+
+    @since 3.1.0
+ */
+int wxDictionaryStringSortAscending(const wxString& s1, const wxString& s2);
 
 // ============================================================================
 // Global functions/macros

tests/arrays/arrays.cpp

@@ -358,6 +358,20 @@ void ArraysTestCase::SortedArray()
     a.push_back("b");
     a.push_back("a");
     CPPUNIT_ASSERT_EQUAL( 0, a.Index("a") );
+
+
+    wxSortedArrayString ar(wxStringSortDescending);
+    ar.Add("a");
+    ar.Add("b");
+    CPPUNIT_ASSERT_EQUAL( "b", ar[0] );
+    CPPUNIT_ASSERT_EQUAL( "a", ar[1] );
+
+    wxSortedArrayString ad(wxDictionaryStringSortAscending);
+    ad.Add("AB");
+    ad.Add("a");
+    ad.Add("Aa");
+    CPPUNIT_ASSERT_EQUAL( "a", ad[0] );
+    CPPUNIT_ASSERT_EQUAL( "Aa", ad[1] );
 }
 
 void ArraysTestCase::wxStringArraySplitTest()