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

Copy
1<?php
2
3/**
4 * LimitIteratorとSeekableIterator::seekの使用例
5 *
6 * このサンプルコードは、イテレータの一部を切り出すLimitIteratorで、
7 * SeekableIteratorインターフェースのseek()メソッドを使い、
8 * 特定の位置に直接移動する方法を示します。
9 */
10function demonstrateLimitIteratorSeek(): void
11{
12    // 1. 元となるデータソース（配列）
13    $data = [
14        'a' => 'Apple',
15        'b' => 'Banana',
16        'c' => 'Cherry',     // LimitIteratorの開始点 (オフセット 2)
17        'd' => 'Date',
18        'e' => 'Elderberry',
19        'f' => 'Fig',        // この範囲の最後の要素 (カウント 4)
20        'g' => 'Grape',
21    ];
22
23    // 2. 配列からSeekableなArrayIteratorを作成します
24    $arrayIterator = new ArrayIterator($data);
25
26    // 3. ArrayIteratorの一部を扱うLimitIteratorを作成します
27    // オフセット 2 ('Cherry') から 4 つの要素を対象とします
28    // 対象範囲: ['c' => 'Cherry', 'd' => 'Date', 'e' => 'Elderberry', 'f' => 'Fig']
29    $limitIterator = new LimitIterator($arrayIterator, 2, 4);
30
31    echo "--- LimitIteratorの対象範囲 ---" . PHP_EOL;
32    foreach ($limitIterator as $key => $value) {
33        // getPosition()はLimitIterator内での相対的な位置 (0から始まる) を返します
34        // key()は元のイテレータのキーを返します
35        echo sprintf(
36            "Position: %d, Key: %s, Value: %s" . PHP_EOL,
37            $limitIterator->getPosition(),
38            $key,
39            $value
40        );
41    }
42    echo PHP_EOL;
43
44    // 4. seek()メソッドでLimitIterator内の特定の位置（position）に移動します
45    // LimitIteratorのインデックスは0から始まります。
46    // seek(2)は、対象範囲内の3番目の要素 ('Elderberry') を指します。
47    $positionToSeek = 2;
48    echo "--- seek({$positionToSeek}) を実行 ---" . PHP_EOL;
49
50    // seek()を実行します。このメソッドはSeekableIteratorインターフェースで定義されています。
51    $limitIterator->seek($positionToSeek);
52
53    // 5. seek()後の現在の要素を確認します
54    if ($limitIterator->valid()) {
55        echo "seek() 後の現在地:" . PHP_EOL;
56        echo sprintf(
57            "Position: %d, Key: %s, Value: %s" . PHP_EOL,
58            $limitIterator->getPosition(),
59            $limitIterator->key(),
60            $limitIterator->current()
61        );
62    } else {
63        echo "位置 {$positionToSeek} は範囲外のため、移動できませんでした。" . PHP_EOL;
64    }
65}
66
67// 関数を実行して結果を表示します
68demonstrateLimitIteratorSeek();

LimitIterator::seek()は、イテレータの内部ポインタ（現在位置）を、指定した位置へ直接移動させるためのメソッドです。この機能は SeekableIterator インターフェースで定義されており、LimitIterator はこのインターフェースを実装しているため seek() を呼び出すことができます。

引数 $position には、移動したい位置を0から始まる整数で指定します。この位置は、LimitIterator が元のイテレータから切り取った範囲内での相対的なインデックスです。元のデータのキーやオフセットとは異なる点に注意が必要です。PHP 8以降、このメソッドは値を返さない（void）ため、指定した位置が有効範囲内にあるかは、seek() 実行後に valid() メソッドを使って確認します。

サンプルコードでは、配列から作成した ArrayIterator の一部（オフセット2から4要素）を LimitIterator で扱います。ここで seek(2) を実行すると、この切り出された範囲内の0から数えて2番目、つまり3番目の要素である 'Elderberry' の位置へポインタが移動します。移動後は、current() メソッドでその要素の値を取得できます。

Copy
1<?php
2
3/**
4 * LimitIterator::seek を使ってイテレータの最後の要素に移動する例
5 *
6 * キーワード `seek_end` は、最後の要素への移動を意図していると解釈し、
7 * イテレータが扱う要素数を元に最後の位置を計算して seek() を実行します。
8 */
9function demonstrateLimitIteratorSeekEnd(): void
10{
11    // 1. 元となるデータの配列
12    $fruits = ['Apple', 'Banana', 'Cherry', 'Durian', 'Elderberry', 'Fig', 'Grape'];
13
14    // 2. 配列から ArrayIterator を作成
15    $arrayIterator = new ArrayIterator($fruits);
16
17    // 3. ArrayIterator の一部分のみを扱う LimitIterator を作成
18    // この例では、インデックス 2 ('Cherry') から 4 つの要素を対象とします。
19    // 対象範囲: ['Cherry', 'Durian', 'Elderberry', 'Fig']
20    $limitIterator = new LimitIterator($arrayIterator, 2, 4);
21
22    // 4. LimitIterator が実際に扱う要素の数を取得
23    // iterator_count() はイテレータを最後まで進めるため、後で巻き戻しが必要です。
24    $count = iterator_count($limitIterator);
25    $limitIterator->rewind(); // イテレータを先頭に戻す
26
27    // 5. 最後の要素のインデックスを計算 (0から始まるため、要素数 - 1)
28    // 要素数が 4 の場合、最後のインデックスは 3
29    if ($count > 0) {
30        $lastPosition = $count - 1;
31
32        // 6. seek() メソッドで最後の要素の位置に移動
33        $limitIterator->seek($lastPosition);
34
35        // 7. 現在の要素 (最後の要素) を取得して表示
36        echo "対象範囲: ['Cherry', 'Durian', 'Elderberry', 'Fig']" . PHP_EOL;
37        echo "最後の要素の位置 ($lastPosition) に移動しました。" . PHP_EOL;
38        echo "最後の要素: " . $limitIterator->current() . PHP_EOL;
39    } else {
40        echo "LimitIterator の対象範囲に要素はありません。" . PHP_EOL;
41    }
42}
43
44// 関数を実行します
45demonstrateLimitIteratorSeekEnd();
46

LimitIterator::seekメソッドは、LimitIteratorが扱う要素の範囲内で、指定した位置に内部ポインタを移動させる機能を提供します。

サンプルコードは、このseekメソッドを使って対象範囲内の「最後の要素」に移動する手順を示したものです。PHPのseekメソッドには直接最後の要素を指定する定数などがないため、まずiterator_count関数を使ってLimitIteratorが実際に扱っている要素の総数を取得します。iterator_count関数は内部でイテレータを最後まで進めてしまうため、実行後にはrewindメソッドでポインタを先頭に戻す必要があります。

次に、取得した要素数から1を引くことで、0から始まるインデックスにおける最後の要素の位置を計算します。この計算結果をseekメソッドの引数$positionに渡すことで、ポインタを目的の最後の要素へ正確に移動させることができます。引数$positionには、移動したい位置を0から始まる整数で指定します。PHP 8のseekメソッドは値を返さない仕様（戻り値はvoid）です。