Generator::rewind

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

Generator::rewind — Retrocede o gerador para o primeiro "yield"

Descrição

public Generator::rewind(): void

O método retrocede o gerador para o ponto antes do primeiro yield. Se o gerador não estiver em uma primeira expressão yield quando este método é chamado, ele primeiramente irá avançar para a primeira expressão yield antes de retroceder. Se o gerador já estiver no ponto de início do segundo yield, uma exceção Exception será lançada.

Nota:
Este é o primeiro método chamado ao iniciar um laço foreach. Ele não será executado após os laços foreach.

Parâmetros

Esta função não possui parâmetros.

Valor Retornado

Nenhum valor é retornado.

Exemplos

Exemplo #1 Exemplo de Generator::rewind()

<?php

function generator(): Generator
{
    echo "Eu sou um gerador!\n";

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

// Inicializa o gerador
$generator = generator();

// Retrocede o gerador para o início da primeira expressão yield,
// se já não estava lá
$generator->rewind(); // Eu sou um gerador!

// Nada acontece aqui. O gerador já está retrocedido.
$generator->rewind(); // Sem saída (NULL)

// Isto retrocede o gerador para a primeira expressão yield,
// se já não estava lá, e itera sobre o gerador.
foreach ($generator as $value) {
    // Após gerar o primeiro valor, o gerador permanece na
    // primeira expressão yield até que continue a execução e avance ao próximo yield
    echo $value, PHP_EOL; // 1

    break;
}

// Continua e retrocede novamente. Nenhum erro ocorre porque o gerador não avançou além do primeiro yield
$generator->rewind();

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

// Nenhum erro ocorre, o gerador ainda está no primeiro yield
$generator->rewind();

// Isto avança o gerador para a segunda expressão yield
$generator->next();

try {
    // Aqui uma Exception é lançada
    // porque o gerador já avançou para o segundo yield
    $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
} catch (Exception $e) {
    echo $e->getMessage();
}

?>

O exemplo acima produzirá:

Eu sou um gerador!
1
1
Cannot rewind a generator that was already run

Melhore Esta Página

Aprenda Como Melhorar Esta Página • Envie uma Solicitação de Modificação • Reporte um Problema

＋adicionar nota

Notas de Usuários 1 note

down

i'm pati on stackoverflow ¶

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. 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.

＋adicionar nota