【PHP8.x】rewindメソッドの使い方

Copy
1<?php
2
3/**
4 * rewind() メソッドの動作を示すサンプルコード。
5 *
6 * Generator::rewind() メソッドは、ジェネレータを最初の状態にリセットし、
7 * 再び最初から値を生成できるようにします。
8 * これは、特にファイル処理やデータセットの複数回パスなど、
9 * 同じデータストリームを複数回処理する必要がある場合に役立ちます。
10 */
11function generateSimpleSequence(): Generator
12{
13    echo "--- ジェネレータが開始/リワインドされました ---\n";
14    for ($i = 1; $i <= 3; $i++) {
15        echo "値を生成: " . $i . "\n";
16        yield $i;
17    }
18    echo "--- ジェネレータが終了しました ---\n";
19}
20
21// ジェネレータのインスタンスを作成
22$myGenerator = generateSimpleSequence();
23
24echo "### 最初のイテレーション ###\n";
25foreach ($myGenerator as $value) {
26    echo "消費された値: " . $value . "\n";
27}
28
29echo "\nrewind() を呼び出してジェネレータをリセットします...\n";
30// rewind() メソッドを呼び出すことで、ジェネレータは初期状態に戻ります。
31// これにより、値を最初から再度イテレートできるようになります。
32$myGenerator->rewind();
33
34echo "\n### rewind() 後の2回目のイテレーション ###\n";
35foreach ($myGenerator as $value) {
36    echo "消費された値: " . $value . "\n";
37}
38
39echo "\nサンプルが完了しました。\n";

PHP 8のGenerator::rewind()メソッドは、一度値を生成し終えたジェネレータを、最初の状態にリセットする機能を提供します。これにより、ジェネレータを最初から再び利用し、値を生成できるようになります。このメソッドは引数を取らず、戻り値もありません（void）。

通常、ジェネレータは一度値を生成し終えると終了し、再度同じデータストリームを最初から取得することはできません。しかし、rewind()メソッドを呼び出すことで、ジェネレータの内部状態が初期化され、まるで新しく作成されたかのように振る舞います。

サンプルコードでは、まずgenerateSimpleSequence関数で作成したジェネレータを最初のforeachループで消費します。その際、ジェネレータは「値を生成: 1, 2, 3」と順に値を出力します。ループが終了すると、ジェネレータは値をすべて生成し終えた状態です。

次に$myGenerator->rewind()を呼び出すことで、ジェネレータは初期状態にリセットされます。これにより、2回目のforeachループでは、再び「値を生成: 1, 2, 3」と最初から値が生成され、消費される様子が確認できます。この機能は、ファイルの内容やデータセットなど、同じデータストリームを複数回処理する必要がある場合に非常に役立ちます。

Copy
1<?php
2
3/**
4 * Generator::rewind() メソッドの動作を示すサンプルコード。
5 * PHPのジェネレータはシングルパスイテレータであるため、一度イテレーションが完了すると巻き戻すことはできません。
6 * rewind() メソッドは、ジェネレータがまだ開始されていない場合にのみ安全に呼び出せますが、
7 * その場合も実質的には何も動作しません。既に実行されたジェネレータに対して呼び出すと例外が発生します。
8 */
9
10/**
11 * 簡単なジェネレータ関数を定義します。
12 * yieldキーワードを使って値を順に生成します。
13 *
14 * @return Generator 生成された値を返します。
15 */
16function simpleGenerator(): Generator
17{
18    echo "  -> Generator started.\n";
19    yield 'Value 1';
20    echo "  -> Yielded 'Value 1'.\n";
21    yield 'Value 2';
22    echo "  -> Yielded 'Value 2'.\n";
23    echo "  -> Generator finished.\n";
24}
25
26/**
27 * Generator::rewind() の使用例と注意点を実行するメイン関数。
28 * システムエンジニアを目指す初心者向けに、ジェネレータの基本的な動作とrewind()の特性を説明します。
29 */
30function demonstrateGeneratorRewind(): void
31{
32    echo "--- Case 1: Rewind on a fresh (not yet started) generator ---\n";
33    // ジェネレータインスタンスを作成します。この時点ではまだジェネレータのコードは実行されていません。
34    $generator = simpleGenerator();
35
36    echo "1.1. Calling rewind() on a fresh generator (no-op expected).\n";
37    // Generator::rewind()を呼び出します。
38    // ジェネレータがまだ開始されていないため、この呼び出しは実質的には何も動作しません。
39    $generator->rewind();
40    echo "1.2. Rewind() called. No generator code executed yet.\n";
41
42    echo "1.3. Iterating the generator for the first time:\n";
43    foreach ($generator as $value) {
44        echo "  Received: " . $value . "\n";
45    }
46    echo "1.4. Generator iteration finished. Generator is now exhausted.\n\n";
47
48
49    echo "--- Case 2: Rewind on an exhausted (already run) generator ---\n";
50    // 既に一度実行し尽くされたジェネレータに対してrewind()を呼び出すと、エラーになります。
51    // これは、PHPのジェネレータが一度しかイテレーションできない性質のためです。
52    try {
53        echo "2.1. Attempting to call rewind() on an exhausted generator.\n";
54        $generator->rewind();
55        echo "2.2. Rewind() succeeded (このメッセージが表示されることはありません)。\n";
56    } catch (LogicException $e) {
57        echo "2.2. Caught expected exception: " . $e->getMessage() . "\n";
58        echo "    Explanation: PHPのジェネレータはシングルパスイテレータです。一度実行が完了すると、最初に戻る（巻き戻す）ことはできません。\n";
59        echo "    再度イテレーションを行うには、新しいジェネレータインスタンスを作成する必要があります。\n";
60    }
61
62    echo "\n--- Case 3: Creating a new generator to iterate again ---\n";
63    echo "3.1. Creating a new generator instance for re-iteration.\n";
64    $newGenerator = simpleGenerator();
65    echo "3.2. Iterating the new generator:\n";
66    foreach ($newGenerator as $value) {
67        echo "  Received: " . $value . "\n";
68    }
69    echo "3.3. New generator iteration finished.\n";
70}
71
72// サンプルコードを実行します。
73demonstrateGeneratorRewind();

PHPのGenerator::rewind()メソッドは、ジェネレータの内部ポインタを最初の要素に戻すことを意図していますが、引数はなく、戻り値もありません（void）。PHPのジェネレータは「シングルパスイテレータ」という特性を持ち、一度生成された値は順に消費され、イテレーションが完了するとそのジェネレータを最初からやり直すことはできません。

サンプルコードでは、このrewind()メソッドの挙動を詳しく示しています。まず、ジェネレータがまだ開始されていない状態でrewind()を呼び出しても、実際には何も処理は実行されず、ジェネレータは最初の状態を保ちます。その後、foreachループでイテレーションを開始すると、ジェネレータ関数が順に実行され、値が生成されます。

しかし、一度イテレーションが完了し、ジェネレータがすべての値を生成し尽くした後に同じジェネレータインスタンスに対してrewind()を呼び出そうとすると、LogicExceptionが発生します。これは、ジェネレータが一度しか通れない性質のためです。もし再度ジェネレータのシーケンスを最初から実行したい場合は、新しいジェネレータインスタンスを改めて作成する必要があります。Generator::rewind()は、既に実行中のジェネレータを最初からやり直す目的では使用できませんので、この点を理解しておくことが重要です。