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