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

Copy
1<?php
2
3// SplStackクラスのインスタンスを作成します。
4// SplStackは、スタック（LIFO: 後入れ先出し）の挙動を模倣したデータ構造ですが、
5// unshiftメソッドはスタックの「先頭」に要素を追加します。
6$stack = new SplStack();
7
8// 既存の要素をいくつか追加します。
9// pushメソッドはスタックの「末尾」（通常はトップ）に要素を追加します。
10$stack->push('既存データA');
11$stack->push('既存データB');
12$stack->push('既存データC');
13
14echo "--- unshift前のスタックの内容 ---" . PHP_EOL;
15// スタックの内容を順番に表示します。
16// SplStackはTraversableインターフェースを実装しているため、foreachで直接イテレートできます。
17foreach ($stack as $item) {
18    echo "- " . $item . PHP_EOL;
19}
20echo "--------------------------------" . PHP_EOL;
21
22// unshiftで追加する連想配列を定義します。
23$newAssociativeArray = [
24    'product_id' => 101,
25    'product_name' => 'Sample Widget',
26    'price' => 29.99,
27    'in_stock' => true
28];
29
30// unshiftメソッドを使って、定義した連想配列をスタックの「先頭」に追加します。
31// unshiftはmixed型の引数を受け取るため、連想配列もそのまま追加できます。
32$stack->unshift($newAssociativeArray);
33
34echo PHP_EOL . "--- unshift後に連想配列が先頭に追加されたスタックの内容 ---" . PHP_EOL;
35// unshift後のスタックの内容を順番に表示し、連想配列が先頭に追加されたことを確認します。
36foreach ($stack as $item) {
37    if (is_array($item)) {
38        // 連想配列の場合は、json_encodeを使って内容を見やすく表示します。
39        echo "- 連想配列: " . json_encode($item, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) . PHP_EOL;
40    } else {
41        echo "- " . $item . PHP_EOL;
42    }
43}
44echo "------------------------------------------------------------" . PHP_EOL;
45
46?>

SplStackは、後入れ先出し（LIFO）の原則に従うスタックデータ構造を提供します。SplStack::unshiftメソッドは、このスタックの「先頭」に新しい要素を追加する際に使用されます。通常のスタック操作では要素は末尾に追加されますが、unshiftを使うことで既存の要素群の前にデータを挿入できます。このメソッドはmixed $valueという引数を受け取るため、文字列や数値だけでなく、連想配列を含むあらゆる型のデータを自由に追加可能です。メソッド自体は要素を追加するだけで、特別な戻り値はありません。

サンプルコードでは、いくつかの既存データを持つSplStackインスタンスに対し、定義済みの連想配列をunshiftメソッドで追加しています。この操作により、連想配列が既存の要素よりも先に、スタックの最前面（先頭）に挿入されます。実行後の出力結果から、新しく追加された連想配列がスタックの最初の要素として正しく格納されていることが確認できます。このように、unshiftはスタックの通常のLIFO挙動とは異なり、新しいデータを強制的にスタックの先頭へ配置したい場合に特に有用なメソッドです。

Copy
1<?php
2
3/**
4 * SplStack::unshift メソッドのデモンストレーション
5 *
6 * SplStack は、スタック（後入れ先出し: LIFO）データ構造を実装するクラスです。
7 * unshift メソッドはスタックの「先頭」に新しい要素を追加します。
8 *
9 * PHPの通常の配列のように、SplStack は要素にキー（文字列や数値インデックス）を直接割り当てる機能はありません。
10 * しかし、連想配列（キーと値のペアを持つ配列）を「一つの要素」としてスタックに格納することは可能です。
11 * このサンプルコードでは、この方法で「キーを持つ要素」を unshift する方法を示します。
12 */
13function demonstrateSplStackUnshiftWithKeyLikeValue(): void
14{
15    echo "--- SplStack::unshift のデモンストレーションを開始します ---\n";
16
17    // 1. SplStack の新しいインスタンスを作成
18    $stack = new SplStack();
19    echo "初期スタックの状態: " . (empty($stack) ? "空" : "エラー") . "\n"; // 初期状態は空です
20
21    // 2. いくつかの要素をスタックに追加（push はスタックの末尾に追加）
22    $stack->push('Task C: Report Generation');
23    $stack->push('Task B: Data Processing');
24    echo "\n'Task C', 'Task B' を push 後（スタックの底からトップの順）：\n";
25    // SplStackはIteratorを実装しているので、foreachでイテレート可能
26    // iterator_to_array() でスタックの底からトップへの順序で配列に変換して表示
27    echo "  現在のスタック内容: [" . implode(", ", iterator_to_array($stack)) . "]\n";
28
29    // 3. unshift を使用してスタックの「先頭」に要素を追加
30    // unshift で追加された要素は、次に pop される際に最初に取り出されます。
31    $stack->unshift('Task A: User Input Collection');
32    echo "\n'Task A' を unshift 後（スタックの底からトップの順）：\n";
33    echo "  現在のスタック内容: [" . implode(", ", iterator_to_array($stack)) . "]\n";
34    echo "  (この時点で pop すると 'Task A' が最初に取り出されます)\n";
35
36    // 4. キーと値のペアを持つ配列を「一つの要素」として準備
37    $newTaskWithDetails = [
38        'id' => 'project_001',
39        'priority' => 'high',
40        'description' => '新規プロジェクトの初期設定',
41        'status' => 'pending',
42    ];
43
44    echo "\nキーと値のペアを含む配列を一つの要素として準備しました:\n";
45    echo "  " . json_encode($newTaskWithDetails, JSON_UNESCAPED_UNICODE) . "\n";
46
47    // 5. この配列を SplStack::unshift メソッドでスタックの先頭に追加
48    $stack->unshift($newTaskWithDetails);
49    echo "\n準備した配列を unshift 後（スタックの底からトップの順）：\n";
50    // 配列要素を適切に表示するため、map関数で整形
51    echo "  現在のスタック内容: [" . implode(", ", array_map(function ($item) {
52        return is_array($item) ? json_encode($item, JSON_UNESCAPED_UNICODE) : $item;
53    }, iterator_to_array($stack))) . "]\n";
54    echo "  (この時点で pop すると上記の配列が最初に取り出されます)\n";
55
56    echo "\n--- スタックから要素を pop して確認します (LIFO: 後入れ先出し) ---\n";
57
58    // 6. スタックから要素を pop して、unshfit した要素が先頭にあることを確認
59    while (!$stack->isEmpty()) {
60        $poppedElement = $stack->pop(); // 最も新しく追加された要素が取り出される
61
62        echo "pop: ";
63        if (is_array($poppedElement)) {
64            // 取り出された要素が配列の場合
65            echo "配列要素を取得: " . json_encode($poppedElement, JSON_UNESCAPED_UNICODE) . "\n";
66            // 配列のキーと値にアクセス
67            if (isset($poppedElement['id'])) {
68                echo "  -> 識別子 (ID): " . $poppedElement['id'] . "\n";
69            }
70            if (isset($poppedElement['priority'])) {
71                echo "  -> 優先度: " . $poppedElement['priority'] . "\n";
72            }
73        } else {
74            // 取り出された要素が文字列の場合
75            echo "文字列要素を取得: " . $poppedElement . "\n";
76        }
77    }
78    echo "\nスタックが空になりました。\n";
79    echo "--- デモンストレーションを終了します ---\n";
80}
81
82// 関数を実行して動作を確認
83demonstrateSplStackUnshiftWithKeyLikeValue();

SplStack::unshiftメソッドは、PHPのSplStackクラスが提供する、スタックデータ構造の「先頭」に新しい要素を追加する機能です。スタックは後入れ先出し（LIFO）の原則に従い、このメソッドで追加された要素は、次にpopされる際に最も早く取り出されます。引数$valueには、文字列、数値、配列、オブジェクトなど、あらゆる型の値を指定でき、戻り値はありません。

SplStack自体はPHPの通常の配列のように要素に直接キーを割り当てる機能はありません。しかし、キーと値のペアを持つ連想配列を「一つの要素」としてスタックに格納することは可能です。サンプルコードでは、まず文字列要素を追加し、その後、IDや優先度などの詳細情報を含む連想配列をunshiftでスタックの先頭に追加する例を示しています。pop操作では連想配列全体が取得され、その内部のキーと値にアクセスできるため、スタックに構造化されたデータを格納する方法として有効です。