Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — Setzt den Iterator zum ersten yield zurück

Beschreibung

public Generator::rewind(): void

Die Methode setzt den Generator wieder an den Punkt vor dem ersten yield-Ausdruck zurück. Wenn sich der Generator beim Aufruf dieser Methode nicht an einem ersten yield-Ausdruck befindet, wird er vor dem Zurücksetzen zunächst zum ersten yield-Ausdruck vorrücken lassen. Befindet sich der Generator bereits am Anfang des zweiten yield-Ausdrucks, wird eine Exception ausgelöst.

Hinweis:
Dies ist die erste Methode, die aufgerufen wird, wenn eine foreach-Schleife gestartet wird. Sie wird nicht nach foreach-Schleifen ausgeführt.

Parameter-Liste

Diese Funktion besitzt keine Parameter.

Rückgabewerte

Es wird kein Wert zurückgegeben.

Beispiele

Beispiel #1 Generator::rewind()-Beispiel

<?php

function generator(): Generator
{
    echo "Ich bin ein Generator!\n";

    for ($i = 1; $i <= 3; $i++) {
        yield $i;
    }
}

// Initialisieren des Generators
$generator = generator();

// Zurücksetzen des Generators an den Anfang des ersten yield-Ausdrucks,
// falls er sich noch nicht dort befindet
$generator->rewind(); // Ich bin ein Generator!

// Hier passiert nichts, der Generator ist bereits zurückgesetzt.
$generator->rewind(); // No output (NULL)

// Dies setzt den Generator auf den ersten yield-Ausdruck zurück, falls
// er sich noch nicht dort befindet, und iteriert über den Generator
foreach ($generator as $value) {
    // Nach der Ausgabe des ersten Wertes bleibt der Generator beim ersten
    // yield-Ausdruck stehen, bis er die Ausführung wieder aufnimmt und zum
    // nächsten übergeht
    echo $value, PHP_EOL; // 1

    break;
}

// Fortsetzen und erneut zurücksetzen. Es tritt kein Fehler auf, da der
// Generator nicht über das erste yield hinausgelangt ist
$generator->rewind();

echo $generator->current(), PHP_EOL; // 1

// Es tritt kein Fehler auf, der Generator ist immer noch beim ersten yield
$generator->rewind();

// Damit wird der Generator zum zweiten yield-Ausdruck vorgerückt
$generator->next();

try {
    // Dies führt zu einer Exception,
    // da der Generator bereits zum zweiten yield vorgerückt ist
    $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
} catch (Exception $e) {
    echo $e->getMessage();
}

?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Ich bin ein Generator!
1
1
Cannot rewind a generator that was already run