# 機能設計書 70-cur_column

## 概要

本ドキュメントは、dplyrパッケージの`cur_column`関数の機能設計について記述する。`cur_column`は`across()`内で現在処理中の列名を取得するコンテキスト関数である。

### 本機能の処理概要

`cur_column`関数は、`across()`関数内で呼び出され、現在変換処理が適用されている列の名前を文字列として返す。これにより、列名に基づいた動的な処理が可能になる。

**業務上の目的・背景**：`across()`を使用して複数の列に同じ関数を適用する際、列名に応じて処理を変えたい場合がある。例えば、列名をログに出力する、列名に基づいて異なるパラメータを使用する、列名を含む新しい値を生成するなどの用途がある。`cur_column()`は、このような列名依存の処理を可能にする。

**機能の利用シーン**：
- `across()`内で列名に基づいた動的処理を行う場合
- 変換結果に列名を含める場合
- 列名に基づいてパラメータを切り替える場合
- デバッグ時に処理中の列名を確認する場合

**主要な処理内容**：
1. 現在のコンテキストから列名を取得（`peek_column()`）
2. 列名（文字列）を返す

**関連システム・外部連携**：コンテキスト環境に依存している。

**権限による制御**：特に権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはRライブラリであり、画面は存在しない |

## 機能種別

コンテキスト関数 / 情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | パラメータなし | - |

### 入力データソース

現在のコンテキスト環境（`peek_column()`経由で取得）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | character | 現在処理中の列名 |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. コンテキストの取得
   └─ peek_column(): 現在のコンテキストから列名を取得

2. 結果の返却
   └─ 文字列を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{across内?}
    B -->|Yes| C[peek_column]
    B -->|No| D[エラー]
    C --> E[文字列返却]
    E --> F[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-70-01 | コンテキスト制限 | `across()`内でのみ使用可能 | 常時 |
| BR-70-02 | 列名返却 | 現在処理中の列の名前を文字列で返す | 常時 |
| BR-70-03 | 列ループ | `across()`が各列を処理するごとに値が変わる | 常時 |

### 計算ロジック

```
cur_column()の動作:
- across()内でのみ有効
- 各列の処理時に、その列の名前を返す
- グループとは独立（グループ化されていても列名を返す）

例:
  df |> mutate(across(everything(), ~ paste(cur_column(), round(.x, 2))))
  # 各列の値の前に列名を付加
```

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

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

該当なし（本関数はデータベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンテキストエラー | `across()`外で呼び出された場合 | `across()`内で呼び出す |

### リトライ仕様

該当なし

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

該当なし（本関数はトランザクション処理を行わない）

## パフォーマンス要件

コンテキスト環境から文字列を取得するだけなのでO(1)で非常に高速。

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

特になし

## 備考

- `across()`のループ内でのみ有効
- `n()`や`cur_group()`などの他のコンテキスト関数とは異なり、DataMaskではなくコンテキスト環境から取得
- `.names`引数で`{.col}`プレースホルダを使用できるが、`cur_column()`はより柔軟な列名操作を可能にする

---

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

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

### 推奨読解順序

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

本関数はコンテキスト環境に依存しており、`across()`がどのように列名を設定するかを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.R | `R/context.R` | cur_column関数定義（133-135行目） |
| 1-2 | context.R | `R/context.R` | peek_column関数（164-166行目） |

**読解のコツ**: `cur_column()`は`peek_column()`を呼び出すだけ。`peek_column()`は`context_peek("column")`を呼び出す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | context.R | `R/context.R` | `cur_column`関数本体（133-135行目） |

**主要処理フロー**:
1. **134行目**: `peek_column()` - 唯一の処理行

#### Step 3: across()での設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | across.R | `R/across.R` | context_poke("column", var)（325行目） |
| 3-2 | context.R | `R/context.R` | local_column関数（167-169行目） |
| 3-3 | test-context.R | `tests/testthat/test-context.R` | エラーテスト（59行目） |

**主要ポイント**:
- **across.R 315-316行目**: 古い列名の保存と終了時の復元
- **across.R 325行目**: 各列処理時にcontext_poke("column", var)で列名を設定

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

```
cur_column()
    │
    └─ peek_column()                    [context.R]
           │
           └─ context_peek("column")    [context.R]
                  │
                  └─ context_env[["column"]]
```

### データフロー図

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

across()で設定 ──▶ context_env["column"] ──▶ cur_column() ──▶ 文字列（列名）
       │
       │   context_poke("column", var)
       │
       ▼
  各列のループ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| context.R | `R/context.R` | ソース | cur_column関数およびコンテキスト管理 |
| across.R | `R/across.R` | ソース | cur_columnの呼び出し元（列名設定） |
| test-context.R | `tests/testthat/test-context.R` | テスト | コンテキスト関数のユニットテスト |
