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

Copy
1<?php
2
3/**
4 * CallbackFilterIterator の getInnerIterator メソッドの使用例を示します。
5 *
6 * CallbackFilterIterator は、指定されたコールバック関数に基づいてイテレータの要素をフィルタリングします。
7 * getInnerIterator メソッドは、フィルタリングされる前の元のイテレータを返します。
8 *
9 * この例では、フルーツ名のリストから「grape」を含む要素のみをフィルタリングし、
10 * その後、getInnerIterator を使ってフィルタリング前の全要素を持つ元のイテレータを取得し、表示します。
11 */
12
13// 1. 元のデータ配列を用意します。
14$fruits = [
15    'apple',
16    'banana',
17    'orange',
18    'white grape',
19    'grapefruit',
20    'strawberry',
21];
22
23// 2. ArrayIterator を使って、元のデータ配列をイテレータ（内部イテレータ）に変換します。
24// これが CallbackFilterIterator によってラップされ、フィルタリングされる対象となります。
25$innerIterator = new ArrayIterator($fruits);
26
27// 3. フィルタリングのためのコールバック関数を定義します。
28// この関数は、現在の要素に「grape」という文字列が含まれている場合に true を返します。
29$filterCallback = function (string $currentValue, string $key, Iterator $iterator): bool {
30    return strpos($currentValue, 'grape') !== false;
31};
32
33// 4. CallbackFilterIterator のインスタンスを作成します。
34// 内部イテレータとフィルタリング用のコールバック関数を渡します。
35$filteredIterator = new CallbackFilterIterator($innerIterator, $filterCallback);
36
37echo "--- フィルタリングされたフルーツ (CallbackFilterIterator) ---" . PHP_EOL;
38// filteredIterator を反復処理すると、フィルタリングされた要素のみが表示されます。
39foreach ($filteredIterator as $fruit) {
40    echo $fruit . PHP_EOL;
41}
42
43echo PHP_EOL;
44
45// 5. getInnerIterator メソッドを呼び出し、フィルタリング前の元のイテレータを取得します。
46// このメソッドは、CallbackFilterIterator がラップしているオリジナルのイテレータを返します。
47$originalInnerIterator = $filteredIterator->getInnerIterator();
48
49echo "--- getInnerIterator で取得した元のフルーツ (全要素) ---" . PHP_EOL;
50// originalInnerIterator を反復処理すると、フィルタリング前のすべての要素が表示されます。
51foreach ($originalInnerIterator as $fruit) {
52    echo $fruit . PHP_EOL;
53}
54
55?>

CallbackFilterIterator::getInnerIteratorメソッドは、PHP 8で利用可能なCallbackFilterIteratorクラスに属するメソッドです。CallbackFilterIteratorは、指定されたコールバック関数に基づいてイテレータの要素をフィルタリングする際に使用します。

このgetInnerIteratorメソッドは、引数なしで呼び出すことができ、CallbackFilterIteratorが内部に保持している、フィルタリング前の元のイテレータをIteratorオブジェクトとして返します。これにより、フィルタリングされた結果だけでなく、フィルタリング処理を行う前のすべてのデータにアクセスすることが可能になります。

サンプルコードでは、まずフルーツ名の配列をArrayIteratorでイテレータ化し、これを内部イテレータとしています。次に、「grape」という文字列を含む要素のみを抽出するコールバック関数を定義し、この内部イテレータとコールバック関数を使ってCallbackFilterIteratorを作成しています。CallbackFilterIteratorを直接反復処理すると、定義した条件に基づいてフィルタリングされた要素のみが表示されます。

しかし、フィルタリング前の元の全要素が必要な場合は、$filteredIterator->getInnerIterator()を呼び出すことで、元のArrayIteratorインスタンスが返されます。この返されたイテレータを反復処理すると、フィルタリング条件にかかわらず、元の配列に含まれるすべてのフルーツ名が表示されます。このように、getInnerIteratorは、フィルタリングの前後で異なるイテレータの状態を柔軟に利用したい場合に役立つメソッドです。

Copy
1<?php
2
3/**
4 * ジェネレータ関数を定義します。
5 * ジェネレータは、メモリ効率よく大きなデータセットを扱うためのイテレータを簡単に作成するPHPの機能です。
6 * yieldキーワードを使って、要素を一つずつ生成します。
7 */
8function dataGenerator(): Generator
9{
10    yield 'apple';
11    yield 'banana';
12    yield 'orange';
13    yield 'grape';
14    yield 'strawberry';
15}
16
17/**
18 * フィルタリング用のコールバック関数を定義します。
19 * この関数はCallbackFilterIteratorによって内部イテレータの各要素に適用され、
20 * trueを返すとその要素は許可され、falseを返すとフィルタリングされます。
21 * 例として、文字数が5より大きいフルーツのみを許可します。
22 *
23 * @param string $current 現在の要素の値
24 * @param string $key 現在の要素のキー
25 * @param Iterator $iterator 現在のイテレータオブジェクト
26 * @return bool フィルタリングを通過させる場合はtrue、それ以外はfalse
27 */
28$filterCallback = function (string $current, string $key, Iterator $iterator): bool {
29    return strlen($current) > 5;
30};
31
32/**
33 * ジェネレータをCallbackFilterIteratorでラップします。
34 * CallbackFilterIteratorは、内部のイテレータとフィルタリングのロジック（コールバック関数）を受け取ります。
35 * ここでは、dataGenerator() を呼び出して得られるGeneratorオブジェクトを直接渡しています。
36 */
37$filteredIterator = new CallbackFilterIterator(dataGenerator(), $filterCallback);
38
39echo "--- フィルタリングされたイテレータ (CallbackFilterIterator) の要素 ---" . PHP_EOL;
40// $filteredIterator をイテレートすると、コールバック関数でフィルタリングされた要素のみが表示されます。
41foreach ($filteredIterator as $item) {
42    echo $item . PHP_EOL; // 出力: banana, orange, strawberry
43}
44
45echo PHP_EOL;
46
47/**
48 * CallbackFilterIterator::getInnerIterator() メソッドを使用して、元の内部イテレータを取得します。
49 * このメソッドは、CallbackFilterIteratorのコンストラクタに渡されたオリジナルのイテレータオブジェクトを返します。
50 * 今回の場合、それは dataGenerator() によって生成されたGeneratorオブジェクトです。
51 */
52$originalInnerIterator = $filteredIterator->getInnerIterator();
53
54echo "--- getInnerIterator() で取得した元のイテレータ (Generator) の要素 ---" . PHP_EOL;
55// 注意: ジェネレータは一度しかイテレートできません。
56// 上記のforeachループで $filteredIterator をイテレートした際、
57// その内部にあるジェネレータ（$originalInnerIterator と同じオブジェクト）も既に消費され、末尾に達しています。
58// そのため、このままでは何も出力されません。
59foreach ($originalInnerIterator as $item) {
60    // このループは何も出力しません
61}
62echo "(元のイテレータは既に消費されているため、このループでは何も表示されません。)" . PHP_EOL;
63
64echo PHP_EOL;
65
66/**
67 * 比較のために、再度新しいジェネレータインスタンスを作成し、
68 * フィルタリングされる前の全データを確認します。
69 * これは、getInnerIterator() が返したオブジェクトが、本来どのようなデータを提供していたかを示します。
70 */
71echo "--- フィルタリングされていない元のデータ (新しいGeneratorインスタンス) ---" . PHP_EOL;
72foreach (dataGenerator() as $item) {
73    echo $item . PHP_EOL; // 出力: apple, banana, orange, grape, strawberry
74}

このサンプルコードは、PHPのイテレータ機能であるCallbackFilterIteratorとそのgetInnerIteratorメソッドの利用方法を示しています。まず、dataGenerator関数で文字列を順に生成するジェネレータ（イテレータの一種）を作成し、メモリ効率の良いデータ処理を実現します。次に、$filterCallback関数で「文字数が5より大きい要素のみを許可する」というフィルタリングルールを定義します。

CallbackFilterIteratorは、このジェネレータとフィルタリングコールバック関数を受け取り、元のデータを条件に基づいてフィルタリングします。foreachループで$filteredIteratorを処理すると、フィルタリングされた要素のみが表示されます。

CallbackFilterIterator::getInnerIterator()メソッドは、引数を取らず、このCallbackFilterIteratorオブジェクトが内部でラップしている元のイテレータを返します。今回のケースでは、dataGenerator()が生成したGeneratorオブジェクトがそれに該当します。戻り値はIteratorインターフェースです。

しかし、ジェネレータは一度イテレートされると、その状態が最後まで進んでしまう特性があります。そのため、$filteredIteratorをforeachでイテレートした時点で、内部のジェネレータも既に消費され尽くしています。したがって、getInnerIterator()で取得した$originalInnerIteratorを再度イテレートしようとしても、表示されるデータはありません。このメソッドは、フィルタリングされたイテレータから、元の未加工のイテレータオブジェクトにアクセスしたい場合に利用できます。