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

Tyto funkce vyžadují 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.

unixNewLines(string $s): string

Převede konce řádků na \n používané v unixových systémech. Konce řádků jsou: \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

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

platformNewLines(string $s): string

Převede konce řádků na znaky specifické pro aktuální platformu, tj. \r\n na Windows a \n jinde. Konce řádků jsou: \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

$platformLines = Strings::platformNewLines($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'

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

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

Používejte nativní str_starts_with().

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

Zjistí jestli řetězec $haystack končí řetězcem $needle.

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

Používejte nativní str_ends_with().

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

Zjistí jestli řetězec $haystack obsahuje $needle.

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

Používejte nativní str_contains().

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

Vrátí část řetězce $haystack před n-tým $nth výskytem řetězce $needle. Nebo null, 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', ' ');     // null
Strings::before('Nette_is_great', '_', 3);  // null

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

Vrátí část řetězce $haystack po n-tém $nth výskytu řetězce $needle. Nebo null, 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', ' ');     // null
Strings::after('Nette_is_great', '_', 3);  // null

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

Vrátí pozici ve znacích n-tého $nth výskýtu řetězce $needle v řetězci $haystack. Nebo null, 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');       // null

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);

Použijte Nette\Utils\Validator::isUnicode().

toAscii(string $s): string

Převede řetězec UTF-8 na ASCII, tj. odebere diakritiku atd.

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

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

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

ord(string $char): int

Vrací kódový bod konkrétního znaku v UTF-8 (číslo v rozsahu 0×0000..D7FF nebo 0xE000..10FFFF).

Strings::ord('©'); // 0xA9

Regulární výrazy

Třída Strings nabízí funkce pro práci s regulárními výrazy. Na rozdíl od nativních PHP funkcí disponují srozumitelnějším API, lepší podporou Unicode a především detekcí chyb. Jakákoliv chyba při kompilaci nebo zpracování výrazu vyhodí výjimku Nette\RegexpException.

split(string $subject, string $pattern, bool $captureOffset=false, bool $skipEmpty=false, int $limit=-1, bool $utf8=false): array

Rozdělí řetězec do pole podle regulárního výrazu. Výrazy v závorkách budou zachyceny a vráceny také.

Strings::split('hello, world', '~,\s*~');
// ['hello', 'world']

Strings::split('hello, world', '~(,)\s*~');
// ['hello', ',', 'world']``

Pokud $skipEmpty je true, budou vráceny pouze neprázdné položky:

Strings::split('hello, world, ', '~,\s*~');
// ['hello', 'world', '']

Strings::split('hello, world, ', '~,\s*~', skipEmpty: true);
// ['hello', 'world']

Je-li zadáno $limit, budou vráceny pouze podřetězce do limitu a zbytek řetězce bude umístěn do posledního prvku. Limit –1 nebo 0 znamená žádné omezení.

Strings::split('hello, world, third', '~,\s*~', limit: 2);
// ['hello', 'world, third']

Pokud $utf8 je true, přepne se vyhodnocování do Unicode režimu. Podobně jako když uvedete modifikátor u.

Pokud $captureOffset je true, bude pro každou vyskytující se shodu vrácena také její pozice v řetězci (v bajtech; pokud je nastaveno $utf8 tak ve znacích). Tím se změní návratová hodnota na pole, kde každý prvek je dvojice složená z matchnutého řetězce a jeho pozice.

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true);
// [['žlutý', 0], ['kůň', 9]]

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true, utf8: true);
// [['žlutý', 0], ['kůň', 7]]

match(string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $utf8=false): ?array

Hledá v řetězci část odpovídající regulárnímu výrazu a vrátí pole s nalezeným výrazem a jednotlivými podvýrazy, nebo null.

Strings::match('hello!', '~\w+(!+)~');
// ['hello!', '!']

Strings::match('hello!', '~X~');
// null

Pokud $unmatchedAsNull je true, jsou nezachycené podvzory vráceny jako null; jinak jsou vráceny jako prázdný řetězec nebo nevráceny:

Strings::match('hello', '~\w+(!+)?~');
// ['hello']

Strings::match('hello', '~\w+(!+)?~', unmatchedAsNull: true);
// ['hello', null]

Pokud $utf8 je true, přepne se vyhodnocování do Unicode režimu. Podobně jako když uvedete modifikátor u:

Strings::match('žlutý kůň', '~\w+~');
// ['lut']

Strings::match('žlutý kůň', '~\w+~', utf8: true);
// ['žlutý']

Parametr $offset lze použít k určení pozice, od které se má začít hledat (v bajtech; pokud je nastaveno $utf8 tak ve znacích).

Pokud $captureOffset je true, bude pro každou vyskytující se shodu vrácena také její pozice v řetězci (v bajtech; pokud je nastaveno $utf8 tak ve znacích). Tím se změní návratová hodnota na pole, kde každý prvek je dvojice složená z matchnutého řetězce a jeho offsetu:

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true);
// [['lut', 2]]

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true);
// [['žlutý!', 0], ['!', 5]]

matchAll(string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $patternOrder=false, bool $utf8=false, bool $lazy=false): array|Generator

Hledá v řetězci všechny výskyty odpovídající regulárnímu výrazu a vrátí pole polí s nalezeným výrazem a jednotlivými podvýrazy.

Strings::matchAll('hello, world!!', '~\w+(!+)?~');
/* [
	0 => ['hello'],
	1 => ['world!!', '!!'],
] */

Pokud $patternOrder je true, změní se struktura výsledků tak, že v první položce je pole úplných shod vzoru, ve druhé je pole řetězců, kterým odpovídá první podvzor v závorce, a tak dále:

Strings::matchAll('hello, world!!', '~\w+(!+)?~', patternOrder: true);
/* [
	0 => ['hello', 'world!!'],
	1 => ['', '!!'],
] */

Pokud $unmatchedAsNull je true, jsou nezachycené podvzory vráceny jako null; jinak jsou vráceny jako prázdný řetězec nebo nevráceny:

Strings::matchAll('hello, world!!', '~\w+(!+)?~', unmatchedAsNull: true);
/* [
	0 => ['hello', null],
	1 => ['world!!', '!!'],
] */

Pokud $utf8 je true, přepne se vyhodnocování do Unicode režimu. Podobně jako když uvedete modifikátor u:

Strings::matchAll('žlutý kůň', '~\w+~');
/* [
	0 => ['lut'],
	1 => ['k'],
] */

Strings::matchAll('žlutý kůň', '~\w+~', utf8: true);
/* [
	0 => ['žlutý'],
	1 => ['kůň'],
] */

Parametr $offset lze použít k určení pozice, od které se má začít hledat (v bajtech; pokud je nastaveno $utf8 tak ve znacích).

Pokud $captureOffset je true, bude pro každou vyskytující se shodu vrácena také její pozice v řetězci (v bajtech; pokud je nastaveno $utf8 tak ve znacích). Tím se změní návratová hodnota na pole, kde každý prvek je dvojice složená z matchnutého řetězce a jeho pozice:

Strings::matchAll('žlutý kůň', '~\w+~', captureOffset: true);
/* [
	0 => [['lut', 2]],
	1 => [['k', 8]],
] */

Strings::matchAll('žlutý kůň', '~\w+~', captureOffset: true, utf8: true);
/* [
	0 => [['žlutý', 0]],
	1 => [['kůň', 6]],
] */

Pokud $lazy je true, funkce vrací Generator místo pole, což přináší významné výkonnostní výhody při práci s velkými řetězci. Generátor umožňuje vyhledávat shody postupně, místo celého řetězce najednou. To umožňuje efektivně pracovat i s extrémně velkými vstupními texty. Navíc můžete kdykoliv přerušit zpracování, pokud najdete hledanou shodu, což šetří výpočetní čas.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Nalezeno: $match[0]\n";
    // Zpracování může být kdykoli přerušeno
}

replace(string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string

Nahrazuje všechny výskyty odpovídající regulárnímu výrazu. $replacement je buď maska náhradního řetězce nebo callback.

Strings::replace('hello, world!', '~\w+~', '--');
// '--, --!'

Strings::replace('hello, world!', '~\w+~', fn($m) => strrev($m[0]));
// 'olleh, dlrow!'

Funkce také umožnuje provést více záměň tím, že ve druhém parametru předáme pole ve tvaru pattern => replacement:

Strings::replace('hello, world!', [
	'~\w+~' => '--',
	'~,\s+~' => ' ',
]);
// '-- --!'

Parametr $limit omezuje počet provedených záměň. Limit –1 znamená žádné omezení.

Pokud $utf8 je true, přepne se vyhodnocování do Unicode režimu. Podobně jako když uvedete modifikátor u.

Strings::replace('žlutý kůň', '~\w+~', '--');
// 'ž--ý --ůň'

Strings::replace('žlutý kůň', '~\w+~', '--', utf8: true);
// '-- --'

Pokud $captureOffset je true, bude pro každou vyskytující se shodu předána callbacku také její pozice v řetězci (v bajtech; pokud je nastaveno $utf8 tak ve znacích). Tím se změní podoba předávaného pole, kde každý prvek je dvojice složená z matchnutého řetězce a jeho pozice.

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// dumps [['lut', 2]] a [['k', 8]]

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// dumps [['žlutý', 0]] a [['kůň', 6]]

Pokud $unmatchedAsNull je true, jsou nezachycené podvzory předány do callbacku jako null; jinak jsou předány jako prázdný řetězec nebo nepředány:

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// dumps ['ac', 'a', '', 'c']

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// dumps ['ac', 'a', null, 'c']