Add functions for sorting strings in natural sort order

Use StrCmpLogicalW() under MSW and generic implementation under the
other platforms.

See https://github.com/wxWidgets/wxWidgets/pull/780

interface/wx/arrstr.h

@@ -363,7 +363,8 @@ public:
     This function can be used with wxSortedArrayString::Sort() or passed as an
     argument to wxSortedArrayString constructor.
 
-    @see wxStringSortDescending(), wxDictionaryStringSortAscending()
+    @see wxStringSortDescending(), wxDictionaryStringSortAscending(),
+         wxNaturalStringSortAscending()
 
     @since 3.1.0
  */
@@ -375,7 +376,8 @@ int wxStringSortAscending(const wxString& s1, const wxString& s2);
     This function can be used with wxSortedArrayString::Sort() or passed as an
     argument to wxSortedArrayString constructor.
 
-    @see wxStringSortAscending(), wxDictionaryStringSortAscending()
+    @see wxStringSortAscending(), wxDictionaryStringSortDescending(),
+         wxNaturalStringSortDescending()
 
     @since 3.1.0
  */
@@ -392,8 +394,10 @@ int wxStringSortDescending(const wxString& s1, const wxString& s2);
     This function can be used with wxSortedArrayString::Sort() or passed as an
     argument to wxSortedArrayString constructor.
 
-    @see wxStringSortAscending(), wxDictionaryStringSortDescending()
-
+    @see wxDictionaryStringSortDescending(),
+         wxStringSortAscending(),
+         wxNaturalStringSortAscending()
+         
     @since 3.1.0
  */
 int wxDictionaryStringSortAscending(const wxString& s1, const wxString& s2);
@@ -403,11 +407,98 @@ int wxDictionaryStringSortAscending(const wxString& s1, const wxString& s2);
 
     See wxDictionaryStringSortAscending() for the dictionary sort description.
 
-    @see wxStringSortDescending()
+    @see wxDictionaryStringSortAscending(),
+         wxStringSortDescending(),
+         wxNaturalStringSortDescending()
 
     @since 3.1.0
  */
-int wxDictionaryStringSortAscending(const wxString& s1, const wxString& s2);
+int wxDictionaryStringSortDescending(const wxString& s1, const wxString& s2);
+
+
+    /**
+        Comparison function used for Natural Sort.
+        
+        Functions in the same way as wxDictionaryStringSortAscending(), with
+        the exception that numbers within the string are recognised, and
+        compared numerically, rather than alphabetically. When used for
+        sorting, the result is that e.g. file names containing numbers are
+        sorted in a natural way.
+
+        This function will use an OS native function if one is available,
+        to ensure that the sort order is the same as the OS uses.
+        
+        Comparison is case insensitive.
+            
+        e.g. Sorting using wxDictionaryStringSortAscending() results in:
+        - file1.txt
+        - file10.txt
+        - file100.txt
+        - file2.txt
+        - file20.txt
+        - file3.txt
+        
+        e.g. Sorting using wxNaturalStringSortAscending() results in:
+        - file1.txt
+        - file2.txt
+        - file3.txt
+        - file11.txt
+        - file20.txt
+        - file100.txt
+        
+        @see wxNaturalStringSortDescending(),
+             wxStringSortAscending(),
+             wxDictionaryStringSortAscending()
+        
+        @since 3.1.2  
+    */
+int wxNaturalStringSortAscending(const wxString& s1, const wxString& s2);
+
+
+    /**
+        Comparison function comparing strings in reverse natural order.
+        
+        See wxNaturalStringSortAscending() for the natural sort description.
+    
+        @see wxNaturalStringSortAscending(),
+             wxStringSortDescending(),
+             wxDictionaryStringSortDescending()
+             
+        @since 3.1.2
+    */
+int wxNaturalStringSortDescending(const wxString& s1, const wxString& s2);
+
+
+    /**
+        This is wxWidgets' own implementation of the natural sort comparison
+        function. This will be used whenever an OS native function is not available.
+        
+        Since OS native implementations might differ from each other, the user might
+        wish to use this function which behaves in the same way across all platforms.
+        
+        @since 3.1.2
+    */
+int wxCMPFUNC_CONV wxCmpNatural(const wxString& s1, const wxString& s2);
+
+
+    /**
+        Comparison function, identical to wxNaturalStringSortAscending().
+        In fact, wxNaturalStringSortAscending() and wxNaturalStringSortDescending()
+        are both implemented using this function.
+        
+        When an OS native natural sort function is available, that will be used,
+        otherwise wxCmpNatural() will be used.
+
+        Be aware that OS native implementations might differ from each other, and
+        might change behaviour from release to release.
+        
+        @see wxNaturalStringSortAscending(),
+             wxNaturalStringSortDescending()
+             
+        @since 3.1.2
+    */
+int wxCMPFUNC_CONV wxCmpNaturalNative(const wxString& s1, const wxString& s2);
+
 
 // ============================================================================
 // Global functions/macros