Práce s řetězci
***************

.[perex]
[api: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:

```shell
composer require nette/utils
```

Všechny příklady předpokládají vytvořený alias:

```php
use Nette\Utils\Strings;
```


Změna velikosti písmen
======================

Tyto funkce vyžadují PHP rozšíření `mbstring`.


lower(string $s): string .[method]
----------------------------------

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

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


upper(string $s): string .[method]
----------------------------------

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

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


firstUpper(string $s): string .[method]
---------------------------------------

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

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


firstLower(string $s): string .[method]
---------------------------------------

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

```php
Strings::firstLower('Dobrý den'); // 'dobrý den'
```


capitalize(string $s): string .[method]
---------------------------------------

Převede první písmeno každého slova v UTF-8 řetězci na velké, ostatní na malé.

```php
Strings::capitalize('Dobrý den'); // 'Dobrý Den'
```


Úprava řetězce
==============


normalize(string $s): string .[method]
--------------------------------------

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 .[method]
----------------------------------------------

Sjednotí v řetězci konce řádků na typ používaný v unixových systémech.

```php
$unixLikeLines = Strings::normalizeNewLines($string);
```


webalize(string $s, ?string $charlist=null, bool $lower=true): string .[method]
-------------------------------------------------------------------------------

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.

```php
Strings::webalize('náš produkt'); // 'nas-produkt'
```

Mají-li být zachovány i jiné znaky, lze je uvést v druhém parametru funkce.

```php
Strings::webalize('10. obrázek_id', '._'); // '10.-obrazek_id'
```

Třetím parametrem lze potlačit převádění na malá písmenka.

```php
Strings::webalize('Dobrý den', null, false); // 'Dobry-den'
```

.[caution]
Vyžaduje PHP rozšíření `intl`.


trim(string $s, ?string $charlist=null): string .[method]
---------------------------------------------------------

Ořízne mezery (nebo jiné znaky určené druhým parametrem) ze začátku a konce UTF-8 řetězce.

```php
Strings::trim('  Hello  '); // 'Hello'
```


truncate(string $s, int $maxLen, string $append=`'…'`): string .[method]
------------------------------------------------------------------------

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

```php
$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 .[method]
---------------------------------------------------------------------------------

Odsadí víceřádkový text zleva. Počet odsazení určuje druhý parametr, čím odsazovat parametr třetí (výchozí hodnotou je tabulátor).

```php
Strings::indent('Nette');         // "\tNette"
Strings::indent('Nette', 2, '+'); // '++Nette'
```


padLeft(string $s, int $length, string $pad=`' '`): string .[method]
--------------------------------------------------------------------

Doplní UTF-8 řetězec na zadanou délku opakováním řetězce `$pad` zleva.

```php
Strings::padLeft('Nette', 6);        // ' Nette'
Strings::padLeft('Nette', 8, '+*');  // '+*+Nette'
```


padRight(string $s, int $length, string $pad=`' '`): string .[method]
---------------------------------------------------------------------

Doplní UTF-8 řetězec na zadanou délku opakováním řetězce `$pad` zprava.

```php
Strings::padRight('Nette', 6);       // 'Nette '
Strings::padRight('Nette', 8, '+*'); // 'Nette+*+'
```


substring(string $s, int $start, ?int $length=null): string .[method]
---------------------------------------------------------------------

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.

```php
Strings::substring('Nette Framework', 0, 5); // 'Nette'
Strings::substring('Nette Framework', 6);    // 'Framework'
Strings::substring('Nette Framework', -4);   // 'work'
```


reverse(string $s): string .[method]
------------------------------------

Obrátí UTF-8 řetězec.

```php
Strings::reverse('Nette'); // 'etteN'
```


length(string $s): int .[method]
--------------------------------

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ů.

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


startsWith(string $haystack, string $needle): bool .[method]
------------------------------------------------------------

Zjistí jestli řetězec `$haystack` začíná řetězcem `$needle`.

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


endsWith(string $haystack, string $needle): bool .[method]
----------------------------------------------------------

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

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


contains(string $haystack, string $needle): bool .[method]
----------------------------------------------------------

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

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


compare(string $left, string $right, ?int $length=null): bool .[method]
-----------------------------------------------------------------------

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.

```php
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 .[method]
-----------------------------------------

Najde společný začátek řetězců. Nebo vrátí prázdný řetězec, pokud společná předpona nebyla nalezena.

```php
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 .[method]
-----------------------------------------------------------------------

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.

```php
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 .[method]
----------------------------------------------------------------------

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.

```php
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 .[method]
---------------------------------------------------------------------

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.

```php
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 .[method]
----------------------------------------

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

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


checkEncoding(string $s): bool .[method]
----------------------------------------

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

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


toAscii(string $s): string .[method]
------------------------------------

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

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

.[caution]
Vyžaduje PHP rozšíření `intl`.


chr(int $code): string .[method]
--------------------------------

Vrací specifický znak v UTF-8 z kódového bodu (číslo v rozsahu 0x0000..D7FF a 0xE000..10FFFF).

```php
Strings::chr(0xA9); // '©' v kódování UTF-8
```


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 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, ?int $flags=null): array .[method]
--------------------------------------------------------------------------

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

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

Strings::split('hello, world', '~(,)\s*~');
// ['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í.

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


match(string $subject, string $pattern, ?int $flags=null, int $offset=0): ?array .[method]
------------------------------------------------------------------------------------------

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`.

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

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

Jako `$flag` je možné uvést stejné příznaky jako u funkce [php:preg_match].

Parametr `$offset` lze použít k určení pozice, od které se má začít hledat (v bajtech).


matchAll(string $subject, string $pattern, ?int $flags=null, int $offset=0): array .[method]
--------------------------------------------------------------------------------------------

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.

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

Jako `$flag` je možné uvést stejné příznaky jako u funkce [php:preg_match_all], s tím rozdílem, že příznak `PREG_SET_ORDER` je výchozí hodnotou.

Parametr `$offset` lze použít k určení pozice, od které se má začít hledat (v bajtech).


replace(string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1): string .[method]
-----------------------------------------------------------------------------------------------------------------

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

```php
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`:

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

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