# 機能設計書 32-format_number

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\format_number` 関数の機能設計について記載する。この関数は数値を桁区切り付きの文字列にフォーマットする機能を提供する。

### 本機能の処理概要

`Str\format_number` 関数は、数値（整数または浮動小数点数）を指定されたフォーマットで桁区切り文字列に変換するための関数である。小数点の桁数、小数点記号、桁区切り記号をカスタマイズ可能で、国際化対応の数値表示に対応している。

**業務上の目的・背景**：数値を人間が読みやすい形式で表示することは、レポート、請求書、統計データの表示など多くのビジネスシーンで必要とされる。特に金額表示や大きな数値の表示において、桁区切りは可読性を大幅に向上させる。また、国や地域によって小数点記号（ピリオドまたはカンマ）や桁区切り記号が異なるため、カスタマイズ可能な数値フォーマット機能は国際化対応アプリケーションにおいて不可欠である。

**機能の利用シーン**：
- 金額表示（例: 8,675,309.00）
- 統計データの表示（例: 人口 1,234,567人）
- 国際化対応の数値表示（欧州形式: 1.234.567,89）
- レポート・帳票での数値フォーマット

**主要な処理内容**：
1. 入力数値をfloat型にキャスト
2. 指定された小数点以下の桁数で丸め処理
3. 千の位ごとに桁区切り記号を挿入
4. 小数点記号を適用して文字列として返却

**関連システム・外部連携**：本関数は内部でPHPの `number_format` 組み込み関数を使用する。

**権限による制御**：本機能は純粋関数であり、権限による制御は不要である。

## 関連画面

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

## 機能種別

計算処理 / 数値フォーマット変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $number | num | Yes | フォーマット対象の数値（intまたはfloat） | なし |
| $decimals | int | No | 小数点以下の桁数（デフォルト: 0） | 0以上 |
| $decimal_point | string | No | 小数点記号（デフォルト: '.'） | なし |
| $thousands_separator | string | No | 桁区切り記号（デフォルト: ','） | なし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | フォーマットされた数値文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力数値をfloat型にキャスト
   └─ 整数の場合も浮動小数点数として処理
2. number_format関数を呼び出し
   └─ 小数点桁数、小数点記号、桁区切り記号を適用
3. フォーマット済み文字列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[数値をfloatにキャスト]
    B --> C[number_format関数呼び出し]
    C --> D[フォーマット済み文字列を返却]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 小数点丸め | 指定桁数で四捨五入される | $decimals指定時 |
| BR-02 | デフォルト小数点 | 小数点記号のデフォルトはピリオド | $decimal_point未指定時 |
| BR-03 | デフォルト桁区切り | 桁区切り記号のデフォルトはカンマ | $thousands_separator未指定時 |
| BR-04 | 整数処理 | 整数も内部でfloatとして処理 | 常時 |

### 計算ロジック

- 小数点以下の丸め: 指定された桁数で四捨五入
- 例: 8675.309 を小数点2桁でフォーマット -> 8,675.31

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライ処理は不要（純粋関数のため）。

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

トランザクション管理は不要（データベース操作なし）。

## パフォーマンス要件

- 計算量: O(n) - nは結果文字列の長さ
- 純粋関数属性 `[]:` により副作用なしが保証され、最適化の対象となる

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

- 入力は数値型のみ受け付けるため、インジェクションリスクは低い
- 純粋関数のため、副作用やセキュリティリスクはない

## 備考

- num型はintまたはfloatのユニオン型
- 負の数値も正しくフォーマットされる
- 非常に大きな数値の精度はfloatの制限に依存

---

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

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

### 推奨読解順序

#### Step 1: メイン実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transform.php | `src/str/transform.php` | format_number関数のメイン実装 |

**主要処理フロー**:
- **75-83行目**: 関数のドキュメントコメント（引数の説明）
- **84-89行目**: 関数シグネチャ（4つのパラメータ定義）
- **90-95行目**: number_format関数の呼び出しと戻り値

**読解のコツ**: `num`型はHackのプリミティブ型で、`int`または`float`のいずれかを受け入れるユニオン型である。

#### Step 2: テストコードで動作を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | StrTransformTest.php | `tests/str/StrTransformTest.php` | format_numberのテストケース |

**主要処理フロー**:
- **105-143行目**: provideFormatNumberテストデータプロバイダ
- **145-159行目**: testFormatNumberテストメソッド

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

```
Str\format_number($number, $decimals, $decimal_point, $thousands_separator)
    │
    └─ \number_format((float)$number, $decimals, $decimal_point, $thousands_separator)
           └─ PHP組み込み関数
```

### データフロー図

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

$number ──────────────────┬──▶ (float)キャスト
$decimals ────────────────┼──▶
$decimal_point ───────────┼──▶ number_format() ────▶ フォーマット済み文字列
$thousands_separator ─────┘

例: 8675309, 2, '.', ',' ──▶ "8,675,309.00"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/str/transform.php` | ソース | format_number関数のメイン実装 |
| StrTransformTest.php | `tests/str/StrTransformTest.php` | テスト | format_numberのユニットテスト |
