Nette Documentation Preview

syntax 
String-Funktionen
*****************

.[perex]
[api:Nette\Utils\Strings] ist eine statische Klasse mit nützlichen Funktionen für die Arbeit mit Strings in UTF-8-Kodierung.


Installation:

```shell
composer require nette/utils
```

Alle Beispiele setzen voraus, dass dieser Klassen-Alias definiert ist:

```php
use Nette\Utils\Strings;
```


Groß-/Kleinschreibung
=====================

Diese Funktionen erfordern die PHP-Erweiterung `mbstring`.


lower(string $s): string .[method]
----------------------------------

Wandelt einen UTF-8-String in Kleinbuchstaben um.

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


upper(string $s): string .[method]
----------------------------------

Wandelt einen UTF-8-String in Großbuchstaben um.

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


firstUpper(string $s): string .[method]
---------------------------------------

Wandelt das erste Zeichen eines UTF-8-Strings in einen Großbuchstaben um und lässt die übrigen Zeichen unverändert.

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


firstLower(string $s): string .[method]
---------------------------------------

Wandelt das erste Zeichen eines UTF-8-Strings in einen Kleinbuchstaben um und lässt die übrigen Zeichen unverändert.

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


capitalize(string $s): string .[method]
---------------------------------------

Wandelt das erste Zeichen jedes Wortes in einem UTF-8-String in einen Großbuchstaben um und die übrigen in Kleinbuchstaben.

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


Bearbeiten eines Strings
========================


normalize(string $s): string .[method]
--------------------------------------

Entfernt Steuerzeichen, vereinheitlicht die Zeilenenden zu `\n`, entfernt leere Zeilen am Anfang und am Ende, entfernt Leerzeichen am Zeilenende und normalisiert UTF-8 in die Normalform NFC.


unixNewLines(string $s): string .[method]
-----------------------------------------

Wandelt die Zeilenenden in das auf Unix-Systemen verwendete `\n` um. Als Zeilenenden gelten: `\n`, `\r`, `\r\n`, U+2028 Zeilentrenner, U+2029 Absatztrenner.

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


platformNewLines(string $s): string .[method]
---------------------------------------------

Wandelt die Zeilenenden in die Zeichen um, die für die aktuelle Plattform typisch sind, also `\r\n` unter Windows und `\n` anderswo. Als Zeilenenden gelten: `\n`, `\r`, `\r\n`, U+2028 Zeilentrenner, U+2029 Absatztrenner.

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


webalize(string $s, ?string $charlist=null, bool $lower=true): string .[method]
-------------------------------------------------------------------------------

Bringt einen UTF-8-String in die in URLs verwendete Form, entfernt also Diakritika und ersetzt alle Zeichen außer den Buchstaben des englischen Alphabets und Ziffern durch Bindestriche.

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

Sollen weitere Zeichen erhalten bleiben, lassen sie sich im zweiten Parameter angeben.

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

Der dritte Parameter kann die Umwandlung in Kleinbuchstaben unterdrücken.

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

.[caution]
Erfordert die PHP-Erweiterung `intl`.


trim(string $s, string $charlist=self::TrimCharacters): string .[method]
------------------------------------------------------------------------

Entfernt Leerraum (oder andere im zweiten Parameter angegebene Zeichen) am Anfang und am Ende eines UTF-8-Strings.

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


truncate(string $s, int $maxLen, string $append=`'…'`): string .[method]
------------------------------------------------------------------------

Kürzt einen UTF-8-String auf die angegebene Maximallänge und versucht dabei, ganze Wörter zu erhalten. Wird der String gekürzt, werden am Ende Auslassungspunkte angehängt (über den dritten Parameter änderbar).

```php
$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 .[method]
-----------------------------------------------------------------------

Rückt einen mehrzeiligen Text von links ein. Der zweite Parameter gibt die Anzahl der Einrückungszeichen an, der dritte das Zeichen bzw. die Zeichen, mit denen eingerückt wird (standardmäßig ein Tabulator).

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


padLeft(string $s, int $length, string $pad=`' '`): string .[method]
--------------------------------------------------------------------

Füllt einen UTF-8-String auf die angegebene Länge auf, indem der String `$pad` von links vorangestellt wird.

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


padRight(string $s, int $length, string $pad=`' '`): string .[method]
---------------------------------------------------------------------

Füllt einen UTF-8-String auf die angegebene Länge auf, indem der String `$pad` von rechts angehängt wird.

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


substring(string $s, int $start, ?int $length=null): string .[method]
---------------------------------------------------------------------

Gibt den Teil des UTF-8-Strings `$s` zurück, der durch die Startposition `$start` und die Länge `$length` bestimmt ist. Ist `$start` negativ, beginnt der zurückgegebene String beim `$start`-ten Zeichen vom Ende.

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


reverse(string $s): string .[method]
------------------------------------

Kehrt einen UTF-8-String um.

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


length(string $s): int .[method]
--------------------------------

Gibt die Anzahl der Zeichen (nicht Bytes) in einem UTF-8-String zurück.

Das ist die Anzahl der Unicode-Codepunkte, die sich von der Anzahl der Grapheme unterscheiden kann.

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


startsWith(string $haystack, string $needle): bool .[method deprecated]
-----------------------------------------------------------------------

Prüft, ob der String `$haystack` mit dem String `$needle` beginnt.

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

.[note]
Verwenden Sie die native Funktion `str_starts_with()`:https://www.php.net/manual/en/function.str-starts-with.php.


endsWith(string $haystack, string $needle): bool .[method deprecated]
---------------------------------------------------------------------

Prüft, ob der String `$haystack` mit dem String `$needle` endet.

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

.[note]
Verwenden Sie die native Funktion `str_ends_with()`:https://www.php.net/manual/en/function.str-ends-with.php.


contains(string $haystack, string $needle): bool .[method deprecated]
---------------------------------------------------------------------

Prüft, ob der String `$haystack` den String `$needle` enthält.

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

.[note]
Verwenden Sie die native Funktion `str_contains()`:https://www.php.net/manual/en/function.str-contains.php.


compare(string $left, string $right, ?int $length=null): bool .[method]
-----------------------------------------------------------------------

Vergleicht zwei UTF-8-Strings oder Teile davon, ohne auf die Groß-/Kleinschreibung zu achten. Ist `$length` gleich null, werden die ganzen Strings verglichen. Ist der Wert negativ, wird die entsprechende Anzahl von Zeichen vom Ende der Strings verglichen, sonst die entsprechende Anzahl von Zeichen vom Anfang.

```php
Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - die ersten 2 Zeichen stimmen überein
Strings::compare('Nette', 'Latte', -2); // true - die letzten 2 Zeichen stimmen überein
```


findPrefix(array $strings): string .[method]
--------------------------------------------

Findet das gemeinsame Präfix der Strings. Gibt einen leeren String zurück, wenn kein gemeinsames Präfix gefunden wird.

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


before(string $haystack, string $needle, int $nth=1): ?string .[method]
-----------------------------------------------------------------------

Gibt den Teil des Strings `$haystack` vor dem `$nth`-ten Vorkommen des Strings `$needle` zurück. Gibt `null` zurück, wenn `$needle` nicht gefunden wird. Ist `$nth` negativ, wird vom Ende des Strings aus gesucht.

```php
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 .[method]
----------------------------------------------------------------------

Gibt den Teil des Strings `$haystack` nach dem `$nth`-ten Vorkommen des Strings `$needle` zurück. Gibt `null` zurück, wenn `$needle` nicht gefunden wird. Ist `$nth` negativ, wird vom Ende des Strings aus gesucht.

```php
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 .[method]
---------------------------------------------------------------------

Gibt die Zeichenposition des `$nth`-ten Vorkommens des Strings `$needle` im String `$haystack` zurück. Gibt `null` zurück, wenn `$needle` nicht gefunden wird. Ist `$nth` negativ, wird vom Ende des Strings aus gesucht.

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


Kodierung
=========


fixEncoding(string $s): string .[method]
----------------------------------------

Entfernt ungültige UTF-8-Zeichen aus einem String.

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


checkEncoding(string $s): bool .[method deprecated]
---------------------------------------------------

Prüft, ob ein String ein gültiger UTF-8-String ist.

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

.[note]
Verwenden Sie [Nette\Utils\Validators::isUnicode() |validators#isUnicode()].


toAscii(string $s): string .[method]
------------------------------------

Wandelt einen UTF-8-String in ASCII um, entfernt also Diakritika und so weiter.

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

.[caution]
Erfordert die PHP-Erweiterung `intl`.


chr(int $code): string .[method]
--------------------------------

Gibt zu einem Codepunkt (einer Zahl im Bereich 0x0000..D7FF oder 0xE000..10FFFF) das entsprechende Zeichen in UTF-8 zurück.

```php
Strings::chr(0xA9); // '©' in UTF-8-Kodierung
```


ord(string $c): int .[method]
-----------------------------

Gibt den Codepunkt eines bestimmten Zeichens in UTF-8 zurück (eine Zahl im Bereich 0x0000..D7FF oder 0xE000..10FFFF).

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


Reguläre Ausdrücke
==================

Die Klasse `Strings` bietet Funktionen für die Arbeit mit regulären Ausdrücken. Anders als die nativen PHP-Funktionen haben sie eine verständlichere API, eine bessere Unterstützung von Unicode und, was entscheidend ist, eine Fehlererkennung. Jeder Fehler beim Kompilieren oder beim Verarbeiten des Ausdrucks wirft eine `Nette\RegexpException`.


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

Teilt einen String anhand eines regulären Ausdrucks in ein Array. Auch die Ausdrücke in Klammern werden erfasst und zurückgegeben.

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

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

Ist `$skipEmpty` gleich `true`, werden nur nicht leere Elemente zurückgegeben:

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

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

Ist `$limit` angegeben, werden nur Teilstrings bis zu diesem Limit zurückgegeben, und der Rest des Strings landet im letzten Element. Ein Limit von -1 oder 0 bedeutet keine Begrenzung.

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

Ist `$utf8` gleich `true`, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator `u`.

Ist `$captureOffset` gleich `true`, wird zusätzlich die Position jedes Treffers im String zurückgegeben (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist). Das ändert den Rückgabewert in ein Array, dessen Elemente jeweils ein Paar aus dem gefundenen String und seiner Position sind.

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

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true, utf8: true);
// [['žlutý', 0], ['kůň', 7]] // die Positionen sind in Zeichen
```


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

Sucht im String nach einem Teil, der dem regulären Ausdruck entspricht, und gibt ein Array mit dem gefundenen Ausdruck und den einzelnen Teilausdrücken zurück, oder `null`, wenn nichts gefunden wird.

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

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

Ist `$unmatchedAsNull` gleich `true`, werden nicht getroffene Teilausdrücke als `null` zurückgegeben, sonst als leerer String oder gar nicht:

```php
Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (die optionale Gruppe !+ hat nicht getroffen)

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

Ist `$utf8` gleich `true`, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator `u`:

```php
Strings::match('žlutý kůň', '~\w+~'); // ohne UTF-8
// ['lut'] (trifft nur ASCII-Wortzeichen)

Strings::match('žlutý kůň', '~\w+~', utf8: true); // mit UTF-8
// ['žlutý'] (trifft Unicode-Wortzeichen)
```

Mit dem Parameter `$offset` lässt sich die Position angeben, ab der gesucht wird (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist).

Ist `$captureOffset` gleich `true`, wird zusätzlich die Position jedes Treffers im String zurückgegeben (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist). Das ändert den Rückgabewert in ein Array, dessen Elemente jeweils ein Paar aus dem gefundenen String und seinem Offset sind:

```php
Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // ohne UTF-8
// [['lut', 2]] (nur ASCII-Treffer, Offset in Bytes)

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // mit UTF-8
// [['žlutý!', 0], ['!', 5]] (Unicode-Treffer, Offsets in Zeichen)
```


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 .[method]
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Sucht im String nach allen Vorkommen, die dem regulären Ausdruck entsprechen, und gibt ein Array von Arrays mit dem gefundenen Ausdruck und den einzelnen Teilausdrücken zurück.

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

Ist `$patternOrder` gleich `true`, ändert sich die Struktur der Ergebnisse: Das erste Element ist ein Array aller vollständigen Treffer, das zweite ein Array der Strings, die dem ersten geklammerten Teilausdruck entsprechen, und so weiter:

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

Ist `$unmatchedAsNull` gleich `true`, werden nicht getroffene Teilausdrücke als `null` zurückgegeben, sonst als leerer String oder gar nicht:

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

Ist `$utf8` gleich `true`, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator `u`:

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

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

Mit dem Parameter `$offset` lässt sich die Position angeben, ab der gesucht wird (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist).

Ist `$captureOffset` gleich `true`, wird zusätzlich die Position jedes Treffers im String zurückgegeben (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist). Das ändert die Struktur des Rückgabewerts, wobei jedes Trefferelement ein Paar `[gefundener_String, Position]` ist:

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

Ist `$lazy` gleich `true`, gibt die Funktion statt eines Arrays einen `Generator` zurück. Bei der Arbeit mit großen Strings bringt das einen erheblichen Leistungsvorteil, weil die Treffer nach und nach gefunden werden, statt den gesamten String auf einmal zu verarbeiten. So lassen sich auch extrem große Eingaben effizient verarbeiten. Außerdem können Sie die Verarbeitung jederzeit abbrechen, sobald Sie den gesuchten Treffer gefunden haben, und sparen so Rechenzeit.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Gefunden: $match[0]\n";
    // Die Verarbeitung lässt sich jederzeit abbrechen, z. B. mit break;
}
```


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

Ersetzt alle Vorkommen, die dem regulären Ausdruck entsprechen. `$replacement` ist entweder eine Maske für den Ersatzstring oder eine Callback-Funktion.

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

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

Die Funktion erlaubt auch mehrere Ersetzungen auf einmal, indem als zweiter Parameter ein Array im Format `Muster => Ersatz` übergeben wird:

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

Der Parameter `$limit` begrenzt die Anzahl der durchgeführten Ersetzungen. Ein Limit von -1 bedeutet keine Begrenzung.

Ist `$utf8` gleich `true`, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator `u`.

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

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

Ist `$captureOffset` gleich `true`, wird dem Callback zusätzlich die Position jedes Treffers im String übergeben (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist). Das ändert die Struktur des übergebenen Arrays, dessen Elemente jeweils ein Paar `[gefundener_String, Position]` sind.

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

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

Ist `$unmatchedAsNull` gleich `true`, werden nicht getroffene Teilausdrücke dem Callback als `null` übergeben, sonst als leerer String oder gar nicht:

```php
Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// gibt ['ac', 'a', '', 'c'] aus

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// gibt ['ac', 'a', null, 'c'] aus
```

String-Funktionen

Nette\Utils\Strings ist eine statische Klasse mit nützlichen Funktionen für die Arbeit mit Strings in UTF-8-Kodierung.

Installation:

composer require nette/utils

Alle Beispiele setzen voraus, dass dieser Klassen-Alias definiert ist:

use Nette\Utils\Strings;

Groß-/Kleinschreibung

Diese Funktionen erfordern die PHP-Erweiterung mbstring.

lower(string $s): string

Wandelt einen UTF-8-String in Kleinbuchstaben um.

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

upper(string $s): string

Wandelt einen UTF-8-String in Großbuchstaben um.

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

firstUpper(string $s): string

Wandelt das erste Zeichen eines UTF-8-Strings in einen Großbuchstaben um und lässt die übrigen Zeichen unverändert.

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

firstLower(string $s): string

Wandelt das erste Zeichen eines UTF-8-Strings in einen Kleinbuchstaben um und lässt die übrigen Zeichen unverändert.

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

capitalize(string $s): string

Wandelt das erste Zeichen jedes Wortes in einem UTF-8-String in einen Großbuchstaben um und die übrigen in Kleinbuchstaben.

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

Bearbeiten eines Strings

normalize(string $s): string

Entfernt Steuerzeichen, vereinheitlicht die Zeilenenden zu \n, entfernt leere Zeilen am Anfang und am Ende, entfernt Leerzeichen am Zeilenende und normalisiert UTF-8 in die Normalform NFC.

unixNewLines(string $s): string

Wandelt die Zeilenenden in das auf Unix-Systemen verwendete \n um. Als Zeilenenden gelten: \n, \r, \r\n, U+2028 Zeilentrenner, U+2029 Absatztrenner.

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

platformNewLines(string $s): string

Wandelt die Zeilenenden in die Zeichen um, die für die aktuelle Plattform typisch sind, also \r\n unter Windows und \n anderswo. Als Zeilenenden gelten: \n, \r, \r\n, U+2028 Zeilentrenner, U+2029 Absatztrenner.

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

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

Bringt einen UTF-8-String in die in URLs verwendete Form, entfernt also Diakritika und ersetzt alle Zeichen außer den Buchstaben des englischen Alphabets und Ziffern durch Bindestriche.

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

Sollen weitere Zeichen erhalten bleiben, lassen sie sich im zweiten Parameter angeben.

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

Der dritte Parameter kann die Umwandlung in Kleinbuchstaben unterdrücken.

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

Erfordert die PHP-Erweiterung intl.

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

Entfernt Leerraum (oder andere im zweiten Parameter angegebene Zeichen) am Anfang und am Ende eines UTF-8-Strings.

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

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

Kürzt einen UTF-8-String auf die angegebene Maximallänge und versucht dabei, ganze Wörter zu erhalten. Wird der String gekürzt, werden am Ende Auslassungspunkte angehängt (über den dritten Parameter änderbar).

$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

Rückt einen mehrzeiligen Text von links ein. Der zweite Parameter gibt die Anzahl der Einrückungszeichen an, der dritte das Zeichen bzw. die Zeichen, mit denen eingerückt wird (standardmäßig ein Tabulator).

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

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

Füllt einen UTF-8-String auf die angegebene Länge auf, indem der String $pad von links vorangestellt wird.

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

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

Füllt einen UTF-8-String auf die angegebene Länge auf, indem der String $pad von rechts angehängt wird.

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

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

Gibt den Teil des UTF-8-Strings $s zurück, der durch die Startposition $start und die Länge $length bestimmt ist. Ist $start negativ, beginnt der zurückgegebene String beim $start-ten Zeichen vom Ende.

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

reverse(string $s): string

Kehrt einen UTF-8-String um.

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

length(string $s): int

Gibt die Anzahl der Zeichen (nicht Bytes) in einem UTF-8-String zurück.

Das ist die Anzahl der Unicode-Codepunkte, die sich von der Anzahl der Grapheme unterscheiden kann.

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

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

Prüft, ob der String $haystack mit dem String $needle beginnt.

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

Verwenden Sie die native Funktion str_starts_with().

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

Prüft, ob der String $haystack mit dem String $needle endet.

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

Verwenden Sie die native Funktion str_ends_with().

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

Prüft, ob der String $haystack den String $needle enthält.

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

Verwenden Sie die native Funktion str_contains().

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

Vergleicht zwei UTF-8-Strings oder Teile davon, ohne auf die Groß-/Kleinschreibung zu achten. Ist $length gleich null, werden die ganzen Strings verglichen. Ist der Wert negativ, wird die entsprechende Anzahl von Zeichen vom Ende der Strings verglichen, sonst die entsprechende Anzahl von Zeichen vom Anfang.

Strings::compare('Nette', 'nette');     // true
Strings::compare('Nette', 'next', 2);   // true - die ersten 2 Zeichen stimmen überein
Strings::compare('Nette', 'Latte', -2); // true - die letzten 2 Zeichen stimmen überein

findPrefix(array $strings): string

Findet das gemeinsame Präfix der Strings. Gibt einen leeren String zurück, wenn kein gemeinsames Präfix gefunden wird.

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

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

Gibt den Teil des Strings $haystack vor dem $nth-ten Vorkommen des Strings $needle zurück. Gibt null zurück, wenn $needle nicht gefunden wird. Ist $nth negativ, wird vom Ende des Strings aus gesucht.

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

Gibt den Teil des Strings $haystack nach dem $nth-ten Vorkommen des Strings $needle zurück. Gibt null zurück, wenn $needle nicht gefunden wird. Ist $nth negativ, wird vom Ende des Strings aus gesucht.

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

Gibt die Zeichenposition des $nth-ten Vorkommens des Strings $needle im String $haystack zurück. Gibt null zurück, wenn $needle nicht gefunden wird. Ist $nth negativ, wird vom Ende des Strings aus gesucht.

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

Kodierung

fixEncoding(string $s): string

Entfernt ungültige UTF-8-Zeichen aus einem String.

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

checkEncoding(string $s): bool

Prüft, ob ein String ein gültiger UTF-8-String ist.

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

Verwenden Sie Nette\Utils\Validators::isUnicode().

toAscii(string $s): string

Wandelt einen UTF-8-String in ASCII um, entfernt also Diakritika und so weiter.

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

Erfordert die PHP-Erweiterung intl.

chr(int $code): string

Gibt zu einem Codepunkt (einer Zahl im Bereich 0×0000..D7FF oder 0xE000..10FFFF) das entsprechende Zeichen in UTF-8 zurück.

Strings::chr(0xA9); // '©' in UTF-8-Kodierung

ord(string $c): int

Gibt den Codepunkt eines bestimmten Zeichens in UTF-8 zurück (eine Zahl im Bereich 0×0000..D7FF oder 0xE000..10FFFF).

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

Reguläre Ausdrücke

Die Klasse Strings bietet Funktionen für die Arbeit mit regulären Ausdrücken. Anders als die nativen PHP-Funktionen haben sie eine verständlichere API, eine bessere Unterstützung von Unicode und, was entscheidend ist, eine Fehlererkennung. Jeder Fehler beim Kompilieren oder beim Verarbeiten des Ausdrucks wirft eine Nette\RegexpException.

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

Teilt einen String anhand eines regulären Ausdrucks in ein Array. Auch die Ausdrücke in Klammern werden erfasst und zurückgegeben.

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

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

Ist $skipEmpty gleich true, werden nur nicht leere Elemente zurückgegeben:

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

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

Ist $limit angegeben, werden nur Teilstrings bis zu diesem Limit zurückgegeben, und der Rest des Strings landet im letzten Element. Ein Limit von –1 oder 0 bedeutet keine Begrenzung.

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

Ist $utf8 gleich true, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator u.

Ist $captureOffset gleich true, wird zusätzlich die Position jedes Treffers im String zurückgegeben (in Bytes; in Zeichen, wenn $utf8 gesetzt ist). Das ändert den Rückgabewert in ein Array, dessen Elemente jeweils ein Paar aus dem gefundenen String und seiner Position sind.

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

Strings::split('žlutý, kůň', '~,\s*~', captureOffset: true, utf8: true);
// [['žlutý', 0], ['kůň', 7]] // die Positionen sind in Zeichen

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

Sucht im String nach einem Teil, der dem regulären Ausdruck entspricht, und gibt ein Array mit dem gefundenen Ausdruck und den einzelnen Teilausdrücken zurück, oder null, wenn nichts gefunden wird.

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

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

Ist $unmatchedAsNull gleich true, werden nicht getroffene Teilausdrücke als null zurückgegeben, sonst als leerer String oder gar nicht:

Strings::match('hello', '~\w+(!+)?~');
// ['hello'] (die optionale Gruppe !+ hat nicht getroffen)

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

Ist $utf8 gleich true, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator u:

Strings::match('žlutý kůň', '~\w+~'); // ohne UTF-8
// ['lut'] (trifft nur ASCII-Wortzeichen)

Strings::match('žlutý kůň', '~\w+~', utf8: true); // mit UTF-8
// ['žlutý'] (trifft Unicode-Wortzeichen)

Mit dem Parameter $offset lässt sich die Position angeben, ab der gesucht wird (in Bytes; in Zeichen, wenn $utf8 gesetzt ist).

Ist $captureOffset gleich true, wird zusätzlich die Position jedes Treffers im String zurückgegeben (in Bytes; in Zeichen, wenn $utf8 gesetzt ist). Das ändert den Rückgabewert in ein Array, dessen Elemente jeweils ein Paar aus dem gefundenen String und seinem Offset sind:

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true); // ohne UTF-8
// [['lut', 2]] (nur ASCII-Treffer, Offset in Bytes)

Strings::match('žlutý!', '~\w+(!+)?~', captureOffset: true, utf8: true); // mit UTF-8
// [['žlutý!', 0], ['!', 5]] (Unicode-Treffer, Offsets in Zeichen)

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

Sucht im String nach allen Vorkommen, die dem regulären Ausdruck entsprechen, und gibt ein Array von Arrays mit dem gefundenen Ausdruck und den einzelnen Teilausdrücken zurück.

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

Ist $patternOrder gleich true, ändert sich die Struktur der Ergebnisse: Das erste Element ist ein Array aller vollständigen Treffer, das zweite ein Array der Strings, die dem ersten geklammerten Teilausdruck entsprechen, und so weiter:

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

Ist $unmatchedAsNull gleich true, werden nicht getroffene Teilausdrücke als null zurückgegeben, sonst als leerer String oder gar nicht:

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

Ist $utf8 gleich true, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator u:

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

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

Mit dem Parameter $offset lässt sich die Position angeben, ab der gesucht wird (in Bytes; in Zeichen, wenn $utf8 gesetzt ist).

Ist $captureOffset gleich true, wird zusätzlich die Position jedes Treffers im String zurückgegeben (in Bytes; in Zeichen, wenn $utf8 gesetzt ist). Das ändert die Struktur des Rückgabewerts, wobei jedes Trefferelement ein Paar [gefundener_String, Position] ist:

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

Ist $lazy gleich true, gibt die Funktion statt eines Arrays einen Generator zurück. Bei der Arbeit mit großen Strings bringt das einen erheblichen Leistungsvorteil, weil die Treffer nach und nach gefunden werden, statt den gesamten String auf einmal zu verarbeiten. So lassen sich auch extrem große Eingaben effizient verarbeiten. Außerdem können Sie die Verarbeitung jederzeit abbrechen, sobald Sie den gesuchten Treffer gefunden haben, und sparen so Rechenzeit.

$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Gefunden: $match[0]\n";
    // Die Verarbeitung lässt sich jederzeit abbrechen, z. B. mit break;
}

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

Ersetzt alle Vorkommen, die dem regulären Ausdruck entsprechen. $replacement ist entweder eine Maske für den Ersatzstring oder eine Callback-Funktion.

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

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

Die Funktion erlaubt auch mehrere Ersetzungen auf einmal, indem als zweiter Parameter ein Array im Format Muster => Ersatz übergeben wird:

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

Der Parameter $limit begrenzt die Anzahl der durchgeführten Ersetzungen. Ein Limit von –1 bedeutet keine Begrenzung.

Ist $utf8 gleich true, schaltet die Auswertung in den Unicode-Modus, ähnlich wie beim Modifikator u.

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

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

Ist $captureOffset gleich true, wird dem Callback zusätzlich die Position jedes Treffers im String übergeben (in Bytes; in Zeichen, wenn $utf8 gesetzt ist). Das ändert die Struktur des übergebenen Arrays, dessen Elemente jeweils ein Paar [gefundener_String, Position] sind.

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

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

Ist $unmatchedAsNull gleich true, werden nicht getroffene Teilausdrücke dem Callback als null übergeben, sonst als leerer String oder gar nicht:

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
);
// gibt ['ac', 'a', '', 'c'] aus

Strings::replace(
	'ac',
	'~(a)(b)*(c)~',
	function (array $m) { dump($m); return ''; },
	unmatchedAsNull: true,
);
// gibt ['ac', 'a', null, 'c'] aus