# 機能設計書 101-contains_key

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `C\contains_key` 関数の機能設計書である。この関数は、KeyedContainerに指定されたキーが存在するかどうかを判定する。

### 本機能の処理概要

`C\contains_key` 関数は、与えられた `KeyedContainer`（dict、vec、keyset、Map、Vector など）に、指定されたキーが含まれているかどうかを判定し、真偽値を返す関数である。

**業務上の目的・背景**：コレクションやマップ構造のデータを操作する際、特定のキーが存在するかどうかを事前に確認することは、安全なデータアクセスのために不可欠である。存在しないキーへのアクセスはエラーの原因となるため、この関数を使用することで防御的プログラミングが可能となる。また、キーの存在確認をO(1)の計算量で高速に実行できるため、大量データを扱う場面でもパフォーマンスを維持できる。

**機能の利用シーン**：
- 辞書型データ（dict）から値を取得する前に、キーの存在を確認する場合
- ユーザー入力やAPIレスポンスから受け取ったデータに、必要なフィールドが含まれているか検証する場合
- キャッシュデータからキーの存在有無をチェックする場合
- 条件分岐でキーの有無によって処理を切り替える場合

**主要な処理内容**：
1. 入力パラメータとして KeyedContainer と検索対象のキーを受け取る
2. PHPの `array_key_exists` 関数を内部的に呼び出し、キーの存在をチェックする
3. キーが存在すれば `true`、存在しなければ `false` を返す

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

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

## 関連画面

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

## 機能種別

判定処理 / 検索処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $container | KeyedContainer<Tk1, Tv> | Yes | 検索対象のコンテナ（dict、vec、keyset、Map、Vectorなど） | Tk1 は arraykey を継承する必要がある |
| $key | Tk2 | Yes | 検索するキー | Tk2 は arraykey を継承する必要がある |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | キーが存在する場合 `true`、存在しない場合 `false` |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. コンテナとキーを引数として受け取る
   └─ 両方とも readonly 修飾されており、関数内で変更されない
2. array_key_exists() を呼び出してキーの存在をチェック
   └─ PHPネイティブ関数を使用してO(1)で判定
3. 判定結果を bool として返却
   └─ true: キーが存在する / false: キーが存在しない
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[container, key を受け取る]
    B --> C[array_key_exists で判定]
    C --> D{キーが存在する?}
    D -->|Yes| E[true を返す]
    D -->|No| F[false を返す]
    E --> G[終了]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-101-01 | 厳密な型比較 | キーの比較は厳密等価で行われる（文字列 "3" と整数 3 は異なるキーとして扱われる） | 常に適用 |
| BR-101-02 | 計算量保証 | 計算量はO(1)である | 常に適用 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- `C\contains` 関数（値の存在確認）とは異なり、本関数はキーの存在確認を行う
- keyset の場合、キーと値が同一であるため `C\contains` と同等の結果となる

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | (Hack組み込み型) | - | KeyedContainer<Tk, Tv> は dict、vec、keyset、Map、Vector などの基底型 |

**読解のコツ**: `KeyedContainer` は Hack の組み込みインターフェースであり、キーと値のペアを持つコレクション型の抽象化である。`<<__NonDisjoint>>` アトリビュートは、型パラメータ間の交差を許可するための指定である。

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

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

**主要処理フロー**:
1. **72-81行目**: `contains_key` 関数の定義
2. **72-76行目**: ジェネリック型パラメータの定義（Tk1, Tk2 は arraykey を継承）
3. **77-79行目**: パラメータ定義（readonly 修飾で不変性を保証）
4. **80行目**: `array_key_exists` を呼び出してキー存在チェック

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | introspect.php | `src/c/introspect.php` | 関連する C\contains 関数（値の存在確認）との違いを理解 |

**主要処理フロー**:
- **48-64行目**: `C\contains` 関数 - 値の存在確認を行う関連関数
- **55-56行目**: keyset や ConstSet の場合は `contains_key` を内部で利用

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

```
C\contains_key($container, $key)
    │
    └─ \array_key_exists($key, $container)  [PHP組み込み関数]
```

### データフロー図

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

KeyedContainer ───┐
                  ├──▶ array_key_exists() ──▶ bool (true/false)
arraykey (key) ───┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| introspect.php | `src/c/introspect.php` | ソース | C\contains_key 関数の実装 |
| CIntrospectTest.php | `tests/c/CIntrospectTest.php` | テスト | contains_key のユニットテスト（168-210行目） |
