Функции для строк

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

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('ž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).

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

Регистр букв

lower (string $s): string

upper (string $s): string

firstUpper (string $s): string

firstLower (string $s): string

capitalize (string $s): string

Изменение строки

normalize (string $s): string

unixNewLines (string $s): string

platformNewLines (string $s): string

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

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

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

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

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

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

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

reverse (string $s): string

length (string $s): int

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

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

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

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

findPrefix (array $strings): string

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

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

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

Кодировка

fixEncoding (string $s): string

checkEncoding (string $s): bool

toAscii (string $s): string

chr (int $code): string

ord (string $c): int

Регулярные выражения

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

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

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

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

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