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

Copy
1<?php
2
3// ArrayIterator は配列を反復処理するためのイテレータです。
4// SeekableIterator インターフェースを実装しており、seek() メソッドを使用することで、
5// 特定のオフセット（配列のインデックス）に直接移動できます。
6// これは、ループを最初から始めることなく、配列内の任意の位置にジャンプしたい場合に非常に便利です。
7
8$data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
9
10// ArrayIterator のインスタンスを作成し、操作したい配列を渡します。
11$iterator = new ArrayIterator($data);
12
13echo "元の配列の内容:\n";
14foreach ($data as $key => $value) {
15    echo "  キー: {$key}, 値: {$value}\n";
16}
17echo "\n";
18
19echo "ArrayIterator::seek() の使用例:\n";
20
21// 例1: オフセット 2 (3番目の要素) に移動します。
22// これにより、イテレータの内部ポインタが 'Cherry' の位置に設定されます。
23$offset_to_seek = 2;
24$iterator->seek($offset_to_seek);
25echo "オフセット {$offset_to_seek} にシークしました。\n";
26echo "  現在のキー: " . $iterator->key() . "\n";
27echo "  現在の値: " . $iterator->current() . "\n";
28echo "\n";
29
30// 例2: オフセット 0 (最初の要素) に移動します。
31// イテレータの内部ポインタが 'Apple' の位置に設定されます。
32$offset_to_seek = 0;
33$iterator->seek($offset_to_seek);
34echo "オフセット {$offset_to_seek} にシークしました。\n";
35echo "  現在のキー: " . $iterator->key() . "\n";
36echo "  現在の値: " . $iterator->current() . "\n";
37echo "\n";
38
39// 例3: オフセット 4 (最後の要素) に移動します。
40// イテレータの内部ポインタが 'Elderberry' の位置に設定されます。
41$offset_to_seek = 4;
42$iterator->seek($offset_to_seek);
43echo "オフセット {$offset_to_seek} にシークしました。\n";
44echo "  現在のキー: " . $iterator->key() . "\n";
45echo "  現在の値: " . $iterator->current() . "\n";
46echo "\n";
47
48?>

ArrayIteratorは、PHPで配列の要素を反復処理（ループで一つずつ取り出すこと）するための便利なクラスです。このクラスはSeekableIteratorインターフェースを実装しており、seekメソッドを使うことで、配列内の特定の要素に直接移動する機能を提供します。

seek(int $offset)メソッドは、引数として整数型の$offsetを受け取ります。この$offsetは、移動したい配列のインデックス（要素の順序を示す番号）を指定します。メソッドを実行すると、イテレータの内部ポインタが指定された$offsetの位置に移動し、その後の操作でその位置の要素にアクセスできるようになります。このメソッドは戻り値を返さず、イテレータの内部状態を直接変更します。

サンプルコードでは、まず$dataという配列をArrayIteratorに渡してインスタンスを作成しています。そして、$iterator->seek(2)と呼び出すことで、イテレータはインデックス2（配列の3番目の要素）である「Cherry」の位置に移動します。その後、key()やcurrent()メソッドで、現在の要素のキーと値を確認できます。同様にseek(0)で最初の要素「Apple」へ、seek(4)で最後の要素「Elderberry」へと移動しており、ループを最初から開始することなく、配列内の任意の場所に効率的にジャンプできることが示されています。

Copy
1<?php
2
3/**
4 * ArrayIterator::seek メソッドの使用例。
5 * 配列の特定のオフセット（インデックス）にイテレータの内部ポインタを移動させます。
6 * この例では、「seek_end」のキーワードに合わせて、配列の最後の要素にシークします。
7 */
8function demonstrateArrayIteratorSeek(): void
9{
10    // サンプルデータとなる配列を準備
11    $data = ['apple', 'banana', 'cherry', 'date', 'elderberry'];
12    echo "元の配列:\n";
13    foreach ($data as $index => $value) {
14        echo "- インデックス: {$index}, 値: {$value}\n";
15    }
16    echo "\n";
17
18    // ArrayIterator のインスタンスを作成
19    $iterator = new ArrayIterator($data);
20
21    // イテレータの初期位置を確認
22    echo "初期位置:\n";
23    echo "- 現在のキー: " . $iterator->key() . "\n";
24    echo "- 現在の値: " . $iterator->current() . "\n";
25    echo "\n";
26
27    // 配列の最後の要素のインデックスを計算
28    // seek() メソッドは0から始まるインデックスを受け取るため、count($data) - 1 となります。
29    $lastIndex = count($data) - 1;
30    echo "最後の要素のインデックス: {$lastIndex}\n";
31
32    try {
33        // seek() メソッドを使用して、イテレータを最後の要素のインデックスに移動
34        // 指定されたオフセットに内部ポインタを移動させます。
35        // オフセットが配列の範囲外の場合 (負の値、または配列の要素数以上) は
36        // OutOfBoundsException がスローされます。
37        $iterator->seek($lastIndex);
38
39        // シーク後の現在の位置を確認
40        echo "ArrayIterator::seek({$lastIndex}) 後:\n";
41        echo "- 現在のキー: " . $iterator->key() . "\n";
42        echo "- 現在の値: " . $iterator->current() . "\n";
43        echo "\n";
44
45        // さらに、一つ前の要素にシークすることも可能です
46        if ($lastIndex > 0) {
47            $prevIndex = $lastIndex - 1;
48            $iterator->seek($prevIndex);
49            echo "ArrayIterator::seek({$prevIndex}) (最後から2番目) 後:\n";
50            echo "- 現在のキー: " . $iterator->key() . "\n";
51            echo "- 現在の値: " . $iterator->current() . "\n";
52            echo "\n";
53        }
54
55    } catch (OutOfBoundsException $e) {
56        echo "エラー: 指定されたオフセットが配列の範囲外です。 " . $e->getMessage() . "\n";
57    }
58}
59
60// 関数を実行
61demonstrateArrayIteratorSeek();
62

ArrayIterator::seekメソッドは、PHP 8で利用できるArrayIteratorクラスの機能の一つです。このメソッドは、ArrayIteratorが内部的に持っているポインタ、つまり現在の要素を指し示す位置を、配列の特定のインデックス（オフセット）へ直接移動させるために使用されます。引数として整数型の$offsetを取り、これは0から始まる配列のインデックスを指定します。例えば、seek(0)と指定すれば最初の要素へ、seek(count($array) - 1)と指定すれば最後の要素へポインタを移動させることができます。このメソッド自体は戻り値を返しません。

サンプルコードでは、まずArrayIteratorを初期化し、その後seekメソッドを使用してイテレータのポインタを配列の最後の要素のインデックスに移動させています。これにより、通常のループで順にたどることなく、任意の要素に直接アクセスできるようになります。また、seekメソッドに配列の範囲外のインデックスを指定した場合、OutOfBoundsExceptionがスローされるため、例外処理を行うことで安全にコードを記述することが推奨されます。このように、ArrayIterator::seekメソッドは、コレクション内の特定の位置に効率的にアクセスしたい場合に非常に便利な機能です。