# 機能設計書 59-cumany

## 概要

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

### 本機能の処理概要

**業務上の目的・背景**：時系列データやシーケンシャルデータの分析において、「最初に条件を満たした時点以降のすべてのデータ」を抽出したい場合がある。例えば、「初回購入以降のすべての取引」や「初回エラー発生以降のすべてのログ」を取得する場合である。`cumany()`は、このような「一度TRUEになったら以降すべてTRUE」という動作を効率的に実現するために設計された。

**機能の利用シーン**：初回TRUE以降のデータ抽出、累積OR計算、条件が一度満たされた後のすべてのデータの選択、`filter()`と組み合わせた「以降すべて」の抽出などに利用される。

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

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

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

## 関連画面

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

## 機能種別

計算処理 / 累積論理関数

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

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

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-01 | 累積OR | 最初のTRUE以降はすべてTRUE | 常に適用 |
| BR-59-02 | FALSE継続 | 最初のTRUEまではFALSEを出力 | TRUE未出現時 |
| BR-59-03 | NA伝播 | NAが出現するとTRUE確定までNA | NA出現時 |
| BR-59-04 | 空ベクトル | 空の入力には空の出力 | 空入力時 |

### 計算ロジック

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

使用例:
- `cumany(x >= 5)`: xが初めて5以上になった時点以降のすべて
- `cumany(!x)`: 最初のFALSEが出現した時点以降のすべて

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

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

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

---

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

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

### 推奨読解順序

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

cumany関数は、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` | `cumany()`関数の定義（113-115行目） |

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

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

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

**主要処理フロー**:
- **41-46行目**: 関数シグネチャと出力ベクトルの確保
- **49-56行目**: FALSEが続く間はFALSEを設定
- **58-64行目**: NA/FALSEが続く間はNAを設定
- **66-70行目**: TRUE以降はTRUEを設定

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

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

### データフロー図

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

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

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

### 関連ファイル一覧

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