# 機能設計書 108-first

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `C\first` 関数の機能設計書である。この関数は、Traversableの最初の要素を取得する。

### 本機能の処理概要

`C\first` 関数は、与えられた `Traversable` の最初の要素を返す関数である。Traversable が空の場合は `null` を返す。Container の場合は O(1) で、それ以外の Traversable の場合も O(1) で最初の要素を取得できる。

**業務上の目的・背景**：コレクションの先頭要素へのアクセスは、キュー処理、デフォルト値の取得、最新/最古のデータ取得など、多くの場面で必要となる基本操作である。HSL の `first` 関数は、空のコレクションに対して安全に null を返すため、エラーハンドリングが簡潔になる。また、Container に対しては内部的に最適化されたネイティブ関数を使用するため、高いパフォーマンスを発揮する。

**機能の利用シーン**：
- リストの先頭要素を取得する場合
- 検索結果の最初の1件を取得する場合
- キューから次の処理対象を取得する場合
- デフォルト値として最初の選択肢を取得する場合
- 時系列データの最初のレコードを取得する場合

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

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

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

## 関連画面

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

## 機能種別

選択処理 / アクセス処理

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ?T | 最初の要素。空の場合は `null` |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. Traversable を引数として受け取る
   └─ 型パラメータ T は要素の型
2. Traversable が Container かどうかを判定
   └─ Container の場合は最適化されたパスを使用
3a. Container の場合: _Private\Native\first を呼び出す
   └─ HHVM 内蔵の最適化された関数を使用
3b. それ以外の場合: foreach で最初の要素を取得
   └─ 最初のイテレーションで即座に return
4. 空の Traversable の場合は null を返す
```

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-108-01 | 空コレクション対応 | 空の Traversable に対しては null を返す | Traversableが空の場合 |
| BR-108-02 | Container最適化 | Container の場合は O(1) のネイティブ関数を使用 | Container型の場合 |
| BR-108-03 | 順序保持 | Traversable の反復順序に従った最初の要素を返す | 常に適用 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TypeError | 型エラー | Traversable 型以外を渡した場合 | 型チェッカーがコンパイル時に検出 |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

- 純粋関数であり、外部への副作用がないためセキュリティリスクは低い
- 読み取り専用の操作であり、入力データは変更されない

## 備考

- 空でないことが保証される場合は `C\firstx` を使用する
- null 許容の Traversable を扱う場合は `C\nfirst` を使用する
- 単一要素のみを期待する場合は `C\onlyx` を使用する
- 非同期版として `C\first_async` が存在する
- 関連関数: `C\firstx`（必須版）、`C\nfirst`（null許容Traversable版）、`C\first_key`（キー取得版）

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: Container は Traversable より具体的な型であり、vec、dict、keyset、Vector、Map、Set などが該当する。Container に対しては最適化されたネイティブ関数が使用される。

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

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

**主要処理フロー**:
1. **76-87行目**: 関数のドキュメントコメント
2. **80-83行目**: 関連関数への参照（firstx, nfirst, onlyx, first_async）
3. **88-98行目**: `first` 関数の定義
4. **91-93行目**: Container の場合は _Private\Native\first を使用
5. **94-96行目**: それ以外は foreach で最初の要素を取得
6. **97行目**: 空の場合は null を返す

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.php | `src/c/select.php` | firstx, nfirst との違いを理解 |

**主要処理フロー**:
- **112-132行目**: `C\firstx` 関数 - 必須版（空の場合は例外）
- **311-315行目**: `C\nfirst` 関数 - null許容Traversable版

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

```
C\first($traversable)
    │
    ├─ $traversable is Container<_>
    │      │
    │      └─ _Private\Native\first($traversable)  [HHVM内蔵関数]
    │
    └─ foreach ($traversable as $value)
           │
           └─ return $value  [最初のイテレーション]
```

### データフロー図

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

Traversable<T> ──▶ Container判定 ──┬──▶ Native\first() ──▶ ?T
                                   │
                                   └──▶ foreach        ──▶ ?T or null
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.php | `src/c/select.php` | ソース | C\first 関数の実装（88-98行目） |
| CSelectTest.php | `tests/c/CSelectTest.php` | テスト | first のユニットテスト（118-144行目） |
