Práce s řetězci – Nette\Utils\Strings

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($s)

Převede UTF-8 řetězec na malá písmena.

echo Strings::lower('Dobrý den'); // dobrý den

upper($s)

Převede UTF-8 řetězec na velká písmena.

echo Strings::upper('Dobrý den'); // DOBRÝ DEN

firstUpper($s)

Převede první písmeno UTF-8 řetězce na velké, ostatní nemění.

echo Strings::firstUpper('dobrý den'); // Dobrý den

capitalize($s)

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($s)

Odstraní z textu pravostranné mezery, řídící znaky a sjednotí oddělovače řádků na \n.

webalize($s, $charlist=NULL, $lower=TRUE)

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($s, $charlist=NULL)

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($s, $maxLen, $append='…')

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($s, $level=1, $indentationChar="\t")

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($s, $length, $pad=' ')

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($s, $length, $pad=' ')

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'

int length($s)

Vrací délku UTF-8 řetězce.

echo Strings::length('Nette'); // '5'
echo Strings::length('červená'); // '7'

bool startsWith($haystack, $needle)

Vrací TRUE v případě, že řetězec $haystack začíná řetězcem $needle.

$haystack = 'Začíná';
$needle = 'Za';
Strings::startsWith($haystack, $needle); // TRUE

bool endsWith($haystack, $needle)

Vrací TRUE v případě, že řetězec $haystack končí řetězcem $needle.

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

bool contains($haystack, $needle)

Vrací TRUE v případě, že řetězec $haystack obsahuje $needle.

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

bool compare($left, $right, $len=NULL)

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ů

chr($code)

Vytvoří znak dle zadaného Unicode kódu a vrátí ho v UTF-8.

echo Strings::chr(0xA9); // vytvoří znak '©'

random($length=10, $charlist='0-9a-z')

Vygeneruje náhodný řetězec o dané délce ze znaků specifikovaných parametrem $charlist. Lze používat i intervaly zapsané jako třeba 0-9.

echo Strings::random(); // '6zq3a1nl8n'
echo Strings::random(5, 'A-Z'); // 'HLKUR'

Kódování

fixEncoding($s)

Odstraní z řetězce neplatné UTF-8 znaky.

$correctStrings = Strings::fixEncoding($string);

bool checkEncoding($s)

Zjistí, jestli jde o UTF-8 řetězec.

$isUtf8 = Strings::checkEncoding($string);

toAscii($s)

Odstraní z UTF-8 řetězce diakritiku.

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

chr($code, $encoding='UTF-8')

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.

array split($subject, $pattern, $flags=NULL)

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

array match($subject, $pattern, $flags=NULL, $offset=0)

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

array matchAll($subject, $pattern, $flags=NULL, $offset=0)

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($subject, $pattern, $replacement=NULL, $limit=-1)

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'