Generator::rewind

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

Generator::rewind — イテレータを最初の yield まで巻き戻す

説明

public Generator::rewind(): void

このメソッドはジェネレーターを最初の yield の前のポイントまで巻き戻します。このメソッドがコールされた際に、ジェネレーターが最初の yield 式に達していない場合、巻き戻す前に最初の yield まで進めます。ジェネレーターが既に二番目の yield の始点に達している場合は Exception がスローされます。

注意:
これは、foreach ループを開始する際に 最初に コールされるメソッドです。foreach ループが実行された後に実行されるのでは ありません。

パラメータ

この関数にはパラメータはありません。

戻り値

値を返しません。

例

例1 Generator::rewind() の例

<?php

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

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

// ジェネレータを初期化
$generator = generator();

// まだ達していない場合、最初の yield 式の開始までジェネレータを巻き戻します。
$generator->rewind(); // I'm a generator!

// ここでは何も起きません; ジェネレータは既に巻き戻されています。
$generator->rewind(); // No output (NULL)

// ここでは、まだ達していない場合、
// 最初の yield 式の開始までジェネレータを巻き戻します。
// そして、ジェネレータを反復します。
foreach ($generator as $value) {
    // 最初の値を yield したあと、ジェネレータは
    // 実行が再開されて次の yield に進むまで最初の
    // yield 式にとどまったままです。
    echo $value, PHP_EOL; // 1

    break;
}

// 巻き戻しを再開します。
// エラーは発生しません。なぜんら、ジェネレータは最初の yield を越えて
// 進んでいないからです。
$generator->rewind();

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

// エラーは起きません。
// ジェネレータはまだ最初の yield に留まっています。
$generator->rewind();

// ここで、ジェネレータを二回目の yield 式に進めます。
$generator->next();

try {
    // これは、例外をスローします。
    // なぜなら、既にジェネレータが二回目の yield に進んでいるからです。
    $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
} catch (Exception $e) {
    echo $e->getMessage();
}

?>

上の例の出力は以下となります。

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