Funkcije nizov
**************

.[perex]
[api:Nette\Utils\Strings] je statični razred, ki vsebuje številne uporabne funkcije za delo z nizi, kodiranimi v zapisu UTF-8.


Namestitev:

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

Vsi primeri predpostavljajo, da je definiran naslednji vzdevek razreda:

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


Velikost črke .[#toc-letter-case]
=================================

Te funkcije zahtevajo razširitev PHP `mbstring`.


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

Pretvori vse znake niza UTF-8 v male črke.

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


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

Pretvori vse znake niza UTF-8 v velike črke.

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


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

Prvi znak niza UTF-8 pretvori v velike črke, drugi znaki ostanejo nespremenjeni.

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


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

Prvi znak niza UTF-8 pretvori v male črke, drugi znaki pa ostanejo nespremenjeni.

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


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

Pretvori prvi znak vsake besede v nizu UTF-8 v velike črke, druge pa v male črke.

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


Urejanje niza .[#toc-editing-a-string]
======================================


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

Odstrani kontrolne znake, normalizira prelome vrstic na `\n`, odstrani vodilne in zadnje prazne vrstice, obreže končne presledke v vrsticah, normalizira UTF-8 na normalno obliko NFC.


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

Pretvarja prelome vrstic v `\n`, ki se uporabljajo v sistemih Unix. Prelomi vrstic so: `\n`, `\r`, `\r\n`, U+2028 ločilo vrstic, U+2029 ločilo odstavkov.

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


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

Pretvarja prelome vrstic v znake, značilne za trenutno platformo, tj. `\r\n` v operacijskem sistemu Windows in `\n` drugje. Prekinitve vrstic so `\n`, `\r`, `\r\n`, U+2028 ločilo vrstic, U+2029 ločilo odstavkov.

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


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

Spremeni niz UTF-8 v obliko, ki se uporablja v naslovu URL, tj. odstrani diakritiko in vse znake razen črk angleške abecede in številk nadomesti s pomišljajem.

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

Ohranijo se lahko tudi drugi znaki, vendar jih je treba posredovati kot drugi argument.

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

Tretji argument lahko prepreči pretvorbo niza v male črke.

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

.[caution]
Zahteva razširitev PHP `intl`.


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

Odstrani vse leve in desne presledke (ali znake, posredovane kot drugi argument) iz niza, kodiranega v UTF-8.

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


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

Skrajša niz UTF-8 na določeno največjo dolžino, pri čemer poskuša preprečiti deljenje celih besed. Samo če je niz skrajšan, se nizu doda elipsa (ali kaj drugega, nastavljenega s tretjim argumentom).

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

Odmik večvrstičnega besedila z leve strani. Drugi argument določa, koliko znakov za alinejo naj se uporabi, medtem ko je sama alineja tretji argument (privzeto *tab*).

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


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

Izpolni niz UTF-8 na določeno dolžino tako, da na začetek doda niz `$pad`.

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


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

Podloži niz UTF-8 na določeno dolžino tako, da na konec doda niz `$pad`.

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


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

Vrne del niza UTF-8, ki ga določata začetni položaj `$start` in dolžina `$length`. Če je `$start` negativen, se vrnjen niz začne pri `$start`'-tem znaku od konca niza.

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

Obrne niz UTF-8.

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


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

Vrne število znakov (ne bajtov) v nizu UTF-8.

To je število kodnih točk Unicode, ki se lahko razlikuje od števila grafemov.

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


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

Preveri, ali se niz `$haystack` začne z `$needle`.

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

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


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

Preveri, ali se niz `$haystack` konča s `$needle`.

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

.[note]
Uporabite domači `str_ends_with()`:https://www.php.net/manual/en/function.str-ends-with.php.


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

Preveri, ali niz `$haystack` vsebuje `$needle`.

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

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


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

Primerja dva niza UTF-8 ali njune dele, pri čemer ne upošteva velikosti znakov. Če je `$length` nič, se primerjajo celi nizi, če je negativen, se primerja ustrezno število znakov od konca niza, sicer se primerja ustrezno število znakov od začetka.

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

Poišče skupno predpono nizov ali vrne prazen niz, če predpona ni bila najdena.

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

Vrne del `$haystack` pred pojavom `$nth` `$needle` ali vrne `null`, če igla ni bila najdena. Negativna vrednost pomeni iskanje od konca.

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

Vrne del `$haystack` po `$nth` pojavu `$needle` ali vrne `null`, če `$needle` ni bil najden. Negativna vrednost `$nth` pomeni iskanje od konca.

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

Vrne položaj v znakih `$nth` pojavljanja `$needle` v `$haystack` ali `null`, če `$needle` ni bil najden. Negativna vrednost `$nth` pomeni iskanje od konca.

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


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


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

Iz niza odstrani vse neveljavne znake UTF-8.

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


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

Preveri, ali je niz veljaven v kodiranju UTF-8.

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

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


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

Pretvori niz UTF-8 v ASCII, tj. odstrani diakritiko itd.

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

.[caution]
Zahteva razširitev PHP `intl`.


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

Vrne določen znak v UTF-8 iz kodne točke (številka v območju 0x0000..D7FF ali 0xE000..10FFFF).

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


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

Vrne kodno točko določenega znaka v UTF-8 (število v območju 0x0000..D7FF ali 0xE000..10FFFF).

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


Redni izrazi .[#toc-regular-expressions]
========================================

Razred Strings ponuja funkcije za delo z regularnimi izrazi. Za razliko od izvornih funkcij PHP imajo razumljivejši API, boljšo podporo Unicode in, kar je najpomembneje, zaznavanje napak. Vsaka napaka pri sestavljanju ali obdelavi izraza vrže izjemo `Nette\RegexpException`.


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

Razdeli niz v polja v skladu z regularnim izrazom. Zajeti in vrnjeni bodo tudi izrazi v oklepajih.

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

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

Če je `$skipEmpty` `true` , bodo vrnjeni samo neprazni elementi:

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

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

Če je naveden `$limit`, bodo vrnjeni samo podrezi do omejitve, preostanek niza pa bo umeščen v zadnji element. Omejitev -1 ali 0 pomeni, da omejitve ni.

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

Če je `$utf8` `true` , se vrednotenje preklopi v način Unicode. To je podobno, kot če bi določili modifikator `u`.

Če je `$captureOffset` `true` , se za vsako pojavljeno ujemanje vrne tudi njegov položaj v nizu (v bajtih; v znakih, če je nastavljen `$utf8` ). To spremeni vrnjeno vrednost v polje, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegovega položaja.

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

Preišče niz za del, ki ustreza regularnemu izrazu, in vrne polje z najdenim izrazom in posameznimi podizrazi ali `null`.

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

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

Če je `$unmatchedAsNull` `true` , se neskladni podvzorci vrnejo kot nič, sicer se vrnejo kot prazen niz ali se ne vrnejo:

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

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

Če je `$utf8` `true` , se vrednotenje preklopi na način Unicode. To je podobno, kot če bi določili modifikator `u`:

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

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

S parametrom `$offset` lahko določimo položaj, s katerega se začne iskanje (v bajtih; v znakih, če je nastavljen `$utf8` ).

Če je `$captureOffset` `true` , bo za vsako najdeno ujemanje vrnjen tudi njegov položaj v nizu (v bajtih; v znakih, če je nastavljen `$utf8` ). To spremeni vrnjeno vrednost v polje, kjer je vsak element par, sestavljen iz ustreznega niza in njegovega odmika:

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

V nizu poišče vse pojavitve, ki ustrezajo regularnemu izrazu, in vrne polje polj, ki vsebuje najden izraz in vsak podizraz.

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

Če je `$patternOrder` `true` , se struktura rezultatov spremeni tako, da je prva postavka polje popolnih ujemanj vzorca, druga je polje nizov, ki ustrezajo prvemu podvzorcu v oklepaju, in tako naprej:

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

Če je `$unmatchedAsNull` `true` , se neskladni podvzorci vrnejo kot nič, sicer se vrnejo kot prazen niz ali se ne vrnejo:

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

Če je `$utf8` `true` , se vrednotenje preklopi na način Unicode. To je podobno, kot če bi določili modifikator `u`:

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

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

S parametrom `$offset` lahko določimo položaj, s katerega se začne iskanje (v bajtih; v znakih, če je nastavljen `$utf8` ).

Če je `$captureOffset` `true` , bo za vsako najdeno ujemanje vrnjen tudi njegov položaj v nizu (v bajtih; v znakih, če je nastavljen `$utf8` ). To spremeni vrnjeno vrednost v polje, kjer je vsak element par, sestavljen iz ustreznega niza in njegovega položaja:

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

Če je `$lazy` `true` , funkcija namesto polja vrne `Generator`, kar pri delu z velikimi nizi zagotavlja znatne prednosti pri delovanju. Generator omogoča postopno iskanje ujemanj, namesto da bi obdelal celoten niz naenkrat. To omogoča učinkovito obdelavo izjemno velikih vhodnih besedil. Poleg tega lahko obdelavo kadar koli prekinete, če najdete želeno ujemanje, s čimer prihranite računski čas.

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

Zamenja vse pojavitve, ki ustrezajo regularnemu izrazu. `$replacement` je bodisi maska nadomestnega niza bodisi povratni klic.

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

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

Funkcija omogoča tudi večkratno zamenjavo, če v drugem parametru posreduje polje v obliki `pattern => replacement`:

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

Parameter `$limit` omejuje število zamenjav. Omejitev -1 pomeni, da omejitve ni.

Če je `$utf8` `true` , se vrednotenje preklopi v način Unicode. To je podobno, kot če bi določili modifikator `u`.

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

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

Če je `$captureOffset` `true` , se povratnemu klicu za vsako nastalo ujemanje posreduje tudi njegov položaj v nizu (v bajtih; v znakih, če je nastavljen `$utf8` ). To spremeni obliko posredovanega polja, v katerem je vsak element par, sestavljen iz ujemajočega se niza in njegovega položaja.

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

Če je `$unmatchedAsNull` `true` , se neusklajeni podvzorci posredujejo povratnemu klicu kot nič, sicer se posredujejo kot prazen niz ali pa se ne posredujejo:

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