String Functions
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(string $s): string
Converts all characters of UTF-8 string to lower case.
echo Strings::lower('Hello world'); // hello world
upper(string $s): string
Converts all characters of a UTF-8 string to upper case.
echo Strings::upper('Hello world'); // HELLO WORLD
firstUpper(string $s): string
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
firstLower(string $s): string
Converts the first character of a UTF-8 string to lower case and leaves the other characters unchanged.
echo Strings::firstLower('Hello world'); // hello world
capitalize(string $s): string
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(string $s): string
Removes right-side spaces, control sequences and unifies line endings to \n
.
webalize(string $s, string $charlist=null, bool $lower=true): string
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(string $s, string $charlist=null): string
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(string $s, int $maxLen, string
$append='…'
): string
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(string $s, int $level=1, string
$indentationChar="\t"
): string
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(string $s, int $length, string
$pad=' '
): string
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(string $s, int $length, string
$pad=' '
): string
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'
substring(string $s, int $start, int $length=null): string
Returns a part of UTF-8 string.
echo Strings::substring('Nette is great', 0, 5); // 'Nette'
echo Strings::substring('Nette is great', 6, 2); // 'is'
echo Strings::substring('Nette is great', 9); // 'great'
normalizeNewLines(string $s): string
Standardize line endings to unix-like.
$unixLikeLines = Strings::normalizeNewLines($string);
reverse(string $s): string
Reverse UTF-8 string.
echo Strings::reverse('Nette'); // 'etteN'
length(string $s): int
Returns a length of a UTF-8 string.
echo Strings::length('Nette'); // '5'
echo Strings::length('červená'); // '7'
startsWith(string $haystack, string $needle): bool
Returns true
if $haystack
string begins with $needle
.
$haystack = 'Begins';
$needle = 'Be';
Strings::startsWith($haystack, $needle); // true
endsWith(string $haystack, string $needle): bool
Returns true
if $haystack
string end with $needle
.
$haystack = 'Ends';
$needle = 'ds';
Strings::endsWith($haystack, $needle); // true
contains(string $haystack, string $needle): bool
Returns true
if $haystack
string contains $needle
.
$haystack = 'Contains';
$needle = 'tai';
Strings::contains($haystack, $needle); // true
compare(string $left, string $right, int $len=null): bool
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
findPrefix(…$strings): string
Finds the common prefix of strings or returns empty string if the prefix was not found.
echo Strings::findPrefix('prefix-Nette', 'prefix-is', 'prefix-great'); // 'prefix-'
echo Strings::findPrefix(['prefix-Nette', 'prefix-is', 'prefix-great']); // 'prefix-'
echo Strings::findPrefix('Nette', 'is', 'great'); // ''
before(string $haystack, string $needle, int $nth=1): ?string
Returns part of $haystack
before $nth
occurence of $needle
or returns null
if the needle was not found. Negative value means searching from the end.
echo Strings::before('Nette_is_great', '_', 1); // 'Nette'
echo Strings::before('Nette_is_great', '_', -2); // 'Nette'
echo Strings::before('Nette_is_great', ' '); // null
echo Strings::before('Nette_is_great', '_', 3); // null
Version 2 returns false
instead of null
.
after(string $haystack, string $needle, int $nth=1): ?string
Returns part of $haystack
after $nth
occurence of $needle
or returns null
if the $needle
was not found. Negative value of $nth
means searching from the end.
echo Strings::after('Nette_is_great', '_', 2); // 'great'
echo Strings::after('Nette_is_great', '_', -1); // 'great'
echo Strings::after('Nette_is_great', ' '); // null
echo Strings::after('Nette_is_great', '_', 3); // null
Version 2 returns false
instead of null
.
indexOf(string $haystack, string $needle, int $nth=1): ?int
Returns position of $nth
occurence of $needle
in $haystack
or null
if the
$needle
was not found. Negative value of $nth
means searching from the end.
echo Strings::indexOf('abc abc abc', 'abc', 2); // 4
echo Strings::indexOf('abc abc abc', 'abc', -1); // 8
echo Strings::indexOf('abc abc abc', 'd'); // null
Version 2 returns false
instead of null
.
Encoding
fixEncoding(string $s): string
Removes all invalid UTF-8 characters from a string.
$correctStrings = Strings::fixEncoding($string);
checkEncoding(string $s): bool
Checks if the string is valid for UTF-8 encoding.
$isUtf8 = Strings::checkEncoding($string);
toAscii(string $s): string
Converts string to ASCII.
echo Strings::toAscii('žluťoučký kůň'); // zlutoucky kun
chr(string $code): string
Returns a specific character in UTF-8.
echo Strings::chr(0xA9); // creates '©'
Regular Expressions
Class Strings 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.
split(string $subject, string $pattern, int $flags=null): array
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*~');
// ['One', 'two', 'three']
$res = Strings::split('One, two,three', '~(,)\s*~');
// ['One', ',', 'two', ',', 'three']
match(string $subject, string $pattern, int $flags=null, int $offset=0): array
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
matchAll(string $subject, string $pattern, int $flags=null, int $offset=0): array
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');
/*
[
0 => ['One'],
1 => ['two'],
2 => ['three'],
]
*/
$res = Strings::matchAll('One, two,three', '~\d+~'); // []
replace(string $subject, string $pattern, string $replacement=null, int $limit=-1): string
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', [
'~[a-z]+~i' => '*',
'~\s+~' => '+',
]);
// '*,+*,*'
echo Strings::replace('One, two,three', '~[a-z]+~i', function (array $m): string {
return strrev($m[0]);
});
// 'enO, owt,eerht'