Nette Documentation Preview

syntax 
Delo z nizi
***********

.[perex]
[api:Nette\Utils\Strings] je statični razred z uporabnimi funkcijami za delo z nizi, pretežno v kodiranju UTF-8.


Namestitev:

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

Vsi primeri predpostavljajo ustvarjen alias:

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


Spreminjanje velikosti črk
==========================

Te funkcije zahtevajo PHP razširitev `mbstring`.


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

Pretvori UTF-8 niz v male črke.

```php
Strings::lower('Dobrý den'); // 'dobrý den'
```


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

Pretvori UTF-8 niz v velike črke.

```php
Strings::upper('Dobrý den'); // 'DOBRÝ DEN'
```


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

Pretvori prvo črko UTF-8 niza v veliko, ostalih ne spreminja.

```php
Strings::firstUpper('dobrý den'); // 'Dobrý den'
```


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

Pretvori prvo črko UTF-8 niza v malo, ostalih ne spreminja.

```php
Strings::firstLower('Dobrý den'); // 'dobrý den'
```


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

Pretvori prvo črko vsake besede v UTF-8 nizu v veliko, ostale v male.

```php
Strings::capitalize('Dobrý den'); // 'Dobrý Den'
```


Urejanje niza
=============


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

Odstrani kontrolne znake, normalizira konce vrstic na `\n`, obreže začetne in končne prazne vrstice, obreže desne presledke v vrsticah, normalizira UTF-8 v normalno obliko NFC.


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

Pretvori konce vrstic v `\n`, ki se uporablja v unix sistemih. Konci vrstic so: `\n`, `\r`, `\r\n`, U+2028 line separator, U+2029 paragraph separator.

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


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

Pretvori konce vrstic v znake, specifične za trenutno platformo, tj. `\r\n` na Windows in `\n` drugje. Konci vrstic so: `\n`, `\r`, `\r\n`, U+2028 line separator, U+2029 paragraph separator.

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


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

Uredi UTF-8 niz v obliko, ki se uporablja v URL-jih, tj. odstrani diakritiko in vse znake, razen črk angleške abecede in številk, nadomesti z vezajem.

```php
Strings::webalize('náš produkt'); // 'nas-produkt'
```

Če naj se ohranijo tudi drugi znaki, jih lahko navedete v drugem parametru funkcije.

```php
Strings::webalize('10. obrázek_id', '._'); // '10.-obrazek_id'
```

S tretjim parametrom lahko preprečite pretvorbo v male črke.

```php
Strings::webalize('Dobrý den', null, false); // 'Dobry-den'
```

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


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

Obreže presledke (ali druge znake, določene z drugim parametrom) z začetka in konca UTF-8 niza.

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


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

Obreže UTF-8 niz na navedeno največjo dolžino, pri čemer poskuša ohraniti cele besede. Če pride do skrajšanja niza, na konec doda tri pike (lahko spremenite s tretjim parametrom).

```php
$text = 'Povejte, kako ste?'; // Povejte, kako ste?
Strings::truncate($text, 5);       // 'Povej…'
Strings::truncate($text, 20);      // 'Povejte, kako se…'
Strings::truncate($text, 30);      // 'Povejte, kako ste?'
Strings::truncate($text, 20, '~'); // 'Povejte, kako se~'
```


indent(string $s, int $level=1, string $indentationChar=`"\t"`): string .[method]
---------------------------------------------------------------------------------

Zamakne večvrstično besedilo z leve. Število zamikov določa drugi parameter, s čim zamakniti pa tretji parameter (privzeta vrednost je tabulator).

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


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

Dopolni UTF-8 niz do podane dolžine s ponavljanjem niza `$pad` z leve.

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


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

Dopolni UTF-8 niz do podane dolžine s ponavljanjem niza `$pad` z desne.

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


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

Vrne del UTF-8 niza `$s`, določen z začetno pozicijo `$start` in dolžino `$length`. Če je `$start` negativen, se bo vrnjeni niz začel z znakom -`$start` od konca.

```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 UTF-8 niz.

```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 razlikujejo od števila grafemov.

```php
Strings::length('Nette');   // 5
Strings::length('červená'); // 7
```


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

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

```php
$haystack = 'Začenja se'; // Začenja se
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true
```

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


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

Ugotovi, ali se niz `$haystack` konča z nizom `$needle`.

```php
$haystack = 'Končuje se'; // Končuje se
$needle = 'se';
Strings::endsWith($haystack, $needle); // true
```

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


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

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

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

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


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

Primerjava dveh UTF-8 nizov ali njunih delov ne glede na velikost črk. Če `$length` vsebuje null, se primerjata cela niza, če je negativen, se primerja ustrezno število znakov od konca nizov, sicer se primerja ustrezno število znakov od začetka.

```php
Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - ujemanje prvih 2 znakov
Strings::compare('Nette', 'Latte', -2); // true - ujemanje zadnjih 2 znakov
```


findPrefix(...$strings): string .[method]
-----------------------------------------

Najde skupni začetek nizov. Ali vrne prazen niz, če skupna 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 niza `$haystack` pred n-tim `$nth` pojavom niza `$needle`. Ali `null`, če `$needle` ni bil najden. Pri negativni vrednosti `$nth` se išče od konca niza.

```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 niza `$haystack` po n-tem `$nth` pojavu niza `$needle`. Ali `null`, če `$needle` ni bil najden. Pri negativni vrednosti `$nth` se išče od konca niza.

```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 pozicijo v znakih n-tega `$nth` pojava niza `$needle` v nizu `$haystack`. Ali `null`, če `$needle` ni bil najden. Pri negativni vrednosti `$nth` se išče od konca niza.

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


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

Odstrani iz niza neveljavne UTF-8 znake.

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


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

Ugotovi, ali gre za veljaven UTF-8 niz.

```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 PHP razširitev `intl`.


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

Vrne specifičen znak v UTF-8 iz kodne točke (število v obsegu 0x0000..D7FF in 0xE000..10FFFF).

```php
Strings::chr(0xA9); // '©' v kodiranju UTF-8
```


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

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

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


Regularni izrazi
================

Razred Strings ponuja funkcije za delo z regularnimi izrazi. V nasprotju z izvornimi PHP funkcijami imajo bolj razumljiv API, boljšo podporo za Unicode in predvsem zaznavanje napak. Vsaka napaka pri prevajanju 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 polje glede na regularni izraz. Izrazi v oklepajih bodo zajeti in vrnjeni tudi.

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

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

Če je `$skipEmpty` `true`, bodo vrnjene samo neprazne postavke:

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

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

Če je podan `$limit`, bodo vrnjeni samo podnizi do limita, preostanek niza pa bo umeščen v zadnji element. Limit -1 ali 0 pomeni brez omejitve.

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

Če je `$utf8` `true`, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator `u`.

Če je `$captureOffset` `true`, bo za vsako pojavljajočo se ujemanje vrnjena tudi njena pozicija v nizu (v bajtih; če je nastavljeno `$utf8`, pa v znakih). S tem se spremeni vrnjena vrednost v polje, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegove pozicije.

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

Išče v nizu 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`, so nezajeti podvzorci vrnjeni kot null; sicer so vrnjeni kot prazen niz ali pa niso vrnjeni:

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

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

Če je `$utf8` `true`, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator `u`:

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

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

Parameter `$offset` lahko uporabite za določitev pozicije, od katere naj se začne iskanje (v bajtih; če je nastavljeno `$utf8`, pa v znakih).

Če je `$captureOffset` `true`, bo za vsako pojavljajočo se ujemanje vrnjena tudi njena pozicija v nizu (v bajtih; če je nastavljeno `$utf8`, pa v znakih). S tem se spremeni vrnjena vrednost v polje, kjer je vsak element par, sestavljen iz ujemajočega se 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]
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Išče v nizu vse pojavitve, ki ustrezajo regularnemu izrazu, in vrne polje polj z najdenim izrazom in posameznimi podizrazi.

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

Če je `$patternOrder` `true`, se struktura rezultatov spremeni tako, da je v prvi postavki polje popolnih ujemanj vzorca, v drugi 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`, so nezajeti podvzorci vrnjeni kot null; sicer so vrnjeni kot prazen niz ali pa niso vrnjeni:

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

Če je `$utf8` `true`, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator `u`:

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

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

Parameter `$offset` lahko uporabite za določitev pozicije, od katere naj se začne iskanje (v bajtih; če je nastavljeno `$utf8`, pa v znakih).

Če je `$captureOffset` `true`, bo za vsako pojavljajočo se ujemanje vrnjena tudi njena pozicija v nizu (v bajtih; če je nastavljeno `$utf8`, pa v znakih). S tem se spremeni vrnjena vrednost v polje, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegove pozicije:

```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 vrne `Generator` namesto polja, kar prinaša znatne prednosti pri zmogljivosti pri delu z velikimi nizi. Generator omogoča postopno iskanje ujemanj, namesto celotnega niza naenkrat. To omogoča učinkovito delo tudi z izjemno velikimi vhodnimi besedili. Poleg tega lahko kadar koli prekinete obdelavo, če najdete iskano ujemanje, kar prihrani računski čas.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
	echo "Najdeno: $match[0]\n";
	// Obdelavo je mogoče kadar koli prekiniti
}
```


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

Nadomešča vse pojavitve, ki ustrezajo regularnemu izrazu. `$replacement` je bodisi maska nadomestnega niza ali povratni klic (callback).

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

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

Funkcija omogoča tudi izvedbo več zamenjav tako, da v drugem parametru posredujemo polje v obliki `pattern => replacement`:

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

Parameter `$limit` omejuje število izvedenih zamenjav. Limit -1 pomeni brez omejitve.

Če je `$utf8` `true`, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator `u`.

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

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

Če je `$captureOffset` `true`, bo za vsako pojavljajočo se ujemanje povratnemu klicu (callbacku) posredovana tudi njena pozicija v nizu (v bajtih; če je nastavljeno `$utf8`, pa v znakih). S tem se spremeni oblika posredovanega polja, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegove pozicije.

```php
Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// izpiše [['lut', 2]] in [['k', 8]]

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// izpiše [['žlutý', 0]] in [['kůň', 6]]
```

Če je `$unmatchedAsNull` `true`, so nezajeti podvzorci posredovani povratnemu klicu (callbacku) kot null; sicer so posredovani kot prazen niz ali pa niso posredovani:

```php
Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// izpiše ['ac', 'a', '', 'c']

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// izpiše ['ac', 'a', null, 'c']
```

Delo z nizi

Nette\Utils\Strings je statični razred z uporabnimi funkcijami za delo z nizi, pretežno v kodiranju UTF-8.

Namestitev:

composer require nette/utils

Vsi primeri predpostavljajo ustvarjen alias:

use Nette\Utils\Strings;

Spreminjanje velikosti črk

Te funkcije zahtevajo PHP razširitev mbstring.

lower(string $s): string

Pretvori UTF-8 niz v male črke.

Strings::lower('Dobrý den'); // 'dobrý den'

upper(string $s): string

Pretvori UTF-8 niz v velike črke.

Strings::upper('Dobrý den'); // 'DOBRÝ DEN'

firstUpper(string $s): string

Pretvori prvo črko UTF-8 niza v veliko, ostalih ne spreminja.

Strings::firstUpper('dobrý den'); // 'Dobrý den'

firstLower(string $s): string

Pretvori prvo črko UTF-8 niza v malo, ostalih ne spreminja.

Strings::firstLower('Dobrý den'); // 'dobrý den'

capitalize(string $s): string

Pretvori prvo črko vsake besede v UTF-8 nizu v veliko, ostale v male.

Strings::capitalize('Dobrý den'); // 'Dobrý Den'

Urejanje niza

normalize(string $s): string

Odstrani kontrolne znake, normalizira konce vrstic na \n, obreže začetne in končne prazne vrstice, obreže desne presledke v vrsticah, normalizira UTF-8 v normalno obliko NFC.

unixNewLines(string $s): string

Pretvori konce vrstic v \n, ki se uporablja v unix sistemih. Konci vrstic so: \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

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

platformNewLines(string $s): string

Pretvori konce vrstic v znake, specifične za trenutno platformo, tj. \r\n na Windows in \n drugje. Konci vrstic so: \n, \r, \r\n, U+2028 line separator, U+2029 paragraph separator.

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

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

Uredi UTF-8 niz v obliko, ki se uporablja v URL-jih, tj. odstrani diakritiko in vse znake, razen črk angleške abecede in številk, nadomesti z vezajem.

Strings::webalize('náš produkt'); // 'nas-produkt'

Če naj se ohranijo tudi drugi znaki, jih lahko navedete v drugem parametru funkcije.

Strings::webalize('10. obrázek_id', '._'); // '10.-obrazek_id'

S tretjim parametrom lahko preprečite pretvorbo v male črke.

Strings::webalize('Dobrý den', null, false); // 'Dobry-den'

Zahteva PHP razširitev intl.

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

Obreže presledke (ali druge znake, določene z drugim parametrom) z začetka in konca UTF-8 niza.

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

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

Obreže UTF-8 niz na navedeno največjo dolžino, pri čemer poskuša ohraniti cele besede. Če pride do skrajšanja niza, na konec doda tri pike (lahko spremenite s tretjim parametrom).

$text = 'Povejte, kako ste?'; // Povejte, kako ste?
Strings::truncate($text, 5);       // 'Povej…'
Strings::truncate($text, 20);      // 'Povejte, kako se…'
Strings::truncate($text, 30);      // 'Povejte, kako ste?'
Strings::truncate($text, 20, '~'); // 'Povejte, kako se~'

indent(string $s, int $level=1, string $indentationChar=`"\t"`): string

Zamakne večvrstično besedilo z leve. Število zamikov določa drugi parameter, s čim zamakniti pa tretji parameter (privzeta vrednost je tabulator).

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

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

Dopolni UTF-8 niz do podane dolžine s ponavljanjem niza $pad z leve.

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

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

Dopolni UTF-8 niz do podane dolžine s ponavljanjem niza $pad z desne.

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

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

Vrne del UTF-8 niza $s, določen z začetno pozicijo $start in dolžino $length. Če je $start negativen, se bo vrnjeni niz začel z znakom -$start od konca.

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

reverse(string $s): string

Obrne UTF-8 niz.

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

length(string $s): int

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

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

Strings::length('Nette');   // 5
Strings::length('červená'); // 7

startsWith(string $haystack, string $needle): bool

Ugotovi, ali se niz $haystack začne z nizom $needle.

$haystack = 'Začenja se'; // Začenja se
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true

Uporabljajte izvorno str_starts_with().

endsWith(string $haystack, string $needle): bool

Ugotovi, ali se niz $haystack konča z nizom $needle.

$haystack = 'Končuje se'; // Končuje se
$needle = 'se';
Strings::endsWith($haystack, $needle); // true

Uporabljajte izvorno str_ends_with().

contains(string $haystack, string $needle): bool

Ugotovi, ali niz $haystack vsebuje $needle.

$haystack = 'Predavalnica'; // Predavalnica
$needle = 'dava';
Strings::contains($haystack, $needle); // true

Uporabljajte izvorno str_contains().

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

Primerjava dveh UTF-8 nizov ali njunih delov ne glede na velikost črk. Če $length vsebuje null, se primerjata cela niza, če je negativen, se primerja ustrezno število znakov od konca nizov, sicer se primerja ustrezno število znakov od začetka.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - ujemanje prvih 2 znakov
Strings::compare('Nette', 'Latte', -2); // true - ujemanje zadnjih 2 znakov

findPrefix(…$strings): string

Najde skupni začetek nizov. Ali vrne prazen niz, če skupna predpona ni bila najdena.

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

Vrne del niza $haystack pred n-tim $nth pojavom niza $needle. Ali null, če $needle ni bil najden. Pri negativni vrednosti $nth se išče od konca niza.

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

Vrne del niza $haystack po n-tem $nth pojavu niza $needle. Ali null, če $needle ni bil najden. Pri negativni vrednosti $nth se išče od konca niza.

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

Vrne pozicijo v znakih n-tega $nth pojava niza $needle v nizu $haystack. Ali null, če $needle ni bil najden. Pri negativni vrednosti $nth se išče od konca niza.

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

Kodiranje

fixEncoding(string $s): string

Odstrani iz niza neveljavne UTF-8 znake.

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

checkEncoding(string $s): bool

Ugotovi, ali gre za veljaven UTF-8 niz.

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

Uporabite Nette\Utils\Validator::isUnicode().

toAscii(string $s): string

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

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

Zahteva PHP razširitev intl.

chr(int $code): string

Vrne specifičen znak v UTF-8 iz kodne točke (število v obsegu 0×0000..D7FF in 0xE000..10FFFF).

Strings::chr(0xA9); // '©' v kodiranju UTF-8

ord(string $char): int

Vrne kodno točko določenega znaka v UTF-8 (število v obsegu 0×0000..D7FF ali 0xE000..10FFFF).

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

Regularni izrazi

Razred Strings ponuja funkcije za delo z regularnimi izrazi. V nasprotju z izvornimi PHP funkcijami imajo bolj razumljiv API, boljšo podporo za Unicode in predvsem zaznavanje napak. Vsaka napaka pri prevajanju 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

Razdeli niz v polje glede na regularni izraz. Izrazi v oklepajih bodo zajeti in vrnjeni tudi.

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

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

Če je $skipEmpty true, bodo vrnjene samo neprazne postavke:

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

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

Če je podan $limit, bodo vrnjeni samo podnizi do limita, preostanek niza pa bo umeščen v zadnji element. Limit –1 ali 0 pomeni brez omejitve.

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

Če je $utf8 true, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator u.

Če je $captureOffset true, bo za vsako pojavljajočo se ujemanje vrnjena tudi njena pozicija v nizu (v bajtih; če je nastavljeno $utf8, pa v znakih). S tem se spremeni vrnjena vrednost v polje, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegove pozicije.

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

Išče v nizu del, ki ustreza regularnemu izrazu, in vrne polje z najdenim izrazom in posameznimi podizrazi, ali null.

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

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

Če je $unmatchedAsNull true, so nezajeti podvzorci vrnjeni kot null; sicer so vrnjeni kot prazen niz ali pa niso vrnjeni:

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

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

Če je $utf8 true, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator u:

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

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

Parameter $offset lahko uporabite za določitev pozicije, od katere naj se začne iskanje (v bajtih; če je nastavljeno $utf8, pa v znakih).

Če je $captureOffset true, bo za vsako pojavljajočo se ujemanje vrnjena tudi njena pozicija v nizu (v bajtih; če je nastavljeno $utf8, pa v znakih). S tem se spremeni vrnjena vrednost v polje, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegovega odmika:

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

Išče v nizu vse pojavitve, ki ustrezajo regularnemu izrazu, in vrne polje polj z najdenim izrazom in posameznimi podizrazi.

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

Če je $patternOrder true, se struktura rezultatov spremeni tako, da je v prvi postavki polje popolnih ujemanj vzorca, v drugi je polje nizov, ki ustrezajo prvemu podvzorcu v oklepaju, in tako naprej:

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

Če je $unmatchedAsNull true, so nezajeti podvzorci vrnjeni kot null; sicer so vrnjeni kot prazen niz ali pa niso vrnjeni:

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

Če je $utf8 true, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator u:

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

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

Parameter $offset lahko uporabite za določitev pozicije, od katere naj se začne iskanje (v bajtih; če je nastavljeno $utf8, pa v znakih).

Če je $captureOffset true, bo za vsako pojavljajočo se ujemanje vrnjena tudi njena pozicija v nizu (v bajtih; če je nastavljeno $utf8, pa v znakih). S tem se spremeni vrnjena vrednost v polje, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegove pozicije:

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 vrne Generator namesto polja, kar prinaša znatne prednosti pri zmogljivosti pri delu z velikimi nizi. Generator omogoča postopno iskanje ujemanj, namesto celotnega niza naenkrat. To omogoča učinkovito delo tudi z izjemno velikimi vhodnimi besedili. Poleg tega lahko kadar koli prekinete obdelavo, če najdete iskano ujemanje, kar prihrani računski čas.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
	echo "Najdeno: $match[0]\n";
	// Obdelavo je mogoče kadar koli prekiniti
}

replace(string $subject, string|array $pattern, string|callable $replacement='', int $limit=-1, bool $captureOffset=false, bool $unmatchedAsNull=false, bool $utf8=false): string

Nadomešča vse pojavitve, ki ustrezajo regularnemu izrazu. $replacement je bodisi maska nadomestnega niza ali povratni klic (callback).

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

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

Funkcija omogoča tudi izvedbo več zamenjav tako, da v drugem parametru posredujemo polje v obliki pattern => replacement:

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

Parameter $limit omejuje število izvedenih zamenjav. Limit –1 pomeni brez omejitve.

Če je $utf8 true, se preklopi vrednotenje v Unicode način. Podobno kot če navedete modifikator u.

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

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

Če je $captureOffset true, bo za vsako pojavljajočo se ujemanje povratnemu klicu (callbacku) posredovana tudi njena pozicija v nizu (v bajtih; če je nastavljeno $utf8, pa v znakih). S tem se spremeni oblika posredovanega polja, kjer je vsak element par, sestavljen iz ujemajočega se niza in njegove pozicije.

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
);
// izpiše [['lut', 2]] in [['k', 8]]

Strings::replace(
	'žlutý kůň',
	'~\w+~',
	function (array $m) { dump($m); return ''; },
	captureOffset: true,
	utf8: true,
);
// izpiše [['žlutý', 0]] in [['kůň', 6]]

Če je $unmatchedAsNull true, so nezajeti podvzorci posredovani povratnemu klicu (callbacku) kot null; sicer so posredovani kot prazen niz ali pa niso posredovani:

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// izpiše ['ac', 'a', '', 'c']

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// izpiše ['ac', 'a', null, 'c']