Funções das cordas
******************

.[perex]
[api:Nette\Utils\Strings] é uma classe estática, que contém muitas funções úteis para trabalhar com cordas codificadas UTF-8.


Instalação:

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

Todos os exemplos assumem que a seguinte classe está definida:

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


Estojo de carta .[#toc-letter-case]
===================================

Estas funções requerem a extensão PHP `mbstring`.


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

Converte todos os caracteres de corda UTF-8 em minúsculas.

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


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

Converte todos os caracteres de uma corda UTF-8 em maiúsculas.

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


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

Converte o primeiro caractere de um fio UTF-8 em maiúsculas e deixa os outros caracteres inalterados.

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


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

Converte o primeiro caractere de uma corda UTF-8 para minúscula e deixa os outros caracteres inalterados.

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


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

Converte o primeiro caractere de cada palavra de uma cadeia UTF-8 para maiúscula e os outros para minúscula.

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


Edição de uma corda .[#toc-editing-a-string]
============================================


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

Remove caracteres de controle, normaliza as quebras de linha para `\n`, remove linhas em branco, corrige os espaços finais nas linhas, normaliza UTF-8 para a forma normal de NFC.


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

Converte as quebras de linha para `\n` utilizadas em sistemas Unix. As quebras de linha são: `\n`, `\r`, `\r\n`, Separador de linha U+2028, Separador de parágrafo U+2029.

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


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

Converte as quebras de linha em caracteres específicos da plataforma atual, ou seja, `\r\n` no Windows e `\n` em outros lugares. As quebras de linha são `\n`, `\r`, `\r\n`, separador de linha U+2028, separador de parágrafo U+2029.

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


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

Modifica a cadeia UTF-8 para a forma usada na URL, ou seja, remove os diacríticos e substitui todos os caracteres exceto letras do alfabeto inglês e números por um hífen.

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

Outros caracteres também podem ser preservados, mas devem ser passados como segundo argumento.

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

O terceiro argumento pode suprimir a conversão da corda em minúscula.

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

.[caution]
Requer extensão PHP `intl`.


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

Remove todos os espaços do lado esquerdo e direito (ou os caracteres passados como segundo argumento) de uma cadeia codificada UTF-8.

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


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

Truncata um fio UTF-8 para dar o comprimento máximo, enquanto tenta não dividir palavras inteiras. Somente se a corda for truncada, uma elipse (ou qualquer outra coisa com terceiro argumento) é anexada à corda.

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

Traz um texto com várias linhas da esquerda. O segundo argumento estabelece quantos caracteres de recuo devem ser usados, enquanto o próprio recuo é o terceiro argumento (*tab* por padrão).

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


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

Coloque uma corda UTF-8 em um determinado comprimento, pré-pendendo a corda `$pad` para o início.

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


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

Comprimento do cordão UTF-8, anexando o cordão `$pad` ao final.

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


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

Retorna uma parte da cadeia UTF-8 especificada pela posição inicial `$start` e comprimento `$length`. Se `$start` for negativo, a cadeia de caracteres retornada começará no `$start`'th character from the end of string'.

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

Inverte a corda UTF-8.

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


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

Retorna o número de caracteres (não bytes) em cadeia UTF-8.

Esse é o número de pontos de código Unicode que pode diferir do número de grafemas.

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


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

Verifica se `$haystack` string começa com `$needle`.

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

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


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

Verifica se `$haystack` string end com `$needle`.

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

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


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

Verifica se o texto `$haystack` contém `$needle`.

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

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


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

Compara duas cordas UTF-8 ou suas partes, sem levar em conta o caso de caracteres. Se `$length` for nulo, cordas inteiras são comparadas, se for negativo, o número correspondente de caracteres do final das cordas é comparado, caso contrário, o número apropriado de caracteres do início é comparado.

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

Encontra o prefixo comum de cordas ou devolve cordas vazias se o prefixo não foi encontrado.

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

Devolve parte de `$haystack` antes da ocorrência de `$nth` `$needle` ou devolve `null` se a agulha não foi encontrada. Valor negativo significa busca a partir do 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]
----------------------------------------------------------------------

Devolve parte de `$haystack` após `$nth` ocorrência de `$needle` ou retorna `null` se o `$needle` não foi encontrado. O valor negativo de `$nth` significa uma busca a partir do 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]
---------------------------------------------------------------------

Retorna posição em caracteres de `$nth` ocorrência de `$needle` em `$haystack` ou `null` se o `$needle` não foi encontrado. O valor negativo de `$nth` significa pesquisa a partir do 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
```


Codificação .[#toc-encoding]
============================


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

Remove todos os caracteres UTF-8 inválidos de uma corda.

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


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

Verifica se a corda é válida na codificação UTF-8.

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

.[note]
Use [Nette\UtilsValidator::isUnicode() |validators#isUnicode].


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

Converte o fio UTF-8 em ASCII, ou seja, remove diacríticos, etc.

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

.[caution]
Requer extensão PHP `intl`.


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

Retorna um caractere específico em UTF-8 do ponto de código (número na faixa 0x0000..D7FF ou 0xE000..10FFFFFF).

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


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

Retorna um ponto de código de caráter específico em UTF-8 (número na faixa 0x0000..D7FF ou 0xE000..10FFFFFF).

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


Expressões regulares .[#toc-regular-expressions]
================================================

A classe Strings fornece funções para trabalhar com expressões regulares. Ao contrário das funções PHP nativas, elas têm uma API mais compreensível, melhor suporte a Unicode e, o mais importante, detecção de erros. Qualquer erro de compilação ou de processamento de expressões lançará uma exceção `Nette\RegexpException`.


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

Divide o cordão em arrays de acordo com a expressão regular. Expressões entre parênteses serão capturadas e devolvidas também.

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

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

Se `$skipEmpty` é `true`, somente os itens não vazios serão devolvidos:

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

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

Se `$limit` for especificado, somente substratos até o limite serão devolvidos e o resto do cordel será colocado no último elemento. Um limite de -1 ou 0 significa que não há limite.

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

Se `$utf8` é `true`, a avaliação muda para o modo Unicode. Isto é semelhante a especificar o modificador `u`.

Se `$captureOffset` for `true`, para cada partida ocorrida, sua posição na cadeia também será devolvida (em bytes; em caracteres se `$utf8` estiver definido). Isto muda o valor de retorno para uma matriz onde cada elemento é um par que consiste da corda combinada e sua posição.

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

Procura na cadeia a peça que corresponde à expressão regular e retorna uma matriz com a expressão encontrada e subexpressões individuais, ou `null`.

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

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

Se `$unmatchedAsNull` é `true`, subpadrões inigualáveis são devolvidos como nulos; caso contrário, são devolvidos como uma cadeia vazia ou não devolvidos:

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

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

Se `$utf8` é `true`, a avaliação muda para o modo Unicode. Isto é semelhante a especificar o modificador `u`:

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

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

O parâmetro `$offset` pode ser usado para especificar a posição a partir da qual se inicia a busca (em bytes; em caracteres se `$utf8` estiver definido).

Se `$captureOffset` for `true`, para cada partida ocorrida, sua posição na cadeia também será devolvida (em bytes; em caracteres se `$utf8` estiver definido). Isto muda o valor de retorno para um array onde cada elemento é um par que consiste na string correspondente e seu offset:

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

Procura na cadeia todas as ocorrências que correspondem à expressão regular e retorna uma matriz de matrizes contendo a expressão encontrada e cada subexpressão.

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

Se `$patternOrder` é `true`, a estrutura dos resultados muda para que o primeiro item seja um conjunto de correspondências de padrões completos, o segundo é um conjunto de cordas correspondentes ao primeiro subpadrão entre parênteses, e assim por diante:

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

Se `$unmatchedAsNull` é `true`, subpadrões inigualáveis são devolvidos como nulos; caso contrário, são devolvidos como uma cadeia vazia ou não devolvidos:

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

Se `$utf8` é `true`, a avaliação muda para o modo Unicode. Isto é semelhante a especificar o modificador `u`:

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

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

O parâmetro `$offset` pode ser usado para especificar a posição a partir da qual se inicia a busca (em bytes; em caracteres se `$utf8` estiver definido).

Se `$captureOffset` for `true`, para cada partida ocorrida, sua posição na cadeia também será devolvida (em bytes; em caracteres se `$utf8` estiver definido). Isto muda o valor de retorno para uma matriz onde cada elemento é um par que consiste da corda combinada e sua posição:

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

Se `$lazy` for `true`, a função retornará um `Generator` em vez de uma matriz, o que proporciona benefícios significativos de desempenho ao trabalhar com cadeias de caracteres grandes. O gerador permite que as correspondências sejam encontradas de forma incremental, em vez de processar a cadeia inteira de uma só vez. Isso permite o manuseio eficiente de textos de entrada extremamente grandes. Além disso, você pode interromper o processamento a qualquer momento se encontrar a correspondência desejada, economizando tempo computacional.

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

Substitui todas as ocorrências que correspondem à expressão regular. O `$replacement` é ou uma máscara de corda substituta ou uma callback.

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

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

A função também permite múltiplas substituições, passando um array do formulário `pattern => replacement` no segundo parâmetro:

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

O parâmetro `$limit` limita o número de substituições. O limite -1 significa sem limite.

Se `$utf8` é `true`, a avaliação muda para o modo Unicode. Isto é semelhante a especificar o modificador `u`.

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

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

Se `$captureOffset` for `true`, para cada partida ocorrida, sua posição na cadeia (em bytes; em caracteres se `$utf8` estiver definido) também é passada para o retorno da chamada. Isto muda a forma da matriz passada, onde cada elemento é um par composto pela corda correspondente e sua posição.

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

Se `$unmatchedAsNull` é `true`, subpadrões inigualáveis são passados como nulos; caso contrário, são passados como um fio vazio ou não são passados:

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