String Processing – Nette\Utils\Strings
Nette\Utils\Strings is a static class, which contains many useful functions for working with UTF-8 encoded strings.
All examples assume the following class alias is defined:
use Nette\Utils\Strings;
Letter case
lower($s)
Converts all characters of UTF-8 string to lower case.
echo Strings::lower('Hello world'); // hello world
upper($s)
Converts all characters of a UTF-8 string to upper case.
echo Strings::upper('Hello world'); // HELLO WORLD
firstUpper($s)
Converts the first character of a UTF-8 string to upper case and leaves the other characters unchanged.
echo Strings::firstUpper('hello world'); // Hello world
capitalize($s)
Converts the first character of every word of a UTF-8 string to upper case and the others to lower case.
echo Strings::capitalize('Hello world'); // Hello World
Editing a string
normalize($s)
Removes right-side spaces, control sequences and unifies line endings to \n
.
webalize($s, $charlist=NULL, $lower=TRUE)
Adjusts a UTF-8 string for usage in URL, i.e. removes all accents and replaces all remaining characters except English alphabet letters and numerals with hyphens.
echo Strings::webalize('žluťoučký kůň'); // zlutoucky-kun
Other characters may be preserved as well, but they must be passed as second argument.
echo Strings::webalize('10. image_id', '._'); // 10.-image_id
The third argument may suppress converting the string to lower case.
echo Strings::webalize('Hello world', NULL, FALSE); // Hello-world
trim($s, $charlist=NULL)
Removes all left and right side spaces (or the characters passed as second argument) from a UTF-8 encoded string.
echo Strings::trim(' Hello '); // 'Hello'
truncate($s, $maxLen, $append='…'
)
Truncates a UTF-8 string to given maximal length, while trying not to split whole words. Only if the string is truncated, an ellipsis (or something else set with third argument) is appended to the string.
$text = 'Hello, how are you today?';
echo Strings::truncate($text, 5); // 'Hell…'
echo Strings::truncate($text, 20); // 'Hello, how are you…'
echo Strings::truncate($text, 30); // 'Hello, how are you today?'
echo Strings::truncate($text, 20, '~'); // 'Hello, how are you~'
indent($s, $level=1, $indentationChar="\t"
)
Indents a multiline text from the left. Second argument sets how many indentation chars should be used, while the indent itself is the third argument (tab by default).
echo Strings::indent('Nette'); // ' Nette'
echo Strings::indent('Nette', 2, '+'); // '++Nette'
padLeft($s, $length, $pad=' '
)
Pads a UTF-8 string to given length by prepending the $pad
string to the beginning.
echo Strings::padLeft('Nette', 6); // ' Nette'
echo Strings::padLeft('Nette', 8, '+'); // '+++Nette'
echo Strings::padLeft(' Nette', 11, 'WOW'); // 'WOWWO Nette'
padRight($s, $length, $pad=' '
)
Pads UTF-8 string to given length by appending the $pad
string to the end.
echo Strings::padRight('Nette', 6); // 'Nette '
echo Strings::padRight('Nette', 8, '+'); // 'Nette+++'
echo Strings::padRight('Nette is ', 16, 'great'); // 'Nette is greatgr'
fixEncoding($s)
Removes all invalid UTF-8 characters from a string.
$correctStrings = Strings::fixEncoding($string);
bool checkEncoding($s)
Checks if the string is valid for UTF-8 encoding.
$isUtf8 = Strings::checkEncoding($string);
int length($s)
Returns a length of a UTF-8 string.
echo Strings::length('Nette'); // '5'
echo Strings::length('červená'); // '7'
bool startsWith($haystack, $needle)
Returns TRUE
if $haystack
string begins with $needle
.
$haystack = 'Begins';
$needle = 'Be';
Strings::startsWith($haystack, $needle); // TRUE
bool endsWith($haystack, $needle)
Returns TRUE
if $haystack
string end with $needle
.
$haystack = 'Ends';
$needle = 'ds';
Strings::endsWith($haystack, $needle); // TRUE
bool contains($haystack, $needle)
Returns TRUE
if $haystack
string contains $needle
.
$haystack = 'Contains';
$needle = 'tai';
Strings::contains($haystack, $needle); // TRUE
bool compare($left, $right, $len=NULL)
Compares two UTF-8 strings or their parts, without taking character case into account. If $len
is greater then
zero, the respective amount of characters from the beginning of strings is compared, if it's negative, the respective amount of
characters from the end is compared, if it's equal to zero, whole strings are compared.
echo Strings::compare('Nette', 'nette'); // TRUE
echo Strings::compare('Nette', 'next', 2); // TRUE - two first characters match
echo Strings::compare('Nette', 'Latte', -2); // TRUE - two last characters match
chr($code)
Returns a specific character in UTF-8.
echo Strings::chr(0xA9); // creates '©'
Generating a string
random($length=10, $charlist='0-9a-z'
)
Generates a random string of given length from characters specified in second argument. Supports intervals, such as
0-9
or A-Z
.
echo Strings::random(); // '6zq3a1nl8n'
echo Strings::random(5, 'A-Z'); // 'HLKUR'
Regular expressions
Strings class contains a few methods for working with regular expressions. Unlike native php functions, it provides
readable API and throws Nette\RegexpException
if any regexp error occurs.
array split($subject, $pattern, $flags=NULL)
Splits a string into array by the regular expression. Argument $flag
takes same arguments as preg_split, but PREG_SPLIT_DELIM_CAPTURE
is set by default.
$res = Strings::split('One, two,three', '~,\s*~');
// array('One', 'two', 'three')
$res = Strings::split('One, two,three', '~(,)\s*~');
// array('One', ',', 'two', ',', 'three')
array match($subject, $pattern, $flags=NULL, $offset=0)
Checks if given string matches a regex pattern and returns an array with first found match and each subpattern. Argument
$flag
takes same arguments as function preg_match.
list($res) = Strings::match('One, two,three', '~[a-z]+~i'); // 'One'
list($res) = Strings::match('One, two,three', '~\d+~'); // NULL
array matchAll($subject, $pattern, $flags=NULL, $offset=0)
Finds all occurrences matching regular expression pattern and returns a two-dimensional array. Argument $flag
takes same arguments as function preg_match_all, but PREG_SET_ORDER
is
set by default.
$res = Strings::matchAll('One, two,tree', '~[a-z]+~i');
/*
array(
0 => array('One'),
1 => array('two'),
2 => array('three'),
)
*/
$res = Strings::matchAll('One, two,three', '~\d+~'); // array()
replace($subject, $pattern, $replacement=NULL, $limit=-1)
Replaces all occurrences matching regular expression, passed in as second argument. Though it might as well be a hash-map in
pattern => replacement
format. The third argument is a replacement string or a callback and the fourth limits the
count of replacements.
echo Strings::replace('One, two,three', '~[a-z]+~i', '*');
// '*, *,*'
echo Strings::replace('One, two,three', array(
'~[a-z]+~i' => '*',
'~\s+~' => '+',
));
// '*,+*,*'
echo Strings::replace('One, two,three', '~[a-z]+~i', function ($m) {
return strrev($m[0]);
});
// 'enO, owt,eerht'