# 機能設計書 102-count

## 概要

本ドキュメントは、Hack Standard Library（HSL）の `C\count` 関数の機能設計書である。この関数は、Containerに含まれる要素数を取得する。

### 本機能の処理概要

`C\count` 関数は、与えられた `Container`（vec、dict、keyset、Vector、Map、Set など）に含まれる要素の数を整数値として返す関数である。

**業務上の目的・背景**：コレクションデータを処理する際、要素数の取得は最も基本的かつ頻繁に使用される操作の一つである。ループの反復回数の決定、空判定の前処理、ページネーションの実装、バリデーションでの件数チェックなど、多様な用途で使用される。O(1)の計算量で高速に要素数を取得できるため、パフォーマンスクリティカルな処理でも安全に使用できる。

**機能の利用シーン**：
- ページネーション実装時の総件数取得
- 配列やコレクションが期待する件数を持っているか検証する場合
- 空でないことを確認する前に要素数をチェックする場合
- ログやデバッグ出力で件数を表示する場合
- 処理結果の統計情報として件数を集計する場合

**主要な処理内容**：
1. 入力パラメータとして Container を受け取る
2. PHPの `count` 関数を内部的に呼び出し、要素数を取得する
3. 要素数を整数として返す

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

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

## 関連画面

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

## 機能種別

計算処理 / 集計処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $container | Container<mixed> | Yes | 要素数を取得する対象のコンテナ | readonly 修飾により不変 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | コンテナに含まれる要素数（0以上の整数） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. コンテナを引数として受け取る
   └─ readonly 修飾されており、関数内で変更されない
2. PHPの count() 関数を呼び出して要素数を取得
   └─ ネイティブ関数を使用してO(1)で取得
3. 要素数を int として返却
   └─ 空のコンテナの場合は 0 を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[container を受け取る]
    B --> C[count 関数で要素数取得]
    C --> D[要素数を返す]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-102-01 | 計算量保証 | 時間計算量・空間計算量ともにO(1)である | 常に適用 |
| BR-102-02 | 非負整数保証 | 戻り値は常に0以上の整数である | 常に適用 |
| BR-102-03 | 空コンテナ対応 | 空のコンテナに対しては0を返す | コンテナが空の場合 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- `C\is_empty` 関数は内部的に `count` の結果を利用する可能性がある
- Hack の Container 型は vec、dict、keyset の3つのプリミティブ型と、それらをベースにした Collection クラスを含む

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | (Hack組み込み型) | - | Container<T> は vec、dict、keyset およびCollectionクラスの基底型 |

**読解のコツ**: `Container` は Hack の組み込みインターフェースであり、カウント可能なコレクション型の抽象化である。`mixed` 型パラメータにより、任意の値型を持つコンテナを受け入れる。

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

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

**主要処理フロー**:
1. **83-87行目**: 関数のドキュメントコメント（計算量の記載を含む）
2. **88-93行目**: `count` 関数の定義
3. **89-91行目**: パラメータ定義（readonly Container<mixed>）
4. **92行目**: PHPの `\count` 関数を呼び出して要素数を返す

#### Step 3: テストケースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CIntrospectTest.php | `tests/c/CIntrospectTest.php` | 各種コンテナでの動作確認 |

**主要処理フロー**:
- **212-223行目**: テストデータプロバイダ（provideTestCount）
- **214行目**: 空の vec は 0 を返す
- **215行目**: Vec\range(1, 10) は 10 を返す
- **216-221行目**: Set、Vector、Map、keyset、dict での動作確認

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

```
C\count($container)
    │
    └─ \count($container)  [PHP組み込み関数]
```

### データフロー図

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

Container<mixed> ──▶ \count() ──▶ int (要素数)
```

### 関連ファイル一覧

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