# 機能設計書 116-nfirst

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `C\nfirst` 関数の機能設計について記述する。この関数は、null許容のTraversable（走査可能コレクション）から最初の要素を取得し、nullまたは空の場合はnullを返す。

### 本機能の処理概要

`C\nfirst` 関数は、null許容のTraversable（`?Traversable<T>`）の最初の要素を取得する関数である。入力がnullの場合、またはコレクションが空の場合は `null` を返す。null安全なコレクションアクセスを提供する。

**業務上の目的・背景**：コレクション操作において、コレクション自体がnullである可能性がある場合に、安全に最初の要素を取得する必要がある。null許容の戻り値を持つ関数の結果や、オプショナルなコレクションフィールドから要素を取得する場合に有用である。

**機能の利用シーン**：
- nullの可能性があるコレクションの最初の要素取得
- Optional な関係を持つデータの先頭要素アクセス
- null チェックと first() 呼び出しを一行で記述したい場合
- 安全なナビゲーション的なコレクションアクセス

**主要な処理内容**：
1. 入力がnullかどうかをチェック
2. nullでない場合は `first()` 関数に委譲
3. nullの場合は null を返却

**関連システム・外部連携**：本機能は外部システムとの連携はなく、HSL内部の `first` 関数に依存する。

**権限による制御**：特になし。純粋な関数であり、権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 画面なし | - | 本機能はUIを持たないライブラリ関数 |

## 機能種別

データアクセス / 要素選択

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $traversable | ?Traversable<T> | Yes | null許容の走査可能コレクション | なし（nullも許容） |

### 入力データソース

関数呼び出し時の引数として直接渡される。null、または vec、dict、keyset、Vector、Map、Set、Generator等のTraversableを実装する任意の型を受け付ける。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ?T | コレクションの最初の要素、またはnullもしくは空の場合はnull |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. nullチェック
   └─ $traversable is nonnull で判定
2. nullの場合
   └─ null を返却
3. nullでない場合
   └─ first($traversable) を呼び出し
   └─ 結果を返却（空の場合は null）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{$traversable is nonnull?}
    B -->|Yes| C[first関数呼び出し]
    C --> D[結果を返却]
    B -->|No| E[nullを返却]
    D --> F[終了]
    E --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-116-01 | null入力許容 | 入力がnullの場合はnullを返す | 常に適用 |
| BR-116-02 | 空コレクション許容 | 空のコレクションが渡された場合はnullを返す | 常に適用 |
| BR-116-03 | 最初の要素取得 | 挿入順序における最初の要素を返す | コレクションがnullでなく空でない場合 |

### 計算ロジック

特に計算ロジックは存在しない。null チェック後、`first()` 関数に処理を委譲する。

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 本関数はエラーをスローしない | - |

### リトライ仕様

エラーが発生しないため、リトライ仕様は不要。

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

本機能はトランザクション管理を行わない純粋関数である。

## パフォーマンス要件

- 時間計算量: O(1)
- 空間計算量: O(1)
- `first()` 関数と同等のパフォーマンス

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

本機能は純粋関数であり、特別なセキュリティ考慮事項はない。入力データの検証は型システムにより保証される。

## 備考

- `first` 関数は非nullのTraversableを受け取る
- `firstx` 関数は非nullのTraversableを受け取り、空の場合は例外をスロー
- `nfirst` は null許容のTraversableを受け取り、最も安全なアクセスを提供
- 三項演算子 `$traversable is nonnull ? first($traversable) : null` の簡潔な代替

---

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

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

### 推奨読解順序

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

Hack言語のnull許容型（`?Type`）について理解することが重要。`?Traversable<T>` は Traversable<T> または null を意味する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.php | `src/c/select.php` | 関数シグネチャと型パラメータ T の理解 |

**読解のコツ**: `?Traversable<T>` は null または Traversable<T> を意味し、戻り値 `?T` も null または T を意味する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.php | `src/c/select.php` | nfirst 関数の実装（311-315行目） |

**主要処理フロー**:
1. **311-313行目**: 関数シグネチャ - ?Traversable<T> を受け取り ?T を返す
2. **314行目**: 三項演算子で null チェックと first() 呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.php | `src/c/select.php` | first 関数（88-98行目）- 委譲先の実装 |
| 3-2 | select.php | `src/c/select.php` | firstx 関数（112-132行目）- 例外をスローする版 |

**主要処理フロー**:
- **311-315行目**: nfirst は null チェック後に first() に委譲
- **88-98行目**: first は最初の要素を取得、空なら null
- **112-132行目**: firstx は空の場合例外をスロー

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

```
C\nfirst($traversable)
    │
    ├─ $traversable is nonnull [nullチェック]
    │      │
    │      ├─ true → C\first($traversable) [委譲]
    │      │            │
    │      │            ├─ Container → Native\first()
    │      │            │
    │      │            └─ その他 → foreach で取得
    │      │
    │      └─ false → null を返却
    │
    └─ 結果を返却
```

### データフロー図

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

?Traversable<T> ───▶ nullチェック ───▶ first()に委譲 ───▶ ?T（最初の要素）
                           │
                           └─────▶ null ───▶ null
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.php | `src/c/select.php` | ソース | nfirst 関数の実装 |
| select.php | `src/c/select.php` | ソース | first 関数の実装（委譲先） |
| CSelectTest.php | `tests/c/CSelectTest.php` | テスト | nfirst のユニットテスト（682-713行目） |
