# 機能設計書 121-pop_frontx

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `C\pop_frontx` 関数に関する機能設計書である。この関数は、Containerから最初の要素を取り出して返し、元のContainerを変更する。空のContainerが渡された場合はInvariantExceptionをスローする。

### 本機能の処理概要

**業務上の目的・背景**：キュー処理やFIFO（First In First Out）パターンを実装する際に、コレクションの先頭から要素を順次取り出す必要がある。`pop_frontx`関数は、要素が必ず存在することを前提とした厳格な処理を行い、空のContainerに対する誤ったアクセスを実行時に検出して早期にエラーを発生させる。これにより、データ処理のバグを早期に発見し、堅牢なアプリケーション開発を支援する。

**機能の利用シーン**：タスクキューからタスクを取り出す処理、イベントキューの先頭イベント取得、バッファからの順次データ読み出し、ワークフローの次ステップ取得など、先頭要素の存在が保証されている状況で使用する。空の可能性がある場合は`pop_front`関数を使用する。

**主要な処理内容**：
1. 入力Containerが空でないことをinvariantでチェック
2. 空の場合はInvariantExceptionをスロー
3. `array_shift`を使用してContainerの最初の要素を取り出す
4. Containerはinoutパラメータとして変更され、取り出された要素が戻り値として返される

**関連システム・外部連携**：本機能はHSLライブラリ内部で完結し、外部システムとの連携はない。`C\is_empty`関数を使用してContainerの空チェックを行う。

**権限による制御**：本機能に権限による制御は存在しない。

## 関連画面

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

## 機能種別

コレクション操作 / 要素取り出し

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $container | T as Container\<Tv\> | Yes | 最初の要素を取り出す対象のContainer（inoutパラメータ） | 空でないこと（空の場合InvariantException） |

### 入力データソース

呼び出し元から直接渡されるinoutパラメータとしてのContainer（vec、dict、keyset、Vector、Map等）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | Tv | Containerから取り出された最初の要素 |
| $container（変更後） | T | 最初の要素が削除された状態のContainer |

### 出力先

戻り値として呼び出し元に返却。inoutパラメータとして渡されたContainer自体も変更される。

## 処理フロー

### 処理シーケンス

```
1. 空チェック
   └─ C\is_empty($container)で空かどうかを判定
2. バリデーション
   └─ 空の場合はinvariant_violationでInvariantExceptionをスロー
3. 要素取り出し
   └─ array_shift(inout $container)で最初の要素を取り出して返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Containerは空か?}
    B -->|Yes| C[InvariantExceptionをスロー]
    B -->|No| D[array_shiftで最初の要素を取り出す]
    D --> E[取り出した要素を返却]
    E --> F[終了]
    C --> G[異常終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 非空制約 | Containerは空であってはならない | 常に適用 |
| BR-002 | inout変更 | 元のContainerは最初の要素が削除された状態に変更される | 常に適用 |
| BR-003 | immutable非対応 | イミュータブルなHack Collectionが渡された場合、結果はHHVMのバージョンに依存し期待通りに動作しない可能性がある | ImmVector、ImmMap、ImmSet等の場合 |

### 計算ロジック

特になし。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | Containerが空の場合 | 事前にC\is_emptyでチェックするか、pop_front関数を使用する |

### リトライ仕様

リトライは不要。空のContainerはリトライしても空のままである。

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

本機能はトランザクション制御を行わない。

## パフォーマンス要件

- 時間計算量: O(1)またはO(N) - インプレース操作が可能な場合はO(1)、Containerのコピーが必要な場合はO(N)
- 空間計算量: O(1)またはO(N) - インプレース操作が可能な場合はO(1)、Containerのコピーが必要な場合はO(N)

vecの場合、全要素のインデックスを再計算する必要があるためO(N)となる。dictやkeysetの場合はO(1)に近い。

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

特になし。ライブラリ関数として純粋な配列操作のみを行う。

## 備考

- `pop_front`関数は空のContainerでnullを返すが、`pop_frontx`は例外をスローする
- `pop_backx`は最後の要素を取り出す対応する関数
- capability context: `[write_props]`

---

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

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

### 推奨読解順序

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

Container型とinoutパラメータの概念を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.php | `src/c/select.php` | Container型の制約とinoutパラメータの使用法を確認 |

**読解のコツ**: HackのContainer型はvec、dict、keyset、Vector、Map、Set等を包含するジェネリックな型。inoutパラメータは参照渡しに似た機能で、関数内での変更が呼び出し元に反映される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.php | `src/c/select.php` | pop_frontx関数の定義（445-452行目） |

**主要処理フロー**:
1. **445行目**: 関数シグネチャ - `inout T $container`でContainerを受け取る
2. **446-449行目**: invariantによる空チェック - 空の場合は例外メッセージ生成
3. **451行目**: array_shiftで最初の要素を取り出して返却

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | introspect.php | `src/c/introspect.php` | is_empty関数の実装（124-131行目） |

**主要処理フロー**:
- **124-131行目**: ConstCollectionの場合はisEmpty()メソッド、それ以外は!$containerで判定

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

```
C\pop_frontx($container)
    │
    ├─ C\is_empty($container)
    │      └─ ConstCollection::isEmpty() または !$container
    │
    └─ \array_shift(inout $container)
```

### データフロー図

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

Container<Tv>    ───▶   空チェック                ───▶   Tv（最初の要素）
(inout)                      │                              │
                             ▼                              ▼
                        array_shift          ───▶   Container（変更後）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.php | `src/c/select.php` | ソース | pop_frontx関数の実装 |
| introspect.php | `src/c/introspect.php` | ソース | is_empty関数の実装 |
| CSelectTest.php | `tests/c/CSelectTest.php` | テスト | pop_frontx関数のユニットテスト |
