[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  * @version        $Id: string.php 14401 2010-01-26 14:10:00Z louis $
   4  * @package        Joomla.Framework
   5  * @subpackage    Utilities
   6  * @copyright    Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
   7  * @license        GNU/GPL, see LICENSE.php
   8  * Joomla! is free software. This version may have been modified pursuant
   9  * to the GNU General Public License, and as distributed it includes or
  10  * is derivative of works licensed under the GNU General Public License or
  11  * other free or open source software licenses.
  12  * See COPYRIGHT.php for copyright notices and details.
  13  */
  14  
  15  // Check to ensure this file is within the rest of the framework
  16  defined('JPATH_BASE') or die();
  17  
  18  /**
  19   * PHP mbstring and iconv local configuration
  20   */
  21  // check if mbstring extension is loaded and attempt to load it if not present except for windows
  22  if (extension_loaded('mbstring') || ((!strtoupper(substr(PHP_OS, 0, 3)) === 'WIN' && dl('mbstring.so')))) {
  23      //Make sure to surpress the output in case ini_set is disabled
  24      @ini_set('mbstring.internal_encoding', 'UTF-8');
  25      @ini_set('mbstring.http_input', 'UTF-8');
  26      @ini_set('mbstring.http_output', 'UTF-8');
  27  }
  28  
  29  // same for iconv
  30  if (function_exists('iconv') || ((!strtoupper(substr(PHP_OS, 0, 3)) === 'WIN' && dl('iconv.so')))) {
  31         // these are settings that can be set inside code
  32      iconv_set_encoding("internal_encoding", "UTF-8");
  33      iconv_set_encoding("input_encoding", "UTF-8");
  34      iconv_set_encoding("output_encoding", "UTF-8");
  35  }
  36  
  37  /**
  38   * Include the utf8 package
  39   */
  40  require_once(JPATH_LIBRARIES.DS.'phputf8'.DS.'utf8.php');
  41  
  42  /**
  43   * String handling class for utf-8 data
  44   * Wraps the phputf8 library
  45   * All functions assume the validity of utf-8 strings.
  46   *
  47   * @static
  48   * @package     Joomla.Framework
  49   * @subpackage    Utilities
  50   * @since        1.5
  51   */
  52  class JString
  53  {
  54      /**
  55       * UTF-8 aware alternative to strpos
  56       * Find position of first occurrence of a string
  57       *
  58       * @static
  59       * @access public
  60       * @param $str - string String being examined
  61       * @param $search - string String being searced for
  62       * @param $offset - int Optional, specifies the position from which the search should be performed
  63       * @return mixed Number of characters before the first match or FALSE on failure
  64       * @see http://www.php.net/strpos
  65       */
  66  	function strpos($str, $search, $offset = FALSE)
  67      {
  68          if ( $offset === FALSE ) {
  69              return utf8_strpos($str, $search);
  70          } else {
  71              return utf8_strpos($str, $search, $offset);
  72          }
  73      }
  74  
  75      /**
  76       * UTF-8 aware alternative to strrpos
  77       * Finds position of last occurrence of a string
  78       *
  79       * @static
  80       * @access public
  81       * @param $str - string String being examined
  82       * @param $search - string String being searced for
  83       * @return mixed Number of characters before the last match or FALSE on failure
  84       * @see http://www.php.net/strrpos
  85       */
  86  	function strrpos($str, $search){
  87          return utf8_strrpos($str, $search);
  88      }
  89  
  90      /**
  91       * UTF-8 aware alternative to substr
  92       * Return part of a string given character offset (and optionally length)
  93       *
  94       * @static
  95       * @access public
  96       * @param string
  97       * @param integer number of UTF-8 characters offset (from left)
  98       * @param integer (optional) length in UTF-8 characters from offset
  99       * @return mixed string or FALSE if failure
 100       * @see http://www.php.net/substr
 101       */
 102  	function substr($str, $offset, $length = FALSE)
 103      {
 104          if ( $length === FALSE ) {
 105              return utf8_substr($str, $offset);
 106          } else {
 107              return utf8_substr($str, $offset, $length);
 108          }
 109      }
 110  
 111      /**
 112       * UTF-8 aware alternative to strtlower
 113       * Make a string lowercase
 114       * Note: The concept of a characters "case" only exists is some alphabets
 115       * such as Latin, Greek, Cyrillic, Armenian and archaic Georgian - it does
 116       * not exist in the Chinese alphabet, for example. See Unicode Standard
 117       * Annex #21: Case Mappings
 118       *
 119       * @access public
 120       * @param string
 121       * @return mixed either string in lowercase or FALSE is UTF-8 invalid
 122       * @see http://www.php.net/strtolower
 123       */
 124  	function strtolower($str){
 125          return utf8_strtolower($str);
 126      }
 127  
 128      /**
 129       * UTF-8 aware alternative to strtoupper
 130       * Make a string uppercase
 131       * Note: The concept of a characters "case" only exists is some alphabets
 132       * such as Latin, Greek, Cyrillic, Armenian and archaic Georgian - it does
 133       * not exist in the Chinese alphabet, for example. See Unicode Standard
 134       * Annex #21: Case Mappings
 135       *
 136       * @access public
 137       * @param string
 138       * @return mixed either string in uppercase or FALSE is UTF-8 invalid
 139       * @see http://www.php.net/strtoupper
 140       */
 141  	function strtoupper($str){
 142          return utf8_strtoupper($str);
 143      }
 144  
 145      /**
 146       * UTF-8 aware alternative to strlen
 147       * Returns the number of characters in the string (NOT THE NUMBER OF BYTES),
 148       *
 149       * @access public
 150       * @param string UTF-8 string
 151       * @return int number of UTF-8 characters in string
 152       * @see http://www.php.net/strlen
 153       */
 154  	function strlen($str){
 155          return utf8_strlen($str);
 156      }
 157  
 158      /**
 159       * UTF-8 aware alternative to str_ireplace
 160       * Case-insensitive version of str_replace
 161       *
 162       * @static
 163       * @access public
 164       * @param string string to search
 165       * @param string existing string to replace
 166       * @param string new string to replace with
 167       * @param int optional count value to be passed by referene
 168       * @see http://www.php.net/str_ireplace
 169      */
 170  	function str_ireplace($search, $replace, $str, $count = NULL)
 171      {
 172          jimport('phputf8.str_ireplace');
 173          if ( $count === FALSE ) {
 174              return utf8_ireplace($search, $replace, $str);
 175          } else {
 176              return utf8_ireplace($search, $replace, $str, $count);
 177          }
 178      }
 179  
 180      /**
 181       * UTF-8 aware alternative to str_split
 182       * Convert a string to an array
 183       *
 184       * @static
 185       * @access public
 186       * @param string UTF-8 encoded
 187       * @param int number to characters to split string by
 188       * @return array
 189       * @see http://www.php.net/str_split
 190      */
 191  	function str_split($str, $split_len = 1)
 192      {
 193          jimport('phputf8.str_split');
 194          return utf8_str_split($str, $split_len);
 195      }
 196  
 197      /**
 198       * UTF-8 aware alternative to strcasecmp
 199       * A case insensivite string comparison
 200       *
 201       * @static
 202       * @access public
 203       * @param string string 1 to compare
 204       * @param string string 2 to compare
 205       * @return int < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal.
 206       * @see http://www.php.net/strcasecmp
 207      */
 208  	function strcasecmp($str1, $str2)
 209      {
 210          jimport('phputf8.strcasecmp');
 211          return utf8_strcasecmp($str1, $str2);
 212      }
 213  
 214      /**
 215       * UTF-8 aware alternative to strcspn
 216       * Find length of initial segment not matching mask
 217       *
 218       * @static
 219       * @access public
 220       * @param string
 221       * @param string the mask
 222       * @param int Optional starting character position (in characters)
 223       * @param int Optional length
 224       * @return int the length of the initial segment of str1 which does not contain any of the characters in str2
 225       * @see http://www.php.net/strcspn
 226      */
 227  	function strcspn($str, $mask, $start = NULL, $length = NULL)
 228      {
 229          jimport('phputf8.strcspn');
 230          if ( $start === FALSE && $length === FALSE ) {
 231              return utf8_strcspn($str, $mask);
 232          } else if ( $length === FALSE ) {
 233              return utf8_strcspn($str, $mask, $start);
 234          } else {
 235              return utf8_strcspn($str, $mask, $start, $length);
 236          }
 237      }
 238  
 239      /**
 240       * UTF-8 aware alternative to stristr
 241       * Returns all of haystack from the first occurrence of needle to the end.
 242       * needle and haystack are examined in a case-insensitive manner
 243       * Find first occurrence of a string using case insensitive comparison
 244       *
 245       * @static
 246       * @access public
 247       * @param string the haystack
 248       * @param string the needle
 249       * @return string the sub string
 250       * @see http://www.php.net/stristr
 251      */
 252  	function stristr($str, $search)
 253      {
 254          jimport('phputf8.stristr');
 255          return utf8_stristr($str, $search);
 256      }
 257  
 258      /**
 259       * UTF-8 aware alternative to strrev
 260       * Reverse a string
 261       *
 262       * @static
 263       * @access public
 264       * @param string String to be reversed
 265       * @return string The string in reverse character order
 266       * @see http://www.php.net/strrev
 267      */
 268  	function strrev($str)
 269      {
 270          jimport('phputf8.strrev');
 271          return utf8_strrev($str);
 272      }
 273  
 274      /**
 275       * UTF-8 aware alternative to strspn
 276       * Find length of initial segment matching mask
 277       *
 278       * @static
 279       * @access public
 280       * @param string the haystack
 281       * @param string the mask
 282       * @param int start optional
 283       * @param int length optional
 284       * @see http://www.php.net/strspn
 285      */
 286  	function strspn($str, $mask, $start = NULL, $length = NULL)
 287      {
 288          jimport('phputf8.strspn');
 289          if ( $start === FALSE && $length === FALSE ) {
 290              return utf8_strspn($str, $mask);
 291          } else if ( $length === FALSE ) {
 292              return utf8_strspn($str, $mask, $start);
 293          } else {
 294              return utf8_strspn($str, $mask, $start, $length);
 295          }
 296      }
 297  
 298      /**
 299       * UTF-8 aware substr_replace
 300       * Replace text within a portion of a string
 301       *
 302       * @static
 303       * @access public
 304       * @param string the haystack
 305       * @param string the replacement string
 306       * @param int start
 307       * @param int length (optional)
 308       * @see http://www.php.net/substr_replace
 309      */
 310  	function substr_replace($str, $repl, $start, $length = NULL )
 311      {
 312          // loaded by library loader
 313          if ( $length === FALSE ) {
 314              return utf8_substr_replace($str, $repl, $start);
 315          } else {
 316              return utf8_substr_replace($str, $repl, $start, $length);
 317          }
 318      }
 319  
 320      /**
 321       * UTF-8 aware replacement for ltrim()
 322       * Strip whitespace (or other characters) from the beginning of a string
 323       * Note: you only need to use this if you are supplying the charlist
 324       * optional arg and it contains UTF-8 characters. Otherwise ltrim will
 325       * work normally on a UTF-8 string
 326       *
 327       * @static
 328       * @access public
 329       * @param string the string to be trimmed
 330       * @param string the optional charlist of additional characters to trim
 331       * @return string the trimmed string
 332       * @see http://www.php.net/ltrim
 333      */
 334  	function ltrim( $str, $charlist = FALSE )
 335      {
 336          jimport('phputf8.trim');
 337          if ( $charlist === FALSE ) {
 338              return utf8_ltrim( $str );
 339          } else {
 340              return utf8_ltrim( $str, $charlist );
 341          }
 342      }
 343  
 344      /**
 345       * UTF-8 aware replacement for rtrim()
 346       * Strip whitespace (or other characters) from the end of a string
 347       * Note: you only need to use this if you are supplying the charlist
 348       * optional arg and it contains UTF-8 characters. Otherwise rtrim will
 349       * work normally on a UTF-8 string
 350       *
 351       * @static
 352       * @access public
 353       * @param string the string to be trimmed
 354       * @param string the optional charlist of additional characters to trim
 355       * @return string the trimmed string
 356       * @see http://www.php.net/rtrim
 357      */
 358  	function rtrim( $str, $charlist = FALSE )
 359      {
 360          jimport('phputf8.trim');
 361          if ( $charlist === FALSE ) {
 362              return utf8_rtrim($str);
 363          } else {
 364              return utf8_rtrim( $str, $charlist );
 365          }
 366      }
 367  
 368      /**
 369       * UTF-8 aware replacement for trim()
 370       * Strip whitespace (or other characters) from the beginning and end of a string
 371       * Note: you only need to use this if you are supplying the charlist
 372       * optional arg and it contains UTF-8 characters. Otherwise trim will
 373       * work normally on a UTF-8 string
 374       *
 375       * @static
 376       * @access public
 377       * @param string the string to be trimmed
 378       * @param string the optional charlist of additional characters to trim
 379       * @return string the trimmed string
 380       * @see http://www.php.net/trim
 381      */
 382  	function trim( $str, $charlist = FALSE )
 383      {
 384          jimport('phputf8.trim');
 385          if ( $charlist === FALSE ) {
 386              return utf8_trim( $str );
 387          } else {
 388              return utf8_trim( $str, $charlist );
 389          }
 390      }
 391  
 392      /**
 393       * UTF-8 aware alternative to ucfirst
 394       * Make a string's first character uppercase
 395       *
 396       * @static
 397       * @access public
 398       * @param string
 399       * @return string with first character as upper case (if applicable)
 400       * @see http://www.php.net/ucfirst
 401      */
 402  	function ucfirst($str)
 403      {
 404          jimport('phputf8.ucfirst');
 405          return utf8_ucfirst($str);
 406      }
 407  
 408      /**
 409       * UTF-8 aware alternative to ucwords
 410       * Uppercase the first character of each word in a string
 411       *
 412       * @static
 413       * @access public
 414       * @param string
 415       * @return string with first char of each word uppercase
 416       * @see http://www.php.net/ucwords
 417      */
 418  	function ucwords($str)
 419      {
 420          jimport('phputf8.ucwords');
 421          return utf8_ucwords($str);
 422      }
 423  
 424      /**
 425       * Transcode a string.
 426       *
 427       * @static
 428       * @param string $source The string to transcode.
 429       * @param string $from_encoding The source encoding.
 430       * @param string $to_encoding The target encoding.
 431       * @return string Transcoded string
 432       * @since 1.5
 433       */
 434  	function transcode($source, $from_encoding, $to_encoding) {
 435  
 436          if (is_string($source)) {
 437              /*
 438               * "//TRANSLIT" is appendd to the $to_encoding to ensure that when iconv comes
 439               * across a character that cannot be represented in the target charset, it can
 440               * be approximated through one or several similarly looking characters.
 441               */
 442              return iconv($from_encoding, $to_encoding.'//TRANSLIT', $source);
 443          }
 444      }
 445  }