Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: Joomla-Framework

Developer Network License

The Joomla! Developer Network content is © copyright 2006 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5
Source code for file /joomla/utilities/string.php

Documentation is available at string.php

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