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

Copy
1<?php
2
3/**
4 * ジェネレータはデフォルトで一度しかイテレーションできません（巻き戻し不可）。
5 * このクラスは、ジェネレータの出力を一度実行してすべてキャッシュすることで、
6 * 複数回のイテレーション（巻き戻し可能）を可能にする Iterator 実装です。
7 *
8 * システムエンジニアを目指す初心者の方へ:
9 * PHPのジェネレータはメモリ効率が良いですが、一度使い切ると最初からやり直せません。
10 * `Iterator`インターフェースを実装することで、`foreach`ループなどでイテレーション可能な
11 * オブジェクトを作成できます。このクラスは、その`Iterator`インターフェースを利用して
12 * ジェネレータを「巻き戻し可能」に変換する例です。
13 * `rewind()`メソッドは、イテレータを初期状態に戻すために使用されます。
14 */
15class RewindableGeneratorWrapper implements Iterator
16{
17    /**
18     * 新しい Generator インスタンスを返す callable (クロージャまたは関数名)。
19     * ジェネレータを再度生成するために使用します。
20     * @var callable
21     */
22    private $generatorFactory;
23
24    /**
25     * ジェネレータから取得した要素をキャッシュする配列。
26     * @var array<mixed>|null
27     */
28    private ?array $cachedData = null;
29
30    /**
31     * 現在のイテレーション位置。
32     * @var int
33     */
34    private int $position = 0;
35
36    /**
37     * コンストラクタ。
38     * @param callable $generatorFactory 新しい Generator インスタンスを返す callable。
39     *                                   `function(): Generator { ... yield ... }` の形式を想定します。
40     */
41    public function __construct(callable $generatorFactory)
42    {
43        $this->generatorFactory = $generatorFactory;
44    }
45
46    /**
47     * イテレータを最初の要素に巻き戻します。
48     * `foreach` ループが開始される時、または明示的に `rewind()` が呼び出された時に実行されます。
49     *
50     * ここでジェネレータを再生成して全要素をキャッシュするか、
51     * 既にキャッシュ済みの場合はポインタをリセットします。
52     *
53     * EmptyIterator::rewind とは異なり、このメソッドは状態をリセットするために具体的な処理を行います。
54     * EmptyIterator::rewind は空のイテレータなので何もする必要がありません。
55     */
56    public function rewind(): void
57    {
58        // まだデータがキャッシュされていない場合のみ、ジェネレータを実行して全要素をキャッシュします。
59        // これにより、ジェネレータは一度しか実行されず、その後のイテレーションはキャッシュから行われます。
60        if ($this->cachedData === null) {
61            $this->cacheGeneratorOutput();
62        }
63        // 現在のイテレーション位置をリセットします。
64        $this->position = 0;
65    }
66
67    /**
68     * ジェネレータファクトリを呼び出し、新しい Generator インスタンスから
69     * すべての要素を取得してキャッシュします。
70     */
71    private function cacheGeneratorOutput(): void
72    {
73        $this->cachedData = [];
74        // ファクトリを呼び出して新しいジェネレータインスタンスを取得
75        $generator = ($this->generatorFactory)();
76        foreach ($generator as $key => $value) {
77            $this->cachedData[$key] = $value;
78        }
79    }
80
81    /**
82     * 現在のイテレーション位置にある要素の値を返します。
83     * @return mixed
84     */
85    public function current(): mixed
86    {
87        return $this->cachedData[$this->position] ?? null;
88    }
89
90    /**
91     * 現在のイテレーション位置にある要素のキーを返します。
92     * @return int|string|null
93     */
94    public function key(): int|string|null
95    {
96        // この実装では、キャッシュ配列のインデックスをキーとして使用します。
97        return $this->position;
98    }
99
100    /**
101     * イテレーションを次の要素に進めます。
102     */
103    public function next(): void
104    {
105        $this->position++;
106    }
107
108    /**
109     * 現在のイテレーション位置が有効かどうかをチェックします。
110     * @return bool
111     */
112    public function valid(): bool
113    {
114        return isset($this->cachedData[$this->position]);
115    }
116}
117
118/**
119 * サンプルで使用するジェネレータ関数を定義します。
120 * 指定された数までの整数を生成します。
121 * @param int $limit 生成する数の上限。
122 * @return Generator
123 */
124function createNumberedGenerator(int $limit): Generator
125{
126    for ($i = 0; $i < $limit; $i++) {
127        echo "  [ジェネレータ] {$i} を生成中...\n";
128        yield $i;
129    }
130}
131
132// --- ジェネレータの基本的な挙動 (巻き戻し不可) ---
133echo "--- 1. 通常のジェネレータ (巻き戻し不可) のデモンストレーション ---\n";
134$simpleGenerator = createNumberedGenerator(3);
135
136echo "1回目のイテレーション:\n";
137foreach ($simpleGenerator as $value) {
138    echo "  [消費済み] 値: {$value}\n";
139}
140
141echo "2回目のイテレーションを試行（何も表示されないか、例外が発生するはず）:\n";
142try {
143    foreach ($simpleGenerator as $value) {
144        // 通常のジェネレータは、一度イテレーションを終えると空になり、
145        // rewind() は例外を投げるか、何も返さない。
146        echo "  [消費済み] 値: {$value}\n"; // ここには到達しない
147    }
148    // PHP 7 以降では、イテレーション終了後に foreach を再度実行しても例外は発生せず、単に何もしない。
149    // PHP 5.x では Generator::rewind() の呼び出しで例外が発生した。
150    echo "  (通常のジェネレータは一度消費されると空になります。)\n";
151} catch (Exception $e) {
152    echo "  !!! 例外発生: " . $e->getMessage() . " (ジェネレータは巻き戻しできません)\n";
153}
154echo "\n";
155
156
157// --- 巻き戻し可能なジェネレータの利用 ---
158echo "--- 2. RewindableGeneratorWrapper を使った巻き戻し可能なジェネレータ ---\n";
159
160// RewindableGeneratorWrapper に、ジェネレータを生成するクロージャを渡します。
161// このクロージャは、必要に応じて新しい Generator インスタンスを返す役割を担います。
162$rewindable = new RewindableGeneratorWrapper(function () {
163    return createNumberedGenerator(3);
164});
165
166echo "1回目のイテレーション:\n";
167foreach ($rewindable as $value) {
168    echo "  [Rewindable] 値: {$value}\n";
169}
170
171echo "2回目のイテレーション:\n";
172// foreach ループは内部的に rewind() を呼び出すため、最初からイテレーションが可能です。
173foreach ($rewindable as $value) {
174    echo "  [Rewindable] 値: {$value}\n";
175}
176echo "\n";
177
178
179// --- EmptyIterator との関連 ---
180echo "--- 3. EmptyIterator の利用例 (空のイテレータ) ---\n";
181// EmptyIterator は PHP の SPL (Standard PHP Library) で提供される特殊なイテレータです。
182// 名前が示す通り、常に空のイテレータを表します。
183// Iterator インターフェースを実装しているため rewind() メソッドを持ちますが、
184// 内部的には何もせず、常に空なのでイテレーションは行われません。
185
186$emptyIterator = new EmptyIterator();
187echo "EmptyIterator をインスタンス化し、rewind() を明示的に呼び出します。\n";
188$emptyIterator->rewind(); // 引数なし、戻り値なし (void) で、何もしません。
189echo "  (EmptyIterator::rewind は何もしません。)\n";
190
191echo "EmptyIterator を使ってイテレーションを試行（何も表示されないはず）:\n";
192foreach ($emptyIterator as $value) {
193    // EmptyIterator は常に空なので、このブロック内のコードは実行されません。
194    echo "  [EmptyIterator] 値: {$value}\n";
195}
196echo "  (EmptyIterator は要素を持たないため、何も出力されませんでした。)\n";
197
198echo "\n--- 4. 空のジェネレータを RewindableGeneratorWrapper でラップした場合 ---\n";
199// RewindableGeneratorWrapper が空のジェネレータをラップした場合の挙動は、
200// EmptyIterator の概念に近くなります。
201$emptyRewindable = new RewindableGeneratorWrapper(function () {
202    return createNumberedGenerator(0); // 何も生成しないジェネレータ
203});
204
205echo "1回目のイテレーション (空):\n";
206foreach ($emptyRewindable as $value) {
207    echo "  [空Rewindable] 値: {$value}\n";
208}
209echo "  (空のジェネレータなので、何も出力されませんでした。)\n";
210
211echo "2回目のイテレーション (空):\n";
212foreach ($emptyRewindable as $value) {
213    echo "  [空Rewindable] 値: {$value}\n";
214}
215echo "  (rewind されても、元のジェネレータが空なので何も出力されませんでした。)\n";
216
217?>

PHP 8のEmptyIteratorクラスは、SPL（Standard PHP Library）に属する、常に要素を持たない「空」のイテレータを表します。このクラスのrewindメソッドは、イテレータを初期状態に巻き戻すためのものですが、EmptyIteratorの特性上、特別な挙動をします。EmptyIterator::rewind()メソッドは引数を一切取らず、戻り値もありません（void型）が、その内部では具体的な処理を何も行いません。これは、イテレータが常に空であるため、状態をリセットしたり、最初の要素を準備したりする必要がないためです。foreachループなどでイテレーションを開始する際に自動的に呼び出されることもありますが、要素がないため、何も起こりません。サンプルコードでは、EmptyIteratorをインスタンス化し、rewind()を明示的に呼び出してその挙動を示しています。通常のイテレータがrewind()でデータを再ロードしたり位置をリセットするのに対し、EmptyIteratorは常に空であるため、単に何もしないことが特徴です。

Copy
1<?php
2
3/**
4 * EmptyIterator::rewind() メソッドのサンプルコード
5 *
6 * このコードは、PHPのEmptyIteratorクラスのrewind()メソッドの動作を示します。
7 * rewind()メソッドは、Iteratorインターフェースの一部であり、イテレータをその最初の要素に
8 * "巻き戻す" ことを目的としています。これは通常、foreachループの開始時など、
9 * イテレータを最初から再利用する際に内部的に呼び出されます。
10 *
11 * EmptyIteratorは、その名前の通り、要素を一切持たないイテレータです。
12 * そのため、rewind()メソッドを呼び出しても、イテレータの状態に目に見える変化は起こらず、
13 * 何の要素も指し示すことはありません。
14 *
15 * PHPにおいて、イテレータは配列のような反復可能なデータ構造を扱うための強力な仕組みです。
16 * EmptyIteratorは、特定の条件で「空のコレクション」を表す場合などに役立ちます。
17 */
18function demonstrateEmptyIteratorRewind(): void
19{
20    echo "--- EmptyIterator::rewind() メソッドのデモンストレーション ---\n\n";
21
22    // EmptyIterator のインスタンスを作成します。
23    // これは常に空のイテレータであり、どんな要素も持ちません。
24    $emptyIterator = new EmptyIterator();
25    echo "EmptyIterator のインスタンスが作成されました。\n";
26
27    // foreach ループを開始すると、イテレータの rewind() メソッドが自動的に呼び出されます。
28    // EmptyIterator は要素を持たないため、このループのブロックは一度も実行されません。
29    echo "foreach ループを開始します (内部で rewind() が自動的に呼び出されます)。\n";
30    $itemCount = 0;
31    foreach ($emptyIterator as $key => $value) {
32        // この行は、EmptyIterator が空であるため、決して表示されません。
33        echo "処理された要素: " . $value . "\n";
34        $itemCount++;
35    }
36    echo "foreach ループが終了しました。イテレートされた要素数: " . $itemCount . "\n\n";
37
38    // rewind() メソッドを直接呼び出す例。
39    // このメソッドは引数を取らず、戻り値もありません。
40    // EmptyIterator の場合、呼び出されても内部的な状態に変化は伴いません。
41    echo "EmptyIterator::rewind() を直接呼び出します。\n";
42    $emptyIterator->rewind();
43    echo "EmptyIterator::rewind() が呼び出されました。特に目に見える効果はありません。\n";
44    echo "EmptyIterator は、常に空のイテレータとして振る舞います。\n";
45}
46
47// デモンストレーションを実行
48demonstrateEmptyIteratorRewind();
49

このPHPコードは、EmptyIteratorクラスのrewind()メソッドの動作を説明しています。EmptyIteratorは、その名の通り、要素を一切持たない「空のイテレータ」です。イテレータとは、配列のように、内部のデータ要素を一つずつ順に処理するための仕組みです。

rewind()メソッドは、イテレータをその最初の要素の位置に「巻き戻す」役割を持っています。これは通常、foreachループが開始される際などに、イテレータを最初から使い始めるために内部的に自動で呼び出されます。

サンプルコードでは、まずEmptyIteratorのインスタンスを作成し、foreachループでイテレーションを試みています。しかし、EmptyIteratorは要素を持たないため、ループ本体は一度も実行されません。この際、rewind()メソッドが自動的に呼び出されていますが、特に目に見える変化はありません。

また、コード内で$emptyIterator->rewind()と直接呼び出す例も示されています。rewind()メソッドは引数を一切取らず、戻り値もありません。EmptyIteratorの場合、rewind()を呼び出しても、もともと要素が存在しないため、イテレータの状態に変化は起こらず、何の要素も指し示すことはありません。これは、空のコレクションを表現する際に使われるメソッドの典型的な挙動です。