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          * Workalike for explode() with limited memory usage.
 173          * Returns an Iterator
 174          */
 175         static function explode( $separator, $subject ) {
 176                 if ( substr_count( $subject, $separator ) > 1000 ) {
 177                         return new ExplodeIterator( $separator, $subject );
 178                 } else {
 179                         return new ArrayIterator( explode( $separator, $subject ) );
 180                 }
 181         }
 182 }
 183
 184 /**
 185  * Base class for "replacers", objects used in preg_replace_callback() and
 186  * StringUtils::delimiterReplaceCallback()
 187  */
 188 class Replacer {
 189         function cb() {
 190                 return array( &$this, 'replace' );
 191         }
 192 }
 193
 194 /**
 195  * Class to replace regex matches with a string similar to that used in preg_replace()
 196  */
 197 class RegexlikeReplacer extends Replacer {
 198         var $r;
 199         function __construct( $r ) {
 200                 $this->r = $r;
 201         }
 202
 203         function replace( $matches ) {
 204                 $pairs = array();
 205                 foreach ( $matches as $i => $match ) {
 206                         $pairs["\$$i"] = $match;
 207                 }
 208                 return strtr( $this->r, $pairs );
 209         }
 210
 211 }
 212
 213 /**
 214  * Class to perform secondary replacement within each replacement string
 215  */
 216 class DoubleReplacer extends Replacer {
 217         function __construct( $from, $to, $index = 0 ) {
 218                 $this->from = $from;
 219                 $this->to = $to;
 220                 $this->index = $index;
 221         }
 222
 223         function replace( $matches ) {
 224                 return str_replace( $this->from, $this->to, $matches[$this->index] );
 225         }
 226 }
 227
 228 /**
 229  * Class to perform replacement based on a simple hashtable lookup
 230  */
 231 class HashtableReplacer extends Replacer {
 232         var $table, $index;
 233
 234         function __construct( $table, $index = 0 ) {
 235                 $this->table = $table;
 236                 $this->index = $index;
 237         }
 238
 239         function replace( $matches ) {
 240                 return $this->table[$matches[$this->index]];
 241         }
 242 }
 243
 244 /**
 245  * Replacement array for FSS with fallback to strtr()
 246  * Supports lazy initialisation of FSS resource
 247  */
 248 class ReplacementArray {
 249         /*mostly private*/ var $data = false;
 250         /*mostly private*/ var $fss = false;
 251
 252         /**
 253          * Create an object with the specified replacement array
 254          * The array should have the same form as the replacement array for strtr()
 255          */
 256         function __construct( $data = array() ) {
 257                 $this->data = $data;
 258         }
 259
 260         function __sleep() {
 261                 return array( 'data' );
 262         }
 263
 264         function __wakeup() {
 265                 $this->fss = false;
 266         }
 267
 268         /**
 269          * Set the whole replacement array at once
 270          */
 271         function setArray( $data ) {
 272                 $this->data = $data;
 273                 $this->fss = false;
 274         }
 275
 276         function getArray() {
 277                 return $this->data;
 278         }
 279
 280         /**
 281          * Set an element of the replacement array
 282          */
 283         function setPair( $from, $to ) {
 284                 $this->data[$from] = $to;
 285                 $this->fss = false;
 286         }
 287
 288         function mergeArray( $data ) {
 289                 $this->data = array_merge( $this->data, $data );
 290                 $this->fss = false;
 291         }
 292
 293         function merge( $other ) {
 294                 $this->data = array_merge( $this->data, $other->data );
 295                 $this->fss = false;
 296         }
 297
 298         function removePair( $from ) {
 299                 unset($this->data[$from]);
 300                 $this->fss = false;
 301         }
 302
 303         function removeArray( $data ) {
 304                 foreach( $data as $from => $to )
 305                         $this->removePair( $from );
 306                 $this->fss = false;
 307         }
 308
 309         function replace( $subject ) {
 310                 if ( function_exists( 'fss_prep_replace' ) ) {
 311                         wfProfileIn( __METHOD__.'-fss' );
 312                         if ( $this->fss === false ) {
 313                                 $this->fss = fss_prep_replace( $this->data );
 314                         }
 315                         $result = fss_exec_replace( $this->fss, $subject );
 316                         wfProfileOut( __METHOD__.'-fss' );
 317                 } else {
 318                         wfProfileIn( __METHOD__.'-strtr' );
 319                         $result = strtr( $subject, $this->data );
 320                         wfProfileOut( __METHOD__.'-strtr' );
 321                 }
 322                 return $result;
 323         }
 324 }
 325
 326 /**
 327  * An iterator which works exactly like:
 328  *
 329  * foreach ( explode( $delim, $s ) as $element ) {
 330  *    ...
 331  * }
 332  *
 333  * Except it doesn't use 193 byte per element
 334  */
 335 class ExplodeIterator implements Iterator {
 336         // The subject string
 337         var $subject, $subjectLength;
 338
 339         // The delimiter
 340         var $delim, $delimLength;
 341
 342         // The position of the start of the line
 343         var $curPos;
 344
 345         // The position after the end of the next delimiter
 346         var $endPos;
 347
 348         // The current token
 349         var $current;
 350
 351         /**
 352          * Construct a DelimIterator
 353          */
 354         function __construct( $delim, $s ) {
 355                 $this->subject = $s;
 356                 $this->delim = $delim;
 357
 358                 // Micro-optimisation (theoretical)
 359                 $this->subjectLength = strlen( $s );
 360                 $this->delimLength = strlen( $delim );
 361
 362                 $this->rewind();
 363         }
 364
 365         function rewind() {
 366                 $this->curPos = 0;
 367                 $this->endPos = strpos( $this->subject, $this->delim );
 368                 $this->refreshCurrent();
 369         }
 370
 371
 372         function refreshCurrent() {
 373                 if ( $this->curPos === false ) {
 374                         $this->current = false;
 375                 } elseif ( $this->curPos >= $this->subjectLength ) {
 376                         $this->current = '';
 377                 } elseif ( $this->endPos === false ) {
 378                         $this->current = substr( $this->subject, $this->curPos );
 379                 } else {
 380                         $this->current = substr( $this->subject, $this->curPos, $this->endPos - $this->curPos );
 381                 }
 382         }
 383
 384         function current() {
 385                 return $this->current;
 386         }
 387
 388         function key() {
 389                 return $this->curPos;
 390         }
 391
 392         function next() {
 393                 if ( $this->endPos === false ) {
 394                         $this->curPos = false;
 395                 } else {
 396                         $this->curPos = $this->endPos + $this->delimLength;
 397                         if ( $this->curPos >= $this->subjectLength ) {
 398                                 $this->endPos = false;
 399                         } else {
 400                                 $this->endPos = strpos( $this->subject, $this->delim, $this->curPos );
 401                         }
 402                 }
 403                 $this->refreshCurrent();
 404                 return $this->current;
 405         }
 406
 407         function valid() {
 408                 return $this->curPos !== false;
 409         }
 410 }
 411