# 機能設計書 35-pad_left

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\pad_left` 関数の機能設計について記載する。この関数は文字列を指定した長さになるまで左側からパディング文字列で埋める機能を提供する。

### 本機能の処理概要

`Str\pad_left` 関数は、入力文字列が指定された総バイト長に満たない場合に、左側（先頭）からパディング文字列を追加して指定長まで埋める機能を提供する。パディング文字列のデフォルトはスペースであり、カスタムパディング文字列も指定可能である。

**業務上の目的・背景**：固定長フィールドへの出力、ゼロパディングによる数値フォーマット、テキストの右揃え表示など、文字列を一定の長さに揃える処理は多くの業務シーンで必要とされる。特に、レポート出力やログフォーマット、ID番号の桁揃えなどにおいて、左側からのパディングは頻繁に使用される。この関数により、開発者は簡潔なコードで左パディング処理を実現できる。

**機能の利用シーン**：
- 数値のゼロパディング（例: "42" -> "00042"）
- 固定長フィールドへのデータ整形
- テキストの右揃え表示
- ファイル出力時の桁揃え
- ログフォーマットの統一

**主要な処理内容**：
1. 入力文字列と総バイト長を受け取る
2. 入力文字列の長さが総バイト長以上の場合はそのまま返却
3. 不足分のバイト数をパディング文字列で補完
4. パディング済み文字列を返却

**関連システム・外部連携**：本関数は内部で `_Str\pad_left_l` 組み込み関数を使用する。文字数（バイト数ではなく）でパディングする場合は `Str\pad_left_l` 関数を使用する。

**権限による制御**：本機能は純粋関数であり、権限による制御は不要である。

## 関連画面

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

## 機能種別

計算処理 / 文字列整形

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $string | string | Yes | パディング対象の文字列 | なし |
| $total_length | int | Yes | パディング後の総バイト長 | なし |
| $pad_string | string | No | パディングに使用する文字列（デフォルト: ' '） | なし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 左側からパディングされた文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータを受け取る
2. 入力文字列の長さを確認
   └─ 総バイト長以上の場合: そのまま返却
   └─ 総バイト長未満の場合: パディング処理に進む
3. 不足バイト数を計算
4. パディング文字列を必要回数繰り返し
   └─ 必要に応じて切り詰め
5. パディング文字列 + 元の文字列を結合
6. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{文字列長 >= 総バイト長?}
    B -->|Yes| C[そのまま返却]
    B -->|No| D[不足バイト数を計算]
    D --> E[パディング文字列を生成]
    E --> F[パディング + 元文字列を結合]
    F --> G[結果を返却]
    C --> H[終了]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パディング不要判定 | 入力長が総バイト長以上の場合はパディングしない | strlen($string) >= $total_length |
| BR-02 | デフォルトパディング | パディング文字列のデフォルトはスペース1文字 | $pad_string未指定時 |
| BR-03 | パディング切り詰め | パディング文字列が長い場合は必要分だけ使用 | パディング文字列長 > 不足バイト数 |
| BR-04 | バイト単位処理 | 長さはバイト単位で計算される | 常時 |

### 計算ロジック

- 不足バイト数 = $total_length - strlen($string)
- パディング文字列を不足バイト数分だけ生成（繰り返しまたは切り詰め）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 本関数は例外をスローしない | - |

### リトライ仕様

リトライ処理は不要（純粋関数のため）。

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

トランザクション管理は不要（データベース操作なし）。

## パフォーマンス要件

- 計算量: O(n) - nは総バイト長
- 純粋関数属性 `[]:` により副作用なしが保証され、最適化の対象となる

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

- 入力文字列はそのまま処理されるため、エスケープ処理は呼び出し元の責任
- 純粋関数のため、副作用やセキュリティリスクはない

## 備考

- 文字数（バイト数ではなく）でパディングする場合は `Str\pad_left_l` を使用
- 右側からパディングする場合は `Str\pad_right` を使用
- マルチバイト文字を含む場合、バイト長と文字数が異なる点に注意

---

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

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

### 推奨読解順序

#### Step 1: メイン実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transform.php | `src/str/transform.php` | pad_left関数のメイン実装 |

**主要処理フロー**:
- **107-118行目**: 関数のドキュメントコメント（パラメータと動作の説明）
- **119-126行目**: 関数シグネチャと実装

**読解のコツ**:
- `$total_length` はバイト長であり、UTF-8マルチバイト文字の場合は文字数と異なる
- デフォルトのパディング文字列はスペース1文字（' '）

#### Step 2: ロケール対応版を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | transform_l.php | `src/str/transform_l.php` | pad_left_l関数のロケール対応版実装 |

**主要処理フロー**:
- **74-94行目**: Localeオブジェクトを受け取り、文字数単位でパディングを実行

#### Step 3: テストコードで動作を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StrTransformTest.php | `tests/str/StrTransformTest.php` | pad_leftのテストケース |
| 3-2 | StrLocaleTest.php | `tests/str/StrLocaleTest.php` | ロケール対応版のテストケース |

**主要処理フロー**:
- **178-197行目**: providePadLeftテストデータと testPadLeftテストメソッド
- StrLocaleTest.php **200-207行目**: testPadLeftL - ロケール依存のパディングテスト

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

```
Str\pad_left($string, $total_length, $pad_string)
    │
    └─ _Str\pad_left_l($string, $total_length, $pad_string)
           └─ HHVM組み込み関数
```

### データフロー図

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

$string ─────────────────┬──▶
$total_length ───────────┼──▶ _Str\pad_left_l() ───▶ パディング済み文字列
$pad_string ─────────────┘

例: "foo", 5, " " ──▶ "  foo"
例: "foo", 6, "0" ──▶ "000foo"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/str/transform.php` | ソース | pad_left関数のメイン実装 |
| transform_l.php | `src/str/transform_l.php` | ソース | ロケール対応版pad_left_l関数の実装 |
| StrTransformTest.php | `tests/str/StrTransformTest.php` | テスト | pad_leftのユニットテスト |
| StrLocaleTest.php | `tests/str/StrLocaleTest.php` | テスト | ロケール対応版のユニットテスト |
