# 機能設計書 45-to_int

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\to_int` 関数の機能設計を記載する。この関数は文字列を整数に変換し、変換が正確に行えない場合はnullを返す機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：文字列から整数への変換は、ユーザー入力の処理、データパース、設定ファイルの読み込みなど多くの場面で必要とされる。しかし、不正な形式の文字列を整数に変換しようとした場合のエラーハンドリングは煩雑になりやすい。本機能は、変換不可能な場合にnullを返すことで、型安全かつ簡潔なエラーハンドリングを可能にする。

**機能の利用シーン**：
- HTMLフォームからの数値入力の検証と変換
- CLIコマンドの引数パース
- CSVやJSONデータの数値フィールドの変換
- 設定ファイルの数値設定の読み込み
- IDやキーとしての文字列から数値への変換

**主要な処理内容**：
1. 入力文字列を受け取る
2. 文字列を整数にキャストし、その結果を文字列に戻す
3. 元の文字列と比較して完全一致する場合のみ整数を返す
4. 一致しない場合はnullを返す

**関連システム・外部連携**：純粋な変換処理のため外部連携なし。

**権限による制御**：本機能は純粋関数であり、権限による制御は行わない。

## 関連画面

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

## 機能種別

文字列変換処理（Transform）/ データ型変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $string | string | Yes | 整数に変換する文字列 | なし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | ?int | 変換成功時は整数値、失敗時はnull |

### 出力先

関数の戻り値として返却される。

## 処理フロー

### 処理シーケンス

```
1. 引数の受け取り
   └─ $string（対象文字列）を受け取る
2. 整数への変換とラウンドトリップ検証
   └─ (string)(int)$string === $string を評価
3. 結果の返却
   └─ 一致する場合は(int)$stringを返し、それ以外はnullを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[文字列を受け取る]
    B --> C[文字列を整数にキャスト]
    C --> D[整数を文字列に再変換]
    D --> E{元の文字列と一致?}
    E -->|Yes| F[整数値を返却]
    E -->|No| G[nullを返却]
    F --> H[終了]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-45-01 | 厳密変換 | 文字列が整数の正規表現に完全一致する場合のみ変換成功 | 常時 |
| BR-45-02 | 先頭ゼロ不許可 | "01"などの先頭ゼロ付き文字列はnullを返す | 先頭ゼロがある場合 |
| BR-45-03 | 空文字列 | 空文字列はnullを返す | 入力が空の場合 |
| BR-45-04 | 小数点不許可 | "8675.309"などの小数点を含む文字列はnullを返す | 小数点がある場合 |
| BR-45-05 | 非数値文字不許可 | "123foo"などの非数値文字を含む文字列はnullを返す | 非数値文字がある場合 |

### 計算ロジック

```hack
if ((string)(int)$string === $string) {
  return (int)$string;
}
return null;
```

このロジックにより、変換のラウンドトリップ（文字列→整数→文字列）が元の文字列と完全一致する場合のみ成功とみなす。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 本関数はエラーをスローしない（失敗時はnullを返す） | - |

### リトライ仕様

該当なし（同期的な純粋関数）

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

該当なし（データベース操作なし）

## パフォーマンス要件

- 時間計算量: O(n)、n = 文字列長
- 空間計算量: O(n)、変換後の文字列比較用

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

- 入力文字列のサニタイズは呼び出し側の責任
- 本関数自体は副作用を持たない純粋関数
- オーバーフローは考慮されないため、極端に大きな数値には注意が必要

## 備考

- 先頭ゼロ付きの数値（"011"など）は`Math\from_base('011', 10)`の使用または先頭ゼロのトリムを推奨
- 本関数は10進数整数のみ対応。他の基数は`Math\from_base`を使用すること

---

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

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

### 推奨読解順序

#### Step 1: 公開API関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transform.php | `src/str/transform.php` | 公開関数to_intの定義とドキュメンテーション |

**主要処理フロー**:
1. **354-359行目**: to_int関数の完全な実装
2. **355-358行目**: ラウンドトリップ検証による変換ロジック

**読解のコツ**: `(string)(int)$string === $string`という式は、整数へのキャストと文字列への再変換を行い、元の文字列と厳密比較することで変換の正確性を検証している。

#### Step 2: ドキュメンテーションコメントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | transform.php | `src/str/transform.php` | 346-353行目のドキュメンテーション |

**主要処理フロー**:
- **349-350行目**: 先頭ゼロ（"01"）がnullになることの説明
- **350行目**: `Math\from_base`の使用推奨

#### Step 3: テストケースで挙動を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StrTransformTest.php | `tests/str/StrTransformTest.php` | to_intのテストケースを確認 |

**主要処理フロー**:
- **787-804行目**: provideToIntとtestToIntで様々な入力パターンと期待結果を確認
- **789-795行目**: 空文字列、有効な整数、小数、非数値文字列のテストケース

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

```
Str\to_int($string)
    │
    └─ [直接実装: ラウンドトリップ検証]
           │
           ├─ (int)$string     [文字列→整数キャスト]
           └─ (string)(int)... [整数→文字列キャスト]
```

### データフロー図

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

$string (string) ──▶ (int)$string ──▶ (string)(int)$string ──▶ ?int
                          │                   │
                          │                   ▼
                          │              元の文字列と比較
                          │                   │
                          ▼                   ▼
                     一致時: int値      不一致時: null
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/str/transform.php` | ソース | 公開API関数の定義（直接実装） |
| StrTransformTest.php | `tests/str/StrTransformTest.php` | テスト | 単体テスト |
