Funkcije nizov

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

Namestitev:

composer require nette/utils

Vsi primeri predpostavljajo, da je definiran naslednji vzdevek razreda:

use Nette\Utils\Strings;

Velikost črke

Te funkcije zahtevajo razširitev PHP mbstring.

lower (string $s): string

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

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

upper (string $s): string

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

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

firstUpper (string $s): string

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

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

firstLower (string $s): string

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

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

capitalize (string $s): string

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

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

Urejanje niza

normalize (string $s): string

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

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.

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

platformNewLines (string $s): string

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.

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

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

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.

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

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

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

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

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

Zahteva razširitev PHP intl.

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

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

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

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

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

$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

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

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

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

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

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

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

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

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

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

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.

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

reverse (string $s): string

Obrne niz UTF-8.

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

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

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

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

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

Uporabi izvirno str_starts_with().

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

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

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

Uporabite domači str_ends_with().

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

Preveri, ali niz $haystack vsebuje $needle.

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

Uporabite izvirni str_contains().

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

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.

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

Poišče skupno predpono nizov ali vrne prazen niz, če 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 $haystack pred pojavom $nth $needle ali vrne null, če igla ni bila najdena. Negativna vrednost pomeni iskanje od konca.

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 $haystack po $nth pojavu $needle ali vrne null, če $needle ni bil najden. Negativna vrednost $nth pomeni iskanje od konca.

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 položaj v znakih $nth pojavljanja $needle v $haystack ali null, če $needle ni bil najden. Negativna vrednost $nth pomeni iskanje od konca.

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

Iz niza odstrani vse neveljavne znake UTF-8.

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

checkEncoding (string $s): bool

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

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

chr (int $code): string

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

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

ord (string $char): int

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

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

Redni izrazi

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

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

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

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

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

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.

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.

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

Preišče niz za 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 , se neskladni podvzorci vrnejo kot nič, sicer se vrnejo kot prazen niz ali se ne vrnejo:

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:

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:

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

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

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:

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:

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:

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:

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.

$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

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

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:

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.

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.

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:

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