Nette Documentation Preview

syntax 
Funkcje do pracy ze stringami
*****************************

.[perex]
[api:Nette\Utils\Strings] to klasa statyczna zawierająca przydatne funkcje do pracy ze stringami w kodowaniu UTF-8.


Instalacja:

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

Wszystkie przykłady zakładają, że zdefiniowany jest następujący alias klasy:

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


Wielkość liter
==============

Te funkcje wymagają rozszerzenia PHP `mbstring`.


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

Zamienia string UTF-8 na małe litery.

```php
Strings::lower('Hello World'); // 'hello world'
```


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

Zamienia string UTF-8 na wielkie litery.

```php
Strings::upper('Hello World'); // 'HELLO WORLD'
```


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

Zamienia pierwszy znak stringa UTF-8 na wielką literę, a pozostałe znaki zostawia bez zmian.

```php
Strings::firstUpper('hello world'); // 'Hello world'
```


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

Zamienia pierwszy znak stringa UTF-8 na małą literę, a pozostałe znaki zostawia bez zmian.

```php
Strings::firstLower('Hello world'); // 'hello world'
```


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

Zamienia pierwszy znak każdego słowa w stringu UTF-8 na wielką literę, a pozostałe na małe.

```php
Strings::capitalize('hello world'); // 'Hello World'
```


Edycja stringa
==============


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

Usuwa znaki sterujące, normalizuje końce wierszy do `\n`, przycina początkowe i końcowe puste wiersze, przycina końcowe spacje w wierszach i normalizuje UTF-8 do postaci normalnej NFC.


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

Konwertuje końce wierszy na `\n` używane w systemach uniksowych. Końcami wierszy są: `\n`, `\r`, `\r\n`, separator wierszy U+2028, separator akapitów U+2029.

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


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

Konwertuje końce wierszy na znaki właściwe dla bieżącej platformy, czyli `\r\n` w Windows i `\n` gdzie indziej. Końcami wierszy są: `\n`, `\r`, `\r\n`, separator wierszy U+2028, separator akapitów U+2029.

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


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

Dostosowuje string UTF-8 do postaci używanej w URL, czyli usuwa znaki diakrytyczne i zastępuje myślnikami wszystkie znaki poza literami alfabetu angielskiego i cyframi.

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

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

```php
Strings::webalize('10. image_id', '._'); // '10.-image_id'
```

Trzeci parametr pozwala wyłączyć zamianę na małe litery.

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

.[caution]
Wymaga rozszerzenia PHP `intl`.


trim(string $s, string $charlist=self::TrimCharacters): string .[method]
------------------------------------------------------------------------

Usuwa początkowe i końcowe białe znaki (albo inne znaki podane w drugim parametrze) ze stringa UTF-8.

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


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

Skraca string UTF-8 do podanej maksymalnej długości, starając się zachować całe słowa. Jeśli string zostanie skrócony, na końcu dodawany jest wielokropek (zmienialny trzecim parametrem).

```php
$text = 'Hello, how are you today?';
Strings::truncate($text, 5);       // 'Hell…'
Strings::truncate($text, 20);      // 'Hello, how are you…'
Strings::truncate($text, 30);      // 'Hello, how are you today?'
Strings::truncate($text, 20, '~'); // 'Hello, how are you~'
```


indent(string $s, int $level=1, string $chars=`"\t"`): string .[method]
-----------------------------------------------------------------------

Wcina wielowierszowy tekst od lewej. Drugi parametr określa liczbę znaków wcięcia, a trzeci znak (albo znaki) używane do wcięcia (domyślnie tabulator).

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


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

Dopełnia string UTF-8 do podanej długości, dopisując string `$pad` od lewej.

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


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

Dopełnia string UTF-8 do podanej długości, dopisując string `$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ęść stringa UTF-8 `$s` określoną przez pozycję początkową `$start` i długość `$length`. Jeśli `$start` jest ujemny, zwracany string zacznie się od `$start`-tego znaku 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 string UTF-8.

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


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

Zwraca liczbę znaków (nie bajtów) w stringu UTF-8.

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

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


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

Sprawdza, czy string `$haystack` zaczyna się od stringa `$needle`.

```php
$haystack = 'Starts';
$needle = 'St';
Strings::startsWith($haystack, $needle); // true
```

.[note]
Użyj natywnej funkcji `str_starts_with()`:https://www.php.net/manual/en/function.str-starts-with.php.


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

Sprawdza, czy string `$haystack` kończy się stringiem `$needle`.

```php
$haystack = 'Ends';
$needle = 'ds';
Strings::endsWith($haystack, $needle); // true
```

.[note]
Użyj natywnej funkcji `str_ends_with()`:https://www.php.net/manual/en/function.str-ends-with.php.


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

Sprawdza, czy string `$haystack` zawiera string `$needle`.

```php
$haystack = 'Auditorium';
$needle = 'dit';
Strings::contains($haystack, $needle); // true
```

.[note]
Użyj natywnej funkcji `str_contains()`:https://www.php.net/manual/en/function.str-contains.php.


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

Porównuje dwa stringi UTF-8 albo ich części, bez rozróżniania wielkości liter. Jeśli `$length` to null, porównuje całe stringi. Jeśli jest ujemna, porównuje odpowiadającą liczbę znaków od końca stringów. W przeciwnym razie porównuje odpowiadającą liczbę znaków od początku.

```php
Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - pierwsze 2 znaki się zgadzają
Strings::compare('Nette', 'Latte', -2); // true - ostatnie 2 znaki się zgadzają
```


findPrefix(array $strings): string .[method]
--------------------------------------------

Znajduje wspólny prefiks stringów. Zwraca pusty string, jeśli wspólnego prefiksu nie ma.

```php
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ęść stringa `$haystack` przed `$nth` wystąpieniem stringa `$needle`. Zwraca `null`, jeśli `$needle` się nie znajdzie. Jeśli `$nth` jest ujemne, szuka od końca stringa.

```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ęść stringa `$haystack` po `$nth` wystąpieniu stringa `$needle`. Zwraca `null`, jeśli `$needle` się nie znajdzie. Jeśli `$nth` jest ujemne, szuka od końca stringa.

```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ę znakową `$nth` wystąpienia stringa `$needle` w stringu `$haystack`. Zwraca `null`, jeśli `$needle` się nie znajdzie. Jeśli `$nth` jest ujemne, szuka od końca stringa.

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


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

Usuwa ze stringa nieprawidłowe znaki UTF-8.

```php
$correctString = Strings::fixEncoding($invalidString);
```


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

Sprawdza, czy string jest prawidłowym stringiem UTF-8.

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

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


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

Konwertuje string UTF-8 na ASCII, czyli usuwa znaki diakrytyczne itd.

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

.[caution]
Wymaga rozszerzenia PHP `intl`.


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

Zwraca konkretny znak w UTF-8 na podstawie punktu kodowego (liczby z zakresu 0x0000..D7FF albo 0xE000..10FFFF).

```php
Strings::chr(0xA9); // '©' w kodowaniu UTF-8
```


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

Zwraca punkt kodowy konkretnego znaku w UTF-8 (liczbę z zakresu 0x0000..D7FF albo 0xE000..10FFFF).

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


Wyrażenia regularne
===================

Klasa `Strings` oferuje funkcje do pracy z wyrażeniami regularnymi. W odróżnieniu od natywnych funkcji PHP mają bardziej zrozumiałe API, lepszą obsługę Unicode i, co kluczowe, wykrywanie błędów. Każdy błąd podczas kompilacji albo przetwarzania wyrażenia zgłasza `Nette\RegexpException`.


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

Dzieli string na tablicę według wyrażenia regularnego. Wyrażenia w nawiasach również zostaną przechwycone i zwrócone.

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

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

Jeśli `$skipEmpty` ma wartość `true`, zwracane będą tylko niepuste elementy:

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

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

Jeśli podano `$limit`, zwracane są tylko podciągi do tego limitu, a reszta stringa trafia do ostatniego elementu. Limit -1 albo 0 oznacza brak limitu.

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

Jeśli `$utf8` ma wartość `true`, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora `u`.

Jeśli `$captureOffset` ma wartość `true`, zwracana będzie również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono `$utf8`). Zmienia to wartość zwracaną na tablicę, w której każdy element jest parą złożoną z dopasowanego stringa 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]] // pozycje w znakach
```


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

Szuka w stringu części pasującej do wyrażenia regularnego i zwraca tablicę zawierającą znalezione wyrażenie i poszczególne podwyrażenia albo `null`, jeśli nic nie pasuje.

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

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

Jeśli `$unmatchedAsNull` ma wartość `true`, niedopasowane podwzorce zwracane są jako `null`; w przeciwnym razie zwracane są jako pusty string albo całkiem pomijane:

```php
Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (opcjonalna grupa !+ nie została dopasowana)

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

Jeśli `$utf8` ma wartość `true`, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora `u`:

```php
Strings::match('žlutý kůň', '~\w+~'); // bez UTF-8
// ['lut'] (dopasowuje tylko znaki słowa z ASCII)

Strings::match('žlutý kůň', '~\w+~', utf8: true); // z UTF-8
// ['žlutý'] (dopasowuje znaki słowa z Unicode)
```

Parametr `$offset` może określić pozycję początkową wyszukiwania (w bajtach; w znakach, jeśli ustawiono `$utf8`).

Jeśli `$captureOffset` ma wartość `true`, zwracana będzie również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono `$utf8`). Zmienia to wartość zwracaną na tablicę, w której każdy element jest parą złożoną z dopasowanego stringa i jego przesunięcia:

```php
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // bez UTF-8
// [['lut', 2]] (tylko dopasowanie ASCII, przesunięcie w bajtach)

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // z UTF-8
// [['žlutý!', 0], ['!', 5]] (dopasowanie Unicode, przesunięcia w znakach)
```


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

Szuka w stringu wszystkich wystąpień pasujących do wyrażenia regularnego i zwraca tablicę tablic zawierających znalezione wyrażenie i poszczególne podwyrażenia.

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

Jeśli `$patternOrder` ma wartość `true`, struktura wyników się zmienia: pierwszym elementem jest tablica pełnych dopasowań wzorca, drugim tablica stringów pasujących do pierwszego podwzorca w nawiasach itd.:

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

Jeśli `$unmatchedAsNull` ma wartość `true`, niedopasowane podwzorce zwracane są jako `null`; w przeciwnym razie zwracane są jako pusty string albo pomijane:

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

Jeśli `$utf8` ma wartość `true`, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora `u`:

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

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

Parametr `$offset` może określić pozycję początkową wyszukiwania (w bajtach; w znakach, jeśli ustawiono `$utf8`).

Jeśli `$captureOffset` ma wartość `true`, zwracana będzie również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono `$utf8`). Zmienia to strukturę wartości zwracanej, w której każdy element dopasowania jest parą `[dopasowany_string, pozycja]`:

```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` ma wartość `true`, funkcja zwraca `Generator` zamiast tablicy. Daje to znaczące korzyści wydajnościowe przy pracy z dużymi stringami, bo dopasowania znajdowane są stopniowo, zamiast przetwarzać cały string naraz. Pozwala to efektywnie obsługiwać wyjątkowo duże dane wejściowe. Ponadto możesz przerwać przetwarzanie w dowolnej chwili, gdy znajdziesz szukane dopasowanie, oszczędzając czas obliczeń.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // przetwarzanie można przerwać w dowolnej chwili, np. przez break;
}
```


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` to maska stringa zastępującego albo funkcja callback.

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

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

Funkcja pozwala też na wiele zamian naraz, przez przekazanie w drugim parametrze tablicy w postaci `wzorzec => zamiennik`:

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

Parametr `$limit` ogranicza liczbę wykonanych zamian. Limit -1 oznacza brak limitu.

Jeśli `$utf8` ma wartość `true`, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora `u`.

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

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

Jeśli `$captureOffset` ma wartość `true`, do callbacku przekazywana jest również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono `$utf8`). Zmienia to strukturę przekazywanej tablicy, w której każdy element jest parą `[dopasowany_string, pozycja]`.

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

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

Jeśli `$unmatchedAsNull` ma wartość `true`, niedopasowane podwzorce przekazywane są do callbacku jako `null`; w przeciwnym razie przekazywane są jako pusty string albo pomijane:

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

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

Funkcje do pracy ze stringami

Nette\Utils\Strings to klasa statyczna zawierająca przydatne funkcje do pracy ze stringami w kodowaniu UTF-8.

Instalacja:

composer require nette/utils

Wszystkie przykłady zakładają, że zdefiniowany jest następujący alias klasy:

use Nette\Utils\Strings;

Wielkość liter

Te funkcje wymagają rozszerzenia PHP mbstring.

lower(string $s): string

Zamienia string UTF-8 na małe litery.

Strings::lower('Hello World'); // 'hello world'

upper(string $s): string

Zamienia string UTF-8 na wielkie litery.

Strings::upper('Hello World'); // 'HELLO WORLD'

firstUpper(string $s): string

Zamienia pierwszy znak stringa UTF-8 na wielką literę, a pozostałe znaki zostawia bez zmian.

Strings::firstUpper('hello world'); // 'Hello world'

firstLower(string $s): string

Zamienia pierwszy znak stringa UTF-8 na małą literę, a pozostałe znaki zostawia bez zmian.

Strings::firstLower('Hello world'); // 'hello world'

capitalize(string $s): string

Zamienia pierwszy znak każdego słowa w stringu UTF-8 na wielką literę, a pozostałe na małe.

Strings::capitalize('hello world'); // 'Hello World'

Edycja stringa

normalize(string $s): string

Usuwa znaki sterujące, normalizuje końce wierszy do \n, przycina początkowe i końcowe puste wiersze, przycina końcowe spacje w wierszach i normalizuje UTF-8 do postaci normalnej NFC.

unixNewLines(string $s): string

Konwertuje końce wierszy na \n używane w systemach uniksowych. Końcami wierszy są: \n, \r, \r\n, separator wierszy U+2028, separator akapitów U+2029.

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

platformNewLines(string $s): string

Konwertuje końce wierszy na znaki właściwe dla bieżącej platformy, czyli \r\n w Windows i \n gdzie indziej. Końcami wierszy są: \n, \r, \r\n, separator wierszy U+2028, separator akapitów U+2029.

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

webalize(string $s, ?string $charlist=null, bool $lower=true): string

Dostosowuje string UTF-8 do postaci używanej w URL, czyli usuwa znaki diakrytyczne i zastępuje myślnikami wszystkie znaki poza literami alfabetu angielskiego i cyframi.

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

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

Strings::webalize('10. image_id', '._'); // '10.-image_id'

Trzeci parametr pozwala wyłączyć zamianę na małe litery.

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

Wymaga rozszerzenia PHP intl.

trim(string $s, string $charlist=self::TrimCharacters): string

Usuwa początkowe i końcowe białe znaki (albo inne znaki podane w drugim parametrze) ze stringa UTF-8.

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

truncate(string $s, int $maxLen, string $append=`'…'`): string

Skraca string UTF-8 do podanej maksymalnej długości, starając się zachować całe słowa. Jeśli string zostanie skrócony, na końcu dodawany jest wielokropek (zmienialny trzecim parametrem).

$text = 'Hello, how are you today?';
Strings::truncate($text, 5);       // 'Hell…'
Strings::truncate($text, 20);      // 'Hello, how are you…'
Strings::truncate($text, 30);      // 'Hello, how are you today?'
Strings::truncate($text, 20, '~'); // 'Hello, how are you~'

indent(string $s, int $level=1, string $chars=`"\t"`): string

Wcina wielowierszowy tekst od lewej. Drugi parametr określa liczbę znaków wcięcia, a trzeci znak (albo znaki) używane do wcięcia (domyślnie tabulator).

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

padLeft(string $s, int $length, string $pad=`' '`): string

Dopełnia string UTF-8 do podanej długości, dopisując string $pad od lewej.

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

padRight(string $s, int $length, string $pad=`' '`): string

Dopełnia string UTF-8 do podanej długości, dopisując string $pad od prawej.

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

substring(string $s, int $start, ?int $length=null): string

Zwraca część stringa UTF-8 $s określoną przez pozycję początkową $start i długość $length. Jeśli $start jest ujemny, zwracany string zacznie się od $start-tego znaku od końca.

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

reverse(string $s): string

Odwraca string UTF-8.

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

length(string $s): int

Zwraca liczbę znaków (nie bajtów) w stringu UTF-8.

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

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

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

Sprawdza, czy string $haystack zaczyna się od stringa $needle.

$haystack = 'Starts';
$needle = 'St';
Strings::startsWith($haystack, $needle); // true

Użyj natywnej funkcji str_starts_with().

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

Sprawdza, czy string $haystack kończy się stringiem $needle.

$haystack = 'Ends';
$needle = 'ds';
Strings::endsWith($haystack, $needle); // true

Użyj natywnej funkcji str_ends_with().

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

Sprawdza, czy string $haystack zawiera string $needle.

$haystack = 'Auditorium';
$needle = 'dit';
Strings::contains($haystack, $needle); // true

Użyj natywnej funkcji str_contains().

compare(string $left, string $right, ?int $length=null): bool

Porównuje dwa stringi UTF-8 albo ich części, bez rozróżniania wielkości liter. Jeśli $length to null, porównuje całe stringi. Jeśli jest ujemna, porównuje odpowiadającą liczbę znaków od końca stringów. W przeciwnym razie porównuje odpowiadającą liczbę znaków od początku.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - pierwsze 2 znaki się zgadzają
Strings::compare('Nette', 'Latte', -2); // true - ostatnie 2 znaki się zgadzają

findPrefix(array $strings): string

Znajduje wspólny prefiks stringów. Zwraca pusty string, jeśli wspólnego prefiksu nie ma.

Strings::findPrefix(['prefix-a', 'prefix-bb', 'prefix-c']); // 'prefix-'
Strings::findPrefix(['Nette', 'is', 'great']);              // ''

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

Zwraca część stringa $haystack przed $nth wystąpieniem stringa $needle. Zwraca null, jeśli $needle się nie znajdzie. Jeśli $nth jest ujemne, szuka od końca stringa.

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

Zwraca część stringa $haystack po $nth wystąpieniu stringa $needle. Zwraca null, jeśli $needle się nie znajdzie. Jeśli $nth jest ujemne, szuka od końca stringa.

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

Zwraca pozycję znakową $nth wystąpienia stringa $needle w stringu $haystack. Zwraca null, jeśli $needle się nie znajdzie. Jeśli $nth jest ujemne, szuka od końca stringa.

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

Kodowanie

fixEncoding(string $s): string

Usuwa ze stringa nieprawidłowe znaki UTF-8.

$correctString = Strings::fixEncoding($invalidString);

checkEncoding(string $s): bool

Sprawdza, czy string jest prawidłowym stringiem UTF-8.

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

Użyj Nette\Utils\Validators::isUnicode().

toAscii(string $s): string

Konwertuje string UTF-8 na ASCII, czyli usuwa znaki diakrytyczne itd.

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

Wymaga rozszerzenia PHP intl.

chr(int $code): string

Zwraca konkretny znak w UTF-8 na podstawie punktu kodowego (liczby z zakresu 0×0000..D7FF albo 0xE000..10FFFF).

Strings::chr(0xA9); // '©' w kodowaniu UTF-8

ord(string $c): int

Zwraca punkt kodowy konkretnego znaku w UTF-8 (liczbę z zakresu 0×0000..D7FF albo 0xE000..10FFFF).

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

Wyrażenia regularne

Klasa Strings oferuje funkcje do pracy z wyrażeniami regularnymi. W odróżnieniu od natywnych funkcji PHP mają bardziej zrozumiałe API, lepszą obsługę Unicode i, co kluczowe, wykrywanie błędów. Każdy błąd podczas kompilacji albo przetwarzania wyrażenia zgłasza Nette\RegexpException.

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

Dzieli string na tablicę według wyrażenia regularnego. Wyrażenia w nawiasach również zostaną przechwycone i zwrócone.

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

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

Jeśli $skipEmpty ma wartość true, zwracane będą tylko niepuste elementy:

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

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

Jeśli podano $limit, zwracane są tylko podciągi do tego limitu, a reszta stringa trafia do ostatniego elementu. Limit –1 albo 0 oznacza brak limitu.

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

Jeśli $utf8 ma wartość true, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora u.

Jeśli $captureOffset ma wartość true, zwracana będzie również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono $utf8). Zmienia to wartość zwracaną na tablicę, w której każdy element jest parą złożoną z dopasowanego stringa i jego pozycji.

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

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

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

Szuka w stringu części pasującej do wyrażenia regularnego i zwraca tablicę zawierającą znalezione wyrażenie i poszczególne podwyrażenia albo null, jeśli nic nie pasuje.

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

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

Jeśli $unmatchedAsNull ma wartość true, niedopasowane podwzorce zwracane są jako null; w przeciwnym razie zwracane są jako pusty string albo całkiem pomijane:

Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (opcjonalna grupa !+ nie została dopasowana)

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

Jeśli $utf8 ma wartość true, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora u:

Strings::match('žlutý kůň', '~\w+~'); // bez UTF-8
// ['lut'] (dopasowuje tylko znaki słowa z ASCII)

Strings::match('žlutý kůň', '~\w+~', utf8: true); // z UTF-8
// ['žlutý'] (dopasowuje znaki słowa z Unicode)

Parametr $offset może określić pozycję początkową wyszukiwania (w bajtach; w znakach, jeśli ustawiono $utf8).

Jeśli $captureOffset ma wartość true, zwracana będzie również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono $utf8). Zmienia to wartość zwracaną na tablicę, w której każdy element jest parą złożoną z dopasowanego stringa i jego przesunięcia:

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // bez UTF-8
// [['lut', 2]] (tylko dopasowanie ASCII, przesunięcie w bajtach)

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // z UTF-8
// [['žlutý!', 0], ['!', 5]] (dopasowanie Unicode, przesunięcia w znakach)

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

Szuka w stringu wszystkich wystąpień pasujących do wyrażenia regularnego i zwraca tablicę tablic zawierających znalezione wyrażenie i poszczególne podwyrażenia.

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

Jeśli $patternOrder ma wartość true, struktura wyników się zmienia: pierwszym elementem jest tablica pełnych dopasowań wzorca, drugim tablica stringów pasujących do pierwszego podwzorca w nawiasach itd.:

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

Jeśli $unmatchedAsNull ma wartość true, niedopasowane podwzorce zwracane są jako null; w przeciwnym razie zwracane są jako pusty string albo pomijane:

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

Jeśli $utf8 ma wartość true, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora u:

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

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

Parametr $offset może określić pozycję początkową wyszukiwania (w bajtach; w znakach, jeśli ustawiono $utf8).

Jeśli $captureOffset ma wartość true, zwracana będzie również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono $utf8). Zmienia to strukturę wartości zwracanej, w której każdy element dopasowania jest parą [dopasowany_string, pozycja]:

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 ma wartość true, funkcja zwraca Generator zamiast tablicy. Daje to znaczące korzyści wydajnościowe przy pracy z dużymi stringami, bo dopasowania znajdowane są stopniowo, zamiast przetwarzać cały string naraz. Pozwala to efektywnie obsługiwać wyjątkowo duże dane wejściowe. Ponadto możesz przerwać przetwarzanie w dowolnej chwili, gdy znajdziesz szukane dopasowanie, oszczędzając czas obliczeń.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // przetwarzanie można przerwać w dowolnej chwili, np. przez break;
}

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

Zastępuje wszystkie wystąpienia pasujące do wyrażenia regularnego. $replacement to maska stringa zastępującego albo funkcja callback.

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

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

Funkcja pozwala też na wiele zamian naraz, przez przekazanie w drugim parametrze tablicy w postaci wzorzec => zamiennik:

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

Parametr $limit ogranicza liczbę wykonanych zamian. Limit –1 oznacza brak limitu.

Jeśli $utf8 ma wartość true, obliczanie przechodzi w tryb Unicode, podobnie jak przy użyciu modyfikatora u.

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

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

Jeśli $captureOffset ma wartość true, do callbacku przekazywana jest również pozycja każdego dopasowania w stringu (w bajtach; w znakach, jeśli ustawiono $utf8). Zmienia to strukturę przekazywanej tablicy, w której każdy element jest parą [dopasowany_string, pozycja].

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

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

Jeśli $unmatchedAsNull ma wartość true, niedopasowane podwzorce przekazywane są do callbacku jako null; w przeciwnym razie przekazywane są jako pusty string albo pomijane:

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

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