3 * Methods to play with strings.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * A collection of static methods to play with strings.
28 * Test whether a string is valid UTF-8.
30 * The function check for invalid byte sequences, overlong encoding but
31 * not for different normalisations.
33 * @note In MediaWiki 1.21, this function did not provide proper UTF-8 validation.
34 * In particular, the pure PHP code path did not in fact check for overlong forms.
35 * Beware of this when backporting code to that version of MediaWiki.
38 * @param string $value String to check
39 * @return bool Whether the given $value is a valid UTF-8 encoded string
41 static function isUtf8( $value ) {
42 return mb_check_encoding( (string)$value, 'UTF-8' );
46 * Explode a string, but ignore any instances of the separator inside
47 * the given start and end delimiters, which may optionally nest.
48 * The delimiters are literal strings, not regular expressions.
49 * @param string $startDelim Start delimiter
50 * @param string $endDelim End delimiter
51 * @param string $separator Separator string for the explode.
52 * @param string $subject Subject string to explode.
53 * @param bool $nested True iff the delimiters are allowed to nest.
54 * @return ArrayIterator
56 static function delimiterExplode( $startDelim, $endDelim, $separator,
57 $subject, $nested = false ) {
61 $encStart = preg_quote( $startDelim, '!' );
62 $encEnd = preg_quote( $endDelim, '!' );
63 $encSep = preg_quote( $separator, '!' );
64 $len = strlen( $subject );
70 "!$encStart|$encEnd|$encSep!S", $subject, $m,
71 PREG_OFFSET_CAPTURE
, $inputPos
76 $inputPos = $matchPos +
strlen( $match );
77 if ( $match === $separator ) {
80 $subject, $lastPos, $matchPos - $lastPos
84 } elseif ( $match === $startDelim ) {
85 if ( $depth === 0 ||
$nested ) {
92 $exploded[] = substr( $subject, $lastPos );
93 // This method could be rewritten in the future to avoid creating an
94 // intermediate array, since the return type is just an iterator.
95 return new ArrayIterator( $exploded );
99 * Perform an operation equivalent to `preg_replace()`
103 * preg_replace( "!$startDelim(.*?)$endDelim!", $replace, $subject );
105 * ..except that it's worst-case O(N) instead of O(N^2). Compared to delimiterReplace(), this
106 * implementation is fast but memory-hungry and inflexible. The memory requirements are such
107 * that I don't recommend using it on anything but guaranteed small chunks of text.
109 * @param string $startDelim
110 * @param string $endDelim
111 * @param string $replace
112 * @param string $subject
115 static function hungryDelimiterReplace( $startDelim, $endDelim, $replace, $subject ) {
116 $segments = explode( $startDelim, $subject );
117 $output = array_shift( $segments );
118 foreach ( $segments as $s ) {
119 $endDelimPos = strpos( $s, $endDelim );
120 if ( $endDelimPos === false ) {
121 $output .= $startDelim . $s;
123 $output .= $replace . substr( $s, $endDelimPos +
strlen( $endDelim ) );
131 * Perform an operation equivalent to `preg_replace_callback()`
135 * preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject );
137 * If the start delimiter ends with an initial substring of the end delimiter,
138 * e.g. in the case of C-style comments, the behavior differs from the model
139 * regex. In this implementation, the end must share no characters with the
140 * start, so e.g. `/*\/` is not considered to be both the start and end of a
141 * comment. `/*\/xy/*\/` is considered to be a single comment with contents `/xy/`.
143 * The implementation of delimiterReplaceCallback() is slower than hungryDelimiterReplace()
144 * but uses far less memory. The delimiters are literal strings, not regular expressions.
146 * @param string $startDelim Start delimiter
147 * @param string $endDelim End delimiter
148 * @param callable $callback Function to call on each match
149 * @param string $subject
150 * @param string $flags Regular expression flags
151 * @throws InvalidArgumentException
154 static function delimiterReplaceCallback( $startDelim, $endDelim, $callback,
155 $subject, $flags = ''
162 $encStart = preg_quote( $startDelim, '!' );
163 $encEnd = preg_quote( $endDelim, '!' );
164 $strcmp = strpos( $flags, 'i' ) === false ?
'strcmp' : 'strcasecmp';
165 $endLength = strlen( $endDelim );
168 while ( $inputPos < strlen( $subject ) &&
169 preg_match( "!($encStart)|($encEnd)!S$flags", $subject, $m, PREG_OFFSET_CAPTURE
, $inputPos )
171 $tokenOffset = $m[0][1];
172 if ( $m[1][0] != '' ) {
174 $strcmp( $endDelim, substr( $subject, $tokenOffset, $endLength ) ) == 0
176 # An end match is present at the same location
178 $tokenLength = $endLength;
180 $tokenType = 'start';
181 $tokenLength = strlen( $m[0][0] );
183 } elseif ( $m[2][0] != '' ) {
185 $tokenLength = strlen( $m[0][0] );
187 throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__
);
190 if ( $tokenType == 'start' ) {
191 # Only move the start position if we haven't already found a start
192 # This means that START START END matches outer pair
193 if ( !$foundStart ) {
195 $inputPos = $tokenOffset +
$tokenLength;
196 # Write out the non-matching section
197 $output .= substr( $subject, $outputPos, $tokenOffset - $outputPos );
198 $outputPos = $tokenOffset;
199 $contentPos = $inputPos;
202 # Move the input position past the *first character* of START,
203 # to protect against missing END when it overlaps with START
204 $inputPos = $tokenOffset +
1;
206 } elseif ( $tokenType == 'end' ) {
209 $output .= call_user_func( $callback, [
210 substr( $subject, $outputPos, $tokenOffset +
$tokenLength - $outputPos ),
211 substr( $subject, $contentPos, $tokenOffset - $contentPos )
215 # Non-matching end, write it out
216 $output .= substr( $subject, $inputPos, $tokenOffset +
$tokenLength - $outputPos );
218 $inputPos = $outputPos = $tokenOffset +
$tokenLength;
220 throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__
);
223 if ( $outputPos < strlen( $subject ) ) {
224 $output .= substr( $subject, $outputPos );
231 * Perform an operation equivalent to `preg_replace()` with flags.
235 * preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject );
237 * @param string $startDelim Start delimiter regular expression
238 * @param string $endDelim End delimiter regular expression
239 * @param string $replace Replacement string. May contain $1, which will be
240 * replaced by the text between the delimiters
241 * @param string $subject String to search
242 * @param string $flags Regular expression flags
243 * @return string The string with the matches replaced
245 static function delimiterReplace( $startDelim, $endDelim, $replace, $subject, $flags = '' ) {
246 $replacer = new RegexlikeReplacer( $replace );
248 return self
::delimiterReplaceCallback( $startDelim, $endDelim,
249 $replacer->cb(), $subject, $flags );
253 * More or less "markup-safe" explode()
254 * Ignores any instances of the separator inside `<...>`
255 * @param string $separator
256 * @param string $text
259 static function explodeMarkup( $separator, $text ) {
260 $placeholder = "\x00";
262 // Remove placeholder instances
263 $text = str_replace( $placeholder, '', $text );
265 // Replace instances of the separator inside HTML-like tags with the placeholder
266 $replacer = new DoubleReplacer( $separator, $placeholder );
267 $cleaned = self
::delimiterReplaceCallback( '<', '>', $replacer->cb(), $text );
269 // Explode, then put the replaced separators back in
270 $items = explode( $separator, $cleaned );
271 foreach ( $items as $i => $str ) {
272 $items[$i] = str_replace( $placeholder, $separator, $str );
279 * More or less "markup-safe" str_replace()
280 * Ignores any instances of the separator inside `<...>`
281 * @param string $search
282 * @param string $replace
283 * @param string $text
286 static function replaceMarkup( $search, $replace, $text ) {
287 $placeholder = "\x00";
289 // Remove placeholder instances
290 $text = str_replace( $placeholder, '', $text );
292 // Replace instances of the separator inside HTML-like tags with the placeholder
293 $replacer = new DoubleReplacer( $search, $placeholder );
294 $cleaned = self
::delimiterReplaceCallback( '<', '>', $replacer->cb(), $text );
296 // Explode, then put the replaced separators back in
297 $cleaned = str_replace( $search, $replace, $cleaned );
298 $text = str_replace( $placeholder, $search, $cleaned );
304 * Escape a string to make it suitable for inclusion in a preg_replace()
305 * replacement parameter.
307 * @param string $string
310 static function escapeRegexReplacement( $string ) {
311 $string = str_replace( '\\', '\\\\', $string );
312 $string = str_replace( '$', '\\$', $string );
317 * Workalike for explode() with limited memory usage.
319 * @param string $separator
320 * @param string $subject
321 * @return ArrayIterator|ExplodeIterator
323 static function explode( $separator, $subject ) {
324 if ( substr_count( $subject, $separator ) > 1000 ) {
325 return new ExplodeIterator( $separator, $subject );
327 return new ArrayIterator( explode( $separator, $subject ) );