Функции для строк
*****************
.[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('Hello World'); // 'hello world'
```
upper(string $s): string .[method]
----------------------------------
Переводит строку UTF-8 в верхний регистр.
```php
Strings::upper('Hello World'); // 'HELLO WORLD'
```
firstUpper(string $s): string .[method]
---------------------------------------
Переводит первый символ строки UTF-8 в верхний регистр, остальные символы оставляет без изменений.
```php
Strings::firstUpper('hello world'); // 'Hello world'
```
firstLower(string $s): string .[method]
---------------------------------------
Переводит первый символ строки UTF-8 в нижний регистр, остальные символы оставляет без изменений.
```php
Strings::firstLower('Hello world'); // 'hello world'
```
capitalize(string $s): string .[method]
---------------------------------------
Переводит первый символ каждого слова строки UTF-8 в верхний регистр, а остальные - в нижний.
```php
Strings::capitalize('hello world'); // 'Hello World'
```
Изменение строки
================
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('žluťoučký kůň'); // 'zlutoucky-kun'
```
Если нужно сохранить другие символы, их можно указать во втором параметре.
```php
Strings::webalize('10. image_id', '._'); // '10.-image_id'
```
Третий параметр может отключить перевод в нижний регистр.
```php
Strings::webalize('Dobrý den', null, false); // 'Dobry-den'
```
.[caution]
Требует расширение PHP `intl`.
trim(string $s, string $charlist=self::TrimCharacters): string .[method]
------------------------------------------------------------------------
Убирает пробельные символы (или другие символы, заданные вторым параметром) в начале и конце строки UTF-8.
```php
Strings::trim(' Hello '); // 'Hello'
```
truncate(string $s, int $maxLen, string $append=`'…'`): string .[method]
------------------------------------------------------------------------
Сокращает строку UTF-8 до указанной максимальной длины, стараясь сохранить целые слова. Если строка укорочена, в конец добавляется многоточие (его можно изменить третьим параметром).
```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]
-----------------------------------------------------------------------
Делает отступ многострочного текста слева. Второй параметр задаёт число символов отступа, а третий - символ или символы для отступа (по умолчанию табуляция).
```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
```
startsWith(string $haystack, string $needle): bool .[method deprecated]
-----------------------------------------------------------------------
Проверяет, начинается ли строка `$haystack` со строки `$needle`.
```php
$haystack = 'Starts';
$needle = 'St';
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 = 'Ends';
$needle = 'ds';
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 = 'Auditorium';
$needle = 'dit';
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(array $strings): string .[method]
--------------------------------------------
Находит общий префикс строк. Возвращает пустую строку, если общего префикса нет.
```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]
-----------------------------------------------------------------------
Возвращает часть строки `$haystack` до `$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` после `$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]
---------------------------------------------------------------------
Возвращает позицию символа, с которого начинается `$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
$correctString = Strings::fixEncoding($invalidString);
```
checkEncoding(string $s): bool .[method deprecated]
---------------------------------------------------
Проверяет, является ли строка корректной строкой UTF-8.
```php
$isUtf8 = Strings::checkEncoding($string);
```
.[note]
Используйте [Nette\Utils\Validators::isUnicode() |validators#isUnicode()].
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); // '©' в кодировке UTF-8
```
ord(string $c): int .[method]
-----------------------------
Возвращает кодовую точку конкретного символа в UTF-8 (число в диапазоне 0x0000..D7FF или 0xE000..10FFFF).
```php
Strings::ord('©'); // 169 (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('ž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`, несовпавшие подшаблоны возвращаются как `null`; иначе они возвращаются как пустая строка или опускаются вовсе:
```php
Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (необязательная группа !+ не совпала)
Strings::match('hello', '~\w+(!+)?~', unmatchedAsNull: true);
// ['hello', null]
```
Если `$utf8` равен `true`, вычисление переключается в режим Unicode, как при использовании модификатора `u`:
```php
Strings::match('žlutý kůň', '~\w+~'); // Без UTF-8
// ['lut'] (совпадают только словесные символы ASCII)
Strings::match('žlutý kůň', '~\w+~', utf8: true); // С UTF-8
// ['žlutý'] (совпадают словесные символы Unicode)
```
Параметр `$offset` может задать начальную позицию поиска (в байтах; в символах, если задан `$utf8`).
Если `$captureOffset` равен `true`, возвращается также позиция каждого совпадения в строке (в байтах; в символах, если задан `$utf8`). Это меняет возвращаемое значение на массив, каждый элемент которого - пара из найденной строки и её смещения:
```php
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // Без UTF-8
// [['lut', 2]] (только совпадение ASCII, смещение в байтах)
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // С UTF-8
// [['žlutý!', 0], ['!', 5]] (совпадение Unicode, смещения в символах)
```
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('ž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";
// Обработку можно прервать в любой момент, например через break;
}
```
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!'
```
Функция позволяет также сделать несколько замен, если передать вторым параметром массив в формате `шаблон => замена`:
```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`, в callback передаётся также позиция каждого совпадения в строке (в байтах; в символах, если задан `$utf8`). Это меняет структуру передаваемого массива: каждый его элемент становится парой `[найденная_строка, позиция]`.
```php
Strings::replace(
'žlutý kůň',
'~\w+~',
function (array $m) { dump($m); return ''; },
captureOffset: true,
);
// выводит дампы [['lut', 2]] и [['k', 8]]
Strings::replace(
'žlutý kůň',
'~\w+~',
function (array $m) { dump($m); return ''; },
captureOffset: true,
utf8: true,
);
// выводит дампы [['žlutý', 0]] и [['kůň', 6]]
```
Если `$unmatchedAsNull` равен `true`, несовпавшие подшаблоны передаются в callback как `null`; иначе они передаются как пустая строка или опускаются:
```php
Strings::replace(
'ac',
'~(a)(b)*(c)~',
function (array $m) { dump($m); return ''; },
);
// выводит дамп ['ac', 'a', '', 'c']
Strings::replace(
'ac',
'~(a)(b)*(c)~',
function (array $m) { dump($m); return ''; },
unmatchedAsNull: true,
);
// выводит дамп ['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('Hello World'); // 'hello world'
upper (string $s):
string
Переводит строку UTF-8 в верхний регистр.
Strings::upper('Hello World'); // 'HELLO WORLD'
firstUpper (string $s): string
Переводит первый символ строки UTF-8 в верхний регистр, остальные
символы оставляет без изменений.
Strings::firstUpper('hello world'); // 'Hello world'
firstLower (string $s): string
Переводит первый символ строки UTF-8 в нижний регистр, остальные
символы оставляет без изменений.
Strings::firstLower('Hello world'); // 'hello world'
capitalize (string $s): string
Переводит первый символ каждого слова строки UTF-8 в верхний регистр, а
остальные – в нижний.
Strings::capitalize('hello world'); // 'Hello World'
Изменение строки
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);
Приводит концы строк к символам, свойственным текущей платформе, то
есть \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('žluťoučký kůň'); // 'zlutoucky-kun'
Если нужно сохранить другие символы, их можно указать во втором
параметре.
Strings::webalize('10. image_id', '._'); // '10.-image_id'
Третий параметр может отключить перевод в нижний регистр.
Strings::webalize('Dobrý den', null, false); // 'Dobry-den'
Требует расширение PHP intl.
trim (string $s, string
$charlist=self::TrimCharacters): string
Убирает пробельные символы (или другие символы, заданные вторым
параметром) в начале и конце строки UTF-8.
Strings::trim(' Hello '); // 'Hello'
truncate (string $s, int $maxLen,
string $append='…'): string
Сокращает строку UTF-8 до указанной максимальной длины, стараясь
сохранить целые слова. Если строка укорочена, в конец добавляется
многоточие (его можно изменить третьим параметром).
$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
Делает отступ многострочного текста слева. Второй параметр задаёт
число символов отступа, а третий – символ или символы для отступа (по
умолчанию табуляция).
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
startsWith (string $haystack,
string $needle): bool
Проверяет, начинается ли строка $haystack со строки $needle.
$haystack = 'Starts';
$needle = 'St';
Strings::startsWith($haystack, $needle); // true
Используйте нативную функцию str_starts_with().
endsWith (string $haystack,
string $needle): bool
Проверяет, заканчивается ли строка $haystack строкой
$needle.
$haystack = 'Ends';
$needle = 'ds';
Strings::endsWith($haystack, $needle); // true
Используйте нативную функцию str_ends_with().
contains (string $haystack,
string $needle): bool
Проверяет, содержит ли строка $haystack строку $needle.
$haystack = 'Auditorium';
$needle = 'dit';
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 (array $strings): string
Находит общий префикс строк. Возвращает пустую строку, если общего
префикса нет.
Strings::findPrefix(['prefix-a', 'prefix-bb', 'prefix-c']); // 'prefix-'
Strings::findPrefix(['Nette', 'is', 'great']); // ''
before (string $haystack, string $needle,
int $nth=1): ?string
Возвращает часть строки $haystack до $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 после $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
Возвращает позицию символа, с которого начинается $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.
$correctString = Strings::fixEncoding($invalidString);
checkEncoding (string
$s): bool
Проверяет, является ли строка корректной строкой UTF-8.
$isUtf8 = Strings::checkEncoding($string);
Используйте Nette\Utils\Validators::isUnicode().
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 или 0xE000..10FFFF).
Strings::chr(0xA9); // '©' в кодировке UTF-8
ord (string $c):
int
Возвращает кодовую точку конкретного символа в UTF-8 (число в диапазоне
0×0000..D7FF или 0xE000..10FFFF).
Strings::ord('©'); // 169 (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, несовпавшие подшаблоны
возвращаются как null; иначе они возвращаются как пустая строка
или опускаются вовсе:
Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (необязательная группа !+ не совпала)
Strings::match('hello', '~\w+(!+)?~', unmatchedAsNull: true);
// ['hello', null]
Если $utf8 равен true, вычисление переключается в режим
Unicode, как при использовании модификатора u:
Strings::match('žlutý kůň', '~\w+~'); // Без UTF-8
// ['lut'] (совпадают только словесные символы ASCII)
Strings::match('žlutý kůň', '~\w+~', utf8: true); // С UTF-8
// ['žlutý'] (совпадают словесные символы Unicode)
Параметр $offset может задать начальную позицию поиска (в байтах;
в символах, если задан $utf8).
Если $captureOffset равен true, возвращается также позиция
каждого совпадения в строке (в байтах; в символах, если задан
$utf8). Это меняет возвращаемое значение на массив, каждый элемент
которого – пара из найденной строки и её смещения:
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // Без UTF-8
// [['lut', 2]] (только совпадение ASCII, смещение в байтах)
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // С UTF-8
// [['žlutý!', 0], ['!', 5]] (совпадение Unicode, смещения в символах)
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('ž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";
// Обработку можно прервать в любой момент, например через break;
}
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!'
Функция позволяет также сделать несколько замен, если передать
вторым параметром массив в формате шаблон => замена:
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, в callback передаётся также позиция
каждого совпадения в строке (в байтах; в символах, если задан
$utf8). Это меняет структуру передаваемого массива: каждый его
элемент становится парой [найденная_строка, позиция].
Strings::replace(
'žlutý kůň',
'~\w+~',
function (array $m) { dump($m); return ''; },
captureOffset: true,
);
// выводит дампы [['lut', 2]] и [['k', 8]]
Strings::replace(
'žlutý kůň',
'~\w+~',
function (array $m) { dump($m); return ''; },
captureOffset: true,
utf8: true,
);
// выводит дампы [['žlutý', 0]] и [['kůň', 6]]
Если $unmatchedAsNull равен true, несовпавшие подшаблоны
передаются в callback как null; иначе они передаются как пустая строка
или опускаются:
Strings::replace(
'ac',
'~(a)(b)*(c)~',
function (array $m) { dump($m); return ''; },
);
// выводит дамп ['ac', 'a', '', 'c']
Strings::replace(
'ac',
'~(a)(b)*(c)~',
function (array $m) { dump($m); return ''; },
unmatchedAsNull: true,
);
// выводит дамп ['ac', 'a', null, 'c']