Робота з рядками

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 = 'Скажіть, як справи?';
Strings::truncate($text, 5);       // 'Скаж…'
Strings::truncate($text, 20);      // 'Скажіть, як спра…'
Strings::truncate($text, 30);      // 'Скажіть, як справи?'
Strings::truncate($text, 20, '~'); // 'Скажіть, як спра~'

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 = 'Починається';
$needle = 'По';
Strings::startsWith($haystack, $needle); // true

Використовуйте нативну function.str-starts-with.php.

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

Перевіряє, чи закінчується рядок $haystack рядком $needle.

$haystack = 'Закінчується';
$needle = 'ється';
Strings::endsWith($haystack, $needle); // true

Використовуйте нативну function.str-ends-with.php.

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

Перевіряє, чи містить рядок $haystack рядок $needle.

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

Використовуйте нативну function.str-contains.php.

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, то в символах).

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 => ['', '!!'],
] */

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ůň'],
] */

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

Робота з рядками

Зміна регістру літер

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=null): string

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

indent (string $s, int $level=1, string $indentationChar=`"\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 (…$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 $char): 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