# 機能設計書 123-base_convert

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\base_convert` 関数に関する機能設計書である。この関数は、任意の基数（2〜36進数）間で数値の文字列表現を変換する。任意精度演算（BC Math）を使用して大きな数値にも対応する。

### 本機能の処理概要

**業務上の目的・背景**：異なる基数間での数値変換は、ハッシュ値の短縮表現、URLセーフなID生成、バイナリデータの可読形式への変換など、多くのシステムで必要とされる。`Math\base_convert`関数は、PHPの`base_convert`関数と異なり、任意精度演算を使用することで、整数のオーバーフローを気にせず非常に大きな数値も正確に変換できる。

**機能の利用シーン**：MD5やSHA-1ハッシュ値の短縮表現への変換、大きな数値IDの36進数表現によるURL短縮、バイナリ文字列と16進数の相互変換、異なる数値システム間でのデータ変換など。

**主要な処理内容**：
1. 入力値と基数のバリデーション
2. 元の基数から10進数（BC Math文字列）への変換
3. 10進数から目的の基数への変換
4. 結果の文字列を返却

**関連システム・外部連携**：BC Math拡張機能（bcadd、bcmul、bcdiv、bcmod、bcpow、bccomp）を使用。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 変換後の基数で表現された数値の文字列（小文字アルファベット使用） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力バリデーション
   ├─ $valueが空文字列でないことを確認
   ├─ $from_baseが2〜36の範囲であることを確認
   └─ $to_baseが2〜36の範囲であることを確認
2. 10進数への変換
   ├─ bcscaleを0に設定（整数演算）
   ├─ 各桁について位置の重みを計算（bcpow）
   └─ 各桁の値を重みと掛けて累積（bcmul、bcadd）
3. 目的基数への変換
   ├─ $to_baseが10の場合はそのまま返却
   ├─ bcmodで余りを取得して対応する文字に変換
   └─ bcdivで商を計算して繰り返し
4. 結果の返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{入力バリデーション}
    B -->|NG| C[InvariantExceptionをスロー]
    B -->|OK| D[bcscale(0)を設定]
    D --> E[各桁を10進数に変換]
    E --> F{to_base == 10?}
    F -->|Yes| G[10進数文字列を返却]
    F -->|No| H[10進数から目的基数に変換]
    H --> I[変換結果を返却]
    G --> J[終了]
    I --> J
    C --> K[異常終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 空文字列禁止 | 空の入力文字列は許可されない | 常に適用 |
| BR-002 | 基数範囲 | 基数は2〜36の範囲内である必要がある | 常に適用 |
| BR-003 | 有効文字 | 入力文字列は指定基数で有効な文字のみを含む必要がある | 常に適用 |
| BR-004 | 大文字小文字 | 入力は大文字小文字を区別しない、出力は小文字 | 常に適用 |
| BR-005 | 先頭ゼロ | 先頭のゼロは無視される（出力には含まれない） | 常に適用 |
| BR-006 | 任意精度 | BC Mathを使用し、整数オーバーフローなし | 常に適用 |

### 計算ロジック

**元の基数から10進数への変換**:
```
result_decimal = Σ(digit_value × base^position)

例: "a37" (16進数) → 10進数
= 10×16² + 3×16¹ + 7×16⁰
= 2560 + 48 + 7
= 2615
```

**10進数から目的基数への変換**:
```
while decimal > 0:
    digit = decimal mod to_base
    result = alphabet[digit] + result
    decimal = decimal div to_base
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $valueが空文字列 | 空でない文字列を渡す |
| - | InvariantException | $from_baseが2〜36の範囲外 | 有効な基数を指定 |
| - | InvariantException | $to_baseが2〜36の範囲外 | 有効な基数を指定 |
| - | InvariantException | $valueに$from_baseで無効な文字が含まれる | 有効な文字のみを含む文字列を渡す |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 時間計算量: O(n × m) - nは入力文字列長、mはBC Math演算の計算量
- 空間計算量: O(n) - 中間結果とBC Math文字列の格納に必要

BC Mathを使用するため、大きな数値でも正確に処理できるが、純粋な整数演算より低速。

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

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

## 備考

- 整数から文字列への変換には `Math\to_base()` を使用
- 文字列から整数への変換には `Math\from_base()` を使用
- ALPHABET_ALPHANUMERIC = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' を使用

---

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

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

### 推奨読解順序

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

アルファベット定数の定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | private.php | `src/private.php` | ALPHABET_ALPHANUMERIC定数の定義（53-54行目） |

**読解のコツ**: アルファベットは'0'-'9', 'a'-'z', 'A'-'Z'の順で定義されており、0-35のインデックスに対応する。

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

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

**主要処理フロー**:
1. **38-43行目**: 空文字列チェック
2. **45-49行目**: $from_baseの範囲チェック
3. **51-55行目**: $to_baseの範囲チェック
4. **57行目**: bcscale(0)で整数演算モード設定
5. **59-75行目**: 入力を10進数に変換
6. **77-78行目**: 10進数出力の場合はそのまま返却
7. **81-87行目**: 10進数から目的基数への変換

#### Step 3: BC Math関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | PHP公式ドキュメント | - | bcadd、bcmul、bcdiv、bcmod、bcpow、bccompの動作 |

**主要処理フロー**:
- bcpow: べき乗計算（位の重み計算に使用）
- bcmul: 乗算（桁値×重みの計算に使用）
- bcadd: 加算（各桁の値の累積に使用）
- bcdiv: 除算（基数で割る操作に使用）
- bcmod: 剰余（桁の値を取得に使用）
- bccomp: 比較（ループ継続条件に使用）

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

```
Math\base_convert($value, $from_base, $to_base)
    │
    ├─ invariant (空文字列チェック)
    ├─ invariant ($from_base範囲チェック)
    ├─ invariant ($to_base範囲チェック)
    │
    ├─ bcscale(0)
    │
    ├─ 10進数変換ループ
    │   ├─ Str\slice (アルファベット取得)
    │   ├─ Str\chunk (文字単位分割)
    │   ├─ Str\search_ci (文字→数値変換)
    │   ├─ bcpow (位の重み計算)
    │   ├─ bcmul (桁値×重み)
    │   ├─ bcadd (累積)
    │   └─ bcdiv (位の重み更新)
    │
    └─ 目的基数変換ループ
        ├─ bcmod (余り取得)
        ├─ ALPHABET_ALPHANUMERIC[index] (文字変換)
        ├─ bcdiv (商計算)
        └─ bccomp (ループ条件)
```

### データフロー図

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

string($value)     ───▶   各桁→数値変換     ───▶
int($from_base)           bcpow/bcmul/bcadd         10進数文字列
                              │                          │
                              ▼                          ▼
                          10進数文字列   ───▶   bcmod/bcdiv  ───▶  string
int($to_base)                             アルファベット変換    (目的基数)
```

### 関連ファイル一覧

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