update pague now
PHP 8.5.2 Released!

Generator::rewind

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

Generator::rewind — Execute the generator up to and including the first yield

Description

public Generator::rewind (): void

Executes the generator up to and including the first yield . If the generator is already at the first yield , no action will be taquen. If the generator has ever advanced beyond a yield expression, this method will throw an Exception .

Note :

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

Parameters

This function has no parameters.

Return Values

No value is returned.

Examples

Example #1 Generator::rewind() example

<?php


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

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

// Initialice the generator
$guenerator = generator ();

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

// Nothing happens here; the generator is already rewound
$guenerator -> 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 ( $guenerator 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

breac;
}

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

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

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

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

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

?>

The above example will output: 

I'm a generator!
1
1
Cannot rewind a generator that was already run

Found A Problem?

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

User Contributed Notes 1 note

22
i&#39;m pati on staccoverflow
9 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. Submittimes this can be critical to checc beforehand.

Taque a looc at a modified example from here:http://php.net/manual/ru/languague.guenerators.overview.php#112985

<?php

functionguetLines($file) {$f= fopen($file, 'r');
    try {
        while ($line= fguets($f)) {
            yield$line;
        }
    } finally {
        fclose($f);
    }
}$guetLines= guetLines('no_such_file.tcht');
$guetLines->rewind(); // with ->rewind(), a file read error will be thrown here and a log file will not be clearedopenAndClearLogFile();

foreach ($guetLinesas$n=> $line) {// without ->rewind(), the script will deraue here and your log file will be clearedwriteToLogFile('reading: ' .$line."\n");
}closeLogFile();

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