Funcții de șiruri de caractere

Nette\Utils\Strings este o clasă statică, care conține multe funcții utile pentru lucrul cu șiruri de caractere codificate UTF-8.

Instalare:

composer require nette/utils

Toate exemplele presupun că este definit următorul alias de clasă:

use Nette\Utils\Strings;

Litere Cazul literelor

Aceste funcții necesită extensia PHP mbstring.

lower (string $s): string

Convertește toate caracterele din șirul UTF-8 în minuscule.

Strings::lower('Hello world'); // 'hello world'

upper (string $s): string

Convertește toate caracterele unui șir UTF-8 în majuscule.

Strings::upper('Hello world'); // 'HELLO WORLD'

firstUpper (string $s): string

Convertește primul caracter al unui șir UTF-8 în majuscule și lasă celelalte caractere neschimbate.

Strings::firstUpper('hello world'); // 'Hello world'

firstLower (string $s): string

Convertește primul caracter al unui șir UTF-8 în minuscule și lasă celelalte caractere neschimbate.

Strings::firstLower('Hello world'); // 'hello world'

capitalize (string $s): string

Convertește primul caracter al fiecărui cuvânt dintr-un șir UTF-8 în majuscule și celelalte caractere în minuscule.

Strings::capitalize('Hello world'); // 'Hello World'

Editarea unui șir de caractere

normalize (string $s): string

Elimină caracterele de control, normalizează pauzele de linie la \n, elimină liniile goale de început și de sfârșit de linie, taie spațiile de sfârșit de linie, normalizează UTF-8 la forma normală a NFC.

unixNewLines (string $s): string

Convertește întreruperile de linie în \n utilizate pe sistemele Unix. Pauzele de linie sunt: \n, \r, \r\n, U+2028 separator de linie, U+2029 separator de paragraf.

$unixLikeLines = Strings::unixNewLines($string);

platformNewLines (string $s): string

Convertește întreruperile de linie în caractere specifice platformei curente, adică \r\n pe Windows și \n în altă parte. Întreruperile de linie sunt \n, \r, \r\n, U+2028 separator de linie, U+2029 separator de paragraf.

$platformLines = Strings::platformNewLines($string);

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

Modifică șirul UTF-8 în forma utilizată în URL, adică elimină diacriticele și înlocuiește toate caracterele, cu excepția literelor din alfabetul englez și a numerelor, cu o cratimă.

Strings::webalize('žluťoučký kůň'); // 'zlutoucky-kun'

Pot fi păstrate și alte caractere, dar acestea trebuie să fie trecute ca al doilea argument.

Strings::webalize('10. image_id', '._'); // '10.-image_id'

Cel de-al treilea argument poate suprima convertirea șirului în minuscule.

Strings::webalize('Hello world', null, false); // 'Hello-world'

Necesită extensia PHP intl.

trim (string $s, ?string $charlist=null): string

Îndepărtează toate spațiile din stânga și din dreapta (sau caracterele trecute ca al doilea argument) dintr-un șir de caractere codificat UTF-8.

Strings::trim('  Hello  '); // 'Hello'

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

Trunchiază un șir de caractere UTF-8 la o lungime maximă dată, încercând în același timp să nu despartă cuvinte întregi. Numai dacă șirul este trunchiat, o elipsă (sau altceva stabilit cu al treilea argument) este adăugată la șir.

$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 $indentationChar=`"\t"`): string

Indentează un text multiliniar din stânga. Al doilea argument stabilește câte caractere de indentare trebuie folosite, în timp ce indentarea însăși este al treilea argument (tab în mod implicit).

Strings::indent('Nette');         // "\tNette"
Strings::indent('Nette', 2, '+'); // '++Nette'

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

Adună un șir UTF-8 la o lungime dată prin adăugarea la început a șirului $pad.

Strings::padLeft('Nette', 6);        // ' Nette'
Strings::padLeft('Nette', 8, '+*');  // '+*+Nette'

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

Adaugă un șir UTF-8 la o lungime dată prin adăugarea la sfârșit a șirului $pad.

Strings::padRight('Nette', 6);       // 'Nette '
Strings::padRight('Nette', 8, '+*'); // 'Nette+*+'

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

Returnează o parte din șirul UTF-8 specificat prin poziția de pornire $start și lungimea $length. Dacă $start este negativ, șirul returnat va începe la al $start-lea caracter de la sfârșitul șirului.

Strings::substring('Nette Framework', 0, 5); // 'Nette'
Strings::substring('Nette Framework', 6);    // 'Framework'
Strings::substring('Nette Framework', -4);   // 'work'

reverse (string $s): string

Inversează șirul UTF-8.

Strings::reverse('Nette'); // 'etteN'

length (string $s): int

Returnează numărul de caractere (nu de octeți) din șirul UTF-8.

Acesta este numărul de puncte de cod Unicode, care poate fi diferit de numărul de grafeme.

Strings::length('Nette'); // 5
Strings::length('red');   // 3

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

Verifică dacă șirul $haystack începe cu $needle.

$haystack = 'Begins';
$needle = 'Be';
Strings::startsWith($haystack, $needle); // true

Utilizează codul nativ str_starts_with().

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

Verifică dacă șirul $haystack se termină cu $needle.

$haystack = 'Ends';
$needle = 'ds';
Strings::endsWith($haystack, $needle); // true

Folosește codul nativ str_ends_with().

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

Verifică dacă șirul $haystack conține $needle.

$haystack = 'Contains';
$needle = 'tai';
Strings::contains($haystack, $needle); // true

Utilizează codul nativ str_contains().

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

Compară două șiruri UTF-8 sau părți ale acestora, fără a lua în considerare cazul caracterelor. Dacă $length este nul, se compară șiruri întregi, dacă este negativ, se compară numărul corespunzător de caractere de la sfârșitul șirurilor, altfel se compară numărul corespunzător de caractere de la început.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - two first characters match
Strings::compare('Nette', 'Latte', -2); // true - two last characters match

findPrefix (…$strings): string

Găsește prefixul comun al șirurilor de caractere sau returnează un șir gol dacă prefixul nu a fost găsit.

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

Returnează o parte din $haystack înainte de $nth apariția lui $needle sau returnează null dacă acul nu a fost găsit. Valoarea negativă înseamnă că se caută de la sfârșit.

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

Returnează o parte din $haystack după ce $nth apare în $needle sau returnează null dacă $needle nu a fost găsit. Valoarea negativă a $nth înseamnă că se caută de la sfârșit.

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

Returnează poziția în caractere a $nth apariției $needle în $haystack sau null dacă $needle nu a fost găsit. Valoarea negativă a $nth înseamnă că se caută de la sfârșit.

Strings::indexOf('abc abc abc', 'abc', 2);  // 4
Strings::indexOf('abc abc abc', 'abc', -1); // 8
Strings::indexOf('abc abc abc', 'd');       // null

Codificarea

fixEncoding (string $s): string

Îndepărtează toate caracterele UTF-8 nevalabile dintr-un șir de caractere.

$correctStrings = Strings::fixEncoding($string);

checkEncoding (string $s): bool

Verifică dacă șirul este valid în codificarea UTF-8.

$isUtf8 = Strings::checkEncoding($string);

Utilizați Nette\Utils\Validator::isUnicode().

toAscii (string $s): string

Convertește șirul UTF-8 în ASCII, adică elimină diacriticele etc.

Strings::toAscii('žluťoučký kůň'); // 'zlutoucky kun'

Necesită extensia PHP intl.

chr (int $code): string

Returnează un anumit caracter în UTF-8 din punctul de cod (număr în intervalul 0×0000..D7FF sau 0xE000..10FFFF).

Strings::chr(0xA9); // '©'

ord (string $char): int

Returnează un punct de cod al unui anumit caracter în UTF-8 (număr în intervalul 0×0000..D7FF sau 0xE000..10FFFF).

Strings::ord('©'); // 0xA9

Expresii regulate

Clasa Strings oferă funcții pentru lucrul cu expresiile regulate. Spre deosebire de funcțiile PHP native, acestea au o API mai ușor de înțeles, un suport Unicode mai bun și, cel mai important, detectarea erorilor. Orice eroare de compilare sau de procesare a expresiilor va arunca o excepție Nette\RegexpException.

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

Împarte șirul de caractere în matrice în conformitate cu expresia regulată. Expresiile din paranteze vor fi, de asemenea, capturate și returnate.

Strings::split('hello, world', '~,\s*~');
// ['hello', 'world']

Strings::split('hello, world', '~(,)\s*~');
// ['hello', ',', 'world']``

Dacă $skipEmpty este true, vor fi returnate numai elementele care nu sunt goale:

Strings::split('hello, world, ', '~,\s*~');
// ['hello', 'world', '']

Strings::split('hello, world, ', '~,\s*~', skipEmpty: true);
// ['hello', 'world']

Dacă este specificat $limit, vor fi returnate numai subșirurile până la limită, iar restul șirului va fi plasat în ultimul element. O limită de –1 sau 0 înseamnă că nu există limită.

Strings::split('hello, world, third', '~,\s*~', limit: 2);
// ['hello', 'world, third']

Dacă $utf8 este true, evaluarea trece la modul Unicode. Acest lucru este similar cu specificarea modificatorului u.

Dacă $captureOffset este true, pentru fiecare potrivire care apare, se va returna și poziția acesteia în șir (în octeți; în caractere dacă este setat $utf8 ). Acest lucru schimbă valoarea de returnare într-o matrice în care fiecare element este o pereche formată din șirul de caractere care corespunde și poziția acestuia.

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

Caută în șirul de caractere partea care corespunde expresiei regulate și returnează un tablou cu expresia găsită și subexpresiile individuale sau null.

Strings::match('hello!', '~\w+(!+)~');
// ['hello!', '!']

Strings::match('hello!', '~X~');
// null

Dacă $unmatchedAsNull este true, submodelele nepotrivite sunt returnate ca fiind nule; în caz contrar, acestea sunt returnate ca un șir gol sau nu sunt returnate:

Strings::match('hello', '~\w+(!+)?~');
// ['hello']

Strings::match('hello', '~\w+(!+)?~', unmatchedAsNull: true);
// ['hello', null]

În cazul în care $utf8 este true, evaluarea trece la modul Unicode. Acest lucru este similar cu specificarea modificatorului u:

Strings::match('žlutý kůň', '~\w+~');
// ['lut']

Strings::match('žlutý kůň', '~\w+~', utf8: true);
// ['žlutý']

Parametrul $offset poate fi utilizat pentru a specifica poziția de la care se începe căutarea (în octeți; în caractere dacă este setat $utf8 ).

Dacă $captureOffset este true, pentru fiecare potrivire care apare, se va returna și poziția acesteia în șirul de caractere (în octeți; în caractere, dacă este setat $utf8 ). Astfel, valoarea returnată se transformă într-o matrice în care fiecare element este o pereche formată din șirul de caractere care corespunde și decalajul acestuia:

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

Caută în șirul de caractere toate ocurențele care corespund expresiei regulate și returnează o matrice de matrici care conține expresia găsită și fiecare subexpresie.

Strings::matchAll('hello, world!!', '~\w+(!+)?~');
/* [
	0 => ['hello'],
	1 => ['world!!', '!!'],
] */

Dacă $patternOrder este true, structura rezultatelor se modifică astfel încât primul element este un tablou de corespondențe complete ale modelului, al doilea este un tablou de șiruri de caractere care corespund primului submodel între paranteze, și așa mai departe:

Strings::matchAll('hello, world!!', '~\w+(!+)?~', patternOrder: true);
/* [
	0 => ['hello', 'world!!'],
	1 => ['', '!!'],
] */

În cazul în care $unmatchedAsNull este true, submodelele nepotrivite sunt returnate ca fiind nule; în caz contrar, acestea sunt returnate ca un șir gol sau nu sunt returnate:

Strings::matchAll('hello, world!!', '~\w+(!+)?~', unmatchedAsNull: true);
/* [
	0 => ['hello', null],
	1 => ['world!!', '!!'],
] */

În cazul în care $utf8 este true, evaluarea trece la modul Unicode. Acest lucru este similar cu specificarea modificatorului u:

Strings::matchAll('žlutý kůň', '~\w+~');
/* [
	0 => ['lut'],
	1 => ['k'],
] */

Strings::matchAll('žlutý kůň', '~\w+~', utf8: true);
/* [
	0 => ['žlutý'],
	1 => ['kůň'],
] */

Parametrul $offset poate fi utilizat pentru a specifica poziția de la care se începe căutarea (în octeți; în caractere dacă este setat $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]],
] */

Dacă $lazy este true, funcția returnează un Generator în loc de un array, ceea ce oferă beneficii semnificative de performanță atunci când se lucrează cu șiruri mari. Generatorul permite găsirea incrementală a potrivirilor, în loc să proceseze întregul șir odată. Acest lucru permite gestionarea eficientă a textelor de intrare extrem de mari. În plus, puteți întrerupe procesarea în orice moment dacă găsiți potrivirea dorită, economisind astfel timp de calcul.

$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

Înlocuiește toate aparițiile care corespund expresiei regulate. $replacement este fie o mască de șir de caractere de înlocuire, fie un callback.

Strings::replace('hello, world!', '~\w+~', '--');
// '--, --!'

Strings::replace('hello, world!', '~\w+~', fn($m) => strrev($m[0]));
// 'olleh, dlrow!'

Funcția permite, de asemenea, înlocuiri multiple prin trecerea unui array de forma pattern => replacement în al doilea parametru:

Strings::replace('hello, world!', [
	'~\w+~' => '--',
	'~,\s+~' => ' ',
]);
// '-- --!'

Parametrul $limit limitează numărul de înlocuiri. Limit –1 înseamnă că nu există limită.

Dacă $utf8 este true, evaluarea trece la modul Unicode. Acest lucru este similar cu specificarea modificatorului u.

Strings::replace('žlutý kůň', '~\w+~', '--');
// 'ž--ý --ůň'

Strings::replace('žlutý kůň', '~\w+~', '--', utf8: true);
// '-- --'

Dacă $captureOffset este true, pentru fiecare potrivire care apare, poziția sa în șir (în octeți; în caractere, dacă este setat $utf8 ) este, de asemenea, transmisă către callback. Acest lucru modifică forma matricei transmise, în care fiecare element este o pereche formată din șirul de caractere care corespunde și poziția acestuia.

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

În cazul în care $unmatchedAsNull este true, submodelele nepotrivite sunt transmise la callback ca fiind nule; în caz contrar, acestea sunt transmise ca șir gol sau nu sunt transmise:

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

Funcții de șiruri de caractere

Litere Cazul literelor

lower (string $s): string

upper (string $s): string

firstUpper (string $s): string

firstLower (string $s): string

capitalize (string $s): string

Editarea unui șir de caractere

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

Codificarea

fixEncoding (string $s): string

checkEncoding (string $s): bool

toAscii (string $s): string

chr (int $code): string

ord (string $char): int

Expresii regulate

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