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

Copy
1<?php
2
3/**
4 * SplHeap::top メソッドの基本的な使い方を示す関数です。
5 * SplHeap は抽象クラスなので、具体的な実装である SplMinHeap を使用します。
6 * SplHeap::top はヒープの最上位要素を返しますが、その要素はヒープから削除されません。
7 * SplMinHeap の場合、最上位要素はヒープ内の最小値です。
8 */
9function demonstrateSplHeapTop(): void
10{
11    echo "--- SplHeap::top メソッドのデモンストレーション ---\n\n";
12
13    // SplMinHeap のインスタンスを作成します。
14    // これは最小値が常に最上位に来るヒープです。
15    $minHeap = new SplMinHeap();
16
17    echo "=== データをヒープに追加 ===\n";
18    $minHeap->insert(10);
19    $minHeap->insert(5);
20    $minHeap->insert(20);
21    $minHeap->insert(3);
22    echo "追加されたデータ: 10, 5, 20, 3\n\n";
23
24    // ヒープが空でないことを確認してから top() を呼び出します。
25    // top() はヒープの最上位要素（SplMinHeap では最小値）を取得します。
26    if (!$minHeap->isEmpty()) {
27        $currentTop = $minHeap->top();
28        echo "現在のヒープの最上位要素 (最小値): " . $currentTop . "\n";
29        echo "(この要素はヒープに残っており、削除されていません。)\n\n";
30    } else {
31        echo "ヒープは空です。\n\n";
32    }
33
34    echo "=== さらにデータを追加 ===\n";
35    $minHeap->insert(1);
36    echo "追加されたデータ: 1\n\n";
37
38    // 新しいデータが追加された後、再び top() を呼び出して最上位要素を確認します。
39    if (!$minHeap->isEmpty()) {
40        $newTop = $minHeap->top();
41        echo "データを追加後のヒープの最上位要素 (最小値): " . $newTop . "\n";
42        echo "(新しい最小値が最上位に来ました。)\n\n";
43    } else {
44        echo "ヒープは空です。\n\n";
45    }
46
47    echo "--- ポイント ---\n";
48    echo "SplHeap::top() メソッドは要素を**取得するだけ**で、ヒープから削除しません。\n";
49    echo "ヒープから最上位要素を削除しつつ取得するには、SplHeap::pop() メソッドを使用します。\n";
50}
51
52// 関数を実行してデモンストレーションを開始します。
53demonstrateSplHeapTop();

PHP 8のSplHeap::topメソッドは、ヒープ構造の最上位に位置する要素を削除せずに取得するために使用されます。SplHeapは抽象クラスのため、具体的な実装であるSplMinHeapを例に説明します。SplMinHeapの場合、top()メソッドはヒープ内の最小値を最上位要素として返します。このメソッドは引数を必要とせず、ヒープに含まれる要素の値を示すmixed型の値を戻り値として返します。

サンプルコードでは、SplMinHeapに複数の数値を挿入した後、top()を呼び出すとヒープ内の最小値が表示されます。このとき、取得された要素はヒープから削除されず、引き続きヒープ内に存在します。さらに新しい最小値が挿入されると、top()は更新された最小値を返します。この挙動は、ヒープの状態に応じて常に現在の最上位要素を確認できることを示しています。要素をヒープから削除しつつ取得したい場合は、SplHeap::pop()メソッドを使用します。top()メソッドは、ヒープの現在の最上位要素を削除せずに確認したい場合に非常に役立ちます。

Copy
1<?php
2
3/**
4 * 複数のPHPからUSDへの為替レートの中から最も高い（有利な）レートを見つけます。
5 * SplMaxHeap を使用して、挿入された値の中から最大値を効率的に取得します。
6 *
7 * @param array<float> $rates PHPからUSDへの為替レートのリスト (例: 1 PHP あたり何 USD か)
8 * @return float|null 最も高い為替レート、またはレートが提供されていない場合は null
9 */
10function findHighestPhpToUsdRate(array $rates): ?float
11{
12    // SplMaxHeap は、ヒープ（優先度キュー）の一種で、常に最大値が最上位にくるように要素を管理します。
13    // これにより、追加された要素の中から効率的に最大値（この場合、最も有利な為替レート）を取得できます。
14    $rateHeap = new SplMaxHeap();
15
16    // 提供された全ての為替レートをヒープに挿入します。
17    // insert() メソッドは、新しい要素をヒープに追加し、ヒープの順序（最大値が最上位）を自動的に維持します。
18    foreach ($rates as $rate) {
19        // 数値でないデータが含まれる可能性を考慮し、型チェックを行います。
20        if (is_numeric($rate)) {
21            $rateHeap->insert((float) $rate);
22        }
23    }
24
25    // ヒープが空でなければ、top() メソッドで最上位（最も高い）レートを取得します。
26    // top() は最上位の要素を返すだけで、ヒープからその要素を削除しません。
27    // ヒープの構造は保たれます。
28    if (!$rateHeap->isEmpty()) {
29        return $rateHeap->top();
30    }
31
32    // レートが何も追加されなかった場合は null を返します。
33    return null;
34}
35
36// --- サンプルコードの実行 ---
37
38// 複数のPHPからUSDへの為替レートの例
39// (例: 1 PHP が 0.017 USD、0.0172 USD など)
40$phpToUsdRates = [
41    0.0170, // ある時点やプロバイダーのレート
42    0.0172, // 別のレート (少し良い)
43    0.0169, // また別のレート (少し悪い)
44    0.0175, // 最も良いレート
45    0.0171, // その他のレート
46];
47
48echo "--- PHP to USD 為替レート分析 ---\n";
49
50// findHighestPhpToUsdRate 関数を呼び出し、最も高いレートを取得
51$highestRate = findHighestPhpToUsdRate($phpToUsdRates);
52
53if ($highestRate !== null) {
54    echo "提示されたレートの中で、最も有利な (高い) PHP to USD レートは: " . sprintf('%.4f', $highestRate) . " USD/PHP\n";
55    echo "これは、1 PHP が約 " . sprintf('%.4f', $highestRate) . " USD に相当することを示します。\n";
56} else {
57    echo "分析できる有効な為替レートが見つかりませんでした。\n";
58}
59
60echo "\n--- 空のレート配列のテスト ---\n";
61$emptyRates = [];
62$highestRateFromEmpty = findHighestPhpToUsdRate($emptyRates);
63
64if ($highestRateFromEmpty === null) {
65    echo "空のレート配列の場合、正しく null が返されました。\n";
66}

このサンプルコードは、PHPのSplMaxHeapクラスとtop()メソッドを活用し、複数のPHPからUSDへの為替レートの中から最も高い（有利な）レートを見つける方法を実演しています。

SplMaxHeapは、要素を追加するたびに、常に最大値が最上位にくるように内部で自動的に並び替えを維持する特別なデータ構造（ヒープ）です。これにより、大量のデータの中から最大値を効率的に取得できます。

まず、findHighestPhpToUsdRate関数は、渡された全ての為替レートをSplMaxHeapに順次追加します。提供されたレートが追加されると、ヒープ内では自動的に最も高いレートがすぐに取り出せる状態で保持されます。

次に、SplHeap::top()メソッドは、ヒープ内の最上位に位置する要素、つまりこのケースでは「最も高い為替レート」を返します。このメソッドは引数を一切取らず、要素をヒープから削除することなく、単にその値を取得するだけです。戻り値はmixed型ですが、このサンプルでは浮動小数点数（float）として扱われます。サンプルコードでは、ヒープが空でないことをisEmpty()で確認してからtop()を呼び出すことで、安全に最大値を取得しています。

このように、top()メソッドをSplMaxHeapと組み合わせることで、与えられた為替レートの中から最も有利なレートを効率的かつ簡潔に特定できるのです。