Funciones de cadena
*******************

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


Instalación:

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

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

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


Caja de letras .[#toc-letter-case]
==================================

Estas funciones requieren la extensión PHP `mbstring`.


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

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

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


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

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

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


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

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

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


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

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

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


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

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

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


Editar una cadena .[#toc-editing-a-string]
==========================================


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

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

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.

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


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

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.

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


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

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.

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

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

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

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

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

.[caution]
Requiere la extensión PHP `intl`.


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

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.

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


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

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.

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

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).

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


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

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

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


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

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

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


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

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.

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

Invierte la cadena UTF-8.

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


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

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.

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


/--comment









































\--


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

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.

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

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

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

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.

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

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.

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

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.

```php
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 .[#toc-encoding]
=============================


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

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

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


/--comment









\--


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

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

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

.[caution]
Requiere la extensión PHP `intl`.


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

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

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


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

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

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


Expresiones regulares .[#toc-encoding]
======================================

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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.

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

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

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

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

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