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

Copy
1<?php
2
3/**
4 * SplDoublyLinkedList::unshift の使用例。
5 * 連想配列をリストの先頭に追加する方法を示します。
6 *
7 * SplDoublyLinkedList は、両端から要素の追加や削除が効率的に行える
8 * 二重連結リストを実装したクラスです。
9 */
10
11// 新しい SplDoublyLinkedList インスタンスを作成します。
12$list = new SplDoublyLinkedList();
13
14// リストにいくつかの初期要素を追加します。
15$list->push('既存の要素B');
16$list->push('既存の要素C');
17$list->push('既存の要素D');
18
19echo "--- unshift 実行前のリスト ---" . PHP_EOL;
20// リストの内容と要素数を出力します。
21foreach ($list as $key => $value) {
22    echo "インデックス {$key}: " . $value . PHP_EOL;
23}
24echo "現在の要素数: " . $list->count() . PHP_EOL . PHP_EOL;
25
26// リストの先頭に追加したい連想配列を定義します。
27$associativeArrayToUnshift = [
28    'id' => 101,
29    'name' => '新規アイテムA',
30    'status' => 'active',
31    'tags' => ['new', 'important']
32];
33
34// unshift メソッドを使用して、連想配列をリストの先頭に追加します。
35// unshift は戻り値を持ちません（void）。
36$list->unshift($associativeArrayToUnshift);
37
38echo "--- unshift 実行後のリスト ---" . PHP_EOL;
39// リストを再度イテレートし、連想配列が先頭に追加されたことを確認します。
40// SplDoublyLinkedList は FIFO モード (Queue) または LIFO モード (Stack) で動作しますが、
41// ここではデフォルトの FIFO モードで順序付けされた要素をイテレートします。
42foreach ($list as $key => $value) {
43    echo "インデックス {$key}: ";
44    // 要素が配列の場合は、可読性のために JSON 形式で出力します。
45    if (is_array($value)) {
46        echo json_encode($value, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) . PHP_EOL;
47    } else {
48        echo $value . PHP_EOL;
49    }
50}
51echo "現在の要素数: " . $list->count() . PHP_EOL . PHP_EOL;
52
53// 先頭の要素が正しく追加された連想配列であることを確認します。
54// bottom() メソッドはリストの最初の要素を返します。
55echo "--- リストの最初の要素の確認 ---" . PHP_EOL;
56$firstElement = $list->bottom();
57if (is_array($firstElement)) {
58    echo "最初の要素 (bottom() で取得): " . json_encode($firstElement, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) . PHP_EOL;
59} else {
60    echo "最初の要素 (bottom() で取得): " . $firstElement . PHP_EOL;
61}
62
63?>

PHPのSplDoublyLinkedListは、要素の追加や削除をリストの両端から効率的に行える、二重連結リストを実装したクラスです。このクラスのunshiftメソッドは、リストの「先頭」に新しい要素を追加するために使用されます。

サンプルコードでは、まずいくつかの文字列要素を持つSplDoublyLinkedListを作成します。その後、unshiftメソッドを使って、連想配列をリストの先頭に追加しています。unshiftの引数$valueには、数値や文字列だけでなく、今回の例のようにidやname、status、tagsなどのキーを持つ「連想配列」も柔軟に指定できます。

unshiftメソッドは、要素の追加後も追加した要素自体を戻り値として返すことはなく、単にリストの状態を変更するだけです（戻り値はvoidです）。サンプルコードの実行結果を見ると、unshiftを実行する前は「既存の要素B」が先頭でしたが、実行後は追加した連想配列が新しい先頭の要素となり、元の要素はすべて一つずつ後方に移動していることが確認できます。また、count()メソッドで要素数が一つ増えていることからも、正しく追加されたことがわかります。最後に、bottom()メソッドでリストの最初の要素を取得し、追加した連想配列が正しく格納されていることを確認しています。

Copy
1<?php
2
3/**
4 * SplDoublyLinkedList::unshift の使用例と、要素の数値インデックスの振る舞いをデモンストレーションします。
5 *
6 * SplDoublyLinkedList はキーと値のペアを持つ連想配列とは異なり、
7 * 要素が追加された順序に基づいて自動的に割り振られる数値インデックスで管理されます。
8 * unshift メソッドはリストの先頭に要素を追加し、既存のすべての要素の数値インデックスを一つずつ増やします。
9 */
10function demonstrateSplDoublyLinkedListUnshift(): void
11{
12    // SplDoublyLinkedList の新しいインスタンスを作成
13    $list = new SplDoublyLinkedList();
14
15    echo "--- SplDoublyLinkedList::unshift デモンストレーション ---\n";
16
17    // 初期要素をリストの末尾に追加
18    $list->push('Banana');
19    $list->push('Cherry');
20    echo "初期状態: リストに 'Banana' と 'Cherry' を追加しました。\n";
21    displayListContents($list);
22
23    // unshift メソッドを使ってリストの先頭に要素を追加
24    $list->unshift('Apple');
25    echo "\nリストの先頭に 'Apple' を unshift しました。\n";
26    displayListContents($list);
27
28    // さらに別の要素をリストの先頭に追加
29    $list->unshift('Date');
30    echo "\nリストの先頭に 'Date' をさらに unshift しました。\n";
31    displayListContents($list);
32
33    echo "\n--- デモンストレーション終了 ---\n";
34}
35
36/**
37 * SplDoublyLinkedList の内容と、各要素の数値インデックスを表示するヘルパー関数。
38 *
39 * @param SplDoublyLinkedList $list 表示するリスト
40 */
41function displayListContents(SplDoublyLinkedList $list): void
42{
43    echo "現在のリスト内容 (要素数: " . $list->count() . "):\n";
44    if ($list->isEmpty()) {
45        echo "  (リストは空です)\n";
46        return;
47    }
48
49    // リストを反復処理し、要素の数値インデックスと値を出力します。
50    // foreach ($list as $key => $value) における $key は、要素の現在の数値インデックスを示します。
51    foreach ($list as $key => $value) {
52        echo "  インデックス: " . $key . ", 値: '" . $value . "'\n";
53    }
54}
55
56// サンプルコードを実行
57demonstrateSplDoublyLinkedListUnshift();
58
59?>

PHPのSplDoublyLinkedListは、要素を前後に効率的に追加・削除できる「双方向連結リスト」というデータ構造を提供するクラスです。これは、連想配列のように開発者が自由にキーを指定するのではなく、要素が追加された順序に基づいて自動的に割り振られる数値インデックスで管理される点が特徴です。

このサンプルコードは、SplDoublyLinkedListクラスのunshiftメソッドの使い方を示しています。unshiftメソッドは、リストの「先頭」に新しい要素を追加します。引数$valueには、リストの先頭に追加したい任意の値を指定します。このメソッドが実行されると、新しく追加された要素がインデックス0となり、それまでリストにあった既存のすべての要素の数値インデックスは一つずつ繰り上がります。例えば、元々インデックス0だった要素はインデックス1に、インデックス1だった要素はインデックス2になる、といった具体的な挙動です。

unshiftメソッドには戻り値がありません。リストの内部状態が直接変更されることで処理が完結します。したがって、連想配列のキーのように特定の「キー」を指定してunshiftすることはできず、常に数値インデックスの先頭に追加される挙動となります。foreachループで$keyとして取得されるのは、要素の現在の数値インデックスであることにご留意ください。