# 機能設計書 103-every

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `C\every` 関数の機能設計書である。この関数は、Traversableの全ての要素が指定された述語を満たすかどうかを判定する。

### 本機能の処理概要

`C\every` 関数は、与えられた `Traversable` の全ての要素に対して述語関数を適用し、全ての要素が条件を満たす場合に `true` を、一つでも条件を満たさない要素がある場合に `false` を返す関数である。述語が指定されない場合は、各要素をboolにキャストして判定する。

**業務上の目的・背景**：データ検証やバリデーション処理において、コレクション内の全要素が特定の条件を満たすことを確認する必要がある場面は多い。例えば、全ての入力値が有効範囲内にあるか、全てのオブジェクトが特定の状態にあるかを一括でチェックする場合に使用される。ショートサーキット評価により、条件を満たさない要素が見つかった時点で処理を終了するため、効率的な判定が可能である。

**機能の利用シーン**：
- フォームの全フィールドが入力されているか検証する場合
- 配列内の全ての数値が正の数かチェックする場合
- 全てのユーザーがアクティブ状態かを確認する場合
- バッチ処理で全てのレコードが処理可能な状態かを事前確認する場合
- 権限チェックで全ての必要権限を持っているか検証する場合

**主要な処理内容**：
1. 入力パラメータとして Traversable と述語関数（オプション）を受け取る
2. 述語が null の場合は、デフォルトでbool変換関数を使用
3. Traversable の各要素に対して述語を適用
4. 一つでも false を返す要素があれば即座に false を返す（ショートサーキット）
5. 全ての要素が true を返した場合、または空の Traversable の場合は true を返す

**関連システム・外部連携**：なし（純粋な関数であり、外部システムへの依存はない）

**権限による制御**：なし（ライブラリ関数のため権限制御は不要）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはUIを持たないライブラリのため画面は存在しない |

## 機能種別

判定処理 / バリデーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $traversable | Traversable<T> | Yes | 判定対象のTraversable | なし |
| $predicate | ?(function(T)[_]: bool) | No | 各要素に適用する述語関数。nullの場合はbool変換 | なし |

### 入力データソース

関数呼び出し元から引数として渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 全要素が述語を満たす場合 `true`、一つでも満たさない場合 `false` |

### 出力先

関数の戻り値として呼び出し元に返される。

## 処理フロー

### 処理シーケンス

```
1. Traversable と述語関数を引数として受け取る
   └─ 述語は省略可能（デフォルトは boolval）
2. 述語が null の場合、boolval 関数をデフォルトとして設定
   └─ _Private\boolval を使用
3. Traversable の各要素に対してループ処理
   └─ foreach で順次処理
4. 各要素に述語を適用
   └─ 述語が false を返した場合、即座に false を返す（ショートサーキット）
5. 全要素が述語を満たした場合、true を返す
   └─ 空の Traversable の場合も true を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[traversable, predicate を受け取る]
    B --> C{predicate が null?}
    C -->|Yes| D[boolval をデフォルトに設定]
    C -->|No| E[foreach ループ開始]
    D --> E
    E --> F{次の要素あり?}
    F -->|Yes| G[要素に predicate を適用]
    G --> H{結果が true?}
    H -->|Yes| E
    H -->|No| I[false を返す]
    F -->|No| J[true を返す]
    I --> K[終了]
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-103-01 | 空Traversable対応 | 空のTraversableに対しては true を返す（空真理） | Traversableが空の場合 |
| BR-103-02 | ショートサーキット | 条件を満たさない要素が見つかった時点で処理を終了し false を返す | 要素が条件を満たさない場合 |
| BR-103-03 | デフォルト述語 | 述語が null の場合、各要素のbool変換結果を使用 | 述語が指定されない場合 |
| BR-103-04 | all相当 | C\all を探している場合は本関数を使用する | ドキュメントに明記 |

### 計算ロジック

特になし（論理判定のみで複雑な計算処理は含まれない）

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

該当なし（本機能はインメモリのコレクション操作のみを行う）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TypeError | 型エラー | 述語が bool を返さない場合 | 型チェッカーがコンパイル時に検出 |

### リトライ仕様

該当なし（同期処理であり、リトライの必要性はない）

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

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

## パフォーマンス要件

- 時間計算量: O(n) - 最悪の場合、全要素をチェック
- 空間計算量: O(1)
- ショートサーキット評価により、条件を満たさない要素が見つかった時点で処理終了

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

- 純粋関数であり、外部への副作用がないためセキュリティリスクは低い
- 述語関数は呼び出し元から渡されるため、述語内での副作用には注意が必要

## 備考

- `C\any` 関数と対をなす関数であり、any は「いずれかが true」、every は「全てが true」を判定
- `C\none` を求める場合は `!C\any(...)` を使用する

---

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

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

### 推奨読解順序

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

本関数で扱うデータ構造は、Hack言語の組み込み型である `Traversable` である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | (Hack組み込み型) | - | Traversable<T> は foreach で反復可能な全ての型の基底インターフェース |

**読解のコツ**: `Traversable` は Hack で最も抽象的なコレクション型であり、Container だけでなく、Generator やカスタムイテレータも含む。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | introspect.php | `src/c/introspect.php` | C\every 関数の定義を確認 |

**主要処理フロー**:
1. **95-104行目**: 関数のドキュメントコメント
2. **99-100行目**: `C\all` を探している場合は本関数を使用するという注記
3. **105-116行目**: `every` 関数の定義
4. **109行目**: デフォルト述語として `_Private\boolval` を設定
5. **110-114行目**: foreach ループで各要素をチェック
6. **111-113行目**: 述語が false を返したら即座に false を返す
7. **115行目**: 全要素がチェックを通過したら true を返す

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | introspect.php | `src/c/introspect.php` | 対となる C\any 関数との違いを理解 |

**主要処理フロー**:
- **28-39行目**: `C\any` 関数 - いずれかが true かを判定する対となる関数
- **23行目**: `C\none` を探している場合は `!C\any` を使用するという注記

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

```
C\every($traversable, $predicate)
    │
    ├─ _Private\boolval<>  [述語がnullの場合のデフォルト]
    │
    └─ $predicate($value)  [ユーザー指定の述語関数]
```

### データフロー図

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

Traversable<T> ───┐
                  ├──▶ foreach + predicate適用 ──▶ bool (true/false)
predicate ────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| introspect.php | `src/c/introspect.php` | ソース | C\every 関数の実装（105-116行目） |
| CIntrospectTest.php | `tests/c/CIntrospectTest.php` | テスト | every のユニットテスト（233-276行目） |
