【PHP8.x】AppendIterator::rewind()メソッドの使い方

Copy
1<?php
2
3/**
4 * A simple generator function that yields a sequence of numbers.
5 *
6 * Standard PHP generators are not inherently rewindable; once fully iterated,
7 * attempting to rewind the same generator instance will result in a RuntimeException.
8 */
9function numberGenerator(): Generator
10{
11    echo "  (Generator: Starting)\n";
12    for ($i = 1; $i <= 3; $i++) {
13        yield $i;
14    }
15    echo "  (Generator: Finished)\n";
16}
17
18// Create an AppendIterator to combine multiple iterators into a single sequence.
19$appendIterator = new AppendIterator();
20
21// 1. Add a standard ArrayIterator. ArrayIterators are inherently rewindable.
22$arrayIterator = new ArrayIterator(['A', 'B', 'C']);
23$appendIterator->append($arrayIterator);
24
25// 2. Add a fresh instance of our generator.
26// At this point, the generator has not started, so it can be iterated from its beginning.
27$generator = numberGenerator();
28$appendIterator->append($generator);
29
30echo "--- First Iteration ---\n";
31// Iterate through all appended iterators.
32// Both the ArrayIterator and the Generator will be consumed.
33foreach ($appendIterator as $value) {
34    echo "Value: " . $value . "\n";
35}
36
37echo "\n--- Attempting to rewind and iterate again ---\n";
38try {
39    // Calling rewind() on AppendIterator attempts to reset all its appended iterators
40    // to their initial state.
41    // - The ArrayIterator will successfully rewind.
42    // - The Generator, having been fully consumed in the first iteration,
43    //   will throw a RuntimeException because standard PHP generators
44    //   cannot be rewound once they have started yielding values.
45    $appendIterator->rewind();
46    echo "AppendIterator successfully rewound (this line might not be reached if an exception occurs).\n";
47
48    echo "\n--- Second Iteration (attempt) ---\n";
49    foreach ($appendIterator as $value) {
50        echo "Value: " . $value . "\n";
51    }
52} catch (RuntimeException $e) {
53    echo "Error during rewind or second iteration: " . $e->getMessage() . "\n";
54    echo "This illustrates that standard PHP generators are not 'rewindable' in the sense\n";
55    echo "that you cannot reset them to their beginning and re-iterate the *same instance*\n";
56    echo "once they have started. To achieve 'rewindable generator' behavior with AppendIterator\n";
57    echo "for multiple passes, one would typically need to append a *new* generator instance\n";
58    echo "for each pass, or use a custom iterator wrapper that manages generator re-creation.\n";
59}

PHPのAppendIteratorは、複数のイテレータを一つにまとめて順次処理するためのクラスです。このAppendIterator::rewind()メソッドは、AppendIteratorに結合されているすべてのイテレータを、それぞれの初期状態（先頭）に巻き戻そうとします。このメソッドは引数を取らず、戻り値もありません。

サンプルコードでは、AppendIteratorに「巻き戻し可能なArrayIterator」と「標準のGenerator」を結合しています。最初のイテレーションでは、両方のイテレータから値が順に取得されます。その後、$appendIterator->rewind()が呼び出されると、ArrayIteratorは正常に巻き戻されますが、一度最後まで処理された標準のGeneratorは、その特性上、初期状態に戻すことができません。このためRuntimeExceptionが発生し、二度目のイテレーションは実行されません。

これは、PHPの標準ジェネレータが、一度値を生成し始めるとその同じインスタンスを再度最初から繰り返し利用できる「巻き戻し可能（rewindable）」な特性を持たないことを示しています。もしジェネレータを再度利用したい場合は、通常、新しいジェネレータインスタンスを生成する必要があります。

Copy
1<?php
2
3/**
4 * AppendIterator::rewind() メソッドの動作を示すサンプルコード。
5 * このメソッドは、複数のイテレータを連結した AppendIterator のポインタを先頭に戻します。
6 */
7
8// 最初のイテレータを作成します。
9$arrayIterator1 = new ArrayIterator(['Apple', 'Banana', 'Cherry']);
10
11// 2番目のイテレータを作成します。
12$arrayIterator2 = new ArrayIterator(['Dog', 'Elephant', 'Frog']);
13
14// AppendIterator のインスタンスを作成します。
15$appendIterator = new AppendIterator();
16
17// 各イテレータを AppendIterator に追加します。
18$appendIterator->append($arrayIterator1);
19$appendIterator->append($arrayIterator2);
20
21echo "--- 最初のイテレーション ---\n";
22// AppendIterator をループして、すべての要素を表示します。
23// これにより、イテレータの内部ポインタが最後に進みます。
24foreach ($appendIterator as $item) {
25    echo "要素: " . $item . "\n";
26}
27
28echo "\n--- rewind() の呼び出し ---\n";
29// AppendIterator のポインタを最初の位置に戻します。
30// このメソッドを呼び出さないと、次のループは何も表示しません。
31$appendIterator->rewind();
32
33echo "\n--- rewind() 後、2回目のイテレーション ---\n";
34// 再度 AppendIterator をループして、rewind() が正しく動作したことを確認します。
35// ポインタが先頭に戻っているため、最初の要素から再度表示されます。
36foreach ($appendIterator as $item) {
37    echo "要素: " . $item . "\n";
38}
39
40?>

このPHPのサンプルコードは、AppendIteratorクラスのrewind()メソッドの動作を示しています。AppendIteratorは、複数のイテレータ（ここではArrayIterator）を連結し、それらをまるで一つのイテレータであるかのように順次処理するためのものです。

コードではまず、二つのArrayIteratorが作成され、それらがAppendIteratorに追加されます。最初のループでは、追加されたすべての要素が「Apple」から「Frog」まで順に表示され、この処理が完了するとAppendIteratorの内部ポインタはデータの終端に到達します。

AppendIterator::rewind()メソッドは、この内部ポインタを先頭の位置に戻すために使用されます。このメソッドは引数を取らず、特定の値を戻り値として返すこともありません。もしrewind()を呼び出さずに再度ループを実行しようとすると、ポインタが終端にあるため、何も表示されません。

サンプルコードでは、rewind()が呼び出された後、二回目のループで再び「Apple」からすべての要素が表示されることを確認しています。これにより、rewind()がイテレータのポインタを正常に先頭に戻し、一度最後まで走査したイテレータを最初から再利用可能にすることが実証されています。このメソッドは、イテレータの再利用に不可欠な操作です。