mb_ereg_search_setpos — Funktion · PHP-Referenz

Signatur

mb_ereg_search_setpos(int $position): bool

Beschreibung

mb_ereg_search_setpos() verschiebt den internen Suchzeiger auf eine bestimmte Byte-Position innerhalb der Zeichenkette, die zuvor mit mb_ereg_search_init() registriert wurde. Alle folgenden Aufrufe von mb_ereg_search() beginnen dann an dieser neuen Position.

Die Funktion ist Teil der multibyte-sicheren Regex-Such-API (mb_ereg_search_*), die für schrittweise, iterative Suchen in Multibyte-Zeichenketten (z. B. UTF-8, EUC-JP) konzipiert wurde. Ohne manuelle Positionierung würde jeder Suchvorgang automatisch hinter dem letzten Treffer fortfahren.

Ein typischer Einsatzfall ist das Zurücksetzen der Suchposition auf den Anfang (0) oder das Überspringen eines bestimmten Bereichs, ohne die gesamt registrierte Zeichenkette erneut initialisieren zu müssen.

Achtung: Die Position bezieht sich auf Byte-Offsets, nicht auf Zeichen-Offsets. Bei Multibyte-Kodierungen kann ein Zeichen mehrere Bytes belegen, daher sollte die Position sorgfältig gewählt werden, um in der Mitte eines Multibyte-Zeichens zu landen.

Parameter

Name	Typ	Default	Beschreibung
$position Pflicht	int		Byte-Position (0-basiert) innerhalb der registrierten Zeichenkette, ab der der nächste Regex-Abgleich beginnen soll. Ein Wert von `0` setzt den Zeiger auf den Anfang zurück.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Position erfolgreich gesetzt wurde, false bei ungültiger Position (z. B. außerhalb des gültigen Bereichs der Zeichenkette).

Beispiele

Einfaches Zurücksetzen auf den Anfang

<?php
$string = 'Hallo Welt, Hallo PHP!';
mb_ereg_search_init($string, 'Hallo');

// Ersten Treffer finden
if (mb_ereg_search()) {
    $pos = mb_ereg_search_getpos();
    echo 'Treffer endet bei Byte-Position: ' . $pos . PHP_EOL;
}

// Zurücksetzen auf Anfang
mb_ereg_search_setpos(0);

// Erneut suchen – findet wieder den ersten Treffer
if (mb_ereg_search()) {
    $regs = mb_ereg_search_getregs();
    echo 'Erneuter Treffer: ' . $regs[0] . PHP_EOL;
}

Treffer endet bei Byte-Position: 5 Erneuter Treffer: Hallo

Iterative Suche mit manueller Positionierung

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

$haystack = 'foo123bar456baz789';
mb_ereg_search_init($haystack, '[0-9]+');

$treffer = [];
while (mb_ereg_search()) {
    $regs = mb_ereg_search_getregs();
    $treffer[] = $regs[0];
}

echo implode(', ', $treffer) . PHP_EOL;

// Suche ab Byte 7 neu starten (hinter 'foo123b')
mb_ereg_search_setpos(7);
$weitereTreeffer = [];
while (mb_ereg_search()) {
    $regs = mb_ereg_search_getregs();
    $weitereTreeffer[] = $regs[0];
}

echo implode(', ', $weitereTreeffer) . PHP_EOL;

123, 456, 789 456, 789

// Wichtig · Fallstricke

Byte- vs. Zeichen-Offsets: Die Position ist ein Byte-Offset, kein Zeichen-Offset. Bei Multibyte-Kodierungen wie UTF-8 kann eine falsch gesetzte Position mitten in ein Multibyte-Zeichen zeigen, was zu unerwarteten Ergebnissen oder Fehlern führen kann. Verwenden Sie mb_strlen() mit mb_internal_encoding(), um sichere Positionen zu berechnen.

Diese Funktion setzt voraus, dass zuvor mb_ereg_search_init() aufgerufen wurde. Ohne vorherige Initialisierung ist das Verhalten undefiniert.

Ab PHP 8.0 wird das zugrundeliegende Oniguruma-Regex-Modul verwendet. Die mb_ereg_*-Funktionen nutzen POSIX-Extended-Regex-Syntax (ERE), die sich von PCRE (preg_*) unterscheidet.

Siehe auch

mb_ereg_search_init mb_ereg_search mb_ereg_search_getpos mb_ereg_search_getregs mb_ereg_search_regs mb_internal_encoding