Generator::rewind

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

    Generator::rewind — Rewind the generator to the first yield

    Descrizione

    public Generator::rewind(): void

    The method rewinds the generator back to the point before the first yield. If the generator is not at a first yield expression when this method is called, it will first be let to advance to the first yield expression before rewinding. If the generator has already at the point of beginning of the second yield, this will throw an Exception.

    Nota:

    This is the first method called when starting a foreach loop. It will not be executed after foreach loops.

    Elenco dei parametri

    Questa funzione non contiene parametri.

    Valori restituiti

    Nessun valore viene restituito.

    Esempi

    Example #1 Generator::rewind() example

    <?php

    function generator(): Generator
    {
    echo     "I'm a generator!\n";

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

    // Initialize the generator
    $generator = generator();

    // Rewind the generator to the beginning of the first yield expression,
    // if it's not already there
    $generator->rewind(); // I'm a generator!

    // Nothing happens here; the generator is already rewound
    $generator->rewind(); // No output (NULL)

    // This rewinds the generator to the first yield expression,
    // if it's not already there, and iterates over the generator
    foreach ($generator as $value) {
    // After yielding the first value, the generator remains at
    // the first yield expression until it resumes execution and advances to the next yield
    echo $value, PHP_EOL; // 1

    break;
    }

    // Resume and rewind again. No error occurs because the generator has not advanced beyond the first yield
    $generator->rewind();

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

    // No error occurs, the generator is still at the first yield
    $generator->rewind();

    // This advances the generator to the second yield expression
    $generator->next();

    try {
    // This will throw an Exception,
    // because the generator has already advanced to the second yield
    $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
    } catch (Exception $e) {
    echo     $e->getMessage();
    }

    ?>

    Il precedente esempio visualizzerà:

    I'm a 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