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

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 разделител на редове, 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('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

Отстъпване на многоредовия текст наляво. Броят на отстъпите се определя от втория параметър, който се използва за отстъпите на третия параметър (стойността по подразбиране е tab).

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

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

Сравняване на два низа в UTF-8 или части от низове, които не се различават по размер. Ако $length съдържа null, се сравняват цели низове, ако е отрицателен, се сравняват съответния брой символи от края на низовете, в противен случай се сравняват съответния брой символи от началото.

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

Намира общото начало на низовете. Или връща празен низ, ако не е намерен общ префикс.

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

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

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

ord(string $char): int

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

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, тогава незаловените подизрази се връщат като нула; в противен случай се връщат като празен низ или не се връщат:

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, тогава несъответстващите подшаблони се връщат като нула; в противен случай те се връщат като празни низове или не се връщат:

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";
    // 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

Заменя всички срещания, отговарящи на регулярен израз. $replacement – е или маска на заместващ низ, или обратна връзка.

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, то за всяко срещнато съвпадение позицията му в низ (в байтове; в символи, ако е зададено $utf8 ) също ще бъде предадена на обратната връзка. Това променя формата на предадения масив, в който всеки елемент е двойка, състояща се от съответстващия низ и неговата позиция.

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; в противен случай те се предават като празен низ или не се предават:

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