# 機能設計書 58-cumall

## 概要

本ドキュメントは、dplyrパッケージにおける`cumall()`関数の機能設計を定義する。`cumall()`は累積「すべて真」を計算する論理累積関数である。

### 本機能の処理概要

**業務上の目的・背景**：時系列データやシーケンシャルデータの分析において、「最初に条件を満たさなくなるまでの連続した区間」を抽出したい場合がある。例えば、「在庫が初めて切れるまでの日数」や「初回エラーが発生するまでの正常稼働期間」を特定する場合である。`cumall()`は、このような「連続してすべてTRUEである区間」を効率的に検出するために設計された。

**機能の利用シーン**：初回FALSEまでのTRUE区間の抽出、連続成功期間の計算、条件が崩れるまでのデータフィルタリング、`filter()`と組み合わせた先頭からの条件抽出などに利用される。

**主要な処理内容**：
1. 入力論理ベクトルを先頭から順に評価する
2. すべてTRUEである間はTRUEを出力する
3. 最初のFALSEが出現した時点で、以降はすべてFALSEを出力する
4. NAは「まだFALSEが確定しない」としてNA伝播する

**関連システム・外部連携**：C++で実装された`dplyr_cumall`関数を内部で呼び出す。高速な処理が可能。

**権限による制御**：本関数に権限による実行制御は存在しない。

## 関連画面

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

## 機能種別

計算処理 / 累積論理関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | logical | Yes | 累積ANDを計算する論理ベクトル | 論理型に変換可能であること |

### 入力データソース

Rの論理ベクトル。`filter()`内で使用される場合は、現在処理中のグループのデータが対象となる。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | logical | 入力と同じ長さの論理ベクトル。累積AND結果 |

### 出力先

関数の戻り値として返却される。通常は`filter()`の条件として使用される。

## 処理フロー

### 処理シーケンス

```
1. 入力を論理型に変換
   └─ as.logical(x)
2. C++実装を呼び出し
   └─ .Call(`dplyr_cumall`, ...)
3. 累積AND計算
   └─ 先頭からTRUEが続く間はTRUE
   └─ 最初のFALSE以降はすべてFALSE
   └─ NAはNA伝播（FALSEが確定するまで）
4. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: cumall] --> B[as.logical で型変換]
    B --> C[C++実装呼び出し]
    C --> D{現在値がTRUEか}
    D -->|TRUE| E[出力: TRUE]
    E --> F{次の要素があるか}
    F -->|Yes| D
    F -->|No| G[終了]
    D -->|FALSE| H[以降すべてFALSE]
    H --> G
    D -->|NA| I[以降NAまたはFALSE]
    I --> J{FALSEが出現したか}
    J -->|Yes| H
    J -->|No| K[NA継続]
    K --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-58-01 | 累積AND | 先頭からTRUEが続く間だけTRUE | 常に適用 |
| BR-58-02 | FALSE確定 | 最初のFALSE以降はすべてFALSE | FALSE出現時 |
| BR-58-03 | NA伝播 | NAが出現するとFALSE確定までNA | NA出現時 |
| BR-58-04 | 空ベクトル | 空の入力には空の出力 | 空入力時 |

### 計算ロジック

- `cumall(c(TRUE, TRUE, TRUE))` → `c(TRUE, TRUE, TRUE)`
- `cumall(c(TRUE, FALSE, TRUE))` → `c(TRUE, FALSE, FALSE)`
- `cumall(c(NA, TRUE, FALSE))` → `c(NA, NA, FALSE)`
- ベクトル化された`all()`と考えることができる

使用例:
- `cumall(x < 5)`: xが5未満である最初の連続区間
- `cumall(!x)`: 最初のTRUEが出現するまでの区間

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

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

本関数はインメモリのベクトル操作のみを行い、データベース操作は行わない。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | 論理型に変換できない入力 | 論理ベクトルを使用する |

### リトライ仕様

リトライは不要（同期的なインメモリ処理）。

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

トランザクション管理は不要（ステートレスな関数型処理）。

## パフォーマンス要件

- 計算量: O(n)（単一パス処理）
- メモリ使用量: O(n)（出力ベクトル用）
- C++実装により高速処理

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

特別なセキュリティ考慮事項はない。

## 備考

- `cumany()`と対になる関数
- `filter(cumall(condition))`で「条件が崩れるまで」のデータを抽出可能
- Rの標準`cumall`は存在しない（dplyr独自）

---

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

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

### 推奨読解順序

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

cumall関数は、C++実装を呼び出すシンプルなラッパーである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | funs.R | `R/funs.R` | cumall/cumany/cummeanのドキュメント（68-106行目） |

**読解のコツ**: ドキュメント内の`@section Cumulative logical functions`（73-80行目）で4つのユースケースを理解できる。

#### Step 2: Rラッパーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | funs.R | `R/funs.R` | `cumall()`関数の定義（107-109行目） |

**主要処理フロー**:
1. **107行目**: `cumall(x)`関数のシグネチャ
2. **108行目**: `.Call(\`dplyr_cumall\`, as.logical(x))`
   - `as.logical(x)`: 論理型に変換
   - `.Call()`: C++実装を呼び出し

#### Step 3: C++実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | funs.cpp | `src/funs.cpp` | `dplyr_cumall`関数の定義（3-39行目） |

**主要処理フロー**:
- **3-5行目**: 関数シグネチャと出力ベクトルの確保
- **10-17行目**: TRUEが続く間はTRUEを設定
- **21-26行目**: NA/TRUEが続く間はNAを設定
- **29-32行目**: FALSE以降はFALSEを設定

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

```
cumall(x)
    │
    ├─ as.logical(x) [型変換]
    │
    └─ .Call(`dplyr_cumall`, ...) [C++呼び出し]
           │
           └─ dplyr_cumall() [src/funs.cpp]
                  ├─ フェーズ1: TRUEが続く間TRUE
                  ├─ フェーズ2: NA/TRUEの間NA
                  └─ フェーズ3: FALSE以降FALSE
```

### データフロー図

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

x = [T,T,F,T,T]   ───▶  cumall(x)                  ───▶  [T, T, F, F, F]
                         │
                         └─▶ C++実装
                               ├─ i=0: TRUE→TRUE
                               ├─ i=1: TRUE→TRUE
                               ├─ i=2: FALSE→以降FALSE
                               ├─ i=3: →FALSE
                               └─ i=4: →FALSE

x = [T,NA,F,T]    ───▶  cumall(x)                  ───▶  [T, NA, F, F]
                         │
                         └─▶ C++実装
                               ├─ i=0: TRUE→TRUE
                               ├─ i=1: NA→NA（確定待ち）
                               ├─ i=2: FALSE→FALSE確定
                               └─ i=3: →FALSE
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| funs.R | `R/funs.R` | ソース | cumall関数のRラッパー |
| funs.cpp | `src/funs.cpp` | ソース | cumall関数のC++実装 |
| test-funs.R | `tests/testthat/test-funs.R` | テスト | 累積論理関数のテスト（109-145行目） |
