Nette Documentation Preview

syntax 
Робота з рядками
****************

.[perex]
[api:Nette\Utils\Strings] статичний клас, що містить корисні функції для роботи з рядками, переважно в кодуванні UTF-8.


Встановлення:

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

У всіх прикладах передбачається, що псевдонім уже створено:

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


З урахуванням регістру .[#toc-letter-case]
==========================================

Для цих функцій потрібне розширення PHP `mbstring`.


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

Перетворює рядок UTF-8 у малий регістр.

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


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

Перетворює рядок UTF-8 у верхній регістр.

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


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

Перетворює першу літеру рядка UTF-8 у верхній регістр, інші не змінює.

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


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

Перетворює першу літеру рядка UTF-8 на малу, інші не змінює.

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


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

Перетворює першу літеру кожного слова в рядку UTF-8 на верхній регістр, інші - на нижній.

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


Редагувати рядок .[#toc-editing-a-string]
=========================================


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

Видаляє керівні символи, нормалізує перенесення рядків до `\n`, обрізає провідні та відстаючі порожні рядки, обрізає праві перенесення рядків, нормалізує UTF-8 до нормальної форми NFC.


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

Перетворює перенесення рядків на `\n`, використовувані в системах Unix. Розриви рядків: `\n`, `\r`, `\r\n`, U+2028 роздільник рядків, U+2029 роздільник абзаців.

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


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

Перетворює переклади рядків на символи, характерні для поточної платформи, тобто `\r\n` у Windows і `\n` в іншому місці. Розриви рядків: `\n`, `\r`, `\r\n`, U+2028 роздільник рядків, U+2029 роздільник абзаців.

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


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

Змінює рядок UTF-8 до формату, використовуваного в URL, тобто видаляє діакритичні знаки та замінює всі символи, окрім букв англійського алфавіту та цифр, на дефіс.

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

Якщо необхідно зберегти інші символи, їх можна вказати в другому параметрі функції.

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

Третій параметр можна використовувати для придушення перетворення в нижній регістр.

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

.[caution]
Потрібне розширення PHP `intl`.


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

Обрізає пробіли (або інші символи, зазначені другим параметром) з початку і кінця рядка UTF-8.

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


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

Усікає рядок UTF-8 до вказаної максимальної довжини, намагаючись зберегти цілі слова. Якщо рядок усічений, то в кінець додається триплет (можна змінити за допомогою третього параметра).

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

Відступ багаторядкового тексту зліва. Кількість відступів визначається другим параметром, який використовується для відступів третього параметра (значення за замовчуванням - tab).

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


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

Завершує рядок UTF-8 до вказаної довжини, повторюючи рядок `$pad` зліва.

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


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

Завершує рядок UTF-8 до зазначеної довжини, повторюючи рядок `$pad` праворуч.

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


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

Повертає частину рядка UTF-8 `$s`, задану початковою позицією `$start` і довжиною `$length`. Якщо `$start` від'ємний, то рядок, що повертається, починатиметься з символу -`$start` символу з кінця.

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

Змінює рядок UTF-8.

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


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

Повертає кількість символів (не байтів) у рядку UTF-8.

Це кількість кодових точок Unicode, яка може відрізнятися від кількості графем.

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


/--comment









































\--


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

Порівняння двох рядків UTF-8 або частин рядків без урахування регістру. Якщо `$length` містить null, то порівнюються цілі рядки, якщо від'ємно, то порівнюється відповідна кількість символів з кінця рядків, інакше порівнюється відповідна кількість символів з початку.

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

Знаходить загальний початок рядків. Або повертає порожній рядок, якщо загальний префікс не знайдено.

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

Повертає частину рядка `$haystack` перед n-м `$nth` входженням рядка `$needle`. Або `null`, якщо `$needle` не було знайдено. Якщо `$nth` від'ємний, то пошук ведеться з кінця рядка.

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

Повертає частину рядка `$haystack` після n-го `$nth` входження рядка `$needle`. Або `null`, якщо `$needle` не було знайдено. Якщо `$nth` від'ємний, то пошук ведеться з кінця рядка.

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

Повертає позицію в символах n-го `$nth` входження рядка `$needle` в рядок `$haystack`. Або `null`, якщо `$needle` не було знайдено. Якщо `$nth` від'ємний, то пошук ведеться з кінця рядка.

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


Кодування .[#toc-kodovani]
==========================


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

Видаляє з рядка неприпустимі символи UTF-8.

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


/--comment









\--


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

Перетворює рядок UTF-8 на ASCII, тобто видаляє діакритичні знаки тощо.

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

.[caution]
Потрібне розширення PHP `intl`.


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

Повертає певний символ UTF-8 з кодової точки (число в діапазоні 0x0000...D7FF і 0xE000...10FFFF).

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


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

Повертає кодову точку UTF-8 певного символу (число в діапазоні 0x0000...D7FF або 0xE000...10FFFF).

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


Регулярні вирази .[#toc-fixencoding]
====================================

Клас Strings надає функції для роботи з регулярними виразами. На відміну від власних функцій PHP, вони мають більш зрозумілий API, кращу підтримку Unicode і, що найважливіше, виявлення помилок. Будь-яка помилка під час компіляції або обробки виразу призведе до виникнення виключення `Nette\RegexpException`.


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

Розділяє рядок на масив відповідно до регулярного виразу. Вирази в круглих дужках також будуть перехоплені та повернуті.

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

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

Якщо `$skipEmpty` дорівнює `true`, то будуть повернуті тільки непорожні записи:

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

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

Якщо `$limit`, то будуть повернуті тільки підрядки до межі, а інша частина рядка буде поміщена в останній елемент. Межа -1 або 0 означає відсутність межі.

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

Якщо `$utf8` дорівнює `true`, то оцінка переключиться в режим Unicode. Це аналогічно вказівці модифікатора `u`.

Якщо `$captureOffset` дорівнює `true`, то для кожного збігу, що трапляється, буде повернуто його позицію в рядку (у байтах; у символах, якщо встановлено `$utf8` ). Це змінює значення, що повертається, на масив, кожний елемент якого є парою, що складається з рядка, що збігається, та його позиції.

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

Шукає в рядку частину, що відповідає регулярному виразу, і повертає масив зі знайденим виразом і кожним підвиразом, або `null`.

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

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

Якщо `$unmatchedAsNull` дорівнює `true`, то не захоплені підвирази повертаються як нульові; в іншому разі вони повертаються як порожній рядок або не повертаються:

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

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

Якщо `$utf8` дорівнює `true`, то оцінка перемикається в режим Unicode. Аналогічно до вказівки модифікатора `u`:

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

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

Параметр `$offset` може використовуватися для вказівки позиції, з якої слід починати пошук (у байтах; у символах, якщо встановлено `$utf8` ).

Якщо `$captureOffset` дорівнює `true`, то для кожного збігу, що трапляється, буде також повернуто його позицію в рядку (у байтах; якщо встановлено `$utf8`, то в символах). Це перетворює значення, що повертається, на масив, кожен елемент якого є парою, що складається з рядка, що збігається, та його зміщення:

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

Шукає в рядку всі входження, що відповідають регулярному виразу, і повертає масив масивів, що містять знайдений вираз і кожен підвираз.

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

Якщо `$patternOrder` дорівнює `true`, то структура результатів змінюється таким чином, що перший запис являє собою масив повних збігів шаблону, другий - масив рядків, що збігаються з першим підшаблоном у круглих дужках, і так далі:

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

Якщо `$unmatchedAsNull` дорівнює `true`, то підшаблони, що не збігаються, повертаються як нульові; в іншому разі вони повертаються як порожні рядки або не повертаються:

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

Якщо `$utf8` дорівнює `true`, то оцінка перемикається в режим Unicode. Аналогічно до вказівки модифікатора `u`:

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

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

Параметр `$offset` може використовуватися для вказівки позиції, з якої слід починати пошук (у байтах; у символах, якщо встановлено `$utf8` ).

Якщо `$captureOffset` дорівнює `true`, то для кожного збігу, що трапляється, буде також повернуто його позицію в рядку (у байтах; якщо встановлено `$utf8`, то в символах). Це змінює значення, що повертається, на масив, кожен елемент якого є парою, що складається з рядка, що збігається, та його позиції:

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

Якщо `$lazy` є `true`, функція повертає `Generator` замість масиву, що дає значні переваги у продуктивності при роботі з великими рядками. Генератор дозволяє шукати збіги поступово, а не обробляти весь рядок одразу. Це дозволяє ефективно працювати з дуже великими вхідними текстами. Крім того, ви можете перервати обробку в будь-який момент, якщо знайдете потрібний збіг, заощадивши час обчислень.

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

Замінює всі входження, що відповідають регулярному виразу. `$replacement` - це або маска рядка заміни, або зворотний виклик.

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

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

Функція також допускає множинну заміну, передаючи в другому параметрі масив виду `pattern => replacement`:

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

Параметр `$limit` обмежує кількість замін, які можуть бути зроблені. Межа -1 означає відсутність межі.

Якщо `$utf8` дорівнює `true`, то оцінка перемикається в режим Unicode. Це аналогічно вказівці модифікатора `u`.

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

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

Якщо `$captureOffset` дорівнює `true`, то для кожного збігу, що трапляється, його позиція в рядку (у байтах; у символах, якщо встановлено `$utf8` ) також буде передана зворотному виклику. Це змінює форму переданого масиву, де кожен елемент являє собою пару, що складається з рядка, що збігається, та його позиції.

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

Якщо `$unmatchedAsNull` - `true`, то підшаблони, що не збігаються, передаються у зворотний виклик як null; в іншому разі вони передаються як порожній рядок або не передаються:

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

Робота з рядками

Nette\Utils\Strings статичний клас, що містить корисні функції для роботи з рядками, переважно в кодуванні UTF-8.

Встановлення:

composer require nette/utils

У всіх прикладах передбачається, що псевдонім уже створено:

use Nette\Utils\Strings;

З урахуванням регістру

Для цих функцій потрібне розширення PHP mbstring.

lower(string $s): string

Перетворює рядок UTF-8 у малий регістр.

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

upper(string $s): string

Перетворює рядок UTF-8 у верхній регістр.

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

firstUpper(string $s): string

Перетворює першу літеру рядка UTF-8 у верхній регістр, інші не змінює.

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

firstLower(string $s): string

Перетворює першу літеру рядка UTF-8 на малу, інші не змінює.

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

capitalize(string $s): string

Перетворює першу літеру кожного слова в рядку UTF-8 на верхній регістр, інші – на нижній.

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

Редагувати рядок

normalize(string $s): string

Видаляє керівні символи, нормалізує перенесення рядків до \n, обрізає провідні та відстаючі порожні рядки, обрізає праві перенесення рядків, нормалізує UTF-8 до нормальної форми NFC.

unixNewLines(string $s): string

Перетворює перенесення рядків на \n, використовувані в системах Unix. Розриви рядків: \n, \r, \r\n, U+2028 роздільник рядків, U+2029 роздільник абзаців.

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

platformNewLines(string $s): string

Перетворює переклади рядків на символи, характерні для поточної платформи, тобто \r\n у Windows і \n в іншому місці. Розриви рядків: \n, \r, \r\n, U+2028 роздільник рядків, U+2029 роздільник абзаців.

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

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

Змінює рядок UTF-8 до формату, використовуваного в URL, тобто видаляє діакритичні знаки та замінює всі символи, окрім букв англійського алфавіту та цифр, на дефіс.

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

Якщо необхідно зберегти інші символи, їх можна вказати в другому параметрі функції.

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

Третій параметр можна використовувати для придушення перетворення в нижній регістр.

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

Потрібне розширення PHP intl.

trim(string $s, ?string $charlist=null): string

Обрізає пробіли (або інші символи, зазначені другим параметром) з початку і кінця рядка UTF-8.

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

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

Усікає рядок UTF-8 до вказаної максимальної довжини, намагаючись зберегти цілі слова. Якщо рядок усічений, то в кінець додається триплет (можна змінити за допомогою третього параметра).

$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

Відступ багаторядкового тексту зліва. Кількість відступів визначається другим параметром, який використовується для відступів третього параметра (значення за замовчуванням – tab).

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

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

Завершує рядок UTF-8 до вказаної довжини, повторюючи рядок $pad зліва.

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

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

Завершує рядок UTF-8 до зазначеної довжини, повторюючи рядок $pad праворуч.

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

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

Повертає частину рядка UTF-8 $s, задану початковою позицією $start і довжиною $length. Якщо $start від'ємний, то рядок, що повертається, починатиметься з символу -$start символу з кінця.

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

reverse(string $s): string

Змінює рядок UTF-8.

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

length(string $s): int

Повертає кількість символів (не байтів) у рядку UTF-8.

Це кількість кодових точок Unicode, яка може відрізнятися від кількості графем.

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

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

Порівняння двох рядків UTF-8 або частин рядків без урахування регістру. Якщо $length містить null, то порівнюються цілі рядки, якщо від'ємно, то порівнюється відповідна кількість символів з кінця рядків, інакше порівнюється відповідна кількість символів з початку.

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

Знаходить загальний початок рядків. Або повертає порожній рядок, якщо загальний префікс не знайдено.

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

Повертає частину рядка $haystack перед n-м $nth входженням рядка $needle. Або null, якщо $needle не було знайдено. Якщо $nth від'ємний, то пошук ведеться з кінця рядка.

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

Повертає частину рядка $haystack після n-го $nth входження рядка $needle. Або null, якщо $needle не було знайдено. Якщо $nth від'ємний, то пошук ведеться з кінця рядка.

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

Повертає позицію в символах n-го $nth входження рядка $needle в рядок $haystack. Або null, якщо $needle не було знайдено. Якщо $nth від'ємний, то пошук ведеться з кінця рядка.

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

Кодування

fixEncoding(string $s): string

Видаляє з рядка неприпустимі символи UTF-8.

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

toAscii(string $s): string

Перетворює рядок UTF-8 на ASCII, тобто видаляє діакритичні знаки тощо.

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

Потрібне розширення PHP intl.

chr(int $code): string

Повертає певний символ UTF-8 з кодової точки (число в діапазоні 0×0000…D7FF і 0×E000…10FFFF).

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

ord(string $char): int

Повертає кодову точку UTF-8 певного символу (число в діапазоні 0×0000…D7FF або 0×E000…10FFFF).

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

Регулярні вирази

Клас Strings надає функції для роботи з регулярними виразами. На відміну від власних функцій PHP, вони мають більш зрозумілий API, кращу підтримку Unicode і, що найважливіше, виявлення помилок. Будь-яка помилка під час компіляції або обробки виразу призведе до виникнення виключення Nette\RegexpException.

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

Розділяє рядок на масив відповідно до регулярного виразу. Вирази в круглих дужках також будуть перехоплені та повернуті.

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

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

Якщо $skipEmpty дорівнює true, то будуть повернуті тільки непорожні записи:

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

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

Якщо $limit, то будуть повернуті тільки підрядки до межі, а інша частина рядка буде поміщена в останній елемент. Межа –1 або 0 означає відсутність межі.

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

Якщо $utf8 дорівнює true, то оцінка переключиться в режим Unicode. Це аналогічно вказівці модифікатора u.

Якщо $captureOffset дорівнює true, то для кожного збігу, що трапляється, буде повернуто його позицію в рядку (у байтах; у символах, якщо встановлено $utf8 ). Це змінює значення, що повертається, на масив, кожний елемент якого є парою, що складається з рядка, що збігається, та його позиції.

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

Шукає в рядку частину, що відповідає регулярному виразу, і повертає масив зі знайденим виразом і кожним підвиразом, або null.

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

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

Якщо $unmatchedAsNull дорівнює true, то не захоплені підвирази повертаються як нульові; в іншому разі вони повертаються як порожній рядок або не повертаються:

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

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

Якщо $utf8 дорівнює true, то оцінка перемикається в режим Unicode. Аналогічно до вказівки модифікатора u:

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

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

Параметр $offset може використовуватися для вказівки позиції, з якої слід починати пошук (у байтах; у символах, якщо встановлено $utf8 ).

Якщо $captureOffset дорівнює true, то для кожного збігу, що трапляється, буде також повернуто його позицію в рядку (у байтах; якщо встановлено $utf8, то в символах). Це перетворює значення, що повертається, на масив, кожен елемент якого є парою, що складається з рядка, що збігається, та його зміщення:

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

Шукає в рядку всі входження, що відповідають регулярному виразу, і повертає масив масивів, що містять знайдений вираз і кожен підвираз.

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

Якщо $patternOrder дорівнює true, то структура результатів змінюється таким чином, що перший запис являє собою масив повних збігів шаблону, другий – масив рядків, що збігаються з першим підшаблоном у круглих дужках, і так далі:

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

Якщо $unmatchedAsNull дорівнює true, то підшаблони, що не збігаються, повертаються як нульові; в іншому разі вони повертаються як порожні рядки або не повертаються:

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

Якщо $utf8 дорівнює true, то оцінка перемикається в режим Unicode. Аналогічно до вказівки модифікатора u:

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

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

Параметр $offset може використовуватися для вказівки позиції, з якої слід починати пошук (у байтах; у символах, якщо встановлено $utf8 ).

Якщо $captureOffset дорівнює true, то для кожного збігу, що трапляється, буде також повернуто його позицію в рядку (у байтах; якщо встановлено $utf8, то в символах). Це змінює значення, що повертається, на масив, кожен елемент якого є парою, що складається з рядка, що збігається, та його позиції:

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

Якщо $lazy є true, функція повертає Generator замість масиву, що дає значні переваги у продуктивності при роботі з великими рядками. Генератор дозволяє шукати збіги поступово, а не обробляти весь рядок одразу. Це дозволяє ефективно працювати з дуже великими вхідними текстами. Крім того, ви можете перервати обробку в будь-який момент, якщо знайдете потрібний збіг, заощадивши час обчислень.

$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

Замінює всі входження, що відповідають регулярному виразу. $replacement – це або маска рядка заміни, або зворотний виклик.

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

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

Функція також допускає множинну заміну, передаючи в другому параметрі масив виду pattern => replacement:

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

Параметр $limit обмежує кількість замін, які можуть бути зроблені. Межа –1 означає відсутність межі.

Якщо $utf8 дорівнює true, то оцінка перемикається в режим Unicode. Це аналогічно вказівці модифікатора u.

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

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

Якщо $captureOffset дорівнює true, то для кожного збігу, що трапляється, його позиція в рядку (у байтах; у символах, якщо встановлено $utf8 ) також буде передана зворотному виклику. Це змінює форму переданого масиву, де кожен елемент являє собою пару, що складається з рядка, що збігається, та його позиції.

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

Якщо $unmatchedAsNull – true, то підшаблони, що не збігаються, передаються у зворотний виклик як null; в іншому разі вони передаються як порожній рядок або не передаються:

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