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

.[perex]
[api:Nette\Utils\Strings] ist eine statische Klasse, die viele nützliche Funktionen für die Arbeit mit UTF-8-kodierten Zeichenketten enthält.


Installation:

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

Alle Beispiele gehen davon aus, dass der folgende Klassenalias definiert ist:

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


Buchstabe Case .[#toc-letter-case]
==================================

Diese Funktionen erfordern die PHP-Erweiterung `mbstring`.


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

Konvertiert alle Zeichen einer UTF-8-Zeichenfolge in Kleinbuchstaben.

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


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

Konvertiert alle Zeichen einer UTF-8-Zeichenfolge in Großbuchstaben.

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


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

Konvertiert das erste Zeichen einer UTF-8-Zeichenkette in Großbuchstaben und lässt die anderen Zeichen unverändert.

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


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

Konvertiert das erste Zeichen einer UTF-8-Zeichenfolge in Kleinbuchstaben und lässt die anderen Zeichen unverändert.

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


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

Konvertiert das erste Zeichen eines jeden Wortes einer UTF-8-Zeichenkette in Großbuchstaben und die anderen in Kleinbuchstaben.

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


Bearbeiten einer Zeichenkette .[#toc-editing-a-string]
======================================================


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

Entfernt Steuerzeichen, normalisiert Zeilenumbrüche auf `\n`, entfernt führende und nachfolgende Leerzeilen, schneidet Leerzeichen am Zeilenende ab, normalisiert UTF-8 auf die normale Form von NFC.


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

Konvertiert Zeilenumbrüche in `\n`, die auf Unix-Systemen verwendet werden. Die Zeilenumbrüche sind: `\n`, `\r`, `\r\n`, U+2028 Zeilentrenner, U+2029 Absatztrenner.

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


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

Konvertiert Zeilenumbrüche in plattformspezifische Zeichen, d. h. `\r\n` unter Windows und `\n` in anderen Betriebssystemen. Die Zeilenumbrüche sind `\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]
-------------------------------------------------------------------------------

Ändert die UTF-8-Zeichenkette in die Form, die in der URL verwendet wird, d. h. entfernt diakritische Zeichen und ersetzt alle Zeichen außer Buchstaben des englischen Alphabets und Zahlen durch einen Bindestrich.

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

Andere Zeichen können ebenfalls beibehalten werden, müssen aber als zweites Argument übergeben werden.

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

Das dritte Argument kann die Umwandlung der Zeichenkette in Kleinbuchstaben unterdrücken.

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

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


trim(string $s, ?string $charlist=null): string .[method]
---------------------------------------------------------

Entfernt alle links- und rechtsseitigen Leerzeichen (oder die als zweites Argument übergebenen Zeichen) aus einer UTF-8-kodierten Zeichenkette.

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


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

Schneidet eine UTF-8-Zeichenkette auf die angegebene Maximallänge ab, wobei versucht wird, keine ganzen Wörter zu trennen. Nur wenn die Zeichenkette abgeschnitten wird, wird ein Ellipsis (oder etwas anderes, das mit dem dritten Argument festgelegt wird) an die Zeichenkette angehängt.

```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 $indentationChar=`"\t"`): string .[method]
---------------------------------------------------------------------------------

Rückt einen mehrzeiligen Text von links ein. Das zweite Argument legt fest, wie viele Einrückungszeichen verwendet werden sollen, während die Einrückung selbst das dritte Argument ist (standardmäßig *tab*).

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


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

Füllt eine UTF-8-Zeichenkette auf die angegebene Länge auf, indem die Zeichenkette `$pad` dem Anfang vorangestellt wird.

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


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

Bringt eine UTF-8-Zeichenfolge auf die angegebene Länge, indem die Zeichenfolge `$pad` am Ende angefügt wird.

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


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

Gibt einen Teil der UTF-8-Zeichenkette zurück, der durch die Startposition `$start` und die Länge `$length` angegeben wird. Wenn `$start` negativ ist, beginnt die zurückgegebene Zeichenkette am `$start`'ten Zeichen vom Ende der Zeichenkette.

```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 die UTF-8-Zeichenkette um.

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


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

Gibt die Anzahl der Zeichen (nicht Bytes) in der UTF-8-Zeichenfolge 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('red');   // 3
```


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

Prüft, ob die Zeichenfolge `$haystack` mit `$needle` beginnt.

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

.[note]
Verwenden Sie die native `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 `$haystack` string mit `$needle` endet.

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

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


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

Überprüft, ob `$haystack` string `$needle` enthält.

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

.[note]
Verwenden Sie die native `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-Zeichenketten oder deren Teile, ohne Berücksichtigung der Groß- und Kleinschreibung. Ist `$length` gleich null, werden ganze Zeichenketten verglichen, ist er negativ, wird die entsprechende Anzahl von Zeichen vom Ende der Zeichenketten verglichen, andernfalls die entsprechende Anzahl von Zeichen vom Anfang.

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

Findet das gemeinsame Präfix von Zeichenketten oder gibt eine leere Zeichenkette zurück, wenn das Präfix nicht gefunden wurde.

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

Gibt einen Teil von `$haystack` zurück, bevor `$nth` in `$needle` vorkommt, oder gibt `null` zurück, wenn die Nadel nicht gefunden wurde. Ein negativer Wert bedeutet, dass vom Ende her gesucht wird.

```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 einen Teil von `$haystack` zurück, nachdem `$nth` in `$needle` vorkommt, oder gibt `null` zurück, wenn `$needle` nicht gefunden wurde. Ein negativer Wert von `$nth` bedeutet, dass vom Ende her gesucht wird.

```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 Position in Zeichen des `$nth` Vorkommens von `$needle` in `$haystack` oder `null` zurück, wenn `$needle` nicht gefunden wurde. Ein negativer Wert von `$nth` bedeutet, dass vom Ende her gesucht wird.

```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 .[#toc-encoding]
==========================


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

Entfernt alle ungültigen UTF-8-Zeichen aus einer Zeichenkette.

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


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

Prüft, ob die Zeichenkette in UTF-8-Kodierung gültig ist.

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

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


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

Konvertiert UTF-8-String in ASCII, d.h. entfernt diakritische Zeichen usw.

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

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


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

Gibt ein bestimmtes Zeichen in UTF-8 ab Codepoint (Zahl im Bereich 0x0000..D7FF oder 0xE000..10FFFF) zurück.

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


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

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

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


Reguläre Ausdrücke .[#toc-regular-expressions]
==============================================

Die Klasse Strings bietet Funktionen für die Arbeit mit regulären Ausdrücken. Im Gegensatz zu den nativen PHP-Funktionen haben sie eine verständlichere API, bessere Unicode-Unterstützung und vor allem eine Fehlererkennung. Jeder Kompilierungs- oder Ausdrucksverarbeitungsfehler löst eine `Nette\RegexpException` Exception aus.


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

Teilt die Zeichenkette entsprechend dem regulären Ausdruck in Arrays auf. Ausdrücke in Klammern werden ebenfalls erfasst und zurückgegeben.

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

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

Wenn `$skipEmpty` `true` ist, werden nur nicht leere Elemente zurückgegeben:

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

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

Wenn `$limit` angegeben ist, werden nur Teilstrings bis zum Limit zurückgegeben und der Rest der Zeichenkette wird in das letzte Element eingefügt. Eine Grenze von -1 oder 0 bedeutet keine Grenze.

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

Wenn `$utf8` für `true` steht, schaltet die Auswertung in den Unicode-Modus. Dies ist ähnlich wie die Angabe des Modifikators "u".

Wenn `$captureOffset` gleich `true` ist, wird für jede auftretende Übereinstimmung auch deren Position in der Zeichenkette zurückgegeben (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist). Dies ändert den Rückgabewert in ein Array, in dem jedes Element ein Paar ist, das aus der übereinstimmenden Zeichenkette und ihrer Position besteht.

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


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

Durchsucht die Zeichenkette nach dem Teil, der mit dem regulären Ausdruck übereinstimmt, und gibt ein Array mit dem gefundenen Ausdruck und einzelnen Unterausdrücken zurück, oder `null`.

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

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

Wenn `$unmatchedAsNull` gleich `true` ist, werden nicht übereinstimmende Teilmuster als Null zurückgegeben; andernfalls werden sie als leere Zeichenfolge oder nicht zurückgegeben:

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

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

Wenn `$utf8` gleich `true` ist, schaltet die Auswertung in den Unicode-Modus. Dies ist vergleichbar mit der Angabe des Modifikators "u":

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

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

Der Parameter `$offset` kann verwendet werden, um die Position anzugeben, an der die Suche beginnen soll (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist).

Wenn `$captureOffset` gleich `true` ist, wird für jede auftretende Übereinstimmung auch deren Position in der Zeichenkette zurückgegeben (in Bytes; in Zeichen, wenn `$utf8` eingestellt ist). Dadurch wird der Rückgabewert zu einem Array, in dem jedes Element ein Paar ist, das aus der übereinstimmenden Zeichenfolge und ihrem Versatz besteht:

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

Durchsucht die Zeichenkette nach allen Vorkommen, die mit dem regulären Ausdruck übereinstimmen, und gibt ein Array von Arrays zurück, das den gefundenen Ausdruck und jeden Unterausdruck enthält.

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

Wenn `$patternOrder` `true` ist, ändert sich die Struktur der Ergebnisse so, dass das erste Element ein Array mit vollständigen Mustertreffern ist, das zweite ein Array mit Zeichenketten, die dem ersten Untermuster in Klammern entsprechen, und so weiter:

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

Wenn `$unmatchedAsNull` gleich `true` ist, werden nicht übereinstimmende Teilmuster als Null zurückgegeben; andernfalls werden sie als leere Zeichenfolge oder nicht zurückgegeben:

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

Wenn `$utf8` gleich `true` ist, schaltet die Auswertung in den Unicode-Modus. Dies ist vergleichbar mit der Angabe des Modifikators "u":

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

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

Der Parameter `$offset` kann verwendet werden, um die Position anzugeben, an der die Suche beginnen soll (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist).

Wenn `$captureOffset` gleich `true` ist, wird für jede auftretende Übereinstimmung auch deren Position in der Zeichenkette zurückgegeben (in Bytes; in Zeichen, wenn `$utf8` eingestellt ist). Dadurch wird der Rückgabewert zu einem Array, in dem jedes Element ein Paar ist, das aus der übereinstimmenden Zeichenfolge und ihrer Position besteht:

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

Wenn `$lazy` `true` ist, gibt die Funktion ein `Generator` anstelle eines Arrays zurück, was bei der Arbeit mit großen Zeichenketten erhebliche Leistungsvorteile bietet. Der Generator ermöglicht es, dass Übereinstimmungen schrittweise gefunden werden, anstatt die gesamte Zeichenkette auf einmal zu verarbeiten. Dies ermöglicht einen effizienten Umgang mit extrem großen Eingabetexten. Außerdem können Sie die Verarbeitung jederzeit unterbrechen, wenn Sie die gewünschte Übereinstimmung gefunden haben, was Rechenzeit spart.

```php
$matches = Strings::matchAll($largeText, '~\w+~', lazy: true);
foreach ($matches as $match) {
    echo "Found: $match[0]\n";
    // Processing can be interrupted at any time
}
```


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 mit dem regulären Ausdruck übereinstimmen. `$replacement` ist entweder eine Ersetzungszeichenfolgenmaske oder ein Rückruf.

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

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

Die Funktion erlaubt auch Mehrfachersetzungen, indem sie im zweiten Parameter ein Array der Form `pattern => replacement` übergibt:

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

Der Parameter `$limit` begrenzt die Anzahl der Ersetzungen. Limit -1 bedeutet kein Limit.

Wenn `$utf8` gleich `true` ist, schaltet die Auswertung in den Unicode-Modus. Dies ist vergleichbar mit der Angabe des Modifikators "u".

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

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

Wenn `$captureOffset` `true` ist, wird für jede auftretende Übereinstimmung auch die Position in der Zeichenkette (in Bytes; in Zeichen, wenn `$utf8` gesetzt ist) an den Callback übergeben. Dies ändert die Form des übergebenen Arrays, wobei jedes Element ein Paar ist, das aus der übereinstimmenden Zeichenkette und ihrer Position besteht.

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

Wenn `$unmatchedAsNull` gleich `true` ist, werden nicht übereinstimmende Teilmuster als Null an den Callback übergeben; andernfalls werden sie als leere Zeichenkette oder nicht übergeben:

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