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

Vyžaduje PHP rozšíření mbstring.

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 ve znacích 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 0xE000..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 znacích!).

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 znacích!).

$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'