# 機能設計書 128-from_base

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\from_base` 関数に関する機能設計書である。この関数は、指定された基数（2〜36進数）で表現された文字列を整数（int）に変換する。整数オーバーフローが発生する場合や無効な入力の場合はInvariantExceptionをスローする。

### 本機能の処理概要

**業務上の目的・背景**：16進数のカラーコード、2進数のビットフラグ、8進数のファイルパーミッションなど、異なる基数で表現された数値を整数として処理する必要がある場合に使用する。`Math\from_base`関数は、性能を重視した実装により、文字から数値への変換を高速に行う。

**機能の利用シーン**：16進カラーコード（#FF0000等）の整数値への変換、ファイルパーミッション（755等）の8進数解釈、バイナリ文字列の整数化、36進数短縮URLの復元など。

**主要な処理内容**：
1. 入力文字列と基数のバリデーション
2. 各桁の文字を対応する数値に変換
3. 位置の重みを考慮して累積計算
4. 整数オーバーフローをチェックしながら結果を計算
5. 結果をintとして返却

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

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

## 関連画面

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

## 機能種別

計算処理 / 数学関数 / 基数変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $number | string | Yes | 変換対象の数値を表す文字列 | 空文字列不可、指定基数で有効な文字のみ |
| $from_base | int | Yes | 入力文字列の基数 | 2以上36以下 |

### 入力データソース

呼び出し元から直接渡される文字列と整数パラメータ。

### 有効な文字

| 基数範囲 | 有効な文字 |
|---------|-----------|
| 2-10 | 0-9（基数未満の数字） |
| 11-36 | 0-9, a-z（またはA-Z） |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 変換された整数値 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力バリデーション
   ├─ $numberが空文字列でないことを確認
   └─ $from_baseが2〜36の範囲であることを確認
2. オーバーフロー制限の計算
   └─ limit = PHP_INT_MAX / $from_base
3. 各桁の処理ループ
   ├─ 文字をord()でASCIIコードに変換
   ├─ 数字/小文字/大文字を判定して数値に変換
   ├─ 数値が基数未満であることを確認
   ├─ オーバーフローチェック
   └─ result = result * base + digit_value
4. 結果をintとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{入力バリデーション}
    B -->|NG| C[InvariantExceptionをスロー]
    B -->|OK| D[limit = PHP_INT_MAX / base]
    D --> E[各桁をループ処理]
    E --> F{文字は有効?}
    F -->|No| C
    F -->|Yes| G{オーバーフロー?}
    G -->|Yes| C
    G -->|No| H[result = result * base + digit]
    H --> I{全桁処理完了?}
    I -->|No| E
    I -->|Yes| J[resultを返却]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 空文字列禁止 | 空の入力文字列は許可されない | 常に適用 |
| BR-002 | 基数範囲 | 基数は2〜36の範囲内である必要がある | 常に適用 |
| BR-003 | 有効文字 | 入力文字列は指定基数で有効な文字のみを含む必要がある | 常に適用 |
| BR-004 | 大文字小文字 | アルファベットは大文字小文字を区別しない | 基数が11以上の場合 |
| BR-005 | オーバーフロー禁止 | 結果がPHP_INT_MAXを超える場合は例外 | 常に適用 |
| BR-006 | 非負数のみ | 負の数の入力はサポートしない | 常に適用 |

### 計算ロジック

```
from_base(string, base) = Σ(digit_value × base^position)

文字→数値変換:
- '0'-'9': ord(char) - 48 (0-9)
- 'a'-'z': ord(char) - 87 (10-35)
- 'A'-'Z': ord(char) - 55 (10-35)

例: from_base("4d2", 16)
= 4×16² + 13×16¹ + 2×16⁰
= 4×256 + 13×16 + 2×1
= 1024 + 208 + 2
= 1234
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $numberが空文字列 | 空でない文字列を渡す |
| - | InvariantException | $from_baseが2〜36の範囲外 | 有効な基数を指定 |
| - | InvariantException | $numberに$from_baseで無効な文字が含まれる | 有効な文字のみを含む文字列を渡す |
| - | InvariantException | 結果がPHP_INT_MAXを超える | より小さい数値または`base_convert`を使用 |

### リトライ仕様

リトライは不要。入力パラメータのエラーは修正が必要。

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

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

## パフォーマンス要件

- 時間計算量: O(n) - nは入力文字列の長さ
- 空間計算量: O(1)

ソースコードのコメントによると、この実装はdict/vecルックアップより約30%高速（インタプリタモード）〜1%高速（コンパイルモード）。プロセッサキャッシュに依存しない実装。

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

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

## 備考

- 整数から基数文字列への変換には `Math\to_base()` を使用
- 任意精度の変換には `Math\base_convert()` を使用
- capability context: `[]`（純粋関数）
- PHP_INT_MAX = 9223372036854775807（64ビット環境）

---

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

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

### 推奨読解順序

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

文字から数値への変換アルゴリズムを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compute.php | `src/math/compute.php` | ASCIIコードを使用した文字→数値変換 |

**読解のコツ**: ord()関数でASCIIコードを取得し、'0'=48, 'a'=97, 'A'=65を基準に計算。分岐はパフォーマンスのため頻度順に並べられている。

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

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

**主要処理フロー**:
1. **117-122行目**: 空文字列チェック
2. **124-128行目**: 基数範囲チェック
3. **130行目**: オーバーフロー制限の計算
4. **132-161行目**: 各桁の処理ループ
5. **141-146行目**: ASCIIコードによる文字→数値変換（パフォーマンス最適化）
6. **147-152行目**: 無効な文字のチェック
7. **153-160行目**: オーバーフローチェックと累積計算

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

```
Math\from_base($number, $from_base)
    │
    ├─ invariant (空文字列チェック)
    ├─ invariant (基数範囲チェック)
    │
    ├─ Math\int_div(PHP_INT_MAX, $from_base) [オーバーフロー制限]
    │
    └─ 各桁処理ループ
        ├─ Str\chunk($number) [文字単位分割]
        ├─ ord($digit) [ASCII変換]
        ├─ invariant (有効文字チェック)
        └─ invariant (オーバーフローチェック)
```

### データフロー図

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

string $number ───▶  Str\chunk()
                         │
                         ▼
                    各桁ループ:
                    ord() → 数値変換
                         │                    ───▶  int（結果）
int $from_base ───▶  累積計算
                    (result * base + digit)
```

### 関連ファイル一覧

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