Работа со строками
Nette\Utils\Strings – это статический класс с полезными функциями для работы со строками, преимущественно в кодировке UTF-8.
Установка:
composer require nette/utils
Все примеры предполагают созданный псевдоним:
use Nette\Utils\Strings;
Изменение регистра букв
Эти функции требуют расширения PHP mbstring
.
lower (string $s): string
Преобразует строку UTF-8 в нижний регистр.
Strings::lower('Dobrý den'); // 'dobrý den'
upper (string $s): string
Преобразует строку UTF-8 в верхний регистр.
Strings::upper('Dobrý den'); // 'DOBRÝ DEN'
firstUpper (string $s): string
Преобразует первую букву строки UTF-8 в верхний регистр, остальные не меняет.
Strings::firstUpper('dobrý den'); // 'Dobrý den'
firstLower (string $s): string
Преобразует первую букву строки UTF-8 в нижний регистр, остальные не меняет.
Strings::firstLower('Dobrý den'); // 'dobrý den'
capitalize (string $s): string
Преобразует первую букву каждого слова в строке UTF-8 в верхний регистр, остальные в нижний.
Strings::capitalize('Dobrý den'); // 'Dobrý Den'
Редактирование строки
normalize (string $s): string
Удаляет управляющие символы, нормализует концы строк в \n
,
обрезает начальные и конечные пустые строки, обрезает пробелы справа
на строках, нормализует UTF-8 в нормальную форму NFC.
unixNewLines (string $s): string
Преобразует концы строк в \n
, используемые в unix-системах. Концы
строк: \n
, \r
, \r\n
, U+2028 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('náš produkt'); // 'nas-produkt'
Если нужно сохранить и другие символы, их можно указать во втором параметре функции.
Strings::webalize('10. obrázek_id', '._'); // '10.-obrazek_id'
Третьим параметром можно отключить преобразование в нижний регистр.
Strings::webalize('Dobrý den', null, false); // 'Dobry-den'
Требует расширения PHP intl
.
trim (string $s, ?string $charlist=null): string
Обрезает пробелы (или другие символы, указанные вторым параметром) с начала и конца строки UTF-8.
Strings::trim(' Hello '); // 'Hello'
truncate (string $s, int $maxLen,
string $append=`'…'
`): string
Обрезает строку UTF-8 до указанной максимальной длины, стараясь сохранять целые слова. Если строка сокращается, в конец добавляется многоточие (можно изменить третьим параметром).
$text = 'Řekněte, jak se máte?';
Strings::truncate($text, 5); // 'Řekn…'
Strings::truncate($text, 20); // 'Řekněte, jak se…'
Strings::truncate($text, 30); // 'Řekněte, jak se máte?'
Strings::truncate($text, 20, '~'); // 'Řekněte, jak se~'
indent (string $s, int $level=1, string
$indentationChar=`"\t"
`): string
Добавляет отступ слева к многострочному тексту. Количество отступов определяет второй параметр, чем отступать – третий параметр (по умолчанию табуляция).
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 = 'Začíná';
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true
Используйте нативную str_starts_with()
.
endsWith (string $haystack, string $needle): bool
Проверяет, заканчивается ли строка $haystack
строкой
$needle
.
$haystack = 'Končí';
$needle = 'čí';
Strings::endsWith($haystack, $needle); // true
Используйте нативную str_ends_with()
.
contains (string $haystack, string $needle): bool
Проверяет, содержит ли строка $haystack
строку $needle
.
$haystack = 'Posluchárna';
$needle = 'sluch';
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('ž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 $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('ž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+~');
// ['lut']
Strings::match('žlutý kůň', '~\w+~', utf8: true);
// ['žlutý']
Параметр $offset
можно использовать для указания позиции, с
которой следует начать поиск (в байтах; если установлено $utf8
, то
в символах).
Если $captureOffset
равно true
, для каждого найденного
совпадения будет также возвращена его позиция в строке (в байтах; если
установлено $utf8
, то в символах). Это изменяет возвращаемое
значение на массив, где каждый элемент является парой, состоящей из
совпавшей строки и ее смещения:
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true);
// [['lut', 2]]
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true);
// [['žlutý!', 0], ['!', 5]]
matchAll (string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $patternOrder=false, bool $utf8=false, bool $lazy=false): array|Generator
Ищет в строке все вхождения, соответствующие регулярному выражению, и возвращает массив массивов с найденным выражением и отдельными подвыражениями.
Strings::matchAll('hello, world!!', '~\w+(!+)?~');
/* [
0 => ['hello'],
1 => ['world!!', '!!'],
] */
Если $patternOrder
равно true
, структура результатов
изменяется так, что в первом элементе находится массив полных
совпадений шаблона, во втором – массив строк, которым соответствует
первый подшаблон в скобках, и так далее:
Strings::matchAll('hello, world!!', '~\w+(!+)?~', patternOrder: true);
/* [
0 => ['hello', 'world!!'],
1 => ['', '!!'],
] */
Если $unmatchedAsNull
равно true
, незахваченные подшаблоны
возвращаются как 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 "Найдено: $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('ž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,
);
// dumps [['lut', 2]] и [['k', 8]]
Strings::replace(
'žlutý kůň',
'~\w+~',
function (array $m) { dump($m); return ''; },
captureOffset: true,
utf8: true,
);
// dumps [['žlutý', 0]] и [['kůň', 6]]
Если $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']