Práce s řetězci

Nette\Utils\Strings je statická třída s užitečnými funkcemi pro práci s řetězci převážně v kódování UTF-8.

Všechny příklady předpokládají vytvořený alias:

use Nette\Utils\Strings;

Změna velikosti písmen

lower(string $s): string

Převede UTF-8 řetězec na malá písmena.

echo Strings::lower('Dobrý den'); // dobrý den

upper(string $s): string

Převede UTF-8 řetězec na velká písmena.

echo Strings::upper('Dobrý den'); // DOBRÝ DEN

firstUpper(string $s): string

Převede první písmeno UTF-8 řetězce na velké, ostatní nemění.

echo Strings::firstUpper('dobrý den'); // Dobrý den

firstLower(string $s): string

Převede první písmeno UTF-8 řetězce na malé, ostatní nemění.

echo Strings::firstLower('Dobrý den'); // dobrý den

capitalize(string $s): string

Převede první písmeno každého slova v UTF-8 řetězci na velké, ostatní na malé.

echo Strings::capitalize('Dobrý den'); // Dobrý Den

Úprava řetězce

normalize(string $s): string

Odstraní z textu pravostranné mezery, řídící znaky a sjednotí oddělovače řádků na \n.

webalize(string $s, string $charlist=null, bool $lower=true): string

Upraví UTF-8 řetězec do tvaru používaného v URL, tj. odstraní diakritiku a všechny znaky kromě písmen anglické abecedy a číslic nahradí spojovníkem.

echo Strings::webalize('náš produkt'); // nas-produkt

Mají-li být zachovány i jiné znaky, lze je uvést v druhém parametru funkce.

echo Strings::webalize('10. obrázek_id', '._'); // 10.-obrazek_id

Třetím parametrem lze potlačit převádění na malá písmenka.

echo Strings::webalize('Dobrý den', null, false); // Dobry-den

trim(string $s, string $charlist=null): string

Ořízne mezery (nebo jiné znaky určené druhým parametrem) ze začátku a konce UTF-8 řetězce.

echo Strings::trim('  Hello  '); // 'Hello'

truncate(string $s, int $maxLen, string $append='…'): string

Ořízne UTF-8 řetězec na uvedenou maximální délku, přičemž se snaží zachovávat celá slova. Pokud dojde ke zkrácení řetězce, přidá nakonec trojtečku (lze změnit třetím parametrem).

$text = 'Řekněte, jak se máte?';
echo Strings::truncate($text, 5); // 'Řekn…'
echo Strings::truncate($text, 20); // 'Řekněte, jak se…'
echo Strings::truncate($text, 30); // 'Řekněte, jak se máte?'
echo Strings::truncate($text, 20, '~'); // 'Řekněte, jak se~'

indent(string $s, int $level=1, string $indentationChar="\t"): string

Odsadí víceřádkový text zleva. Počet odsazení určuje druhý parametr, čím odsazovat parametr třetí (výchozí hodnotou je tabulátor).

echo Strings::indent('Nette'); // '	Nette'
echo Strings::indent('Nette', 2, '+'); // '++Nette'

padLeft(string $s, int $length, string $pad=' '): string

Doplní UTF-8 řetězec na zadanou délku opakováním řetězce $pad zleva.

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

Doplní UTF-8 řetězec na zadanou délku opakováním řetězce $pad zprava.

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

Vrátí vybranou část UTF-8 řetězce.

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

Sjednotí v řetězci konce řádků na typ používaný v unixových systémech.

$unixLikeLines = Strings::normalizeNewLines($string);

reverse(string $s): string

Obrátí UTF-8 řetězec.

echo Strings::reverse('Nette'); // 'etteN'

length(string $s): int

Vrací délku UTF-8 řetězce.

echo Strings::length('Nette'); // '5'
echo Strings::length('červená'); // '7'

startsWith(string $haystack, string $needle): bool

Vrací true v případě, že řetězec $haystack začíná řetězcem $needle.

$haystack = 'Začíná';
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true

endsWith(string $haystack, string $needle): bool

Vrací true v případě, že řetězec $haystack končí řetězcem $needle.

$haystack = 'Končí';
$needle = 'čí';
Strings::endsWith($haystack, $needle); // true

contains(string $haystack, string $needle): bool

Vrací true v případě, že řetězec $haystack obsahuje $needle.

$haystack = 'Posluchárna';
$needle = 'sluch';
Strings::contains($haystack, $needle); // true

compare(string $left, string $right, int $len=null): bool

Porovnání dvou UTF-8 řetězců nebo jejich částí bez ohledu na velikost písmen. Pokud je $len větší než nula, porovnává se příslušný počet znaků na začátku řetězců, pokud je menší než nula, porovnává se příslušný počet posledních znaků řetězců a pokud je argument roven nule, porovnávají se celé řetězce.

echo Strings::compare('Nette', 'nette'); // true
echo Strings::compare('Nette', 'next', 2); // true - shoda prvních 2 znaků
echo Strings::compare('Nette', 'Latte', -2); // true - shoda posledních 2 znaků

findPrefix(…$strings): string

Najde společný začátek řetězců. Nebo vrátí prázdný řetězec, pokud společná předpona nebyla nalezena.

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|false

Vrátí část řetězce $haystack před n-tým $nth výskytem řetězce $needle. Nebo false, pokud $needle nebyl nalezen. Při záporné hodnotě $nth se hledá od konce řetězce.

echo Strings::before('Nette_is_great', '_', 1); // 'Nette'
echo Strings::before('Nette_is_great', '_', -2); // 'Nette'
echo Strings::before('Nette_is_great', ' '); // false
echo Strings::before('Nette_is_great', '_', 3); // false

Od verze 3 bude vracet null místo false.

after(string $haystack, string $needle, int $nth=1): string|false

Vrátí část řetězce $haystack po n-tém $nth výskytu řetězce $needle. Nebo false, pokud $needle nebyl nalezen. Při záporné hodnotě $nth se hledá od konce řetězce.

echo Strings::after('Nette_is_great', '_', 2); // 'great'
echo Strings::after('Nette_is_great', '_', -1); // 'great'
echo Strings::after('Nette_is_great', ' '); // false
echo Strings::after('Nette_is_great', '_', 3); // false

Od verze 3 bude vracet null místo false.

indexOf(string $haystack, string $needle, int $nth=1): int|false

Vrátí pozici n-tého $nth výskýtu řetězce $needle v řetězci $haystack. Nebo false, pokud nebyl $needle nalezen. Při záporné hodnotě $nth se hledá od konce řetězce.

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'); // false

Od verze 3 bude vracet null místo false.

Kódování

fixEncoding(string $s): string

Odstraní z řetězce neplatné UTF-8 znaky.

$correctStrings = Strings::fixEncoding($string);

checkEncoding(string $s): bool

Zjistí, jestli jde o UTF-8 řetězec.

$isUtf8 = Strings::checkEncoding($string);

toAscii(string $s): string

Odstraní z UTF-8 řetězce diakritiku.

echo Strings::toAscii('žluťoučký kůň'); // zlutoucky kun

chr(int $code): string

Vytvoří znak dle zadaného Unicode kódu a vrátí ho v požadovaném kódování.

echo Strings::chr(0xA9); // vytvoří znak '©' v kódování UTF-8
echo Strings::chr(0x2026, 'CP1250'); // trojtečka v kódování CP1250

Regulární výrazy

Třída Strings zapouzdřuje několik funkcí pro práci s regulárními výrazy. Na rozdíl od nativních PHP funkcí disponuje čitelnějším API a především jakákoliv chyba při kompilaci nebo zpracování výrazu vyhodí výjimku Nette\RegexpException.

split(string $subject, string $pattern, int $flags=null): array

Rozdělí řetězec do pole podle regulárního výrazu. Jako $flag je možné uvést stejné příznaky jako u funkce preg_split, s tím, že příznak PREG_SPLIT_DELIM_CAPTURE je nastaven vždy.

$res = Strings::split('Prvni,  druhy,treti', '~,\s*~');
// ['Prvni', 'druhy', 'treti']
$res = Strings::split('Prvni,  druhy,treti', '~(,)\s*~');
// ['Prvni', ',', 'druhy', ',', 'treti']

match(string $subject, string $pattern, int $flags=null, int $offset=0): array

Zjistí, jestli zadaný řetězec odpovídá regulárnímu výrazu, a vrátí pole s nalezeným výrazem a jednotlivými podvýrazy. Jako $flag je možné uvést stejné příznaky jako u funkce preg_match.

list($res) = Strings::match('Prvni,  druhy,treti', '~[a-z]+~i'); // 'Prvni'
list($res) = Strings::match('Prvni,  druhy,treti', '~\d+~'); // null

matchAll(string $subject, string $pattern, int $flags=null, int $offset=0): array

Hledá v řetězci všechny výskyty odpovídající regulárnímu výrazu a vrátí je jako dvourozměrné pole. Jako $flag je možné uvést stejné příznaky jako u funkce preg_match_all, s tím rozdílem, že příznak PREG_SET_ORDER je výchozí hodnotou.

$res = Strings::matchAll('Prvni,  druhy,treti', '~[a-z]+~i');
/*
[
	0 => ['Prvni'],
	1 => ['druhy'],
	2 => ['treti'],
]
*/

$res = Strings::matchAll('Prvni,  druhy,treti', '~\d+~'); // []

replace(string $subject, string $pattern, string $replacement=null, int $limit=-1): string

Provede v řetězci záměny dle regulárního výrazu. Ten je určen druhým parametrem metody a nemusí být pouze textovým řetězcem, ale může být i asociativním polem ve tvaru pattern ⇒ replacement. Jako třetí parametr lze uvést nahrazovací callback a čtvrtým parametrem lze limitovat počet nahrazení.

echo Strings::replace('Prvni,  druhy,treti', '~[a-z]+~i', '*');
// '*,  *,*'

echo Strings::replace('Prvni,  druhy,treti', [
	'~[a-z]+~i' => '*',
	'~\s+~' => '+',
]);
// '*,+*,*'

echo Strings::replace('Prvni,  druhy,treti', '~[a-z]+~i', function ($m) {
	return strrev($m[0]);
});
// 'invrP,  yhurd,itert'