# 機能設計書 138-min

## 概要

本ドキュメントは、Hack Standard Library (HSL) の Math 名前空間における `min` 関数の機能設計書である。この関数は、与えられた Traversable（走査可能なコレクション）から数値型の最小要素を取得して返す。

### 本機能の処理概要

**業務上の目的・背景**：
コレクション内の最小値を取得することは、データ分析、統計処理、ビジネスロジックにおいて頻繁に必要とされる基本的な操作である。最低価格、最低気温、最小スコアなど、様々な場面で使用される。`Math\min` 関数は、Hack 言語において型安全かつジェネリックなインターフェースで最小値の取得を提供する。Traversable インターフェースを受け入れるため、vec、Set、Vector、Iterator など様々なコレクション型に対応している。

**機能の利用シーン**：
- データ分析における最小値の抽出
- 価格比較における最安価格の特定
- センサーデータの最小値検出
- 在庫管理における最小在庫数の監視
- パフォーマンス計測における最短応答時間の特定

**主要な処理内容**：
1. Traversable<T as num> 型のコレクションを受け取る
2. コレクションを走査して各要素を比較する
3. 最小の要素を追跡する
4. コレクションが空の場合は null を返し、そうでなければ最小要素を返す

**関連システム・外部連携**：
本機能は純粋な数学演算関数であり、外部システムとの連携はない。

**権限による制御**：
本機能は純粋関数（pure function）として実装されており、副作用がなく、権限による実行制御は不要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本プロジェクト（Hack Standard Library）はUIを持たないライブラリプロジェクトのため、画面機能マッピングは該当しない |

## 機能種別

計算処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $numbers | Traversable<T as num> | Yes | 最小値を求める数値のコレクション | なし |

### 入力データソース

関数呼び出し時の引数として直接指定される。vec、Set、Vector、Iterator など Traversable を実装するあらゆるコレクションが使用可能。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | ?T | コレクション内の最小要素、または空の場合は null |

### 出力先

関数の戻り値として呼び出し元に返される。

## 処理フロー

### 処理シーケンス

```
1. 引数 $numbers を受け取る
   └─ Traversable<T as num> 型のコレクション
2. 最小値変数を null で初期化
   └─ $min = null
3. コレクションを走査
   └─ foreach ($numbers as $number)
4. 各要素を比較
   ├─ $min が null、または $number < $min の場合
   └─ $min = $number に更新
5. 最小値を返す
   └─ 空のコレクションの場合は null
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B["$min = null"]
    B --> C{$numbers に要素あり?}
    C -->|No| G[null を返す]
    C -->|Yes| D[次の $number を取得]
    D --> E{"$min === null または $number < $min?"}
    E -->|Yes| F["$min = $number"]
    E -->|No| C
    F --> C
    C -->|走査完了| H["$min を返す"]
    G --> I[終了]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 空コレクション | 空のコレクションに対しては null を返す | $numbers が空の場合 |
| BR-002 | 型保持 | 戻り値の型は入力要素の型と同じ（int または float） | 常に適用 |
| BR-003 | 純粋関数 | 同じ入力に対して常に同じ出力を返す | 常に適用 |
| BR-004 | 厳密比較 | < 演算子による比較（数値の大小比較） | 常に適用 |

### 計算ロジック

線形走査による最小値探索：
- 時間計算量: O(n) - n は要素数
- 空間計算量: O(1) - 追加のメモリ使用は定数

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を行わない純粋な計算関数である。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 本関数はエラーをスローしない | - |

### リトライ仕様

該当なし（エラーが発生しないため）

## トランザクション仕様

該当なし（データベース操作を行わないため）

## パフォーマンス要件

コレクションを一度だけ走査するため、時間計算量は O(n) である。追加のメモリ使用は定数（O(1)）であり、大きなコレクションに対しても効率的に動作する。

## セキュリティ考慮事項

純粋関数として実装されており、副作用がないため、セキュリティ上のリスクはない。

## 備考

- 固定数の入力値に対しては `Math\minva` 関数を使用することで、null チェックが不要になる
- 最大値を求める場合は `Math\max` 関数を使用する
- 数値以外のオブジェクトから最小値を求める場合は `Math\min_by` 関数を使用する
- 負の値を含むコレクションに対しても正しく動作する

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: min 関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | containers.php | `src/math/containers.php` | min 関数の実装（97-114行目）を確認。線形走査による最小値探索アルゴリズムを理解する |

**主要処理フロー**:
1. **97-103行目**: 関数のドキュメントコメント - minva と max への参照を含む
2. **104-106行目**: 関数シグネチャ `function min<T as num>(Traversable<T> $numbers)[]: ?T` - ジェネリック型と nullable 戻り値
3. **107行目**: 最小値変数の初期化 `$min = null`
4. **108-112行目**: foreach による走査と比較ロジック（< 比較）
5. **113行目**: 結果を返す

**読解のコツ**: max 関数との違いは比較演算子のみ（> vs <）。対称的な実装になっている。

#### Step 2: 関連する関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | containers.php | `src/math/containers.php` | max 関数（21-31行目）の実装を比較。min と対称的な実装であることを確認 |
| 2-2 | compare.php | `src/math/compare.php` | minva 関数（33-51行目）の実装を確認。可変長引数版との違いを理解する |

#### Step 3: テストケースを確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MathContainersTest.php | `tests/math/MathContainersTest.php` | provideTestMin メソッド（122-143行目）とtestMin メソッド（145-151行目）を確認 |

**主要処理フロー**:
- **123-127行目**: 空の vec に対するテスト - null が返される
- **128-132行目**: Set に対するテスト - 0 が返される
- **133-138行目**: Iterator に対するテスト - 0 が返される
- **139-142行目**: 負の値を含む Vector に対するテスト - -5 が返される

### プログラム呼び出し階層図

```
Math\min($numbers)
    │
    ├─ $min = null の初期化
    │
    └─ foreach ($numbers as $number)
           │
           └─ if ($min === null || $number < $min)
                  └─ $min = $number
```

### データフロー図

```
[入力]                           [処理]                        [出力]

Traversable<T as num> ───▶ foreach で走査 ───▶ ?T 最小値
      $numbers                    │                 または null
                                  ▼
                           各要素を比較
                           最小値を更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| containers.php | `src/math/containers.php` | ソース | min 関数の実装ファイル（コレクション操作関数群） |
| compare.php | `src/math/compare.php` | ソース | minva 関数（可変長引数版の最小値） |
| MathContainersTest.php | `tests/math/MathContainersTest.php` | テスト | min 関数を含むコレクション関数のユニットテスト |
