lib/classes/collator.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Defines string apis
  19  *
  20  * @package   core
  21  * @copyright 2011 Sam Hemelryk
  22  *            2012 Petr Skoda
  23  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 defined('MOODLE_INTERNAL') || die();
  27
  28 /**
  29  * A collator class with static methods that can be used for sorting.
  30  *
  31  * @package   core
  32  * @copyright 2011 Sam Hemelryk
  33  *            2012 Petr Skoda
  34  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  35  */
  36 class core_collator {
  37     /** @const compare items using general PHP comparison, equivalent to Collator::SORT_REGULAR, this may bot be locale aware! */
  38     const SORT_REGULAR = 0;
  39
  40     /** @const compare items as strings, equivalent to Collator::SORT_STRING */
  41     const SORT_STRING = 1;
  42
  43     /** @const compare items as numbers, equivalent to Collator::SORT_NUMERIC */
  44     const SORT_NUMERIC = 2;
  45
  46     /** @const compare items like natsort(), equivalent to SORT_NATURAL */
  47     const SORT_NATURAL = 6;
  48
  49     /** @const do not ignore case when sorting, use bitwise "|" with SORT_NATURAL or SORT_STRING, equivalent to Collator::UPPER_FIRST */
  50     const CASE_SENSITIVE = 64;
  51
  52     /** @var Collator|false|null **/
  53     protected static $collator = null;
  54
  55     /** @var string|null The locale that was used in instantiating the current collator **/
  56     protected static $locale = null;
  57
  58     /**
  59      * Prevent class instances, all methods are static.
  60      */
  61     private function __construct() {
  62     }
  63
  64     /**
  65      * Ensures that a collator is available and created
  66      *
  67      * @return bool Returns true if collation is available and ready
  68      */
  69     protected static function ensure_collator_available() {
  70         $locale = get_string('locale', 'langconfig');
  71         if (is_null(self::$collator) || $locale != self::$locale) {
  72             self::$collator = false;
  73             self::$locale = $locale;
  74             if (class_exists('Collator', false)) {
  75                 $collator = new Collator($locale);
  76                 if (!empty($collator) && $collator instanceof Collator) {
  77                     // Check for non fatal error messages. This has to be done immediately
  78                     // after instantiation as any further calls to collation will cause
  79                     // it to reset to 0 again (or another error code if one occurred)
  80                     $errorcode = $collator->getErrorCode();
  81                     $errormessage = $collator->getErrorMessage();
  82                     // Check for an error code, 0 means no error occurred
  83                     if ($errorcode !== 0) {
  84                         // Get the actual locale being used, e.g. en, he, zh
  85                         $localeinuse = $collator->getLocale(Locale::ACTUAL_LOCALE);
  86                         // Check for the common fallback warning error codes. If any of the two
  87                         // following errors occurred, there is normally little to worry about:
  88                         // * U_USING_FALLBACK_WARNING (-128) indicates that a fall back locale was
  89                         //   used. For example, 'de_CH' was requested, but nothing was found
  90                         //   there, so 'de' was used.
  91                         // * U_USING_DEFAULT_WARNING (-127) indicates that the default locale
  92                         //   data was used; neither the requested locale nor any of its fall
  93                         //   back locales could be found. For example, 'pt' was requested, but
  94                         //   UCA was used (Unicode Collation Algorithm http://unicode.org/reports/tr10/).
  95                         // See http://www.icu-project.org/apiref/icu4c/classicu_1_1ResourceBundle.html
  96                         if ($errorcode === -127 || $errorcode === -128) {
  97                             // Check if the locale in use is UCA default one ('root') or
  98                             // if it is anything like the locale we asked for
  99                             if ($localeinuse !== 'root' && strpos($locale, $localeinuse) !== 0) {
 100                                 // The locale we asked for is completely different to the locale
 101                                 // we have received, let the user know via debugging
 102                                 debugging('Locale warning (not fatal) '.$errormessage.': '.
 103                                     'Requested locale "'.$locale.'" not found, locale "'.$localeinuse.'" used instead. '.
 104                                     'The most specific locale supported by ICU relatively to the requested locale is "'.
 105                                     $collator->getLocale(Locale::VALID_LOCALE).'".');
 106                             } else {
 107                                 // Nothing to do here, this is expected!
 108                                 // The Moodle locale setting isn't what the collator expected but
 109                                 // it is smart enough to match the first characters of our locale
 110                                 // to find the correct locale or to use UCA collation
 111                             }
 112                         } else {
 113                             // We've received some other sort of non fatal warning - let the
 114                             // user know about it via debugging.
 115                             debugging('Problem with locale: '.$errormessage.'. '.
 116                                 'Requested locale: "'.$locale.'", actual locale "'.$localeinuse.'". '.
 117                                 'The most specific locale supported by ICU relatively to the requested locale is "'.
 118                                 $collator->getLocale(Locale::VALID_LOCALE).'".');
 119                         }
 120                     }
 121                     // Store the collator object now that we can be sure it is in a workable condition
 122                     self::$collator = $collator;
 123                 } else {
 124                     // Fatal error while trying to instantiate the collator... something went wrong
 125                     debugging('Error instantiating collator for locale: "' . $locale . '", with error [' .
 126                     intl_get_error_code() . '] ' . intl_get_error_message($collator));
 127                 }
 128             }
 129         }
 130         return (self::$collator instanceof Collator);
 131     }
 132
 133     /**
 134      * Restore array contents keeping new keys.
 135      * @static
 136      * @param array $arr
 137      * @param array $original
 138      * @return void modifies $arr
 139      */
 140     protected static function restore_array(array &$arr, array &$original) {
 141         foreach ($arr as $key => $ignored) {
 142             $arr[$key] = $original[$key];
 143         }
 144     }
 145
 146     /**
 147      * Normalise numbers in strings for natural sorting comparisons.
 148      * @static
 149      * @param string $string
 150      * @return string string with normalised numbers
 151      */
 152     protected static function naturalise($string) {
 153         return preg_replace_callback('/[0-9]+/', array('core_collator', 'callback_naturalise'), $string);
 154     }
 155
 156     /**
 157      * @internal
 158      * @static
 159      * @param array $matches
 160      * @return string
 161      */
 162     public static function callback_naturalise($matches) {
 163         return str_pad($matches[0], 20, '0', STR_PAD_LEFT);
 164     }
 165
 166     /**
 167      * Locale aware sorting, the key associations are kept, values are sorted alphabetically.
 168      *
 169      * @param array $arr array to be sorted (reference)
 170      * @param int $sortflag One of core_collator::SORT_NUMERIC, core_collator::SORT_STRING, core_collator::SORT_NATURAL, core_collator::SORT_REGULAR
 171      *      optionally "|" core_collator::CASE_SENSITIVE
 172      * @return bool True on success
 173      */
 174     public static function asort(array &$arr, $sortflag = core_collator::SORT_STRING) {
 175         if (empty($arr)) {
 176             // nothing to do
 177             return true;
 178         }
 179
 180         $original = null;
 181
 182         $casesensitive = (bool)($sortflag & core_collator::CASE_SENSITIVE);
 183         $sortflag = ($sortflag & ~core_collator::CASE_SENSITIVE);
 184         if ($sortflag != core_collator::SORT_NATURAL and $sortflag != core_collator::SORT_STRING) {
 185             $casesensitive = false;
 186         }
 187
 188         if (self::ensure_collator_available()) {
 189             if ($sortflag == core_collator::SORT_NUMERIC) {
 190                 $flag = Collator::SORT_NUMERIC;
 191
 192             } else if ($sortflag == core_collator::SORT_REGULAR) {
 193                 $flag = Collator::SORT_REGULAR;
 194
 195             } else {
 196                 $flag = Collator::SORT_STRING;
 197             }
 198
 199             if ($sortflag == core_collator::SORT_NATURAL) {
 200                 $original = $arr;
 201                 if ($sortflag == core_collator::SORT_NATURAL) {
 202                     foreach ($arr as $key => $value) {
 203                         $arr[$key] = self::naturalise((string)$value);
 204                     }
 205                 }
 206             }
 207             if ($casesensitive) {
 208                 self::$collator->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);
 209             } else {
 210                 self::$collator->setAttribute(Collator::CASE_FIRST, Collator::OFF);
 211             }
 212             $result = self::$collator->asort($arr, $flag);
 213             if ($original) {
 214                 self::restore_array($arr, $original);
 215             }
 216             return $result;
 217         }
 218
 219         // try some fallback that works at least for English
 220
 221         if ($sortflag == core_collator::SORT_NUMERIC) {
 222             return asort($arr, SORT_NUMERIC);
 223
 224         } else if ($sortflag == core_collator::SORT_REGULAR) {
 225             return asort($arr, SORT_REGULAR);
 226         }
 227
 228         if (!$casesensitive) {
 229             $original = $arr;
 230             foreach ($arr as $key => $value) {
 231                 $arr[$key] = core_text::strtolower($value);
 232             }
 233         }
 234
 235         if ($sortflag == core_collator::SORT_NATURAL) {
 236             $result = natsort($arr);
 237
 238         } else {
 239             $result = asort($arr, SORT_LOCALE_STRING);
 240         }
 241
 242         if ($original) {
 243             self::restore_array($arr, $original);
 244         }
 245
 246         return $result;
 247     }
 248
 249     /**
 250      * Locale aware sort of objects by a property in common to all objects
 251      *
 252      * @param array $objects An array of objects to sort (handled by reference)
 253      * @param string $property The property to use for comparison
 254      * @param int $sortflag One of core_collator::SORT_NUMERIC, core_collator::SORT_STRING, core_collator::SORT_NATURAL, core_collator::SORT_REGULAR
 255      *      optionally "|" core_collator::CASE_SENSITIVE
 256      * @return bool True on success
 257      */
 258     public static function asort_objects_by_property(array &$objects, $property, $sortflag = core_collator::SORT_STRING) {
 259         $original = $objects;
 260         foreach ($objects as $key => $object) {
 261             $objects[$key] = $object->$property;
 262         }
 263         $result = self::asort($objects, $sortflag);
 264         self::restore_array($objects, $original);
 265         return $result;
 266     }
 267
 268     /**
 269      * Locale aware sort of objects by a method in common to all objects
 270      *
 271      * @param array $objects An array of objects to sort (handled by reference)
 272      * @param string $method The method to call to generate a value for comparison
 273      * @param int $sortflag One of core_collator::SORT_NUMERIC, core_collator::SORT_STRING, core_collator::SORT_NATURAL, core_collator::SORT_REGULAR
 274      *      optionally "|" core_collator::CASE_SENSITIVE
 275      * @return bool True on success
 276      */
 277     public static function asort_objects_by_method(array &$objects, $method, $sortflag = core_collator::SORT_STRING) {
 278         $original = $objects;
 279         foreach ($objects as $key => $object) {
 280             $objects[$key] = $object->{$method}();
 281         }
 282         $result = self::asort($objects, $sortflag);
 283         self::restore_array($objects, $original);
 284         return $result;
 285     }
 286
 287     /**
 288      * Locale aware sort of array of arrays.
 289      *
 290      * Given an array like:
 291      * $array = array(
 292      *     array('name' => 'bravo'),
 293      *     array('name' => 'charlie'),
 294      *     array('name' => 'alpha')
 295      * );
 296      *
 297      * If you call:
 298      * core_collator::asort_array_of_arrays_by_key($array, 'name')
 299      *
 300      * You will be returned $array sorted by the name key of the subarrays. e.g.
 301      * $array = array(
 302      *     array('name' => 'alpha'),
 303      *     array('name' => 'bravo'),
 304      *     array('name' => 'charlie')
 305      * );
 306      *
 307      * @param array $array An array of objects to sort (handled by reference)
 308      * @param string $key The key to use for comparison
 309      * @param int $sortflag One of
 310      *          core_collator::SORT_NUMERIC,
 311      *          core_collator::SORT_STRING,
 312      *          core_collator::SORT_NATURAL,
 313      *          core_collator::SORT_REGULAR
 314      *      optionally "|" core_collator::CASE_SENSITIVE
 315      * @return bool True on success
 316      */
 317     public static function asort_array_of_arrays_by_key(array &$array, $key, $sortflag = core_collator::SORT_STRING) {
 318         $original = $array;
 319         foreach ($array as $initkey => $item) {
 320             $array[$initkey] = $item[$key];
 321         }
 322         $result = self::asort($array, $sortflag);
 323         self::restore_array($array, $original);
 324         return $result;
 325     }
 326
 327     /**
 328      * Locale aware sorting, the key associations are kept, keys are sorted alphabetically.
 329      *
 330      * @param array $arr array to be sorted (reference)
 331      * @param int $sortflag One of core_collator::SORT_NUMERIC, core_collator::SORT_STRING, core_collator::SORT_NATURAL, core_collator::SORT_REGULAR
 332      *      optionally "|" core_collator::CASE_SENSITIVE
 333      * @return bool True on success
 334      */
 335     public static function ksort(array &$arr, $sortflag = core_collator::SORT_STRING) {
 336         $keys = array_keys($arr);
 337         if (!self::asort($keys, $sortflag)) {
 338             return false;
 339         }
 340         // This is a bit slow, but we need to keep the references
 341         $original = $arr;
 342         $arr = array(); // Surprisingly this does not break references outside
 343         foreach ($keys as $key) {
 344             $arr[$key] = $original[$key];
 345         }
 346
 347         return true;
 348     }
 349 }