# 機能設計書 130-cos

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\cos` 関数に関する機能設計書である。この関数は、引数（ラジアン単位）のコサイン（余弦）を計算し、結果をfloat型で返す。

### 本機能の処理概要

**業務上の目的・背景**：コサイン関数は、三角法、信号処理、グラフィックス、物理シミュレーションなど、多くの科学技術計算で必要とされる基本的な三角関数である。`Math\cos`関数は、PHPの`cos`関数をラップし、Hackの型システムと統合された型安全な実装を提供する。

**機能の利用シーン**：2D/3Dグラフィックスでの回転計算、波形生成、フーリエ変換、物理シミュレーション（振動、波動）、ゲーム開発での軌道計算、地理座標の距離計算など。

**主要な処理内容**：
1. 入力値（intまたはfloat）をfloatにキャスト
2. PHPのcos関数に渡す
3. cos関数が計算した結果（コサイン値）をfloatとして返却

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

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

## 関連画面

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

## 機能種別

計算処理 / 数学関数 / 三角関数

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

### 角度の単位

- 入力はラジアン単位
- 度数法からの変換: ラジアン = 度 x (PI / 180)

| 度数 | ラジアン | cos値 |
|-----|---------|-------|
| 0 | 0 | 1.0 |
| 30 | PI/6 | sqrt(3)/2 |
| 45 | PI/4 | sqrt(2)/2 |
| 60 | PI/3 | 0.5 |
| 90 | PI/2 | 0.0 |
| 180 | PI | -1.0 |
| 270 | 3*PI/2 | 0.0 |
| 360 | 2*PI | 1.0 |

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力値をfloatにキャスト
   └─ (float)$arg
2. PHPのcos関数を呼び出し
   └─ \cos((float)$arg) を実行
3. 結果をfloatとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力をfloatにキャスト]
    B --> C[PHPのcos関数を呼び出し]
    C --> D[コサイン値をfloatで返却]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ラジアン入力 | 入力角度はラジアン単位である | 常に適用 |
| BR-002 | 出力範囲 | 出力は-1.0から1.0の範囲の浮動小数点数 | 常に適用 |
| BR-003 | 周期性 | cos(x) = cos(x + 2*PI*n) for any integer n | 常に適用 |
| BR-004 | 偶関数 | cos(-x) = cos(x) | 常に適用 |
| BR-005 | 浮動小数点精度 | 結果は浮動小数点演算の精度限界による誤差を含む可能性がある | 常に適用 |

### 計算ロジック

```
cos(x) = 隣辺 / 斜辺 （直角三角形において）

数学的性質:
- cos(0) = 1
- cos(PI/2) = 0
- cos(PI) = -1
- cos(3*PI/2) = 0
- cos(2*PI) = 1

関連する恒等式:
- sin^2(x) + cos^2(x) = 1
- cos(2x) = cos^2(x) - sin^2(x)
```

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライは不要。純粋な計算関数である。

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

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

## パフォーマンス要件

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

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

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

## 備考

- サインを計算する場合は `Math\sin()` を使用
- タンジェントを計算する場合は `Math\tan()` を使用
- capability context: `[]`（純粋関数）
- 浮動小数点精度の関係で、厳密な0や1を期待する場合は注意が必要（例: cos(PI/2)は厳密には0ではなく非常に小さな値）

---

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

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

### 推奨読解順序

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

Hackのnum型と三角関数の入出力を理解することが重要。

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

**読解のコツ**: num型はintとfloatの両方を受け入れるユニオン型。内部でfloatにキャストされてからPHPのcos関数に渡される。

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

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

**主要処理フロー**:
1. **101-106行目**: ドキュメントコメント - sin関数とtan関数への参照
2. **107行目**: 関数シグネチャ - `num $arg`を受け取り`float`を返す
3. **108行目**: floatにキャストしてPHPのcos関数を呼び出し

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

```
Math\cos($arg)
    │
    └─ \cos((float)$arg)
```

### データフロー図

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

num型数値  ───▶  (float)キャスト
(ラジアン)              │
                        ▼
                  PHP\cos()  ───▶  float型数値
                                   (コサイン値)
```

### 関連ファイル一覧

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