Funcții de șiruri de caractere
******************************

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


Instalare:

```shell
composer require nette/utils
```

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

```php
use Nette\Utils\Strings;
```


Litere Cazul literelor .[#toc-letter-case]
==========================================

Aceste funcții necesită extensia PHP `mbstring`.


lower(string $s): string .[method]
----------------------------------

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

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


upper(string $s): string .[method]
----------------------------------

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

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


firstUpper(string $s): string .[method]
---------------------------------------

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

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


firstLower(string $s): string .[method]
---------------------------------------

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

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


capitalize(string $s): string .[method]
---------------------------------------

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

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


Editarea unui șir de caractere .[#toc-editing-a-string]
=======================================================


normalize(string $s): string .[method]
--------------------------------------

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 .[method]
-----------------------------------------

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.

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


platformNewLines(string $s): string .[method]
---------------------------------------------

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.

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


webalize(string $s, ?string $charlist=null, bool $lower=true): string .[method]
-------------------------------------------------------------------------------

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ă.

```php
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.

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

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

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

.[caution]
Necesită extensia PHP `intl`.


trim(string $s, ?string $charlist=null): string .[method]
---------------------------------------------------------

Î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.

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


truncate(string $s, int $maxLen, string $append=`'…'`): string .[method]
------------------------------------------------------------------------

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.

```php
$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 .[method]
---------------------------------------------------------------------------------

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

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


padLeft(string $s, int $length, string $pad=`' '`): string .[method]
--------------------------------------------------------------------

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

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


padRight(string $s, int $length, string $pad=`' '`): string .[method]
---------------------------------------------------------------------

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

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


substring(string $s, int $start, ?int $length=null): string .[method]
---------------------------------------------------------------------

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.

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


reverse(string $s): string .[method]
------------------------------------

Inversează șirul UTF-8.

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


length(string $s): int .[method]
--------------------------------

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.

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


startsWith(string $haystack, string $needle): bool .[method deprecated]
-----------------------------------------------------------------------

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

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

.[note]
Utilizează codul nativ `str_starts_with()`:https://www.php.net/manual/en/function.str-starts-with.php.


endsWith(string $haystack, string $needle): bool .[method deprecated]
---------------------------------------------------------------------

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

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

.[note]
Folosește codul nativ `str_ends_with()`:https://www.php.net/manual/en/function.str-ends-with.php.


contains(string $haystack, string $needle): bool .[method deprecated]
---------------------------------------------------------------------

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

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

.[note]
Utilizează codul nativ `str_contains()`:https://www.php.net/manual/en/function.str-contains.php.


compare(string $left, string $right, ?int $length=null): bool .[method]
-----------------------------------------------------------------------

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.

```php
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 .[method]
-----------------------------------------

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

```php
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 .[method]
-----------------------------------------------------------------------

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.

```php
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 .[method]
----------------------------------------------------------------------

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.

```php
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 .[method]
---------------------------------------------------------------------

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.

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


Codificarea .[#toc-encoding]
============================


fixEncoding(string $s): string .[method]
----------------------------------------

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

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


checkEncoding(string $s): bool .[method deprecated]
---------------------------------------------------

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

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

.[note]
Utilizați [Nette\Utils\Validator::isUnicode() |validators#isUnicode].


toAscii(string $s): string .[method]
------------------------------------

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

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

.[caution]
Necesită extensia PHP `intl`.


chr(int $code): string .[method]
--------------------------------

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

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


ord(string $char): int .[method]
--------------------------------

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

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


Expresii regulate .[#toc-regular-expressions]
=============================================

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 .[method]
-------------------------------------------------------------------------------------------------------------------------------------------

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

```php
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:

```php
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ă.

```php
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.

```php
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 .[method]
--------------------------------------------------------------------------------------------------------------------------------------------------

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

```php
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:

```php
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`:

```php
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:

```php
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 .[method]
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

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.

```php
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:

```php
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:

```php
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`:

```php
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` ).

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 poziția acestuia:

```php
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.

```php
$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 .[method]
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

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

```php
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:

```php
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`.

```php
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.

```php
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:

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