Nette Documentation Preview

syntax 
Lavorare con le stringhe
************************

.[perex]
[api:Nette\Utils\Strings] è una classe statica con funzioni utili per lavorare con stringhe, principalmente in codifica UTF-8.


Installazione:

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

Tutti gli esempi presuppongono la creazione di un alias:

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


Cambio di maiuscole/minuscole
=============================

Queste funzioni richiedono l'estensione PHP `mbstring`.


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

Converte una stringa UTF-8 in minuscolo.

```php
Strings::lower('Dobrý den'); // 'dobrý den'
```


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

Converte una stringa UTF-8 in maiuscolo.

```php
Strings::upper('Dobrý den'); // 'DOBRÝ DEN'
```


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

Converte la prima lettera di una stringa UTF-8 in maiuscolo, le altre rimangono invariate.

```php
Strings::firstUpper('dobrý den'); // 'Dobrý den'
```


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

Converte la prima lettera di una stringa UTF-8 in minuscolo, le altre rimangono invariate.

```php
Strings::firstLower('Dobrý den'); // 'dobrý den'
```


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

Converte la prima lettera di ogni parola in una stringa UTF-8 in maiuscolo, le altre in minuscolo.

```php
Strings::capitalize('Dobrý den'); // 'Dobrý Den'
```


Modifica della stringa
======================


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

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


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

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

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


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

Converte le terminazioni di riga nei caratteri specifici della piattaforma corrente, ovvero `\r\n` su Windows e `\n` altrove. Le terminazioni di riga sono: `\n`, `\r`, `\r\n`, separatore di riga U+2028, separatore di paragrafo U+2029.

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


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

Modifica una stringa UTF-8 nella forma utilizzata negli URL, ovvero rimuove i diacritici e sostituisce tutti i caratteri, ad eccezione delle lettere dell'alfabeto inglese e dei numeri, con un trattino.

```php
Strings::webalize('náš produkt'); // 'nas-produkt'
```

Se devono essere conservati anche altri caratteri, possono essere specificati nel secondo parametro della funzione.

```php
Strings::webalize('10. obrázek_id', '._'); // '10.-obrazek_id'
```

Con il terzo parametro è possibile sopprimere la conversione in minuscolo.

```php
Strings::webalize('Dobrý den', null, false); // 'Dobry-den'
```

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


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

Rimuove gli spazi (o altri caratteri specificati dal secondo parametro) dall'inizio e dalla fine di una stringa UTF-8.

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


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

Tronca una stringa UTF-8 alla lunghezza massima specificata, cercando di mantenere le parole intere. Se la stringa viene accorciata, aggiunge tre puntini alla fine (modificabile con il terzo parametro).

```php
$text = 'Řekněte, jak se máte?';
Strings::truncate($text, 5);       // 'Řekn…'
Strings::truncate($text, 20);      // 'Řekněte, jak se…'
Strings::truncate($text, 30);      // 'Řekněte, jak se máte?'
Strings::truncate($text, 20, '~'); // 'Řekněte, jak se~'
```


indent(string $s, int $level=1, string $indentationChar=`"\t"`): string .[method]
---------------------------------------------------------------------------------

Indenta un testo multilinea da sinistra. Il numero di indentazioni è determinato dal secondo parametro, il carattere di indentazione dal terzo (il valore predefinito è il tabulatore).

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


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

Completa una stringa UTF-8 alla lunghezza specificata ripetendo la stringa `$pad` da sinistra.

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


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

Completa una stringa UTF-8 alla lunghezza specificata ripetendo la stringa `$pad` da destra.

```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 `$s` specificata dalla posizione iniziale `$start` e dalla lunghezza `$length`. Se `$start` è negativo, la stringa restituita inizierà dal carattere -`$start` dalla fine.

```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 una stringa UTF-8.

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


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

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

Questo è il numero di punti di codice Unicode, che può differire dal numero di grafemi.

```php
Strings::length('Nette');   // 5
Strings::length('červená'); // 7
```


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

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

```php
$haystack = 'Začíná';
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true
```

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


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

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

```php
$haystack = 'Končí';
$needle = 'čí';
Strings::endsWith($haystack, $needle); // true
```

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


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

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

```php
$haystack = 'Posluchárna';
$needle = 'sluch';
Strings::contains($haystack, $needle); // true
```

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


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

Confronto di due stringhe UTF-8 o delle loro parti senza distinzione tra maiuscole e minuscole. Se `$length` contiene null, vengono confrontate le stringhe intere, se è negativo, viene confrontato il numero corrispondente di caratteri dalla fine delle stringhe, altrimenti viene confrontato il numero corrispondente di caratteri dall'inizio.

```php
Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - corrispondenza dei primi 2 caratteri
Strings::compare('Nette', 'Latte', -2); // true - corrispondenza degli ultimi 2 caratteri
```


findPrefix(...$strings): string .[method]
-----------------------------------------

Trova l'inizio comune delle stringhe. Oppure restituisce una stringa vuota se non è stato trovato alcun prefisso comune.

```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 la parte della stringa `$haystack` prima della n-esima `$nth` occorrenza della stringa `$needle`. Oppure `null` se `$needle` non è stato trovato. Con un valore negativo di `$nth`, la ricerca avviene dalla fine della stringa.

```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 la parte della stringa `$haystack` dopo la n-esima `$nth` occorrenza della stringa `$needle`. Oppure `null` se `$needle` non è stato trovato. Con un valore negativo di `$nth`, la ricerca avviene dalla fine della stringa.

```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 della n-esima `$nth` occorrenza della stringa `$needle` nella stringa `$haystack`. Oppure `null` se `$needle` non è stato trovato. Con un valore negativo di `$nth`, la ricerca avviene dalla fine della stringa.

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


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

Rimuove dalla stringa i caratteri UTF-8 non validi.

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


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

Verifica se si tratta di una stringa UTF-8 valida.

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

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


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

Converte una stringa UTF-8 in ASCII, ovvero 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 e 0xE000..10FFFF).

```php
Strings::chr(0xA9); // '©' in codifica UTF-8
```


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

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

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


Espressioni regolari
====================

La classe Strings offre funzioni per lavorare con le espressioni regolari. A differenza delle funzioni PHP native, dispongono di un'API più comprensibile, un migliore supporto Unicode e, soprattutto, il rilevamento degli errori. Qualsiasi errore durante la compilazione o l'elaborazione dell'espressione lancia un'eccezione `Nette\RegexpException`.


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

Divide una stringa in un array secondo un'espressione regolare. Le espressioni tra parentesi verranno catturate e restituite anch'esse.

```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 nessuna restrizione.

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Simile a quando si specifica il modificatore `u`.

Se `$captureOffset` è `true`, per ogni corrispondenza trovata verrà restituita anche la sua posizione nella stringa (in byte; se è impostato `$utf8`, in caratteri). Ciò modifica il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa corrispondente 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 una 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`, i sottogruppi non catturati vengono restituiti come null; altrimenti vengono restituiti come stringa vuota o non restituiti:

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

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Simile a quando si specifica il modificatore `u`:

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

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

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

Se `$captureOffset` è `true`, per ogni corrispondenza trovata verrà restituita anche la sua posizione nella stringa (in byte; se è impostato `$utf8`, in caratteri). Ciò modifica 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 corrispondenti all'espressione regolare e restituisce un array di array con l'espressione trovata e le singole sottoespressioni.

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

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

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

Se `$unmatchedAsNull` è `true`, i sottogruppi non catturati vengono restituiti come null; altrimenti vengono restituiti come stringa vuota o non restituiti:

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Simile a quando si specifica il 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 utilizzato per specificare la posizione da cui iniziare la ricerca (in byte; se è impostato `$utf8`, in caratteri).

Se `$captureOffset` è `true`, per ogni corrispondenza trovata verrà restituita anche la sua posizione nella stringa (in byte; se è impostato `$utf8`, in caratteri). Ciò modifica 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, il che comporta significativi vantaggi in termini di prestazioni quando si lavora con stringhe di grandi dimensioni. Il generatore consente di cercare le corrispondenze gradualmente, invece dell'intera stringa contemporaneamente. Ciò consente di lavorare in modo efficiente anche con testi di input estremamente grandi. Inoltre, è possibile interrompere l'elaborazione in qualsiasi momento se si trova la corrispondenza cercata, risparmiando tempo di calcolo.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Trovato: $match[0]\n";
    // L'elaborazione può essere interrotta in qualsiasi momento
}
```


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 corrispondenti all'espressione regolare. `$replacement` è una maschera di stringa di sostituzione o un callback.

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

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

La funzione consente anche di eseguire più sostituzioni passando un array nel secondo parametro nella forma `pattern => replacement`:

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

Il parametro `$limit` limita il numero di sostituzioni eseguite. Un limite di -1 significa nessuna restrizione.

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode. Simile a quando si specifica il modificatore `u`.

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

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

Se `$captureOffset` è `true`, per ogni corrispondenza trovata verrà passata al callback anche la sua posizione nella stringa (in byte; se è impostato `$utf8`, in caratteri). Ciò modifica 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]] e [['k', 8]]

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// dumps [['žlutý', 0]] e [['kůň', 6]]
```

Se `$unmatchedAsNull` è `true`, i sottogruppi non catturati vengono passati al callback come null; altrimenti vengono passati come stringa vuota o non 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']
```

Lavorare con le stringhe

Nette\Utils\Strings è una classe statica con funzioni utili per lavorare con stringhe, principalmente in codifica UTF-8.

Installazione:

composer require nette/utils

Tutti gli esempi presuppongono la creazione di un alias:

use Nette\Utils\Strings;

Cambio di maiuscole/minuscole

Queste funzioni richiedono l'estensione PHP mbstring.

lower(string $s): string

Converte una stringa UTF-8 in minuscolo.

Strings::lower('Dobrý den'); // 'dobrý den'

upper(string $s): string

Converte una stringa UTF-8 in maiuscolo.

Strings::upper('Dobrý den'); // 'DOBRÝ DEN'

firstUpper(string $s): string

Converte la prima lettera di una stringa UTF-8 in maiuscolo, le altre rimangono invariate.

Strings::firstUpper('dobrý den'); // 'Dobrý den'

firstLower(string $s): string

Converte la prima lettera di una stringa UTF-8 in minuscolo, le altre rimangono invariate.

Strings::firstLower('Dobrý den'); // 'dobrý den'

capitalize(string $s): string

Converte la prima lettera di ogni parola in una stringa UTF-8 in maiuscolo, le altre in minuscolo.

Strings::capitalize('Dobrý den'); // 'Dobrý Den'

Modifica della stringa

normalize(string $s): string

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

unixNewLines(string $s): string

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

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

platformNewLines(string $s): string

Converte le terminazioni di riga nei caratteri specifici della piattaforma corrente, ovvero \r\n su Windows e \n altrove. Le terminazioni di riga sono: \n, \r, \r\n, separatore di riga U+2028, separatore di paragrafo U+2029.

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

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

Modifica una stringa UTF-8 nella forma utilizzata negli URL, ovvero rimuove i diacritici e sostituisce tutti i caratteri, ad eccezione delle lettere dell'alfabeto inglese e dei numeri, con un trattino.

Strings::webalize('náš produkt'); // 'nas-produkt'

Se devono essere conservati anche altri caratteri, possono essere specificati nel secondo parametro della funzione.

Strings::webalize('10. obrázek_id', '._'); // '10.-obrazek_id'

Con il terzo parametro è possibile sopprimere la conversione in minuscolo.

Strings::webalize('Dobrý den', null, false); // 'Dobry-den'

Richiede l'estensione PHP intl.

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

Rimuove gli spazi (o altri caratteri specificati dal secondo parametro) dall'inizio e dalla fine di una stringa UTF-8.

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

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

Tronca una stringa UTF-8 alla lunghezza massima specificata, cercando di mantenere le parole intere. Se la stringa viene accorciata, aggiunge tre puntini alla fine (modificabile con il terzo parametro).

$text = 'Řekněte, jak se máte?';
Strings::truncate($text, 5);       // 'Řekn…'
Strings::truncate($text, 20);      // 'Řekněte, jak se…'
Strings::truncate($text, 30);      // 'Řekněte, jak se máte?'
Strings::truncate($text, 20, '~'); // 'Řekněte, jak se~'

indent(string $s, int $level=1, string $indentationChar=`"\t"`): string

Indenta un testo multilinea da sinistra. Il numero di indentazioni è determinato dal secondo parametro, il carattere di indentazione dal terzo (il valore predefinito è il tabulatore).

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

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

Completa una stringa UTF-8 alla lunghezza specificata ripetendo la stringa $pad da sinistra.

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

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

Completa una stringa UTF-8 alla lunghezza specificata ripetendo la stringa $pad da destra.

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

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

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

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

reverse(string $s): string

Inverte una stringa UTF-8.

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

length(string $s): int

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

Questo è il numero di punti di codice Unicode, che può differire dal numero di grafemi.

Strings::length('Nette');   // 5
Strings::length('červená'); // 7

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

Verifica se la stringa $haystack inizia con la stringa $needle.

$haystack = 'Začíná';
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true

Utilizzare la funzione nativa str_starts_with().

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

Verifica se la stringa $haystack termina con la stringa $needle.

$haystack = 'Končí';
$needle = 'čí';
Strings::endsWith($haystack, $needle); // true

Utilizzare la funzione nativa str_ends_with().

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

Verifica se la stringa $haystack contiene $needle.

$haystack = 'Posluchárna';
$needle = 'sluch';
Strings::contains($haystack, $needle); // true

Utilizzare la funzione nativa str_contains().

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

Confronto di due stringhe UTF-8 o delle loro parti senza distinzione tra maiuscole e minuscole. Se $length contiene null, vengono confrontate le stringhe intere, se è negativo, viene confrontato il numero corrispondente di caratteri dalla fine delle stringhe, altrimenti viene confrontato il numero corrispondente di caratteri dall'inizio.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - corrispondenza dei primi 2 caratteri
Strings::compare('Nette', 'Latte', -2); // true - corrispondenza degli ultimi 2 caratteri

findPrefix(…$strings): string

Trova l'inizio comune delle stringhe. Oppure restituisce una stringa vuota se non è stato trovato alcun prefisso comune.

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

Restituisce la parte della stringa $haystack prima della n-esima $nth occorrenza della stringa $needle. Oppure null se $needle non è stato trovato. Con un valore negativo di $nth, la ricerca avviene dalla fine della stringa.

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

Restituisce la parte della stringa $haystack dopo la n-esima $nth occorrenza della stringa $needle. Oppure null se $needle non è stato trovato. Con un valore negativo di $nth, la ricerca avviene dalla fine della stringa.

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

Restituisce la posizione in caratteri della n-esima $nth occorrenza della stringa $needle nella stringa $haystack. Oppure null se $needle non è stato trovato. Con un valore negativo di $nth, la ricerca avviene dalla fine della stringa.

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

Codifica

fixEncoding(string $s): string

Rimuove dalla stringa i caratteri UTF-8 non validi.

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

checkEncoding(string $s): bool

Verifica se si tratta di una stringa UTF-8 valida.

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

Utilizzare Nette\Utils\Validator::isUnicode().

toAscii(string $s): string

Converte una stringa UTF-8 in ASCII, ovvero rimuove i diacritici, ecc.

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

Richiede l'estensione PHP intl.

chr(int $code): string

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

Strings::chr(0xA9); // '©' in codifica UTF-8

ord(string $char): int

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

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

Espressioni regolari

La classe Strings offre funzioni per lavorare con le espressioni regolari. A differenza delle funzioni PHP native, dispongono di un'API più comprensibile, un migliore supporto Unicode e, soprattutto, il rilevamento degli errori. Qualsiasi errore durante la compilazione o l'elaborazione dell'espressione lancia un'eccezione Nette\RegexpException.

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

Divide una stringa in un array secondo un'espressione regolare. Le espressioni tra parentesi verranno catturate e restituite anch'esse.

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

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

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

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 nessuna restrizione.

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

Se $utf8 è true, la valutazione passa alla modalità Unicode. Simile a quando si specifica il modificatore u.

Se $captureOffset è true, per ogni corrispondenza trovata verrà restituita anche la sua posizione nella stringa (in byte; se è impostato $utf8, in caratteri). Ciò modifica il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa corrispondente e dalla sua posizione.

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

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

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

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

Se $unmatchedAsNull è true, i sottogruppi non catturati vengono restituiti come null; altrimenti vengono restituiti come stringa vuota o non restituiti:

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

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

Se $utf8 è true, la valutazione passa alla modalità Unicode. Simile a quando si specifica il modificatore u:

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

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

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

Se $captureOffset è true, per ogni corrispondenza trovata verrà restituita anche la sua posizione nella stringa (in byte; se è impostato $utf8, in caratteri). Ciò modifica il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa corrispondente e dal suo offset:

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

Cerca nella stringa tutte le occorrenze corrispondenti all'espressione regolare e restituisce un array di array con l'espressione trovata e le singole sottoespressioni.

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

Se $patternOrder è true, la struttura dei risultati cambia in modo che il primo elemento sia un array di corrispondenze complete del pattern, il secondo sia un array di stringhe corrispondenti al primo sottogruppo tra parentesi, e così via:

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

Se $unmatchedAsNull è true, i sottogruppi non catturati vengono restituiti come null; altrimenti vengono restituiti come stringa vuota o non restituiti:

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

Se $utf8 è true, la valutazione passa alla modalità Unicode. Simile a quando si specifica il modificatore u:

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 utilizzato per specificare la posizione da cui iniziare la ricerca (in byte; se è impostato $utf8, in caratteri).

Se $captureOffset è true, per ogni corrispondenza trovata verrà restituita anche la sua posizione nella stringa (in byte; se è impostato $utf8, in caratteri). Ciò modifica il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa corrispondente e dalla sua posizione:

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, il che comporta significativi vantaggi in termini di prestazioni quando si lavora con stringhe di grandi dimensioni. Il generatore consente di cercare le corrispondenze gradualmente, invece dell'intera stringa contemporaneamente. Ciò consente di lavorare in modo efficiente anche con testi di input estremamente grandi. Inoltre, è possibile interrompere l'elaborazione in qualsiasi momento se si trova la corrispondenza cercata, risparmiando tempo di calcolo.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Trovato: $match[0]\n";
    // L'elaborazione può essere interrotta in qualsiasi momento
}

replace(string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string

Sostituisce tutte le occorrenze corrispondenti all'espressione regolare. $replacement è una maschera di stringa di sostituzione o un callback.

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

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

La funzione consente anche di eseguire più sostituzioni passando un array nel secondo parametro nella forma pattern => replacement:

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

Il parametro $limit limita il numero di sostituzioni eseguite. Un limite di –1 significa nessuna restrizione.

Se $utf8 è true, la valutazione passa alla modalità Unicode. Simile a quando si specifica il modificatore u.

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

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

Se $captureOffset è true, per ogni corrispondenza trovata verrà passata al callback anche la sua posizione nella stringa (in byte; se è impostato $utf8, in caratteri). Ciò modifica la forma dell'array passato, dove ogni elemento è una coppia composta dalla stringa corrispondente e dalla sua posizione.

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// dumps [['lut', 2]] e [['k', 8]]

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// dumps [['žlutý', 0]] e [['kůň', 6]]

Se $unmatchedAsNull è true, i sottogruppi non catturati vengono passati al callback come null; altrimenti vengono passati come stringa vuota o non passati:

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