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