includes/StringUtils.php

   1 <?php
   2 /**
   3  * A collection of static methods to play with strings.
   4  */
   5 class StringUtils {
   6         /**
   7          * Perform an operation equivalent to
   8          *
   9          *     preg_replace( "!$startDelim(.*?)$endDelim!", $replace, $subject );
  10          *
  11          * except that it's worst-case O(N) instead of O(N^2)
  12          *
  13          * Compared to delimiterReplace(), this implementation is fast but memory-
  14          * hungry and inflexible. The memory requirements are such that I don't
  15          * recommend using it on anything but guaranteed small chunks of text.
  16          */
  17         static function hungryDelimiterReplace( $startDelim, $endDelim, $replace, $subject ) {
  18                 $segments = explode( $startDelim, $subject );
  19                 $output = array_shift( $segments );
  20                 foreach ( $segments as $s ) {
  21                         $endDelimPos = strpos( $s, $endDelim );
  22                         if ( $endDelimPos === false ) {
  23                                 $output .= $startDelim . $s;
  24                         } else {
  25                                 $output .= $replace . substr( $s, $endDelimPos + strlen( $endDelim ) );
  26                         }
  27                 }
  28                 return $output;
  29         }
  30
  31         /**
  32          * Perform an operation equivalent to
  33          *
  34          *   preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject )
  35          *
  36          * This implementation is slower than hungryDelimiterReplace but uses far less
  37          * memory. The delimiters are literal strings, not regular expressions.
  38          *
  39          * @param string $flags Regular expression flags
  40          */
  41         # If the start delimiter ends with an initial substring of the end delimiter,
  42         # e.g. in the case of C-style comments, the behaviour differs from the model
  43         # regex. In this implementation, the end must share no characters with the
  44         # start, so e.g. /*/ is not considered to be both the start and end of a
  45         # comment. /*/xy/*/ is considered to be a single comment with contents /xy/.
  46         static function delimiterReplaceCallback( $startDelim, $endDelim, $callback, $subject, $flags = '' ) {
  47                 $inputPos = 0;
  48                 $outputPos = 0;
  49                 $output = '';
  50                 $foundStart = false;
  51                 $encStart = preg_quote( $startDelim, '!' );
  52                 $encEnd = preg_quote( $endDelim, '!' );
  53                 $strcmp = strpos( $flags, 'i' ) === false ? 'strcmp' : 'strcasecmp';
  54                 $endLength = strlen( $endDelim );
  55                 $m = array();
  56
  57                 while ( $inputPos < strlen( $subject ) &&
  58                   preg_match( "!($encStart)|($encEnd)!S$flags", $subject, $m, PREG_OFFSET_CAPTURE, $inputPos ) )
  59                 {
  60                         $tokenOffset = $m[0][1];
  61                         if ( $m[1][0] != '' ) {
  62                                 if ( $foundStart &&
  63                                   $strcmp( $endDelim, substr( $subject, $tokenOffset, $endLength ) ) == 0 )
  64                                 {
  65                                         # An end match is present at the same location
  66                                         $tokenType = 'end';
  67                                         $tokenLength = $endLength;
  68                                 } else {
  69                                         $tokenType = 'start';
  70                                         $tokenLength = strlen( $m[0][0] );
  71                                 }
  72                         } elseif ( $m[2][0] != '' ) {
  73                                 $tokenType = 'end';
  74                                 $tokenLength = strlen( $m[0][0] );
  75                         } else {
  76                                 throw new MWException( 'Invalid delimiter given to ' . __METHOD__ );
  77                         }
  78
  79                         if ( $tokenType == 'start' ) {
  80                                 $inputPos = $tokenOffset + $tokenLength;
  81                                 # Only move the start position if we haven't already found a start
  82                                 # This means that START START END matches outer pair
  83                                 if ( !$foundStart ) {
  84                                         # Found start
  85                                         # Write out the non-matching section
  86                                         $output .= substr( $subject, $outputPos, $tokenOffset - $outputPos );
  87                                         $outputPos = $tokenOffset;
  88                                         $contentPos = $inputPos;
  89                                         $foundStart = true;
  90                                 }
  91                         } elseif ( $tokenType == 'end' ) {
  92                                 if ( $foundStart ) {
  93                                         # Found match
  94                                         $output .= call_user_func( $callback, array(
  95                                                 substr( $subject, $outputPos, $tokenOffset + $tokenLength - $outputPos ),
  96                                                 substr( $subject, $contentPos, $tokenOffset - $contentPos )
  97                                         ));
  98                                         $foundStart = false;
  99                                 } else {
 100                                         # Non-matching end, write it out
 101                                         $output .= substr( $subject, $inputPos, $tokenOffset + $tokenLength - $outputPos );
 102                                 }
 103                                 $inputPos = $outputPos = $tokenOffset + $tokenLength;
 104                         } else {
 105                                 throw new MWException( 'Invalid delimiter given to ' . __METHOD__ );
 106                         }
 107                 }
 108                 if ( $outputPos < strlen( $subject ) ) {
 109                         $output .= substr( $subject, $outputPos );
 110                 }
 111                 return $output;
 112         }
 113
 114         /*
 115          * Perform an operation equivalent to
 116          *
 117          *   preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject )
 118          *
 119          * @param string $startDelim Start delimiter regular expression
 120          * @param string $endDelim End delimiter regular expression
 121          * @param string $replace Replacement string. May contain $1, which will be
 122          *               replaced by the text between the delimiters
 123          * @param string $subject String to search
 124          * @return string The string with the matches replaced
 125          */
 126         static function delimiterReplace( $startDelim, $endDelim, $replace, $subject, $flags = '' ) {
 127                 $replacer = new RegexlikeReplacer( $replace );
 128                 return self::delimiterReplaceCallback( $startDelim, $endDelim,
 129                         $replacer->cb(), $subject, $flags );
 130         }
 131
 132         /**
 133          * More or less "markup-safe" explode()
 134          * Ignores any instances of the separator inside <...>
 135          * @param string $separator
 136          * @param string $text
 137          * @return array
 138          */
 139         static function explodeMarkup( $separator, $text ) {
 140                 $placeholder = "\x00";
 141
 142                 // Remove placeholder instances
 143                 $text = str_replace( $placeholder, '', $text );
 144
 145                 // Replace instances of the separator inside HTML-like tags with the placeholder
 146                 $replacer = new DoubleReplacer( $separator, $placeholder );
 147                 $cleaned = StringUtils::delimiterReplaceCallback( '<', '>', $replacer->cb(), $text );
 148
 149                 // Explode, then put the replaced separators back in
 150                 $items = explode( $separator, $cleaned );
 151                 foreach( $items as $i => $str ) {
 152                         $items[$i] = str_replace( $placeholder, $separator, $str );
 153                 }
 154
 155                 return $items;
 156         }
 157
 158         /**
 159          * Escape a string to make it suitable for inclusion in a preg_replace()
 160          * replacement parameter.
 161          *
 162          * @param string $string
 163          * @return string
 164          */
 165         static function escapeRegexReplacement( $string ) {
 166                 $string = str_replace( '\\', '\\\\', $string );
 167                 $string = str_replace( '$', '\\$', $string );
 168                 return $string;
 169         }
 170 }
 171
 172 /**
 173  * Base class for "replacers", objects used in preg_replace_callback() and
 174  * StringUtils::delimiterReplaceCallback()
 175  */
 176 class Replacer {
 177         function cb() {
 178                 return array( &$this, 'replace' );
 179         }
 180 }
 181
 182 /**
 183  * Class to replace regex matches with a string similar to that used in preg_replace()
 184  */
 185 class RegexlikeReplacer extends Replacer {
 186         var $r;
 187         function __construct( $r ) {
 188                 $this->r = $r;
 189         }
 190
 191         function replace( $matches ) {
 192                 $pairs = array();
 193                 foreach ( $matches as $i => $match ) {
 194                         $pairs["\$$i"] = $match;
 195                 }
 196                 return strtr( $this->r, $pairs );
 197         }
 198
 199 }
 200
 201 /**
 202  * Class to perform secondary replacement within each replacement string
 203  */
 204 class DoubleReplacer extends Replacer {
 205         function __construct( $from, $to, $index = 0 ) {
 206                 $this->from = $from;
 207                 $this->to = $to;
 208                 $this->index = $index;
 209         }
 210
 211         function replace( $matches ) {
 212                 return str_replace( $this->from, $this->to, $matches[$this->index] );
 213         }
 214 }
 215
 216 /**
 217  * Class to perform replacement based on a simple hashtable lookup
 218  */
 219 class HashtableReplacer extends Replacer {
 220         var $table, $index;
 221
 222         function __construct( $table, $index = 0 ) {
 223                 $this->table = $table;
 224                 $this->index = $index;
 225         }
 226
 227         function replace( $matches ) {
 228                 return $this->table[$matches[$this->index]];
 229         }
 230 }
 231
 232 /**
 233  * Replacement array for FSS with fallback to strtr()
 234  * Supports lazy initialisation of FSS resource
 235  */
 236 class ReplacementArray {
 237         /*mostly private*/ var $data = false;
 238         /*mostly private*/ var $fss = false;
 239
 240         /**
 241          * Create an object with the specified replacement array
 242          * The array should have the same form as the replacement array for strtr()
 243          */
 244         function __construct( $data = array() ) {
 245                 $this->data = $data;
 246         }
 247
 248         function __sleep() {
 249                 return array( 'data' );
 250         }
 251
 252         function __wakeup() {
 253                 $this->fss = false;
 254         }
 255
 256         /**
 257          * Set the whole replacement array at once
 258          */
 259         function setArray( $data ) {
 260                 $this->data = $data;
 261                 $this->fss = false;
 262         }
 263
 264         function getArray() {
 265                 return $this->data;
 266         }
 267
 268         /**
 269          * Set an element of the replacement array
 270          */
 271         function setPair( $from, $to ) {
 272                 $this->data[$from] = $to;
 273                 $this->fss = false;
 274         }
 275
 276         function mergeArray( $data ) {
 277                 $this->data = array_merge( $this->data, $data );
 278                 $this->fss = false;
 279         }
 280
 281         function merge( $other ) {
 282                 $this->data = array_merge( $this->data, $other->data );
 283                 $this->fss = false;
 284         }
 285
 286         function replace( $subject ) {
 287                 if ( function_exists( 'fss_prep_replace' ) ) {
 288                         wfProfileIn( __METHOD__.'-fss' );
 289                         if ( $this->fss === false ) {
 290                                 $this->fss = fss_prep_replace( $this->data );
 291                         }
 292                         $result = fss_exec_replace( $this->fss, $subject );
 293                         wfProfileOut( __METHOD__.'-fss' );
 294                 } else {
 295                         wfProfileIn( __METHOD__.'-strtr' );
 296                         $result = strtr( $subject, $this->data );
 297                         wfProfileOut( __METHOD__.'-strtr' );
 298                 }
 299                 return $result;
 300         }
 301 }