# 機能設計書 134-log

## 概要

本ドキュメントは、Hack Standard Library (HSL) の Math 名前空間における `log` 関数の機能設計書である。この関数は、与えられた正の数値の対数を計算して返す。底を指定しない場合は自然対数（底 e）を計算し、底を指定した場合はその底による対数を計算する。

### 本機能の処理概要

**業務上の目的・背景**：
対数関数は指数関数の逆関数であり、科学技術計算、データ分析、情報理論など幅広い分野で必要とされる基本的な数学関数である。pH 値の計算、音量のデシベル表記、情報エントロピーの計算、機械学習のロス関数など、様々な場面で使用される。`Math\log` 関数は、Hack 言語において型安全かつ柔軟なインターフェースで対数計算を提供する。底の指定がオプションであるため、自然対数と任意の底による対数の両方に対応できる。

**機能の利用シーン**：
- 科学技術計算における対数スケールの処理
- 情報理論におけるエントロピー計算
- 機械学習におけるクロスエントロピーロスの計算
- 音響工学におけるデシベル計算
- 化学における pH 値の計算
- 複利計算における期間の逆算

**主要な処理内容**：
1. 入力値（num 型）と底（オプションの num 型）を受け取る
2. 入力値が正であることを検証する
3. 底が指定されている場合、底が正かつ 1 以外であることを検証する
4. 組み込みの `\log` 関数を呼び出して対数を計算する
5. 計算結果（float 型）を返す

**関連システム・外部連携**：
本機能は純粋な数学演算関数であり、外部システムとの連携はない。HHVM ランタイムの組み込み `\log` 関数に依存する。

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

## 関連画面

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

## 機能種別

計算処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $arg | num | Yes | 対数を計算する正の数値 | $arg > 0 であること（違反時に InvariantException） |
| $base | ?num | No | 対数の底（デフォルト: null = 自然対数） | 指定時は $base > 0 かつ $base !== 1 であること |

### 入力データソース

関数呼び出し時の引数として直接指定される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | float | 入力値の対数（底が指定された場合はその底での対数、指定されない場合は自然対数） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 引数 $arg と $base を受け取る
   └─ $arg: num 型（必須）、$base: ?num 型（オプション、デフォルト null）
2. $arg のバリデーション
   └─ $arg > 0 でない場合、InvariantException をスロー
3. $base が null かどうか判定
   ├─ null の場合: \log((float)$arg) を呼び出し（自然対数）
   └─ null でない場合:
       ├─ $base > 0 でない場合、InvariantException をスロー
       ├─ $base === 1 の場合、InvariantException をスロー
       └─ \log((float)$arg, (float)$base) を呼び出し
4. 計算結果を返す
   └─ float 型の対数値を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数 $arg, $base を受け取る]
    B --> C{$arg > 0?}
    C -->|No| D[InvariantException をスロー]
    C -->|Yes| E{$base === null?}
    E -->|Yes| F[自然対数 \log$arg を計算]
    E -->|No| G{$base > 0?}
    G -->|No| H[InvariantException をスロー]
    G -->|Yes| I{$base !== 1?}
    I -->|No| J[InvariantException をスロー]
    I -->|Yes| K[\log$arg, $base を計算]
    F --> L[結果を返す]
    K --> L
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 正の入力 | 対数の引数は正の数値のみ有効 | 常に適用 |
| BR-002 | 自然対数デフォルト | 底が指定されない場合は自然対数（底 e）を計算 | $base が null の場合 |
| BR-003 | 底の制約 | 底は正の数値かつ 1 以外でなければならない | $base が指定される場合 |
| BR-004 | 純粋関数 | 同じ入力に対して常に同じ出力を返す | 常に適用 |

### 計算ロジック

対数関数は以下の数学的定義に基づく：
- log_e(e) = 1（自然対数）
- log_b(b) = 1（任意の底 b）
- log_b(b^x) = x
- log_b(xy) = log_b(x) + log_b(y)
- log_b(x/y) = log_b(x) - log_b(y)
- 底の変換公式: log_b(x) = log_a(x) / log_a(b)

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $arg <= 0 の場合 | 正の数値を入力する |
| - | InvariantException | $base <= 0 の場合 | 正の数値を底として指定する |
| - | InvariantException | $base === 1 の場合 | 1 以外の数値を底として指定する |

### リトライ仕様

該当なし（入力値を修正することで解決）

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

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

## パフォーマンス要件

HHVM 組み込みの `\log` 関数をラップしているため、オーバーヘッドは最小限である。バリデーション処理が含まれるが、計算量は O(1) であり、入力値のサイズに関係なく一定時間で処理が完了する。

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

純粋関数として実装されており、副作用がないため、セキュリティ上のリスクはない。入力値のバリデーションが含まれており、不正な入力に対しては InvariantException がスローされる。

## 備考

- `Math\exp` 関数は逆関数として使用可能（log と exp は互いに逆関数）
- 底 10 の常用対数が必要な場合は `Math\log($x, 10)` と指定
- 底 2 の二進対数（情報理論で使用）が必要な場合は `Math\log($x, 2)` と指定

---

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

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

### 推奨読解順序

#### Step 1: 定数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.php | `src/math/constants.php` | E 定数（30行目）の定義を確認。自然対数の底として使用される |

#### Step 2: log 関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compute.php | `src/math/compute.php` | log 関数の実装（198-211行目）を確認。バリデーションロジックと条件分岐を理解する |

**主要処理フロー**:
1. **198-202行目**: 関数のドキュメントコメント - exp 関数への参照を含む
2. **203行目**: 関数シグネチャ `function log(num $arg, ?num $base = null)[]: float`
3. **204行目**: 引数の正値バリデーション `invariant($arg > 0, ...)`
4. **205-207行目**: 底が null の場合は自然対数を返す
5. **208行目**: 底の正値バリデーション `invariant($base > 0, ...)`
6. **209行目**: 底が 1 でないことのバリデーション `invariant($base !== 1, ...)`
7. **210行目**: 底を指定した対数を返す

**読解のコツ**: `invariant()` は Hack の組み込み関数で、条件が false の場合に InvariantException をスローする。

#### Step 3: 関連する関数（逆関数）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | compute.php | `src/math/compute.php` | exp 関数（170-172行目）の実装を確認。log と exp の関係性を理解する |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | MathComputeTest.php | `tests/math/MathComputeTest.php` | provideTestLog メソッド（357-363行目）とtestLog メソッド（365-371行目）を確認。様々な底でのテストを理解する |
| 4-2 | MathComputeTest.php | `tests/math/MathComputeTest.php` | provideTestLogNoBase メソッド（373-380行目）とtestLogNoBase メソッド（382-386行目）を確認。自然対数のテストを理解する |
| 4-3 | MathComputeTest.php | `tests/math/MathComputeTest.php` | testLogException メソッド（388-393行目）を確認。エラーケースのテストを理解する |

**主要処理フロー**:
- **358-362行目**: 底として e, 10, 2 を使用したテストケース
- **389-392行目**: エラーケースのテスト - 負の引数、0 の底、負の底、1 の底

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

```
Math\log($arg, $base)
    │
    ├─ invariant($arg > 0, ...)
    │
    ├─ $base === null の場合
    │      └─ \log((float)$arg)
    │             └─ HHVM 組み込み log 関数（自然対数）
    │
    └─ $base !== null の場合
           ├─ invariant($base > 0, ...)
           ├─ invariant($base !== 1, ...)
           └─ \log((float)$arg, (float)$base)
                  └─ HHVM 組み込み log 関数（底指定）
```

### データフロー図

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

num $arg ─────────┐
                  │
                  ▼
              バリデーション
              ($arg > 0)
                  │
?num $base ───────┼─────▶ 条件分岐 ─────────────────▶ float 対数値
                  │       │
                  │       ├─ null: \log($arg)
                  │       │
                  │       └─ 非null: バリデーション後
                  │                 \log($arg, $base)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compute.php | `src/math/compute.php` | ソース | log 関数の実装ファイル |
| constants.php | `src/math/constants.php` | ソース | E 定数の定義（自然対数の底） |
| MathComputeTest.php | `tests/math/MathComputeTest.php` | テスト | log 関数を含む計算関数のユニットテスト |
