Praca z łańcuchami
******************

.[perex]
[api:Nette\Utils\Strings] jest klasą statyczną zawierającą przydatne funkcje do pracy z ciągami znaków, głównie w kodowaniu UTF-8.


Instalacja:

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

Wszystkie przykłady zakładają, że alias został utworzony:

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


Rozróżnianie wielkości liter .[#toc-letter-case]
================================================

Funkcje te wymagają rozszerzenia PHP `mbstring`.


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

Konwertuje ciąg UTF-8 na małe litery.

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


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

Konwertuje ciąg znaków UTF-8 na wielkie litery.

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


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

Konwertuje pierwszą literę łańcucha UTF-8 na wielkie litery, nie zmienia pozostałych.

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


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

Konwertuje pierwszą literę łańcucha UTF-8 na małe litery, nie zmienia reszty.

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


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

Konwertuje pierwszą literę każdego słowa w łańcuchu UTF-8 na duże litery, resztę na małe.

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


Ciąg dalszy .[#toc-editing-a-string]
====================================


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

Usuwa znaki sterujące, normalizuje przerwy w linii do `\n`, przycina wiodące i ciągnące się puste linie, przycina prawe przerwy w linii, normalizuje UTF-8 do normalnej postaci NFC.


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

Konwertuje podziały linii na `\n` używane w systemach uniksowych. Podziałami linii są: `\n`, `\r`, `\r\n`, U+2028 separator linii, U+2029 separator akapitu.

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


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

Konwertuje przerwy między wierszami na znaki specyficzne dla bieżącej platformy, tj. `\r\n` w Windows i `\n` w innych miejscach. Podziałami linii są: `\n`, `\r`, `\r\n`, U+2028 separator linii, U+2029 separator akapitu.

```php
$platformLines = Strings::platformNewLines($string);
```


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

Modyfikuje ciąg UTF-8 do formatu używanego w adresie URL, tj. usuwa znaki diakrytyczne i zastępuje wszystkie znaki z wyjątkiem liter alfabetu angielskiego i cyfr myślnikiem.

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

Jeśli mają być zachowane inne znaki, można je podać w drugim parametrze funkcji.

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

Trzeci parametr może być użyty do tłumienia konwersji na małe litery.

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

.[caution]
Wymaga rozszerzenia PHP `intl`.


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

Wycina spacje (lub inne znaki określone przez drugi parametr) z początku i końca łańcucha UTF-8.

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


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

Obcina łańcuch UTF-8 do określonej maksymalnej długości, starając się zachować całe słowa. Jeśli łańcuch jest obcięty, dodaje triplet na koniec (można go zmienić za pomocą trzeciego parametru).

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

Wcięcie tekstu wielowierszowego od lewej strony. Ilość wcięć określa drugi parametr, który służy do wcięcia trzeciego parametru (domyślną wartością jest tabulator).

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


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

Uzupełnia łańcuch UTF-8 do określonej długości, powtarzając łańcuch `$pad` od lewej.

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


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

Uzupełnia łańcuch UTF-8 do określonej długości, powtarzając łańcuch `$pad` od prawej.

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


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

Zwraca część łańcucha UTF-8 `$s` określoną przez pozycję początkową `$start` i długość `$length`. Jeśli `$start` jest ujemny, zwrócony łańcuch rozpocznie się od znaku -`$start` znak od końca.

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

Odwraca łańcuch UTF-8.

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


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

Zwraca liczbę znaków (nie bajtów) w łańcuchu UTF-8.

Jest to liczba punktów kodowych Unicode, która może się różnić od liczby grafemów.

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


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

Ustalić, czy ciąg `$haystack` zaczyna się od ciągu `$needle`.

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

.[note]
Korzystaj z rodzimego `str_starts_with()`:https://www.php.net/manual/en/function.str-starts-with.php.


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

Dowiedz się, czy ciąg `$haystack` kończy się ciągiem `$needle`.

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

.[note]
Korzystaj z rodzimego `str_ends_with()`:https://www.php.net/manual/en/function.str-ends-with.php.


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

Ustalić, czy ciąg `$haystack` zawiera `$needle`.

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

.[note]
Korzystaj z rodzimego `str_contains()`:https://www.php.net/manual/en/function.str-contains.php.


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

Porównanie bez rozróżniania wielkości liter dwóch łańcuchów UTF-8 lub ich części. Jeśli `$length` zawiera null, to porównywane są całe ciągi, jeśli ujemnie, to porównywana jest odpowiednia liczba znaków z końca ciągów, w przeciwnym razie porównywana jest odpowiednia liczba znaków z począ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]
-----------------------------------------

Znajduje wspólny początek ciągów znaków. Lub zwraca pusty łańcuch, jeśli nie znaleziono wspólnego prefiksu.

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

Zwraca część ciągu `$haystack` przed n-tym `$nth` wystąpieniem ciągu `$needle`. Lub `null`, jeśli nie znaleziono `$needle`. Jeśli `$nth` jest ujemne, to szuka od końca łańcucha.

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

Zwraca część ciągu `$haystack` po n-tym `$nth` wystąpieniu ciągu `$needle`. Lub `null`, jeśli nie znaleziono `$needle`. Jeśli `$nth` jest ujemne, to szuka od końca łańcucha.

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

Zwraca pozycję w znakach n-tego `$nth` wystąpienia ciągu `$needle` w ciągu `$haystack`. Lub `null`, jeśli nie znaleziono `$needle`. Jeśli `$nth` jest ujemne, to jest wyszukiwane od końca łańcucha.

```php
Strings::indexOf('abc abc abc', 'abc', 2);  // 4
Strings::indexOf('abc abc abc', 'abc', -1); // 8
Strings::indexOf('abc abc abc', 'd');       // null
```


Kodowanie .[#toc-encoding]
==========================


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

Usuwa niepoprawne znaki UTF-8 z łańcucha.

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


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

Określ, czy jest to prawidłowy ciąg znaków UTF-8.

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

.[note]
Użyj funkcji [Nette\Validator::isUnicode() |validators#isUnicode].


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

Konwertuje ciąg UTF-8 na ASCII, tzn. usuwa znaki diakrytyczne itp.

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

.[caution]
Wymaga rozszerzenia PHP `intl`.


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

Zwraca określony znak UTF-8 z punktu kodowego (liczba z zakresu 0x0000..D7FF i 0xE000..10FFFF).

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


ord(string $char): int .[method]
--------------------------------

Zwraca punkt kodowy UTF-8 określonego znaku (liczba z zakresu 0x0000..D7FF lub 0xE000..10FFFF).

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


Wyrażenia regularne .[#toc-regular-expressions]
===============================================

Klasa Strings dostarcza funkcji do pracy z wyrażeniami regularnymi. W przeciwieństwie do natywnych funkcji PHP, mają one bardziej zrozumiałe API, lepszą obsługę Unicode, a co najważniejsze - wykrywanie błędów. Każdy błąd w kompilacji lub przetwarzaniu wyrażenia rzuci wyjątek `Nette\RegexpException`.


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

Dzieli łańcuch na tablicę zgodnie z wyrażeniem regularnym. Wyrażenia w nawiasach będą również przechwytywane i zwracane.

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

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

Jeśli `$skipEmpty` to `true`, zwrócone zostaną tylko niepuste wpisy:

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

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

Jeśli `$limit`, zwrócone zostaną tylko podciągi do limitu, a reszta łańcucha zostanie umieszczona w ostatnim elemencie. Limit o wartości -1 lub 0 oznacza brak limitu.

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

Jeśli `$utf8` to `true`, ocena przełączy się na tryb Unicode. Podobnie jak w przypadku określenia modyfikatora `u`.

Jeśli `$captureOffset` jest `true`, dla każdego występującego dopasowania, zwrócona zostanie także jego pozycja w łańcuchu (w bajtach; w znakach, jeśli ustawiono `$utf8` ). Zmienia to wartość zwracaną na tablicę, gdzie każdy element jest parą składającą się z dopasowanego łańcucha i jego pozycji.

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

Przeszukuje łańcuch w poszukiwaniu części pasującej do wyrażenia regularnego i zwraca tablicę ze znalezionym wyrażeniem i każdym podwyrażeniem, lub `null`.

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

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

Jeśli `$unmatchedAsNull` jest `true`, to nie przechwycone podwyrażenia są zwracane jako null; w przeciwnym razie są zwracane jako pusty łańcuch lub nie są zwracane:

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

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

Jeśli `$utf8` to `true`, ocena przełącza się na tryb Unicode. Podobnie jak w przypadku określenia modyfikatora `u`:

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

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

Za pomocą parametru `$offset` można określić pozycję, od której ma się rozpocząć wyszukiwanie (w bajtach; w znakach, jeśli ustawiono `$utf8` ).

Jeśli `$captureOffset` to `true`, dla każdego występującego dopasowania, zwrócona zostanie także jego pozycja w łańcuchu (w bajtach; jeśli ustawiono `$utf8`, w znakach). To zamienia wartość zwrotną w tablicę, gdzie każdy element jest parą składającą się z dopasowanego łańcucha i jego przesunięcia:

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

Przeszukuje łańcuch w poszukiwaniu wszystkich wystąpień pasujących do wyrażenia regularnego i zwraca tablicę tablic zawierających dopasowane wyrażenie i każde podwyrażenie.

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

Jeśli `$patternOrder` jest `true`, struktura wyników zmienia się tak, że pierwszy wpis jest tablicą pełnych dopasowań wzorca, drugi jest tablicą łańcuchów dopasowanych przez pierwszy podwzorzec w nawiasach, i tak dalej:

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

Jeśli `$unmatchedAsNull` jest `true`, niedopasowane podwzorce są zwracane jako null; w przeciwnym razie są zwracane jako puste łańcuchy lub nie są zwracane:

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

Jeśli `$utf8` to `true`, ocena przełącza się na tryb Unicode. Podobnie jak w przypadku określenia modyfikatora `u`:

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

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

Za pomocą parametru `$offset` można określić pozycję, od której ma się rozpocząć wyszukiwanie (w bajtach; w znakach, jeśli ustawiono `$utf8` ).

Jeśli `$captureOffset` to `true`, dla każdego występującego dopasowania, zwrócona zostanie także jego pozycja w łańcuchu (w bajtach; jeśli ustawiono `$utf8`, w znakach). Zmienia to wartość zwracaną na tablicę, gdzie każdy element jest parą składającą się z dopasowanego łańcucha i jego pozycji:

```php
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]],
] */
```

Jeśli `$lazy` to `true`, funkcja zwraca `Generator` zamiast tablicy, co zapewnia znaczne korzyści w zakresie wydajności podczas pracy z dużymi ciągami znaków. Generator pozwala na znajdowanie dopasowań przyrostowo, zamiast przetwarzania całego ciągu na raz. Umożliwia to wydajną obsługę bardzo dużych tekstów wejściowych. Dodatkowo, można przerwać przetwarzanie w dowolnym momencie, jeśli zostanie znalezione pożądane dopasowanie, oszczędzając czas obliczeniowy.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // Processing can be interrupted at any time
}
```


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

Zastępuje wszystkie wystąpienia pasujące do wyrażenia regularnego. `$replacement` jest maską łańcucha zastępczego lub wywołaniem zwrotnym.

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

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

Funkcja umożliwia również wielokrotne podstawianie, przekazując w drugim parametrze tablicę o postaci `pattern => replacement`:

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

Parametr `$limit` ogranicza liczbę podstawień, które można wykonać. Limit o wartości -1 oznacza brak limitu.

Jeśli `$utf8` to `true`, ocena przełącza się na tryb Unicode. Jest to podobne do określenia modyfikatora `u`.

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

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

Jeśli `$captureOffset` to `true`, dla każdego występującego dopasowania, jego pozycja w łańcuchu (w bajtach; w znakach, jeśli ustawiono `$utf8` ) również zostanie przekazana do callbacka. Zmienia to postać przekazywanej tablicy, gdzie każdy element jest parą składającą się z dopasowanego łańcucha i jego pozycji.

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

Jeśli `$unmatchedAsNull` to `true`, niedopasowane podwzorce są przekazywane do callbacka jako null; w przeciwnym razie są przekazywane jako pusty łańcuch lub nie są przekazywane:

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