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 0×E000..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 0×E000..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): array
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]],
] */
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']