Dize Fonksiyonları

Nette\Utils\Strings, UTF-8 kodlamalı dizelerle çalışmaya yarayan kullanışlı fonksiyonlar içeren statik bir sınıftır.

Kurulum:

composer require nette/utils

Tüm örnekler, aşağıdaki sınıf takma adının tanımlandığını varsayar:

use Nette\Utils\Strings;

Harf Büyüklüğü

Bu fonksiyonlar mbstring PHP eklentisini gerektirir.

lower (string $s): string

UTF-8 dizesini küçük harfe dönüştürür.

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

upper (string $s): string

UTF-8 dizesini büyük harfe dönüştürür.

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

firstUpper (string $s): string

UTF-8 dizesinin ilk karakterini büyük harfe dönüştürür, diğer karakterleri değiştirmez.

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

firstLower (string $s): string

UTF-8 dizesinin ilk karakterini küçük harfe dönüştürür, diğer karakterleri değiştirmez.

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

capitalize (string $s): string

UTF-8 dizesindeki her sözcüğün ilk karakterini büyük, diğerlerini küçük harfe dönüştürür.

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

Dize Düzenleme

normalize (string $s): string

Denetim karakterlerini kaldırır, satır sonlarını \n biçimine normalleştirir, baştaki ve sondaki boş satırları kırpar, satırların sonundaki boşlukları kırpar ve UTF-8'i NFC normal biçimine normalleştirir.

unixNewLines (string $s): string

Satır sonlarını Unix sistemlerinde kullanılan \n biçimine 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ı geçerli platforma özgü karakterlere, yani Windows'ta \r\n, diğer sistemlerde \n biçimine 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ı.

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

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

UTF-8 dizesini URL'lerde kullanılan biçime dönüştürür; yani aksan işaretlerini kaldırır ve İngiliz alfabesindeki harfler ile rakamlar dışındaki tüm karakterleri tireyle değiştirir.

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

Başka karakterlerin de korunması gerekiyorsa bunlar ikinci parametrede belirtilebilir.

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

Üçüncü parametre, küçük harfe dönüştürmeyi engelleyebilir.

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

intl PHP eklentisini gerektirir.

trim (string $s, string $charlist=self::TrimCharacters): string

UTF-8 dizesinin başındaki ve sonundaki boşlukları (ya da ikinci parametrede belirtilen başka karakterleri) kırpar.

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

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

UTF-8 dizesini belirtilen en fazla uzunluğa kısaltır, bunu yaparken sözcükleri bölmemeye çalışır. Dize kısaltılırsa sonuna üç nokta (üçüncü parametreyle değiştirilebilir) eklenir.

$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 $chars=`"\t"`): string

Çok satırlı bir metni soldan girintiler. İkinci parametre girinti karakterlerinin sayısını, üçüncü parametre ise girinti için kullanılacak karakter(ler)i belirtir (varsayılan sekme).

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

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

UTF-8 dizesini, soldan $pad dizesini ekleyerek belirtilen uzunluğa tamamlar.

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

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

UTF-8 dizesini, sağdan $pad dizesini ekleyerek 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 dizesinin, $start başlangıç konumu ve $length uzunluğuyla belirtilen bir parçasını döndürür. $start negatifse döndürülen dize, sondan $start'ıncı karakterden 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

UTF-8 dizesini ters çevirir.

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

length (string $s): int

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

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

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

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

$haystack dizesinin $needle dizesiyle başlayıp başlamadığını denetler.

$haystack = 'Starts';
$needle = 'St';
Strings::startsWith($haystack, $needle); // true

Yerleşik str_starts_with() fonksiyonunu kullanın.

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

$haystack dizesinin $needle dizesiyle bitip bitmediğini denetler.

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

Yerleşik str_ends_with() fonksiyonunu kullanın.

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

$haystack dizesinin $needle dizesini içerip içermediğini denetler.

$haystack = 'Auditorium';
$needle = 'dit';
Strings::contains($haystack, $needle); // true

Yerleşik str_contains() fonksiyonunu kullanın.

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

İki UTF-8 dizesini ya da onların parçalarını, büyük/küçük harf ayrımı gözetmeden karşılaştırır. $length null ise dizelerin tamamını karşılaştırır. Negatifse dizelerin sonundan ilgili sayıda karakteri karşılaştırır. Diğer durumlarda baştan ilgili sayıda karakteri karşılaştırı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 (array $strings): string

Dizelerin ortak önekini bulur. Ortak önek yoksa boş dize döndürür.

Strings::findPrefix(['prefix-a', 'prefix-bb', 'prefix-c']); // 'prefix-'
Strings::findPrefix(['Nette', 'is', 'great']);              // ''

before (string $haystack, string $needle, int $nth=1): ?string

$haystack dizesinin, $needle dizesinin $nth'inci geçtiği yerden önceki parçasını döndürür. $needle bulunmazsa null döndürür. $nth negatifse dizenin sonundan arar.

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 dizesinin, $needle dizesinin $nth'inci geçtiği yerden sonraki parçasını döndürür. $needle bulunmazsa null döndürür. $nth negatifse dizenin sonundan arar.

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

$needle dizesinin $haystack içinde $nth'inci geçtiği yerin karakter konumunu döndürür. $needle bulunmazsa null döndürür. $nth negatifse dizenin sonundan arar.

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

Dizeden geçersiz UTF-8 karakterlerini kaldırır.

$correctString = Strings::fixEncoding($invalidString);

checkEncoding (string $s): bool

Dizenin geçerli bir UTF-8 dizesi olup olmadığını denetler.

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

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

toAscii (string $s): string

UTF-8 dizesini ASCII'ye dönüştürür; yani aksan işaretlerini vb. kaldırır.

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

intl PHP eklentisini gerektirir.

chr (int $code): string

Bir kod noktasından (0×0000..D7FF ya da 0xE000..10FFFF aralığında bir sayı) UTF-8'deki ilgili karakteri döndürür.

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

ord (string $c): int

UTF-8'deki bir karakterin kod noktasını (0×0000..D7FF ya da 0xE000..10FFFF aralığında bir sayı) döndürür.

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

Düzenli İfadeler

Strings sınıfı, düzenli ifadelerle çalışmaya yarayan fonksiyonlar sunar. Yerleşik PHP fonksiyonlarının aksine daha anlaşılır bir API'ye, daha iyi Unicode desteğine ve en önemlisi hata saptamaya sahiptirler. Derleme ya da ifade işleme sırasındaki her hata Nette\RegexpException fırlatır.

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

Bir dizeyi düzenli ifade kullanarak diziye böler. Parantez içindeki ifadeler de yakalanıp döndürülür.

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 belirtilirse yalnızca sınıra kadar alt dizeler döndürülür ve dizenin geri kalanı son öğeye konur. –1 ya da 0 sınırı, sınır yok demektir.

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

$utf8 true ise değerlendirme, u değiştiricisini kullanmaya benzer şekilde Unicode kipine geçer.

$captureOffset true ise her eşleşmenin dizedeki konumu da döndürülür (bayt cinsinden; $utf8 ayarlıysa karakter cinsinden). Bu, dönüş değerini her öğesi eşleşen dize ile konumundan oluşan bir çift olan bir diziye çevirir.

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true);
// [['žlutý', 0], ['kůň', 9]]

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true, utf8: true);
// [['žlutý', 0], ['kůň', 7]] // konumlar karakter cinsinden

match (string $subject, string $pattern, bool $captureOffset=false, int $offset=0, bool $unmatchedAsNull=false, bool $utf8=false): ?array

Bir dizede düzenli ifadeyle eşleşen bir parça arar ve bulunan ifadeyle alt ifadeleri içeren bir dizi, eşleşme yoksa null döndürür.

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

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

$unmatchedAsNull true ise eşleşmeyen alt desenler null olarak döndürülür; aksi hâlde boş dize olarak döndürülür ya da tümüyle atlanır:

Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (isteğe bağlı !+ grubu eşleşmedi)

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

$utf8 true ise değerlendirme, u değiştiricisini kullanmaya benzer şekilde Unicode kipine geçer:

Strings::match('žlutý kůň', '~\w+~'); // UTF-8 olmadan
// ['lut'] (yalnızca ASCII sözcük karakterleriyle eşleşir)

Strings::match('žlutý kůň', '~\w+~', utf8: true); // UTF-8 ile
// ['žlutý'] (Unicode sözcük karakterleriyle eşleşir)

$offset parametresi, aramanın başlangıç konumunu belirtebilir (bayt cinsinden; $utf8 ayarlıysa karakter cinsinden).

$captureOffset true ise her eşleşmenin dizedeki konumu da döndürülür (bayt cinsinden; $utf8 ayarlıysa karakter cinsinden). Bu, dönüş değerini her öğesi eşleşen dize ile kaymasından oluşan bir çift olan bir diziye çevirir:

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // UTF-8 olmadan
// [['lut', 2]] (yalnızca ASCII eşleşmesi, kayma bayt cinsinden)

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // UTF-8 ile
// [['žlutý!', 0], ['!', 5]] (Unicode eşleşmesi, kaymalar karakter cinsinden)

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 dizede düzenli ifadeyle eşleşen tüm yerleri arar ve bulunan ifadeyle alt ifadeleri içeren dizilerden oluşan bir dizi döndürür.

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

$patternOrder true ise sonuçların yapısı değişir: ilk öğe tam desen eşleşmelerinin dizisi, ikincisi ilk parantezli alt desenle eşleşen dizelerin dizisi vb. olur:

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

$unmatchedAsNull true ise eşleşmeyen alt desenler null olarak döndürülür; aksi hâlde boş dize olarak döndürülür ya da atlanır:

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

$utf8 true ise değerlendirme, u değiştiricisini kullanmaya benzer şekilde Unicode kipine geçer:

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

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

$offset parametresi, aramanın başlangıç konumunu belirtebilir (bayt cinsinden; $utf8 ayarlıysa karakter cinsinden).

$captureOffset true ise her eşleşmenin dizedeki konumu da döndürülür (bayt cinsinden; $utf8 ayarlıysa karakter cinsinden). Bu, dönüş değerinin yapısını değiştirir; her eşleşme öğesi [eşleşen_dize, konum] çifti olur:

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 dizi yerine bir Generator döndürür. Bu, büyük dizelerle çalışırken belirgin bir başarım kazancı sağlar; çünkü eşleşmeler dizenin tamamı bir kerede işlenmek yerine adım adım bulunur. Böylece çok büyük girdiler verimli biçimde ele alınabilir. Ayrıca aradığınız eşleşmeyi bulduğunuzda işlemeyi istediğiniz anda kesip hesaplama süresinden tasarruf edebilirsiniz.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // İşleme istenildiği an kesilebilir, örneğin break; ile
}

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

Düzenli ifadeyle eşleşen tüm yerleri değiştirir. $replacement, bir değiştirme dizesi maskesi ya da bir callback fonksiyonudur.

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

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

Fonksiyon, ikinci parametre olarak desen => değiştirme biçiminde bir dizi vererek birden çok değiştirme yapmaya da olanak tanır:

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

$limit parametresi yapılan değiştirmelerin sayısını sınırlar. –1 sınırı, sınır yok demektir.

$utf8 true ise değerlendirme, u değiştiricisini kullanmaya benzer şekilde Unicode kipine geçer.

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

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

$captureOffset true ise her eşleşmenin dizedeki konumu da (bayt cinsinden; $utf8 ayarlıysa karakter cinsinden) callback'e aktarılır. Bu, aktarılan dizinin yapısını değiştirir; her öğe [eşleşen_dize, konum] çifti olur.

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

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

$unmatchedAsNull true ise eşleşmeyen alt desenler callback'e null olarak aktarılır; aksi hâlde boş dize olarak aktarılır ya da atlanır:

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// ['ac', 'a', '', 'c'] dökümünü verir

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// ['ac', 'a', null, 'c'] dökümünü verir
  1. Dokümantasyon
  2. Nette Utils
  3. Dize Fonksiyonları
versiyon: 4.x
Image