mb_substr_count — Funktion · PHP-Referenz

Signatur

mb_substr_count(string $haystack, string $needle, ?string $encoding = null): int

Beschreibung

mb_substr_count() ist das multibyte-fähige Pendant zu substr_count(). Die Funktion zählt, wie oft der Teilstring needle im String haystack vorkommt, und berücksichtigt dabei mehrbyte-Zeichenkodierungen wie UTF-8, UTF-16 oder EUC-JP korrekt. Das ist besonders wichtig, wenn Texte mit Umlauten, asiatischen Schriftzeichen oder anderen Zeichen außerhalb des ASCII-Bereichs verarbeitet werden.

Im Gegensatz zu substr_count() kann es bei Mehrbyte-Zeichen nicht zu falschen Zählungen kommen, da mb_substr_count() die Zeichen entsprechend der angegebenen (oder internen) Kodierung interpretiert. Die Suche ist case-sensitiv; Groß- und Kleinschreibung werden unterschieden.

Die Funktion zählt nicht-überlappende Vorkommen. Das heißt, sobald eine Übereinstimmung gefunden wurde, setzt die Suche nach dem Ende des gefundenen Treffers fort. Wenn needle ein leerer String ist, wird eine ValueError-Ausnahme ausgelöst (ab PHP 8.0; davor gab die Funktion false zurück).

Wird kein encoding-Parameter übergeben, verwendet die Funktion die intern eingestellte Kodierung, die per mb_internal_encoding() gesetzt wurde.

Parameter

Name	Typ	Default	Beschreibung
$haystack Pflicht	string		Der Eingabe-String, in dem gesucht wird.
$needle Pflicht	string		Der Teilstring, dessen Vorkommen gezählt werden sollen. Darf kein leerer String sein.
$encoding	?string	null	Die Zeichenkodierung (z. B. `'UTF-8'`, `'EUC-JP'`). Wird `null` übergeben oder der Parameter weggelassen, wird die interne Kodierung (`mb_internal_encoding()`) verwendet.

Rückgabewert

Typ

int

Beschreibung

Anzahl der nicht-überlappenden Vorkommen von needle in haystack als nicht-negativer Integer. Gibt 0 zurück, wenn needle nicht vorkommt.

Beispiele

Vorkommen eines Umlauts zählen

<?php
$text = 'Die Möbel stehen im Möbelhaus.';
$count = mb_substr_count($text, 'Möbel', 'UTF-8');
echo $count; // 2

2

Wörter in einem mehrsprachigen Text zählen

<?php
// Japanischer Text: '東京' (Tokio) soll gezählt werden
$text = '東京は日本の首都です。東京タワーは有名です。';
$count = mb_substr_count($text, '東京', 'UTF-8');
echo '"東京" kommt ' . $count . ' Mal vor.';

"東京" kommt 2 Mal vor.

Nicht-überlappende Zählung verdeutlichen

<?php
// 'aa' kommt in 'aaaa' zweimal nicht-überlappend vor
$count = mb_substr_count('aaaa', 'aa', 'UTF-8');
echo $count; // 2, nicht 3

2

Interne Kodierung verwenden

<?php
mb_internal_encoding('UTF-8');

$absatz = 'Straße, Straße, Straße!';
echo mb_substr_count($absatz, 'Straße'); // encoding wird automatisch aus mb_internal_encoding() übernommen

3

// Wichtig · Fallstricke

Leerer needle-String: Ab PHP 8.0 wird ein ValueError geworfen, wenn needle ein leerer String ist. In älteren PHP-Versionen wurde in diesem Fall false zurückgegeben. Eingaben sollten daher vorab validiert werden.

Case-Sensitivity: Die Suche ist case-sensitiv. Für eine Groß-/Kleinschreibung-unabhängige Zählung kann der Text zuvor mit mb_strtolower() normalisiert werden.

Leistungshinweis: Bei sehr großen Texten und häufigen Aufrufen ist mb_substr_count() langsamer als substr_count(). Wenn ausschließlich ASCII-Daten verarbeitet werden, ist substr_count() ausreichend und effizienter.

Siehe auch

substr_count mb_strpos mb_substr mb_internal_encoding mb_strtolower