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

Copy
1<?php
2
3// PHP 8: NoRewindIterator::getInnerIterator() のサンプルコード
4
5// システムエンジニアを目指す初心者向けに、
6// NoRewindIterator クラスが内部で保持している「元のイテレータ」を
7// getInnerIterator() メソッドで取得する方法を示します。
8
9// 1. まず、処理したいデータを持つシンプルなイテレータ（ArrayIterator）を作成します。
10//    これが NoRewindIterator がラップする「元のイテレータ」になります。
11$data = ['Apple', 'Banana', 'Cherry'];
12$originalIterator = new ArrayIterator($data);
13
14echo "--- 元のイテレータの内容 ---\n";
15foreach ($originalIterator as $key => $value) {
16    echo "キー: {$key}, 値: {$value}\n";
17}
18echo "\n";
19
20// 2. この元のイテレータを NoRewindIterator でラップします。
21//    NoRewindIterator は、内部のイテレータの rewind() メソッドが
22//    自動で呼び出されるのを防ぐ、特殊なイテレータです。
23$noRewindIterator = new NoRewindIterator($originalIterator);
24
25// NoRewindIterator を一度イテレートすると、その内部イテレータのポインタが進みます。
26echo "--- NoRewindIterator を一度イテレート ---\n";
27foreach ($noRewindIterator as $key => $value) {
28    echo "キー: {$key}, 値: {$value}\n";
29}
30echo "\n";
31
32// 3. NoRewindIterator::getInnerIterator() を使用して、
33//    NoRewindIterator がラップしていた「元のイテレータ」を取得します。
34$retrievedInnerIterator = $noRewindIterator->getInnerIterator();
35
36echo "--- getInnerIterator() で取得したイテレータの内容 ---\n";
37// 取得されたイテレータは、NoRewindIterator にラップされる前の
38// $originalIterator と同じインスタンスであり、その現在の状態を反映しています。
39// 上で NoRewindIterator をイテレートしたため、このイテレータのポインタも最後に到達しています。
40// したがって、再度最初から内容を見るためには rewind() メソッドを呼び出す必要があります。
41$retrievedInnerIterator->rewind(); // イテレータのポインタを先頭に巻き戻します。
42foreach ($retrievedInnerIterator as $key => $value) {
43    echo "キー: {$key}, 値: {$value}\n";
44}
45echo "\n";
46

PHP 8のNoRewindIterator::getInnerIterator()メソッドは、NoRewindIteratorが内部で保持する「元のイテレータ」を取得する際に用います。NoRewindIteratorは、foreachループ開始時などにイテレータのポインタが自動的に先頭へ戻される（rewind()が呼ばれる）のを防ぐ、特殊なイテレータです。

このサンプルコードでは、ArrayIteratorで作成したデータイテレータをNoRewindIteratorでラップしています。NoRewindIteratorを一度イテレートすると、その内部の「元のイテレータ」のポインタも進みます。

getInnerIterator()メソッドは引数なしで呼び出し、Iterator型の戻り値として、ラップされていた「元のイテレータ」のインスタンスを返します。このとき取得されるイテレータは、NoRewindIteratorを介して進められたポインタの状態をそのまま反映しています。したがって、再び最初からデータを読み込むには、取得したイテレータに対し明示的にrewind()メソッドを呼び出す必要があります。これにより、イテレータの状態を細かく制御できます。

Copy
1<?php
2
3/**
4 * NoRewindIterator::getInnerIterator() メソッドの使用例を示します。
5 *
6 * この関数は、ジェネレータを NoRewindIterator でラップし、
7 * その後 getInnerIterator() を使って元のジェネレータを取り出し、
8 * イテレータが状態を共有していることをデモンストレーションします。
9 *
10 * NoRewindIterator は、内部イテレータの rewind() メソッドが呼び出されるのを防ぐイテレータです。
11 * ジェネレータは一度しかイテレートできない（rewind()がサポートされないか無意味な）性質を持つため、
12 * NoRewindIterator と非常に相性が良いです。
13 */
14function demonstrateNoRewindIteratorWithGenerator(): void
15{
16    /**
17     * 3つの数値を順に生成するシンプルなジェネレータ関数を定義し、
18     * その Generator オブジェクトを $myGenerator に格納します。
19     * 各値を生成する際にメッセージを出力します。
20     */
21    $myGenerator = (function (int $start, int $end): Generator {
22        for ($i = $start; $i <= $end; $i++) {
23            echo "  [オリジナルジェネレータ] " . $i . " を生成中..." . PHP_EOL;
24            yield $i;
25        }
26    })(1, 3); // 開始と終了の値を指定してジェネレータを初期化
27
28    echo "--- 1. オリジナルのジェネレータを作成しました ---" . PHP_EOL;
29    // 初期状態では、ジェネレータはまだ値を生成していません。
30    echo "  現在のジェネレータの状態: " . ($myGenerator->valid() ? $myGenerator->current() : "有効な値なし") . PHP_EOL;
31
32    // オリジナルのジェネレータを NoRewindIterator でラップします。
33    // これにより、NoRewindIterator は内部のジェネレータの rewimd() 呼び出しをブロックします。
34    $noRewindIterator = new NoRewindIterator($myGenerator);
35
36    echo PHP_EOL . "--- 2. NoRewindIterator を介して一部をイテレート ---" . PHP_EOL;
37    echo "  NoRewindIterator を使って最初の要素だけ取得します。" . PHP_EOL;
38    foreach ($noRewindIterator as $value) {
39        echo "  [NoRewindIterator] 取得した値: " . $value . PHP_EOL;
40        // 最初の要素でループを中断し、イテレータの内部状態を進めます。
41        if ($value === 1) {
42            echo "  最初の要素でループを中断しました。NoRewindIterator は次の要素に進んでいます。" . PHP_EOL;
43            break;
44        }
45    }
46
47    echo PHP_EOL . "--- 3. getInnerIterator() で元のジェネレータを取得 ---" . PHP_EOL;
48    // NoRewindIterator がラップしている元のジェネレータオブジェクトを取得します。
49    // これは、$myGenerator と同じインスタンスであり、同じ状態を共有しています。
50    $innerIterator = $noRewindIterator->getInnerIterator();
51
52    echo "  getInnerIterator() で取得した内部イテレータの現在値: " . ($innerIterator->valid() ? $innerIterator->current() : "有効な値なし") . PHP_EOL;
53    // 上の出力は "2" になるはずです。
54    // なぜなら、NoRewindIterator を介したイテレーションによって、
55    // 内部のジェネレータも既に「1」を通過して「2」の位置にいるためです。
56
57    echo PHP_EOL . "--- 4. 取得した内部イテレータで残りをイテレート ---" . PHP_EOL;
58    echo "  内部イテレータは、中断された位置からイテレーションを再開します。" . PHP_EOL;
59    foreach ($innerIterator as $value) {
60        echo "  [内部イテレータ] 取得した値: " . $value . PHP_EOL;
61    }
62
63    echo PHP_EOL . "--- 5. 全てのイテレーションが完了しました ---" . PHP_EOL;
64}
65
66// 関数を実行してデモンストレーションを開始します。
67demonstrateNoRewindIteratorWithGenerator();

PHP 8のNoRewindIterator::getInnerIterator()メソッドは、NoRewindIteratorがラップしている「内部のイテレータ」オブジェクトを取得するために利用されます。このメソッドは引数を必要とせず、内部に保持しているイテレータ（Iteratorインターフェースを実装するオブジェクト）をそのまま戻り値として返します。

NoRewindIteratorは、その名前が示す通り、内部のイテレータのrewind()メソッドが誤って呼び出されるのを防ぐ役割を持つイテレータです。ジェネレータのように、一度しかイテレーションできない性質を持つオブジェクトと組み合わせて使う際に特に有効です。

サンプルコードでは、まず数値を順に生成するシンプルなジェネレータを定義し、それをNoRewindIteratorでラップします。その後、NoRewindIteratorを使って最初の要素のみをイテレートし、途中で処理を中断しています。これにより、内部のジェネレータもその時点まで状態が進みます。

次に、getInnerIterator()メソッドを呼び出すことで、NoRewindIteratorが内部に持っていた元のジェネレータオブジェクトを取り出します。ここで取得されるジェネレータは、ラップする前のものと完全に同じインスタンスであり、イテレーションの状態を共有しています。そのため、取り出したジェネレータを使って残りの要素をイテレートすると、中断された位置から処理が再開され、残りの値が順に出力されます。このメソッドは、ラップされたイテレータの状態を元のイテレータとして直接操作する際に役立ちます。