# 機能設計書 75-replace_values

## 概要

本ドキュメントは、dplyrパッケージの`replace_values()`関数に関する機能設計書です。`replace_values()`は、既存のベクトルの一部の値を部分的に更新するための関数です。

### 本機能の処理概要

`replace_values()`関数は、ベクトル内の特定の値を別の値に置き換えます。`recode_values()`と異なり、マッチしなかった値は元の値が保持されるため、ベクトルの部分的な更新に適しています。

**業務上の目的・背景**：データクリーニングにおいて、特定の値だけを修正したい場合があります。例えば、誤ったコード値の修正、欠損値の補完、外れ値の処理などです。`replace_values()`は、元のデータを基本的に保持しながら、特定の値だけを置き換えるという意図を明確に表現できます。

**機能の利用シーン**：
- 特定の値だけを修正する場合
- NA値を特定の値で補完する場合
- 複数の異なる値を同一の値に統合する場合
- データの正規化（例：表記ゆれの統一）

**主要な処理内容**：
1. フォーミュラ形式またはfrom/toベクトル形式で置換ルールを受け取る
2. 入力ベクトルの型に基づいて置換を実行
3. マッチしなかった値は元の値を保持
4. 結果ベクトルを返却（入力と同じ型）

**関連システム・外部連携**：外部システムとの連携はありません。内部でvctrsパッケージの`vec_replace_values()`を使用します。

**権限による制御**：特になし。Rの関数として公開されており、dplyrをロードした任意のユーザーが使用可能です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはRライブラリであり、ユーザーインターフェース画面は存在しません |

## 機能種別

値変換 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | vector | Yes | 更新対象のベクトル | ベクトルであること |
| ... | dynamic-dots | No | フォーミュラ形式の置換ルール（from ~ to） | fromとtoと排他的 |
| from | vector/list | No | 置換対象の値（...と排他的） | ...と排他的 |
| to | vector/list | No | 置換後の値（...と排他的） | ...と排他的 |

### 入力データソース

関数の引数として直接渡されるベクトル。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | vector | 入力xと同じ型、同じ長さのベクトル。名前もxから継承 |

### 出力先

呼び出し元のR環境に返却されます。

## 処理フロー

### 処理シーケンス

```
1. 引数の検証
   └─ check_dots_unnamed()で名前付き引数がないことを確認
2. 置換ルールの解析
   └─ eval_formulas_or_from_and_to()でフォーミュラまたはfrom/toを解析
3. 置換の実行
   └─ vec_replace_values()で実際の置換を実行
4. 結果の返却
   └─ 入力と同じ型のベクトルを返却
```

### フローチャート

```mermaid
flowchart TD
    A[replace_values呼び出し] --> B[引数の検証]
    B --> C{どの形式?}
    C -->|フォーミュラ| D[eval_formulasで解析]
    C -->|from/to| E[from/toをそのまま使用]
    C -->|何もなし| F[入力をそのまま返却]
    D --> G[vec_replace_values実行]
    E --> G
    G --> H[結果を返却]
    F --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | 型安定 | 出力は入力xと同じ型 | 常時 |
| BR-75-02 | 名前継承 | 出力の名前はxから継承 | 常時 |
| BR-75-03 | 未マッチ保持 | マッチしなかった値は元の値を保持 | 常時 |
| BR-75-04 | 排他的引数 | ...とfrom/toは同時に指定不可 | 常時 |
| BR-75-05 | 空呼び出し | 置換ルールなしの場合は入力をそのまま返却 | 引数なしの場合 |
| BR-75-06 | NA完全一致 | NAはNA（同じ型のNA）に正確にマッチ | NA置換時 |

### 計算ロジック

**フォーミュラ形式**:
- `from ~ to`の形式で指定
- 左辺（LHS）がマッチ対象、右辺（RHS）が置換値
- 複数のfromを`c(from1, from2) ~ to`でグループ化可能

**from/toベクトル形式**:
- `from`と`to`は同じ長さ、または`to`が長さ1
- `from`がリストの場合、各要素がグループとして扱われる

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

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

本機能はデータベースを直接操作しません。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | メモリ内データの操作のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | エラー | ...とfromを同時に指定 | どちらか一方のみ使用 |
| - | エラー | ...とtoを同時に指定 | どちらか一方のみ使用 |
| - | エラー | fromのみ指定（toなし） | toも指定する |
| - | エラー | toのみ指定（fromなし） | fromも指定する |
| - | エラー | fromの値がxの型に変換不可 | 互換性のある型を使用 |
| - | エラー | toの値がxの型に変換不可 | 互換性のある型を使用 |

### リトライ仕様

リトライ機構はありません。

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

トランザクション管理はありません（メモリ内操作のため）。

## パフォーマンス要件

- 線形時間計算量（O(n)）で動作
- 内部でvctrsの効率的な実装を使用

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

特別なセキュリティ考慮事項はありません。

## 備考

- `recode_values()`との違いは、未マッチ値の扱い
- `recode_values()`は未マッチ値をNAまたはデフォルト値に、`replace_values()`は元の値を保持
- `replace_when()`と同様に、置換ルールなしでも動作（no-op）
- 型安定性が保証されており、互換性のない型への変換は不可

---

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

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

### 推奨読解順序

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

入出力の型とvctrsの役割を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | recode-values.R | `R/recode-values.R` | 関数定義とドキュメント |

**読解のコツ**: vctrsパッケージの型強制（coercion）と再利用（recycling）の概念を理解しておくと、エラーメッセージの意味が理解しやすくなります。

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

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | recode-values.R | `R/recode-values.R` | replace_values関数の定義（345-377行目） |

**主要処理フロー**:
1. **351行目**: check_dots_unnamed()で名前付き引数がないことを確認
2. **353-364行目**: eval_formulas_or_from_and_to()で置換ルールを解析
3. **366-376行目**: vec_replace_values()を呼び出し

#### Step 3: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | recode-values.R | `R/recode-values.R` | eval_formulas_or_from_and_to（379-428行目） |
| 3-2 | recode-values.R | `R/recode-values.R` | determine_implementation（430-469行目） |

**主要処理フロー（eval_formulas_or_from_and_to）**:
- **387-392行目**: determine_implementation()で"dots"か"from-to"かを判定
- **394-409行目**: "dots"の場合はeval_formulas()でフォーミュラを解析
- **411-416行目**: "from-to"の場合はfrom/toをそのまま使用

**主要処理フロー（determine_implementation）**:
- **436-451行目**: ...とfrom/toの同時指定をエラーとする
- **455-464行目**: fromとtoの片方のみ指定をエラーとする
- **466-468行目**: 何も指定されていない場合は"dots"を返す（no-op用）

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

```
replace_values(x, ...) [R/recode-values.R:345-377]
    │
    ├─ check_dots_unnamed() [rlang]
    │      └─ 名前付き引数がないことを確認
    │
    ├─ eval_formulas_or_from_and_to() [R/recode-values.R:379-428]
    │      │
    │      ├─ determine_implementation() [R/recode-values.R:430-469]
    │      │      └─ "dots"か"from-to"かを判定
    │      │
    │      └─ eval_formulas() [case-when.R内の関数]
    │             └─ フォーミュラを解析
    │
    └─ vec_replace_values() [vctrs]
           └─ 実際の値置換を実行
```

### データフロー図

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

x (vector) ─────────────▶ check_dots_unnamed()
                                │
                                ▼
... または from/to ───────▶ eval_formulas_or_from_and_to()
                                │
                                ├─▶ determine_implementation()
                                │         │
                                │         ▼
                                │   "dots" or "from-to"
                                │
                                ▼
                          from, toリストを取得
                                │
                                ▼
                          vec_replace_values()
                                │
                                ▼
                           結果ベクトル ───────────▶ 呼び出し元
                           (xと同じ型、名前継承)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| recode-values.R | `R/recode-values.R` | ソース | replace_values/recode_values関数の実装 |
| test-recode-values.R | `tests/testthat/test-recode-values.R` | テスト | テストケース |
| recode.R | `R/recode.R` | ソース | 旧関数recode（superseded） |
