Functions renamed with "intl" prefix

Better naming of functions to help future maintenance.
- compare() renamed to intl_strcmp()
- sort_pagenames() renamed to intl_sort()
- sort_keys() renamed to intl_ksort()
- new function intl_asort()
- sort_filenames() renamed to intl_asortFN()
Updated documentation.

inc/Ajax.php

@@ -98,7 +98,7 @@ class Ajax {
         $data = array_map('trim', $data);
         $data = array_map('noNS', $data);
         $data = array_unique($data);
-        sort_pagenames($data);
+        intl_sort($data);
 
         /* now construct a json */
         $suggestions = array(

inc/Ui/Admin.php

@@ -159,7 +159,7 @@ class Admin extends Ui {
      * @return int
      */
     protected function menuSort($a, $b) {
-        $strcmp = compare($a['prompt'], $b['prompt']);
+        $strcmp = intl_strcmp($a['prompt'], $b['prompt']);
         if($strcmp != 0) return $strcmp;
         if($a['sort'] === $b['sort']) return 0;
         return ($a['sort'] < $b['sort']) ? -1 : 1;

inc/Ui/Search.php

@@ -384,7 +384,7 @@ class Search extends Ui
             }
             $namespaces[$subtopNS] += 1;
         }
-        sort_keys($namespaces);
+        intl_ksort($namespaces);
         arsort($namespaces);
         return $namespaces;
     }

inc/fulltext.php

@@ -180,7 +180,7 @@ function ft_backlinks($id, $ignore_perms = false){
         }
     }
 
-    sort_pagenames($result);
+    intl_sort($result);
     return $result;
 }
 
@@ -211,7 +211,7 @@ function ft_mediause($id, $ignore_perms = false){
         }
     }
 
-    sort_pagenames($result);
+    intl_sort($result);
     return $result;
 }
 
@@ -370,7 +370,7 @@ function ft_pagesorter($a, $b){
     }elseif($ac > $bc){
         return 1;
     }
-    return compare($a,$b);
+    return intl_strcmp($a,$b);
 }
 
 /**

inc/search.php

@@ -49,9 +49,9 @@ function search(&$data,$base,$func,$opts,$dir='',$lvl=1,$sort='natural'){
         if ($sort == 'date') {
             @array_multisort(array_map('filemtime', $filepaths), SORT_NUMERIC, SORT_DESC, $files);
         } else /* natural */ {
-            sort_filenames($files);
+            intl_asortFN($files);
         }
-        sort_filenames($dirs);
+        intl_asortFN($dirs);
     }
 
     //give directories to userfunction then recurse
@@ -368,7 +368,7 @@ function sort_search_fulltext($a,$b){
     }elseif($a['count'] < $b['count']){
         return 1;
     }else{
-        return compare($a['id'],$b['id']);
+        return intl_strcmp($a['id'],$b['id']);
     }
 }
 

inc/sort.php

@@ -7,7 +7,7 @@
  *
  * The collator is created using the locale given in $conf['lang'].
  * It always uses case insensitive "natural" ordering in its collation.
- * The fallback solution uses the primitive PHP functions that return the same results.
+ * The fallback solution uses the primitive PHP functions that return almost the same results.
  *
  * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
  * @author     Moisés Braga Ribeiro <moisesbr@gmail.com>
@@ -40,116 +40,138 @@ function _init_collator() {
 }
 
 /**
- * Drop-in replacement for string comparison functions.
+ * Drop-in replacement for strcmp(), strcasecmp(), strnatcmp() and strnatcasecmp().
  * It uses a collator-based comparison, or strnatcasecmp() as a fallback.
  *
  * Replacement for strcmp() in fulltext.php, line 373.
  * Replacement for strcmp() in search.php, line 371.
  * Replacement for strcasecmp() in Ui/Admin.php, line 162.
  *
- * @param string $first  first string to compare
- * @param string $second second string to compare
- * @return int negative value if $first is before $second; positive value if $first is after $second; zero if they are equal
+ * @param string $str1 The first string.
+ * @param string $str2 The second string.
+ * @return int Returns < 0 if $str1 is less than $str2; > 0 if $str1 is greater than $str2, and 0 if they are equal.
  *
  * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  */
-function compare($first, $second) {
+function intl_strcmp($str1, $str2) {
     global $collator;
     _init_collator();
 
     if (isset($collator))
-        return $collator->compare($first, $second);
+        return $collator->compare($str1, $str2);
     else
-        return strnatcasecmp($first, $second);
+        return strnatcasecmp($str1, $str2);
 }
 
 /**
- * Drop-in replacement for sort() when the parameter is an array of page names or generic strings.
+ * Drop-in replacement for sort().
  * It uses a collator-based sort, or sort() with flags SORT_NATURAL and SORT_FLAG_CASE as a fallback.
  *
  * Replacement for sort() in fulltext.php, lines 183 and 214.
  * Replacement for sort() in Ajax.php, line 101.
  *
- * @param string $pagenames the array to be sorted
+ * @param array $array The input array.
+ * @return bool Returns TRUE on success or FALSE on failure.
  *
  * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  */
-function sort_pagenames(&$pagenames) {
+function intl_sort(&$array) {
     global $collator;
     _init_collator();
 
     if (isset($collator))
-        $collator->sort($pagenames);
+        return $collator->sort($array);
     else
-        sort($pagenames, SORT_NATURAL | SORT_FLAG_CASE);
+        return sort($array, SORT_NATURAL | SORT_FLAG_CASE);
 }
 
 /**
- * Drop-in replacement for ksort() when the parameter is an associative array with page names as keys.
+ * Drop-in replacement for ksort().
  * It uses a collator-based sort, or ksort() with flags SORT_NATURAL and SORT_FLAG_CASE as a fallback.
  *
  * Replacement for ksort() in Ui/Search.php, line 387.
  *
- * @param string $keys the associative array to be sorted
+ * @param array $array The input array.
+ * @return bool Returns TRUE on success or FALSE on failure.
  *
  * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  */
-function sort_keys(&$keys) {
+function intl_ksort(&$array) {
     global $collator;
     _init_collator();
 
     if (isset($collator))
-        uksort($keys, array($collator, 'compare'));
+        return uksort($array, array($collator, 'compare'));
     else
-        ksort($keys, SORT_NATURAL | SORT_FLAG_CASE);
+        return ksort($array, SORT_NATURAL | SORT_FLAG_CASE);
 }
 
 /**
- * Drop-in replacement for natsort() when the parameter is an array of file names.
+ * Drop-in replacement for asort(), natsort() and natcasesort().
+ * It uses a collator-based sort, or asort() with flags SORT_NATURAL and SORT_FLAG_CASE as a fallback.
+ *
+ * @param array $array The input array.
+ * @return bool Returns TRUE on success or FALSE on failure.
+ *
+ * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
+ */
+function intl_asort(&$array) {
+    global $collator;
+    _init_collator();
+
+    if (isset($collator))
+        return $collator->asort($array);
+    else
+        return asort($array, SORT_NATURAL | SORT_FLAG_CASE);
+}
+
+/**
+ * Drop-in replacement for asort(), natsort() and natcasesort() when the parameter is an array of filenames.
  * Filenames may not be equal to page names, depending on the setting in $conf['fnencode'],
  * so the correct behavior is to sort page names and reflect this sorting in the filename array.
  *
  * Replacement for natsort() in search.php, lines 52 and 54.
  *
- * @param string $filenames the array to be sorted
+ * @param array $array The input array.
+ * @return bool Returns TRUE on success or FALSE on failure.
  *
  * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  */
-function sort_filenames(&$filenames) {
+function intl_asortFN(&$array) {
     global $collator;
     _init_collator();
 
     if (isset($collator))
-        return uasort($filenames, '_sort_filenames_with_collator');
+        return uasort($array, '_sort_filenames_with_collator');
     else
-        return uasort($filenames, '_sort_filenames_without_collator');
+        return uasort($array, '_sort_filenames_without_collator');
 }
 
 /**
  * Collator-based string comparison for filenames.
  * The filenames are converted to page names with utf8_decodeFN() before the comparison.
  * 
- * @param string $first  first filename to compare
- * @param string $second second filename to compare
- * @return int negative value if $first is before $second; positive value if $first is after $second; zero if they are equal
+ * @param string $fn1 The first filename.
+ * @param string $fn2 The second filename.
+ * @return int Returns < 0 if $fn1 is less than $fn2; > 0 if $fn1 is greater than $fn2, and 0 if they are equal.
  *
  * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  */
-function _sort_filenames_with_collator($first, $second) {
+function _sort_filenames_with_collator($fn1, $fn2) {
     global $collator;
-    return $collator->compare(utf8_decodeFN($first), utf8_decodeFN($second));
+    return $collator->compare(utf8_decodeFN($fn1), utf8_decodeFN($fn2));
 }
 
 /**
  * Fallback string comparison for filenames, using strnatcasecmp().
  * The filenames are converted to page names with utf8_decodeFN() before the comparison.
  * 
- * @param string $first  first filename to compare
- * @param string $second second filename to compare
- * @return int negative value if $first is before $second; positive value if $first is after $second; zero if they are equal
+ * @param string $fn1 The first filename.
+ * @param string $fn2 The second filename.
+ * @return int Returns < 0 if $fn1 is less than $fn2; > 0 if $fn1 is greater than $fn2, and 0 if they are equal.
  *
  * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  */
-function _sort_filenames_without_collator($first, $second) {
-    return strnatcasecmp(utf8_decodeFN($first), utf8_decodeFN($second));
+function _sort_filenames_without_collator($fn1, $fn2) {
+    return strnatcasecmp(utf8_decodeFN($fn1), utf8_decodeFN($fn2));
 }