Funzioni di stringa

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

Installazione:

composer require nette/utils

Tutti gli esempi presuppongono che sia definito il seguente alias di classe:

use Nette\Utils\Strings;

Lettera Caso

Queste funzioni richiedono l'estensione PHP mbstring.

lower (string $s): string

Converte tutti i caratteri della stringa UTF-8 in minuscolo.

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

upper (string $s): string

Converte tutti i caratteri di una stringa UTF-8 in maiuscole.

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

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

Modifica di una stringa

normalize (string $s): string

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

unixNewLines (string $s): string

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

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

platformNewLines (string $s): string

Converte le interruzioni di riga in caratteri specifici della piattaforma corrente, ad esempio \r\n su Windows e \n altrove. Le interruzioni di riga sono \n, \r, \r\n, U+2028 separatore di riga, U+2029 separatore di paragrafo.

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

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

Modifica la stringa UTF-8 nella forma usata nell'URL, cioè rimuove i diacritici e sostituisce tutti i caratteri tranne le lettere dell'alfabeto inglese e i numeri con un trattino.

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

Anche altri caratteri possono essere conservati, ma devono essere passati come secondo argomento.

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

Il terzo argomento può sopprimere la conversione della stringa in minuscolo.

Strings::webalize('Hello world', null, false); // 'Hello-world'

Richiede l'estensione PHP intl.

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

Rimuove tutti gli spazi a sinistra e a destra (o i caratteri passati come secondo argomento) da una stringa codificata UTF-8.

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

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

Tronca una stringa UTF-8 alla lunghezza massima indicata, cercando di non dividere le parole intere. Solo se la stringa viene troncata, alla stringa viene aggiunta un'ellissi (o qualcos'altro impostato con il terzo argomento).

$text = 'Hello, how are you today?';
Strings::truncate($text, 5);       // 'Hell…'
Strings::truncate($text, 20);      // 'Hello, how are you…'
Strings::truncate($text, 30);      // 'Hello, how are you today?'
Strings::truncate($text, 20, '~'); // 'Hello, how are you~'

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

Rientra un testo multilinea da sinistra. Il secondo argomento stabilisce il numero di caratteri di rientro da utilizzare, mentre il rientro stesso è il terzo argomento (tab per impostazione predefinita).

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

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

Imbottisce una stringa UTF-8 alla lunghezza data, anteponendo la stringa $pad all'inizio.

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

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

Imbottisce una stringa UTF-8 alla lunghezza data aggiungendo la stringa $pad alla fine.

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

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

reverse (string $s): string

Inverte la stringa UTF-8.

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

length (string $s): int

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

Si tratta del numero di punti di codice Unicode, che può differire dal numero di grafemi.

Strings::length('Nette'); // 5
Strings::length('red');   // 3

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

Controlla se la stringa $haystack inizia con $needle.

$haystack = 'Begins';
$needle = 'Be';
Strings::startsWith($haystack, $needle); // true

Utilizzare il nativo str_starts_with().

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

Controlla se la stringa $haystack termina con $needle.

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

Utilizzare str_ends_with() nativo:https://www.php.net/…nds-with.php.

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

Controlla se la stringa $haystack contiene $needle.

$haystack = 'Contains';
$needle = 'tai';
Strings::contains($haystack, $needle); // true

Utilizzare str_contains() nativo :https://www.php.net/…contains.php.

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

Confronta due stringhe UTF-8 o le loro parti, senza tenere conto del caso dei caratteri. Se $length è nullo, vengono confrontate le stringhe intere, se è negativo, viene confrontato il numero corrispondente di caratteri dalla fine delle stringhe, altrimenti viene confrontato il numero appropriato di caratteri dall'inizio.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - two first characters match
Strings::compare('Nette', 'Latte', -2); // true - two last characters match

findPrefix (…$strings): string

Trova il prefisso comune delle stringhe o restituisce una stringa vuota se il prefisso non è stato trovato.

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 una parte di $haystack prima dell'occorrenza di $nth in $needle o restituisce null se l'ago non è stato trovato. Il valore negativo indica la ricerca dalla fine.

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 una parte di $haystack dopo l'occorrenza di $nth in $needle o restituisce null se $needle non è stato trovato. Il valore negativo di $nth indica la ricerca dalla fine.

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 di $nth in cui si trova $needle in $haystack o null se $needle non è stato trovato. Il valore negativo di $nth indica la ricerca dalla fine.

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 tutti i caratteri UTF-8 non validi da una stringa.

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

checkEncoding (string $s): bool

Verifica se la stringa è valida nella codifica UTF-8.

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

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

toAscii (string $s): string

Converte le stringhe UTF-8 in ASCII, cioè 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 o 0xE000..10FFFF).

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

ord (string $char): int

Restituisce un 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 fornisce funzioni per lavorare con le espressioni regolari. A differenza delle funzioni native di PHP, hanno un'API più comprensibile, un migliore supporto Unicode e, soprattutto, un rilevamento degli errori. Qualsiasi errore di compilazione o di elaborazione delle espressioni lancerà un'eccezione Nette\RegexpException.

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

Divide la stringa in array in base all'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, 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 nessun limite.

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

Se $utf8 è true, la valutazione passa alla modalità Unicode. Questo è simile alla specificazione del modificatore u.

Se $captureOffset è true, per ogni corrispondenza che si verifica, viene restituita anche la sua posizione nella stringa (in byte; in caratteri se $utf8 è impostato). Questo cambia il valore di ritorno in un array in cui ogni elemento è una coppia composta dalla stringa abbinata e dalla sua posizione.

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 la 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, le sottoespressioni non corrispondenti vengono restituite come null; altrimenti vengono restituite come una stringa vuota o non vengono restituite:

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

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

Se $utf8 è true, la valutazione passa alla modalità Unicode. Ciò è simile alla specificazione del modificatore u:

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

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

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

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

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 che corrispondono all'espressione regolare e restituisce un array di array contenenti l'espressione trovata e ogni sottoespressione.

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

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

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

Se $unmatchedAsNull è true, i sottopattern senza corrispondenza vengono restituiti come null; altrimenti vengono restituiti come una stringa vuota o non vengono restituiti:

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

Se $utf8 è true, la valutazione passa alla modalità Unicode. Ciò è simile alla specificazione del modificatore u:

Strings::matchAll('žlutý kůň', '~\w+~');
/* [
	0 => ['lut'],
	1 => ['k'],
] */

Strings::matchAll('žlutý kůň', '~\w+~', utf8: true);
/* [
	0 => ['žlutý'],
	1 => ['kůň'],
] */

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

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

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, con notevoli vantaggi in termini di prestazioni quando si lavora con stringhe di grandi dimensioni. Il generatore consente di trovare le corrispondenze in modo incrementale, anziché elaborare l'intera stringa in una sola volta. Ciò consente di gestire in modo efficiente testi di input molto grandi. Inoltre, è possibile interrompere l'elaborazione in qualsiasi momento se si trova la corrispondenza desiderata, risparmiando tempo di calcolo.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // Processing can be interrupted at any time
}

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 all'espressione regolare. Il parametro $replacement è una maschera di stringa sostitutiva o un richiamo.

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

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

La funzione consente anche sostituzioni multiple passando un array della forma pattern => replacement nel secondo parametro:

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

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

Se $utf8 è true, la valutazione passa alla modalità Unicode. Ciò è simile alla specificazione del modificatore u.

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

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

Se $captureOffset è true, per ogni corrispondenza che si verifica, la sua posizione nella stringa (in byte; in caratteri se $utf8 è impostato) viene passata anche al callback. Questo cambia la forma dell'array passato, dove ogni elemento è una coppia composta dalla stringa corrispondente e dalla sua posizione.

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

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

Se $unmatchedAsNull è true, i sottopattern non abbinati vengono passati alla callback come null; altrimenti vengono passati come una stringa vuota o non vengono passati:

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