tools\String.php

  1: <?php
  2: 
  3: /**
  4:  * This file is part of the Nette Framework (http://nette.org)
  5:  *
  6:  * Copyright (c) 2004, 2011 David Grudl (http://davidgrudl.com)
  7:  *
  8:  * For the full copyright and license information, please view
  9:  * the file license.txt that was distributed with this source code.
 10:  */
 11: 
 12: namespace Nette;
 13: 
 14: use Nette;
 15: 
 16: 
 17: 
 18: /**
 19:  * String tools library.
 20:  *
 21:  * @author     David Grudl
 22:  */
 23: final class String
 24: {
 25: 
 26:     /**
 27:      * Static class - cannot be instantiated.
 28:      */
 29:     final public function __construct()
 30:     {
 31:         throw new \LogicException("Cannot instantiate static class " . get_class($this));
 32:     }
 33: 
 34: 
 35: 
 36:     /**
 37:      * Checks if the string is valid for the specified encoding.
 38:      * @param  string  byte stream to check
 39:      * @param  string  expected encoding
 40:      * @return bool
 41:      */
 42:     public static function checkEncoding($s, $encoding = 'UTF-8')
 43:     {
 44:         return $s === self::fixEncoding($s, $encoding);
 45:     }
 46: 
 47: 
 48: 
 49:     /**
 50:      * Returns correctly encoded string.
 51:      * @param  string  byte stream to fix
 52:      * @param  string  encoding
 53:      * @return string
 54:      */
 55:     public static function fixEncoding($s, $encoding = 'UTF-8')
 56:     {
 57:         // removes xD800-xDFFF, xFEFF, xFFFF, x110000 and higher
 58:         return @iconv('UTF-16', $encoding . '//IGNORE', iconv($encoding, 'UTF-16//IGNORE', $s)); // intentionally @
 59:     }
 60: 
 61: 
 62: 
 63:     /**
 64:      * Returns a specific character.
 65:      * @param  int     codepoint
 66:      * @param  string  encoding
 67:      * @return string
 68:      */
 69:     public static function chr($code, $encoding = 'UTF-8')
 70:     {
 71:         return iconv('UTF-32BE', $encoding . '//IGNORE', pack('N', $code));
 72:     }
 73: 
 74: 
 75: 
 76:     /**
 77:      * Starts the $haystack string with the prefix $needle?
 78:      * @param  string
 79:      * @param  string
 80:      * @return bool
 81:      */
 82:     public static function startsWith($haystack, $needle)
 83:     {
 84:         return strncmp($haystack, $needle, strlen($needle)) === 0;
 85:     }
 86: 
 87: 
 88: 
 89:     /**
 90:      * Ends the $haystack string with the suffix $needle?
 91:      * @param  string
 92:      * @param  string
 93:      * @return bool
 94:      */
 95:     public static function endsWith($haystack, $needle)
 96:     {
 97:         return strlen($needle) === 0 || substr($haystack, -strlen($needle)) === $needle;
 98:     }
 99: 
100: 
101: 
102:     /**
103:      * Removes special controls characters and normalizes line endings and spaces.
104:      * @param  string  UTF-8 encoding or 8-bit
105:      * @return string
106:      */
107:     public static function normalize($s)
108:     {
109:         // standardize line endings to unix-like
110:         $s = str_replace("\r\n", "\n", $s); // DOS
111:         $s = strtr($s, "\r", "\n"); // Mac
112: 
113:         // remove control characters; leave \t + \n
114:         $s = preg_replace('#[\x00-\x08\x0B-\x1F]+#', '', $s);
115: 
116:         // right trim
117:         $s = preg_replace("#[\t ]+$#m", '', $s);
118: 
119:         // trailing spaces
120:         $s = trim($s, "\n");
121: 
122:         return $s;
123:     }
124: 
125: 
126: 
127:     /**
128:      * Converts to ASCII.
129:      * @param  string  UTF-8 encoding
130:      * @return string  ASCII
131:      */
132:     public static function toAscii($s)
133:     {
134:         $s = preg_replace('#[^\x09\x0A\x0D\x20-\x7E\xA0-\x{10FFFF}]#u', '', $s);
135:         $s = strtr($s, '`\'"^~', "\x01\x02\x03\x04\x05");
136:         if (ICONV_IMPL === 'glibc') {
137:             $s = @iconv('UTF-8', 'WINDOWS-1250//TRANSLIT', $s); // intentionally @
138:             $s = strtr($s, "\xa5\xa3\xbc\x8c\xa7\x8a\xaa\x8d\x8f\x8e\xaf\xb9\xb3\xbe\x9c\x9a\xba\x9d\x9f\x9e\xbf\xc0\xc1\xc2\xc3\xc4\xc5\xc6\xc7\xc8\xc9\xca\xcb\xcc\xcd\xce\xcf\xd0\xd1\xd2"
139:                 ."\xd3\xd4\xd5\xd6\xd7\xd8\xd9\xda\xdb\xdc\xdd\xde\xdf\xe0\xe1\xe2\xe3\xe4\xe5\xe6\xe7\xe8\xe9\xea\xeb\xec\xed\xee\xef\xf0\xf1\xf2\xf3\xf4\xf5\xf6\xf8\xf9\xfa\xfb\xfc\xfd\xfe",
140:                 "ALLSSSSTZZZallssstzzzRAAAALCCCEEEEIIDDNNOOOOxRUUUUYTsraaaalccceeeeiiddnnooooruuuuyt");
141:         } else {
142:             $s = @iconv('UTF-8', 'ASCII//TRANSLIT', $s); // intentionally @
143:         }
144:         $s = str_replace(array('`', "'", '"', '^', '~'), '', $s);
145:         return strtr($s, "\x01\x02\x03\x04\x05", '`\'"^~');
146:     }
147: 
148: 
149: 
150:     /**
151:      * Converts to web safe characters [a-z0-9-] text.
152:      * @param  string  UTF-8 encoding
153:      * @param  string  allowed characters
154:      * @param  bool
155:      * @return string
156:      */
157:     public static function webalize($s, $charlist = NULL, $lower = TRUE)
158:     {
159:         $s = self::toAscii($s);
160:         if ($lower) $s = strtolower($s);
161:         $s = preg_replace('#[^a-z0-9' . preg_quote($charlist, '#') . ']+#i', '-', $s);
162:         $s = trim($s, '-');
163:         return $s;
164:     }
165: 
166: 
167: 
168:     /**
169:      * Truncates string to maximal length.
170:      * @param  string  UTF-8 encoding
171:      * @param  int
172:      * @param  string  UTF-8 encoding
173:      * @return string
174:      */
175:     public static function truncate($s, $maxLen, $append = "\xE2\x80\xA6")
176:     {
177:         if (self::length($s) > $maxLen) {
178:             $maxLen = $maxLen - self::length($append);
179:             if ($maxLen < 1) {
180:                 return $append;
181: 
182:             } elseif ($matches = self::match($s, '#^.{1,'.$maxLen.'}(?=[\s\x00-/:-@\[-`{-~])#us')) {
183:                 return $matches[0] . $append;
184: 
185:             } else {
186:                 return iconv_substr($s, 0, $maxLen, 'UTF-8') . $append;
187:             }
188:         }
189:         return $s;
190:     }
191: 
192: 
193: 
194:     /**
195:      * Indents the content from the left.
196:      * @param  string  UTF-8 encoding or 8-bit
197:      * @param  int
198:      * @param  string
199:      * @return string
200:      */
201:     public static function indent($s, $level = 1, $chars = "\t")
202:     {
203:         return $level < 1 ? $s : self::replace($s, '#(?:^|[\r\n]+)(?=[^\r\n])#', '$0' . str_repeat($chars, $level));
204:     }
205: 
206: 
207: 
208:     /**
209:      * Convert to lower case.
210:      * @param  string  UTF-8 encoding
211:      * @return string
212:      */
213:     public static function lower($s)
214:     {
215:         return mb_strtolower($s, 'UTF-8');
216:     }
217: 
218: 
219: 
220:     /**
221:      * Convert to upper case.
222:      * @param  string  UTF-8 encoding
223:      * @return string
224:      */
225:     public static function upper($s)
226:     {
227:         return mb_strtoupper($s, 'UTF-8');
228:     }
229: 
230: 
231: 
232:     /**
233:      * Convert first character to upper case.
234:      * @param  string  UTF-8 encoding
235:      * @return string
236:      */
237:     public static function firstUpper($s)
238:     {
239:         return self::upper(mb_substr($s, 0, 1, 'UTF-8')) . mb_substr($s, 1, self::length($s), 'UTF-8');
240:     }
241: 
242: 
243: 
244:     /**
245:      * Capitalize string.
246:      * @param  string  UTF-8 encoding
247:      * @return string
248:      */
249:     public static function capitalize($s)
250:     {
251:         return mb_convert_case($s, MB_CASE_TITLE, 'UTF-8');
252:     }
253: 
254: 
255: 
256:     /**
257:      * Case-insensitive compares UTF-8 strings.
258:      * @param  string
259:      * @param  string
260:      * @param  int
261:      * @return bool
262:      */
263:     public static function compare($left, $right, $len = NULL)
264:     {
265:         if ($len < 0) {
266:             $left = iconv_substr($left, $len, -$len, 'UTF-8');
267:             $right = iconv_substr($right, $len, -$len, 'UTF-8');
268:         } elseif ($len !== NULL) {
269:             $left = iconv_substr($left, 0, $len, 'UTF-8');
270:             $right = iconv_substr($right, 0, $len, 'UTF-8');
271:         }
272:         return self::lower($left) === self::lower($right);
273:     }
274: 
275: 
276: 
277:     /**
278:      * Returns UTF-8 string length.
279:      * @param  string
280:      * @return int
281:      */
282:     public static function length($s)
283:     {
284:         return function_exists('mb_strlen') ? mb_strlen($s, 'UTF-8') : strlen(utf8_decode($s));
285:     }
286: 
287: 
288: 
289:     /**
290:      * Strips whitespace.
291:      * @param  string  UTF-8 encoding
292:      * @param  string
293:      * @return string
294:      */
295:     public static function trim($s, $charlist = " \t\n\r\0\x0B\xC2\xA0")
296:     {
297:         $charlist = preg_quote($charlist, '#');
298:         return self::replace($s, '#^['.$charlist.']+|['.$charlist.']+$#u', '');
299:     }
300: 
301: 
302: 
303:     /**
304:      * Pad a string to a certain length with another string.
305:      * @param  string  UTF-8 encoding
306:      * @param  int
307:      * @param  string
308:      * @return string
309:      */
310:     public static function padLeft($s, $length, $pad = ' ')
311:     {
312:         $length = max(0, $length - self::length($s));
313:         $padLen = self::length($pad);
314:         return str_repeat($pad, $length / $padLen) . iconv_substr($pad, 0, $length % $padLen, 'UTF-8') . $s;
315:     }
316: 
317: 
318: 
319:     /**
320:      * Pad a string to a certain length with another string.
321:      * @param  string  UTF-8 encoding
322:      * @param  int
323:      * @param  string
324:      * @return string
325:      */
326:     public static function padRight($s, $length, $pad = ' ')
327:     {
328:         $length = max(0, $length - self::length($s));
329:         $padLen = self::length($pad);
330:         return $s . str_repeat($pad, $length / $padLen) . iconv_substr($pad, 0, $length % $padLen, 'UTF-8');
331:     }
332: 
333: 
334: 
335:     /**
336:      * Generate random string.
337:      * @param  int
338:      * @param  string
339:      * @return string
340:      */
341:     public static function random($length = 10, $charlist = '0-9a-z')
342:     {
343:         $charlist = str_shuffle(preg_replace_callback('#.-.#', function($m) {
344:             return implode('', range($m[0][0], $m[0][2]));
345:         }, $charlist));
346:         $chLen = strlen($charlist);
347: 
348:         $s = '';
349:         for ($i = 0; $i < $length; $i++) {
350:             if ($i % 5 === 0) {
351:                 $rand = lcg_value();
352:                 $rand2 = microtime(TRUE);
353:             }
354:             $rand *= $chLen;
355:             $s .= $charlist[($rand + $rand2) % $chLen];
356:             $rand -= (int) $rand;
357:         }
358:         return $s;
359:     }
360: 
361: 
362: 
363:     /**
364:      * Splits string by a regular expression.
365:      * @param  string
366:      * @param  string
367:      * @param  int
368:      * @return array
369:      */
370:     public static function split($subject, $pattern, $flags = 0)
371:     {
372:         Debug::tryError();
373:         $res = preg_split($pattern, $subject, -1, $flags | PREG_SPLIT_DELIM_CAPTURE);
374:         self::catchPregError($pattern);
375:         return $res;
376:     }
377: 
378: 
379: 
380:     /**
381:      * Performs a regular expression match.
382:      * @param  string
383:      * @param  string
384:      * @param  int
385:      * @param  int
386:      * @return mixed
387:      */
388:     public static function match($subject, $pattern, $flags = 0, $offset = 0)
389:     {
390:         Debug::tryError();
391:         $res = preg_match($pattern, $subject, $m, $flags, $offset);
392:         self::catchPregError($pattern);
393:         if ($res) {
394:             return $m;
395:         }
396:     }
397: 
398: 
399: 
400:     /**
401:      * Performs a global regular expression match.
402:      * @param  string
403:      * @param  string
404:      * @param  int  (PREG_SET_ORDER is default)
405:      * @param  int
406:      * @return array
407:      */
408:     public static function matchAll($subject, $pattern, $flags = 0, $offset = 0)
409:     {
410:         Debug::tryError();
411:         $res = preg_match_all($pattern, $subject, $m, ($flags & PREG_PATTERN_ORDER) ? $flags : ($flags | PREG_SET_ORDER), $offset);
412:         self::catchPregError($pattern);
413:         return $m;
414:     }
415: 
416: 
417: 
418:     /**
419:      * Perform a regular expression search and replace.
420:      * @param  string
421:      * @param  string|array
422:      * @param  string|callback
423:      * @param  int
424:      * @return string
425:      */
426:     public static function replace($subject, $pattern, $replacement = NULL, $limit = -1)
427:     {
428:         Debug::tryError();
429:         if (is_object($replacement) || is_array($replacement)) {
430:             if ($replacement instanceof Callback) {
431:                 $replacement = $replacement->getNative();
432:             }
433:             if (!is_callable($replacement, FALSE, $textual)) {
434:                 Debug::catchError($foo);
435:                 throw new \InvalidStateException("Callback '$textual' is not callable.");
436:             }
437:             $res = preg_replace_callback($pattern, $replacement, $subject, $limit);
438: 
439:             if (Debug::catchError($e)) { // compile error
440:                 $trace = $e->getTrace();
441:                 if (isset($trace[2]['class']) && $trace[2]['class'] === __CLASS__) {
442:                     throw new RegexpException($e->getMessage() . " in pattern: $pattern");
443:                 }
444:             }
445: 
446:         } elseif (is_array($pattern)) {
447:             $res = preg_replace(array_keys($pattern), array_values($pattern), $subject, $limit);
448: 
449:         } else {
450:             $res = preg_replace($pattern, $replacement, $subject, $limit);
451:         }
452:         self::catchPregError($pattern);
453:         return $res;
454:     }
455: 
456: 
457: 
458:     /** @internal */
459:     public static function catchPregError($pattern)
460:     {
461:         if (Debug::catchError($e)) { // compile error
462:             throw new RegexpException($e->getMessage() . " in pattern: $pattern");
463: 
464:         } elseif (preg_last_error()) { // run-time error
465:             static $messages = array(
466:                 PREG_INTERNAL_ERROR => 'Internal error',
467:                 PREG_BACKTRACK_LIMIT_ERROR => 'Backtrack limit was exhausted',
468:                 PREG_RECURSION_LIMIT_ERROR => 'Recursion limit was exhausted',
469:                 PREG_BAD_UTF8_ERROR => 'Malformed UTF-8 data',
470:                 5 => 'Offset didn\'t correspond to the begin of a valid UTF-8 code point', // PREG_BAD_UTF8_OFFSET_ERROR
471:             );
472:             $code = preg_last_error();
473:             throw new RegexpException((isset($messages[$code]) ? $messages[$code] : 'Unknown error') . " (pattern: $pattern)", $code);
474:         }
475:     }
476: 
477: }
478:
Namespaces

Classes

Interfaces
