# 機能設計書 9-rename

## 概要

本ドキュメントは、dplyrパッケージの`rename`関数に関する機能設計書です。`rename`関数は、`new_name = old_name`構文を使用してデータフレームの列名を変更する機能を提供します。

### 本機能の処理概要

`rename`関数は、tidy-select構文を使用して個別の列名を変更するデータ操作関数です。`new_name = old_name`の形式で、変更前の列名と変更後の列名を指定します。列の内容や順序は変更されず、名前のみが変更されます。

**業務上の目的・背景**：データ分析において、列名の変更は基本的かつ頻繁に必要とされる操作です。外部データの取り込み時に列名を統一したり、分析用に分かりやすい名前に変更したりする際に使用します。SQLのAS句やALTER TABLE RENAME COLUMNに相当する機能を提供します。

**機能の利用シーン**：
- 外部データの列名を内部規約に合わせて変更
- 略語を正式名称に展開
- スペースや特殊文字を含む列名の正規化
- 分析結果のレポート用に列名を日本語化

**主要な処理内容**：
1. tidy-select式の評価（`tidyselect::eval_rename`）
2. 変更対象の列位置と新しい名前の取得
3. 元の名前配列の該当位置を更新
4. `set_names`による名前の適用

**関連システム・外部連携**：
- tidyselect: tidy-select構文のパース・評価
- rlang: quosureとデータマスキング機能

**権限による制御**：該当なし（Rライブラリのため）

## 関連画面

本プロジェクトはRライブラリ（dplyr）であり、ユーザーインターフェース画面は存在しません。

## 機能種別

データ操作（列名の変更）/ データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| .data | data.frame | Yes | 処理対象のデータフレーム | data.frameまたはその派生クラス |
| ... | tidy-select | No | リネーム指定（new_name = old_name形式） | - |

### 入力データソース

- メモリ上のdata.frame、tibble、grouped_df

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | .dataと同じ型 | 列名が変更されたデータフレーム |

### 出力先

- 関数の戻り値として返却（メモリ上）

## 処理フロー

### 処理シーケンス

```
1. tidy-select式の評価
   └─ tidyselect::eval_rename()で変更対象と新名前を取得
2. 名前配列の更新
   └─ names(.data)を取得
   └─ 変更位置の名前を新しい名前で上書き
3. 名前の適用
   └─ set_names()で新しい名前を設定
```

### フローチャート

```mermaid
flowchart TD
    A[rename開始] --> B[UseMethod dispatch]
    B --> C[rename.data.frame]
    C --> D[tidyselect::eval_rename]
    D --> E[names取得]
    E --> F[変更位置の名前を更新]
    F --> G[set_names]
    G --> H[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 行の不変 | 行は影響を受けない | 常時 |
| BR-02 | 列順序の保持 | 列の順序は変更されない | 常時 |
| BR-03 | データの不変 | 列のデータ内容は変更されない | 常時 |
| BR-04 | 属性の保持 | データフレーム属性は保持される | 常時 |
| BR-05 | グループの更新 | グループ変数名も更新される | grouped_df使用時 |

### 計算ロジック

- `tidyselect::eval_rename`で変更対象の列位置と新しい名前を取得
- 元の名前配列の該当位置のみを更新
- 指定されていない列は元の名前を維持

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

該当なし（インメモリ操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | tidyselect error | 存在しない列を指定した場合 | 正しい列名を指定 |
| - | tidyselect error | 重複する新しい名前を指定した場合 | 一意な名前を指定 |

### リトライ仕様

該当なし（同期処理のため）

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

該当なし（インメモリ操作のため）

## パフォーマンス要件

- 列名の変更のみのため非常に高速
- データのコピーは発生しない

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

- 入力データの検証はdplyrフレームワーク内で実施

## 備考

- `all_of()`と`any_of()`を使用して、名前付きベクトルで複数の列を一度にリネーム可能
- `rename_with()`は関数を使用して列名を変更する別バリアント

---

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

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

### 推奨読解順序

#### Step 1: rename関数の基本構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | rename.R | `R/rename.R` | rename関数の定義と基本フロー |

**読解のコツ**: rename関数は非常にシンプルで、主な処理はtidyselectパッケージに委譲されている。

**主要処理フロー**:
- **63-65行目**: rename関数定義（ジェネリック関数）
- **68-75行目**: rename.data.frame実装

#### Step 2: tidyselectとの連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | rename.R | `R/rename.R` | eval_renameの呼び出し |

**主要処理フロー**:
- **69行目**: tidyselect::eval_rename()で変更情報を取得
- eval_renameは変更対象の列位置と新しい名前を含む名前付きベクトルを返す

#### Step 3: 名前の適用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | rename.R | `R/rename.R` | 名前更新ロジック |

**主要処理フロー**:
- **71行目**: names(.data)で現在の名前を取得
- **72行目**: names[loc] <- names(loc)で該当位置を更新
- **74行目**: set_names()で新しい名前を適用

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

```
rename(.data, ...)
    │
    └─ UseMethod("rename")
           │
           └─ rename.data.frame(.data, ...)
                  │
                  ├─ tidyselect::eval_rename(expr(c(...)), .data)
                  │      └─ 変更対象の列位置と新名前を返す
                  │         例: c(new_name = 3) → 3列目をnew_nameに
                  │
                  ├─ names <- names(.data)
                  │
                  ├─ names[loc] <- names(loc)
                  │      └─ 該当位置の名前を更新
                  │
                  └─ set_names(.data, names)
                         └─ 新しい名前を適用
```

### データフロー図

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

.data (data.frame)  ───▶ eval_rename ───▶ 名前配列更新 ───▶ set_names
      │                       │                  │              │
      │                       ▼                  ▼              ▼
      │              loc (変更位置)       names[]更新      .data
      │              names(loc) (新名前)       │        （名前変更済み）
      │                       │                  │              │
      └───────────────────────┴──────────────────┴──────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| rename.R | `R/rename.R` | ソース | rename/rename_with関数の実装 |
| select-helpers.R | `R/select-helpers.R` | ソース | tidyselectヘルパーの再エクスポート |
