You are browsing the unmaintained documentation for old Nette 2.1. See documentation for current Nette.

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'

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.

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'

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.

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

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 $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(array('prefix-a', 'prefix-bb', 'prefix-c')); // 'prefix-'
Strings::findPrefix('Nette', 'is', 'great');                // ''

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*~');
// array('Prvni', 'druhy', 'treti')
$res = Strings::split('Prvni,  druhy,treti', '~(,)\s*~');
// array('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 => array('Prvni'),
	1 => array('druhy'),
	2 => array('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', array(
	'~[a-z]+~i' => '*',
	'~\s+~' => '+',
));
// '*,+*,*'

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