strings.texy

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

.[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...10FFFFFF).

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


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

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

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