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.
Instalace:
composer require nette/utils
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.
Strings::lower('Dobrý den'); // 'dobrý den'
upper(string $s): string
Převede UTF-8 řetězec na velká písmena.
Strings::upper('Dobrý den'); // 'DOBRÝ DEN'
firstUpper(string $s): string
Převede první písmeno UTF-8 řetězce na velké, ostatní nemění.
Strings::firstUpper('dobrý den'); // 'Dobrý den'
firstLower(string $s): string
Převede první písmeno UTF-8 řetězce na malé, ostatní nemění.
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é.
Strings::capitalize('Dobrý den'); // 'Dobrý Den'
Úprava řetězce
normalize(string $s): string
Odstraňuje kontrolní znaky, normalizuje konce řádků na \n, ořízne úvodní a koncové prázdné řádky,
ořízne pravostranné mezery na řádcích, normalizuje UTF-8 na normální formu NFC.
normalizeNewLines(string $s): string
Sjednotí v řetězci konce řádků na typ používaný v unixových systémech.
$unixLikeLines = Strings::normalizeNewLines($string);
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.
Strings::webalize('náš produkt'); // 'nas-produkt'
Mají-li být zachovány i jiné znaky, lze je uvést v druhém parametru funkce.
Strings::webalize('10. obrázek_id', '._'); // '10.-obrazek_id'
Třetím parametrem lze potlačit převádění na malá písmenka.
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.
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á na konec trojtečku (lze změnit třetím parametrem).
$text = 'Řekněte, jak se máte?';
Strings::truncate($text, 5); // 'Řekn…'
Strings::truncate($text, 20); // 'Řekněte, jak se…'
Strings::truncate($text, 30); // 'Řekněte, jak se máte?'
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).
Strings::indent('Nette'); // "\tNette"
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.
Strings::padLeft('Nette', 6); // ' Nette'
Strings::padLeft('Nette', 8, '+*'); // '+*+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.
Strings::padRight('Nette', 6); // 'Nette '
Strings::padRight('Nette', 8, '+*'); // 'Nette+*+'
substring(string $s, int $start, int $length=null): string
Vrátí část UTF-8 řetězce $s zadanou počáteční pozicí $start a délkou
$length. Pokud je $start záporný, bude vrácený řetězec začínat znakem -$start
znakem od konce.
Strings::substring('Nette Framework', 0, 5); // 'Nette'
Strings::substring('Nette Framework', 6); // 'Framework'
Strings::substring('Nette Framework', -4); // 'work'
reverse(string $s): string
Obrátí UTF-8 řetězec.
Strings::reverse('Nette'); // 'etteN'
length(string $s): int
Vrací počet znaků (nikoli bytů) v řetězci UTF-8.
To je počet kódových bodů Unicode, které se mohou lišit od počtu grafémů.
Strings::length('Nette'); // 5
Strings::length('červená'); // 7
startsWith(string $haystack, string $needle): bool
Zjistí jestli řetězec $haystack začíná řetězcem $needle.
$haystack = 'Začíná';
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true
endsWith(string $haystack, string $needle): bool
Zjistí jestli řetězec $haystack končí řetězcem $needle.
$haystack = 'Končí';
$needle = 'čí';
Strings::endsWith($haystack, $needle); // true
contains(string $haystack, string $needle): bool
Zjistí jestli řetězec $haystack obsahuje $needle.
$haystack = 'Posluchárna';
$needle = 'sluch';
Strings::contains($haystack, $needle); // true
compare(string $left, string $right, int $length=null): bool
Porovnání dvou UTF-8 řetězců nebo jejich částí bez ohledu na velikost písmen. Pokud $length obsahuje
null, porovnávají se celé řetězce, pokud je záporný, porovnává se příslušný počet znaků od konce řetězců, jinak
se porovnává příslušný počet znaků od začátku.
Strings::compare('Nette', 'nette'); // true
Strings::compare('Nette', 'next', 2); // true - shoda prvních 2 znaků
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.
Strings::findPrefix('prefix-a', 'prefix-bb', 'prefix-c'); // 'prefix-'
Strings::findPrefix(['prefix-a', 'prefix-bb', 'prefix-c']); // 'prefix-'
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.
Strings::before('Nette_is_great', '_', 1); // 'Nette'
Strings::before('Nette_is_great', '_', -2); // 'Nette'
Strings::before('Nette_is_great', ' '); // false
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.
Strings::after('Nette_is_great', '_', 2); // 'great'
Strings::after('Nette_is_great', '_', -1); // 'great'
Strings::after('Nette_is_great', ' '); // false
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 v bajtech 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.
Strings::indexOf('abc abc abc', 'abc', 2); // 4
Strings::indexOf('abc abc abc', 'abc', -1); // 8
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 platný UTF-8 řetězec.
$isUtf8 = Strings::checkEncoding($string);
toAscii(string $s): string
Převede řetězec UTF-8 na ASCII, tj. odebere diakritiku atd.
Strings::toAscii('žluťoučký kůň'); // 'zlutoucky kun'
chr(int $code): string
Vrací specifický znak v UTF-8 z kódového bodu (číslo v rozsahu 0×0000..D7FF a 0×E000..10FFFF).
Strings::chr(0xA9); // '©' v kódování UTF-8
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.
Volitelný parametr $offset lze použít k určení alternativního místa, od kterého se má začít hledat
(v bajtech, nikoliv ve znakech!).
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.
Volitelný parametr $offset lze použít k určení alternativního místa, od kterého se má začít hledat
(v bajtech, nikoliv ve znakech!).
$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|array $pattern, string|callable $replacement=null, int $limit=-1): string
Nahrazuje všechny výskyty odpovídající regulárnímu výrazu $pattern, který může být řetězec nebo pole
ve tvaru pattern => replacement. Třetí argument je náhradní řetězec nebo callback a čtvrtý omezuje
počet záměn.
Strings::replace('Prvni, druhy,treti', '~[a-z]+~i', '*');
// '*, *,*'
Strings::replace('Prvni, druhy,treti', [
'~[a-z]+~i' => '*',
'~\s+~' => '+',
]);
// '*,+*,*'
Strings::replace('Prvni, druhy,treti', '~[a-z]+~i', function ($m) {
return strrev($m[0]);
});
// 'invrP, yhurd,itert'