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

    Found A Problem?

    Learn How To Improve This Page • Submit a Pull Request • Report a Bug
    ＋add a note

    User Contributed Notes 1 note

    up
    22
    i&#39;m pati on stackoverflow
    8 years ago
    Actually, this method can be useful to test a generator before iterating, as it executes your function up to the first yield statement. I.e. if you try to read a non-existent file in a generator, an error will normally occur only in client code foreach()'s first iteration. Sometimes this can be critical to check beforehand.

    Take a look at a modified example from here:
    http://php.net/manual/ru/language.generators.overview.php#112985

    <?php

    function getLines($file) {
    $f = fopen($file, 'r');
    try {
    while (    $line = fgets($f)) {
    yield     $line;
    }
    } finally {
    fclose($f);
    }
    }

    $getLines = getLines('no_such_file.txt');
    $getLines->rewind(); // with ->rewind(), a file read error will be thrown here and a log file will not be cleared

    openAndClearLogFile();

    foreach (    $getLines as $n => $line) { // without ->rewind(), the script will die here and your log file will be cleared
    writeToLogFile('reading: ' . $line . "\n");
    }

    closeLogFile();

    ?>

    P.S.: When you iterate over a generator after ->rewind(), you'll get the first yielded value immediately, as the preceding code was already executed.
    ＋add a note
    To Top