Nette Documentation Preview

syntax 
Funzioni per le stringhe
************************

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


Installazione:

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

Tutti gli esempi presuppongono che sia definito questo alias di classe:

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


Maiuscole e minuscole
=====================

Queste funzioni richiedono l'estensione PHP `mbstring`.


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

Converte una stringa UTF-8 in minuscolo.

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


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

Converte una stringa UTF-8 in maiuscolo.

```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 in maiuscolo il primo carattere di ogni parola di una stringa UTF-8 e in minuscolo gli altri.

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


Modificare una stringa
======================


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

Rimuove i caratteri di controllo, normalizza i fine riga in `\n`, elimina le righe vuote iniziali e finali, elimina gli spazi finali delle righe e normalizza l'UTF-8 nella forma normale NFC.


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

Converte i fine riga in `\n`, come si usa nei sistemi Unix. I fine riga sono: `\n`, `\r`, `\r\n`, il separatore di riga U+2028, il separatore di paragrafo U+2029.

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


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

Converte i fine riga nei caratteri specifici della piattaforma corrente, cioè `\r\n` su Windows e `\n` altrove. I fine riga sono: `\n`, `\r`, `\r\n`, il separatore di riga U+2028, il separatore di paragrafo U+2029.

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


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

Trasforma una stringa UTF-8 nella forma usata negli URL, cioè rimuove i segni diacritici e sostituisce con trattini tutti i caratteri tranne le lettere dell'alfabeto inglese e le cifre.

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

Se altri caratteri devono essere conservati, si possono indicare nel secondo parametro.

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

Il terzo parametro può disattivare la conversione in minuscolo.

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

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


trim(string $s, string $charlist=self::TrimCharacters): string .[method]
------------------------------------------------------------------------

Rimuove gli spazi bianchi (o altri caratteri indicati dal secondo parametro) all'inizio e alla fine di una stringa UTF-8.

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


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

Accorcia una stringa UTF-8 alla lunghezza massima indicata, cercando di preservare le parole intere. Se la stringa viene accorciata, alla fine vengono aggiunti i puntini di sospensione (modificabili con il terzo parametro).

```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 $chars=`"\t"`): string .[method]
-----------------------------------------------------------------------

Indenta da sinistra un testo su più righe. Il secondo parametro indica il numero di caratteri di indentazione, il terzo il carattere (o i caratteri) da usare per indentare (di norma la tabulazione).

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


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

Riempie una stringa UTF-8 fino alla lunghezza indicata anteponendo da sinistra la stringa `$pad`.

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


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

Riempie una stringa UTF-8 fino alla lunghezza indicata aggiungendo da destra la stringa `$pad`.

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


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

Restituisce la porzione della stringa UTF-8 `$s` indicata dalla posizione iniziale `$start` e dalla lunghezza `$length`. Se `$start` è negativo, la stringa restituita inizierà dal `$start`-esimo carattere a partire 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) di una stringa UTF-8.

È il numero di code point 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]
-----------------------------------------------------------------------

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

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

.[note]
Usate 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]
---------------------------------------------------------------------

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

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

.[note]
Usate 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]
---------------------------------------------------------------------

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

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

.[note]
Usate 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]
-----------------------------------------------------------------------

Confronta due stringhe UTF-8 o loro parti, senza distinguere maiuscole e minuscole. Se `$length` è null, confronta le stringhe intere. Se è negativo, confronta il numero corrispondente di caratteri a partire dalla fine delle stringhe. Altrimenti confronta il numero corrispondente di caratteri a partire dall'inizio.

```php
Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - i primi 2 caratteri coincidono
Strings::compare('Nette', 'Latte', -2); // true - gli ultimi 2 caratteri coincidono
```


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

Trova il prefisso comune delle stringhe. Restituisce una stringa vuota se non trova alcun prefisso comune.

```php
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 porzione della stringa `$haystack` che precede la `$nth` occorrenza della stringa `$needle`. Restituisce `null` se `$needle` non viene trovata. Se `$nth` è negativo, la ricerca parte 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 porzione della stringa `$haystack` che segue la `$nth` occorrenza della stringa `$needle`. Restituisce `null` se `$needle` non viene trovata. Se `$nth` è negativo, la ricerca parte 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 `$nth` occorrenza della stringa `$needle` nella stringa `$haystack`. Restituisce `null` se `$needle` non viene trovata. Se `$nth` è negativo, la ricerca parte 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 da una stringa i caratteri UTF-8 non validi.

```php
$correctString = Strings::fixEncoding($invalidString);
```


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

Controlla se una stringa è una stringa UTF-8 valida.

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

.[note]
Usate [Nette\Utils\Validators::isUnicode() |validators#isUnicode()].


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

Converte una stringa UTF-8 in ASCII, cioè rimuove i segni diacritici e simili.

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

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


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

Restituisce un determinato carattere in UTF-8 a partire da un code point (un numero nell'intervallo 0x0000..D7FF oppure 0xE000..10FFFF).

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


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

Restituisce il code point di un determinato carattere in UTF-8 (un numero nell'intervallo 0x0000..D7FF oppure 0xE000..10FFFF).

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


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

La classe `Strings` offre funzioni per lavorare con le espressioni regolari. A differenza delle funzioni native di PHP, hanno un'API più comprensibile, un supporto migliore per Unicode e, cosa essenziale, rilevano gli errori. Qualsiasi errore durante la compilazione o l'elaborazione dell'espressione solleva `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 usando un'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`, vengono restituiti solo gli elementi non vuoti:

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

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

Se è indicato `$limit`, vengono restituite solo le sottostringhe fino al limite e il resto della stringa viene messo 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, come con l'uso del modificatore `u`.

Se `$captureOffset` è `true`, viene restituita anche la posizione di ogni corrispondenza nella stringa (in byte; in caratteri se è impostato `$utf8`). Questo cambia il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa trovata 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]] // le posizioni sono in caratteri
```


match(string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $utf8=false): ?array .[method]
--------------------------------------------------------------------------------------------------------------------------------------------------

Cerca in una stringa una parte che corrisponda a un'espressione regolare e restituisce un array che contiene l'espressione trovata e le singole sottoespressioni, oppure `null` se non trova alcuna corrispondenza.

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

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

Se `$unmatchedAsNull` è `true`, i sottopattern senza corrispondenza vengono restituiti come `null`; altrimenti vengono restituiti come stringa vuota oppure omessi del tutto:

```php
Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (il gruppo facoltativo !+ non ha trovato corrispondenza)

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode, come con l'uso del modificatore `u`:

```php
Strings::match('žlutý kůň', '~\w+~'); // senza UTF-8
// ['lut'] (trova solo i caratteri di parola ASCII)

Strings::match('žlutý kůň', '~\w+~', utf8: true); // con UTF-8
// ['žlutý'] (trova i caratteri di parola Unicode)
```

Il parametro `$offset` può indicare la posizione iniziale della ricerca (in byte; in caratteri se è impostato `$utf8`).

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

```php
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // senza UTF-8
// [['lut', 2]] (solo corrispondenza ASCII, offset in byte)

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // con UTF-8
// [['žlutý!', 0], ['!', 5]] (corrispondenza Unicode, offset in caratteri)
```


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 in una stringa tutte le occorrenze che corrispondono a un'espressione regolare e restituisce un array di array contenenti 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: il primo elemento è un array delle corrispondenze complete del pattern, il secondo è un array delle stringhe che corrispondono al primo sottopattern 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 stringa vuota oppure omessi:

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode, come con l'uso 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ò indicare la posizione iniziale della ricerca (in byte; in caratteri se è impostato `$utf8`).

Se `$captureOffset` è `true`, viene restituita anche la posizione di ogni corrispondenza nella stringa (in byte; in caratteri se è impostato `$utf8`). Questo cambia la struttura del valore di ritorno, dove ogni elemento di corrispondenza è una coppia `[stringa_trovata, 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. Questo offre vantaggi notevoli in termini di prestazioni quando si lavora con stringhe grandi, perché le corrispondenze vengono trovate progressivamente invece di elaborare l'intera stringa in una volta. Permette così di gestire in modo efficiente input molto grandi. Inoltre potete interrompere l'elaborazione in qualsiasi momento, se trovate la corrispondenza cercata, risparmiando tempo di calcolo.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // l'elaborazione si può interrompere in qualsiasi momento, per esempio con break;
}
```


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 a un'espressione regolare. `$replacement` è una maschera della stringa di sostituzione oppure una funzione di callback.

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

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

La funzione permette anche più sostituzioni passando come secondo parametro un array nel formato `pattern => replacement`:

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

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

Se `$utf8` è `true`, la valutazione passa alla modalità Unicode, come con l'uso del modificatore `u`.

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

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

Se `$captureOffset` è `true`, alla callback viene passata anche la posizione di ogni corrispondenza nella stringa (in byte; in caratteri se è impostato `$utf8`). Questo cambia la struttura dell'array passato, dove ogni elemento è una coppia `[stringa_trovata, posizione]`.

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

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

Se `$unmatchedAsNull` è `true`, i sottopattern senza corrispondenza vengono passati alla callback come `null`; altrimenti vengono passati come stringa vuota oppure omessi:

```php
Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// stampa ['ac', 'a', '', 'c']

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// stampa ['ac', 'a', null, 'c']
```

Funzioni per le stringhe

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

Installazione:

composer require nette/utils

Tutti gli esempi presuppongono che sia definito questo alias di classe:

use Nette\Utils\Strings;

Maiuscole e minuscole

Queste funzioni richiedono l'estensione PHP mbstring.

lower(string $s): string

Converte una stringa UTF-8 in minuscolo.

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

upper(string $s): string

Converte una stringa UTF-8 in maiuscolo.

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

firstUpper(string $s): string

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

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

firstLower(string $s): string

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

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

capitalize(string $s): string

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

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

Modificare una stringa

normalize(string $s): string

Rimuove i caratteri di controllo, normalizza i fine riga in \n, elimina le righe vuote iniziali e finali, elimina gli spazi finali delle righe e normalizza l'UTF-8 nella forma normale NFC.

unixNewLines(string $s): string

Converte i fine riga in \n, come si usa nei sistemi Unix. I fine riga sono: \n, \r, \r\n, il separatore di riga U+2028, il separatore di paragrafo U+2029.

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

platformNewLines(string $s): string

Converte i fine riga nei caratteri specifici della piattaforma corrente, cioè \r\n su Windows e \n altrove. I fine riga sono: \n, \r, \r\n, il separatore di riga U+2028, il separatore di paragrafo U+2029.

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

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

Trasforma una stringa UTF-8 nella forma usata negli URL, cioè rimuove i segni diacritici e sostituisce con trattini tutti i caratteri tranne le lettere dell'alfabeto inglese e le cifre.

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

Se altri caratteri devono essere conservati, si possono indicare nel secondo parametro.

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

Il terzo parametro può disattivare la conversione in minuscolo.

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

Richiede l'estensione PHP intl.

trim(string $s, string $charlist=self::TrimCharacters): string

Rimuove gli spazi bianchi (o altri caratteri indicati dal secondo parametro) all'inizio e alla fine di una stringa UTF-8.

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

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

Accorcia una stringa UTF-8 alla lunghezza massima indicata, cercando di preservare le parole intere. Se la stringa viene accorciata, alla fine vengono aggiunti i puntini di sospensione (modificabili con il terzo parametro).

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

Indenta da sinistra un testo su più righe. Il secondo parametro indica il numero di caratteri di indentazione, il terzo il carattere (o i caratteri) da usare per indentare (di norma la tabulazione).

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

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

Riempie una stringa UTF-8 fino alla lunghezza indicata anteponendo da sinistra la stringa $pad.

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

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

Riempie una stringa UTF-8 fino alla lunghezza indicata aggiungendo da destra la stringa $pad.

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

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

Restituisce la porzione della stringa UTF-8 $s indicata dalla posizione iniziale $start e dalla lunghezza $length. Se $start è negativo, la stringa restituita inizierà dal $start-esimo carattere a partire 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) di una stringa UTF-8.

È il numero di code point Unicode, che può differire dal numero di grafemi.

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

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

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

$haystack = 'Starts';
$needle = 'St';
Strings::startsWith($haystack, $needle); // true

Usate la funzione nativa str_starts_with().

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

Controlla se la stringa $haystack finisce con la stringa $needle.

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

Usate la funzione nativa str_ends_with().

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

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

$haystack = 'Auditorium';
$needle = 'dit';
Strings::contains($haystack, $needle); // true

Usate la funzione nativa str_contains().

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

Confronta due stringhe UTF-8 o loro parti, senza distinguere maiuscole e minuscole. Se $length è null, confronta le stringhe intere. Se è negativo, confronta il numero corrispondente di caratteri a partire dalla fine delle stringhe. Altrimenti confronta il numero corrispondente di caratteri a partire dall'inizio.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - i primi 2 caratteri coincidono
Strings::compare('Nette', 'Latte', -2); // true - gli ultimi 2 caratteri coincidono

findPrefix(array $strings): string

Trova il prefisso comune delle stringhe. Restituisce una stringa vuota se non trova alcun prefisso comune.

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 porzione della stringa $haystack che precede la $nth occorrenza della stringa $needle. Restituisce null se $needle non viene trovata. Se $nth è negativo, la ricerca parte 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 porzione della stringa $haystack che segue la $nth occorrenza della stringa $needle. Restituisce null se $needle non viene trovata. Se $nth è negativo, la ricerca parte 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 $nth occorrenza della stringa $needle nella stringa $haystack. Restituisce null se $needle non viene trovata. Se $nth è negativo, la ricerca parte 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 da una stringa i caratteri UTF-8 non validi.

$correctString = Strings::fixEncoding($invalidString);

checkEncoding(string $s): bool

Controlla se una stringa è una stringa UTF-8 valida.

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

Usate Nette\Utils\Validators::isUnicode().

toAscii(string $s): string

Converte una stringa UTF-8 in ASCII, cioè rimuove i segni diacritici e simili.

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

Richiede l'estensione PHP intl.

chr(int $code): string

Restituisce un determinato carattere in UTF-8 a partire da un code point (un numero nell'intervallo 0×0000..D7FF oppure 0xE000..10FFFF).

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

ord(string $c): int

Restituisce il code point di un determinato carattere in UTF-8 (un numero nell'intervallo 0×0000..D7FF oppure 0xE000..10FFFF).

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

Espressioni regolari

La classe Strings offre funzioni per lavorare con le espressioni regolari. A differenza delle funzioni native di PHP, hanno un'API più comprensibile, un supporto migliore per Unicode e, cosa essenziale, rilevano gli errori. Qualsiasi errore durante la compilazione o l'elaborazione dell'espressione solleva 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 usando un'espressione regolare. Anche le espressioni tra parentesi vengono catturate e restituite.

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

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

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

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

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

Se è indicato $limit, vengono restituite solo le sottostringhe fino al limite e il resto della stringa viene messo nell'ultimo elemento. Un limite di –1 o 0 significa nessun limite.

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

Se $utf8 è true, la valutazione passa alla modalità Unicode, come con l'uso del modificatore u.

Se $captureOffset è true, viene restituita anche la posizione di ogni corrispondenza nella stringa (in byte; in caratteri se è impostato $utf8). Questo cambia il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa trovata 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]] // le posizioni sono in caratteri

match(string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $utf8=false): ?array

Cerca in una stringa una parte che corrisponda a un'espressione regolare e restituisce un array che contiene l'espressione trovata e le singole sottoespressioni, oppure null se non trova alcuna corrispondenza.

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

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

Se $unmatchedAsNull è true, i sottopattern senza corrispondenza vengono restituiti come null; altrimenti vengono restituiti come stringa vuota oppure omessi del tutto:

Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (il gruppo facoltativo !+ non ha trovato corrispondenza)

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

Se $utf8 è true, la valutazione passa alla modalità Unicode, come con l'uso del modificatore u:

Strings::match('žlutý kůň', '~\w+~'); // senza UTF-8
// ['lut'] (trova solo i caratteri di parola ASCII)

Strings::match('žlutý kůň', '~\w+~', utf8: true); // con UTF-8
// ['žlutý'] (trova i caratteri di parola Unicode)

Il parametro $offset può indicare la posizione iniziale della ricerca (in byte; in caratteri se è impostato $utf8).

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

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // senza UTF-8
// [['lut', 2]] (solo corrispondenza ASCII, offset in byte)

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // con UTF-8
// [['žlutý!', 0], ['!', 5]] (corrispondenza Unicode, offset in caratteri)

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 in una stringa tutte le occorrenze che corrispondono a un'espressione regolare e restituisce un array di array contenenti l'espressione trovata e le singole sottoespressioni.

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

Se $patternOrder è true, la struttura dei risultati cambia: il primo elemento è un array delle corrispondenze complete del pattern, il secondo è un array delle stringhe che corrispondono al primo sottopattern tra parentesi e così via:

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 stringa vuota oppure omessi:

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

Se $utf8 è true, la valutazione passa alla modalità Unicode, come con l'uso del 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ò indicare la posizione iniziale della ricerca (in byte; in caratteri se è impostato $utf8).

Se $captureOffset è true, viene restituita anche la posizione di ogni corrispondenza nella stringa (in byte; in caratteri se è impostato $utf8). Questo cambia la struttura del valore di ritorno, dove ogni elemento di corrispondenza è una coppia [stringa_trovata, 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. Questo offre vantaggi notevoli in termini di prestazioni quando si lavora con stringhe grandi, perché le corrispondenze vengono trovate progressivamente invece di elaborare l'intera stringa in una volta. Permette così di gestire in modo efficiente input molto grandi. Inoltre potete interrompere l'elaborazione in qualsiasi momento, se trovate la corrispondenza cercata, risparmiando tempo di calcolo.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // l'elaborazione si può interrompere in qualsiasi momento, per esempio con break;
}

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 che corrispondono a un'espressione regolare. $replacement è una maschera della stringa di sostituzione oppure una funzione di callback.

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

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

La funzione permette anche più sostituzioni passando come secondo parametro un array nel formato pattern => replacement:

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

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

Se $utf8 è true, la valutazione passa alla modalità Unicode, come con l'uso del modificatore u.

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

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

Se $captureOffset è true, alla callback viene passata anche la posizione di ogni corrispondenza nella stringa (in byte; in caratteri se è impostato $utf8). Questo cambia la struttura dell'array passato, dove ogni elemento è una coppia [stringa_trovata, posizione].

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

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

Se $unmatchedAsNull è true, i sottopattern senza corrispondenza vengono passati alla callback come null; altrimenti vengono passati come stringa vuota oppure omessi:

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// stampa ['ac', 'a', '', 'c']

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// stampa ['ac', 'a', null, 'c']