3 * A collection of static methods to play with strings.
7 * Perform an operation equivalent to
9 * preg_replace( "!$startDelim(.*?)$endDelim!", $replace, $subject );
11 * except that it's worst-case O(N) instead of O(N^2)
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.
24 static function hungryDelimiterReplace( $startDelim, $endDelim, $replace, $subject ) {
25 $segments = explode( $startDelim, $subject );
26 $output = array_shift( $segments );
27 foreach ( $segments as $s ) {
28 $endDelimPos = strpos( $s, $endDelim );
29 if ( $endDelimPos === false ) {
30 $output .= $startDelim . $s;
32 $output .= $replace . substr( $s, $endDelimPos +
strlen( $endDelim ) );
39 * Perform an operation equivalent to
41 * preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject )
43 * This implementation is slower than hungryDelimiterReplace but uses far less
44 * memory. The delimiters are literal strings, not regular expressions.
46 * If the start delimiter ends with an initial substring of the end delimiter,
47 * e.g. in the case of C-style comments, the behaviour differs from the model
48 * regex. In this implementation, the end must share no characters with the
49 * start, so e.g. /*\/ is not considered to be both the start and end of a
50 * comment. /*\/xy/*\/ is considered to be a single comment with contents /xy/.
52 * @param $startDelim String: start delimiter
53 * @param $endDelim String: end delimiter
54 * @param $callback Callback: function to call on each match
55 * @param $subject String
56 * @param $flags String: regular expression flags
60 static function delimiterReplaceCallback( $startDelim, $endDelim, $callback, $subject, $flags = '' ) {
65 $encStart = preg_quote( $startDelim, '!' );
66 $encEnd = preg_quote( $endDelim, '!' );
67 $strcmp = strpos( $flags, 'i' ) === false ?
'strcmp' : 'strcasecmp';
68 $endLength = strlen( $endDelim );
71 while ( $inputPos < strlen( $subject ) &&
72 preg_match( "!($encStart)|($encEnd)!S$flags", $subject, $m, PREG_OFFSET_CAPTURE
, $inputPos ) )
74 $tokenOffset = $m[0][1];
75 if ( $m[1][0] != '' ) {
77 $strcmp( $endDelim, substr( $subject, $tokenOffset, $endLength ) ) == 0 )
79 # An end match is present at the same location
81 $tokenLength = $endLength;
84 $tokenLength = strlen( $m[0][0] );
86 } elseif ( $m[2][0] != '' ) {
88 $tokenLength = strlen( $m[0][0] );
90 throw new MWException( 'Invalid delimiter given to ' . __METHOD__
);
93 if ( $tokenType == 'start' ) {
94 # Only move the start position if we haven't already found a start
95 # This means that START START END matches outer pair
98 $inputPos = $tokenOffset +
$tokenLength;
99 # Write out the non-matching section
100 $output .= substr( $subject, $outputPos, $tokenOffset - $outputPos );
101 $outputPos = $tokenOffset;
102 $contentPos = $inputPos;
105 # Move the input position past the *first character* of START,
106 # to protect against missing END when it overlaps with START
107 $inputPos = $tokenOffset +
1;
109 } elseif ( $tokenType == 'end' ) {
112 $output .= call_user_func( $callback, array(
113 substr( $subject, $outputPos, $tokenOffset +
$tokenLength - $outputPos ),
114 substr( $subject, $contentPos, $tokenOffset - $contentPos )
118 # Non-matching end, write it out
119 $output .= substr( $subject, $inputPos, $tokenOffset +
$tokenLength - $outputPos );
121 $inputPos = $outputPos = $tokenOffset +
$tokenLength;
123 throw new MWException( 'Invalid delimiter given to ' . __METHOD__
);
126 if ( $outputPos < strlen( $subject ) ) {
127 $output .= substr( $subject, $outputPos );
133 * Perform an operation equivalent to
135 * preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject )
137 * @param $startDelim String: start delimiter regular expression
138 * @param $endDelim String: end delimiter regular expression
139 * @param $replace String: replacement string. May contain $1, which will be
140 * replaced by the text between the delimiters
141 * @param $subject String to search
142 * @param $flags String: regular expression flags
143 * @return String: The string with the matches replaced
145 static function delimiterReplace( $startDelim, $endDelim, $replace, $subject, $flags = '' ) {
146 $replacer = new RegexlikeReplacer( $replace );
147 return self
::delimiterReplaceCallback( $startDelim, $endDelim,
148 $replacer->cb(), $subject, $flags );
152 * More or less "markup-safe" explode()
153 * Ignores any instances of the separator inside <...>
154 * @param $separator String
155 * @param $text String
158 static function explodeMarkup( $separator, $text ) {
159 $placeholder = "\x00";
161 // Remove placeholder instances
162 $text = str_replace( $placeholder, '', $text );
164 // Replace instances of the separator inside HTML-like tags with the placeholder
165 $replacer = new DoubleReplacer( $separator, $placeholder );
166 $cleaned = StringUtils
::delimiterReplaceCallback( '<', '>', $replacer->cb(), $text );
168 // Explode, then put the replaced separators back in
169 $items = explode( $separator, $cleaned );
170 foreach( $items as $i => $str ) {
171 $items[$i] = str_replace( $placeholder, $separator, $str );
178 * Escape a string to make it suitable for inclusion in a preg_replace()
179 * replacement parameter.
181 * @param $string String
184 static function escapeRegexReplacement( $string ) {
185 $string = str_replace( '\\', '\\\\', $string );
186 $string = str_replace( '$', '\\$', $string );
191 * Workalike for explode() with limited memory usage.
192 * Returns an Iterator
195 * @return ArrayIterator|\ExplodeIterator
197 static function explode( $separator, $subject ) {
198 if ( substr_count( $subject, $separator ) > 1000 ) {
199 return new ExplodeIterator( $separator, $subject );
201 return new ArrayIterator( explode( $separator, $subject ) );
207 * Base class for "replacers", objects used in preg_replace_callback() and
208 * StringUtils::delimiterReplaceCallback()
216 return array( &$this, 'replace' );
221 * Class to replace regex matches with a string similar to that used in preg_replace()
223 class RegexlikeReplacer
extends Replacer
{
229 function __construct( $r ) {
234 * @param $matches array
237 function replace( $matches ) {
239 foreach ( $matches as $i => $match ) {
240 $pairs["\$$i"] = $match;
242 return strtr( $this->r
, $pairs );
248 * Class to perform secondary replacement within each replacement string
250 class DoubleReplacer
extends Replacer
{
257 function __construct( $from, $to, $index = 0 ) {
260 $this->index
= $index;
264 * @param $matches array
267 function replace( $matches ) {
268 return str_replace( $this->from
, $this->to
, $matches[$this->index
] );
273 * Class to perform replacement based on a simple hashtable lookup
275 class HashtableReplacer
extends Replacer
{
282 function __construct( $table, $index = 0 ) {
283 $this->table
= $table;
284 $this->index
= $index;
288 * @param $matches array
291 function replace( $matches ) {
292 return $this->table
[$matches[$this->index
]];
297 * Replacement array for FSS with fallback to strtr()
298 * Supports lazy initialisation of FSS resource
300 class ReplacementArray
{
301 /*mostly private*/ var $data = false;
302 /*mostly private*/ var $fss = false;
305 * Create an object with the specified replacement array
306 * The array should have the same form as the replacement array for strtr()
309 function __construct( $data = array() ) {
317 return array( 'data' );
320 function __wakeup() {
325 * Set the whole replacement array at once
327 function setArray( $data ) {
335 function getArray() {
340 * Set an element of the replacement array
341 * @param $from string
344 function setPair( $from, $to ) {
345 $this->data
[$from] = $to;
352 function mergeArray( $data ) {
353 $this->data
= array_merge( $this->data
, $data );
360 function merge( $other ) {
361 $this->data
= array_merge( $this->data
, $other->data
);
366 * @param $from string
368 function removePair( $from ) {
369 unset($this->data
[$from]);
376 function removeArray( $data ) {
377 foreach( $data as $from => $to ) {
378 $this->removePair( $from );
384 * @param $subject string
387 function replace( $subject ) {
388 if ( function_exists( 'fss_prep_replace' ) ) {
389 wfProfileIn( __METHOD__
.'-fss' );
390 if ( $this->fss
=== false ) {
391 $this->fss
= fss_prep_replace( $this->data
);
393 $result = fss_exec_replace( $this->fss
, $subject );
394 wfProfileOut( __METHOD__
.'-fss' );
396 wfProfileIn( __METHOD__
.'-strtr' );
397 $result = strtr( $subject, $this->data
);
398 wfProfileOut( __METHOD__
.'-strtr' );
405 * An iterator which works exactly like:
407 * foreach ( explode( $delim, $s ) as $element ) {
411 * Except it doesn't use 193 byte per element
413 class ExplodeIterator
implements Iterator
{
414 // The subject string
415 var $subject, $subjectLength;
418 var $delim, $delimLength;
420 // The position of the start of the line
423 // The position after the end of the next delimiter
430 * Construct a DelimIterator
431 * @param $delim string
434 function __construct( $delim, $s ) {
436 $this->delim
= $delim;
438 // Micro-optimisation (theoretical)
439 $this->subjectLength
= strlen( $s );
440 $this->delimLength
= strlen( $delim );
447 $this->endPos
= strpos( $this->subject
, $this->delim
);
448 $this->refreshCurrent();
451 function refreshCurrent() {
452 if ( $this->curPos
=== false ) {
453 $this->current
= false;
454 } elseif ( $this->curPos
>= $this->subjectLength
) {
456 } elseif ( $this->endPos
=== false ) {
457 $this->current
= substr( $this->subject
, $this->curPos
);
459 $this->current
= substr( $this->subject
, $this->curPos
, $this->endPos
- $this->curPos
);
464 return $this->current
;
468 return $this->curPos
;
475 if ( $this->endPos
=== false ) {
476 $this->curPos
= false;
478 $this->curPos
= $this->endPos +
$this->delimLength
;
479 if ( $this->curPos
>= $this->subjectLength
) {
480 $this->endPos
= false;
482 $this->endPos
= strpos( $this->subject
, $this->delim
, $this->curPos
);
485 $this->refreshCurrent();
486 return $this->current
;
493 return $this->curPos
!== false;