# 機能設計書 55-format

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\format` 関数の機能設計書である。この関数はフォーマット文字列を使用して、型安全なsprintf相当の文字列フォーマット処理を提供する。

### 本機能の処理概要

**業務上の目的・背景**：
文字列の書式設定は、ログ出力、ユーザーメッセージ生成、デバッグ情報の出力など、多くの場面で必要とされる。従来のPHP `sprintf` 関数は引数の型チェックが実行時に行われるため、型の不一致によるエラーが発生しやすい。`Str\format` 関数は、Hackの型システムと連携し、コンパイル時に引数の型をチェックすることで、より安全な文字列フォーマットを実現する。

**機能の利用シーン**：
- ログメッセージの生成（数値や文字列の埋め込み）
- ユーザー向けメッセージの組み立て
- デバッグ出力の整形
- 数値の桁揃えや小数点以下の精度指定
- 異なる基数（2進数、8進数、16進数）での数値表示
- 科学的表記での数値表示

**主要な処理内容**：
1. フォーマット文字列と可変長引数を受け取る
2. Hackの型システムによりコンパイル時に引数の型を検証
3. フォーマット指定子に従って各引数を変換
4. フォーマットされた文字列を生成して返却

**関連システム・外部連携**：
内部実装では `_Private\_Str\vsprintf_l` を呼び出し、PHPの `vsprintf` 関数相当の処理を行う。ロケール対応版として `Str\format_l()` も提供されている。

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

## 関連画面

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

## 機能種別

文字列フォーマット処理 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $format_string | TypedFormatString<SprintfFormat, Targs> | Yes | フォーマット文字列 | コンパイル時に型チェック |
| ...$format_args | Targs | Yes | フォーマット引数（可変長） | フォーマット指定子に対応した型 |

### フォーマット指定子一覧

| 指定子 | 引数型 | 説明 |
|--------|--------|------|
| %s | string | 文字列 |
| %d | int | 10進数整数 |
| %u | int | 符号なし10進数 |
| %b | int | 2進数 |
| %o | int | 8進数 |
| %x | int | 16進数（小文字） |
| %X | int | 16進数（大文字） |
| %f | float | 浮動小数点数 |
| %F | float | 浮動小数点数（大文字） |
| %e | float | 科学的表記（小文字） |
| %E | float | 科学的表記（大文字） |
| %g | float | %eまたは%fの短い方 |
| %c | int | ASCII文字 |
| %% | - | リテラルの%記号 |

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 関数呼び出し
   └─ Str\format($format_string, ...$format_args) が呼び出される
2. 型チェック（コンパイル時）
   └─ フォーマット文字列の指定子と引数の型を検証
3. 内部関数への委譲
   └─ _Str\vsprintf_l(null, $format_string, $format_args) を呼び出し
4. フォーマット処理
   └─ 各指定子に対応する引数を変換・埋め込み
5. 結果返却
   └─ フォーマットされた文字列を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力: $format_string, ...$format_args]
    B --> C[コンパイル時型チェック]
    C --> D[_Str\vsprintf_l呼び出し]
    D --> E[フォーマット指定子を解析]
    E --> F[各引数を変換・埋め込み]
    F --> G[フォーマット済み文字列を返却]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-01 | 型安全性 | フォーマット指定子と引数の型はコンパイル時にチェックされる | 常時 |
| BR-55-02 | 幅修飾子 | 数値で出力幅を指定可能（例: %5s） | 幅指定がある場合 |
| BR-55-03 | パディング | '文字で任意のパディング文字を指定可能（例: %'=5s） | パディング指定がある場合 |
| BR-55-04 | 精度指定 | .数値で精度を指定可能（例: %.3f） | 精度指定がある場合 |
| BR-55-05 | ロケール非依存 | %fは常にロケール非依存の出力を生成 | %f使用時 |

### 計算ロジック

特定の計算ロジックは存在しない。文字列フォーマット処理のみ。

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

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

本機能はデータベース操作を行わない純粋関数である。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンパイルエラー | フォーマット指定子と引数の型が不一致 | 正しい型の引数を渡す |

### リトライ仕様

リトライは不要（コンパイル時エラーは実行前に検出される）

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

該当なし（データベース操作を行わないため）

## パフォーマンス要件

- 純粋関数 `[]` として定義されており、副作用なし
- 型チェックはコンパイル時に行われるため、実行時オーバーヘッドなし

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

- ユーザー入力をフォーマット文字列として直接使用しないこと
- SQL文やHTML出力を生成する場合は、適切なエスケープ処理が必要
- フォーマット文字列はリテラルまたは信頼できるソースから取得すること

## 備考

- PHPの `sprintf` 関数と同等の機能を型安全に提供
- `<<__NoAutoLikes>>` 属性により自動的なlike型変換を抑制
- ロケール対応が必要な場合は `Str\format_l()` を使用
- `SprintfFormat` インターフェースによりフォーマット文字列の型を定義

---

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

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

### 推奨読解順序

#### Step 1: インターフェース定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | format.php | `src/str/format.php` | SprintfFormat インターフェース（18-53行目） |

**読解のコツ**:
- `SprintfFormat` インターフェースは各フォーマット指定子のメソッドを定義
- `format_d`, `format_s`, `format_f` などがそれぞれ %d, %s, %f に対応
- `format_0x25` は %% に対応（リテラルの%）

#### Step 2: 型定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | format.php | `src/str/format.php` | SprintfFormatQuote インターフェース（61-63行目） |
| 2-2 | format.php | `src/str/format.php` | SprintfFormatString 型定義（65行目） |

**主要ポイント**:
- `SprintfFormatQuote` はカスタムパディング文字を指定するためのインターフェース
- `SprintfFormatString` は `FormatString<SprintfFormat>` のエイリアス

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.php | `src/str/format.php` | format 関数の実装（74-84行目） |

**主要処理フロー**:
1. **74行目**: `<<__NoAutoLikes>>` 属性
2. **75-78行目**: 関数定義と引数（可変長引数を使用）
3. **79-83行目**: `_Str\vsprintf_l` への委譲

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

```
Str\format($format_string, ...$format_args)
    │
    └─ _Str\vsprintf_l(null, $format_string, $format_args)
           │
           └─ PHP vsprintf() 相当の処理
```

### データフロー図

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

$format_string ─────────────▶
 (TypedFormatString)          Str\format ────────────▶ formatted string
                                   │
...$format_args ────────────▶      │
 (mixed...)                        │
                                   ▼
                            _Str\vsprintf_l
                                   │
                                   ▼
                            vsprintf処理
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| format.php | `src/str/format.php` | ソース | format関数とインターフェース定義 |
| format_l.php | `src/str/format_l.php` | ソース | ロケール対応版のformat実装 |
| StrFormatTest.php | `tests/str/StrFormatTest.php` | テスト | format関数のユニットテスト |
