# 機能設計書 131-sin

## 概要

本ドキュメントは、Hack Standard Library (HSL) の Math 名前空間における `sin` 関数の機能設計書である。この関数は、与えられた角度（ラジアン単位）のサイン（正弦）値を計算して返す三角関数である。

### 本機能の処理概要

**業務上の目的・背景**：
三角関数は科学技術計算、ゲーム開発、グラフィックス処理、信号処理など幅広い分野で必要とされる基本的な数学演算である。`Math\sin` 関数は、Hack 言語において型安全かつ直感的なインターフェースでサイン値を計算する手段を提供する。HHVM 組み込みの `\sin` 関数をラップし、HSL の統一的な API 設計に従った形で提供することで、開発者の利便性を高めている。

**機能の利用シーン**：
- 2D/3D グラフィックスにおける座標変換・回転処理
- 波形生成やオーディオ信号処理
- 物理シミュレーションにおける周期運動の計算
- 三角測量や測位システムの計算
- 科学技術計算やデータ分析における数学的処理

**主要な処理内容**：
1. 入力値（num 型）を受け取る
2. 入力値を float 型にキャストする
3. 組み込みの `\sin` 関数を呼び出してサイン値を計算する
4. 計算結果（float 型）を返す

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

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

## 関連画面

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

## 機能種別

計算処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $arg | num | Yes | サインを計算する角度（ラジアン単位） | なし（任意の数値を受け入れる） |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | float | 入力角度のサイン値（-1.0 から 1.0 の範囲） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 引数 $arg を受け取る
   └─ num 型（int または float）の値を受け取る
2. float 型へのキャスト
   └─ (float)$arg で明示的に float に変換
3. 組み込み \sin 関数の呼び出し
   └─ HHVM の組み込みサイン関数で計算を実行
4. 計算結果を返す
   └─ float 型のサイン値を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数 $arg を受け取る]
    B --> C[$arg を float にキャスト]
    C --> D[組み込み \sin 関数を呼び出し]
    D --> E[サイン値を返す]
    E --> F[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ラジアン入力 | 入力値はラジアン単位として解釈される | 常に適用 |
| BR-002 | 純粋関数 | 同じ入力に対して常に同じ出力を返す | 常に適用 |
| BR-003 | 型変換 | int 型の入力も自動的に float に変換される | 常に適用 |

### 計算ロジック

サイン関数は以下の数学的定義に基づく：
- sin(0) = 0
- sin(π/6) = 0.5
- sin(π/4) = √2/2
- sin(π/3) = √3/2
- sin(π/2) = 1
- sin(π) ≈ 0（浮動小数点演算による微小誤差あり）

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

純粋関数として実装されており、副作用がないため、セキュリティ上のリスクはない。入力値のバリデーションは不要であり、任意の数値入力に対して安全に動作する。

## 備考

- `Math\cos` 関数と組み合わせて使用することで、より複雑な三角関数計算が可能
- `Math\tan` 関数も関連する三角関数として利用可能
- 角度がラジアンではなく度（degree）で与えられる場合は、事前に `degrees * π / 180` で変換する必要がある

---

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

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

### 推奨読解順序

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

まず、Math 名前空間で定義されている定数を理解することで、関連する三角関数全体の設計を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.php | `src/math/constants.php` | PI 定数（29行目）と E 定数（30行目）の定義を確認。三角関数で使用される数学定数の提供方法を理解する |

**読解のコツ**: Hack 言語では `const` キーワードで名前空間レベルの定数を定義する。`Math\PI` として外部からアクセス可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compute.php | `src/math/compute.php` | sin 関数の実装（229-231行目）を確認。シンプルなラッパー実装を理解する |

**主要処理フロー**:
1. **229行目**: 関数シグネチャ `function sin(num $arg)[]: float` - num 型を受け取り float を返す純粋関数として定義
2. **230行目**: `return \sin((float)$arg);` - 入力を float にキャストして組み込み関数を呼び出し

#### Step 3: 関連する三角関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | compute.php | `src/math/compute.php` | cos 関数（107-109行目）、tan 関数（247-249行目）の実装パターンを比較。三角関数群の統一的な実装方針を理解する |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | MathComputeTest.php | `tests/math/MathComputeTest.php` | provideTestSin メソッド（426-438行目）とtestSin メソッド（440-444行目）を確認。期待される動作と境界値を理解する |

**主要処理フロー**:
- **428-437行目**: テストケースの定義 - 0, π/2, -π/2, π, -π, 3π/2, π/6, π/3, π/4 での期待値
- **441-444行目**: テスト実行とアサーション - `toAlmostEqual` による浮動小数点比較

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

```
Math\sin($arg)
    │
    └─ \sin((float)$arg)
           └─ HHVM 組み込み sin 関数
```

### データフロー図

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

num $arg ───▶ (float)$arg キャスト ───▶ float サイン値
                    │
                    ▼
            \sin() 組み込み関数
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compute.php | `src/math/compute.php` | ソース | sin 関数の実装ファイル（三角関数・指数関数などの計算関数群） |
| constants.php | `src/math/constants.php` | ソース | PI, E などの数学定数定義 |
| compare.php | `src/math/compare.php` | ソース | 数値比較関数（maxva, minva など） |
| MathComputeTest.php | `tests/math/MathComputeTest.php` | テスト | sin 関数を含む計算関数のユニットテスト |
