# 機能設計書 38-replace

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\replace` 関数の機能設計について記載する。この関数は文字列内の部分文字列を検索し、すべての出現箇所を置換文字列で置き換える機能を提供する。

### 本機能の処理概要

`Str\replace` 関数は、対象文字列（haystack）内の検索文字列（needle）をすべて置換文字列（replacement）に置き換えるための関数である。大文字小文字を区別して検索・置換を行う。

**業務上の目的・背景**：文字列の置換は、テンプレート処理、データクレンジング、フォーマット変換など、あらゆるテキスト処理の基本となる操作である。例えば、HTMLエスケープ、ユーザー入力の正規化、設定値の動的置換などに使用される。この関数により、開発者は簡潔なコードで文字列置換を実現できる。

**機能の利用シーン**：
- テンプレート変数の置換
- 文字列のサニタイズ処理
- データフォーマットの変換
- 不要文字の除去（空文字列への置換）
- 区切り文字の変更

**主要な処理内容**：
1. 対象文字列、検索文字列、置換文字列を受け取る
2. 検索文字列のすべての出現箇所を置換文字列に置き換え
3. 置換後の文字列を返却

**関連システム・外部連携**：本関数は内部で `_Str\replace_l` 組み込み関数を使用する。大文字小文字を無視した置換には `Str\replace_ci` 関数を使用する。

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

## 関連画面

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

## 機能種別

計算処理 / 文字列変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $haystack | string | Yes | 検索・置換対象の文字列 | なし |
| $needle | string | Yes | 検索する部分文字列 | なし |
| $replacement | string | Yes | 置換後の文字列 | なし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 検索文字列がすべて置換された文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータを受け取る
2. _Str\replace_l関数を呼び出し
   └─ 検索文字列が空の場合: 元の文字列をそのまま返却
   └─ 検索文字列が見つからない場合: 元の文字列をそのまま返却
   └─ 検索文字列が見つかった場合: すべての出現箇所を置換
3. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{検索文字列が空?}
    B -->|Yes| C[元の文字列を返却]
    B -->|No| D{検索文字列が存在?}
    D -->|No| C
    D -->|Yes| E[すべての出現箇所を置換]
    E --> F[置換後の文字列を返却]
    C --> G[終了]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 大文字小文字区別 | 検索は大文字小文字を区別する | 常時 |
| BR-02 | 全置換 | 検索文字列のすべての出現箇所を置換 | 常時 |
| BR-03 | 空検索文字列 | 検索文字列が空の場合は置換しない | $needle === '' |
| BR-04 | 検索文字列未発見 | 検索文字列が見つからない場合は元の文字列を返却 | 常時 |

### 計算ロジック

- 検索文字列のすべての出現箇所を左から順に置換文字列に置き換える

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- 計算量: O(n * m) - nは対象文字列長、mは検索文字列の出現回数
- 純粋関数属性 `[]:` により副作用なしが保証され、最適化の対象となる

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

- 入力文字列はそのまま処理されるため、エスケープ処理は呼び出し元の責任
- XSS対策やSQLインジェクション対策としての使用には注意が必要
- 純粋関数のため、その他のセキュリティリスクはない

## 備考

- 大文字小文字を無視した置換には `Str\replace_ci` を使用
- 複数の検索/置換を一括実行するには `Str\replace_every` を使用
- ロケール対応版として `Str\replace_l` も提供されている

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
- **163-172行目**: 関数のドキュメントコメント（パラメータと関連関数の説明）
- **173-179行目**: 関数シグネチャと実装

**読解のコツ**:
- この関数は内部の `_Str\replace_l` 関数を呼び出すシンプルなラッパー
- 大文字小文字を区別することが重要なポイント

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

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

**主要処理フロー**:
- **118-138行目**: Localeオブジェクトを受け取り、ロケール対応の置換を実行

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

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

**主要処理フロー**:
- **237-280行目**: provideReplaceテストデータと testReplaceテストメソッド
- StrLocaleTest.php **218-230行目**: testReplaceL - ロケール依存の置換テスト

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

```
Str\replace($haystack, $needle, $replacement)
    │
    └─ _Str\replace_l($haystack, $needle, $replacement)
           └─ HHVM組み込み関数
```

### データフロー図

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

$haystack ───────────────┬──▶
$needle ─────────────────┼──▶ _Str\replace_l() ───▶ 置換後の文字列
$replacement ────────────┘

例: "goodbye world", " ", " cruel " ──▶ "goodbye cruel world"
例: "foo", "foo", "bar" ──▶ "bar"
```

### 関連ファイル一覧

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