Λειτουργίες συμβολοσειράς

Nette\Utils\Strings είναι μια στατική κλάση, η οποία περιέχει πολλές χρήσιμες συναρτήσεις για την εργασία με κωδικοποιημένα αλφαριθμητικά UTF-8.

Εγκατάσταση:

composer require nette/utils

Όλα τα παραδείγματα προϋποθέτουν ότι έχει οριστεί το ακόλουθο ψευδώνυμο κλάσης:

use Nette\Utils\Strings;

Letter Case

Αυτές οι λειτουργίες απαιτούν την επέκταση PHP mbstring.

lower(string $s): string

Μετατρέπει όλους τους χαρακτήρες της συμβολοσειράς UTF-8 σε πεζά γράμματα.

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

upper(string $s): string

Μετατρέπει όλους τους χαρακτήρες μιας συμβολοσειράς UTF-8 σε κεφαλαίους.

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

firstUpper(string $s): string

Μετατρέπει τον πρώτο χαρακτήρα μιας συμβολοσειράς UTF-8 σε κεφαλαίο και αφήνει τους υπόλοιπους χαρακτήρες αμετάβλητους.

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

firstLower(string $s): string

Μετατρέπει τον πρώτο χαρακτήρα μιας συμβολοσειράς UTF-8 σε πεζά και αφήνει τους υπόλοιπους χαρακτήρες αμετάβλητους.

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

capitalize(string $s): string

Μετατρέπει τον πρώτο χαρακτήρα κάθε λέξης μιας συμβολοσειράς UTF-8 σε κεφαλαία και τους υπόλοιπους σε πεζά.

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

Επεξεργασία μιας συμβολοσειράς

normalize(string $s): string

Αφαιρεί τους χαρακτήρες ελέγχου, κανονικοποιεί τα διαλείμματα γραμμής στο \n, αφαιρεί τις κενές γραμμές που προηγούνται και ακολουθούν, κόβει τα κενά στο τέλος των γραμμών, κανονικοποιεί το UTF-8 στην κανονική μορφή του NFC.

unixNewLines(string $s): string

Μετατρέπει τα διαλείμματα γραμμής σε \n που χρησιμοποιούνται στα συστήματα Unix. Τα διαλείμματα γραμμής είναι: \n \r \r\n U+2028 διαχωριστικό γραμμής, U+2029 διαχωριστικό παραγράφου.

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

platformNewLines(string $s): string

Μετατρέπει τα διαχωριστικά γραμμών σε χαρακτήρες που αφορούν την τρέχουσα πλατφόρμα, δηλαδή \r\n στα Windows και \n αλλού. Τα διαλείμματα γραμμής είναι \n, \r, \r\n, U+2028 διαχωριστικό γραμμής, U+2029 διαχωριστικό παραγράφου.

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

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

Τροποποιεί τη συμβολοσειρά UTF-8 στη μορφή που χρησιμοποιείται στη διεύθυνση URL, δηλαδή αφαιρεί τους διακριτικούς χαρακτήρες και αντικαθιστά όλους τους χαρακτήρες εκτός από τα γράμματα του αγγλικού αλφαβήτου και τους αριθμούς με μια παύλα.

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

Μπορούν να διατηρηθούν και άλλοι χαρακτήρες, αλλά πρέπει να μεταβιβαστούν ως δεύτερο όρισμα.

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

Το τρίτο όρισμα μπορεί να εμποδίσει τη μετατροπή της συμβολοσειράς σε πεζά γράμματα.

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

Απαιτεί την επέκταση PHP intl.

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

Αφαιρεί όλα τα αριστερά και δεξιά κενά (ή τους χαρακτήρες που περνούν ως δεύτερο όρισμα) από μια κωδικοποιημένη συμβολοσειρά UTF-8.

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

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

Αποκόπτει μια συμβολοσειρά UTF-8 σε δεδομένο μέγιστο μήκος, ενώ προσπαθεί να μην διασπάσει ολόκληρες λέξεις. Μόνο αν η συμβολοσειρά είναι περικομμένη, μια έλλειψη (ή κάτι άλλο που ορίζεται με το τρίτο όρισμα) προσαρτάται στη συμβολοσειρά.

$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

Παρεμβάλλει ένα κείμενο πολλών γραμμών από τα αριστερά. Το δεύτερο όρισμα ορίζει πόσα σύμβολα εσοχής θα χρησιμοποιηθούν, ενώ η ίδια η εσοχή είναι το τρίτο όρισμα (tab από προεπιλογή).

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

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

Γεμίζει μια συμβολοσειρά UTF-8 στο δεδομένο μήκος, προτάσσοντας τη συμβολοσειρά $pad στην αρχή.

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

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

Στερεοποιεί τη συμβολοσειρά UTF-8 στο δεδομένο μήκος, προσθέτοντας τη συμβολοσειρά $pad στο τέλος.

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

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

Επιστρέφει ένα τμήμα της συμβολοσειράς UTF-8 που καθορίζεται από τη θέση έναρξης $start και το μήκος $length. Εάν το $start είναι αρνητικό, το επιστρεφόμενο αλφαριθμητικό θα ξεκινήσει από τον $start'οστό χαρακτήρα από το τέλος του αλφαριθμητικού.

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.

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

length(string $s): int

Επιστρέφει τον αριθμό των χαρακτήρων (όχι bytes) στη συμβολοσειρά UTF-8.

Δηλαδή τον αριθμό των κωδικών σημείων Unicode, ο οποίος μπορεί να διαφέρει από τον αριθμό των γραφημάτων.

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

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

Ελέγχει αν η συμβολοσειρά $haystack αρχίζει με $needle.

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

Χρησιμοποιεί το εγγενές str_starts_with().

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

Ελέγχει αν η συμβολοσειρά $haystack τελειώνει με $needle.

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

Χρησιμοποιεί το εγγενές str_ends_with().

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

Ελέγχει αν η συμβολοσειρά $haystack περιέχει το $needle.

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

Χρήση εγγενούς str_contains().

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

Συγκρίνει δύο συμβολοσειρές UTF-8 ή τα μέρη τους, χωρίς να λαμβάνει υπόψη την περίπτωση χαρακτήρων. Αν $length είναι null, συγκρίνονται ολόκληρες συμβολοσειρές, αν είναι αρνητικό, συγκρίνεται ο αντίστοιχος αριθμός χαρακτήρων από το τέλος των συμβολοσειρών, διαφορετικά συγκρίνεται ο αντίστοιχος αριθμός χαρακτήρων από την αρχή.

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

Βρίσκει το κοινό πρόθεμα των συμβολοσειρών ή επιστρέφει κενή συμβολοσειρά εάν το πρόθεμα δεν βρέθηκε.

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 πριν από την εμφάνιση του $nth στο $needle ή επιστρέφει το null εάν δεν βρέθηκε η βελόνα. Αρνητική τιμή σημαίνει αναζήτηση από το τέλος.

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 μετά την εμφάνιση του $nth στο $needle ή επιστρέφει το null εάν το $needle δεν βρέθηκε. Αρνητική τιμή του $nth σημαίνει αναζήτηση από το τέλος.

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

Επιστρέφει τη θέση σε χαρακτήρες του $nth εμφάνισης του $needle στο $haystack ή στο null εάν το $needle δεν βρέθηκε. Αρνητική τιμή του $nth σημαίνει αναζήτηση από το τέλος.

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

Κωδικοποίηση

fixEncoding(string $s): string

Αφαιρεί όλους τους μη έγκυρους χαρακτήρες UTF-8 από μια συμβολοσειρά.

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

checkEncoding(string $s): bool

Ελέγχει αν η συμβολοσειρά είναι έγκυρη σε κωδικοποίηση UTF-8.

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

Χρησιμοποιήστε την Nette\Utils\Validator::isUnicode().

toAscii(string $s): string

Μετατρέπει τη συμβολοσειρά UTF-8 σε ASCII, δηλαδή αφαιρεί τα διακριτικά κ.λπ.

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

Απαιτεί την επέκταση PHP intl.

chr(int $code): string

Επιστρέφει έναν συγκεκριμένο χαρακτήρα σε UTF-8 από το σημείο κωδικού (αριθμός στην περιοχή 0×0000..D7FF ή 0×E000..10FFFF).

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

ord(string $char): int

Επιστρέφει ένα σημείο κωδικού από συγκεκριμένο χαρακτήρα σε UTF-8 (αριθμός στην περιοχή 0×0000..D7FF ή 0×E000..10FFFF).

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

Κανονικές εκφράσεις

Η κλάση Strings παρέχει συναρτήσεις για την εργασία με κανονικές εκφράσεις. Σε αντίθεση με τις εγγενείς συναρτήσεις της PHP, έχουν ένα πιο κατανοητό API, καλύτερη υποστήριξη Unicode και, το σημαντικότερο, ανίχνευση σφαλμάτων. Οποιοδήποτε σφάλμα μεταγλώττισης ή επεξεργασίας εκφράσεων θα πετάξει μια εξαίρεση Nette\RegexpException.

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

Χωρίζει τη συμβολοσειρά σε πίνακες σύμφωνα με την κανονική έκφραση. Οι εκφράσεις σε παρενθέσεις θα καταγραφούν και θα επιστραφούν επίσης.

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

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

Εάν $skipEmpty είναι true, θα επιστραφούν μόνο μη κενά στοιχεία:

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

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

Εάν καθοριστεί το $limit, θα επιστραφούν μόνο υποσύνολα μέχρι το όριο και το υπόλοιπο της συμβολοσειράς θα τοποθετηθεί στο τελευταίο στοιχείο. Ένα όριο –1 ή 0 σημαίνει ότι δεν υπάρχει όριο.

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

Εάν $utf8 είναι true, η αξιολόγηση μεταβαίνει σε λειτουργία Unicode. Αυτό είναι παρόμοιο με τον προσδιορισμό του τροποποιητή u.

Εάν $captureOffset είναι true, για κάθε εμφανιζόμενη αντιστοιχία, θα επιστραφεί επίσης η θέση της στη συμβολοσειρά (σε bytes- σε χαρακτήρες εάν έχει οριστεί $utf8 ). Αυτό αλλάζει την τιμή επιστροφής σε έναν πίνακα όπου κάθε στοιχείο είναι ένα ζεύγος αποτελούμενο από το αλφαριθμητικό που ταιριάζει και τη θέση του.

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

Ψάχνει τη συμβολοσειρά για το τμήμα που ταιριάζει με την κανονική έκφραση και επιστρέφει έναν πίνακα με την έκφραση που βρέθηκε και τις επιμέρους υποεκφράσεις ή null.

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

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

Εάν το $unmatchedAsNull είναι true, τα μη ταιριαστά υποδείγματα επιστρέφονται ως null- διαφορετικά επιστρέφονται ως κενή συμβολοσειρά ή δεν επιστρέφονται:

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

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

Εάν $utf8 είναι true, η αξιολόγηση μεταβαίνει σε λειτουργία Unicode. Αυτό είναι παρόμοιο με τον προσδιορισμό του τροποποιητή u:

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

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

Η παράμετρος $offset μπορεί να χρησιμοποιηθεί για να καθορίσει τη θέση από την οποία θα ξεκινήσει η αναζήτηση (σε bytes- σε χαρακτήρες αν έχει οριστεί το $utf8 ).

Εάν $captureOffset είναι true, για κάθε εμφανιζόμενη αντιστοιχία, θα επιστρέφεται επίσης η θέση της στη συμβολοσειρά (σε bytes- σε χαρακτήρες εάν έχει οριστεί $utf8 ). Αυτό αλλάζει την τιμή επιστροφής σε έναν πίνακα όπου κάθε στοιχείο είναι ένα ζεύγος αποτελούμενο από το αλφαριθμητικό που ταιριάζει και τη μετατόπισή του:

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

Ψάχνει τη συμβολοσειρά για όλες τις εμφανίσεις που ταιριάζουν με την κανονική έκφραση και επιστρέφει έναν πίνακα πινάκων που περιέχει την έκφραση που βρέθηκε και κάθε υποέκφραση.

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

Εάν $patternOrder είναι true, η δομή των αποτελεσμάτων αλλάζει έτσι ώστε το πρώτο στοιχείο να είναι ένας πίνακας με πλήρεις αντιστοιχίες προτύπων, ο δεύτερος είναι ένας πίνακας με συμβολοσειρές που αντιστοιχούν στο πρώτο υποπρότυπο σε παρένθεση κ.ο.κ:

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

Εάν $unmatchedAsNull είναι true, τα υποδείγματα που δεν ταιριάζουν επιστρέφονται ως null- διαφορετικά επιστρέφονται ως κενή συμβολοσειρά ή δεν επιστρέφονται:

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

Εάν $utf8 είναι true, η αξιολόγηση μεταβαίνει σε λειτουργία Unicode. Αυτό είναι παρόμοιο με τον προσδιορισμό του τροποποιητή u:

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

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

Η παράμετρος $offset μπορεί να χρησιμοποιηθεί για να καθορίσει τη θέση από την οποία θα ξεκινήσει η αναζήτηση (σε bytes- σε χαρακτήρες αν έχει οριστεί το $utf8 ).

Εάν $captureOffset είναι true, για κάθε εμφανιζόμενη αντιστοιχία, θα επιστρέφεται επίσης η θέση της στη συμβολοσειρά (σε bytes- σε χαρακτήρες εάν έχει οριστεί $utf8 ). Αυτό αλλάζει την τιμή επιστροφής σε έναν πίνακα όπου κάθε στοιχείο είναι ένα ζεύγος που αποτελείται από το αλφαριθμητικό που ταιριάζει και τη θέση του:

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

Αντικαθιστά όλες τις εμφανίσεις που ταιριάζουν με την κανονική έκφραση. Το $replacement είναι είτε μια μάσκα συμβολοσειράς αντικατάστασης είτε μια επανάκληση.

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

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

Η συνάρτηση επιτρέπει επίσης πολλαπλές αντικαταστάσεις περνώντας στη δεύτερη παράμετρο έναν πίνακα της μορφής pattern => replacement:

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

Η παράμετρος $limit περιορίζει τον αριθμό των αντικαταστάσεων. Το όριο –1 σημαίνει ότι δεν υπάρχει όριο.

Εάν $utf8 είναι true, η αξιολόγηση μεταβαίνει σε λειτουργία Unicode. Αυτό είναι παρόμοιο με τον προσδιορισμό του τροποποιητή u.

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

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

Εάν $captureOffset είναι true, για κάθε εμφανιζόμενη αντιστοιχία, η θέση της στη συμβολοσειρά (σε bytes- σε χαρακτήρες εάν έχει οριστεί το $utf8 ) μεταβιβάζεται επίσης στο callback. Αυτό αλλάζει τη μορφή του περασμένου πίνακα, όπου κάθε στοιχείο είναι ένα ζεύγος που αποτελείται από το αλφαριθμητικό που ταιριάζει και τη θέση του.

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

Εάν το $unmatchedAsNull είναι true, τα μη ταιριασμένα υποδείγματα μεταβιβάζονται στο callback ως null- διαφορετικά μεταβιβάζονται ως κενή συμβολοσειρά ή δεν μεταβιβάζονται:

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