Funciones de cadena

Nette\Utils\Strings es una clase estática que contiene muchas funciones útiles para trabajar con cadenas codificadas en UTF-8.

Instalación:

composer require nette/utils

Todos los ejemplos asumen que el siguiente alias de clase está definido:

use Nette\Utils\Strings;

Caja de letras

Estas funciones requieren la extensión PHP mbstring.

lower (string $s): string

Convierte todos los caracteres de la cadena UTF-8 a minúsculas.

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

upper (string $s): string

Convierte todos los caracteres de una cadena UTF-8 a mayúsculas.

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

firstUpper (string $s): string

Convierte el primer carácter de una cadena UTF-8 a mayúsculas y deja el resto de caracteres sin cambios.

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

firstLower (string $s): string

Convierte el primer carácter de una cadena UTF-8 a minúsculas y deja el resto de caracteres sin cambios.

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

capitalize (string $s): string

Convierte el primer carácter de cada palabra de una cadena UTF-8 a mayúsculas y los demás a minúsculas.

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

Editar una cadena

normalize (string $s): string

Elimina los caracteres de control, normaliza los saltos de línea a \n, elimina las líneas en blanco iniciales y finales, recorta los espacios al final de las líneas, normaliza UTF-8 a la forma normal de NFC.

unixNewLines (string $s): string

Convierte los saltos de línea en \n utilizados en los sistemas Unix. Los saltos de línea son: \n, \r, \r\n, U+2028 separador de línea, U+2029 separador de párrafo.

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

platformNewLines (string $s): string

Convierte los saltos de línea en caracteres específicos de la plataforma actual, es decir, \r\n en Windows y \n en otros sitios. Los saltos de línea son \n, \r, \r\n, U+2028 separador de línea, U+2029 separador de párrafo.

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

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

Modifica la cadena UTF-8 a la forma utilizada en la URL, es decir, elimina los diacríticos y sustituye todos los caracteres excepto las letras del alfabeto inglés y los números por un guión.

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

También pueden conservarse otros caracteres, pero deben pasarse como segundo argumento.

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

El tercer argumento puede suprimir la conversión de la cadena a minúsculas.

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

Requiere la extensión PHP intl.

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

Elimina todos los espacios a la izquierda y a la derecha (o los caracteres pasados como segundo argumento) de una cadena codificada en UTF-8.

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

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

Trunca una cadena UTF-8 a la longitud máxima dada, intentando no dividir palabras enteras. Sólo si la cadena está truncada, se añade una elipsis (u otra cosa establecida con el tercer argumento) a la cadena.

$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

Indenta un texto multilínea desde la izquierda. El segundo argumento establece cuántos caracteres de sangría deben utilizarse, mientras que la propia sangría es el tercer argumento (tab por defecto).

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

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

Rellena una cadena UTF-8 con la longitud dada añadiendo la cadena $pad al principio.

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

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

Rellena la cadena UTF-8 a la longitud dada añadiendo la cadena $pad al final.

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

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

Devuelve una parte de la cadena UTF-8 especificada por la posición inicial $start y la longitud $length. Si $start es negativo, la cadena devuelta comenzará en el carácter $start'th desde el final de la cadena.

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

reverse (string $s): string

Invierte la cadena UTF-8.

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

length (string $s): int

Devuelve el número de caracteres (no bytes) de una cadena UTF-8.

Es decir, el número de puntos de código Unicode, que puede diferir del número de grafemas.

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

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

Compara dos cadenas UTF-8 o sus partes, sin tener en cuenta las mayúsculas y minúsculas. Si $length es nulo, se comparan cadenas enteras; si es negativo, se compara el número correspondiente de caracteres desde el final de las cadenas; en caso contrario, se compara el número correspondiente de caracteres desde el principio.

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

Busca el prefijo común de las cadenas o devuelve una cadena vacía si no se ha encontrado el prefijo.

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

Devuelve parte de $haystack antes de $nth ocurrencia de $needle o devuelve null si no se encontró la aguja. Un valor negativo significa buscar desde el final.

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

Devuelve parte de $haystack tras la aparición de $nth en $needle o devuelve null si no se ha encontrado $needle. El valor negativo de $nth significa buscar desde el final.

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

Devuelve la posición en caracteres de $nth ocurrencia de $needle en $haystack o null si no se encontró $needle. El valor negativo de $nth significa buscar desde el final.

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

Codificación

fixEncoding (string $s): string

Elimina todos los caracteres UTF-8 no válidos de una cadena.

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

toAscii (string $s): string

Convierte una cadena UTF-8 a ASCII, es decir, elimina los diacríticos, etc.

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

Requiere la extensión PHP intl.

chr (int $code): string

Devuelve un carácter específico en UTF-8 desde el punto de código (número en el rango 0×0000..D7FF o 0xE000..10FFFF).

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

ord (string $char): int

Devuelve un punto de código de carácter específico en UTF-8 (número en el rango 0×0000..D7FF o 0xE000..10FFFF).

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

Expresiones regulares

La clase Strings proporciona funciones para trabajar con expresiones regulares. A diferencia de las funciones nativas de PHP, tiene una API más comprensible, mejor soporte Unicode y, lo más importante, detección de errores. Cualquier error de compilación o de procesamiento de expresiones lanzará una excepción Nette\RegexpException.

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

Divide la cadena en matrices según la expresión regular. Las expresiones entre paréntesis también se capturarán y devolverán.

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

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

Si $skipEmpty es true, sólo se devolverán los elementos no vacíos:

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

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

Si se especifica $limit, sólo se devolverán las subcadenas hasta el límite y el resto de la cadena se colocará en el último elemento. Un límite de –1 o 0 significa que no hay límite.

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

Si $utf8 es true, la evaluación cambia a modo Unicode. Esto es similar a especificar el modificador u.

Si $captureOffset es true, su posición en la cadena (en bytes; en caracteres si $utf8 está definido) también se devolverá para cada coincidencia que se produzca. Esto cambia el valor de retorno a un array donde cada elemento es un par formado por la cadena coincidente y su posición.

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

Busca en la cadena la parte que coincide con la expresión regular y devuelve una matriz con la expresión encontrada y las subexpresiones individuales, o null.

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

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

Si $unmatchedAsNull es true, los subpatrones no coincidentes se devuelven como nulos; en caso contrario, se devuelven como una cadena vacía o no se devuelven:

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

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

Si $utf8 es true, la evaluación cambia a modo Unicode. Esto es similar a especificar el modificador u:

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

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

El parámetro $offset puede utilizarse para especificar la posición a partir de la cual se inicia la búsqueda (en bytes; en caracteres si se establece $utf8).

Si $captureOffset es true, para cada coincidencia que se produzca, también se devolverá su posición en la cadena (en bytes; en caracteres si se establece $utf8). Esto cambia el valor de retorno a una matriz en la que cada elemento es un par formado por la cadena coincidente y su desplazamiento:

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

Busca en la cadena todas las ocurrencias que coincidan con la expresión regular y devuelve una matriz de matrices que contiene la expresión encontrada y cada subexpresión.

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

Si $patternOrder es true, la estructura de los resultados cambia de modo que el primer elemento es una matriz de coincidencias de patrones completos, el segundo es una matriz de cadenas que coinciden con el primer sub-patrón entre paréntesis, y así sucesivamente:

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

Si $unmatchedAsNull es true, los subpatrones no coincidentes se devuelven como nulos; en caso contrario, se devuelven como una cadena vacía o no se devuelven:

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

Si $utf8 es true, la evaluación cambia a modo Unicode. Esto es similar a especificar el modificador u:

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

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

El parámetro $offset puede utilizarse para especificar la posición a partir de la cual se inicia la búsqueda (en bytes; en caracteres si se establece $utf8).

Si $captureOffset es true, para cada coincidencia que se produzca, también se devolverá su posición en la cadena (en bytes; en caracteres si se establece $utf8). Esto cambia el valor de retorno a un array donde cada elemento es un par formado por la cadena coincidente y su posición:

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 es true, la función devuelve un Generator en lugar de una matriz, lo que proporciona importantes ventajas de rendimiento cuando se trabaja con cadenas de gran tamaño. El generador permite encontrar coincidencias de forma incremental, en lugar de procesar toda la cadena a la vez. Esto permite trabajar con textos de entrada de gran tamaño. Además, puede interrumpir el procesamiento en cualquier momento si encuentra la coincidencia deseada, lo que ahorra tiempo de cálculo.

$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

Reemplaza todas las ocurrencias que coincidan con la expresión regular. El $replacement es una máscara de cadena de reemplazo o una llamada de retorno.

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

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

La función también permite reemplazos múltiples pasando una matriz de la forma patrón => reemplazo en el segundo parámetro:

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

El parámetro $limit limita el número de sustituciones. Límite –1 significa sin límite.

Si $utf8 es true, la evaluación cambia a modo Unicode. Esto es similar a especificar el modificador u.

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

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

Si $captureOffset es true, por cada coincidencia que se produzca, su posición en la cadena (en bytes; en caracteres si se establece $utf8) también se pasa a la llamada de retorno. Esto cambia la forma del array pasado, donde cada elemento es un par formado por la cadena coincidente y su posición.

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 es true, los subpatrones no coincidentes se pasan a la llamada de retorno como nulos; en caso contrario, se pasan como una cadena vacía o no se pasan:

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']
  1. Documentación
  2. Utilidades
  3. Funciones de cadena
versión: 4.0