# 機能設計書 126-round

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\round` 関数に関する機能設計書である。この関数は、数値を指定された精度で四捨五入し、結果をfloat型で返す。正の精度は小数点以下の桁数、負の精度は整数部分の丸めを指定する。

### 本機能の処理概要

**業務上の目的・背景**：四捨五入は、金額計算での端数処理、統計データの丸め、表示用数値のフォーマットなど、多くの業務処理で必要とされる基本的な数学演算である。`Math\round`関数は、PHPの`round`関数をラップし、精度パラメータにより柔軟な丸め処理を提供する。

**機能の利用シーン**：金額の小数点以下を丸める処理、統計値の有効数字指定、表示用数値の桁揃え、科学計算での有効桁数制御、概算値への変換（10の位への丸め等）など。

**主要な処理内容**：
1. 入力値（intまたはfloat）と精度をPHPのround関数に渡す
2. round関数が計算した結果（四捨五入値）をfloatとして返却

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

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

## 関連画面

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

## 機能種別

計算処理 / 数学関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $val | num | Yes | 四捨五入対象の数値（intまたはfloat） | なし |
| $precision | int | No | 丸めの精度（デフォルト: 0） | なし |

### 入力データソース

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

### 精度パラメータの解釈

| 精度値 | 丸め位置 | 例 |
|-------|---------|-----|
| 2 | 小数点以下2桁 | 549.375 → 549.38 |
| 1 | 小数点以下1桁 | 549.375 → 549.4 |
| 0 | 整数部分（デフォルト） | 549.375 → 549.0 |
| -1 | 10の位 | 549.375 → 550.0 |
| -2 | 100の位 | 549.375 → 500.0 |
| -3 | 1000の位 | 549.375 → 1000.0 |
| -4 | 10000の位 | 549.375 → 0.0 |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | float | 四捨五入された値 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. PHPのround関数を呼び出し
   └─ \round($val, $precision) を実行
2. 結果をfloatとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[PHPのround関数を呼び出し]
    B --> C[四捨五入値をfloatで返却]
    C --> D[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 四捨五入定義 | 0.5以上は切り上げ、0.5未満は切り捨て | 常に適用 |
| BR-002 | 正の精度 | 正の精度は小数点以下の桁数を指定 | $precision > 0 の場合 |
| BR-003 | 負の精度 | 負の精度は10の累乗単位での丸めを指定 | $precision < 0 の場合 |
| BR-004 | デフォルト精度 | 精度未指定時は0（整数への丸め） | $precision省略時 |
| BR-005 | 負数の四捨五入 | 負の数も同様に0.5基準で丸められる | $val < 0の場合 |

### 計算ロジック

```
round(x, precision) = ⌊x × 10^precision + 0.5⌋ / 10^precision

例:
round(3.5, 0) = 4.0
round(-3.5, 0) = -4.0 (銀行丸めではなく標準の四捨五入)
round(0.25, 1) = 0.3
round(-0.25, 1) = -0.3
round(549.375, -1) = 550.0
```

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- 常に切り上げの場合は `Math\ceil()` を使用
- 常に切り捨ての場合は `Math\floor()` を使用
- capability context: `[]`（純粋関数）

---

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

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

### 推奨読解順序

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

Hackのnum型と精度パラメータの概念を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compute.php | `src/math/compute.php` | num型の入力と精度パラメータ |

**読解のコツ**: 精度パラメータは正の値で小数点以下の桁数、負の値で10の累乗単位の丸めを指定する。

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

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

**主要処理フロー**:
1. **213-218行目**: ドキュメントコメント - 精度パラメータの説明
2. **219行目**: 関数シグネチャ - `num $val`と`int $precision = 0`
3. **220行目**: PHPのround関数を呼び出して結果を返す

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

```
Math\round($val, $precision)
    │
    └─ \round($val, $precision)
```

### データフロー図

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

num型数値      ───▶
                    PHP\round()   ───▶  float型数値
int精度        ───▶                     (四捨五入値)
```

### 関連ファイル一覧

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