# 機能設計書 127-int_div

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\int_div` 関数に関する機能設計書である。この関数は、整数除算を行い、商の整数部分を返す。ゼロで除算しようとした場合はDivisionByZeroExceptionをスローする。

### 本機能の処理概要

**業務上の目的・背景**：整数除算は、ページネーション計算、配列インデックス計算、リソース配分計算など、多くの業務処理で必要とされる基本的な演算である。`Math\int_div`関数は、PHPの`intdiv`関数をラップし、ゼロ除算時に明確な例外をスローすることで、より安全な整数除算を提供する。

**機能の利用シーン**：ページ番号から開始インデックスの計算、配列を等分割する際のグループ数計算、時間を分や秒に分解する処理、バイト数をキロバイト等の単位に変換する処理など。

**主要な処理内容**：
1. 分母が0でないことをチェック
2. ゼロの場合はDivisionByZeroExceptionをスロー
3. PHPのintdiv関数を使用して整数除算を実行
4. 商の整数部分をintとして返却

**関連システム・外部連携**：本機能はHSLライブラリ内部で完結し、外部システムとの連携はない。

**権限による制御**：本機能に権限による制御は存在しない。

## 関連画面

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

## 機能種別

計算処理 / 数学関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $numerator | int | Yes | 被除数（分子） | なし |
| $denominator | int | Yes | 除数（分母） | 0以外（0の場合DivisionByZeroException） |

### 入力データソース

呼び出し元から直接渡される整数パラメータ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 整数除算の商（小数部分は切り捨て） |

### 出力先

戻り値として呼び出し元に返却。

## 処理フロー

### 処理シーケンス

```
1. ゼロ除算チェック
   └─ $denominator === 0 かどうかを判定
2. 例外スロー
   └─ ゼロの場合はDivisionByZeroExceptionをスロー
3. 整数除算実行
   └─ \intdiv($numerator, $denominator) を実行
4. 結果をintとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{$denominator === 0 ?}
    B -->|Yes| C[DivisionByZeroExceptionをスロー]
    B -->|No| D[intdiv関数で整数除算]
    D --> E[商をintで返却]
    E --> F[終了]
    C --> G[異常終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ゼロ除算禁止 | 分母が0の場合は例外をスロー | $denominator === 0 の場合 |
| BR-002 | 切り捨て除算 | 商は0方向への切り捨て（truncation towards zero） | 常に適用 |
| BR-003 | 負数の除算 | 負の商は0に向かって切り捨てられる（例: -5/2 = -2） | 符号が異なる場合 |

### 計算ロジック

```
int_div(a, b) = trunc(a / b) = a / b の小数部分を0方向に切り捨て

例:
int_div(1, 2) = 0
int_div(2, 1) = 2
int_div(-1, 2) = 0
int_div(-2, 1) = -2
int_div(-5, 2) = -2
int_div(-5, -2) = 2
```

**注意**: `int_div`は0方向への切り捨て（truncation）を行う。これは`floor`関数とは異なる動作である。
- `int_div(-5, 2) = -2`（0方向への切り捨て）
- `floor(-5 / 2) = -3`（負の無限大方向への切り捨て）

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DivisionByZeroException | $denominator === 0 | 事前にゼロチェックを行う、またはtry-catchで捕捉 |

### リトライ仕様

リトライは不要。ゼロ除算は入力パラメータのエラーであり、修正が必要。

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

本機能はトランザクション制御を行わない。

## パフォーマンス要件

- 時間計算量: O(1)
- 空間計算量: O(1)

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

特になし。純粋な数学計算関数である。

## 備考

- 浮動小数点数の切り捨てには `Math\floor()` を使用
- capability context: `[]`（純粋関数）
- `Math\to_base()` 関数内部でも使用されている

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

整数除算の入出力型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compute.php | `src/math/compute.php` | int型の入出力 |

**読解のコツ**: int_div関数は整数のみを扱い、常にint型を返す。floatを扱う場合は他の関数を使用する。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compute.php | `src/math/compute.php` | int_div関数の定義（186-196行目） |

**主要処理フロー**:
1. **186-190行目**: ドキュメントコメント - floor関数との関係を記載
2. **191行目**: 関数シグネチャ - 2つのint引数を受け取りintを返す
3. **192-194行目**: ゼロ除算チェックと例外スロー
4. **195行目**: PHPのintdiv関数を呼び出して結果を返す

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

```
Math\int_div($numerator, $denominator)
    │
    ├─ ゼロ除算チェック
    │      └─ new DivisionByZeroException()
    │
    └─ \intdiv($numerator, $denominator)
```

### データフロー図

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

int $numerator  ───▶
                    ゼロチェック → intdiv()  ───▶  int（商）
int $denominator ──▶
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compute.php | `src/math/compute.php` | ソース | int_div関数の実装 |
| MathComputeTest.php | `tests/math/MathComputeTest.php` | テスト | int_div関数のユニットテスト |
