Merge branch 'w24_MDL-33635_m23_sort' of git://github.com/skodak/moodle
[moodle.git] / lib / textlib.class.php
CommitLineData
72fb21b6 1<?php
72fb21b6 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/>.
779dc9ac 16
72fb21b6 17/**
55d1f272
RT
18 * Defines string apis
19 *
78bfb562 20 * @package core
78bfb562
PS
21 * @copyright (C) 2001-3001 Eloy Lafuente (stronk7) {@link http://contiento.com}
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
72fb21b6 23 */
6aaa17c7 24
78bfb562
PS
25defined('MOODLE_INTERNAL') || die();
26
5a7e4c11 27/**
55d1f272
RT
28 * defines string api's for manipulating strings
29 *
5a7e4c11
PS
30 * This class is used to manipulate strings under Moodle 1.6 an later. As
31 * utf-8 text become mandatory a pool of safe functions under this encoding
32 * become necessary. The name of the methods is exactly the
33 * same than their PHP originals.
34 *
35 * A big part of this class acts as a wrapper over the Typo3 charset library,
36 * really a cool group of utilities to handle texts and encoding conversion.
37 *
38 * Take a look to its own copyright and license details.
72fb21b6 39 *
40 * IMPORTANT Note: Typo3 libraries always expect lowercase charsets to use 100%
41 * its capabilities so, don't forget to make the conversion
42 * from every wrapper function!
43 *
55d1f272
RT
44 * @package core
45 * @category string
5a7e4c11
PS
46 * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
47 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
72fb21b6 48 */
5a7e4c11
PS
49class textlib {
50
51 /**
55d1f272
RT
52 * Return t3lib helper class, which is used for conversion between charsets
53 *
bc5c10f6 54 * @param bool $reset
5a7e4c11
PS
55 * @return t3lib_cs
56 */
bc5c10f6 57 protected static function typo3($reset = false) {
5a7e4c11 58 static $typo3cs = null;
3b093310 59
bc5c10f6
PS
60 if ($reset) {
61 $typo3cs = null;
62 return null;
63 }
64
5a7e4c11
PS
65 if (isset($typo3cs)) {
66 return $typo3cs;
67 }
3b093310 68
5a7e4c11 69 global $CFG;
3b093310 70
5a7e4c11 71 // Required files
3b093310 72 require_once($CFG->libdir.'/typo3/class.t3lib_cs.php');
73 require_once($CFG->libdir.'/typo3/class.t3lib_div.php');
bc5c10f6
PS
74 require_once($CFG->libdir.'/typo3/interface.t3lib_singleton.php');
75 require_once($CFG->libdir.'/typo3/class.t3lib_l10n_locales.php');
3b093310 76
b25a1714
PS
77 // do not use mbstring or recode because it may return invalid results in some corner cases
78 $GLOBALS['TYPO3_CONF_VARS']['SYS']['t3lib_cs_convMethod'] = 'iconv';
79 $GLOBALS['TYPO3_CONF_VARS']['SYS']['t3lib_cs_utils'] = 'iconv';
3b093310 80
5a7e4c11 81 // Tell Typo3 we are curl enabled always (mandatory since 2.0)
850ea1ee
EL
82 $GLOBALS['TYPO3_CONF_VARS']['SYS']['curlUse'] = '1';
83
5a7e4c11
PS
84 // And this directory must exist to allow Typo to cache conversion
85 // tables when using internal functions
af9b1444 86 make_temp_directory('typo3temp/cs');
3b093310 87
5a7e4c11 88 // Make sure typo is using our dir permissions
8d3bf3e0
PS
89 $GLOBALS['TYPO3_CONF_VARS']['BE']['folderCreateMask'] = decoct($CFG->directorypermissions);
90
5a7e4c11 91 // Default mask for Typo
3b093310 92 $GLOBALS['TYPO3_CONF_VARS']['BE']['fileCreateMask'] = $CFG->directorypermissions;
93
5a7e4c11
PS
94 // This full path constants must be defined too, transforming backslashes
95 // to forward slashed because Typo3 requires it.
bc5c10f6
PS
96 if (!defined('PATH_t3lib')) {
97 define('PATH_t3lib', str_replace('\\','/',$CFG->libdir.'/typo3/'));
98 define('PATH_typo3', str_replace('\\','/',$CFG->libdir.'/typo3/'));
99 define('PATH_site', str_replace('\\','/',$CFG->tempdir.'/'));
100 define('TYPO3_OS', stristr(PHP_OS,'win')&&!stristr(PHP_OS,'darwin')?'WIN':'');
101 }
3b093310 102
5a7e4c11 103 $typo3cs = new t3lib_cs();
779dc9ac 104
5a7e4c11
PS
105 return $typo3cs;
106 }
779dc9ac 107
bc5c10f6
PS
108 /**
109 * Reset internal textlib caches.
110 * @static
111 */
112 public static function reset_caches() {
113 self::typo3(true);
114 }
115
e4023a4c 116 /**
5a7e4c11
PS
117 * Standardise charset name
118 *
119 * Please note it does not mean the returned charset is actually supported.
779dc9ac 120 *
5a7e4c11
PS
121 * @static
122 * @param string $charset raw charset name
123 * @return string normalised lowercase charset name
779dc9ac 124 */
5a7e4c11 125 public static function parse_charset($charset) {
5a7e4c11 126 $charset = strtolower($charset);
5a7e4c11 127
a7a20faf
PS
128 // shortcuts so that we do not have to load typo3 on every page
129
130 if ($charset === 'utf8' or $charset === 'utf-8') {
131 return 'utf-8';
132 }
133
134 if (preg_match('/^(cp|win|windows)-?(12[0-9]{2})$/', $charset, $matches)) {
135 return 'windows-'.$matches[2];
136 }
137
138 if (preg_match('/^iso-8859-[0-9]+$/', $charset, $matches)) {
139 return $charset;
5a7e4c11
PS
140 }
141
b25a1714
PS
142 if ($charset === 'euc-jp') {
143 return 'euc-jp';
144 }
145 if ($charset === 'iso-2022-jp') {
146 return 'iso-2022-jp';
147 }
148 if ($charset === 'shift-jis' or $charset === 'shift_jis') {
149 return 'shift_jis';
150 }
151 if ($charset === 'gb2312') {
152 return 'gb2312';
153 }
154 if ($charset === 'gb18030') {
155 return 'gb18030';
156 }
157
5a7e4c11
PS
158 // fallback to typo3
159 return self::typo3()->parse_charset($charset);
779dc9ac 160 }
161
e4023a4c 162 /**
2e0ecae4
PS
163 * Converts the text between different encodings. It uses iconv extension with //TRANSLIT parameter,
164 * falls back to typo3.
5a7e4c11
PS
165 * Returns false if fails.
166 *
167 * @param string $text
168 * @param string $fromCS source encoding
169 * @param string $toCS result encoding
a7a20faf 170 * @return string|bool converted string or false on error
e4023a4c 171 */
5a7e4c11
PS
172 public static function convert($text, $fromCS, $toCS='utf-8') {
173 $fromCS = self::parse_charset($fromCS);
174 $toCS = self::parse_charset($toCS);
175
a7a20faf
PS
176 $text = (string)$text; // we can work only with strings
177
178 if ($text === '') {
179 return '';
180 }
181
182 $result = iconv($fromCS, $toCS.'//TRANSLIT', $text);
183
184 if ($result === false or $result === '') {
2e0ecae4
PS
185 // note: iconv is prone to return empty string when invalid char encountered, or false if encoding unsupported
186 $oldlevel = error_reporting(E_PARSE);
b2948766 187 $result = self::typo3()->conv((string)$text, $fromCS, $toCS);
2e0ecae4 188 error_reporting($oldlevel);
a7a20faf
PS
189 }
190
191 return $result;
779dc9ac 192 }
193
e4023a4c 194 /**
ca281c51 195 * Multibyte safe substr() function, uses mbstring or iconv for UTF-8, falls back to typo3.
5a7e4c11 196 *
55d1f272 197 * @param string $text string to truncate
5a7e4c11 198 * @param int $start negative value means from end
55d1f272 199 * @param int $len maximum length of characters beginning from start
5a7e4c11 200 * @param string $charset encoding of the text
55d1f272 201 * @return string portion of string specified by the $start and $len
e4023a4c 202 */
5a7e4c11
PS
203 public static function substr($text, $start, $len=null, $charset='utf-8') {
204 $charset = self::parse_charset($charset);
205
2e0ecae4 206 if ($charset === 'utf-8') {
ca281c51
PS
207 if (function_exists('mb_substr')) {
208 // this is much faster than iconv - see MDL-31142
209 if ($len === null) {
210 $oldcharset = mb_internal_encoding();
211 mb_internal_encoding('UTF-8');
212 $result = mb_substr($text, $start);
213 mb_internal_encoding($oldcharset);
214 return $result;
215 } else {
216 return mb_substr($text, $start, $len, 'UTF-8');
217 }
218
219 } else {
220 if ($len === null) {
221 $len = iconv_strlen($text, 'UTF-8');
222 }
223 return iconv_substr($text, $start, $len, 'UTF-8');
224 }
a7a20faf
PS
225 }
226
2e0ecae4 227 $oldlevel = error_reporting(E_PARSE);
ca281c51 228 if ($len === null) {
b2948766 229 $result = self::typo3()->substr($charset, (string)$text, $start);
ca281c51 230 } else {
b2948766 231 $result = self::typo3()->substr($charset, (string)$text, $start, $len);
ca281c51 232 }
2e0ecae4
PS
233 error_reporting($oldlevel);
234
a7a20faf 235 return $result;
779dc9ac 236 }
237
e4023a4c 238 /**
ca281c51 239 * Multibyte safe strlen() function, uses mbstring or iconv for UTF-8, falls back to typo3.
5a7e4c11 240 *
55d1f272 241 * @param string $text input string
5a7e4c11
PS
242 * @param string $charset encoding of the text
243 * @return int number of characters
e4023a4c 244 */
5a7e4c11
PS
245 public static function strlen($text, $charset='utf-8') {
246 $charset = self::parse_charset($charset);
247
2e0ecae4 248 if ($charset === 'utf-8') {
ca281c51
PS
249 if (function_exists('mb_strlen')) {
250 return mb_strlen($text, 'UTF-8');
251 } else {
252 return iconv_strlen($text, 'UTF-8');
253 }
a7a20faf
PS
254 }
255
2e0ecae4 256 $oldlevel = error_reporting(E_PARSE);
b2948766 257 $result = self::typo3()->strlen($charset, (string)$text);
2e0ecae4
PS
258 error_reporting($oldlevel);
259
a7a20faf 260 return $result;
779dc9ac 261 }
262
e4023a4c 263 /**
2e0ecae4 264 * Multibyte safe strtolower() function, uses mbstring, falls back to typo3.
5a7e4c11 265 *
55d1f272 266 * @param string $text input string
5a7e4c11
PS
267 * @param string $charset encoding of the text (may not work for all encodings)
268 * @return string lower case text
e4023a4c 269 */
5a7e4c11
PS
270 public static function strtolower($text, $charset='utf-8') {
271 $charset = self::parse_charset($charset);
272
2e0ecae4 273 if ($charset === 'utf-8' and function_exists('mb_strtolower')) {
ca281c51 274 return mb_strtolower($text, 'UTF-8');
5a7e4c11
PS
275 }
276
779dc9ac 277 $oldlevel = error_reporting(E_PARSE);
b2948766 278 $result = self::typo3()->conv_case($charset, (string)$text, 'toLower');
779dc9ac 279 error_reporting($oldlevel);
2e0ecae4 280
779dc9ac 281 return $result;
282 }
283
e4023a4c 284 /**
2e0ecae4 285 * Multibyte safe strtoupper() function, uses mbstring, falls back to typo3.
5a7e4c11 286 *
55d1f272 287 * @param string $text input string
5a7e4c11
PS
288 * @param string $charset encoding of the text (may not work for all encodings)
289 * @return string upper case text
e4023a4c 290 */
5a7e4c11
PS
291 public static function strtoupper($text, $charset='utf-8') {
292 $charset = self::parse_charset($charset);
293
2e0ecae4 294 if ($charset === 'utf-8' and function_exists('mb_strtoupper')) {
ca281c51 295 return mb_strtoupper($text, 'UTF-8');
5a7e4c11
PS
296 }
297
779dc9ac 298 $oldlevel = error_reporting(E_PARSE);
b2948766 299 $result = self::typo3()->conv_case($charset, (string)$text, 'toUpper');
779dc9ac 300 error_reporting($oldlevel);
2e0ecae4 301
779dc9ac 302 return $result;
303 }
304
e4023a4c 305 /**
55d1f272 306 * Find the position of the first occurrence of a substring in a string.
ca281c51 307 * UTF-8 ONLY safe strpos(), uses mbstring, falls back to iconv.
5a7e4c11 308 *
55d1f272
RT
309 * @param string $haystack the string to search in
310 * @param string $needle one or more charachters to search for
311 * @param int $offset offset from begining of string
312 * @return int the numeric position of the first occurrence of needle in haystack.
e4023a4c 313 */
5a7e4c11 314 public static function strpos($haystack, $needle, $offset=0) {
ca281c51
PS
315 if (function_exists('mb_strpos')) {
316 return mb_strpos($haystack, $needle, $offset, 'UTF-8');
317 } else {
318 return iconv_strpos($haystack, $needle, $offset, 'UTF-8');
319 }
779dc9ac 320 }
321
e4023a4c 322 /**
55d1f272 323 * Find the position of the last occurrence of a substring in a string
ca281c51 324 * UTF-8 ONLY safe strrpos(), uses mbstring, falls back to iconv.
5a7e4c11 325 *
55d1f272
RT
326 * @param string $haystack the string to search in
327 * @param string $needle one or more charachters to search for
328 * @return int the numeric position of the last occurrence of needle in haystack
e4023a4c 329 */
5a7e4c11 330 public static function strrpos($haystack, $needle) {
ca281c51
PS
331 if (function_exists('mb_strpos')) {
332 return mb_strrpos($haystack, $needle, null, 'UTF-8');
333 } else {
334 return iconv_strrpos($haystack, $needle, 'UTF-8');
335 }
779dc9ac 336 }
337
e4023a4c 338 /**
339 * Try to convert upper unicode characters to plain ascii,
5a7e4c11
PS
340 * the returned string may contain unconverted unicode characters.
341 *
55d1f272 342 * @param string $text input string
5a7e4c11 343 * @param string $charset encoding of the text
55d1f272 344 * @return string converted ascii string
e4023a4c 345 */
5a7e4c11
PS
346 public static function specialtoascii($text, $charset='utf-8') {
347 $charset = self::parse_charset($charset);
e05fc498 348 $oldlevel = error_reporting(E_PARSE);
b2948766 349 $result = self::typo3()->specCharsToASCII($charset, (string)$text);
e05fc498 350 error_reporting($oldlevel);
351 return $result;
46b81130 352 }
353
e4023a4c 354 /**
355 * Generate a correct base64 encoded header to be used in MIME mail messages.
3ec5ec15 356 * This function seems to be 100% compliant with RFC1342. Credits go to:
357 * paravoid (http://www.php.net/manual/en/function.mb-encode-mimeheader.php#60283).
5a7e4c11 358 *
55d1f272 359 * @param string $text input string
5a7e4c11 360 * @param string $charset encoding of the text
55d1f272 361 * @return string base64 encoded header
3ec5ec15 362 */
5a7e4c11 363 public static function encode_mimeheader($text, $charset='utf-8') {
53146827 364 if (empty($text)) {
365 return (string)$text;
366 }
5a7e4c11
PS
367 // Normalize charset
368 $charset = self::parse_charset($charset);
369 // If the text is pure ASCII, we don't need to encode it
370 if (self::convert($text, $charset, 'ascii') == $text) {
c539d622 371 return $text;
372 }
5a7e4c11
PS
373 // Although RFC says that line feed should be \r\n, it seems that
374 // some mailers double convert \r, so we are going to use \n alone
3ec5ec15 375 $linefeed="\n";
5a7e4c11 376 // Define start and end of every chunk
3ec5ec15 377 $start = "=?$charset?B?";
378 $end = "?=";
5a7e4c11 379 // Accumulate results
3ec5ec15 380 $encoded = '';
5a7e4c11 381 // Max line length is 75 (including start and end)
3ec5ec15 382 $length = 75 - strlen($start) - strlen($end);
5a7e4c11
PS
383 // Multi-byte ratio
384 $multilength = self::strlen($text, $charset);
385 // Detect if strlen and friends supported
53146827 386 if ($multilength === false) {
387 if ($charset == 'GB18030' or $charset == 'gb18030') {
388 while (strlen($text)) {
389 // try to encode first 22 chars - we expect most chars are two bytes long
390 if (preg_match('/^(([\x00-\x7f])|([\x81-\xfe][\x40-\x7e])|([\x81-\xfe][\x80-\xfe])|([\x81-\xfe][\x30-\x39]..)){1,22}/m', $text, $matches)) {
391 $chunk = $matches[0];
392 $encchunk = base64_encode($chunk);
393 if (strlen($encchunk) > $length) {
394 // find first 11 chars - each char in 4 bytes - worst case scenario
e8515774 395 preg_match('/^(([\x00-\x7f])|([\x81-\xfe][\x40-\x7e])|([\x81-\xfe][\x80-\xfe])|([\x81-\xfe][\x30-\x39]..)){1,11}/m', $text, $matches);
53146827 396 $chunk = $matches[0];
397 $encchunk = base64_encode($chunk);
398 }
399 $text = substr($text, strlen($chunk));
400 $encoded .= ' '.$start.$encchunk.$end.$linefeed;
401 } else {
402 break;
403 }
404 }
405 $encoded = trim($encoded);
e8515774 406 return $encoded;
53146827 407 } else {
408 return false;
409 }
410 }
411 $ratio = $multilength / strlen($text);
5a7e4c11 412 // Base64 ratio
3ec5ec15 413 $magic = $avglength = floor(3 * $length * $ratio / 4);
5a7e4c11 414 // basic infinite loop protection
684663f5 415 $maxiterations = strlen($text)*2;
e8515774 416 $iteration = 0;
5a7e4c11 417 // Iterate over the string in magic chunks
53146827 418 for ($i=0; $i <= $multilength; $i+=$magic) {
684663f5 419 if ($iteration++ > $maxiterations) {
e8515774 420 return false; // probably infinite loop
421 }
3ec5ec15 422 $magic = $avglength;
423 $offset = 0;
5a7e4c11 424 // Ensure the chunk fits in length, reducing magic if necessary
3ec5ec15 425 do {
426 $magic -= $offset;
5a7e4c11 427 $chunk = self::substr($text, $i, $magic, $charset);
3ec5ec15 428 $chunk = base64_encode($chunk);
429 $offset++;
430 } while (strlen($chunk) > $length);
5a7e4c11 431 // This chunk doesn't break any multi-byte char. Use it.
3ec5ec15 432 if ($chunk)
433 $encoded .= ' '.$start.$chunk.$end.$linefeed;
434 }
5a7e4c11 435 // Strip the first space and the last linefeed
3ec5ec15 436 $encoded = substr($encoded, 1, -strlen($linefeed));
437
438 return $encoded;
439 }
9c1cd39d 440
4e2cb0e3 441 /**
442 * Converts all the numeric entities &#nnnn; or &#xnnn; to UTF-8
443 * Original from laurynas dot butkus at gmail at:
444 * http://php.net/manual/en/function.html-entity-decode.php#75153
445 * with some custom mods to provide more functionality
e8515774 446 *
55d1f272
RT
447 * @param string $str input string
448 * @param boolean $htmlent convert also html entities (defaults to true)
449 * @return string encoded UTF-8 string
4e2cb0e3 450 *
451 * NOTE: we could have used typo3 entities_to_utf8() here
452 * but the direct alternative used runs 400% quicker
453 * and uses 0.5Mb less memory, so, let's use it
5a7e4c11 454 * (tested against 10^6 conversions)
4e2cb0e3 455 */
5a7e4c11
PS
456 public static function entities_to_utf8($str, $htmlent=true) {
457 static $trans_tbl; // Going to use static transliteration table
4e2cb0e3 458
5a7e4c11 459 // Replace numeric entities
4e2cb0e3 460 $result = preg_replace('~&#x([0-9a-f]+);~ei', 'textlib::code2utf8(hexdec("\\1"))', $str);
461 $result = preg_replace('~&#([0-9]+);~e', 'textlib::code2utf8(\\1)', $result);
462
5a7e4c11 463 // Replace literal entities (if desired)
4e2cb0e3 464 if ($htmlent) {
5a7e4c11 465 // Generate/create $trans_tbl
4e2cb0e3 466 if (!isset($trans_tbl)) {
467 $trans_tbl = array();
468 foreach (get_html_translation_table(HTML_ENTITIES) as $val=>$key) {
469 $trans_tbl[$key] = utf8_encode($val);
470 }
471 }
472 $result = strtr($result, $trans_tbl);
473 }
5a7e4c11 474 // Return utf8-ised string
4e2cb0e3 475 return $result;
476 }
477
9c1cd39d 478 /**
479 * Converts all Unicode chars > 127 to numeric entities &#nnnn; or &#xnnn;.
480 *
55d1f272
RT
481 * @param string $str input string
482 * @param boolean $dec output decadic only number entities
483 * @param boolean $nonnum remove all non-numeric entities
484 * @return string converted string
9c1cd39d 485 */
5a7e4c11
PS
486 public static function utf8_to_entities($str, $dec=false, $nonnum=false) {
487 // Avoid some notices from Typo3 code
9c1cd39d 488 $oldlevel = error_reporting(E_PARSE);
489 if ($nonnum) {
b2948766 490 $str = self::typo3()->entities_to_utf8((string)$str, true);
9c1cd39d 491 }
b2948766 492 $result = self::typo3()->utf8_to_entities((string)$str);
9c1cd39d 493 if ($dec) {
494 $result = preg_replace('/&#x([0-9a-f]+);/ie', "'&#'.hexdec('$1').';'", $result);
495 }
5a7e4c11 496 // Restore original debug level
9c1cd39d 497 error_reporting($oldlevel);
498 return $result;
499 }
500
77b4d4be 501 /**
55d1f272 502 * Removes the BOM from unicode string {@link http://unicode.org/faq/utf_bom.html}
5a7e4c11 503 *
55d1f272 504 * @param string $str input string
5a7e4c11 505 * @return string
77b4d4be 506 */
5a7e4c11 507 public static function trim_utf8_bom($str) {
77b4d4be 508 $bom = "\xef\xbb\xbf";
509 if (strpos($str, $bom) === 0) {
510 return substr($str, strlen($bom));
511 }
512 return $str;
513 }
e8515774 514
4d40aa14 515 /**
516 * Returns encoding options for select boxes, utf-8 and platform encoding first
55d1f272 517 *
e8515774 518 * @return array encodings
4d40aa14 519 */
5a7e4c11 520 public static function get_encodings() {
4d40aa14 521 $encodings = array();
522 $encodings['UTF-8'] = 'UTF-8';
bf69b06d 523 $winenc = strtoupper(get_string('localewincharset', 'langconfig'));
4d40aa14 524 if ($winenc != '') {
525 $encodings[$winenc] = $winenc;
526 }
bf69b06d 527 $nixenc = strtoupper(get_string('oldcharset', 'langconfig'));
4d40aa14 528 $encodings[$nixenc] = $nixenc;
e8515774 529
5a7e4c11 530 foreach (self::typo3()->synonyms as $enc) {
4d40aa14 531 $enc = strtoupper($enc);
532 $encodings[$enc] = $enc;
533 }
534 return $encodings;
535 }
4e2cb0e3 536
537 /**
e8515774 538 * Returns the utf8 string corresponding to the unicode value
4e2cb0e3 539 * (from php.net, courtesy - romans@void.lv)
e8515774 540 *
4e2cb0e3 541 * @param int $num one unicode value
542 * @return string the UTF-8 char corresponding to the unicode value
543 */
5a7e4c11 544 public static function code2utf8($num) {
4e2cb0e3 545 if ($num < 128) {
546 return chr($num);
547 }
548 if ($num < 2048) {
549 return chr(($num >> 6) + 192) . chr(($num & 63) + 128);
550 }
551 if ($num < 65536) {
552 return chr(($num >> 12) + 224) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
553 }
554 if ($num < 2097152) {
555 return chr(($num >> 18) + 240) . chr((($num >> 12) & 63) + 128) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
556 }
557 return '';
558 }
e8515774 559
560 /**
561 * Makes first letter of each word capital - words must be separated by spaces.
562 * Use with care, this function does not work properly in many locales!!!
5a7e4c11 563 *
55d1f272 564 * @param string $text input string
e8515774 565 * @return string
566 */
5a7e4c11 567 public static function strtotitle($text) {
e8515774 568 if (empty($text)) {
569 return $text;
570 }
571
572 if (function_exists('mb_convert_case')) {
5a7e4c11 573 return mb_convert_case($text, MB_CASE_TITLE, 'UTF-8');
e8515774 574 }
575
5a7e4c11 576 $text = self::strtolower($text);
e8515774 577 $words = explode(' ', $text);
578 foreach ($words as $i=>$word) {
5a7e4c11 579 $length = self::strlen($word);
e8515774 580 if (!$length) {
581 continue;
582
583 } else if ($length == 1) {
5a7e4c11 584 $words[$i] = self::strtoupper($word);
e8515774 585
586 } else {
5a7e4c11
PS
587 $letter = self::substr($word, 0, 1);
588 $letter = self::strtoupper($letter);
589 $rest = self::substr($word, 1);
e8515774 590 $words[$i] = $letter.$rest;
591 }
592 }
593 return implode(' ', $words);
594 }
878bcc7f
PS
595
596 /**
597 * Locale aware sorting, the key associations are kept, values are sorted alphabetically.
5a7e4c11 598 *
d609d962
SH
599 * @param array $arr array to be sorted (reference)
600 * @param int $sortflag One of Collator::SORT_REGULAR, Collator::SORT_NUMERIC, Collator::SORT_STRING
601 * @return void modifies parameter
602 */
603 public static function asort(array &$arr, $sortflag = null) {
604 debugging('textlib::asort has been superseeded by collatorlib::asort please upgrade your code to use that', DEBUG_DEVELOPER);
605 collatorlib::asort($arr, $sortflag);
606 }
607}
608
21282685 609
d609d962
SH
610/**
611 * A collator class with static methods that can be used for sorting.
612 *
55d1f272 613 * @package core
d609d962 614 * @copyright 2011 Sam Hemelryk
21282685 615 * 2012 Petr Skoda
d609d962
SH
616 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
617 */
21282685
PS
618class collatorlib {
619 /** @const compare items as strings, equivalent to Collator::SORT_REGULAR */
620 const SORT_REGULAR = 0;
621
622 /** @const compare items as strings, equivalent to Collator::SORT_STRING */
623 const SORT_STRING = 1;
624
625 /** @const compare items as numbers, equivalent to Collator::SORT_NUMERIC */
626 const SORT_NUMERIC = 2;
627
628 /** @const compare items like natsort(), equivalent to SORT_NATURAL */
629 const SORT_NATURAL = 6;
630
631 /** @const do not ignore case when sorting, use bitwise "|" with SORT_NATURAL or SORT_STRING, equivalent to Collator::UPPER_FIRST */
632 const CASE_SENSITIVE = 64;
d609d962
SH
633
634 /** @var Collator|false|null **/
635 protected static $collator = null;
636
637 /** @var string|null The locale that was used in instantiating the current collator **/
638 protected static $locale = null;
639
21282685
PS
640 /**
641 * Prevent class instances, all methods are static.
642 */
643 private function __construct() {
644 }
645
d609d962
SH
646 /**
647 * Ensures that a collator is available and created
648 *
649 * @return bool Returns true if collation is available and ready
650 */
651 protected static function ensure_collator_available() {
d609d962
SH
652 $locale = get_string('locale', 'langconfig');
653 if (is_null(self::$collator) || $locale != self::$locale) {
654 self::$collator = false;
655 self::$locale = $locale;
656 if (class_exists('Collator', false)) {
657 $collator = new Collator($locale);
658 if (!empty($collator) && $collator instanceof Collator) {
659 // Check for non fatal error messages. This has to be done immediately
7aacd75b
EL
660 // after instantiation as any further calls to collation will cause
661 // it to reset to 0 again (or another error code if one occurred)
d609d962 662 $errorcode = $collator->getErrorCode();
20079ee7 663 $errormessage = $collator->getErrorMessage();
7aacd75b 664 // Check for an error code, 0 means no error occurred
d609d962
SH
665 if ($errorcode !== 0) {
666 // Get the actual locale being used, e.g. en, he, zh
667 $localeinuse = $collator->getLocale(Locale::ACTUAL_LOCALE);
7aacd75b
EL
668 // Check for the common fallback warning error codes. If this occurred
669 // there is normally little to worry about:
670 // - U_USING_DEFAULT_WARNING (127) - default fallback locale used (pt => UCA)
671 // - U_USING_FALLBACK_WARNING (128) - fallback locale used (de_CH => de)
672 // (UCA: Unicode Collation Algorithm http://unicode.org/reports/tr10/)
673 if ($errorcode === -127 || $errorcode === -128) {
674 // Check if the locale in use is UCA default one ('root') or
675 // if it is anything like the locale we asked for
676 if ($localeinuse !== 'root' && strpos($locale, $localeinuse) !== 0) {
d609d962 677 // The locale we asked for is completely different to the locale
7aacd75b
EL
678 // we have received, let the user know via debugging
679 debugging('Invalid locale: "' . $locale . '", with warning (not fatal) "' . $errormessage .
680 '", falling back to "' . $collator->getLocale(Locale::VALID_LOCALE) . '"');
d609d962
SH
681 } else {
682 // Nothing to do here, this is expected!
683 // The Moodle locale setting isn't what the collator expected but
684 // it is smart enough to match the first characters of our locale
7aacd75b 685 // to find the correct locale or to use UCA collation
d609d962
SH
686 }
687 } else {
21282685 688 // We've received some other sort of non fatal warning - let the
d609d962 689 // user know about it via debugging.
7aacd75b
EL
690 debugging('Problem with locale: "' . $locale . '", with message "' . $errormessage .
691 '", falling back to "' . $collator->getLocale(Locale::VALID_LOCALE) . '"');
d609d962
SH
692 }
693 }
7aacd75b 694 // Store the collator object now that we can be sure it is in a workable condition
d609d962
SH
695 self::$collator = $collator;
696 } else {
7aacd75b
EL
697 // Fatal error while trying to instantiate the collator... something went wrong
698 debugging('Error instantiating collator for locale: "' . $locale . '", with error [' .
699 intl_get_error_code() . '] ' . intl_get_error_message($collator));
d609d962
SH
700 }
701 }
702 }
703 return (self::$collator instanceof Collator);
704 }
705
706 /**
21282685
PS
707 * Restore array contents keeping new keys.
708 * @static
709 * @param array $arr
710 * @param array $original
711 * @return void modifies $arr
878bcc7f 712 */
21282685
PS
713 protected static function restore_array(array &$arr, array &$original) {
714 foreach ($arr as $key => $ignored) {
715 $arr[$key] = $original[$key];
878bcc7f 716 }
878bcc7f 717 }
d609d962
SH
718
719 /**
21282685
PS
720 * Normalise numbers in strings for natural sorting comparisons.
721 * @static
722 * @param string $string
723 * @return string string with normalised numbers
d609d962 724 */
21282685
PS
725 protected static function naturalise($string) {
726 return preg_replace_callback('/[0-9]+/', array('collatorlib', 'callback_naturalise'), $string);
d609d962
SH
727 }
728
729 /**
21282685
PS
730 * @internal
731 * @static
732 * @param array $matches
733 * @return string
d609d962 734 */
21282685
PS
735 public static function callback_naturalise($matches) {
736 return str_pad($matches[0], 20, '0', STR_PAD_LEFT);
d609d962
SH
737 }
738
739 /**
21282685 740 * Locale aware sorting, the key associations are kept, values are sorted alphabetically.
d609d962 741 *
21282685
PS
742 * @param array $arr array to be sorted (reference)
743 * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
744 * optionally "|" collatorlib::CASE_SENSITIVE
d609d962
SH
745 * @return bool True on success
746 */
21282685
PS
747 public static function asort(array &$arr, $sortflag = collatorlib::SORT_STRING) {
748 if (empty($arr)) {
749 // nothing to do
750 return true;
751 }
d609d962 752
21282685 753 $original = null;
d609d962 754
21282685
PS
755 $casesensitive = (bool)($sortflag & collatorlib::CASE_SENSITIVE);
756 $sortflag = ($sortflag & ~collatorlib::CASE_SENSITIVE);
757 if ($sortflag != collatorlib::SORT_NATURAL and $sortflag != collatorlib::SORT_STRING) {
758 $casesensitive = false;
759 }
d609d962 760
21282685
PS
761 if (self::ensure_collator_available()) {
762 if ($sortflag == collatorlib::SORT_NUMERIC) {
763 $flag = Collator::SORT_NUMERIC;
d609d962 764
21282685
PS
765 } else if ($sortflag == collatorlib::SORT_REGULAR) {
766 $flag = Collator::SORT_REGULAR;
d609d962 767
21282685
PS
768 } else {
769 $flag = Collator::SORT_STRING;
770 }
d609d962 771
21282685
PS
772 if ($sortflag == collatorlib::SORT_NATURAL) {
773 $original = $arr;
774 if ($sortflag == collatorlib::SORT_NATURAL) {
775 foreach ($arr as $key => $value) {
776 $arr[$key] = self::naturalise((string)$value);
777 }
778 }
779 }
780 if ($casesensitive) {
781 self::$collator->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);
782 } else {
783 self::$collator->setAttribute(Collator::CASE_FIRST, Collator::OFF);
784 }
785 $result = self::$collator->asort($arr, $flag);
786 if ($original) {
787 self::restore_array($arr, $original);
788 }
789 return $result;
790 }
791
792 // try some fallback that works at least for English
793
794 if ($sortflag == collatorlib::SORT_NUMERIC) {
795 return asort($arr, SORT_NUMERIC);
796
797 } else if ($sortflag == collatorlib::SORT_REGULAR) {
798 return asort($arr, SORT_REGULAR);
799 }
800
801 if (!$casesensitive) {
802 $original = $arr;
803 foreach ($arr as $key => $value) {
804 $arr[$key] = textlib::strtolower($value);
805 }
806 }
807
808 if ($sortflag == collatorlib::SORT_NATURAL) {
809 $result = natsort($arr);
810
811 } else {
812 $result = asort($arr, SORT_LOCALE_STRING);
813 }
814
815 if ($original) {
816 self::restore_array($arr, $original);
817 }
d609d962 818
21282685
PS
819 return $result;
820 }
d609d962
SH
821
822 /**
21282685 823 * Locale aware sort of objects by a property in common to all objects
55d1f272 824 *
21282685
PS
825 * @param array $objects An array of objects to sort (handled by reference)
826 * @param string $property The property to use for comparison
827 * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
828 * optionally "|" collatorlib::CASE_SENSITIVE
829 * @return bool True on success
d609d962 830 */
21282685
PS
831 public static function asort_objects_by_property(array &$objects, $property, $sortflag = collatorlib::SORT_STRING) {
832 $original = $objects;
833 foreach ($objects as $key => $object) {
834 $objects[$key] = $object->$property;
835 }
836 $result = self::asort($objects, $sortflag);
837 self::restore_array($objects, $original);
838 return $result;
d609d962
SH
839 }
840
841 /**
21282685 842 * Locale aware sort of objects by a method in common to all objects
d609d962 843 *
21282685
PS
844 * @param array $objects An array of objects to sort (handled by reference)
845 * @param string $method The method to call to generate a value for comparison
846 * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
847 * optionally "|" collatorlib::CASE_SENSITIVE
848 * @return bool True on success
d609d962 849 */
21282685
PS
850 public static function asort_objects_by_method(array &$objects, $method, $sortflag = collatorlib::SORT_STRING) {
851 $original = $objects;
852 foreach ($objects as $key => $object) {
853 $objects[$key] = $object->{$method}();
854 }
855 $result = self::asort($objects, $sortflag);
856 self::restore_array($objects, $original);
857 return $result;
d609d962 858 }
b71d0b43
PS
859
860 /**
861 * Locale aware sorting, the key associations are kept, keys are sorted alphabetically.
862 *
863 * @param array $arr array to be sorted (reference)
864 * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
865 * optionally "|" collatorlib::CASE_SENSITIVE
866 * @return bool True on success
867 */
868 public static function ksort(array &$arr, $sortflag = collatorlib::SORT_STRING) {
869 $keys = array_keys($arr);
870 if (!self::asort($keys, $sortflag)) {
871 return false;
872 }
873 // This is a bit slow, but we need to keep the references
874 $original = $arr;
bc53b4e9 875 $arr = array(); // Surprisingly this does not break references outside
b71d0b43
PS
876 foreach ($keys as $key) {
877 $arr[$key] = $original[$key];
878 }
879
880 return true;
881 }
20079ee7 882}
b71d0b43 883