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

Copy
1<?php
2
3/**
4 * SplQueue::top() メソッドのサンプルコード
5 *
6 * SplQueue は、キュー（待ち行列）のデータ構造を提供するPHPのクラスです。
7 * キューは「先入れ先出し (FIFO: First-In, First-Out)」の原則に従います。
8 *
9 * SplQueue::top() メソッドは、キューの先頭にある要素を取得しますが、
10 * その要素をキューから削除することはありません。
11 * キューが空の場合、RuntimeException をスローします。
12 */
13function demonstrateSplQueueTop(): void
14{
15    echo "--- SplQueue::top() のデモンストレーション ---" . PHP_EOL;
16
17    // 1. 新しい SplQueue オブジェクトを作成
18    $queue = new SplQueue();
19    echo "キューを初期化しました。" . PHP_EOL;
20    echo "キューは現在空です。" . PHP_EOL;
21
22    // 2. キューに要素を追加 (enqueue)
23    $queue->enqueue("タスクA");
24    $queue->enqueue("タスクB");
25    $queue->enqueue("タスクC");
26    echo "要素 'タスクA', 'タスクB', 'タスクC' をキューに追加しました。" . PHP_EOL;
27
28    // 3. キューの先頭要素を Peek (top)
29    // top() は要素を削除しないため、キューのサイズは変わらない
30    echo PHP_EOL . "--- キューの先頭要素を確認 (top) ---" . PHP_EOL;
31    if (!$queue->isEmpty()) {
32        $firstItem = $queue->top();
33        echo "現在のキューの先頭要素: " . $firstItem . PHP_EOL;
34        echo "キューの要素数: " . $queue->count() . PHP_EOL; // 要素数は変わらない
35    } else {
36        echo "キューは空です。" . PHP_EOL;
37    }
38
39    // 4. 要素をキューから取り出す (dequeue)
40    echo PHP_EOL . "--- キューから要素を取り出す (dequeue) ---" . PHP_EOL;
41    if (!$queue->isEmpty()) {
42        $dequeuedItem = $queue->dequeue();
43        echo "取り出した要素: " . $dequeuedItem . PHP_EOL;
44        echo "キューの要素数: " . $queue->count() . PHP_EOL; // 要素数が減る
45    }
46
47    // 5. 再度キューの先頭要素を Peek (top)
48    // dequeue された後、先頭要素が変わっていることを確認
49    echo PHP_EOL . "--- dequeue 後、再度先頭要素を確認 (top) ---" . PHP_EOL;
50    if (!$queue->isEmpty()) {
51        $newFirstItem = $queue->top();
52        echo "新しいキューの先頭要素: " . $newFirstItem . PHP_EOL;
53        echo "キューの要素数: " . $queue->count() . PHP_EOL;
54    } else {
55        echo "キューは空です。" . PHP_EOL;
56    }
57
58    // 6. 全ての要素を dequeue し、空の状態にする
59    while (!$queue->isEmpty()) {
60        echo "要素 '" . $queue->dequeue() . "' を取り出しました。" . PHP_EOL;
61    }
62    echo "キューが空になりました。" . PHP_EOL;
63
64    // 7. 空のキューで top() を呼び出した場合の例外処理
65    echo PHP_EOL . "--- 空のキューで top() を試行 ---" . PHP_EOL;
66    try {
67        echo "空のキューの先頭要素を取得しようとしています..." . PHP_EOL;
68        $queue->top(); // ここで RuntimeException がスローされる
69        echo "このメッセージは表示されません。" . PHP_EOL;
70    } catch (RuntimeException $e) {
71        echo "エラー発生: " . $e->getMessage() . PHP_EOL;
72        echo "期待通りの動作: 空のキューに対して top() を呼び出すと RuntimeException がスローされます。" . PHP_EOL;
73    }
74
75    echo PHP_EOL . "--- デモンストレーション終了 ---" . PHP_EOL;
76}
77
78// 関数を実行
79demonstrateSplQueueTop();

PHPのSplQueueクラスは、データ構造の一つである「キュー（待ち行列）」を扱うためのもので、データが「先入れ先出し（FIFO）」の原則で処理されます。

SplQueue::top()メソッドは、このキューの「先頭にある要素」を「削除せずに」取得するために使用します。このメソッドは引数を必要とせず、キューの先頭要素の値をそのまま返します（戻り値はmixed型です）。

top()メソッドの重要な特徴は、要素を参照するだけでキューから取り除かないため、キューのサイズは変化しない点です。対照的に、dequeue()メソッドは先頭要素を取得すると同時にキューから削除します。

もしキューが空の状態でtop()メソッドを呼び出した場合、取り出すべき要素が存在しないためRuntimeExceptionがスローされます。サンプルコードでは、要素の追加、top()による先頭要素の確認、dequeue()による要素の削除、そして空のキューでtop()を呼び出した際の例外発生といった一連の流れを通じて、このメソッドの正確な挙動が具体的に示されています。これにより、top()メソッドがキューの状態にどう影響し、どのような状況でエラーとなるかを明確に理解できます。

Copy
1<?php
2
3/**
4 * PHP (フィリピンペソ) から USD (米ドル) への金額換算をシミュレートする関数です。
5 * SplQueue を使用して、キューの先頭にある金額を参照し換算します。
6 *
7 * @param float[] $phpAmounts 換算するPHP金額の配列
8 * @return void
9 */
10function convertPhpToUsdUsingQueue(array $phpAmounts): void
11{
12    // PHP 8では、SplQueueは型宣言をサポート
13    $queue = new SplQueue();
14
15    // キューにPHP金額を追加
16    foreach ($phpAmounts as $amount) {
17        // enqueueメソッドで要素をキューの末尾に追加
18        $queue->enqueue($amount);
19    }
20
21    // USDへの換算レート (例: 1 PHP = 0.017 USD)
22    $exchangeRate = 0.017;
23
24    if (!$queue->isEmpty()) {
25        // top() メソッドでキューの先頭の要素 (一番最初にエンキューされた要素) を参照します。
26        // このメソッドは要素をキューから削除しません。
27        $phpAmountToConvert = $queue->top();
28
29        $usdAmount = $phpAmountToConvert * $exchangeRate;
30
31        echo "PHP " . number_format($phpAmountToConvert, 2) . " は、USD " . number_format($usdAmount, 2) . " に相当します。\n";
32        echo "参照された金額はキューから削除されていないため、現在のキューの先頭は引き続き PHP " . number_format($queue->top(), 2) . " です。\n";
33    } else {
34        echo "換算するPHP金額がキューにありません。\n";
35    }
36}
37
38// --- サンプル実行 ---
39// 複数のPHP金額を用意 (フィリピンペソ)
40$amountsToProcess = [1000.00, 500.50, 250.75];
41
42// 関数を実行し、キューの先頭の金額をUSDに換算
43convertPhpToUsdUsingQueue($amountsToProcess);
44
45echo "\n--- キューに金額がない場合の例 ---\n";
46convertPhpToUsdUsingQueue([]);
47
48?>

PHP 8のSplQueueクラスは、データが「先入れ先出し（FIFO）」の原則で処理されるキュー構造を提供します。このSplQueue::top()メソッドは、キューの「一番先頭にある要素」を参照するために使用されます。引数は必要なく、キューの先頭にある要素の値をmixed型（PHPでは様々な型を意味します）で返します。最も重要な点は、このメソッドが要素をキューから「参照するだけ」であり、その要素をキューから「削除しない」ことです。

サンプルコードでは、複数のPHP金額をキューに追加し、USDへの換算をシミュレートしています。top()メソッドを使用することで、キューの一番先頭にある金額（この例では「1000.00」）を読み取り、USDに換算して表示しています。top()が要素を削除しないため、換算後にもう一度top()を呼び出すと、同じ「1000.00」が引き続きキューの先頭にあることが出力結果から確認できます。この機能は、キューから実際に要素を取り出す前に、次に処理されるデータの内容を事前に確認したい場合に非常に役立ちます。