# 機能設計書 62-when_all

## 概要

本ドキュメントは、dplyrパッケージの`when_all`関数の機能設計について記述する。`when_all`は複数の論理ベクトルに対して要素ごとの論理積（AND演算）を行う関数である。

### 本機能の処理概要

`when_all`関数は、複数の論理ベクトルを受け取り、各位置における論理積を計算する。これは`all()`関数の「並列（parallel）」版であり、`&`演算子を任意の数の入力に一般化したものである。

**業務上の目的・背景**：データ分析において、複数の条件がすべて真である行を特定する必要がある場面は非常に多い。従来は`cond1 & cond2 & cond3`のように条件を`&`で連結する必要があったが、条件数が多い場合や動的に条件を生成する場合に可読性と保守性が低下する。`when_all`はこの問題を解決し、複数条件をカンマ区切りで指定でき、`!!!`演算子でリストを展開することも可能にする。

**機能の利用シーン**：
- 複数の条件がすべて真である場合のみ処理を行う場合
- 複数のフラグ列がすべてTRUEの行を抽出する場合
- 動的に生成した条件リストを展開して適用する場合
- `filter()`内での複数条件の明示的なAND結合

**主要な処理内容**：
1. 可変長引数`...`から論理ベクトルを受け取る
2. `na_rm`引数に基づいてNA値の処理方法を決定
3. `size`引数で出力サイズを制御（空入力時に有用）
4. vctrsパッケージの`vec_pall`関数を呼び出して要素ごとのAND演算を実行
5. 各位置で論理積を計算した論理ベクトルを返す

**関連システム・外部連携**：vctrsパッケージの`vec_pall`関数に依存している。

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

## 関連画面

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

## 機能種別

計算処理 / ベクトル演算

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ... | logical vectors | No | 同じサイズの論理ベクトル群 | 論理ベクトル型であること、名前付き引数は不可 |
| na_rm | logical | No | NA値の処理方法（デフォルト: FALSE） | 論理値（TRUE/FALSE）であること |
| size | integer | No | 出力サイズ（空入力時に有用） | 整数値であること |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | logical | 各位置における論理積の結果 |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. 引数の検証
   └─ check_dots_unnamed(): 名前付き引数がないことを確認
   └─ check_bool(na_rm): na_rmが論理値であることを確認

2. NA値の処理方法決定
   └─ na_rm=TRUEの場合: missing = TRUE（NAを除外してTRUE扱い）
   └─ na_rm=FALSEの場合: missing = NA（NAを伝播）

3. vec_pall関数の呼び出し
   └─ vctrsパッケージの内部関数を使用
   └─ 要素ごとのAND演算を実行

4. 結果の返却
   └─ 論理ベクトルを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[check_dots_unnamed]
    B --> C[check_bool na_rm]
    C --> D{na_rm?}
    D -->|TRUE| E[missing = TRUE]
    D -->|FALSE| F[missing = NA]
    E --> G[vec_pall呼び出し]
    F --> G
    G --> H[論理ベクトル返却]
    H --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-62-01 | NA伝播規則 | na_rm=FALSEの場合、NA値は`&`演算子と同様に伝播する | デフォルト動作時 |
| BR-62-02 | NA除外規則 | na_rm=TRUEの場合、NA値は計算から除外される | na_rm=TRUE指定時 |
| BR-62-03 | 空入力規則 | 入力が空の場合、`all()`と一貫してTRUEを返す | 入力なしの場合 |
| BR-62-04 | サイズ整合性 | すべての入力ベクトルは同じサイズである必要がある | 常時 |

### 計算ロジック

```
when_all(x, y) は x & y と同等
when_all(x, y, z) は x & y & z と同等

NA処理（na_rm=FALSE時）:
- TRUE & NA = NA
- FALSE & NA = FALSE
- NA & NA = NA

NA処理（na_rm=TRUE時）:
- TRUE & NA = TRUE
- FALSE & NA = FALSE
- NA & NA = TRUE
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 引数エラー | 名前付き引数が渡された場合 | 名前を削除して引数を渡す |
| - | 型エラー | 論理ベクトル以外が渡された場合 | 論理ベクトルに変換する |
| - | サイズエラー | 異なるサイズのベクトルが渡された場合 | 同じサイズに揃える |
| - | 型エラー | na_rmが論理値でない場合 | TRUE/FALSEを指定する |

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

ベクトル演算を使用しており、大規模データでも効率的に動作する。vctrsパッケージの最適化された内部関数を使用。

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

特になし

## 備考

- `when_all()`は`pmin()`/`pmax()`が`min()`/`max()`の並列版であるのと同様に、`all()`の並列版である
- `when_any()`と対をなす関数であり、使い分けが重要

---

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

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

### 推奨読解順序

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

本関数は特別なデータ構造を持たないが、引数の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | when.R | `R/when.R` | 関数シグネチャと引数定義（149-162行目） |

**読解のコツ**: `when_all`は`when_any`と同じファイルで定義されており、`missing`値の設定が異なる点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | when.R | `R/when.R` | `when_all`関数本体（149-162行目） |

**主要処理フロー**:
1. **150行目**: `check_dots_unnamed()` - 名前付き引数の検証
2. **152行目**: `check_bool(na_rm)` - na_rm引数の型検証
3. **153行目**: `missing`値の決定 - na_rmがTRUEならTRUE、FALSEならNA
4. **155-161行目**: `vec_pall()`呼び出し - 実際のAND演算実行

#### Step 3: when_anyとの比較で理解を深める

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | when.R | `R/when.R` | `when_any`との違い（136行目 vs 153行目） |
| 3-2 | test-when.R | `tests/testthat/test-when.R` | テストケースによる動作仕様の確認 |

**主要な違い**:
- `when_any`: `missing = if (na_rm) FALSE else NA`
- `when_all`: `missing = if (na_rm) TRUE else NA`

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

```
when_all(...)
    │
    ├─ check_dots_unnamed()      [rlang]
    │
    ├─ check_bool(na_rm)         [rlang]
    │
    └─ vec_pall(...)             [vctrs]
           └─ 内部実装（要素ごとAND演算）
```

### データフロー図

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

論理ベクトル群 ──────▶ vec_pall() ──────▶ 論理ベクトル（要素ごとAND）
    (...引数)              │
                          │
na_rm引数 ──────────▶ missing値決定
                          │
size引数 ───────────▶ 出力サイズ制御
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| when.R | `R/when.R` | ソース | when_any/when_all関数の実装 |
| test-when.R | `tests/testthat/test-when.R` | テスト | when_any/when_allのユニットテスト |
