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

Nette\Utils\Strings е статичен клас с полезни функции за работа с низове, предимно в кодировка UTF-8.

Инсталация:

composer require nette/utils

Всички примери предполагат създаден псевдоним:

use Nette\Utils\Strings;

Промяна на регистъра на буквите

Тези функции изискват PHP разширението mbstring.

lower (string $s): string

Преобразува UTF-8 низ в малки букви.

Strings::lower('Добър ден'); // 'добър ден'

upper (string $s): string

Преобразува UTF-8 низ в главни букви.

Strings::upper('Добър ден'); // 'ДОБЪР ДЕН'

firstUpper (string $s): string

Преобразува първата буква на UTF-8 низ в главна, останалите не променя.

Strings::firstUpper('добър ден'); // 'Добър ден'

firstLower (string $s): string

Преобразува първата буква на UTF-8 низ в малка, останалите не променя.

Strings::firstLower('Добър ден'); // 'добър ден'

capitalize (string $s): string

Преобразува първата буква на всяка дума в UTF-8 низ в главна, останалите в малки.

Strings::capitalize('Добър ден'); // 'Добър Ден'

Редактиране на низ

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('нашият продукт'); // 'nashiyat-produkt'

Ако трябва да се запазят и други знаци, те могат да бъдат посочени във втория параметър на функцията.

Strings::webalize('10. изображение_id', '._'); // '10.-izobrazhenie_id'

С третия параметър може да се потисне преобразуването в малки букви.

Strings::webalize('Добър ден', null, false); // 'Dobyr-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, 15);      // 'Кажете как…'
Strings::truncate($text, 30);      // 'Кажете как сте?'
Strings::truncate($text, 15, '~'); // 'Кажете как~'

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('червена'); // 7

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

Проверява дали низът $haystack започва с низ $needle.

$haystack = 'Започва';
$needle = 'За';
Strings::startsWith($haystack, $needle); // true

Използвайте нативната str_starts_with().

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

Проверява дали низът $haystack завършва с низ $needle.

$haystack = 'Завършва';
$needle = 'шва';
Strings::endsWith($haystack, $needle); // true

Използвайте нативната str_ends_with().

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

Проверява дали низът $haystack съдържа $needle.

$haystack = 'Аудитория';
$needle = 'дитор';
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('жълт кон'); // 'zhalt kon'

Изисква 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('жълт, кон', '~,\s*~', captureOffset: true);
// [['жълт', 0], ['кон', 7]]

Strings::split('жълт, кон', '~,\s*~', captureOffset: true, utf8: true);
// [['жълт', 0], ['кон', 6]]

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('жълт кон', '~\w+~');
// ['лт']

Strings::match('жълт кон', '~\w+~', utf8: true);
// ['жълт']

Параметърът $offset може да се използва за определяне на позицията, от която да започне търсенето (в байтове; ако е зададено $utf8, тогава в знаци).

Strings::match('жълт!', '~\w+(!+)?~', captureOffset: true);
// [['лт', 2]]

Strings::match('жълт!', '~\w+(!+)?~', captureOffset: true, utf8: true);
// [['жълт!', 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('жълт кон', '~\w+~');
/* [
	0 => ['лт'],
	1 => ['к'],
] */

Strings::matchAll('жълт кон', '~\w+~', utf8: true);
/* [
	0 => ['жълт'],
	1 => ['кон'],
] */

Strings::matchAll('жълт кон', '~\w+~', captureOffset: true);
/* [
	0 => [['лт', 2]],
	1 => [['к', 6]],
] */

Strings::matchAll('жълт кон', '~\w+~', captureOffset: true, utf8: true);
/* [
	0 => [['жълт', 0]],
	1 => [['кон', 5]],
] */

Ако $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('жълт кон', '~\w+~', '--');
// 'ж--т --он'

Strings::replace('жълт кон', '~\w+~', '--', utf8: true);
// '-- --'

Ако $captureOffset е true, за всяко срещано съвпадение ще бъде предадена на callback-а и неговата позиция в низа (в байтове; ако е зададено $utf8, тогава в знаци). Това променя формата на предавания масив, където всеки елемент е двойка, съставена от съвпадащия низ и неговата позиция.

Strings::replace(
	'жълт кон',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// dumps [['лт', 2]] и [['к', 6]]

Strings::replace(
	'жълт кон',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// dumps [['жълт', 0]] и [['кон', 5]]

Ако $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