Document fl_numericsort() and fl_casenumericsort().

Note: These two functions are not yet UTF-8 aware. Results may be unexpected.

Possible test case: run test/file_chooser or any FLTK program with
Fl_File_Chooser. The default display order is determined by fl_numericsort():

  Fl_File_Chooser::sort = fl_numericsort;


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.4@12738 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

src/numericsort.c

@@ -3,7 +3,7 @@
  *
  * Numeric sorting routine for the Fast Light Tool Kit (FLTK).
  *
- * Copyright 1998-2016 by Bill Spitzak and others.
+ * Copyright 1998-2018 by Bill Spitzak and others.
  *
  * This library is free software. Distribution and use rights are outlined in
  * the file "COPYING" which should have been included with this file.  If this
@@ -21,10 +21,17 @@
 #include <FL/platform_types.h>
 #include <FL/filename.H>
 
+/**
+  \file numericsort.c
+*/
+
 /*
- * 'numericsort()' - Compare two directory entries, possibly with
- *                   a case-insensitive comparison...
- */
+  numericsort() - Compare two directory entries, possibly with a
+                  case-insensitive comparison...
+
+  *FIXME* This is not UTF-8 aware -- particularly case-insensitive comparison.
+  *FIXME* If you fix it, don't forget to update the documentation below.
+*/
 
 static int numericsort(struct dirent **A, struct dirent **B, int cs) {
   const char* a = (*A)->d_name;
@@ -40,14 +47,14 @@ static int numericsort(struct dirent **A, struct dirent **B, int cs) {
       magdiff = 0;
       while (isdigit(*a & 255)) {magdiff++; a++;}
       while (isdigit(*b & 255)) {magdiff--; b++;}
-      if (magdiff) {ret = magdiff; break;} /* compare # of significant digits*/
-      if (diff) {ret = diff; break;}	/* compare first non-zero digit */
+      if (magdiff) {ret = magdiff; break;} /* compare # of significant digits */
+      if (diff) {ret = diff; break;}       /* compare first non-zero digit */
     } else {
       if (cs) {
       	/* compare case-sensitive */
 	if ((ret = *a-*b)) break;
       } else {
-	/* compare case-insensitve */
+	/* compare case-insensitive */
 	if ((ret = tolower(*a & 255)-tolower(*b & 255))) break;
       }
 
@@ -59,17 +66,58 @@ static int numericsort(struct dirent **A, struct dirent **B, int cs) {
   else return (ret < 0) ? -1 : 1;
 }
 
-/*
- * 'fl_casenumericsort()' - Compare directory entries with case-sensitivity.
- */
+/**
+  Compares directory entries alphanumerically (case-insensitive).
+
+  \note	This comparison is not (yet) UTF-8 aware.
+
+  \todo Make comparison UTF-8 aware.
+
+  \see fl_numericsort()
+*/
 
 int fl_casenumericsort(struct dirent **A, struct dirent **B) {
   return numericsort(A, B, 0);
 }
 
-/*
- * 'fl_numericsort()' - Compare directory entries with case-sensitivity.
- */
+/**
+  Compares directory entries alphanumerically (case-sensitive).
+
+  Numbers are compared without sign, i.e. "-" is not taken as a sign of
+  following numerical values. The following list of files would be in
+  ascending order (examples are ASCII and numbers only for simplicity):
+
+   -# 1zzz.txt
+   -# 2xxx.txt
+   -# 19uuu.txt
+   -# 100aaa.txt
+   -# file1z.txt
+   -# file5a.txt
+   -# file5z.txt
+   -# file30z.txt
+   -# file200a.txt
+   -# temp+5.txt   ('+' is lexically lower than '-')
+   -# temp-5.txt   ('-' is not a sign)
+   -# temp-100.txt (100 is bigger than 5, no sign)
+
+  \param[in] A first directory entry
+  \param[in] B second directory entry
+
+  \returns comparison result (-1, 0, or +1)
+  \retval  -1 A \< B
+  \retval   0 A == B
+  \retval  +1 A \> B
+
+  \note	This comparison is not (yet) UTF-8 aware:
+    - UTF-8 characters are compared according to their binary values.
+    - Locale settings may influence the result in unexpected ways.
+    - The latter is particularly true for fl_casenumericsort().
+  This may be changed in a future release.
+
+  \todo Make comparison UTF-8 aware.
+
+  \see fl_casenumericsort()
+*/
 
 int fl_numericsort(struct dirent **A, struct dirent **B) {
   return numericsort(A, B, 1);