String Functions
****************

.[perex]
[api:Nette\Utils\Strings] is a static class, which contains many useful functions for working with UTF-8 encoded strings.


Installation:

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

All examples assume the following class alias is defined:

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


Letter Case
===========

These functions require the PHP extension `mbstring`.


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

Converts all characters of UTF-8 string to lower case.

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


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

Converts all characters of a UTF-8 string to upper case.

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


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

Converts the first character of a UTF-8 string to upper case and leaves the other characters unchanged.

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


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

Converts the first character of a UTF-8 string to lower case and leaves the other characters unchanged.

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


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

Converts the first character of every word of a UTF-8 string to upper case and the others to lower case.

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


Editing a String
================


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

Removes control characters, normalizes line breaks to `\n`, removes leading and trailing blank lines, trims end spaces on lines, normalizes UTF-8 to the normal form of NFC.


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

Standardize line endings to unix-like.

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


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

Modifies the UTF-8 string to the form used in the URL, ie removes diacritics and replaces all characters except letters of the English alphabet and numbers with a hyphens.

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

Other characters may be preserved as well, but they must be passed as second argument.

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

The third argument may suppress converting the string to lower case.

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

.[caution]
Requires PHP extension `intl`.


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

Removes all left and right side spaces (or the characters passed as second argument) from a UTF-8 encoded string.

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


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

Truncates a UTF-8 string to given maximal length, while trying not to split whole words. Only if the string is truncated, an ellipsis (or something else set with third argument) is appended to the string.

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

Indents a multiline text from the left. Second argument sets how many indentation chars should be used, while the indent itself is the third argument (*tab* by default).

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


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

Pads a UTF-8 string to given length by prepending the `$pad` string to the beginning.

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


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

Pads UTF-8 string to given length by appending the `$pad` string to the end.

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


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

Returns a part of UTF-8 string specified by starting position `$start` and length `$length`. If `$start` is negative, the returned string will start at the `$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]
------------------------------------

Reverses UTF-8 string.

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


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

Returns number of characters (not bytes) in UTF-8 string.

That is the number of Unicode code points which may differ from the number of graphemes.

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


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

Checks if `$haystack` string begins with `$needle`.

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


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

Checks if `$haystack` string end with `$needle`.

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


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

Checks if `$haystack` string contains `$needle`.

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


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

Compares two UTF-8 strings or their parts, without taking character case into account. If `$length` is null, whole strings are compared, if it is negative, the corresponding number of characters from the end of the strings is compared, otherwise the appropriate number of characters from the beginning is compared.

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

Finds the common prefix of strings or returns empty string if the prefix was not found.

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

Returns part of `$haystack` before `$nth` occurence of `$needle` or returns `null` if the needle was not found. Negative value means searching from the end.

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

Returns part of `$haystack` after `$nth` occurence of `$needle` or returns `null` if the `$needle` was not found. Negative value of `$nth` means searching from the end.

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

Returns position in characters of `$nth` occurence of `$needle` in `$haystack` or `null` if the `$needle` was not found. Negative value of `$nth` means searching from the end.

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


Encoding
========


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

Removes all invalid UTF-8 characters from a string.

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


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

Checks if the string is valid in UTF-8 encoding.

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


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

Converts UTF-8 string to ASCII, ie removes diacritics etc.

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

.[caution]
Requires PHP extension `intl`.


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

Returns a specific character in UTF-8 from code point (number in range 0x0000..D7FF or 0xE000..10FFFF).

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


Regular Expressions
===================

The Strings class provides functions for working with regular expressions. Unlike native PHP functions, they have a more understandable API, and most importantly, error detection. Any compilation or expression processing error will throw a `Nette\RegexpException` exception.


split(string $subject, string $pattern, int $flags=null): array .[method]
-------------------------------------------------------------------------

Divides the string into arrays according to the regular expression. Expressions in parentheses will be captured and returned as well.

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

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

If `$limit` is specified, only substrings up to the limit will be returned and the rest of the string will be placed in the last element. A limit of -1 or 0 means no limit.

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


match(string $subject, string $pattern, int $flags=null, int $offset=0): ?array .[method]
-----------------------------------------------------------------------------------------

Searches the string for the part matching the regular expression and returns an array with the found expression and individual subexpressions, or `null`.

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

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

The `$flag` can be set to the same flags as the [php:preg_match] function.

The `$offset` parameter can be used to specify the position to start the search from (in bytes).


matchAll(string $subject, string $pattern, int $flags=null, int $offset=0): array .[method]
-------------------------------------------------------------------------------------------

Searches the string for all occurrences matching the regular expression and returns an array of arrays containing the found expression and each subexpression.

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

The `$flag` can be set to the same flags as the [php:preg_match_all] function, except that the `PREG_SET_ORDER` flag is the default value.

The `$offset` parameter can be used to specify the position to start the search from (in bytes).


replace(string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1): string .[method]
-----------------------------------------------------------------------------------------------------------------

Replaces all occurrences matching the regular expression. The `$replacement` is either a replacement string mask or a callback.

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

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

The function also allows multiple replacements by passing an array of the form `pattern => replacement` in the second parameter:

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

The `$limit` parameter limits the number of substitutions. Limit -1 means no limit.