Karakter Dizileriyle Çalışma

Nette\Utils\Strings, çoğunlukla UTF-8 kodlamasındaki karakter dizileriyle çalışmak için yararlı fonksiyonlar içeren statik bir sınıftır.

Kurulum:

composer require nette/utils

Tüm örnekler, bir takma ad oluşturulduğunu varsayar:

use Nette\Utils\Strings;

Harf Büyüklüğünü Değiştirme

Bu fonksiyonlar PHP mbstring uzantısını gerektirir.

lower(string $s): string

Bir UTF-8 karakter dizisini küçük harfe dönüştürür.

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

upper(string $s): string

Bir UTF-8 karakter dizisini büyük harfe dönüştürür.

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

firstUpper(string $s): string

Bir UTF-8 karakter dizisinin ilk harfini büyük harfe dönüştürür, diğerlerini değiştirmez.

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

firstLower(string $s): string

Bir UTF-8 karakter dizisinin ilk harfini küçük harfe dönüştürür, diğerlerini değiştirmez.

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

capitalize(string $s): string

Bir UTF-8 karakter dizisindeki her kelimenin ilk harfini büyük harfe, diğerlerini küçük harfe dönüştürür.

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

Karakter Dizisini Düzenleme

normalize(string $s): string

Kontrol karakterlerini kaldırır, satır sonlarını \n olarak normalleştirir, baştaki ve sondaki boş satırları kırpar, satırlardaki sağdaki boşlukları kırpar, UTF-8'i normal NFC formuna normalleştirir.

unixNewLines(string $s): string

Satır sonlarını unix sistemlerinde kullanılan \n karakterine dönüştürür. Satır sonları şunlardır: \n, \r, \r\n, U+2028 satır ayırıcı, U+2029 paragraf ayırıcı.

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

platformNewLines(string $s): string

Satır sonlarını mevcut platforma özgü karakterlere dönüştürür, yani Windows'ta \r\n ve diğerlerinde \n. Satır sonları şunlardır: \n, \r, \r\n, U+2028 satır ayırıcı, U+2029 paragraf ayırıcı.

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

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

Bir UTF-8 karakter dizisini URL'lerde kullanılan forma dönüştürür, yani aksanları kaldırır ve İngiliz alfabesi harfleri ve rakamlar dışındaki tüm karakterleri tire ile değiştirir.

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

Başka karakterlerin de korunması gerekiyorsa, fonksiyonun ikinci parametresinde belirtilebilirler.

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

Üçüncü parametre ile küçük harfe dönüştürme engellenebilir.

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

PHP intl uzantısını gerektirir.

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

Bir UTF-8 karakter dizisinin başından ve sonundan boşlukları (veya ikinci parametre ile belirtilen diğer karakterleri) kırpar.

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

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

Bir UTF-8 karakter dizisini belirtilen maksimum uzunluğa kırpar, bu sırada tam kelimeleri korumaya çalışır. Karakter dizisi kısaltılırsa, sonuna üç nokta ekler (üçüncü parametre ile değiştirilebilir).

$text = 'Řekněte, jak se máte?';
Strings::truncate($text, 5);       // 'Řekn…'
Strings::truncate($text, 20);      // 'Řekněte, jak se…'
Strings::truncate($text, 30);      // 'Řekněte, jak se máte?'
Strings::truncate($text, 20, '~'); // 'Řekněte, jak se~'

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

Çok satırlı metni soldan girintiler. Girinti sayısı ikinci parametre ile, ne ile girintileneceği üçüncü parametre ile belirlenir (varsayılan değer tab karakteridir).

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

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

Bir UTF-8 karakter dizisini, $pad karakter dizisini soldan tekrarlayarak belirtilen uzunluğa tamamlar.

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

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

Bir UTF-8 karakter dizisini, $pad karakter dizisini sağdan tekrarlayarak belirtilen uzunluğa tamamlar.

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

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

$s UTF-8 karakter dizisinin, $start başlangıç konumu ve $length uzunluğu ile belirtilen bir bölümünü döndürür. $start negatif ise, döndürülen karakter dizisi sondan -$start karakteri ile başlar.

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

reverse(string $s): string

Bir UTF-8 karakter dizisini ters çevirir.

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

length(string $s): int

Bir UTF-8 karakter dizisindeki karakter sayısını (bayt sayısını değil) döndürür.

Bu, grafem sayısından farklı olabilen Unicode kod noktalarının sayısıdır.

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

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

$haystack karakter dizisinin $needle karakter dizisiyle başlayıp başlamadığını kontrol eder.

$haystack = 'Začíná';
$needle = 'Za';
Strings::startsWith($haystack, $needle); // true

Yerel str_starts_with() kullanın.

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

$haystack karakter dizisinin $needle karakter dizisiyle bitip bitmediğini kontrol eder.

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

Yerel str_ends_with() kullanın.

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

$haystack karakter dizisinin $needle içerip içermediğini kontrol eder.

$haystack = 'Posluchárna';
$needle = 'sluch';
Strings::contains($haystack, $needle); // true

Yerel str_contains() kullanın.

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

İki UTF-8 karakter dizisini veya bunların bölümlerini büyük/küçük harf duyarlılığı olmadan karşılaştırır. $length null içeriyorsa, tüm karakter dizileri karşılaştırılır, negatif ise, karakter dizilerinin sonundan ilgili sayıda karakter karşılaştırılır, aksi takdirde baştan ilgili sayıda karakter karşılaştırılır.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - ilk 2 karakter eşleşiyor
Strings::compare('Nette', 'Latte', -2); // true - son 2 karakter eşleşiyor

findPrefix(…$strings): string

Karakter dizilerinin ortak başlangıcını bulur. Veya ortak önek bulunamazsa boş bir karakter dizisi döndürür.

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

$haystack karakter dizisinin, $needle karakter dizisinin n'inci $nth oluşumundan önceki bölümünü döndürür. Veya $needle bulunamazsa null. $nth negatif bir değerse, karakter dizisinin sonundan aranır.

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

$haystack karakter dizisinin, $needle karakter dizisinin n'inci $nth oluşumundan sonraki bölümünü döndürür. Veya $needle bulunamazsa null. $nth negatif bir değerse, karakter dizisinin sonundan aranır.

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

$haystack karakter dizisindeki $needle karakter dizisinin n'inci $nth oluşumunun karakter cinsinden konumunu döndürür. Veya $needle bulunamazsa null. $nth negatif bir değerse, karakter dizisinin sonundan aranır.

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

Kodlama

fixEncoding(string $s): string

Karakter dizisinden geçersiz UTF-8 karakterlerini kaldırır.

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

checkEncoding(string $s): bool

Geçerli bir UTF-8 karakter dizisi olup olmadığını kontrol eder.

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

Nette\Utils\Validator::isUnicode() kullanın.

toAscii(string $s): string

Bir UTF-8 karakter dizisini ASCII'ye dönüştürür, yani aksanları vb. kaldırır.

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

PHP intl uzantısını gerektirir.

chr(int $code): string

Bir kod noktasından (0×0000..D7FF ve 0xE000..10FFFF aralığında bir sayı) belirli bir UTF-8 karakterini döndürür.

Strings::chr(0xA9); // UTF-8 kodlamasında '©'

ord(string $char): int

Belirli bir UTF-8 karakterinin kod noktasını döndürür (0×0000..D7FF veya 0xE000..10FFFF aralığında bir sayı).

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

Düzenli İfadeler

Strings sınıfı, düzenli ifadelerle çalışmak için fonksiyonlar sunar. Yerel PHP fonksiyonlarının aksine, daha anlaşılır bir API'ye, daha iyi Unicode desteğine ve hepsinden önemlisi hata tespitine sahiptirler. İfadenin derlenmesi veya işlenmesi sırasında herhangi bir hata Nette\RegexpException istisnası fırlatır.

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

Bir karakter dizisini düzenli bir ifadeye göre bir diziye böler. Parantez içindeki ifadeler de yakalanacak ve döndürülecektir.

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

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

$skipEmpty true ise, yalnızca boş olmayan öğeler döndürülür:

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

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

$limit belirtilmişse, yalnızca limite kadar olan alt diziler döndürülür ve karakter dizisinin geri kalanı son öğeye yerleştirilir. –1 veya 0 limiti kısıtlama olmadığı anlamına gelir.

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

$utf8 true ise, değerlendirme Unicode moduna geçer. u değiştiricisini belirtmişsiniz gibi.

$captureOffset true ise, her eşleşen oluşum için karakter dizisindeki konumu da döndürülür (bayt cinsinden; $utf8 ayarlanmışsa karakter cinsinden). Bu, dönüş değerini, her öğenin eşleşen karakter dizisi ve konumundan oluşan bir çift olduğu bir diziye değiştirir.

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

Bir karakter dizisinde düzenli bir ifadeye uyan bölümü arar ve bulunan ifade ve tek tek alt ifadelerle birlikte bir dizi veya null döndürür.

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

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

$unmatchedAsNull true ise, yakalanmayan alt desenler null olarak döndürülür; aksi takdirde boş bir karakter dizisi olarak döndürülür veya döndürülmez:

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

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

$utf8 true ise, değerlendirme Unicode moduna geçer. u değiştiricisini belirtmişsiniz gibi:

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

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

$offset parametresi, aramaya başlanacak konumu belirtmek için kullanılabilir (bayt cinsinden; $utf8 ayarlanmışsa karakter cinsinden).

$captureOffset true ise, her eşleşen oluşum için karakter dizisindeki konumu da döndürülür (bayt cinsinden; $utf8 ayarlanmışsa karakter cinsinden). Bu, dönüş değerini, her öğenin eşleşen karakter dizisi ve ofsetinden oluşan bir çift olduğu bir diziye değiştirir:

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

Bir karakter dizisindeki düzenli bir ifadeye uyan tüm oluşumları arar ve bulunan ifade ve tek tek alt ifadelerle birlikte bir dizi dizisi döndürür.

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

$patternOrder true ise, sonuçların yapısı değişir, öyle ki ilk öğe tam desen eşleşmeleri dizisidir, ikinci öğe parantez içindeki ilk alt desene karşılık gelen karakter dizileri dizisidir ve bu şekilde devam eder:

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

$unmatchedAsNull true ise, yakalanmayan alt desenler null olarak döndürülür; aksi takdirde boş bir karakter dizisi olarak döndürülür veya döndürülmez:

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

$utf8 true ise, değerlendirme Unicode moduna geçer. u değiştiricisini belirtmişsiniz gibi:

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

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

$offset parametresi, aramaya başlanacak konumu belirtmek için kullanılabilir (bayt cinsinden; $utf8 ayarlanmışsa karakter cinsinden).

$captureOffset true ise, her eşleşen oluşum için karakter dizisindeki konumu da döndürülür (bayt cinsinden; $utf8 ayarlanmışsa karakter cinsinden). Bu, dönüş değerini, her öğenin eşleşen karakter dizisi ve konumundan oluşan bir çift olduğu bir diziye değiştirir:

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

$lazy true ise, fonksiyon bir dizi yerine bir Generator döndürür, bu da büyük karakter dizileriyle çalışırken önemli performans avantajları sağlar. Jeneratör, tüm karakter dizisini bir kerede yerine eşleşmeleri aşamalı olarak aramanıza olanak tanır. Bu, son derece büyük girdi metinleriyle bile verimli bir şekilde çalışmanıza olanak tanır. Ayrıca, aradığınız eşleşmeyi bulduğunuzda işlemi istediğiniz zaman kesebilirsiniz, bu da hesaplama süresinden tasarruf sağlar.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Bulundu: $match[0]\n";
    // İşlem herhangi bir zamanda kesilebilir
}

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

Düzenli bir ifadeye uyan tüm oluşumları değiştirir. $replacement ya bir değiştirme karakter dizisi maskesi ya da bir geri çağırmadır.

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

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

Fonksiyon ayrıca, ikinci parametrede pattern => replacement şeklinde bir dizi ileterek birden fazla değiştirme yapılmasına da olanak tanır:

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

$limit parametresi yapılan değiştirme sayısını sınırlar. –1 limiti kısıtlama olmadığı anlamına gelir.

$utf8 true ise, değerlendirme Unicode moduna geçer. u değiştiricisini belirtmişsiniz gibi.

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

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

$captureOffset true ise, her eşleşen oluşum için karakter dizisindeki konumu da geri çağırmaya iletilir (bayt cinsinden; $utf8 ayarlanmışsa karakter cinsinden). Bu, iletilen dizinin biçimini değiştirir, burada her öğe eşleşen karakter dizisi ve konumundan oluşan bir çifttir.

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

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

$unmatchedAsNull true ise, yakalanmayan alt desenler geri çağırmaya null olarak iletilir; aksi takdirde boş bir karakter dizisi olarak iletilir veya iletilmez:

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