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

Copy
1<?php
2
3/**
4 * SplObjectStorage::seek() メソッドの使用例を示します。
5 * seek() は、イテレータの内部ポインタを指定されたオフセット（位置）に移動させるために使用されます。
6 * SplObjectStorage は Iterator インターフェースを実装しており、seek() メソッドによって
7 * SeekableIterator のような振る舞いを提供し、コレクション内の特定の位置に直接移動することを可能にします。
8 */
9function demonstrateSplObjectStorageSeek(): void
10{
11    // SplObjectStorage のインスタンスを作成します。
12    // これはオブジェクトをキーとしてデータを格納する特殊なコレクションです。
13    $storage = new SplObjectStorage();
14
15    // いくつかのオブジェクトを作成し、ストレージにアタッチ（追加）します。
16    // attach() の第2引数は、各オブジェクトに紐づける追加情報です。
17    $obj1 = new stdClass();
18    $obj1->name = 'Object A';
19    $storage->attach($obj1, 'データ1');
20
21    $obj2 = new stdClass();
22    $obj2->name = 'Object B';
23    $storage->attach($obj2, 'データ2');
24
25    $obj3 = new stdClass();
26    $obj3->name = 'Object C';
27    $storage->attach($obj3, 'データ3');
28
29    echo "--- ストレージの初期状態 (foreachで順にアクセス) ---\n";
30    foreach ($storage as $object) {
31        // current() は現在のオブジェクト、getInfo() はそのオブジェクトに紐づけられたデータを返します。
32        echo "キー (オブジェクト名): " . $object->name . ", 値: " . $storage->getInfo() . "\n";
33    }
34    echo "\n";
35
36    echo "--- seek() を使用して特定の位置へ移動 ---\n";
37
38    // イテレータをオフセット 1 の位置にシークします (0-indexed)。
39    // これは2番目のオブジェクト ($obj2) を指すことになります。
40    $offsetToSeek = 1;
41    try {
42        $storage->seek($offsetToSeek);
43        echo "オフセット {$offsetToSeek} にシークしました。\n";
44
45        // シーク後の現在のオブジェクトとデータを取得します。
46        $currentObject = $storage->current();
47        $currentInfo = $storage->getInfo();
48        echo "現在のオブジェクト: " . ($currentObject ? $currentObject->name : 'N/A') . "\n";
49        echo "現在の値: " . ($currentInfo ?? 'N/A') . "\n";
50
51        // さらにオフセット 0 (最初のオブジェクト) にシークしてみます。
52        $offsetToSeek = 0;
53        $storage->seek($offsetToSeek);
54        echo "\nオフセット {$offsetToSeek} にシークしました。\n";
55        $currentObject = $storage->current();
56        $currentInfo = $storage->getInfo();
57        echo "現在のオブジェクト: " . ($currentObject ? $currentObject->name : 'N/A') . "\n";
58        echo "現在の値: " . ($currentInfo ?? 'N/A') . "\n";
59
60    } catch (OutOfBoundsException $e) {
61        // 指定されたオフセットがストレージの範囲外の場合にこの例外が発生します。
62        echo "エラー: " . $e->getMessage() . "\n";
63    }
64
65    echo "\n--- 範囲外のオフセットに seek() を使用した場合 (OutOfBoundsException が発生) ---\n";
66    try {
67        // 存在しないインデックス (要素数を超えるオフセット) にシークしようとすると例外がスローされます。
68        $offsetOutOfRange = 5;
69        $storage->seek($offsetOutOfRange);
70        // この行は、上記の seek() で例外がスローされるため実行されません。
71        echo "オフセット {$offsetOutOfRange} にシークしました。\n";
72    } catch (OutOfBoundsException $e) {
73        echo "例外を捕捉しました: " . $e->getMessage() . "\n";
74        echo "これは、指定されたオフセットがストレージの要素数 ({$storage->count()}) を超えているためです。\n";
75    }
76}
77
78// 上で定義したサンプル関数を実行します。
79demonstrateSplObjectStorageSeek();
80

SplObjectStorage::seek() メソッドは、PHPのSplObjectStorageという、オブジェクトをキーとしてデータを管理する特殊なコレクションにおいて、コレクション内で現在見ている位置を、指定した場所へ移動させるための機能です。

SplObjectStorageは、コレクションの要素を順番に処理するための仕組み（イテレータ）を内蔵しており、このseek()メソッドを使うことで、0から数え始める番号（オフセット）を指定して、目的のオブジェクトへ直接移動することが可能になります。これにより、リストの途中にある特定のオブジェクトに素早くアクセスできます。

引数 $offset には、移動したいオブジェクトの0から始まるインデックスを整数値で指定します。例えば $offset に 1 を指定すると、コレクションの2番目のオブジェクトにアクセス位置が移動します。このメソッドは値を何も返さず（戻り値は void）、移動後に現在のオブジェクトやその情報を取得するには current() や getInfo() メソッドなどを使います。

サンプルコードでは、複数のオブジェクトをSplObjectStorageに追加した後、seek()を使って特定のオブジェクトにアクセス位置を移動させ、そのオブジェクトの情報を取り出す様子を示しています。もし、存在しない番号やコレクションの範囲外のオフセットを指定してseek()を呼び出すと、OutOfBoundsExceptionというエラーが発生し、プログラムの実行が中断されますので、オフセットの範囲には注意が必要です。

Copy
1<?php
2
3/**
4 * SplObjectStorageの末尾に内部ポインタをシークするサンプル。
5 *
6 * SplObjectStorage::seek()メソッドを使用して、指定されたオフセット位置に
7 * 内部ポインタを移動させます。キーワード「seek_end」に対応するため、
8 * ストレージの最後の要素にシークする例を示します。
9 */
10
11// ストレージに格納するオブジェクトのサンプルクラスを定義
12class MyData
13{
14    private string $name;
15
16    public function __construct(string $name)
17    {
18        $this->name = $name;
19    }
20
21    public function getName(): string
22    {
23        return $this->name;
24    }
25}
26
27// SplObjectStorageのインスタンスを作成
28$storage = new SplObjectStorage();
29
30// オブジェクトをいくつか作成し、ストレージにアタッチ
31$data1 = new MyData('データA');
32$data2 = new MyData('データB');
33$data3 = new MyData('データC'); // これが最後のオブジェクトになる
34
35$storage->attach($data1);
36$storage->attach($data2);
37$storage->attach($data3);
38
39echo "ストレージに " . $storage->count() . " 個のオブジェクトがあります。\n";
40
41// 末尾にシークする前に、現在のポインタ位置を確認
42$storage->rewind(); // ポインタを先頭に戻す
43echo "現在のポインタ（先頭）: " . $storage->current()->getName() . "\n";
44
45// ストレージが空でない場合のみ、末尾にシーク
46$count = $storage->count();
47if ($count > 0) {
48    // 最後の要素のインデックスは count - 1
49    $lastIndex = $count - 1;
50
51    // seek() メソッドで末尾にポインタを移動
52    $storage->seek($lastIndex);
53
54    echo "SplObjectStorageの末尾 (" . $lastIndex . "番目のインデックス) にシークしました。\n";
55    echo "末尾のオブジェクト: " . $storage->current()->getName() . "\n";
56
57    // 期待される最後のオブジェクトが正しいか確認
58    echo "期待される最後のオブジェクト: " . $data3->getName() . "\n";
59} else {
60    echo "ストレージが空のため、末尾にシークできません。\n";
61}
62

PHPのSplObjectStorage::seekメソッドは、オブジェクトの集合を効率的に管理するSplObjectStorage内で、現在参照している内部ポインタを指定された位置に移動させるためのものです。引数$offsetには、ポインタを移動させたい要素のインデックスを整数値で指定します。インデックスは0から始まり、コレクションの最初の要素が0番目です。このメソッドはポインタを移動させるだけで、特定の値を返さないため、戻り値はvoidです。

提供されたサンプルコードでは、SplObjectStorageに複数のMyDataオブジェクトを格納し、その末尾に内部ポインタをシークする例を示しています。具体的には、ストレージ内のオブジェクトの総数から1を引いた値（$storage->count() - 1）を$offsetとしてseekメソッドに渡すことで、コレクションの最後の要素にポインタを移動させています。

ポインタが末尾に移動した後、$storage->current()を呼び出すことで、末尾に位置するオブジェクト（この場合はMyData('データC')）に直接アクセスできるようになります。このようにseekメソッドを利用することで、SplObjectStorage内の特定のインデックスにあるオブジェクトへ効率的に移動し、操作することが可能になります。