Nette Documentation Preview

syntax 
Работа с низове
***************

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


Инсталация:

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

Всички примери предполагат създаден псевдоним:

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


Промяна на регистъра на буквите
===============================

Тези функции изискват PHP разширението `mbstring`.


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

Преобразува UTF-8 низ в малки букви.

```php
Strings::lower('Добър ден'); // 'добър ден'
```


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

Преобразува UTF-8 низ в главни букви.

```php
Strings::upper('Добър ден'); // 'ДОБЪР ДЕН'
```


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

Преобразува първата буква на UTF-8 низ в главна, останалите не променя.

```php
Strings::firstUpper('добър ден'); // 'Добър ден'
```


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

Преобразува първата буква на UTF-8 низ в малка, останалите не променя.

```php
Strings::firstLower('Добър ден'); // 'добър ден'
```


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

Преобразува първата буква на всяка дума в UTF-8 низ в главна, останалите в малки.

```php
Strings::capitalize('Добър ден'); // 'Добър Ден'
```


Редактиране на низ
==================


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

Премахва контролните знаци, нормализира краищата на редовете до `\n`, изрязва водещите и крайните празни редове, изрязва десните интервали на редовете, нормализира UTF-8 до нормална форма NFC.


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

Преобразува краищата на редовете в `\n`, използвани в unix системи. Краищата на редовете са: `\n`, `\r`, `\r\n`, U+2028 line separator, U+2029 paragraph separator.

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


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

Преобразува краищата на редовете в знаци, специфични за текущата платформа, т.е. `\r\n` на Windows и `\n` другаде. Краищата на редовете са: `\n`, `\r`, `\r\n`, U+2028 line separator, U+2029 paragraph separator.

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


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

Редактира UTF-8 низ във формата, използван в URL, т.е. премахва диакритиката и всички знаци, освен буквите от английската азбука и цифрите, заменя с тире.

```php
Strings::webalize('нашият продукт'); // 'nashiyat-produkt'
```

Ако трябва да се запазят и други знаци, те могат да бъдат посочени във втория параметър на функцията.

```php
Strings::webalize('10. изображение_id', '._'); // '10.-izobrazhenie_id'
```

С третия параметър може да се потисне преобразуването в малки букви.

```php
Strings::webalize('Добър ден', null, false); // 'Dobyr-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 = 'Кажете как сте?';
Strings::truncate($text, 5);       // 'Каже…'
Strings::truncate($text, 15);      // 'Кажете как…'
Strings::truncate($text, 30);      // 'Кажете как сте?'
Strings::truncate($text, 15, '~'); // 'Кажете как~'
```


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

Отстъпва многоредов текст отляво. Броят на отстъпите се определя от втория параметър, с какво да се отстъпва - от третия параметър (стойността по подразбиране е табулатор).

```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('червена'); // 7
```


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

Проверява дали низът `$haystack` започва с низ `$needle`.

```php
$haystack = 'Започва';
$needle = 'За';
Strings::startsWith($haystack, $needle); // true
```

.[note]
Използвайте нативната `str_starts_with()`:https://www.php.net/manual/en/function.str-starts-with.php.


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

Проверява дали низът `$haystack` завършва с низ `$needle`.

```php
$haystack = 'Завършва';
$needle = 'шва';
Strings::endsWith($haystack, $needle); // true
```

.[note]
Използвайте нативната `str_ends_with()`:https://www.php.net/manual/en/function.str-ends-with.php.


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

Проверява дали низът `$haystack` съдържа `$needle`.

```php
$haystack = 'Аудитория';
$needle = 'дитор';
Strings::contains($haystack, $needle); // true
```

.[note]
Използвайте нативната `str_contains()`:https://www.php.net/manual/en/function.str-contains.php.


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 - съвпадение на първите 2 знака
Strings::compare('Nette', 'Latte', -2); // true - съвпадение на последните 2 знака
```


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


Кодиране
========


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

Премахва от низа невалидни UTF-8 знаци.

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


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

Проверява дали това е валиден UTF-8 низ.

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

.[note]
Използвайте [Nette\Utils\Validator::isUnicode() |validators#isUnicode].


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

Преобразува UTF-8 низ в ASCII, т.е. премахва диакритиката и т.н.

```php
Strings::toAscii('жълт кон'); // 'zhalt kon'
```

.[caution]
Изисква PHP разширението `intl`.


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

Връща специфичен знак в UTF-8 от кодова точка (число в диапазона 0x0000..D7FF и 0xE000..10FFFF).

```php
Strings::chr(0xA9); // '©' в кодировка UTF-8
```


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

Връща кодовата точка на конкретен знак в UTF-8 (число в диапазона 0x0000..D7FF или 0xE000..10FFFF).

```php
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 .[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('жълт, кон', '~,\s*~', captureOffset: true);
// [['жълт', 0], ['кон', 7]]

Strings::split('жълт, кон', '~,\s*~', captureOffset: true, utf8: true);
// [['жълт', 0], ['кон', 6]]
```


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`, неуловените подшаблони се връщат като null; в противен случай се връщат като празен низ или не се връщат:

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

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

Ако `$utf8` е `true`, оценяването се превключва в Unicode режим. Подобно на това, когато посочите модификатор `u`:

```php
Strings::match('жълт кон', '~\w+~');
// ['лт']

Strings::match('жълт кон', '~\w+~', utf8: true);
// ['жълт']
```

Параметърът `$offset` може да се използва за определяне на позицията, от която да започне търсенето (в байтове; ако е зададено `$utf8`, тогава в знаци).

Ако `$captureOffset` е `true`, за всяко срещано съвпадение ще бъде върната и неговата позиция в низа (в байтове; ако е зададено `$utf8`, тогава в знаци). Това променя върнатата стойност на масив, където всеки елемент е двойка, съставена от съвпадащия низ и неговото отместване:

```php
Strings::match('жълт!', '~\w+(!+)?~', captureOffset: true);
// [['лт', 2]]

Strings::match('жълт!', '~\w+(!+)?~', captureOffset: true, utf8: true);
// [['жълт!', 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`, неуловените подшаблони се връщат като null; в противен случай се връщат като празен низ или не се връщат:

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

Ако `$utf8` е `true`, оценяването се превключва в Unicode режим. Подобно на това, когато посочите модификатор `u`:

```php
Strings::matchAll('жълт кон', '~\w+~');
/* [
	0 => ['лт'],
	1 => ['к'],
] */

Strings::matchAll('жълт кон', '~\w+~', utf8: true);
/* [
	0 => ['жълт'],
	1 => ['кон'],
] */
```

Параметърът `$offset` може да се използва за определяне на позицията, от която да започне търсенето (в байтове; ако е зададено `$utf8`, тогава в знаци).

Ако `$captureOffset` е `true`, за всяко срещано съвпадение ще бъде върната и неговата позиция в низа (в байтове; ако е зададено `$utf8`, тогава в знаци). Това променя върнатата стойност на масив, където всеки елемент е двойка, съставена от съвпадащия низ и неговата позиция:

```php
Strings::matchAll('жълт кон', '~\w+~', captureOffset: true);
/* [
	0 => [['лт', 2]],
	1 => [['к', 6]],
] */

Strings::matchAll('жълт кон', '~\w+~', captureOffset: true, utf8: true);
/* [
	0 => [['жълт', 0]],
	1 => [['кон', 5]],
] */
```

Ако `$lazy` е `true`, функцията връща `Generator` вместо масив, което носи значителни предимства в производителността при работа с големи низове. Генераторът позволява търсене на съвпадения постепенно, вместо на целия низ наведнъж. Това позволява ефективна работа дори с изключително големи входни текстове. Освен това можете по всяко време да прекъснете обработката, ако намерите търсеното съвпадение, което спестява изчислително време.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Намерено: $match[0]\n";
    // Обработката може да бъде прекъсната по всяко време
}
```


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

Заменя всички срещания, съответстващи на регулярен израз. `$replacement` е или маска на заместващия низ, или callback.

```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('жълт кон', '~\w+~', '--');
// 'ж--т --он'

Strings::replace('жълт кон', '~\w+~', '--', utf8: true);
// '-- --'
```

Ако `$captureOffset` е `true`, за всяко срещано съвпадение ще бъде предадена на callback-а и неговата позиция в низа (в байтове; ако е зададено `$utf8`, тогава в знаци). Това променя формата на предавания масив, където всеки елемент е двойка, съставена от съвпадащия низ и неговата позиция.

```php
Strings::replace(
	'жълт кон',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// dumps [['лт', 2]] и [['к', 6]]

Strings::replace(
	'жълт кон',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// dumps [['жълт', 0]] и [['кон', 5]]
```

Ако `$unmatchedAsNull` е `true`, неуловените подшаблони се предават на callback-а като 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('Добър ден'); // 'добър ден'

upper(string $s): string

Преобразува UTF-8 низ в главни букви.

Strings::upper('Добър ден'); // 'ДОБЪР ДЕН'

firstUpper(string $s): string

Преобразува първата буква на UTF-8 низ в главна, останалите не променя.

Strings::firstUpper('добър ден'); // 'Добър ден'

firstLower(string $s): string

Преобразува първата буква на UTF-8 низ в малка, останалите не променя.

Strings::firstLower('Добър ден'); // 'добър ден'

capitalize(string $s): string

Преобразува първата буква на всяка дума в UTF-8 низ в главна, останалите в малки.

Strings::capitalize('Добър ден'); // 'Добър Ден'

Редактиране на низ

normalize(string $s): string

Премахва контролните знаци, нормализира краищата на редовете до \n, изрязва водещите и крайните празни редове, изрязва десните интервали на редовете, нормализира UTF-8 до нормална форма NFC.

unixNewLines(string $s): string

Преобразува краищата на редовете в \n, използвани в unix системи. Краищата на редовете са: \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

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

platformNewLines(string $s): string

Преобразува краищата на редовете в знаци, специфични за текущата платформа, т.е. \r\n на Windows и \n другаде. Краищата на редовете са: \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

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

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

Редактира UTF-8 низ във формата, използван в URL, т.е. премахва диакритиката и всички знаци, освен буквите от английската азбука и цифрите, заменя с тире.

Strings::webalize('нашият продукт'); // 'nashiyat-produkt'

Ако трябва да се запазят и други знаци, те могат да бъдат посочени във втория параметър на функцията.

Strings::webalize('10. изображение_id', '._'); // '10.-izobrazhenie_id'

С третия параметър може да се потисне преобразуването в малки букви.

Strings::webalize('Добър ден', null, false); // 'Dobyr-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 = 'Кажете как сте?';
Strings::truncate($text, 5);       // 'Каже…'
Strings::truncate($text, 15);      // 'Кажете как…'
Strings::truncate($text, 30);      // 'Кажете как сте?'
Strings::truncate($text, 15, '~'); // 'Кажете как~'

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

Отстъпва многоредов текст отляво. Броят на отстъпите се определя от втория параметър, с какво да се отстъпва – от третия параметър (стойността по подразбиране е табулатор).

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('червена'); // 7

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

Проверява дали низът $haystack започва с низ $needle.

$haystack = 'Започва';
$needle = 'За';
Strings::startsWith($haystack, $needle); // true

Използвайте нативната str_starts_with().

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

Проверява дали низът $haystack завършва с низ $needle.

$haystack = 'Завършва';
$needle = 'шва';
Strings::endsWith($haystack, $needle); // true

Използвайте нативната str_ends_with().

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

Проверява дали низът $haystack съдържа $needle.

$haystack = 'Аудитория';
$needle = 'дитор';
Strings::contains($haystack, $needle); // true

Използвайте нативната str_contains().

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

Сравнение на два UTF-8 низа или техни части без оглед на регистъра на буквите. Ако $length съдържа null, се сравняват целите низове, ако е отрицателен, се сравнява съответният брой знаци от края на низовете, в противен случай се сравнява съответният брой знаци от началото.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - съвпадение на първите 2 знака
Strings::compare('Nette', 'Latte', -2); // true - съвпадение на последните 2 знака

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

checkEncoding(string $s): bool

Проверява дали това е валиден UTF-8 низ.

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

Използвайте Nette\Utils\Validator::isUnicode().

toAscii(string $s): string

Преобразува UTF-8 низ в ASCII, т.е. премахва диакритиката и т.н.

Strings::toAscii('жълт кон'); // 'zhalt kon'

Изисква PHP разширението intl.

chr(int $code): string

Връща специфичен знак в UTF-8 от кодова точка (число в диапазона 0×0000..D7FF и 0xE000..10FFFF).

Strings::chr(0xA9); // '©' в кодировка UTF-8

ord(string $char): int

Връща кодовата точка на конкретен знак в UTF-8 (число в диапазона 0×0000..D7FF или 0xE000..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('жълт, кон', '~,\s*~', captureOffset: true);
// [['жълт', 0], ['кон', 7]]

Strings::split('жълт, кон', '~,\s*~', captureOffset: true, utf8: true);
// [['жълт', 0], ['кон', 6]]

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, неуловените подшаблони се връщат като null; в противен случай се връщат като празен низ или не се връщат:

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

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

Ако $utf8 е true, оценяването се превключва в Unicode режим. Подобно на това, когато посочите модификатор u:

Strings::match('жълт кон', '~\w+~');
// ['лт']

Strings::match('жълт кон', '~\w+~', utf8: true);
// ['жълт']

Параметърът $offset може да се използва за определяне на позицията, от която да започне търсенето (в байтове; ако е зададено $utf8, тогава в знаци).

Ако $captureOffset е true, за всяко срещано съвпадение ще бъде върната и неговата позиция в низа (в байтове; ако е зададено $utf8, тогава в знаци). Това променя върнатата стойност на масив, където всеки елемент е двойка, съставена от съвпадащия низ и неговото отместване:

Strings::match('жълт!', '~\w+(!+)?~', captureOffset: true);
// [['лт', 2]]

Strings::match('жълт!', '~\w+(!+)?~', captureOffset: true, utf8: true);
// [['жълт!', 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, неуловените подшаблони се връщат като null; в противен случай се връщат като празен низ или не се връщат:

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

Ако $utf8 е true, оценяването се превключва в Unicode режим. Подобно на това, когато посочите модификатор u:

Strings::matchAll('жълт кон', '~\w+~');
/* [
	0 => ['лт'],
	1 => ['к'],
] */

Strings::matchAll('жълт кон', '~\w+~', utf8: true);
/* [
	0 => ['жълт'],
	1 => ['кон'],
] */

Параметърът $offset може да се използва за определяне на позицията, от която да започне търсенето (в байтове; ако е зададено $utf8, тогава в знаци).

Ако $captureOffset е true, за всяко срещано съвпадение ще бъде върната и неговата позиция в низа (в байтове; ако е зададено $utf8, тогава в знаци). Това променя върнатата стойност на масив, където всеки елемент е двойка, съставена от съвпадащия низ и неговата позиция:

Strings::matchAll('жълт кон', '~\w+~', captureOffset: true);
/* [
	0 => [['лт', 2]],
	1 => [['к', 6]],
] */

Strings::matchAll('жълт кон', '~\w+~', captureOffset: true, utf8: true);
/* [
	0 => [['жълт', 0]],
	1 => [['кон', 5]],
] */

Ако $lazy е true, функцията връща Generator вместо масив, което носи значителни предимства в производителността при работа с големи низове. Генераторът позволява търсене на съвпадения постепенно, вместо на целия низ наведнъж. Това позволява ефективна работа дори с изключително големи входни текстове. Освен това можете по всяко време да прекъснете обработката, ако намерите търсеното съвпадение, което спестява изчислително време.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Намерено: $match[0]\n";
    // Обработката може да бъде прекъсната по всяко време
}

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

Заменя всички срещания, съответстващи на регулярен израз. $replacement е или маска на заместващия низ, или callback.

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('жълт кон', '~\w+~', '--');
// 'ж--т --он'

Strings::replace('жълт кон', '~\w+~', '--', utf8: true);
// '-- --'

Ако $captureOffset е true, за всяко срещано съвпадение ще бъде предадена на callback-а и неговата позиция в низа (в байтове; ако е зададено $utf8, тогава в знаци). Това променя формата на предавания масив, където всеки елемент е двойка, съставена от съвпадащия низ и неговата позиция.

Strings::replace(
	'жълт кон',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// dumps [['лт', 2]] и [['к', 6]]

Strings::replace(
	'жълт кон',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// dumps [['жълт', 0]] и [['кон', 5]]

Ако $unmatchedAsNull е true, неуловените подшаблони се предават на callback-а като 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']