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): array .[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]],
] */
```


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