# 機能設計書 37-repeat

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\repeat` 関数の機能設計について記載する。この関数は入力文字列を指定回数繰り返した新しい文字列を生成する機能を提供する。

### 本機能の処理概要

`Str\repeat` 関数は、入力文字列を指定された回数（乗数）だけ繰り返した新しい文字列を生成するための関数である。乗数が0の場合は空文字列を返す。

**業務上の目的・背景**：文字列の繰り返しは、パターン生成、区切り線の作成、フォーマット用文字列の生成など、多くの場面で必要とされる。例えば、ログの区切り線（"---"を10回繰り返すなど）、インデント用スペースの生成、テスト用のダミーデータ作成などに利用される。この関数により、開発者はループを使わずに簡潔なコードで文字列の繰り返しを実現できる。

**機能の利用シーン**：
- 区切り線の生成（例: "-" を 40回繰り返して "----------------------------------------"）
- インデント用スペースの生成
- テスト用ダミーデータの作成
- パターン文字列の生成
- 固定長フィールドの埋め文字生成

**主要な処理内容**：
1. 入力文字列と乗数を受け取る
2. 乗数が負の場合は例外をスロー
3. 乗数が0の場合は空文字列を返却
4. 入力文字列を乗数回繰り返した文字列を返却

**関連システム・外部連携**：本関数は内部でPHPの `str_repeat` 組み込み関数を使用する。

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

## 関連画面

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

## 機能種別

計算処理 / 文字列生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $string | string | Yes | 繰り返す対象の文字列 | なし |
| $multiplier | int | Yes | 繰り返し回数（乗数） | 0以上 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 入力文字列を乗数回繰り返した文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータを受け取る
2. 乗数のバリデーション
   └─ 負の値の場合: InvalidArgumentExceptionをスロー
3. str_repeat関数で繰り返し処理
   └─ 乗数が0の場合: 空文字列を返却
   └─ 乗数が1以上の場合: 繰り返し文字列を返却
4. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{乗数 < 0?}
    B -->|Yes| C[InvalidArgumentExceptionをスロー]
    B -->|No| D[str_repeat関数呼び出し]
    D --> E{乗数 == 0?}
    E -->|Yes| F[空文字列を返却]
    E -->|No| G[繰り返し文字列を返却]
    F --> H[終了]
    G --> H
    C --> I[例外終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 非負乗数 | 乗数は0以上でなければならない | 常時 |
| BR-02 | ゼロ乗数 | 乗数が0の場合は空文字列を返す | $multiplier === 0 |
| BR-03 | 空文字列繰り返し | 空文字列を繰り返しても空文字列 | $string === '' |

### 計算ロジック

- 結果文字列長 = strlen($string) * $multiplier

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgumentException | 乗数が負の値 | 0以上の乗数を指定する |

### リトライ仕様

リトライ処理は不要（入力値の修正が必要）。

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

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

## パフォーマンス要件

- 計算量: O(n * m) - nは入力文字列長、mは乗数
- 純粋関数属性 `[]:` により副作用なしが保証され、最適化の対象となる
- 非常に大きな乗数を指定するとメモリを大量に消費する可能性がある

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

- 入力文字列はそのまま処理されるため、エスケープ処理は呼び出し元の責任
- 非常に大きな乗数はDoS攻撃のベクトルとなる可能性がある
- 純粋関数のため、その他のセキュリティリスクはない

## 備考

- PHPの `str_repeat` 関数と同等の機能
- 空文字列を任意回数繰り返しても空文字列が返される

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
- **149-154行目**: 関数のドキュメントコメント
- **155-161行目**: 関数シグネチャと実装
- **157-159行目**: 負の乗数チェックとInvalidArgumentException

**読解のコツ**:
- この関数は乗数のバリデーションを行い、PHPの `str_repeat` 関数を呼び出す
- 乗数が負の場合のみ例外がスローされる

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | StrTransformTest.php | `tests/str/StrTransformTest.php` | repeatのテストケース |

**主要処理フロー**:
- **220-235行目**: provideRepeatテストデータと testRepeatテストメソッド

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

```
Str\repeat($string, $multiplier)
    │
    ├─ ($multiplier < 0 の場合)
    │      └─ throw InvalidArgumentException
    │
    └─ \str_repeat($string, $multiplier)
           └─ PHP組み込み関数
```

### データフロー図

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

$string ─────────────┬──▶ バリデーション
$multiplier ─────────┼──▶ str_repeat() ────────▶ 繰り返し文字列
                     │
                     └──▶ 負の乗数 → InvalidArgumentException

例: "foo", 3 ──▶ "foofoofoo"
例: "foo", 0 ──▶ ""
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transform.php | `src/str/transform.php` | ソース | repeat関数のメイン実装 |
| StrTransformTest.php | `tests/str/StrTransformTest.php` | テスト | repeatのユニットテスト |
