# 機能設計書 129-to_base

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\to_base` 関数に関する機能設計書である。この関数は、非負の整数を指定された基数（2〜36進数）の文字列表現に変換する。小文字アルファベット（a-z）を使用して10以上の桁を表現する。

### 本機能の処理概要

**業務上の目的・背景**：数値IDの短縮表現、16進数カラーコードの生成、2進数ビットパターンの可視化など、整数を異なる基数の文字列で表現する必要がある場合に使用する。`Math\to_base`関数は、パフォーマンスを重視した実装により、高速な変換を提供する。

**機能の利用シーン**：数値IDの36進数短縮URL生成、16進数カラーコードの生成、デバッグ用2進数表示、ハッシュ値の短縮表現、ファイルパーミッションの8進数表示など。

**主要な処理内容**：
1. 入力値と基数のバリデーション
2. 繰り返し除算により各桁の値を計算
3. 各桁の値を対応する文字に変換
4. 結果の文字列を返却

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $number | int | Yes | 変換対象の非負整数 | 0以上（負の場合InvariantException） |
| $to_base | int | Yes | 出力の基数 | 2以上36以下 |

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

### 出力文字

| 桁の値 | 出力文字 |
|-------|---------|
| 0-9 | '0'-'9' |
| 10-35 | 'a'-'z' |

## 処理フロー

### 処理シーケンス

```
1. 入力バリデーション
   ├─ $to_baseが2〜36の範囲であることを確認
   └─ $numberが0以上であることを確認
2. 変換ループ
   ├─ quotient = int_div($number, $to_base)
   ├─ remainder = $number - quotient * $to_base
   ├─ result = ALPHABET[remainder] + result
   └─ $number = quotient
3. $number === 0 になるまで繰り返し
4. 結果の文字列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{基数は2-36の範囲?}
    B -->|No| C[InvariantExceptionをスロー]
    B -->|Yes| D{$numberは非負?}
    D -->|No| C
    D -->|Yes| E[result = 空文字列]
    E --> F[quotient = int_div]
    F --> G[remainder = 余り計算]
    G --> H[result = ALPHABET#91;remainder#93; + result]
    H --> I[number = quotient]
    I --> J{number === 0 ?}
    J -->|No| F
    J -->|Yes| K[resultを返却]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 基数範囲 | 基数は2〜36の範囲内である必要がある | 常に適用 |
| BR-002 | 非負数のみ | 入力は非負整数（0以上）である必要がある | 常に適用 |
| BR-003 | 小文字出力 | 10以上の桁は小文字アルファベット（a-z）で表現 | 基数が11以上の場合 |
| BR-004 | ゼロ表現 | $number === 0 の場合は "0" を返す | $number === 0 の場合 |

### 計算ロジック

```
to_base(number, base):
    result = ""
    do:
        quotient = int_div(number, base)
        remainder = number - quotient * base
        result = ALPHABET[remainder] + result
        number = quotient
    while number !== 0
    return result

例: to_base(1234, 16)
1234 / 16 = 77 余り 2  → '2'
77 / 16 = 4 余り 13    → 'd'
4 / 16 = 0 余り 4      → '4'
結果: "4d2"
```

**パフォーマンス注記**: ソースコードのコメントによると、`%`演算子と`int_div`を使用するよりも、`int_div`と引き算で余りを計算する方がJITコンパイル時に約20%高速。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $to_baseが2〜36の範囲外 | 有効な基数を指定 |
| - | InvariantException | $numberが負の値 | 非負の整数を渡す |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 時間計算量: O(log_base(number)) - 出力文字列の長さに比例
- 空間計算量: O(log_base(number)) - 出力文字列の長さに比例

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

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

## 備考

- 文字列から整数への変換には `Math\from_base()` を使用
- 任意精度の変換には `Math\base_convert()` を使用
- capability context: `[]`（純粋関数）
- ALPHABET_ALPHANUMERIC = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
1. **258-262行目**: 基数範囲チェック
2. **263-267行目**: 非負数チェック
3. **268行目**: 結果文字列の初期化
4. **269-275行目**: do-whileループによる変換処理
5. **270行目**: パフォーマンス最適化コメント
6. **271行目**: int_divで商を計算
7. **272行目**: ALPHABET_ALPHANUMERICから文字を取得

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

```
Math\to_base($number, $to_base)
    │
    ├─ invariant (基数範囲チェック)
    ├─ invariant (非負チェック)
    │
    └─ 変換ループ
        ├─ Math\int_div($number, $to_base)
        └─ ALPHABET_ALPHANUMERIC[remainder]
```

### データフロー図

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

int $number    ───▶  do-whileループ:
                     int_div → 商
                     引き算 → 余り
                     ALPHABET[余り] → 文字  ───▶  string（基数表現）
int $to_base   ───▶
```

### 関連ファイル一覧

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