# 機能設計書 104-is_empty

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `C\is_empty` 関数の機能設計書である。この関数は、Containerが空かどうかを判定する。

### 本機能の処理概要

`C\is_empty` 関数は、与えられた `Container`（vec、dict、keyset、Vector、Map、Set など）が空（要素数が0）かどうかを判定し、真偽値を返す関数である。

**業務上の目的・背景**：コレクションデータを処理する前に、空かどうかを確認することは安全なプログラミングの基本である。空のコレクションに対して first や last などの操作を行うとエラーになる可能性があるため、事前チェックとして本関数が使用される。O(1)の計算量で高速に判定できるため、条件分岐での使用に適している。

**機能の利用シーン**：
- コレクションから要素を取得する前の空チェック
- 検索結果が空かどうかを確認する場合
- デフォルト値を設定する前の条件チェック
- ループ処理の前に空チェックを行い、不要な処理をスキップする場合
- APIレスポンスのデータ配列が空かどうかを判定する場合

**主要な処理内容**：
1. 入力パラメータとして Container を受け取る
2. Container が ConstCollection の場合、isEmpty() メソッドを呼び出す
3. それ以外の場合、Container を論理否定して空かどうかを判定
4. 空の場合は true、要素がある場合は false を返す

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

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

## 関連画面

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

## 機能種別

判定処理 / 検査処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $container | Container<T> | Yes | 空判定を行う対象のコンテナ | readonly 修飾により不変 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | コンテナが空の場合 `true`、要素がある場合 `false` |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. コンテナを引数として受け取る
   └─ readonly 修飾されており、関数内で変更されない
2. コンテナが ConstCollection かどうかを判定
   └─ Collection クラス（Vector、Map、Set など）の場合
3a. ConstCollection の場合: isEmpty() メソッドを呼び出す
   └─ Collection 固有の最適化されたメソッドを使用
3b. それ以外の場合: 論理否定 (!$container) で判定
   └─ 空のコンテナは falsy であることを利用
4. 判定結果を bool として返却
   └─ true: 空 / false: 要素あり
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[container を受け取る]
    B --> C{ConstCollection?}
    C -->|Yes| D[isEmpty メソッドを呼び出す]
    C -->|No| E[!container で判定]
    D --> F[結果を返す]
    E --> F
    F --> G[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-104-01 | 計算量保証 | 時間計算量・空間計算量ともにO(1)である | 常に適用 |
| BR-104-02 | null非対応 | null を受け取ることはできない（型エラー） | 常に適用 |
| BR-104-03 | Collection最適化 | ConstCollection の場合は isEmpty() を使用 | コンテナがConstCollectionの場合 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

- 純粋関数であり、外部への副作用がないためセキュリティリスクは低い
- readonly 修飾により入力データが変更されないことが保証されている

## 備考

- `C\count($container) === 0` と同等だが、より意図が明確で読みやすい
- 他の関数（firstx, lastx, pop_backx など）の内部で空チェックに使用されている
- null を許容する場合は、事前に null チェックを行う必要がある

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | (Hack組み込み型) | - | Container<T> は vec、dict、keyset およびCollectionクラスの基底型 |
| 1-2 | (Hack組み込み型) | - | ConstCollection<T> は不変コレクションのインターフェース |

**読解のコツ**: `ConstCollection` は Vector、Map、Set などの Collection クラスが実装するインターフェースであり、isEmpty() メソッドを持つ。

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

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

**主要処理フロー**:
1. **118-123行目**: 関数のドキュメントコメント（計算量の記載を含む）
2. **124-131行目**: `is_empty` 関数の定義
3. **127-129行目**: ConstCollection の場合は isEmpty() メソッドを使用
4. **130行目**: それ以外の場合は論理否定で判定

#### Step 3: 利用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.php | `src/c/select.php` | is_empty を使用している他の関数を確認 |

**主要処理フロー**:
- **121行目**: firstx 内で is_empty を使用して空チェック
- **227行目**: lastx 内で is_empty を使用して空チェック
- **381行目**: pop_back 内で is_empty を使用して空チェック
- **406行目**: pop_backx 内で is_empty を使用して空チェック

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

```
C\is_empty($container)
    │
    ├─ $container is ConstCollection
    │      │
    │      └─ $container->isEmpty()  [Collection メソッド]
    │
    └─ !$container  [論理否定による判定]
```

### データフロー図

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

Container<T> ──▶ isEmpty() または !$container ──▶ bool (true/false)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| introspect.php | `src/c/introspect.php` | ソース | C\is_empty 関数の実装（124-131行目） |
| select.php | `src/c/select.php` | ソース | is_empty を使用する他の関数群 |
| CIntrospectTest.php | `tests/c/CIntrospectTest.php` | テスト | is_empty のユニットテスト（278-304行目） |
