Nette Documentation Preview

syntax 
Fonctions des chaînes de caractères
***********************************

.[perex]
[api:Nette\Utils\Strings] est une classe statique qui contient de nombreuses fonctions utiles pour travailler avec des chaînes de caractères codées UTF-8.


Installation :

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

Tous les exemples supposent que l'alias de classe suivant est défini :

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


Letter Case .[#toc-letter-case]
===============================

Ces fonctions nécessitent l'extension PHP `mbstring`.


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

Convertit tous les caractères de la chaîne UTF-8 en minuscules.

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


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

Convertit tous les caractères d'une chaîne UTF-8 en majuscules.

```php
Strings::upper('Hello world'); // 'HELLO WORLD'
```


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

Convertit le premier caractère d'une chaîne UTF-8 en majuscule et laisse les autres caractères inchangés.

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


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

Convertit le premier caractère d'une chaîne UTF-8 en minuscule et laisse les autres caractères inchangés.

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


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

Convertit le premier caractère de chaque mot d'une chaîne UTF-8 en majuscule et les autres en minuscule.

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


Modification d'une chaîne de caractères .[#toc-editing-a-string]
================================================================


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

Supprime les caractères de contrôle, normalise les sauts de ligne à `\n`, supprime les lignes vides de début et de fin, coupe les espaces de fin de ligne, normalise UTF-8 à la forme normale de NFC.


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

Convertit les sauts de ligne en `\n` utilisés sur les systèmes Unix. Les sauts de ligne sont : `\n`, `\r`, `\r\n`, U+2028 séparateur de ligne, U+2029 séparateur de paragraphe.

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


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

Convertit les sauts de ligne en caractères spécifiques à la plate-forme actuelle, c'est-à-dire `\r\n` sous Windows et `\n` ailleurs. Les sauts de ligne sont `\n`, `\r`, `\r\n`, U+2028 séparateur de ligne, U+2029 séparateur de paragraphe.

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


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

Modifie la chaîne UTF-8 à la forme utilisée dans l'URL, c'est-à-dire supprime les diacritiques et remplace tous les caractères sauf les lettres de l'alphabet anglais et les chiffres par un trait d'union.

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

D'autres caractères peuvent également être préservés, mais ils doivent être passés en second argument.

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

Le troisième argument peut supprimer la conversion de la chaîne en minuscules.

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

.[caution]
Nécessite l'extension PHP `intl`.


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

Supprime tous les espaces à gauche et à droite (ou les caractères passés en second argument) d'une chaîne de caractères encodée en UTF-8.

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


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

Tronque une chaîne UTF-8 à une longueur maximale donnée, tout en essayant de ne pas couper des mots entiers. Seulement si la chaîne est tronquée, une ellipse (ou autre chose définie avec le troisième argument) est ajoutée à la chaîne.

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

Indente un texte multiligne à partir de la gauche. Le deuxième argument définit le nombre de caractères d'indentation à utiliser, tandis que l'indentation elle-même est le troisième argument (*tab* par défaut).

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


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

Remplit une chaîne UTF-8 à une longueur donnée en ajoutant la chaîne `$pad` au début.

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


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

Ajoute une chaîne UTF-8 à une longueur donnée en ajoutant la chaîne `$pad` à la fin.

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


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

Renvoie une partie de la chaîne UTF-8 spécifiée par la position de départ `$start` et la longueur `$length`. Si `$start` est négatif, la chaîne retournée commencera au `$start`'ème caractère à partir de la fin de la chaîne.

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

Inverse la chaîne UTF-8.

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


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

Renvoie le nombre de caractères (et non d'octets) dans une chaîne UTF-8.

Il s'agit du nombre de points de code Unicode, qui peut différer du nombre de graphèmes.

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


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

Vérifie si la chaîne `$haystack` commence par `$needle`.

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

.[note]
Utilise les natifs `str_starts_with()`:https://www.php.net/manual/en/function.str-starts-with.php.


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

Vérifie si la chaîne `$haystack` se termine par `$needle`.

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

.[note]
Utilisation de `str_ends_with()`:https://www.php.net/manual/en/function.str-ends-with.php.


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

Vérifie si la chaîne `$haystack` contient `$needle`.

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

.[note]
Utilise le natif `str_contains()`:https://www.php.net/manual/en/function.str-contains.php.


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

Compare deux chaînes de caractères UTF-8 ou leurs parties, sans tenir compte de la casse des caractères. Si `$length` est nul, les chaînes entières sont comparées, s'il est négatif, le nombre correspondant de caractères depuis la fin des chaînes est comparé, sinon le nombre approprié de caractères depuis le début est comparé.

```php
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 .[method]
-----------------------------------------

Trouve le préfixe commun des chaînes de caractères ou renvoie une chaîne vide si le préfixe n'a pas été trouvé.

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

Renvoie la partie de `$haystack` avant l'occurrence de `$nth` de `$needle` ou renvoie `null` si l'aiguille n'a pas été trouvée. Une valeur négative signifie que la recherche se fait à partir de la fin.

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

Renvoie une partie de `$haystack` après l'occurrence de `$nth` sur `$needle` ou renvoie `null` si `$needle` n'a pas été trouvé. Une valeur négative de `$nth` signifie que la recherche se fait à partir de la fin.

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

Renvoie la position en caractères de `$nth`, l'occurrence de `$needle` dans `$haystack` ou `null` si `$needle` n'a pas été trouvé. Une valeur négative de `$nth` signifie que la recherche se fait à partir de la fin.

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


Encodage .[#toc-encoding]
=========================


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

Supprime tous les caractères UTF-8 invalides d'une chaîne de caractères.

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


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

Vérifie si la chaîne est valide dans l'encodage UTF-8.

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

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


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

Convertit une chaîne UTF-8 en ASCII, c'est-à-dire qu'elle supprime les diacritiques, etc.

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

.[caution]
Nécessite l'extension PHP `intl`.


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

Renvoie un caractère spécifique en UTF-8 à partir du point de code (numéro dans la plage 0x0000..D7FF ou 0xE000..10FFFF).

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


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

Renvoie le point de code d'un caractère spécifique en UTF-8 (nombre compris entre 0x0000..D7FF ou 0xE000..10FFFF).

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


Expressions régulières .[#toc-regular-expressions]
==================================================

La classe Strings fournit des fonctions pour travailler avec des expressions régulières. Contrairement aux fonctions natives de PHP, elles disposent d'une API plus compréhensible, d'un meilleur support de l'Unicode et, surtout, d'une détection des erreurs. Toute erreur de compilation ou de traitement d'expression entraînera une exception `Nette\RegexpException`.


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

Divise la chaîne de caractères en tableaux selon l'expression régulière. Les expressions entre parenthèses seront également capturées et renvoyées.

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

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

Si `$skipEmpty` est `true`, seuls les éléments non vides seront renvoyés :

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

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

Si `$limit` est spécifié, seules les sous-chaînes jusqu'à la limite seront retournées et le reste de la chaîne sera placé dans le dernier élément. Une limite de -1 ou 0 signifie qu'il n'y a pas de limite.

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

Si `$utf8` est `true`, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur `u`.

Si `$captureOffset` est `true`, pour chaque correspondance, sa position dans la chaîne sera également retournée (en octets ; en caractères si `$utf8` est défini). Cela change la valeur de retour en un tableau où chaque élément est une paire composée de la chaîne de caractères correspondante et de sa position.

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

Recherche dans la chaîne la partie correspondant à l'expression régulière et renvoie un tableau contenant l'expression trouvée et les sous-expressions individuelles, ou `null`.

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

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

Si `$unmatchedAsNull` est `true`, les sous-motifs non appariés sont renvoyés comme nuls ; sinon, ils sont renvoyés comme une chaîne vide ou ne sont pas renvoyés :

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

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

Si `$utf8` est `true`, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur `u` :

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

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

Le paramètre `$offset` peut être utilisé pour spécifier la position à partir de laquelle commencer la recherche (en octets ; en caractères si `$utf8` est défini).

Si `$captureOffset` est `true`, pour chaque correspondance, sa position dans la chaîne sera également renvoyée (en octets ; en caractères si `$utf8` est défini). Cela transforme la valeur de retour en un tableau où chaque élément est une paire constituée de la chaîne de caractères correspondante et de son décalage :

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

Recherche dans la chaîne toutes les occurrences correspondant à l'expression régulière et renvoie un tableau de tableaux contenant l'expression trouvée et chaque sous-expression.

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

Si `$patternOrder` est `true`, la structure des résultats change de sorte que le premier élément est un tableau de correspondances de motifs complets, le second est un tableau de chaînes correspondant au premier sous-modèle entre parenthèses, et ainsi de suite :

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

Si `$unmatchedAsNull` est `true`, les sous-motifs non appariés sont renvoyés sous la forme de null ; sinon, ils sont renvoyés sous la forme d'une chaîne vide ou ne sont pas renvoyés :

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

Si `$utf8` est `true`, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur `u` :

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

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

Le paramètre `$offset` peut être utilisé pour spécifier la position à partir de laquelle commencer la recherche (en octets ; en caractères si `$utf8` est défini).

Si `$captureOffset` est `true`, pour chaque correspondance, sa position dans la chaîne sera également renvoyée (en octets ; en caractères si `$utf8` est défini). Cela transforme la valeur de retour en un tableau où chaque élément est une paire constituée de la chaîne de caractères correspondante et de sa position :

```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]],
] */
```

Si `$lazy` est `true`, la fonction renvoie un `Generator` au lieu d'un tableau, ce qui offre des avantages considérables en termes de performances lorsque l'on travaille avec des chaînes de grande taille. Le générateur permet de trouver les correspondances de manière incrémentielle, plutôt que de traiter l'ensemble de la chaîne en une seule fois. Cela permet de traiter efficacement des textes d'entrée extrêmement volumineux. En outre, vous pouvez interrompre le traitement à tout moment si vous trouvez la correspondance souhaitée, ce qui permet d'économiser du temps de calcul.

```php
$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 .[method]
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Remplace toutes les occurrences correspondant à l'expression régulière. L'adresse `$replacement` est soit un masque de chaîne de remplacement, soit une fonction de rappel.

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

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

La fonction permet également des remplacements multiples en passant un tableau de la forme `pattern => replacement` dans le second paramètre :

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

Le paramètre `$limit` limite le nombre de substitutions. Limite -1 signifie aucune limite.

Si `$utf8` est `true`, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur `u`.

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

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

Si `$captureOffset` est `true`, pour chaque correspondance, sa position dans la chaîne (en octets ; en caractères si `$utf8` est défini) est également transmise à la fonction de rappel. Cela change la forme du tableau passé, où chaque élément est une paire composée de la chaîne de caractères correspondante et de sa position.

```php
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]]
```

Si `$unmatchedAsNull` est `true`, les sous-motifs non appariés sont transmis à la fonction d'appel comme nuls ; sinon, ils sont transmis comme une chaîne vide ou ne sont pas transmis :

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

Fonctions des chaînes de caractères

Nette\Utils\Strings est une classe statique qui contient de nombreuses fonctions utiles pour travailler avec des chaînes de caractères codées UTF-8.

Installation :

composer require nette/utils

Tous les exemples supposent que l'alias de classe suivant est défini :

use Nette\Utils\Strings;

Letter Case

Ces fonctions nécessitent l'extension PHP mbstring.

lower(string $s): string

Convertit tous les caractères de la chaîne UTF-8 en minuscules.

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

upper(string $s): string

Convertit tous les caractères d'une chaîne UTF-8 en majuscules.

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

firstUpper(string $s): string

Convertit le premier caractère d'une chaîne UTF-8 en majuscule et laisse les autres caractères inchangés.

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

firstLower(string $s): string

Convertit le premier caractère d'une chaîne UTF-8 en minuscule et laisse les autres caractères inchangés.

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

capitalize(string $s): string

Convertit le premier caractère de chaque mot d'une chaîne UTF-8 en majuscule et les autres en minuscule.

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

Modification d'une chaîne de caractères

normalize(string $s): string

Supprime les caractères de contrôle, normalise les sauts de ligne à \n, supprime les lignes vides de début et de fin, coupe les espaces de fin de ligne, normalise UTF-8 à la forme normale de NFC.

unixNewLines(string $s): string

Convertit les sauts de ligne en \n utilisés sur les systèmes Unix. Les sauts de ligne sont : \n, \r, \r\n, U+2028 séparateur de ligne, U+2029 séparateur de paragraphe.

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

platformNewLines(string $s): string

Convertit les sauts de ligne en caractères spécifiques à la plate-forme actuelle, c'est-à-dire \r\n sous Windows et \n ailleurs. Les sauts de ligne sont \n, \r, \r\n, U+2028 séparateur de ligne, U+2029 séparateur de paragraphe.

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

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

Modifie la chaîne UTF-8 à la forme utilisée dans l'URL, c'est-à-dire supprime les diacritiques et remplace tous les caractères sauf les lettres de l'alphabet anglais et les chiffres par un trait d'union.

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

D'autres caractères peuvent également être préservés, mais ils doivent être passés en second argument.

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

Le troisième argument peut supprimer la conversion de la chaîne en minuscules.

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

Nécessite l'extension PHP intl.

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

Supprime tous les espaces à gauche et à droite (ou les caractères passés en second argument) d'une chaîne de caractères encodée en UTF-8.

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

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

Tronque une chaîne UTF-8 à une longueur maximale donnée, tout en essayant de ne pas couper des mots entiers. Seulement si la chaîne est tronquée, une ellipse (ou autre chose définie avec le troisième argument) est ajoutée à la chaîne.

$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

Indente un texte multiligne à partir de la gauche. Le deuxième argument définit le nombre de caractères d'indentation à utiliser, tandis que l'indentation elle-même est le troisième argument (tab par défaut).

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

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

Remplit une chaîne UTF-8 à une longueur donnée en ajoutant la chaîne $pad au début.

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

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

Ajoute une chaîne UTF-8 à une longueur donnée en ajoutant la chaîne $pad à la fin.

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

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

Renvoie une partie de la chaîne UTF-8 spécifiée par la position de départ $start et la longueur $length. Si $start est négatif, la chaîne retournée commencera au $start'ème caractère à partir de la fin de la chaîne.

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

reverse(string $s): string

Inverse la chaîne UTF-8.

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

length(string $s): int

Renvoie le nombre de caractères (et non d'octets) dans une chaîne UTF-8.

Il s'agit du nombre de points de code Unicode, qui peut différer du nombre de graphèmes.

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

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

Vérifie si la chaîne $haystack commence par $needle.

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

Utilise les natifs str_starts_with().

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

Vérifie si la chaîne $haystack se termine par $needle.

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

Utilisation de str_ends_with().

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

Vérifie si la chaîne $haystack contient $needle.

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

Utilise le natif str_contains().

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

Compare deux chaînes de caractères UTF-8 ou leurs parties, sans tenir compte de la casse des caractères. Si $length est nul, les chaînes entières sont comparées, s'il est négatif, le nombre correspondant de caractères depuis la fin des chaînes est comparé, sinon le nombre approprié de caractères depuis le début est comparé.

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

Trouve le préfixe commun des chaînes de caractères ou renvoie une chaîne vide si le préfixe n'a pas été trouvé.

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

Renvoie la partie de $haystack avant l'occurrence de $nth de $needle ou renvoie null si l'aiguille n'a pas été trouvée. Une valeur négative signifie que la recherche se fait à partir de la fin.

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

Renvoie une partie de $haystack après l'occurrence de $nth sur $needle ou renvoie null si $needle n'a pas été trouvé. Une valeur négative de $nth signifie que la recherche se fait à partir de la fin.

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

Renvoie la position en caractères de $nth, l'occurrence de $needle dans $haystack ou null si $needle n'a pas été trouvé. Une valeur négative de $nth signifie que la recherche se fait à partir de la fin.

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

Encodage

fixEncoding(string $s): string

Supprime tous les caractères UTF-8 invalides d'une chaîne de caractères.

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

checkEncoding(string $s): bool

Vérifie si la chaîne est valide dans l'encodage UTF-8.

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

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

toAscii(string $s): string

Convertit une chaîne UTF-8 en ASCII, c'est-à-dire qu'elle supprime les diacritiques, etc.

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

Nécessite l'extension PHP intl.

chr(int $code): string

Renvoie un caractère spécifique en UTF-8 à partir du point de code (numéro dans la plage 0×0000..D7FF ou 0×E000..10FFFF).

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

ord(string $char): int

Renvoie le point de code d'un caractère spécifique en UTF-8 (nombre compris entre 0×0000..D7FF ou 0×E000..10FFFF).

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

Expressions régulières

La classe Strings fournit des fonctions pour travailler avec des expressions régulières. Contrairement aux fonctions natives de PHP, elles disposent d'une API plus compréhensible, d'un meilleur support de l'Unicode et, surtout, d'une détection des erreurs. Toute erreur de compilation ou de traitement d'expression entraînera une exception Nette\RegexpException.

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

Divise la chaîne de caractères en tableaux selon l'expression régulière. Les expressions entre parenthèses seront également capturées et renvoyées.

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

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

Si $skipEmpty est true, seuls les éléments non vides seront renvoyés :

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

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

Si $limit est spécifié, seules les sous-chaînes jusqu'à la limite seront retournées et le reste de la chaîne sera placé dans le dernier élément. Une limite de –1 ou 0 signifie qu'il n'y a pas de limite.

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

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u.

Si $captureOffset est true, pour chaque correspondance, sa position dans la chaîne sera également retournée (en octets ; en caractères si $utf8 est défini). Cela change la valeur de retour en un tableau où chaque élément est une paire composée de la chaîne de caractères correspondante et de sa position.

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

Recherche dans la chaîne la partie correspondant à l'expression régulière et renvoie un tableau contenant l'expression trouvée et les sous-expressions individuelles, ou null.

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

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

Si $unmatchedAsNull est true, les sous-motifs non appariés sont renvoyés comme nuls ; sinon, ils sont renvoyés comme une chaîne vide ou ne sont pas renvoyés :

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

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

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u :

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

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

Le paramètre $offset peut être utilisé pour spécifier la position à partir de laquelle commencer la recherche (en octets ; en caractères si $utf8 est défini).

Si $captureOffset est true, pour chaque correspondance, sa position dans la chaîne sera également renvoyée (en octets ; en caractères si $utf8 est défini). Cela transforme la valeur de retour en un tableau où chaque élément est une paire constituée de la chaîne de caractères correspondante et de son décalage :

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

Recherche dans la chaîne toutes les occurrences correspondant à l'expression régulière et renvoie un tableau de tableaux contenant l'expression trouvée et chaque sous-expression.

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

Si $patternOrder est true, la structure des résultats change de sorte que le premier élément est un tableau de correspondances de motifs complets, le second est un tableau de chaînes correspondant au premier sous-modèle entre parenthèses, et ainsi de suite :

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

Si $unmatchedAsNull est true, les sous-motifs non appariés sont renvoyés sous la forme de null ; sinon, ils sont renvoyés sous la forme d'une chaîne vide ou ne sont pas renvoyés :

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

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u :

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

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

Le paramètre $offset peut être utilisé pour spécifier la position à partir de laquelle commencer la recherche (en octets ; en caractères si $utf8 est défini).

Si $captureOffset est true, pour chaque correspondance, sa position dans la chaîne sera également renvoyée (en octets ; en caractères si $utf8 est défini). Cela transforme la valeur de retour en un tableau où chaque élément est une paire constituée de la chaîne de caractères correspondante et de sa position :

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]],
] */

Si $lazy est true, la fonction renvoie un Generator au lieu d'un tableau, ce qui offre des avantages considérables en termes de performances lorsque l'on travaille avec des chaînes de grande taille. Le générateur permet de trouver les correspondances de manière incrémentielle, plutôt que de traiter l'ensemble de la chaîne en une seule fois. Cela permet de traiter efficacement des textes d'entrée extrêmement volumineux. En outre, vous pouvez interrompre le traitement à tout moment si vous trouvez la correspondance souhaitée, ce qui permet d'économiser du temps de calcul.

$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

Remplace toutes les occurrences correspondant à l'expression régulière. L'adresse $replacement est soit un masque de chaîne de remplacement, soit une fonction de rappel.

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

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

La fonction permet également des remplacements multiples en passant un tableau de la forme pattern => replacement dans le second paramètre :

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

Le paramètre $limit limite le nombre de substitutions. Limite –1 signifie aucune limite.

Si $utf8 est true, l'évaluation passe en mode Unicode. Ceci est similaire à la spécification du modificateur u.

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

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

Si $captureOffset est true, pour chaque correspondance, sa position dans la chaîne (en octets ; en caractères si $utf8 est défini) est également transmise à la fonction de rappel. Cela change la forme du tableau passé, où chaque élément est une paire composée de la chaîne de caractères correspondante et de sa position.

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

Si $unmatchedAsNull est true, les sous-motifs non appariés sont transmis à la fonction d'appel comme nuls ; sinon, ils sont transmis comme une chaîne vide ou ne sont pas transmis :

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