# 機能設計書 109-firstx

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `C\firstx` 関数の機能設計書である。この関数は、Traversableの最初の要素を取得し、空の場合は例外をスローする。

### 本機能の処理概要

`C\firstx` 関数は、与えられた `Traversable` の最初の要素を返す関数である。Traversable が空の場合は `InvariantException` をスローする（`x` は「exception」を表す）。

**業務上の目的・背景**：コレクションに少なくとも1つの要素が存在することがビジネスロジック上保証される場合、null チェックを省略してコードを簡潔にすることができる。例えば、デフォルト設定が必ず存在するシステム、検索結果が1件以上あることが保証される場合など、空のコレクションが異常事態である場合に使用される。例外をスローすることで、想定外の状況を早期に検出し、堅牢なプログラムを実現できる。

**機能の利用シーン**：
- 必ず存在するはずのデフォルト設定を取得する場合
- ソート済みリストの最小値（先頭）を取得する場合（リストが空でないことが保証される場合）
- 検索結果が必ず1件以上あることが保証される場合
- キューに必ず要素があることが保証される場合
- null チェックを避けて型安全なコードを書きたい場合

**主要な処理内容**：
1. 入力パラメータとして Traversable を受け取る
2. Container の場合は _Private\Native\first を呼び出し、結果を確認
3. それ以外の場合は foreach で最初の要素を取得
4. 空の場合は InvariantException をスロー

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

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

## 関連画面

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

## 機能種別

選択処理 / アクセス処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $traversable | Traversable<T> | Yes | 最初の要素を取得する対象のTraversable | なし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | T | 最初の要素（非null保証） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. Traversable を引数として受け取る
   └─ 型パラメータ T は要素の型
2. Traversable が Container かどうかを判定
   └─ Container の場合は最適化されたパスを使用
3a. Container の場合:
   └─ _Private\Native\first を呼び出す
   └─ 結果が nonnull の場合はそのまま返す
   └─ 結果が null の場合は is_empty で空チェックし、空なら例外
   └─ 空でないが null が返った場合（要素自体が null）はその null を返す
3b. それ以外の場合:
   └─ foreach で最初の要素を取得し即座に返す
4. ループに入らなかった場合（空）は invariant_violation で例外スロー
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[traversable を受け取る]
    B --> C{Container?}
    C -->|Yes| D[_Private\Native\first を呼び出す]
    D --> E{結果が nonnull?}
    E -->|Yes| F[その値を返す]
    E -->|No| G{is_empty?}
    G -->|Yes| H[InvariantException をスロー]
    G -->|No| I[null を返す 要素自体が null]
    C -->|No| J[foreach ループ開始]
    J --> K{要素あり?}
    K -->|Yes| L[最初の要素を返す]
    K -->|No| H
    F --> M[終了]
    I --> M
    L --> M
    H --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-109-01 | 例外スロー | 空の Traversable に対しては InvariantException をスロー | Traversableが空の場合 |
| BR-109-02 | Container最適化 | Container の場合は O(1) のネイティブ関数を使用 | Container型の場合 |
| BR-109-03 | null要素対応 | 要素自体が null の場合も正しく返す | 最初の要素が null の場合 |
| BR-109-04 | 非null戻り値保証 | 戻り値の型は T（null を含まない） | 常に適用 |

### 計算ロジック

特になし（要素取得のみで複雑な計算処理は含まれない）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvariantException | 実行時例外 | Traversable が空の場合 | try-catch で捕捉するか、事前に C\is_empty で確認 |
| TypeError | 型エラー | Traversable 型以外を渡した場合 | 型チェッカーがコンパイル時に検出 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 時間計算量: O(1)
- 空間計算量: O(1)

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

- 純粋関数であり、外部への副作用がないためセキュリティリスクは低い
- 読み取り専用の操作であり、入力データは変更されない
- 例外メッセージに機密情報が含まれないよう注意

## 備考

- 関数名の末尾の `x` は例外（exception）を表す HSL の命名規則
- 空である可能性がある場合は `C\first` を使用する
- エラーメッセージは "Expected at least one element." 固定
- null 許容の Traversable を扱う場合は `C\nfirst` を使用する
- 非同期版として `C\firstx_async` が存在する
- 関連関数: `C\first`（null許容版）、`C\nfirst`（null許容Traversable版）

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: 戻り値が `T`（非null）であることに注目。`C\first` の `?T` とは異なり、必ず値を返すか例外をスローする。

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

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

**主要処理フロー**:
1. **100-111行目**: 関数のドキュメントコメント
2. **104-107行目**: 関連関数への参照（first, nfirst, onlyx, firstx_async）
3. **112-132行目**: `firstx` 関数の定義
4. **115-127行目**: Container の場合の処理
5. **116行目**: _Private\Native\first を呼び出す
6. **117-119行目**: 結果が nonnull ならそのまま返す
7. **120-124行目**: null の場合、is_empty で空チェック、空なら例外
8. **126行目**: 空でなければ（要素が null）その値を返す
9. **128-130行目**: Container 以外は foreach で取得
10. **131行目**: ループに入らなかった場合は invariant_violation

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.php | `src/c/select.php` | 比較: C\first 関数との違い |

**主要処理フロー**:
- **88-98行目**: `C\first` 関数 - null許容版（比較用）
- **97行目**: first は空の場合 null を返す
- **131行目**: firstx は空の場合 invariant_violation

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

```
C\firstx($traversable)
    │
    ├─ $traversable is Container<_>
    │      │
    │      ├─ _Private\Native\first($traversable)  [HHVM内蔵関数]
    │      │
    │      └─ is_empty($traversable)  [空チェック]
    │             │
    │             └─ invariant()  [空の場合例外]
    │
    └─ foreach ($traversable as $value)
           │
           ├─ return $value  [最初のイテレーション]
           │
           └─ invariant_violation()  [ループに入らなかった場合]
```

### データフロー図

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

Traversable<T> ──▶ Container判定 ──┬──▶ Native\first() ──┬──▶ T
                                   │                      │
                                   │                      └──▶ Exception (空)
                                   │
                                   └──▶ foreach ──────────┬──▶ T
                                                          │
                                                          └──▶ Exception (空)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.php | `src/c/select.php` | ソース | C\firstx 関数の実装（112-132行目） |
| CSelectTest.php | `tests/c/CSelectTest.php` | テスト | firstx のユニットテスト（146-187行目） |
