Funzioni di stringa
*******************

.[perex]
[api:Nette\Utils\Strings] è una classe statica che contiene molte funzioni utili per lavorare con le stringhe codificate in UTF-8.


Installazione:

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

Tutti gli esempi presuppongono che sia definito il seguente alias di classe:

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


Lettera Caso .[#toc-letter-case]
================================

Queste funzioni richiedono l'estensione PHP `mbstring`.


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

Converte tutti i caratteri della stringa UTF-8 in minuscolo.

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


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

Converte tutti i caratteri di una stringa UTF-8 in maiuscole.

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


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

Converte il primo carattere di una stringa UTF-8 in maiuscolo e lascia invariati gli altri caratteri.

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


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

Converte il primo carattere di una stringa UTF-8 in minuscolo e lascia invariati gli altri caratteri.

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


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

Converte il primo carattere di ogni parola di una stringa UTF-8 in maiuscolo e gli altri in minuscolo.

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


Modifica di una stringa .[#toc-editing-a-string]
================================================


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

Rimuove i caratteri di controllo, normalizza le interruzioni di riga a `\n`, rimuove le righe vuote iniziali e finali, taglia gli spazi finali delle righe, normalizza UTF-8 alla forma normale di NFC.


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

Converte le interruzioni di riga in `\n` usato nei sistemi Unix. Le interruzioni di riga sono: `\n`, `\r`, `\r\n`, U+2028 separatore di riga, U+2029 separatore di paragrafo.

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


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

Converte le interruzioni di riga in caratteri specifici della piattaforma corrente, ad esempio `\r\n` su Windows e `\n` altrove. Le interruzioni di riga sono `\n`, `\r`, `\r\n`, U+2028 separatore di riga, U+2029 separatore di paragrafo.

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


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

Modifica la stringa UTF-8 nella forma usata nell'URL, cioè rimuove i diacritici e sostituisce tutti i caratteri tranne le lettere dell'alfabeto inglese e i numeri con un trattino.

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

Anche altri caratteri possono essere conservati, ma devono essere passati come secondo argomento.

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

Il terzo argomento può sopprimere la conversione della stringa in minuscolo.

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

.[caution]
Richiede l'estensione PHP `intl`.


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

Rimuove tutti gli spazi a sinistra e a destra (o i caratteri passati come secondo argomento) da una stringa codificata UTF-8.

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


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

Tronca una stringa UTF-8 alla lunghezza massima indicata, cercando di non dividere le parole intere. Solo se la stringa viene troncata, alla stringa viene aggiunta un'ellissi (o qualcos'altro impostato con il terzo argomento).

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

Rientra un testo multilinea da sinistra. Il secondo argomento stabilisce il numero di caratteri di rientro da utilizzare, mentre il rientro stesso è il terzo argomento (*tab* per impostazione predefinita).

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


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

Imbottisce una stringa UTF-8 alla lunghezza data, anteponendo la stringa `$pad` all'inizio.

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


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

Imbottisce una stringa UTF-8 alla lunghezza data aggiungendo la stringa `$pad` alla fine.

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


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

Restituisce una parte della stringa UTF-8 specificata dalla posizione iniziale `$start` e dalla lunghezza `$length`. Se `$start` è negativo, la stringa restituita inizierà a partire dal `$start`'esimo carattere dalla fine della stringa.

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

Inverte la stringa UTF-8.

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


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

Restituisce il numero di caratteri (non di byte) nella stringa UTF-8.

Si tratta del numero di punti di codice Unicode, che può differire dal numero di grafemi.

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


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

Controlla se la stringa `$haystack` inizia con `$needle`.

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

.[note]
Utilizzare il nativo `str_starts_with()`:https://www.php.net/manual/en/function.str-starts-with.php.


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

Controlla se la stringa `$haystack` termina con `$needle`.

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

.[note]
Utilizzare `str_ends_with()` nativo:https://www.php.net/manual/en/function.str-ends-with.php.


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

Controlla se la stringa `$haystack` contiene `$needle`.

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

.[note]
Utilizzare `str_contains()` nativo :https://www.php.net/manual/en/function.str-contains.php.


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

Confronta due stringhe UTF-8 o le loro parti, senza tenere conto del caso dei caratteri. Se `$length` è nullo, vengono confrontate le stringhe intere, se è negativo, viene confrontato il numero corrispondente di caratteri dalla fine delle stringhe, altrimenti viene confrontato il numero appropriato di caratteri dall'inizio.

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

Trova il prefisso comune delle stringhe o restituisce una stringa vuota se il prefisso non è stato trovato.

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

Restituisce una parte di `$haystack` prima dell'occorrenza di `$nth` in `$needle` o restituisce `null` se l'ago non è stato trovato. Il valore negativo indica la ricerca dalla fine.

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

Restituisce una parte di `$haystack` dopo l'occorrenza di `$nth` in `$needle` o restituisce `null` se `$needle` non è stato trovato. Il valore negativo di `$nth` indica la ricerca dalla fine.

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

Restituisce la posizione in caratteri di `$nth` in cui si trova `$needle` in `$haystack` o `null` se `$needle` non è stato trovato. Il valore negativo di `$nth` indica la ricerca dalla fine.

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


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


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

Rimuove tutti i caratteri UTF-8 non validi da una stringa.

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


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

Verifica se la stringa è valida nella codifica UTF-8.

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

.[note]
Utilizzare [Nette\Utils\Validator::isUnicode() |validators#isUnicode].


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

Converte le stringhe UTF-8 in ASCII, cioè rimuove i diacritici ecc.

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

.[caution]
Richiede l'estensione PHP `intl`.


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

Restituisce un carattere specifico in UTF-8 dal punto di codice (numero nell'intervallo 0x0000..D7FF o 0xE000..10FFFF).

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


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

Restituisce un punto di codice di un carattere specifico in UTF-8 (numero nell'intervallo 0x0000..D7FF o 0xE000..10FFFF).

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


Espressioni regolari .[#toc-regular-expressions]
================================================

La classe Strings fornisce funzioni per lavorare con le espressioni regolari. A differenza delle funzioni native di PHP, hanno un'API più comprensibile, un migliore supporto Unicode e, soprattutto, un rilevamento degli errori. Qualsiasi errore di compilazione o di elaborazione delle espressioni lancerà un'eccezione `Nette\RegexpException`.


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

Divide la stringa in array in base all'espressione regolare. Anche le espressioni tra parentesi vengono catturate e restituite.

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

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

Se `$skipEmpty` è `true`, verranno restituiti solo gli elementi non vuoti:

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

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

Se viene specificato `$limit`, verranno restituite solo le sottostringhe fino al limite e il resto della stringa verrà inserito nell'ultimo elemento. Un limite di -1 o 0 significa nessun limite.

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Questo è simile alla specificazione del modificatore `u`.

Se `$captureOffset` è `true`, per ogni corrispondenza che si verifica, viene restituita anche la sua posizione nella stringa (in byte; in caratteri se `$utf8` è impostato). Questo cambia il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa abbinata e dalla sua posizione.

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

Cerca nella stringa la parte corrispondente all'espressione regolare e restituisce un array con l'espressione trovata e le singole sottoespressioni, oppure `null`.

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

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

Se `$unmatchedAsNull` è `true`, le sottoespressioni non corrispondenti vengono restituite come null; altrimenti vengono restituite come una stringa vuota o non vengono restituite:

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

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Ciò è simile alla specificazione del modificatore `u`:

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

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

Il parametro `$offset` può essere usato per specificare la posizione da cui iniziare la ricerca (in byte; in caratteri se è impostato `$utf8` ).

Se `$captureOffset` è `true`, per ogni corrispondenza che si verifica, viene restituita anche la sua posizione nella stringa (in byte; in caratteri se `$utf8` è impostato). Questo cambia il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa corrispondente e dal suo offset:

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

Cerca nella stringa tutte le occorrenze che corrispondono all'espressione regolare e restituisce un array di array contenenti l'espressione trovata e ogni sottoespressione.

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

Se `$patternOrder` è `true`, la struttura dei risultati cambia in modo che il primo elemento è un array di corrispondenze complete del modello, il secondo è un array di stringhe corrispondenti alla prima sottoespressione tra parentesi e così via:

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

Se `$unmatchedAsNull` è `true`, i sottopattern senza corrispondenza vengono restituiti come null; altrimenti vengono restituiti come una stringa vuota o non vengono restituiti:

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Ciò è simile alla specificazione del modificatore `u`:

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

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

Il parametro `$offset` può essere usato per specificare la posizione da cui iniziare la ricerca (in byte; in caratteri se è impostato `$utf8` ).

Se `$captureOffset` è `true`, per ogni corrispondenza che si verifica, viene restituita anche la sua posizione nella stringa (in byte; in caratteri se `$utf8` è impostato). Questo cambia il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa corrispondente e dalla sua posizione:

```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]],
] */
```

Se `$lazy` è `true`, la funzione restituisce un `Generator` invece di un array, con notevoli vantaggi in termini di prestazioni quando si lavora con stringhe di grandi dimensioni. Il generatore consente di trovare le corrispondenze in modo incrementale, anziché elaborare l'intera stringa in una sola volta. Ciò consente di gestire in modo efficiente testi di input molto grandi. Inoltre, è possibile interrompere l'elaborazione in qualsiasi momento se si trova la corrispondenza desiderata, risparmiando tempo di calcolo.

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

Sostituisce tutte le occorrenze che corrispondono all'espressione regolare. Il parametro `$replacement` è una maschera di stringa sostitutiva o un richiamo.

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

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

La funzione consente anche sostituzioni multiple passando un array della forma `pattern => replacement` nel secondo parametro:

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

Il parametro `$limit` limita il numero di sostituzioni. Limite -1 significa nessun limite.

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Ciò è simile alla specificazione del modificatore `u`.

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

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

Se `$captureOffset` è `true`, per ogni corrispondenza che si verifica, la sua posizione nella stringa (in byte; in caratteri se `$utf8` è impostato) viene passata anche al callback. Questo cambia la forma dell'array passato, dove ogni elemento è una coppia composta dalla stringa corrispondente e dalla sua posizione.

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

Se `$unmatchedAsNull` è `true`, i sottopattern non abbinati vengono passati alla callback come null; altrimenti vengono passati come una stringa vuota o non vengono passati:

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