Fix for r47482: put the RELEASE-NOTES entry in the "bug fixes" section and not the...
[mediawiki.git] / includes / StringUtils.php
blobc437b3c19e48a5d2b8341b303ee5802afdc22505
1 <?php
2 /**
3 * A collection of static methods to play with strings.
4 */
5 class StringUtils {
6 /**
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.
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 ) );
28 return $output;
31 /**
32 * Perform an operation equivalent to
34 * preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject )
36 * This implementation is slower than hungryDelimiterReplace but uses far less
37 * memory. The delimiters are literal strings, not regular expressions.
39 * @param string $flags Regular expression flags
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();
57 while ( $inputPos < strlen( $subject ) &&
58 preg_match( "!($encStart)|($encEnd)!S$flags", $subject, $m, PREG_OFFSET_CAPTURE, $inputPos ) )
60 $tokenOffset = $m[0][1];
61 if ( $m[1][0] != '' ) {
62 if ( $foundStart &&
63 $strcmp( $endDelim, substr( $subject, $tokenOffset, $endLength ) ) == 0 )
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] );
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__ );
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;
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 );
103 $inputPos = $outputPos = $tokenOffset + $tokenLength;
104 } else {
105 throw new MWException( 'Invalid delimiter given to ' . __METHOD__ );
108 if ( $outputPos < strlen( $subject ) ) {
109 $output .= substr( $subject, $outputPos );
111 return $output;
115 * Perform an operation equivalent to
117 * preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject )
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
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 );
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
139 static function explodeMarkup( $separator, $text ) {
140 $placeholder = "\x00";
142 // Remove placeholder instances
143 $text = str_replace( $placeholder, '', $text );
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 );
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 );
155 return $items;
159 * Escape a string to make it suitable for inclusion in a preg_replace()
160 * replacement parameter.
162 * @param string $string
163 * @return string
165 static function escapeRegexReplacement( $string ) {
166 $string = str_replace( '\\', '\\\\', $string );
167 $string = str_replace( '$', '\\$', $string );
168 return $string;
172 * Workalike for explode() with limited memory usage.
173 * Returns an Iterator
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 ) );
185 * Base class for "replacers", objects used in preg_replace_callback() and
186 * StringUtils::delimiterReplaceCallback()
188 class Replacer {
189 function cb() {
190 return array( &$this, 'replace' );
195 * Class to replace regex matches with a string similar to that used in preg_replace()
197 class RegexlikeReplacer extends Replacer {
198 var $r;
199 function __construct( $r ) {
200 $this->r = $r;
203 function replace( $matches ) {
204 $pairs = array();
205 foreach ( $matches as $i => $match ) {
206 $pairs["\$$i"] = $match;
208 return strtr( $this->r, $pairs );
214 * Class to perform secondary replacement within each replacement string
216 class DoubleReplacer extends Replacer {
217 function __construct( $from, $to, $index = 0 ) {
218 $this->from = $from;
219 $this->to = $to;
220 $this->index = $index;
223 function replace( $matches ) {
224 return str_replace( $this->from, $this->to, $matches[$this->index] );
229 * Class to perform replacement based on a simple hashtable lookup
231 class HashtableReplacer extends Replacer {
232 var $table, $index;
234 function __construct( $table, $index = 0 ) {
235 $this->table = $table;
236 $this->index = $index;
239 function replace( $matches ) {
240 return $this->table[$matches[$this->index]];
245 * Replacement array for FSS with fallback to strtr()
246 * Supports lazy initialisation of FSS resource
248 class ReplacementArray {
249 /*mostly private*/ var $data = false;
250 /*mostly private*/ var $fss = false;
253 * Create an object with the specified replacement array
254 * The array should have the same form as the replacement array for strtr()
256 function __construct( $data = array() ) {
257 $this->data = $data;
260 function __sleep() {
261 return array( 'data' );
264 function __wakeup() {
265 $this->fss = false;
269 * Set the whole replacement array at once
271 function setArray( $data ) {
272 $this->data = $data;
273 $this->fss = false;
276 function getArray() {
277 return $this->data;
281 * Set an element of the replacement array
283 function setPair( $from, $to ) {
284 $this->data[$from] = $to;
285 $this->fss = false;
288 function mergeArray( $data ) {
289 $this->data = array_merge( $this->data, $data );
290 $this->fss = false;
293 function merge( $other ) {
294 $this->data = array_merge( $this->data, $other->data );
295 $this->fss = false;
298 function removePair( $from ) {
299 unset($this->data[$from]);
300 $this->fss = false;
303 function removeArray( $data ) {
304 foreach( $data as $from => $to )
305 $this->removePair( $from );
306 $this->fss = false;
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 );
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' );
322 return $result;
327 * An iterator which works exactly like:
329 * foreach ( explode( $delim, $s ) as $element ) {
330 * ...
333 * Except it doesn't use 193 byte per element
335 class ExplodeIterator implements Iterator {
336 // The subject string
337 var $subject, $subjectLength;
339 // The delimiter
340 var $delim, $delimLength;
342 // The position of the start of the line
343 var $curPos;
345 // The position after the end of the next delimiter
346 var $endPos;
348 // The current token
349 var $current;
351 /**
352 * Construct a DelimIterator
354 function __construct( $delim, $s ) {
355 $this->subject = $s;
356 $this->delim = $delim;
358 // Micro-optimisation (theoretical)
359 $this->subjectLength = strlen( $s );
360 $this->delimLength = strlen( $delim );
362 $this->rewind();
365 function rewind() {
366 $this->curPos = 0;
367 $this->endPos = strpos( $this->subject, $this->delim );
368 $this->refreshCurrent();
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 );
384 function current() {
385 return $this->current;
388 function key() {
389 return $this->curPos;
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 );
403 $this->refreshCurrent();
404 return $this->current;
407 function valid() {
408 return $this->curPos !== false;