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