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

Copy
1<?php
2
3/**
4 * SplDoublyLinkedList のイテレータモード (setIteratorMode) の使用例
5 *
6 * SplDoublyLinkedList は、双方向連結リストを実装する PHP のデータ構造です。
7 * setIteratorMode メソッドは、リストの要素をイテレートする際の順序や動作を制御します。
8 */
9
10// 新しい双方向連結リストを作成します。
11$list = new SplDoublyLinkedList();
12
13// リストに要素を追加します。
14// unshift はリストの先頭に要素を追加します。
15$list->unshift('Orange'); // リスト: [Orange]
16$list->push('Apple');    // リスト: [Orange, Apple]
17$list->push('Banana');   // リスト: [Orange, Apple, Banana]
18
19echo "--- リストに追加された要素の順序 (内部的な並び) ---" . PHP_EOL;
20echo "1. Orange (unshiftで先頭に追加)" . PHP_EOL;
21echo "2. Apple (pushで末尾に追加)" . PHP_EOL;
22echo "3. Banana (pushで末尾に追加)" . PHP_EOL;
23echo PHP_EOL;
24
25// 1. FIFO (First In, First Out) モードでのイテレーション
26// SplDoublyLinkedList::IT_MODE_FIFO を設定すると、
27// 最初に追加された要素 (またはリストの先頭にある要素) から順にイテレートされます。
28// これはデフォルトのイテレータモードでもあります。
29echo "--- FIFO (First In, First Out) モード ---" . PHP_EOL;
30$list->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO);
31
32// foreach ループは内部的に SplDoublyLinkedList::getIterator() を呼び出します。
33foreach ($list as $item) {
34    echo $item . PHP_EOL;
35}
36echo PHP_EOL;
37
38// 2. LIFO (Last In, First Out) モードでのイテレーション
39// SplDoublyLinkedList::IT_MODE_LIFO を設定すると、
40// 最後に追加された要素 (またはリストの末尾にある要素) から逆順にイテレートされます。
41echo "--- LIFO (Last In, First Out) モード ---" . PHP_EOL;
42$list->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO);
43
44foreach ($list as $item) {
45    echo $item . PHP_EOL;
46}
47echo PHP_EOL;
48
49// setIteratorMode には、イテレート中に要素を削除するモード
50// (SplDoublyLinkedList::IT_MODE_DELETE) もありますが、
51// 基本的な動作を理解するため、ここでは FIFO と LIFO に焦点を当てています。
52
53?>

PHPのSplDoublyLinkedListは、要素の追加や削除を効率的に行える双方向連結リストというデータ構造を実装したクラスです。このクラスに用意されているsetIteratorModeメソッドは、リストに格納された要素をforeach文などで順に処理する（イテレートする）際の動作モードを設定するために利用されます。

このメソッドは、int $modeという整数型の引数を一つ取ります。この$modeには、イテレーションの順序や挙動を定義する定数を指定します。例えば、SplDoublyLinkedList::IT_MODE_FIFOを指定すると、リストに最初に追加された要素から順に（First In, First Out、先入れ先出し）イテレートされます。これはSplDoublyLinkedListのデフォルトのイテレータモードです。一方、SplDoublyLinkedList::IT_MODE_LIFOを指定すると、リストに最後に追加された要素から逆順に（Last In, First Out、後入れ先出し）イテレートされるようになります。setIteratorModeメソッド自体は、イテレータモードを設定するだけで、特に戻り値はありません。

サンプルコードでは、SplDoublyLinkedListに複数の要素を追加した後、setIteratorModeメソッドを使ってイテレータモードを設定し、foreachループで要素を取り出して表示しています。IT_MODE_FIFOモードでは、要素が追加された順序である「Orange」「Apple」「Banana」と表示されます。IT_MODE_LIFOモードに切り替えて再度foreachループを実行すると、最後に追加された要素から逆順に「Banana」「Apple」「Orange」と表示されることが確認できます。このようにsetIteratorModeは、foreachが内部的に呼び出すgetIteratorメソッドの動作を制御し、リストの要素へのアクセス順序を柔軟に変更できる便利な機能です。

Copy
1<?php
2
3/**
4 * SplDoublyLinkedList のイテレータモードを設定し、イテレーションの挙動を確認するサンプルコードです。
5 *
6 * SplDoublyLinkedList は双方向連結リストを実装しており、PHP の foreach 構文で直接イテレート可能です。
7 * これは、SplDoublyLinkedList が内部的に IteratorAggregate の概念に沿ったイテレーション機能を提供しているためです。
8 *
9 * setIteratorMode メソッドは、このイテレーションの順序（FIFO: 先入れ先出し、LIFO: 後入れ先出し）や、
10 * イテレーション中に要素をリスト内に保持するか削除するか（KEEP: 保持、DELETE: 削除）を設定します。
11 *
12 * このサンプルでは、主に FIFO と LIFO の順序の違い、および KEEP と DELETE の違いを示します。
13 */
14function demonstrateSplDoublyLinkedListIteratorModes(): void
15{
16    echo "--- SplDoublyLinkedList Iterator Mode Demo ---" . PHP_EOL;
17    echo "----------------------------------------" . PHP_EOL;
18
19    // SplDoublyLinkedList のインスタンスを作成
20    $list = new SplDoublyLinkedList();
21
22    // リストに要素を追加
23    $list->push('Apple');  // 最初に追加
24    $list->push('Banana');
25    $list->push('Cherry'); // 最後に追加
26
27    echo "リストに要素を追加しました: 'Apple', 'Banana', 'Cherry'" . PHP_EOL;
28    echo "----------------------------------------" . PHP_EOL;
29
30    // 1. デフォルトモード (FIFO | KEEP) でのイテレーション
31    // setIteratorMode を呼び出さない場合、または明示的に設定した場合のデフォルト動作です。
32    // FIFO: 先に入れたものから順に取得されます。
33    // KEEP: イテレーション中に要素はリストに残ります。
34    echo "1. デフォルトモード (FIFO: 先入れ先出し, KEEP: 保持) でのイテレーション:" . PHP_EOL;
35    echo "   => 追加した順 ('Apple' -> 'Banana' -> 'Cherry') に要素が取得されます。" . PHP_EOL;
36    // 明示的にデフォルトモードを設定
37    $list->setIteratorMode(SplDoublyLinkedList::IT_MODE_FIFO | SplDoublyLinkedList::IT_MODE_KEEP);
38    foreach ($list as $item) {
39        echo "   - " . $item . PHP_EOL;
40    }
41    echo "   イテレーション後のリストの要素数: " . $list->count() . " (要素は削除されていません)" . PHP_EOL;
42    echo "----------------------------------------" . PHP_EOL;
43
44    // 2. LIFOモード (LIFO | KEEP) でのイテレーション
45    // LIFO: 後に入れたものから順に取得されます。
46    // KEEP: イテレーション中に要素はリストに残ります。
47    echo "2. LIFOモード (LIFO: 後入れ先出し, KEEP: 保持) でのイテレーション:" . PHP_EOL;
48    echo "   => 最後に追加したものから逆順 ('Cherry' -> 'Banana' -> 'Apple') に要素が取得されます。" . PHP_EOL;
49    $list->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO | SplDoublyLinkedList::IT_MODE_KEEP);
50    foreach ($list as $item) {
51        echo "   - " . $item . PHP_EOL;
52    }
53    echo "   イテレーション後のリストの要素数: " . $list->count() . " (要素は削除されていません)" . PHP_EOL;
54    echo "----------------------------------------" . PHP_EOL;
55
56    // 3. LIFOかつDELETEモードでのイテレーション
57    // DELETE: イテレーション中に要素がリストから削除されます。
58    // 新しいリストを作成して、この挙動を明確に示します。
59    $deleteList = new SplDoublyLinkedList();
60    $deleteList->push('One');
61    $deleteList->push('Two');
62    $deleteList->push('Three');
63    echo "3. LIFOモード (LIFO: 後入れ先出し, DELETE: 削除) でのイテレーション:" . PHP_EOL;
64    echo "   元のリスト要素: 'One', 'Two', 'Three'" . PHP_EOL;
65    echo "   => 最後に追加したものから逆順で取得され、同時にリストから削除されます。" . PHP_EOL;
66    $deleteList->setIteratorMode(SplDoublyLinkedList::IT_MODE_LIFO | SplDoublyLinkedList::IT_MODE_DELETE);
67    foreach ($deleteList as $item) {
68        echo "   - 取得して削除: " . $item . PHP_EOL;
69    }
70    echo "   イテレーション後のリストの要素数: " . $deleteList->count() . " (全ての要素が削除されました)" . PHP_EOL;
71    echo "----------------------------------------" . PHP_EOL;
72}
73
74// 関数を実行し、デモンストレーションを開始
75demonstrateSplDoublyLinkedListIteratorModes();

PHPのSplDoublyLinkedListクラスは、要素の追加や削除がリストの先頭と末尾のどちらからでも効率的に行える双方向連結リストを実装しています。このリストは、IteratorAggregateの機能によって、PHPのforeach構文でその要素を順番に処理することが可能です。

SplDoublyLinkedList::setIteratorModeメソッドは、このforeachなどによるリストのイテレーション（要素の巡回処理）の挙動を設定するために利用されます。引数$modeには整数値を指定し、SplDoublyLinkedListクラスが持つ複数の定数をビットOR演算子（|）で組み合わせて渡します。

この$mode引数により、主に二つの制御が行えます。一つはイテレーション時の要素の取得順序で、SplDoublyLinkedList::IT_MODE_FIFOを指定すると追加した順に、SplDoublyLinkedList::IT_MODE_LIFOを指定すると最後に追加したものから逆順に要素が取得されます。もう一つは、イテレーション中に要素をリスト内に保持するか、取得と同時に削除するかという挙動で、SplDoublyLinkedList::IT_MODE_KEEPを指定するとイテレーション後も要素はリストに残りますが、SplDoublyLinkedList::IT_MODE_DELETEを指定すると要素が取得されるたびにリストから削除されます。このメソッドは戻り値を返しません。

サンプルコードでは、まずデフォルトの「先入れ先出し（FIFO）かつ保持（KEEP）」モードで、追加順に要素が取得されリストに残ることを示しています。次に、「後入れ先出し（LIFO）かつ保持（KEEP）」モードでは、逆順で要素が取得されリストに残ることが確認できます。最後に、「後入れ先出し（LIFO）かつ削除（DELETE）」モードでは、逆順で要素が取得されると同時にリストから削除されるため、イテレーション後にはリストが空になる挙動が示され、リストの柔軟なイテレーション制御方法を理解することができます。