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'