[svn r21509] FS#306 - The multibyte string function: Adding functions for language-sensitive sorting - api_asort() and api_arsort().

main/inc/lib/multibyte_string_functions.lib.php

@@ -1054,7 +1054,7 @@ function api_strcasecmp($string1, $string2, $language = null, $encoding = null)
  */
 function api_strcmp($string1, $string2, $language = null, $encoding = null) {
 	if (INTL_INSTALLED) {
-		$collator = api_get_collator($language);
+		$collator = _api_get_collator($language);
 		if (is_object($collator)) {
 			$result = collator_compare($collator, api_utf8_encode($string1, $encoding), api_utf8_encode($string2, $encoding));
 			return $result === false ? 0 : $result;
@@ -1063,24 +1063,6 @@ function api_strcmp($string1, $string2, $language = null, $encoding = null) {
 	return strcmp($string1, $string2);
 }
 
-/**
- * Returns an instance of Collator class (ICU) created for a specified language.
- * @param string $language (optional)	The specified language. If it is omitted, then the interface language is assumed.
- * @return object						The corresponding instance of Collator class.
- * @link http://php.net/manual/en/collator.create.php
- */
-function api_get_collator($language = null) {
-	static $collator = array();
-	if (INTL_INSTALLED) {
-		if (!isset($collator[$language])) {
-			$locale = api_get_locale_from_language($language);
-			$collator[$language] = collator_create($locale);
-		}
-		return $collator[$language];
-	}
-	return null;
-}
-
 /**
  * Checks if a value exists in an array, a case insensitive version of in_array() function with extended multibyte support.
  * @param mixed $needle					The searched value. If needle is a string, the comparison is done in a case-insensitive manner.
@@ -1112,12 +1094,93 @@ function api_in_array_nocase($needle, $haystack, $strict = false, $encoding = nu
 	return false;
 }
 
+// Returns an instance of Collator class (ICU) created for a specified language, for internal use.
+function _api_get_collator($language = null) {
+	static $collator = array();
+	if (!isset($collator[$language])) {
+		$locale = api_get_locale_from_language($language);
+		$collator[$language] = collator_create($locale);
+	}
+	return $collator[$language];
+}
+
 /**
  * ----------------------------------------------------------------------------
  * Sorting arrays
  * ----------------------------------------------------------------------------
  */
 
+/**
+ * Sorts an array with maintaining index association, elements will be arranged from the lowest to the highest.
+ * @param array $array					The input array.
+ * @param int $sort_flag (optional)		Shows how elements of the array to be compared.
+ * @param string $language (optional)	The language in which comparison is to be made. If language is omitted, interface language is assumed then.
+ * @param string $encoding (optional)	The used internally by this function character encoding. If it is omitted, the platform character set will be used by default.
+ * @return bool							Returns TRUE on success, FALSE on error.
+ * Note: $sort_flag may have the following values:
+ * SORT_REGULAR - for simple byte ordered ASCII comparison without changing types;
+ * SORT_NUMERIC - items will be compared as numbers;
+ * SORT_STRING - items will be compared as strings. If intl extension is enabled, then comparison will be language-sensitive using internally a created ICU locale;
+ * SORT_LOCALE_STRING - items will be compared as strings depending on the current POSIX locale. If intl extension is enabled, then comparison will be language-sensitive using internally a created ICU locale.
+ * This function is aimed at replacing the function sort() for sorting human-language strings.
+ * @link http://php.net/manual/en/function.asort.php
+ * @link http://php.net/manual/en/collator.asort.php
+ */
+function api_asort(&$array, $sort_flag = SORT_REGULAR, $language = null, $encoding = null) {
+	if (INTL_INSTALLED) {
+		if (empty($encoding)) {
+			$encoding = api_mb_internal_encoding();
+		}
+		$collator = _api_get_collator($language);
+		if (is_object($collator)) {
+			if (api_is_utf8($encoding)) {
+				$sort_flag = ($sort_flag == SORT_LOCALE_STRING) ? SORT_STRING : $sort_flag;
+				return collator_asort($collator, $array, _api_get_collator_sort_flag($sort_flag));
+			}
+			elseif ($sort_flag == SORT_STRING || $sort_flag == SORT_LOCALE_STRING) {
+				global $_api_collator, $_api_encoding;
+				$_api_collator = $collator;
+				$_api_encoding = $encoding;
+				return uasort($array, '_api_cmp');
+			}
+		}
+	}
+	return asort($array, $sort_flag);
+}
+
+/**
+ * Sorts an array with maintaining index association, elements will be arranged from the highest to the lowest (in reverse order).
+ * @param array $array					The input array.
+ * @param int $sort_flag (optional)		Shows how elements of the array to be compared.
+ * @param string $language (optional)	The language in which comparison is to be made. If language is omitted, interface language is assumed then.
+ * @param string $encoding (optional)	The used internally by this function character encoding. If it is omitted, the platform character set will be used by default.
+ * @return bool							Returns TRUE on success, FALSE on error.
+ * Note: $sort_flag may have the following values:
+ * SORT_REGULAR - for simple byte ordered ASCII comparison without changing types;
+ * SORT_NUMERIC - items will be compared as numbers;
+ * SORT_STRING - items will be compared as strings. If intl extension is enabled, then comparison will be language-sensitive using internally a created ICU locale;
+ * SORT_LOCALE_STRING - items will be compared as strings depending on the current POSIX locale. If intl extension is enabled, then comparison will be language-sensitive using internally a created ICU locale.
+ * This function is aimed at replacing the function rsort() for sorting human-language strings.
+ * @link http://php.net/manual/en/function.arsort.php
+ */
+function api_arsort(&$array, $sort_flag = SORT_REGULAR, $language = null, $encoding = null) {
+	if (INTL_INSTALLED) {
+		if (empty($encoding)) {
+			$encoding = api_mb_internal_encoding();
+		}
+		$collator = _api_get_collator($language);
+		if (is_object($collator)) {
+			if ($sort_flag == SORT_STRING || $sort_flag == SORT_LOCALE_STRING) {
+				global $_api_collator, $_api_encoding;
+				$_api_collator = $collator;
+				$_api_encoding = $encoding;
+				return uasort($array, '_api_rcmp');
+			}
+		}
+	}
+	return arsort($array, $sort_flag);
+}
+
 /**
  * Sorts an array, elements will be arranged from the lowest to the highest.
  * @param array $array					The input array.
@@ -1139,7 +1202,7 @@ function api_sort(&$array, $sort_flag = SORT_REGULAR, $language = null, $encodin
 		if (empty($encoding)) {
 			$encoding = api_mb_internal_encoding();
 		}
-		$collator = api_get_collator($language);
+		$collator = _api_get_collator($language);
 		if (is_object($collator)) {
 			if (api_is_utf8($encoding)) {
 				$sort_flag = ($sort_flag == SORT_LOCALE_STRING) ? SORT_STRING : $sort_flag;
@@ -1170,14 +1233,13 @@ function api_sort(&$array, $sort_flag = SORT_REGULAR, $language = null, $encodin
  * SORT_LOCALE_STRING - items will be compared as strings depending on the current POSIX locale. If intl extension is enabled, then comparison will be language-sensitive using internally a created ICU locale.
  * This function is aimed at replacing the function rsort() for sorting human-language strings.
  * @link http://php.net/manual/en/function.rsort.php
- * @link http://php.net/manual/en/collator.sort.php
  */
 function api_rsort(&$array, $sort_flag = SORT_REGULAR, $language = null, $encoding = null) {
 	if (INTL_INSTALLED) {
 		if (empty($encoding)) {
 			$encoding = api_mb_internal_encoding();
 		}
-		$collator = api_get_collator($language);
+		$collator = _api_get_collator($language);
 		if (is_object($collator)) {
 			if ($sort_flag == SORT_STRING || $sort_flag == SORT_LOCALE_STRING) {
 				global $_api_collator, $_api_encoding;